uql-orm 0.6.0 → 0.7.2

package/dist/dialect/abstractSqlDialect.js

@@ -33,9 +33,33 @@ export class AbstractSqlDialect extends AbstractDialect {
         return new SqlQueryContext(this);
     }
     addValue(values, value) {
-        values.push(value ?? null);
+        values.push(this.normalizeValue(value));
         return this.placeholder(values.length);
     }
+    /**
+     * Normalizes a parameter value for the database driver.
+     * Handles bigint, boolean, and serializes plain objects/arrays to JSON strings.
+     * Date values are preserved so SQL drivers can apply native date/time binding.
+     * Postgres overrides to pass objects through to its native JSONB driver.
+     */
+    normalizeValue(value) {
+        if (typeof value === 'bigint')
+            return Number(value);
+        if (typeof value === 'boolean')
+            return value ? 1 : 0;
+        if (value instanceof Date)
+            return value;
+        if (value !== null && typeof value === 'object' && !(value instanceof Uint8Array) && !(value instanceof QueryRaw)) {
+            return JSON.stringify(value);
+        }
+        return value;
+    }
+    /**
+     * Normalizes a list of parameter values.
+     */
+    normalizeValues(values) {
+        return values?.map((v) => this.normalizeValue(v));
+    }
     placeholder(_index) {
         return '?';
     }
@@ -368,48 +392,61 @@ export class AbstractSqlDialect extends AbstractDialect {
         $gte: ' >= ',
         $lt: ' < ',
         $lte: ' <= ',
-        $regex: ' REGEXP ',
     };
-    /** String/LIKE operators: wrap the value, optionally lowercase it. */
     static LIKE_OP_MAP = {
-        $startsWith: { wrap: (v) => `${v}%`, lower: false },
-        $istartsWith: { wrap: (v) => `${v.toLowerCase()}%`, lower: false },
-        $endsWith: { wrap: (v) => `%${v}`, lower: false },
-        $iendsWith: { wrap: (v) => `%${v.toLowerCase()}`, lower: false },
-        $includes: { wrap: (v) => `%${v}%`, lower: false },
-        $iincludes: { wrap: (v) => `%${v.toLowerCase()}%`, lower: false },
-        $like: { wrap: (v) => v, lower: false },
-        $ilike: { wrap: (v) => v.toLowerCase(), lower: false },
+        $startsWith: (v) => `${v}%`,
+        $istartsWith: (v) => `${v.toLowerCase()}%`,
+        $endsWith: (v) => `%${v}`,
+        $iendsWith: (v) => `%${v.toLowerCase()}`,
+        $includes: (v) => `%${v}%`,
+        $iincludes: (v) => `%${v.toLowerCase()}%`,
+        $like: (v) => v,
+        $ilike: (v) => v.toLowerCase(),
     };
