turbine-orm 0.27.1 → 0.28.1

package/dist/cjs/query/deferred.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * turbine-orm — Deferred query + QueryInterface option types
+ *
+ * Split from builder.ts so the class file focuses on SQL assembly / execution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/query/filters.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * turbine-orm — Where-filter type guards and shape helpers
+ *
+ * Pure detection / fingerprint utilities used by the query builder's WHERE
+ * compiler. Kept out of builder.ts so the class file stays about SQL assembly
+ * and execution rather than filter-shape bookkeeping.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VECTOR_DISTANCE_COMPARATORS = exports.VECTOR_METRIC_OPERATORS = exports.TEXT_SEARCH_KEYS = exports.ARRAY_UNIQUE_KEYS = exports.ARRAY_OPERATOR_KEYS = exports.JSONB_UNIQUE_KEYS = exports.JSONB_OPERATOR_KEYS = exports.UPDATE_OPERATOR_KEYS = void 0;
+exports.isWhereOperator = isWhereOperator;
+exports.isUnmatchedPlainObject = isUnmatchedPlainObject;
+exports.fingerprintOperatorShape = fingerprintOperatorShape;
+exports.assertBindableEqualsOperand = assertBindableEqualsOperand;
+exports.sortedKeys = sortedKeys;
+exports.sortedEntries = sortedEntries;
+exports.isJsonFilter = isJsonFilter;
+exports.findJsonUniqueKey = findJsonUniqueKey;
+exports.isArrayFilter = isArrayFilter;
+exports.findArrayUniqueKey = findArrayUniqueKey;
+exports.isTextSearchFilter = isTextSearchFilter;
+exports.validateTextSearchConfig = validateTextSearchConfig;
+exports.isVectorFilter = isVectorFilter;
+exports.isVectorOrderBy = isVectorOrderBy;
+exports.isOrderBySpec = isOrderBySpec;
+exports.normalizeOrderBy = normalizeOrderBy;
+const errors_js_1 = require("../errors.js");
+const utils_js_1 = require("./utils.js");
+// ---------------------------------------------------------------------------
+// Where-operator detection
+// ---------------------------------------------------------------------------
+/** Check if a value is a where operator object (has at least one known operator key) */
+function isWhereOperator(value) {
+    if (value === null ||
+        value === undefined ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        value instanceof Date) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every((k) => utils_js_1.OPERATOR_KEYS.has(k));
+}
+/**
+ * True for a *plain object literal* that reached an equality fallthrough
+ * without matching any known filter shape — the misspelled-operator case.
+ * Class instances (Buffer for bytea, Decimal wrappers, ...) are legitimate
+ * bind values and return false, as do arrays and Dates.
+ */
+function isUnmatchedPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value) || value instanceof Date)
+        return false;
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
+ * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
+ * param pushed), so null-ness is part of the shape — without it a cache entry
+ * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ */
+function fingerprintOperatorShape(value) {
+    const obj = value;
+    const opKeys = Object.keys(obj)
+        .filter((k) => k !== 'mode')
+        .map((k) => ((k === 'equals' || k === 'not') && obj[k] === null ? `${k}:null` : k))
+        .sort();
+    const modeStr = value.mode === 'insensitive' ? ':i' : '';
+    return `op(${opKeys.join(',')}${modeStr})`;
+}
+/**
+ * Guard for the value of an `equals` operator reaching the plain-equality
+ * operator path. A plain object literal can only legitimately be an equality
+ * value on a json/jsonb column — and those route to the JSONB filter branch
+ * BEFORE the operator branch, so any plain object that reaches here is a
+ * mistake (e.g. `{ equals: { foo: 1 } }` on a text column). Shared by the
+ * SQL-build path and the cache-hit param-collect path so a warmed cache can
+ * never skip the check.
+ */
+function assertBindableEqualsOperand(value, column) {
+    if (!isUnmatchedPlainObject(value))
+        return;
+    throw new errors_js_1.ValidationError(`[turbine] Plain-object value for operator 'equals' on ${column}: ` +
+        `objects are only valid 'equals' values on JSON (json/jsonb) columns, ` +
+        `where 'equals' is the JSONB containment filter.`);
+}
+/**
+ * Object keys in sorted order, mirroring the canonical order used by every
+ * cache fingerprint. The SQL-build and cache-hit param-collect paths MUST
+ * enumerate object keys in this exact order: fingerprints sort keys, so two
+ * where clauses with the same fields in different insertion order share one
+ * cache entry — if build/collect iterated insertion order, the cached SQL's
+ * `$N` placeholders would bind the wrong values (cross-tenant-leak class).
+ * Array order (OR/AND members) is positional and is never sorted.
+ */
+function sortedKeys(obj) {
+    return Object.keys(obj).sort();
+}
+/** {@link sortedKeys}, but yielding `[key, value]` pairs. */
+function sortedEntries(obj) {
+    return Object.entries(obj).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+// ---------------------------------------------------------------------------
+// Atomic-update / JSONB / Array / text-search / vector key sets
+// ---------------------------------------------------------------------------
+/** Known atomic-update operator keys — used to detect operator objects vs plain JSON values */
+exports.UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
+/** Known JSONB operator keys */
+exports.JSONB_OPERATOR_KEYS = new Set(['path', 'equals', 'contains', 'hasKey']);
+/**
+ * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
+ * appear in any other where-filter shape, so the presence of one of these is
+ * an unambiguous signal that the user meant a JSON filter. Used by the
+ * strict-validation path so that `{ contains: 'foo' }` (which is also a valid
+ * `WhereOperator` for LIKE) is not misclassified. Note `equals` is NOT in this
+ * set: on non-JSON columns it is a plain equality operator (`WhereOperator`),
+ * so it must fall through instead of throwing.
+ */
+exports.JSONB_UNIQUE_KEYS = new Set(['path', 'hasKey']);
+/** Check if a value is a JSONB filter object */
+function isJsonFilter(value) {
+    if (value === null ||
+        value === undefined ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        value instanceof Date) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.some((k) => exports.JSONB_OPERATOR_KEYS.has(k));
+}
+/**
+ * Returns the first JSON-unique key found in `value`, or `null` if none.
+ * Used to drive the strict-validation error message.
+ */
+function findJsonUniqueKey(value) {
+    for (const k of Object.keys(value)) {
+        if (exports.JSONB_UNIQUE_KEYS.has(k))
+            return k;
+    }
+    return null;
+}
+/** Known Array operator keys */
+exports.ARRAY_OPERATOR_KEYS = new Set(['has', 'hasEvery', 'hasSome', 'isEmpty']);
+/**
+ * Array operator keys that are *unique* to {@link ArrayFilter}. None of the
+ * array operators currently overlap with `WhereOperator` or `JsonFilter`, so
+ * this set equals {@link ARRAY_OPERATOR_KEYS}; it is kept as a separate
+ * constant so a future overlap (e.g. a `contains` for arrays) is easy to
+ * carve out.
+ */
+exports.ARRAY_UNIQUE_KEYS = new Set(['has', 'hasEvery', 'hasSome', 'isEmpty']);
+/** Check if a value is an Array filter object */
+function isArrayFilter(value) {
+    if (value === null ||
+        value === undefined ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        value instanceof Date) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.some((k) => exports.ARRAY_OPERATOR_KEYS.has(k));
+}
+/**
+ * Returns the first array-unique key found in `value`, or `null` if none.
+ * Used to drive the strict-validation error message.
+ */
+function findArrayUniqueKey(value) {
+    for (const k of Object.keys(value)) {
+        if (exports.ARRAY_UNIQUE_KEYS.has(k))
+            return k;
+    }
+    return null;
+}
+/** Known text search operator keys */
+exports.TEXT_SEARCH_KEYS = new Set(['search', 'config']);
+/** Check if a value is a TextSearchFilter object */
+function isTextSearchFilter(value) {
+    if (value === null ||
+        value === undefined ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        value instanceof Date) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    // Must have 'search' key and only known text search keys
+    return keys.includes('search') && keys.every((k) => exports.TEXT_SEARCH_KEYS.has(k));
+}
+/**
+ * Validate a text search config name. Only alphanumeric characters and
+ * underscores are allowed to prevent SQL injection via the config parameter.
+ */
+function validateTextSearchConfig(config) {
+    return /^[a-zA-Z0-9_]+$/.test(config);
+}
+/**
+ * pgvector distance metric → operator allow-list. This is the ONLY mapping
+ * from a user-supplied metric token to a SQL operator; any token not present
+ * here is rejected, so a user value can never become an arbitrary operator.
+ *
+ *  - `l2`     → `<->` (Euclidean / L2 distance)
+ *  - `cosine` → `<=>` (cosine distance)
+ *  - `ip`     → `<#>` (negative inner product)
+ */
+exports.VECTOR_METRIC_OPERATORS = {
+    l2: '<->',
+    cosine: '<=>',
+    ip: '<#>',
+};
+/** Comparison keys allowed on a {@link VectorDistanceFilter}. */
+exports.VECTOR_DISTANCE_COMPARATORS = {
+    lt: '<',
+    lte: '<=',
+    gt: '>',
+    gte: '>=',
+};
+/** Check if a value is a vector distance WHERE filter: `{ distance: { to, metric } }` */
+function isVectorFilter(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value) || value instanceof Date) {
+        return false;
+    }
+    const dist = value.distance;
+    return (typeof dist === 'object' &&
+        dist !== null &&
+        !Array.isArray(dist) &&
+        'to' in dist &&
+        'metric' in dist);
+}
+/** Check if an orderBy value is a vector KNN ordering: `{ distance: { to, metric } }` */
+function isVectorOrderBy(value) {
+    return isVectorFilter(value);
+}
+/** Check if an orderBy value is an explicit `{ sort, nulls? }` spec. */
+function isOrderBySpec(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && 'sort' in value;
+}
+/**
+ * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
+ * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile
+ * path (findMany, groupBy, relation inner subqueries).
+ */
+function normalizeOrderBy(value) {
+    if (isOrderBySpec(value)) {
+        return { dir: value.sort.toLowerCase() === 'desc' ? 'DESC' : 'ASC', nulls: value.nulls };
+    }
+    return { dir: String(value).toLowerCase() === 'desc' ? 'DESC' : 'ASC' };
+}

