ts-prorm-orm 1.2.2 → 2.0.0

package/dist/dialects/oracle/index.d.ts

@@ -772,7 +772,14 @@ export declare class OracleDialect implements Dialect {
      */
     private buildOperatorWhere;
     /**
-     * Build ORDER BY clause
+     * Build ORDER BY clause.
+     *
+     * Every `Order` shape is handled explicitly. Previously this only ever
+     * called `Object.keys()`/`Object.entries()` on each item, which is correct
+     * for the `{ field: 'DESC' }` map form but silently mis-reads every other
+     * one: a `['name', 'DESC']` tuple yielded its indices (`ORDER BY "0" ASC`)
+     * and a bare `'name DESC'` string yielded its character indices — ordering
+     * by the wrong thing rather than failing.
      */
     buildOrderClause(order: Order, _options?: BuildOptions): string;
     /**
@@ -1020,9 +1027,13 @@ export declare class OracleDialect implements Dialect {
      */
     commentColumn(tableName: string, columnName: string, comment: string): Promise<void>;
     /**
-     * Create a partial index (index with WHERE clause)
+     * Partial indexes - not available on Oracle.
+     *
+     * Oracle's `CREATE INDEX` has no `WHERE` clause; the equivalent is a
+     * function-based index on a CASE expression that yields NULL for the rows to
+     * exclude, since a B-tree index does not store all-NULL keys.
      */
-    createPartialIndex(tableName: string, indexName: string, fields: string[], where: string, options?: IndexOptions): Promise<void>;
+    createPartialIndex(_tableName: string, _indexName: string, _fields: string[], _where: string, _options?: IndexOptions): Promise<void>;
     /**
      * Create an expression index (functional index)
      */

package/dist/dialects/oracle/index.js

@@ -6,6 +6,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OracleDialect = void 0;
 exports.createOracleDialect = createOracleDialect;
+const partial_index_1 = require("../partial-index");
 // Lazily-loaded `oracledb` driver. The native Oracle client is only loaded the
 // first time a connection is opened, so importing this ORM never dlopens the
 // oracledb native addon.
@@ -24,8 +25,10 @@ function loadOracleDb() {
     return oracledbModule;
 }
 const query_stream_helper_1 = require("../query-stream-helper");
+const lock_clause_helper_1 = require("../lock-clause-helper");
 const errors_1 = require("../../errors");
 const crypto_1 = require("crypto");
+const order_expression_helper_1 = require("../order-expression-helper");
 /**
  * Oracle-specific transaction class
  */
@@ -1295,9 +1298,12 @@ class OracleDialect {
             sql += ` ${options.type.toUpperCase()}`;
         }
         sql += ` INDEX ${this.quoteIdentifier(indexName)} ON ${this.quoteTable(tableName)} (${fieldsSql})`;
+        // Oracle's CREATE INDEX has no WHERE clause - there are no partial indexes.
+        // This used to append one built by the ordinary WHERE builder, so the
+        // statement reached the server both syntactically invalid and carrying
+        // unbound placeholders. Fail with a reason instead.
         if (options?.where) {
-            const whereClause = this.buildWhereClause(options.where);
-            sql += ` WHERE ${whereClause.sql}`;
+            throw (0, partial_index_1.unsupportedPartialIndex)(this.name);
         }
         return sql;
     }
