@sqb/builder 5.0.6 → 6.0.0

package/README.md

@@ -6,16 +6,40 @@
 
 [![NPM Version][npm-image]][npm-url]
 [![NPM Downloads][downloads-image]][downloads-url]
-[![Build Status][travis-image]][travis-url]
+[![CI Tests][ci-test-image]][ci-test-url]
 [![Test Coverage][coveralls-image]][coveralls-url]
-[![Dependencies][dependencies-image]][dependencies-url]
-[![DevDependencies][devdependencies-image]][devdependencies-url]
-[![Package Quality][quality-image]][quality-url]
 
 ## About SQB
 
 SQB is an extensible, multi-dialect SQL query builder and Database connection wrapper for NodeJS.
 
+## About @sqb/builder
+
+`@sqb/builder` is the query construction and serialization core the whole SQB stack is built on.
+It lets you compose `Select`, `Insert`, `Update` and `Delete` statements as plain JavaScript/
+TypeScript objects — with type-checked columns, joins, conditions and parameters — and turns them
+into the correct SQL text for whichever database you're targeting, without depending on any driver
+or network connection itself.
+
+Serialization is dialect-driven: each target database (Postgres, MySQL, MariaDB, Oracle, SQL
+Server, SQLite, ...) is a pluggable `SerializerExtension` that can override how any part of a query
+is rendered — identifier quoting, `LIMIT`/`OFFSET` syntax, boolean literals, `RETURNING` support,
+and more — while everything it doesn't override falls through to sensible defaults. This is what
+lets [`@sqb/connect`](../connect) and the various dialect/adapter packages share one query-building
+API across every supported database.
+
+```ts
+import { Select, Eq } from '@sqb/builder';
+
+const query = Select('id', 'given_name', 'family_name')
+  .from('customers')
+  .where(Eq('active', true))
+  .orderBy('id')
+  .limit(10);
+
+const { sql, params } = query.generate({ dialect: 'postgres' });
+```
+
 ## Main goals
 
 - Single code base for any sql based database
@@ -39,7 +63,7 @@ $ npm install @sqb/builder --save
 
 ## Node Compatibility
 
-- node >= 16.x
+- node >= 20.x
 
 ### License
 
@@ -47,17 +71,9 @@ SQB is available under [MIT](LICENSE) license.
 
 [npm-image]: https://img.shields.io/npm/v/@sqb/builder.svg
 [npm-url]: https://npmjs.org/package/@sqb/builder
-[travis-image]: https://img.shields.io/travis/sqbjs/@sqb/builder/master.svg
-[travis-url]: https://travis-ci.org/sqbjs/@sqb/builder
-[coveralls-image]: https://img.shields.io/coveralls/sqbjs/@sqb/builder/master.svg
-[coveralls-url]: https://coveralls.io/r/sqbjs/@sqb/builder
 [downloads-image]: https://img.shields.io/npm/dm/@sqb/builder.svg
 [downloads-url]: https://npmjs.org/package/@sqb/builder
-[gitter-image]: https://badges.gitter.im/sqbjs/@sqb/builder.svg
-[gitter-url]: https://gitter.im/sqbjs/@sqb/builder?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
-[dependencies-image]: https://david-dm.org/sqbjs/@sqb/builder/status.svg
-[dependencies-url]: https://david-dm.org/sqbjs/@sqb/builder
-[devdependencies-image]: https://david-dm.org/sqbjs/@sqb/builder/dev-status.svg
-[devdependencies-url]: https://david-dm.org/sqbjs/@sqb/builder?type=dev
-[quality-image]: http://npm.packagequality.com/shield/@sqb/builder.png
-[quality-url]: http://packagequality.com/#?package=@sqb/builder
+[ci-test-image]: https://github.com/panates/sqb/actions/workflows/test.yml/badge.svg
+[ci-test-url]: https://github.com/panates/sqb/actions/workflows/test.yml
+[coveralls-image]: https://coveralls.io/repos/github/sqbjs/sqb/badge.svg?branch=master
+[coveralls-url]: https://coveralls.io/github/sqbjs/sqb?branch=master