package/dist/cjs/schema-builder.js

@@ -57,12 +57,34 @@ const TYPE_MAP = {
     double: 'DOUBLE PRECISION',
     numeric: 'NUMERIC',
     bytea: 'BYTEA',
+    // Sentinels — the real DDL type is derived from `enumName` / `dimensions`
+    // in schema-sql.ts, never from these placeholders.
+    enum: 'ENUM',
+    vector: 'VECTOR',
 };
 /** Convert a user-facing ColumnDef to the internal ColumnConfig */
 function resolveColumn(def) {
     if (!(def.type in TYPE_MAP)) {
         throw new Error(`Invalid column type "${def.type}". Valid types: ${Object.keys(TYPE_MAP).join(', ')}`);
     }
+    if (def.type === 'enum' && !def.enumName) {
+        throw new Error(`Column of type "enum" requires an "enumName" (the CREATE TYPE name).`);
+    }
+    if (def.type === 'vector' && (def.dimensions == null || def.dimensions <= 0)) {
+        throw new Error(`Column of type "vector" requires a positive "dimensions" count.`);
+    }
+    // `references` is either the "table.column" string or a { target, onDelete, onUpdate } object.
+    let referencesTarget = null;
+    let onDelete = null;
+    let onUpdate = null;
+    if (typeof def.references === 'string') {
+        referencesTarget = def.references;
+    }
+    else if (def.references) {
+        referencesTarget = def.references.target;
+        onDelete = def.references.onDelete ?? null;
+        onUpdate = def.references.onUpdate ?? null;
+    }
     return {
         type: TYPE_MAP[def.type],
         isPrimaryKey: def.primaryKey ?? false,
@@ -70,8 +92,14 @@ function resolveColumn(def) {
         isNullable: def.nullable ?? false,
         isUnique: def.unique ?? false,
         defaultValue: def.default ?? null,
-        referencesTarget: def.references ?? null,
+        referencesTarget,
         maxLength: def.maxLength ?? null,
+        onDelete,
+        onUpdate,
+        enumName: def.enumName ?? null,
+        vectorDimensions: def.dimensions ?? null,
+        isArray: def.array ?? false,
+        check: def.check ?? null,
     };
 }
 /** Check if a value is a TableDef (from legacy table() builder) */
@@ -97,7 +125,7 @@ function isTableDef(v) {
  * });
  * ```
  */
-function defineSchema(input) {
+function defineSchema(input, options) {
     const tables = {};
     for (const [accessor, value] of Object.entries(input)) {
         // The user-facing key is the camelCase JS accessor; the DDL-facing
@@ -116,6 +144,7 @@ function defineSchema(input) {
             const columns = {};
             let pk;
             let m2m;
+            let checks;
             for (const [fieldName, def] of Object.entries(raw)) {
                 if (fieldName === 'manyToMany') {
                     if (def !== undefined) {
@@ -126,6 +155,15 @@ function defineSchema(input) {
                     }
                     continue;
                 }
+                if (fieldName === 'checks') {
+                    if (def !== undefined) {
+                        if (!Array.isArray(def)) {
+                            throw new Error(`Table "${accessor}": "checks" must be an array of { name?, expression } objects`);
+                        }
+                        checks = def;
+                    }
+                    continue;
+                }
                 if (fieldName === 'primaryKey') {
                     // Top-level composite primary key declaration
                     if (def !== undefined) {
@@ -166,10 +204,11 @@ function defineSchema(input) {
                 columns,
                 ...(pk && pk.length > 0 ? { primaryKey: pk } : {}),
                 ...(m2m && m2m.length > 0 ? { manyToMany: m2m } : {}),
+                ...(checks && checks.length > 0 ? { checks } : {}),
             };
         }
     }
-    return { tables };
+    return { tables, ...(options?.enums ? { enums: options.enums } : {}) };
 }
 /**
  * Local copy of camelToSnake to avoid a circular import dependency at the
@@ -193,6 +232,12 @@ class ColumnBuilder {
             defaultValue: null,
             referencesTarget: null,
             maxLength: null,
+            onDelete: null,
+            onUpdate: null,
+            enumName: null,
+            vectorDimensions: null,
+            isArray: false,
+            check: null,
         };
     }
     serial() {
@@ -289,8 +334,18 @@ class ColumnBuilder {
         this._config.defaultValue = val;
         return this;
     }
-    references(target) {
+    references(target, opts) {
         this._config.referencesTarget = target;
+        this._config.onDelete = opts?.onDelete ?? null;
+        this._config.onUpdate = opts?.onUpdate ?? null;
+        return this;
+    }
+    check(expression) {
+        this._config.check = expression;
+        return this;
+    }
+    array() {
+        this._config.isArray = true;
         return this;
     }
     build() {