@@ -1616,22 +1622,52 @@ class OracleDialect {
         }
     }
     /**
-     * Build ORDER BY clause
+     * Build ORDER BY clause.
+     *
+     * Every `Order` shape is handled explicitly. Previously this only ever
+     * called `Object.keys()`/`Object.entries()` on each item, which is correct
+     * for the `{ field: 'DESC' }` map form but silently mis-reads every other
+     * one: a `['name', 'DESC']` tuple yielded its indices (`ORDER BY "0" ASC`)
+     * and a bare `'name DESC'` string yielded its character indices — ordering
+     * by the wrong thing rather than failing.
      */
     buildOrderClause(order, _options) {
         if (!order || (Array.isArray(order) && order.length === 0)) {
             return '';
         }
-        const orderParts = Array.isArray(order)
-            ? order.map((o) => {
-                const field = Object.keys(o)[0];
-                const direction = Object.values(o)[0];
-                return `${this.quoteIdentifier(field)} ${direction === 'DESC' ? 'DESC' : 'ASC'}`;
-            })
-            : Object.entries(order).map(([field, direction]) => {
-                return `${this.quoteIdentifier(field)} ${direction === 'DESC' ? 'DESC' : 'ASC'}`;
-            });
-        return `ORDER BY ${orderParts.join(', ')}`;
+        const orderParts = [];
+        const term = (field, direction) => `${this.quoteIdentifier(field)} ${String(direction).toUpperCase() === 'DESC' ? 'DESC' : 'ASC'}`;
+        const processOrder = (orderItem) => {
+            // Order helpers: asc('name') / desc('name') / random(). Handled first so
+            // a bare `order: random()` works as well as one inside the order array.
+            const orderExpr = (0, order_expression_helper_1.renderOrderExpressionItem)(this, orderItem);
+            if (orderExpr !== null) {
+                orderParts.push(orderExpr);
+            }
+            else if (typeof orderItem === 'string') {
+                // 'name' or 'name DESC'
+                const [field, direction] = orderItem.trim().split(/\s+/);
+                orderParts.push(term(field, direction));
+            }
+            else if (Array.isArray(orderItem)) {
+                // ['name', 'DESC'] or ['name']
+                const [field, direction] = orderItem;
+                orderParts.push(term(String(field), direction));
+            }
+            else if (orderItem && typeof orderItem === 'object') {
+                // { field: 'DESC' } map form
+                for (const [field, direction] of Object.entries(orderItem)) {
+                    orderParts.push(term(field, direction));
+                }
+            }
+        };
+        if (Array.isArray(order)) {
+            order.forEach(processOrder);
+        }
+        else {
+            processOrder(order);
+        }
+        return orderParts.length > 0 ? `ORDER BY ${orderParts.join(', ')}` : '';
     }
     /**
      * Build a list of ORDER BY items (without the leading `ORDER BY` keyword),
@@ -1899,13 +1935,11 @@ class OracleDialect {
                 sql += ` AND ROWNUM <= ${limit + offset}`;
             }
         }
-        // FOR UPDATE (locking)
-        if (options.lock) {
-            sql += ' FOR UPDATE';
-            if (options.lock === 'SHARE') {
-                sql += ' NOWAIT';
-            }
-        }
+        // Row-level locking: `FOR UPDATE [NOWAIT | SKIP LOCKED]`. Oracle has no
+        // shared row lock, so `lock: 'SHARE'` now throws instead of quietly turning
+        // into an exclusive `FOR UPDATE NOWAIT`. `lock.of` names *columns* in
+        // Oracle, not a table, so a `{ of: Model }` lock stays a plain FOR UPDATE.
+        sql += (0, lock_clause_helper_1.appendLockClause)(options.lock, lock_clause_helper_1.ORACLE_LOCK_SPEC);
         return { sql, values };
     }
     /**
@@ -2705,22 +2739,18 @@ END;
     }
     // ==================== Advanced Indexes ====================
     /**
-     * Create a partial index (index with WHERE clause)
-     */
-    async createPartialIndex(tableName, indexName, fields, where, options) {
-        const fieldsSql = fields.map((f) => this.quoteIdentifier(f)).join(', ');
-        let sql = `CREATE`;
-        if (options?.unique) {
-            sql += ' UNIQUE';
-        }
-        sql += ` INDEX ${this.quoteIdentifier(indexName)} ON ${this.quoteTable(tableName)} (${fieldsSql}) WHERE ${where}`;
-        if (options?.tablespace) {
-            sql += ` TABLESPACE ${options.tablespace}`;
-        }
-        if (options?.compress) {
-            sql += ` COMPRESS`;
-        }
-        await this.query(sql);
+     * Partial indexes - not available on Oracle.
+     *
+     * Oracle's `CREATE INDEX` has no `WHERE` clause; the equivalent is a
+     * function-based index on a CASE expression that yields NULL for the rows to
+     * exclude, since a B-tree index does not store all-NULL keys.
+     */
+    async createPartialIndex(_tableName, _indexName, _fields, _where, _options) {
+        // This used to emit `CREATE INDEX ... WHERE ...`, which Oracle has never
+        // accepted. The Oracle-shaped equivalent is a function-based index on a
+        // CASE expression that returns NULL for the excluded rows (NULLs are not
+        // stored in a B-tree index), i.e. createExpressionIndex.
+        throw (0, partial_index_1.unsupportedPartialIndex)(this.name);
     }
     /**
      * Create an expression index (functional index)

package/dist/dialects/order-expression-helper.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared rendering for the `OrderExpression` objects produced by the public
+ * `asc()` / `desc()` / `random()` helpers exported from `src/operators.ts`.
+ *
+ * Every dialect implements its own `buildOrderClause()` with slightly
+ * different handling of the legacy `order` shapes it accepts (bare strings,
+ * `['field', 'DESC']` tuples, `{ field: 'DESC' }` maps, `[Model, 'field']`
+ * pairs, ...). Rather than teach ~27 dialect files how to recognise and
+ * render an `OrderExpression` — the same code copied 27 times — each dialect
+ * calls into this module for exactly that one item shape and keeps its own
+ * handling for everything else. This mirrors `./query-stream-helper.ts`,
+ * which factors one cross-cutting behaviour out of the dialects the same way.
+ *
+ * The one genuinely dialect-specific piece is `random()`: the function used
+ * to produce a random sort key differs per engine, so it is looked up from
+ * `RANDOM_FUNCTIONS` by the dialect's own `name`. Dialects with no known
+ * random-ordering function throw a descriptive error rather than silently
+ * emitting SQL that would not run (or, worse, no `ORDER BY` at all, which is
+ * what `order: random()` used to do everywhere).
+ */
+import { type OrderExpression } from '../operators';
+import type { Order } from '../types';
+/**
+ * The slice of a dialect this helper needs. Deliberately narrower than the
+ * full `Dialect` interface so it can be unit tested with a stub, and so
+ * `buildOrderClause()` implementations can pass `this` without a cast.
+ */
+export interface OrderExpressionDialect {
+    /** The dialect's registered name, e.g. `'sqlite'`, `'mysql'`, `'mssql'`. */
+    readonly name: string;
+    /** The dialect's own identifier quoting. */
+    escapeId(identifier: unknown): string;
+}
+/**
+ * The SQL expression that orders rows randomly on `dialectName`.
+ *
+ * @throws if the dialect has no known random-ordering function — callers get
+ * an actionable error instead of SQL that silently does the wrong thing.
+ */
+export declare function randomOrderFunction(dialectName: string | undefined): string;
+/**
+ * Render one `OrderExpression` as an `ORDER BY` list item (no leading
+ * `ORDER BY`), using the dialect's own identifier quoting.
+ */
+export declare function renderOrderExpression(dialect: OrderExpressionDialect, expression: OrderExpression): string;
+/**
+ * Render `item` if — and only if — it is an `OrderExpression`; otherwise
+ * return `null` so the caller falls through to its own handling of the
+ * legacy order shapes.
+ *
+ * Usage inside a dialect's `buildOrderClause()`:
+ *
+ * ```ts
+ * const orderExpr = renderOrderExpressionItem(this, item);
+ * if (orderExpr !== null) {
+ *   orderParts.push(orderExpr);
+ *   continue;
+ * }
+ * ```
+ */
+export declare function renderOrderExpressionItem(dialect: OrderExpressionDialect, item: unknown): string | null;
+/**
+ * Normalise a `FindOptions.order` value into the list of items a dialect
+ * should iterate over.
+ *
+ * Behaviour is intentionally conservative so no currently-working shape
+ * changes: arrays pass straight through, a **bare** `OrderExpression`
+ * (`order: random()`) is wrapped into a single-item list, and anything else
+ * non-array yields `[]` — exactly what the `!Array.isArray(order)` guard the
+ * dialects used to open with produced.
+ */
+export declare function normalizeOrderItems(order: Order | undefined | null): unknown[];

package/dist/dialects/order-expression-helper.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Shared rendering for the `OrderExpression` objects produced by the public
+ * `asc()` / `desc()` / `random()` helpers exported from `src/operators.ts`.
+ *
+ * Every dialect implements its own `buildOrderClause()` with slightly
+ * different handling of the legacy `order` shapes it accepts (bare strings,
+ * `['field', 'DESC']` tuples, `{ field: 'DESC' }` maps, `[Model, 'field']`
+ * pairs, ...). Rather than teach ~27 dialect files how to recognise and
+ * render an `OrderExpression` — the same code copied 27 times — each dialect
+ * calls into this module for exactly that one item shape and keeps its own
+ * handling for everything else. This mirrors `./query-stream-helper.ts`,
+ * which factors one cross-cutting behaviour out of the dialects the same way.
+ *
+ * The one genuinely dialect-specific piece is `random()`: the function used
+ * to produce a random sort key differs per engine, so it is looked up from
+ * `RANDOM_FUNCTIONS` by the dialect's own `name`. Dialects with no known
+ * random-ordering function throw a descriptive error rather than silently
+ * emitting SQL that would not run (or, worse, no `ORDER BY` at all, which is
+ * what `order: random()` used to do everywhere).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.randomOrderFunction = randomOrderFunction;
+exports.renderOrderExpression = renderOrderExpression;
+exports.renderOrderExpressionItem = renderOrderExpressionItem;
+exports.normalizeOrderItems = normalizeOrderItems;
+const operators_1 = require("../operators");
+/**
+ * The expression each dialect uses to produce a per-row random sort key.
+ *
+ * Keyed by `Dialect.name`, so dialects that inherit `buildOrderClause()` from
+ * a parent (TiDB from MySQL, Turso from SQLite, TimescaleDB from Postgres,
+ * ...) still get their own function — the lookup happens at call time against
+ * the concrete instance's `name`.
+ *
+ * Notes on the less obvious entries:
+ * - SQL Server: `RAND()` is evaluated **once per query** in T-SQL, so
+ *   `ORDER BY RAND()` does not shuffle anything. `NEWID()` is the documented
+ *   way to order rows randomly.
+ * - Oracle has no `RANDOM()`/`RAND()`; the built-in package function
+ *   `DBMS_RANDOM.VALUE` is the standard idiom.
+ * - ClickHouse's function is `rand()` (lower case is always accepted).
+ *
+ * Dialects deliberately absent (they throw instead of guessing):
+ * - `questdb`: QuestDB's random generators (`rnd_double()` and friends) are
+ *   row-generator functions, not a general random sort key.
+ */
+const RANDOM_FUNCTIONS = {
+    // RANDOM()
+    sqlite: 'RANDOM()',
+    sqlite3: 'RANDOM()',
+    turso: 'RANDOM()',
+    postgres: 'RANDOM()',
+    postgresql: 'RANDOM()',
+    cockroachdb: 'RANDOM()',
+    cratedb: 'RANDOM()',
+    greenplum: 'RANDOM()',
+    timescaledb: 'RANDOM()',
+    yugabytedb: 'RANDOM()',
+    redshift: 'RANDOM()',
+    vertica: 'RANDOM()',
+    exasol: 'RANDOM()',
+    duckdb: 'RANDOM()',
+    snowflake: 'RANDOM()',
+    trino: 'RANDOM()',
+    // RAND()
+    mysql: 'RAND()',
+    mariadb: 'RAND()',
+    tidb: 'RAND()',
+    singlestore: 'RAND()',
+    databricks: 'RAND()',
+    firebird: 'RAND()',
+    hana: 'RAND()',
+    db2: 'RAND()',
+    spanner: 'RAND()',
+    // Dialect-specific spellings
+    clickhouse: 'rand()',
+    mssql: 'NEWID()',
+    sqlserver: 'NEWID()',
+    oracle: 'DBMS_RANDOM.VALUE',
+    oracledb: 'DBMS_RANDOM.VALUE',
+};
+/**
+ * The SQL expression that orders rows randomly on `dialectName`.
+ *
+ * @throws if the dialect has no known random-ordering function — callers get
+ * an actionable error instead of SQL that silently does the wrong thing.
+ */
+function randomOrderFunction(dialectName) {
+    const key = String(dialectName ?? '').toLowerCase();
+    const fn = RANDOM_FUNCTIONS[key];
+    if (!fn) {
+        throw new Error(`random() ordering is not supported by the '${dialectName ?? 'unknown'}' dialect: ` +
+            `no known random-ordering function. Pass a raw ORDER BY expression instead, ` +
+            `e.g. order: ['<dialect random expression>'].`);
+    }
+    return fn;
+}
+/**
+ * Render one `OrderExpression` as an `ORDER BY` list item (no leading
+ * `ORDER BY`), using the dialect's own identifier quoting.
+ */
+function renderOrderExpression(dialect, expression) {
+    const direction = String(expression.direction ?? '').toUpperCase();
+    if (direction === 'RANDOM') {
+        return randomOrderFunction(dialect.name);
+    }
+    if (direction !== 'ASC' && direction !== 'DESC') {
+        // `direction` is typed as a union, but `order` values routinely arrive
+        // from untyped callers (JS consumers, JSON config). Interpolating an
+        // arbitrary string straight into ORDER BY would be an injection point,
+        // so reject anything that is not a real sort direction.
+        throw new Error(`Invalid order direction '${String(expression.direction)}'. ` +
+            `Expected 'ASC', 'DESC' or 'RANDOM'.`);
+    }
+    return `${dialect.escapeId(expression.field)} ${direction}`;
+}
+/**
+ * Render `item` if — and only if — it is an `OrderExpression`; otherwise
+ * return `null` so the caller falls through to its own handling of the
+ * legacy order shapes.
+ *
+ * Usage inside a dialect's `buildOrderClause()`:
+ *
+ * ```ts
+ * const orderExpr = renderOrderExpressionItem(this, item);
+ * if (orderExpr !== null) {
+ *   orderParts.push(orderExpr);
+ *   continue;
+ * }
+ * ```
+ */
+function renderOrderExpressionItem(dialect, item) {
+    return (0, operators_1.isOrderExpression)(item) ? renderOrderExpression(dialect, item) : null;
+}
+/**
+ * Normalise a `FindOptions.order` value into the list of items a dialect
+ * should iterate over.
+ *
+ * Behaviour is intentionally conservative so no currently-working shape
+ * changes: arrays pass straight through, a **bare** `OrderExpression`
+ * (`order: random()`) is wrapped into a single-item list, and anything else
+ * non-array yields `[]` — exactly what the `!Array.isArray(order)` guard the
+ * dialects used to open with produced.
+ */
+function normalizeOrderItems(order) {
+    if (Array.isArray(order)) {
+        return order;
+    }
+    if ((0, operators_1.isOrderExpression)(order)) {
+        return [order];
+    }
+    return [];
+}

package/dist/dialects/partial-index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Partial-index predicates (`IndexOptions.where`).
+ *
+ * A partial index predicate lives inside DDL, and DDL is executed without a
+ * parameter list. Compiling `where` through the ordinary WHERE builder
+ * therefore produced `CREATE INDEX ... WHERE "status" = ?` with the values
+ * silently dropped on the floor - SQLite rejects that outright ("parameters
+ * prohibited in partial index WHERE clauses") and PostgreSQL fails on the
+ * dangling `$1`. So predicates are compiled here instead, with every value
+ * inlined as a literal through the dialect's own `escape()`.
+ *
+ * That inlining makes `escape()` the security boundary for this path: nothing
+ * in this module hand-rolls quoting, and no user value ever reaches the SQL by
+ * concatenation. `escapeId()` does the same job for column names.
+ *
+ * Only the operator forms that mean something in a predicate are supported.
+ * Anything else throws with a reason rather than emitting SQL the server will
+ * reject - the same convention as {@link UnsupportedSchemaObjectError} in
+ * `src/schema-objects.ts`, which this module reuses for dialects that have no
+ * partial indexes at all.
+ */
+import { UnsupportedSchemaObjectError } from '../schema-objects';
+/**
+ * The escaping surface a predicate needs. Every dialect implements both
+ * (they are abstract on `BaseDialect`), so any dialect can be passed straight in.
+ */
+export interface PartialIndexEscaper {
+    escape(value: any): string;
+    escapeId(identifier: string): string;
+}
+/** Whether `dialect` supports a `WHERE` predicate on `CREATE INDEX`. */
+export declare function supportsPartialIndexes(dialect: string): boolean;
+/**
+ * Raise the standard "this database has no partial indexes" error.
+ *
+ * Exported so a dialect can fail the same way from its own `createPartialIndex`.
+ */
+export declare function unsupportedPartialIndex(dialect: string): UnsupportedSchemaObjectError;
+/**
+ * Compile one `IndexOptions.where` into a self-contained SQL predicate with all
+ * values inlined as escaped literals.
+ *
+ * A string `where` is a predicate the caller already wrote by hand and is
+ * returned unchanged, which is also what `createPartialIndex()` takes.
+ *
+ * @param where - Predicate object, or raw SQL predicate string
+ * @param dialect - Dialect name, used for the unsupported-database error
+ * @param escaper - The dialect itself; supplies `escape` / `escapeId`
+ * @returns The predicate SQL, or `''` when `where` is empty (emit no WHERE)
+ * @throws {UnsupportedSchemaObjectError} when the dialect has no partial indexes
+ */
+export declare function buildPartialIndexPredicate(where: unknown, dialect: string, escaper: PartialIndexEscaper): string;