+    resolveColumnWithPrefix(entity, key, { prefix } = {}) {
+        const meta = getMeta(entity);
+        const field = meta.fields[key];
+        const columnName = this.resolveColumnName(key, field);
+        const escapedPrefix = this.escapeId(prefix, true, true);
+        return escapedPrefix + this.escapeId(columnName);
+    }
+    /**
+     * Resolves the SQL operand for a field comparison.
+     * For QueryRaw virtuals, appends the raw expression to ctx and returns undefined.
+     */
+    resolveOperandField(ctx, entity, key, opts) {
+        const col = getMeta(entity).fields[key];
+        if (col?.virtual) {
+            if (col.virtual instanceof QueryRaw) {
+                this.getComparisonKey(ctx, entity, key, opts);
+                return undefined;
+            }
+            return `(${col.virtual})`;
+        }
+        return this.resolveColumnWithPrefix(entity, key, opts);
+    }
+    appendFieldSql(ctx, field, sql) {
+        ctx.append(field ? `${field}${sql}` : sql);
+    }
     compareFieldOperator(ctx, entity, key, op, val, opts = {}) {
-        // Simple comparison operators (5 cases)
+        const field = this.resolveOperandField(ctx, entity, key, opts);
         const simpleOp = AbstractSqlDialect.COMPARE_OP_MAP[op];
         if (simpleOp) {
-            this.getComparisonKey(ctx, entity, key, opts);
-            ctx.append(simpleOp);
-            ctx.addValue(val);
+            this.appendFieldSql(ctx, field, `${simpleOp}${this.addValue(ctx.values, val)}`);
             return;
         }
-        // LIKE string operators (8 cases)
-        const likeEntry = AbstractSqlDialect.LIKE_OP_MAP[op];
-        if (likeEntry) {
-            this.getComparisonKey(ctx, entity, key, opts);
-            ctx.append(' LIKE ');
-            ctx.addValue(likeEntry.wrap(val));
+        const likeWrap = AbstractSqlDialect.LIKE_OP_MAP[op];
+        if (likeWrap) {
+            this.appendLikeOp(ctx, field, op, likeWrap(val));
             return;
         }
         switch (op) {
             case '$eq':
-                this.getComparisonKey(ctx, entity, key, opts);
-                ctx.append(val === null ? ' IS NULL' : ' = ');
-                if (val !== null)
-                    ctx.addValue(val);
-                break;
             case '$ne':
-                this.getComparisonKey(ctx, entity, key, opts);
-                ctx.append(val === null ? ' IS NOT NULL' : ' <> ');
-                if (val !== null)
-                    ctx.addValue(val);
+                this.appendEqNe(ctx, field, op, val);
+                break;
+            case '$regex':
+                this.appendFieldSql(ctx, field, ` ${this.regexpOp} ${this.addValue(ctx.values, val)}`);
                 break;
             case '$not':
                 ctx.append('NOT (');
@@ -417,35 +454,20 @@ export class AbstractSqlDialect extends AbstractDialect {
                 ctx.append(')');
                 break;
             case '$in':
-            case '$nin': {
-                this.getComparisonKey(ctx, entity, key, opts);
-                const keyword = op === '$in' ? ' IN ' : ' NOT IN ';
-                if (Array.isArray(val) && val.length > 0) {
-                    ctx.append(`${keyword}(`);
-                    this.addValues(ctx, val);
-                    ctx.append(')');
-                }
-                else {
-                    ctx.append(`${keyword}(NULL)`);
-                }
+            case '$nin':
+                this.appendInNin(ctx, field, op, val);
                 break;
-            }
             case '$between': {
+                const col = this.resolveColumnWithPrefix(entity, key, opts);
                 const [min, max] = val;
-                this.getComparisonKey(ctx, entity, key, opts);
-                ctx.append(' BETWEEN ');
-                ctx.addValue(min);
-                ctx.append(' AND ');
-                ctx.addValue(max);
+                ctx.append(`${col} BETWEEN ${this.addValue(ctx.values, min)} AND ${this.addValue(ctx.values, max)}`);
                 break;
             }
             case '$isNull':
-                this.getComparisonKey(ctx, entity, key, opts);
-                ctx.append(val ? ' IS NULL' : ' IS NOT NULL');
+                this.appendFieldSql(ctx, field, val ? ' IS NULL' : ' IS NOT NULL');
                 break;
             case '$isNotNull':
-                this.getComparisonKey(ctx, entity, key, opts);
-                ctx.append(val ? ' IS NOT NULL' : ' IS NULL');
+                this.appendFieldSql(ctx, field, val ? ' IS NOT NULL' : ' IS NULL');
                 break;
             case '$all':
             case '$size':
@@ -455,6 +477,36 @@ export class AbstractSqlDialect extends AbstractDialect {
                 throw TypeError(`unknown operator: ${op}`);
         }
     }
+    appendLikeOp(ctx, field, op, wrappedVal) {
+        const isIlike = op.startsWith('$i') || op === '$ilike';
+        const ph = this.addValue(ctx.values, wrappedVal);
+        if (isIlike && field) {
+            ctx.append(this.ilikeExpr(field, ph));
+        }
+        else {
+            this.appendFieldSql(ctx, field, ` ${this.likeFn} ${ph}`);
+        }
+    }
+    appendEqNe(ctx, field, op, val) {
+        if (val === null) {
+            this.appendFieldSql(ctx, field, op === '$eq' ? ' IS NULL' : ' IS NOT NULL');
+            return;
+        }
+        const ph = this.addValue(ctx.values, val);
+        if (op === '$eq') {
+            this.appendFieldSql(ctx, field, ` = ${ph}`);
+            return;
+        }
+        if (field) {
+            ctx.append(this.neExpr(field, ph));
+        }
+        else {
+            this.appendFieldSql(ctx, field, ` ${this.neOp} ${ph}`);
+        }
+    }
+    appendInNin(ctx, field, op, val) {
+        this.appendFieldSql(ctx, field, this.formatIn(ctx, Array.isArray(val) ? val : [], op === '$nin'));
+    }
     addValues(ctx, vals) {
         vals.forEach((val, index) => {
             if (index > 0) {
@@ -465,63 +517,54 @@ export class AbstractSqlDialect extends AbstractDialect {
     }
     /**
      * Build a comparison condition for a JSON field.
-     * Used by both `$elemMatch` and dot-notation paths. Each dialect provides a `JsonFieldConfig`.
+     * Used by both `$elemMatch` and dot-notation paths.
+     * All dialect-specific behavior comes from overridable methods on `this`.
      */
-    buildJsonFieldCondition(ctx, config, jsonPath, op, value) {
-        const jsonField = config.fieldAccessor(jsonPath);
+    buildJsonFieldCondition(ctx, fieldAccessor, jsonPath, op, value) {
+        const jsonField = fieldAccessor(jsonPath);
         switch (op) {
             case '$eq':
-                return value === null ? `${jsonField} IS NULL` : `${jsonField} = ${config.addValue(ctx, value)}`;
+                return value === null ? `${jsonField} IS NULL` : `${jsonField} = ${this.addValue(ctx.values, value)}`;
             case '$ne':
                 if (value === null)
                     return `${jsonField} IS NOT NULL`;
-                return config.neExpr
-                    ? config.neExpr(jsonField, config.addValue(ctx, value))
-                    : `${jsonField} <> ${config.addValue(ctx, value)}`;
+                return this.neExpr(jsonField, this.addValue(ctx.values, value));
             case '$gt':
-                return `${config.numericCast(jsonField)} > ${config.addValue(ctx, value)}`;
+                return `${this.numericCast(jsonField)} > ${this.addValue(ctx.values, value)}`;
             case '$gte':
-                return `${config.numericCast(jsonField)} >= ${config.addValue(ctx, value)}`;
+                return `${this.numericCast(jsonField)} >= ${this.addValue(ctx.values, value)}`;
             case '$lt':
-                return `${config.numericCast(jsonField)} < ${config.addValue(ctx, value)}`;
+                return `${this.numericCast(jsonField)} < ${this.addValue(ctx.values, value)}`;
             case '$lte':
-                return `${config.numericCast(jsonField)} <= ${config.addValue(ctx, value)}`;
+                return `${this.numericCast(jsonField)} <= ${this.addValue(ctx.values, value)}`;
             case '$like':
-                return `${jsonField} ${config.likeFn} ${config.addValue(ctx, value)}`;
+                return `${jsonField} ${this.likeFn} ${this.addValue(ctx.values, value)}`;
             case '$ilike':
-                return config.ilikeExpr(jsonField, config.addValue(ctx, value.toLowerCase()));
+                return this.ilikeExpr(jsonField, this.addValue(ctx.values, value.toLowerCase()));
             case '$startsWith':
-                return `${jsonField} ${config.likeFn} ${config.addValue(ctx, `${value}%`)}`;
+                return `${jsonField} ${this.likeFn} ${this.addValue(ctx.values, `${value}%`)}`;
             case '$istartsWith':
-                return config.ilikeExpr(jsonField, config.addValue(ctx, `${value.toLowerCase()}%`));
+                return this.ilikeExpr(jsonField, this.addValue(ctx.values, `${value.toLowerCase()}%`));
             case '$endsWith':
-                return `${jsonField} ${config.likeFn} ${config.addValue(ctx, `%${value}`)}`;
+                return `${jsonField} ${this.likeFn} ${this.addValue(ctx.values, `%${value}`)}`;
             case '$iendsWith':
-                return config.ilikeExpr(jsonField, config.addValue(ctx, `%${value.toLowerCase()}`));
+                return this.ilikeExpr(jsonField, this.addValue(ctx.values, `%${value.toLowerCase()}`));
             case '$includes':
-                return `${jsonField} ${config.likeFn} ${config.addValue(ctx, `%${value}%`)}`;
+                return `${jsonField} ${this.likeFn} ${this.addValue(ctx.values, `%${value}%`)}`;
             case '$iincludes':
-                return config.ilikeExpr(jsonField, config.addValue(ctx, `%${value.toLowerCase()}%`));
+                return this.ilikeExpr(jsonField, this.addValue(ctx.values, `%${value.toLowerCase()}%`));
             case '$regex':
-                return `${jsonField} ${config.regexpOp} ${config.addValue(ctx, value)}`;
-            case '$in': {
-                if (config.inExpr) {
-                    return config.inExpr(jsonField, config.addValue(ctx, value));
-                }
-                const inVals = value;
-                return `${jsonField} IN (${inVals.map((v) => config.addValue(ctx, v)).join(', ')})`;
-            }
-            case '$nin': {
-                if (config.ninExpr) {
-                    return config.ninExpr(jsonField, config.addValue(ctx, value));
-                }
-                const ninVals = value;
-                return `${jsonField} NOT IN (${ninVals.map((v) => config.addValue(ctx, v)).join(', ')})`;
-            }
+                return `${jsonField} ${this.regexpOp} ${this.addValue(ctx.values, value)}`;
+            case '$in':
+            case '$nin':
+                return this.jsonInNin(ctx, jsonField, op, value);
             default:
                 throw TypeError(`JSON field condition does not support operator: ${op}`);
         }
     }
+    jsonInNin(ctx, jsonField, op, value) {
+        return `${jsonField}${this.formatIn(ctx, Array.isArray(value) ? value : [], op === '$nin')}`;
+    }
     getComparisonKey(ctx, entity, key, { prefix } = {}) {
         const meta = getMeta(entity);
         const escapedPrefix = this.escapeId(prefix, true, true);
@@ -579,7 +622,7 @@ export class AbstractSqlDialect extends AbstractDialect {
             // Detect JSONB dot-notation: 'column.path'
             const jsonDot = this.resolveJsonDotPath(meta, key);
             if (jsonDot) {
-                ctx.append(jsonDot.config.fieldAccessor(jsonDot.jsonPath) + direction);
+                ctx.append(jsonDot.fieldAccessor(jsonDot.jsonPath) + direction);
                 return;
             }
             const field = meta.fields[key];
@@ -599,34 +642,47 @@ export class AbstractSqlDialect extends AbstractDialect {
         return { colName, distance, field, vectorCast };
     }
     /**
-     * Append a vector similarity ORDER BY expression.
-     * Base implementation throws — subclasses (Postgres, SQLite, MariaDB) override for dialect-specific operators.
+     * Mapping of UQL vector distance metrics to native SQL functions.
+     * Override in dialects that use function-call syntax (e.g. SQLite, MariaDB).
+     * Dialects with operator-based syntax (e.g. Postgres) leave this empty and override `appendVectorSort` directly.
      */
-    appendVectorSort(_ctx, _meta, _key, _search) {
-        throw new TypeError('Vector similarity sort is not supported by this dialect. Use raw() for vector queries.');
-    }
+    vectorDistanceFns = {};
     /**
-     * Shared helper for dialects that use function-call syntax: `fn(col, ?)`.
-     * Used by SQLite (`vec_distance_cosine`) and MariaDB (`VEC_DISTANCE_COSINE`).
+     * Append a vector similarity function call: `fn(col, ?)`.
+     * Used by dialects that express vector distance via SQL functions (SQLite, MariaDB).
      */
-    appendFunctionVectorSort(ctx, meta, key, search, fnMap, dialectName) {
-        const { colName, distance } = this.resolveVectorSortParams(meta, key, search);
-        const fn = fnMap[distance];
+    appendFunctionVectorSort(ctx, meta, key, search, dialectName) {
+        const { colName, distance, vectorCast } = this.resolveVectorSortParams(meta, key, search);
+        const fn = this.vectorDistanceFns[distance];
         if (!fn) {
-            throw new TypeError(`${dialectName} does not support vector distance metric: ${distance}`);
+            throw Error(`${dialectName} does not support vector distance metric: ${distance}`);
         }
         ctx.append(`${fn}(${this.escapeId(colName)}, `);
         ctx.addValue(`[${search.$vector.join(',')}]`);
+        if (vectorCast && dialectName === 'PostgreSQL') {
+            ctx.append(`::${vectorCast}`);
+        }
         ctx.append(')');
     }
     /**
-     * Append a vector distance projection (`<expr> AS <alias>`) in the SELECT clause.
-     * Delegates to `appendVectorSort()` (which emits the distance expression) then appends the alias.
+     * Append a vector distance projection.
      */
     appendVectorProjection(ctx, meta, key, search) {
         this.appendVectorSort(ctx, meta, key, search);
         ctx.append(` AS ${this.escapeId(search.$project)}`);
     }
+    /**
+     * Append a vector similarity ORDER BY expression.
+     * Default: auto-delegates to `appendFunctionVectorSort` when `vectorDistanceFns` has entries.
+     * Override for operator-based syntax (e.g. PostgreSQL `<=>`, `<->` operators).
+     */
+    appendVectorSort(ctx, meta, key, search) {
+        if (hasKeys(this.vectorDistanceFns)) {
+            this.appendFunctionVectorSort(ctx, meta, key, search, this.dialect);
+            return;
+        }
+        throw new TypeError('Vector similarity sort is not supported by this dialect. Use raw() for vector queries.');
+    }
     pager(ctx, opts) {
         if (opts.$limit) {
             ctx.append(` LIMIT ${Number(opts.$limit)}`);
@@ -733,15 +789,7 @@ export class AbstractSqlDialect extends AbstractDialect {
                 ctx.addValue(max);
             }
             else if (op === '$in' || op === '$nin') {
-                const keyword = op === '$in' ? 'IN' : 'NOT IN';
-                if (Array.isArray(val) && val.length > 0) {
-                    ctx.append(`${expr} ${keyword} (`);
-                    this.addValues(ctx, val);
-                    ctx.append(')');
-                }
-                else {
-                    ctx.append(`${expr} ${keyword} (NULL)`);
-                }
+                ctx.append(`${expr}${this.formatIn(ctx, Array.isArray(val) ? val : [], op === '$nin')}`);
             }
             else if (op === '$isNull') {
                 ctx.append(`${expr}${val ? ' IS NULL' : ' IS NOT NULL'}`);
@@ -749,6 +797,9 @@ export class AbstractSqlDialect extends AbstractDialect {
             else if (op === '$isNotNull') {
                 ctx.append(`${expr}${val ? ' IS NOT NULL' : ' IS NULL'}`);
             }
+            else if (op === '$ne') {
+                ctx.append(this.neExpr(expr, this.addValue(ctx.values, val)));
+            }
             else {
                 const sqlOp = AbstractSqlDialect.havingOpMap[op];
                 if (!sqlOp)
@@ -1012,15 +1063,14 @@ export class AbstractSqlDialect extends AbstractDialect {
         const jsonPath = key.slice(dotIndex + 1);
         const colName = this.resolveColumnName(root, field);
         const escapedCol = (prefix ? this.escapeId(prefix, true, true) : '') + this.escapeId(colName);
-        const config = this.getJsonFieldConfig(escapedCol, jsonPath);
-        return { root, jsonPath, config };
+        return { root, jsonPath, fieldAccessor: () => this.getJsonPathScalarExpr(escapedCol, jsonPath) };
     }
     /**
      * Compare a JSONB dot-notation path, e.g. `'settings.isArchived': { $ne: true }`.
      * Receives a pre-resolved `resolveJsonDotPath` result to avoid redundant computation.
      */
     compareJsonPath(ctx, resolved, val) {
-        const { jsonPath, config } = resolved;
+        const { jsonPath, fieldAccessor } = resolved;
         const value = this.normalizeWhereValue(val);
         const operators = getKeys(value);
         if (operators.length > 1) {
@@ -1029,25 +1079,12 @@ export class AbstractSqlDialect extends AbstractDialect {
         operators.forEach((op, index) => {
             if (index > 0)
                 ctx.append(' AND ');
-            ctx.append(this.buildJsonFieldCondition(ctx, config, jsonPath, op, value[op]));
+            ctx.append(this.buildJsonFieldCondition(ctx, fieldAccessor, jsonPath, op, value[op]));
         });
         if (operators.length > 1) {
             ctx.append(')');
         }
     }
-    /**
-     * Returns a dialect-specific `JsonFieldConfig` for accessing a nested JSON path.
-     * Dialects should override this to provide their specific JSON accessor syntax.
-     *
-     * @param escapedColumn - The escaped column name (possibly prefixed with table name)
-     * @param jsonPath - The dot-separated path within the JSON field (e.g. 'isArchived' or 'theme.color')
-     */
-    getJsonFieldConfig(escapedColumn, jsonPath) {
-        return {
-            ...this.getBaseJsonConfig(),
-            fieldAccessor: () => this.getJsonPathScalarExpr(escapedColumn, jsonPath),
-        };
-    }
     /**
      * Returns SQL that extracts a scalar value from a JSON path.
      * Dialects can override this to customize path access syntax while preserving
@@ -1062,23 +1099,6 @@ export class AbstractSqlDialect extends AbstractDialect {
         }
         return expr;
     }
-    /**
-     * Returns the dialect-invariant portion of `JsonFieldConfig`.
-     * Dialects override this to provide casts, operators, and value binding.
-     * Both `getJsonFieldConfig` (dot-notation) and `buildJsonFieldOperator` ($elemMatch) compose with this.
-     */
-    getBaseJsonConfig() {
-        return {
-            numericCast: (expr) => `CAST(${expr} AS NUMERIC)`,
-            likeFn: 'LIKE',
-            ilikeExpr: (f, ph) => `LOWER(${f}) LIKE ${ph}`,
-            regexpOp: 'REGEXP',
-            addValue: (c, v) => {
-                c.pushValue(v);
-                return '?';
-            },
-        };
-    }
     /**
      * Normalizes a raw WHERE value into an operator map.
      * Arrays become `$in`, scalars/null become `$eq`, objects pass through.
@@ -1248,6 +1268,38 @@ export class AbstractSqlDialect extends AbstractDialect {
                 throw TypeError(`unsupported $size comparison operator: ${op}`);
         }
     }
+    get regexpOp() {
+        return 'REGEXP';
+    }
+    get likeFn() {
+        return 'LIKE';
+    }
+    /**
+     * Not-equal operator token for non-null comparisons.
+     * Postgres uses `IS DISTINCT FROM`; MySQL/Maria uses custom `neExpr`.
+     */
+    get neOp() {
+        return '<>';
+    }
+    neExpr(field, ph) {
+        return `${field} ${this.neOp} ${ph}`;
+    }
+    ilikeExpr(f, ph) {
+        return `LOWER(${f}) LIKE ${ph}`;
+    }
+    /**
+     * Formats an IN/NOT IN expression, binding each value individually.
+     * Postgres overrides to use `= ANY($1)` / `<> ALL($1)` with a single array parameter.
+     */
+    formatIn(ctx, values, negate) {
+        if (values.length === 0)
+            return negate ? ' NOT IN (NULL)' : ' IN (NULL)';
+        const phs = values.map((v) => this.addValue(ctx.values, v)).join(', ');
+        return ` ${negate ? 'NOT IN' : 'IN'} (${phs})`;
+    }
+    numericCast(expr) {
+        return expr;
+    }
 }
 /**
  * Type guard: narrows a relation select value to a query object (with optional `$required`).