Registry / database / json-sql-enhanced

json-sql-enhanced

JSON →
library3.0.0jsnpmunverified

A modern fork of json-sql that converts MongoDB-style query objects into SQL queries with support for PostgreSQL, MySQL, SQLite, and MSSQL dialects. Version 3.0.0 is the current stable release with zero dependencies, active development on GitHub, and comprehensive support for operators like $regex, $size, $exists, $elemMatch, and nested logical operations. It differentiates from alternatives by providing dialect-optimized SQL generation, TypeScript type definitions, and a leaner API compared to larger ORMs.

database
npm install json-sql-enhanced
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · JSON-SQL-ENHANCED
J
json-sql-enhanced
databasejavascriptv3.0.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (factory function)
✓ const jsonSql = require('json-sql-enhanced')();
✗ import jsonSql from 'json-sql-enhanced';
The package does not export a default constructor; call the exported factory function (which returns an object with .build()) or use ESM interop: const jsonSql = (await import('json-sql-enhanced')).default(). Note: as of v3, there is no named export for the factory; it is the default export.
jsonSql.build
✓ const result = jsonSql.build({ type: 'select', table: 'users', condition: {} });
✗ const result = jsonSql({ type: 'select', table: 'users' });
Do not call jsonSql() directly; it must be invoked as a factory (returning an object) then .build() on that object. In ESM: import jsonSqlFactory from 'json-sql-enhanced'; const jsonSql = jsonSqlFactory();
types
✓ import type { BuildResult, QueryObject } from 'json-sql-enhanced';
✗ import { BuildResult } from 'json-sql-enhanced';
TypeScript types are exported as named exports (e.g., BuildResult, QueryObject, Dialect). Use import type for type-only usage. In CJS: /** @type {import('json-sql-enhanced').BuildResult} */

Demonstrates factory import, building a SELECT query with $regex, $gt, and $size operators, and extracting the generated SQL and values.

const jsonSql = require('json-sql-enhanced')(); const result = jsonSql.build({ type: 'select', table: 'users', condition: { name: { $regex: 'John', $options: 'i' }, age: { $gt: 18 }, emails: { $size: { $gt: 0 } }, }, }); console.log(result.query); console.log(result.values); // Output (PostgreSQL): // select * from "users" where "name" ILIKE $p1 and "age" > $p2 and JSON_LENGTH("emails") > $p3 // { p1: '%John%', p2: 18, p3: 0 }
Debug
Known issues
breakingFactory function must be called (e.g., require('json-sql-enhanced')()) — the import no longer returns a pre-configured builder instance.
fix
Change from const jsonSql = require('json-sql'); to const jsonSql = require('json-sql-enhanced')();
affects: >=3.0.0
breakingNode.js 18+ required; version 3.x drops support for Node <18.
fix
Update Node.js to version 18 or higher, or use v2.x for older Node versions.
affects: >=3.0.0
deprecatedUnderscore.js dependency removed; some methods like _.pick are no longer available internally.
fix
If you relied on underscore methods, polyfill them or use native alternatives.
affects: >=3.0.0
gotchaResult.values uses numbered placeholders ($p1, $p2, …) for all dialects, not named parameters.
fix
When using the result.values object, reference keys like 'p1', 'p2' instead of named placeholders.
affects: >=3.0.0
gotcha$regex with $options: options are not validated; supplying an unsupported option may produce invalid SQL.
fix
Check the dialect's allowed flags (e.g., 'i' for case-insensitive) before passing $options.
affects: >=3.0.0
breakingEmpty object {} in conditions now converts to NULL instead of being ignored (fixes issue #57).
fix
If you used {} to mean 'no condition', use undefined or remove the key instead.
affects: >=3.0.0
gotchaBuffer and BSON ObjectId values are automatically converted to hex strings; explicit string conversion may produce double encoding.
fix
Let the library handle conversion; do not call .toString('hex') beforehand.
affects: >=3.0.0
Errors
Common errors & fixes
TypeError: jsonSql is not a function
Calling the imported factory without parentheses, or using the value returned from require without calling it.
fix
Use const jsonSql = require('json-sql-enhanced')(); (notice the invocation parentheses).
AggregateError [ERR_VM_MODULE_LINK]: Module not found
Node.js version is below 18.0.0; the package uses top-level await or modern JS features.
fix
Upgrade Node.js to version 18 or higher.
Cannot read property 'build' of undefined
Attempting to call .build on the factory function itself rather than the object it returns.
fix
Ensure you call the factory: const instance = require('json-sql-enhanced')(); then instance.build().
TypeError: result.values is not an object
Using an older version (v1/v2) where values were returned as an array; v3 returns an object.
fix
Access values as an object, e.g., result.values.p1, not result.values[0].
Upgrade
Version history
3.0.0latest on npm
Audit
Dependencies
noderequiredRuntime requirement; version >=18.0.0 is required for modern JS features used by the library
Agent activity
3 hits · last 30 days
node
2
Resources
githubhttps://github.com/forwardemail/json-sql-enhanced ↗
packagejson-sql-enhanced ↗
homepagehttps://github.com/forwardemail/json-sql-enhanced#readme ↗
json-sql-enhanced — npm install json-sql-enhanced · libregistry