package/enums.d.ts

@@ -72,7 +72,8 @@ export declare enum OperatorType {
     isNot = "isNot",
     exists = "exists",
     notExists = "notExists",
-    not = "not"
+    not = "not",
+    match = "match"
 }
 export declare enum DataType {
     BOOL = "BOOL",

package/enums.js

@@ -76,6 +76,7 @@ export var OperatorType;
     OperatorType["exists"] = "exists";
     OperatorType["notExists"] = "notExists";
     OperatorType["not"] = "not";
+    OperatorType["match"] = "match";
 })(OperatorType || (OperatorType = {}));
 export var DataType;
 (function (DataType) {

package/op.ns.d.ts

@@ -11,6 +11,7 @@ import { IsNot } from './sql/operators/is-not.js';
 import { Like } from './sql/operators/like.js';
 import { Lt } from './sql/operators/lt.js';
 import { Lte } from './sql/operators/lte.js';
+import { Match } from './sql/operators/match.js';
 import { Ne } from './sql/operators/ne.js';
 import { Not } from './sql/operators/not.js';
 import { NotBetween } from './sql/operators/not-between.js';
@@ -59,6 +60,7 @@ export interface OperatorsMap {
     exists: typeof Exists;
     notExists: typeof NotExists;
     '!exists': typeof NotExists;
+    match: typeof Match;
 }
 declare const Operators: OperatorsMap;
 export { Operators };

package/op.ns.js

@@ -12,6 +12,7 @@ import { IsNot } from './sql/operators/is-not.js';
 import { Like } from './sql/operators/like.js';
 import { Lt } from './sql/operators/lt.js';
 import { Lte } from './sql/operators/lte.js';
+import { Match } from './sql/operators/match.js';
 import { Ne } from './sql/operators/ne.js';
 import { Not } from './sql/operators/not.js';
 import { NotBetween } from './sql/operators/not-between.js';
@@ -60,6 +61,7 @@ const Operators = {
     exists: Exists,
     notExists: NotExists,
     '!exists': NotExists,
+    match: Match,
 };
 LogicalOperator.Operators = Operators;
 export { Operators };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sqb/builder",
   "description": "Extensible multi-dialect SQL query builder written with TypeScript",
-  "version": "5.0.6",
+  "version": "6.0.0",
   "author": "Panates",
   "license": "Apache-2.0",
   "dependencies": {

package/serialize-context.d.ts

@@ -2,7 +2,7 @@ import { Query } from './sql/index.js';
 import type { DefaultSerializeFunction, GenerateOptions, ParamOptions } from './types.js';
 export declare class SerializeContext implements GenerateOptions {
     readonly rootQuery: Query;
-    readonly reservedWords: string[];
+    readonly reservedWords: Set<string>;
     dialect?: string;
     prettyPrint?: boolean;
     params?: Record<string, any>;

package/serialize-context.js

@@ -4,7 +4,7 @@ import { Query } from './sql/index.js';
 import { isLogicalOperator, isQuery, isSqlElement } from './type-guards.js';
 export class SerializeContext {
     rootQuery;
-    reservedWords = [
+    reservedWords = new Set([
         'schema',
         'table',
         'field',
@@ -61,7 +61,27 @@ export class SerializeContext {
         'foreign',
         'user',
         'password',
-    ];
+        'all',
+        'as',
+        'asc',
+        'case',
+        'cast',
+        'check',
+        'column',
+        'desc',
+        'else',
+        'end',
+        'for',
+        'in',
+        'into',
+        'is',
+        'on',
+        'then',
+        'to',
+        'union',
+        'unique',
+        'when',
+    ]);
     dialect;
     prettyPrint;
     params;
@@ -182,7 +202,7 @@ export class SerializeContext {
     isReservedWord(s) {
         if (!s)
             return false;
-        if (this.reservedWords.includes(s.toLowerCase()))
+        if (this.reservedWords.has(s.toLowerCase()))
             return true;
         for (const ext of SerializerRegistry.items()) {
             if (ext.dialect === this.dialect && ext.isReservedWord) {

package/sql/elements/field.js

@@ -19,7 +19,7 @@ class FieldClass extends BaseField {
             const prefix = ctx.escapeReserved(this._schema ? this._schema + '.' : '') +
                 (this._table ? this._table + '.' : '');
             return (prefix +
-                (!prefix && o.isReservedWord ? '"' + this._field + '"' : this._field) +
+                (o.isReservedWord ? '"' + this._field + '"' : this._field) +
                 (this._alias ? ' as ' + this._alias : ''));
         });
     }

package/sql/elements/min.d.ts

@@ -4,7 +4,6 @@ import { SerializeContext } from '../../serialize-context.js';
 declare class MinClass extends SqlElement {
     _expression: any;
     _alias?: string;
-    constructor(expression: any);
     get _type(): SerializationType;
     /**
      * Sets alias to case expression.

package/sql/elements/min.js

@@ -4,10 +4,6 @@ import { SerializeContext } from '../../serialize-context.js';
 class MinClass extends SqlElement {
     _expression;
     _alias;
-    constructor(expression) {
-        super();
-        this._expression = expression;
-    }
     get _type() {
         return SerializationType.MIN_STATEMENT;
     }
@@ -38,6 +34,7 @@ class MinClass extends SqlElement {
 export const Min = function (expression) {
     if (!(this instanceof Min))
         return new Min(expression);
+    SqlElement.call(this);
     this._expression = expression;
 };
 Min.prototype = MinClass.prototype;

package/sql/insert.d.ts

@@ -12,6 +12,7 @@ declare class InsertClass extends ReturningQuery {
      * Performs serialization
      */
     _serialize(ctx: SerializeContext): string;
+    protected __defaultSerialize(ctx: SerializeContext, o: any): string;
     /**
      *
      */

package/sql/insert.js

@@ -23,6 +23,9 @@ class InsertClass extends ReturningQuery {
             values: this.__serializeValues(ctx),
             returning: this.__serializeReturning(ctx),
         };
+        return ctx.serialize(this._type, o, () => this.__defaultSerialize(ctx, o));
+    }
+    __defaultSerialize(ctx, o) {
         let out = 'insert into ' +
             o.table +
             '\n\t(' +
@@ -53,7 +56,7 @@ class InsertClass extends ReturningQuery {
         }
         else
             arr = Object.keys(this._input);
-        return ctx.serialize(SerializationType.INSERT_QUERY_COLUMNS, arr, () => printArray(arr));
+        return ctx.serialize(SerializationType.INSERT_QUERY_COLUMNS, arr, () => printArray(arr.map(c => ctx.escapeReserved(c))));
     }
     /**
      *

package/sql/operators/in.js

@@ -4,8 +4,13 @@ import { isSqlElement } from '../../type-guards.js';
 import { CompOperator } from './comp-operator.js';
 class InClass extends CompOperator {
     _serialize(ctx) {
-        if (Array.isArray(this._right) && !this._right.length)
-            return '';
+        if (Array.isArray(this._right) && !this._right.length) {
+            // Nothing can be IN an empty list (always false), and everything is
+            // NOT IN an empty list (always true). Emit a self-contained literal
+            // instead of dropping the condition, which would silently invert its
+            // meaning into "no filter at all".
+            return this._operatorType === OperatorType.notIn ? '1=1' : '1=0';
+        }
         return super._serialize(ctx);
     }
 }

package/sql/operators/index.d.ts

@@ -13,6 +13,7 @@ export * from './like.js';
 export * from './logical-operator.js';
 export * from './lt.js';
 export * from './lte.js';
+export * from './match.js';
 export * from './ne.js';
 export * from './not.js';
 export * from './not-between.js';

package/sql/operators/index.js

@@ -13,6 +13,7 @@ export * from './like.js';
 export * from './logical-operator.js';
 export * from './lt.js';
 export * from './lte.js';
+export * from './match.js';
 export * from './ne.js';
 export * from './not.js';
 export * from './not-between.js';

package/sql/operators/logical-operator.js

@@ -29,10 +29,13 @@ function wrapObject(obj) {
             const m = n.match(COMPARE_LEFT_PATTERN);
             if (!m)
                 throw new TypeError(`"${n}" is not a valid expression definition`);
-            fn = registeredOperators[m[2] || 'eq'];
+            // A bare array value with no explicit operator (e.g. {status: [...]})
+            // means "one of these values", not literal equality to an array.
+            const opKey = m[2] || (Array.isArray(v) ? 'in' : 'eq');
+            fn = registeredOperators[opKey];
             if (!fn)
-                throw new Error(`Unknown operator "${m[2]}"`);
-            const inst = fn(m[1], obj[n]);
+                throw new Error(`Unknown operator "${opKey}"`);
+            const inst = fn(m[1], v);
             result.push(inst);
         }
     }

package/sql/operators/match.d.ts

@@ -0,0 +1,16 @@
+import { SqlElement } from '../../serializable.js';
+import { SerializeContext } from '../../serialize-context.js';
+import { CompOperator } from './comp-operator.js';
+declare class MatchClass extends CompOperator {
+    customArgs?: any;
+    __serialize(ctx: SerializeContext, o: any): string;
+}
+interface MatchCtor {
+    new (left: string | SqlElement, right?: string | SqlElement, customArgs?: any): Match;
+    (left: string | SqlElement, right?: string | SqlElement, customArgs?: any): Match;
+    prototype: Match;
+}
+export declare const Match: MatchCtor;
+export interface Match extends MatchClass {
+}
+export {};

package/sql/operators/match.js

@@ -0,0 +1,32 @@
+import { OperatorType } from '../../enums.js';
+import { SqlElement } from '../../serializable.js';
+import { SerializeContext } from '../../serialize-context.js';
+import { CompOperator } from './comp-operator.js';
+class MatchClass extends CompOperator {
+    customArgs;
+    __serialize(ctx, o) {
+        if (!o.right.expression)
+            return '';
+        if (o.right && typeof o.right.expression !== 'string')
+            o.right.expression = String(o.right.expression);
+        o.customArgs = this.customArgs;
+        return ctx.serialize(this._type, o, (_ctx, _o) => this.__defaultSerialize(_ctx, _o));
+    }
+}
+export const Match = function (left, right, customArgs) {
+    if (!(this instanceof Match))
+        return new Match(left, right, customArgs);
+    CompOperator.call(this, left, right);
+    this._operatorType = OperatorType.match;
+    this._symbol = '=';
+    this.customArgs = customArgs;
+    if (typeof left === 'string') {
+        const m = left.match(/^([\w\\.$]+)(\[])?/);
+        if (!m)
+            throw new TypeError(`"${left}" is not a valid expression definition`);
+        this._left = m[1];
+        this._isArray = !!m[2];
+    }
+};
+Match.prototype = MatchClass.prototype;
+Match.prototype.constructor = Match;

package/sql/update.d.ts

@@ -18,6 +18,7 @@ declare class UpdateClass extends ReturningQuery {
      * Performs serialization
      */
     _serialize(ctx: SerializeContext): string;
+    protected __defaultSerialize(ctx: SerializeContext, o: any): string;
     /**
      *
      */

package/sql/update.js

@@ -33,6 +33,9 @@ class UpdateClass extends ReturningQuery {
             where: this.__serializeWhere(ctx),
             returning: this.__serializeReturning(ctx),
         };
+        return ctx.serialize(this._type, o, () => this.__defaultSerialize(ctx, o));
+    }
+    __defaultSerialize(ctx, o) {
         let out = 'update ' + o.table + ' set \n\t' + o.values + '\b';
         if (o.where)
             out += '\n' + o.where;
@@ -54,7 +57,7 @@ class UpdateClass extends ReturningQuery {
             });
         }
         return ctx.serialize(SerializationType.UPDATE_QUERY_VALUES, arr, () => {
-            const a = arr.map(o => o.field + ' = ' + o.value);
+            const a = arr.map(o => ctx.escapeReserved(o.field) + ' = ' + o.value);
             return printArray(a, ',');
         });
     }