ts-prorm-orm 1.2.3 → 2.1.0

package/dist/dialects/mariadb/index.js

@@ -15,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MariaDBRowFormats = exports.MariaDBConnectTypes = exports.MariaDBStorageEngines = exports.MariaDBTransaction = exports.MariaDBDialect = void 0;
 exports.createMariaDBDialect = createMariaDBDialect;
 const operators_1 = require("../../operators");
+const partial_index_1 = require("../partial-index");
 // Lazily-loaded `mariadb` driver. Required only when a connection is opened,
 // so importing this ORM never loads the mariadb driver.
 let mariadbModule = null;
@@ -32,8 +33,10 @@ function loadMariaDb() {
     return mariadbModule;
 }
 const query_stream_helper_1 = require("../query-stream-helper");
+const lock_clause_helper_1 = require("../lock-clause-helper");
 const prorm_1 = require("../../prorm");
 const operators_2 = require("../../operators");
+const order_expression_helper_1 = require("../order-expression-helper");
 /**
  * MariaDB dialect class that implements the Dialect interface
  * Extends MySQL compatibility with MariaDB-specific features
@@ -1835,10 +1838,12 @@ class MariaDBDialect {
         if (options?.include && options.include.length > 0) {
             sql += ` INCLUDE (${options.include.map((f) => this.escapeId(f)).join(', ')})`;
         }
-        // Add WHERE clause for partial index (MariaDB 10.0.3+)
-        if (options?.where && Object.keys(options.where).length > 0) {
-            const whereClause = this.buildWhereClause(options.where);
-            sql += ` WHERE ${whereClause.sql}`;
+        // MariaDB has no partial/filtered indexes at any version - `CREATE INDEX`
+        // takes no WHERE clause. This used to compile the predicate through the
+        // ordinary WHERE builder and append it, producing SQL the server rejects
+        // (with unbound `?` placeholders in it, no less), so fail with a reason.
+        if (options?.where) {
+            throw (0, partial_index_1.unsupportedPartialIndex)(this.name);
         }
         // Index visibility (MariaDB 10.6+). Unlike MySQL, MariaDB uses the
         // `IGNORED` keyword for indexes (not `INVISIBLE` — that keyword is
@@ -1858,15 +1863,16 @@ class MariaDBDialect {
         await this.query(sql);
     }
     /**
-     * Create a partial index (index with WHERE clause)
-     * MariaDB supports partial indexes since version 10.0.3
+     * Partial (filtered) indexes - not available on MariaDB.
+     *
+     * The claim that MariaDB 10.0.3 added them is wrong: `CREATE INDEX` has never
+     * taken a `WHERE` clause on MariaDB (a live mariadb:11 server answers
+     * ER_PARSE_ERROR), so this throws rather than build that statement.
      */
-    async createPartialIndex(tableName, indexName, fields, where, options) {
-        const fieldsSql = fields.map((f) => this.escapeId(f)).join(', ');
-        let sql = `CREATE INDEX ${this.escapeId(indexName)} ON ${this.quoteTable(tableName)} (${fieldsSql}) WHERE ${where}`;
-        if (options?.unique)
-            sql = sql.replace('CREATE INDEX', 'CREATE UNIQUE INDEX');
-        await this.query(sql);
+    async createPartialIndex(_tableName, _indexName, _fields, _where, _options) {
+        // This used to emit `CREATE INDEX ... WHERE ...`, which MariaDB has never
+        // accepted; the statement failed at the server with a syntax error.
+        throw (0, partial_index_1.unsupportedPartialIndex)(this.name);
     }
     /**
      * Create an index on a table with full options support
@@ -1891,10 +1897,9 @@ class MariaDBDialect {
         if (indexDef.using) {
             sql += ` USING ${indexDef.using}`;
         }
-        // Add WHERE clause for partial index (MariaDB 10.0.3+)
-        if (indexDef.where && Object.keys(indexDef.where).length > 0) {
-            const whereClause = this.buildWhereClause(indexDef.where);
-            sql += ` WHERE ${whereClause.sql}`;
+        // No partial/filtered indexes on MariaDB - see addIndex.
+        if (indexDef.where) {
+            throw (0, partial_index_1.unsupportedPartialIndex)(this.name);
         }
         // Index visibility (MariaDB 10.6+). Unlike MySQL, MariaDB uses
         // `IGNORED` (not `INVISIBLE`) for indexes. Not ignored by default.
@@ -2368,12 +2373,18 @@ class MariaDBDialect {
      * Build an ORDER BY clause
      */
     buildOrderClause(order, options) {
-        const orderArray = order;
-        if (!orderArray || !Array.isArray(orderArray) || orderArray.length === 0) {
+        const orderArray = (0, order_expression_helper_1.normalizeOrderItems)(order);
+        if (orderArray.length === 0) {
             return '';
         }
         const orderParts = [];
         for (const item of orderArray) {
+            // Order helpers: asc('name') / desc('name') / random()
+            const orderExpr = (0, order_expression_helper_1.renderOrderExpressionItem)(this, item);
+            if (orderExpr !== null) {
+                orderParts.push(orderExpr);
+                continue;
+            }
             if (Array.isArray(item)) {
                 const field = typeof item[0] === 'string' ? this.escapeId(item[0]) : item[0];
                 const direction = item[1] ? ` ${item[1]}` : '';
@@ -3025,48 +3036,13 @@ class MariaDBDialect {
         }
         // Build LIMIT/OFFSET clause
         sql += this.buildLimitOffset(options.limit, options.offset);
-        // Handle row-level locking
-        if (options.lock) {
-            // lock: true is equivalent to 'UPDATE'
-            let lockType;
-            let skipLocked = false;
-            let noWait = false;
-            if (options.lock === true) {
-                lockType = 'UPDATE';
-            }
-            else if (typeof options.lock === 'string') {
-                lockType = options.lock;
-            }
-            else if (typeof options.lock === 'object' && options.lock !== null) {
-                // lock: { of: Model, mode: 'UPDATE' | 'SHARE', skipLocked?, noWait? }
-                lockType = options.lock.mode || (options.lock.of ? 'UPDATE' : undefined);
-                skipLocked = !!options.lock.skipLocked;
-                noWait = !!options.lock.noWait;
-            }
-            if (lockType === 'UPDATE') {
-                sql += ' FOR UPDATE';
-            }
-            else if (lockType === 'SHARE') {
-                // MariaDB 10.6+ prefers `FOR SHARE` over the legacy `LOCK IN SHARE MODE`
-                // syntax, but only `LOCK IN SHARE MODE` supports no modifiers, so use
-                // `FOR SHARE` whenever a SKIP LOCKED/NOWAIT modifier is requested.
-                if (skipLocked || noWait) {
-                    sql += ' FOR SHARE';
-                }
-                else {
-                    sql += ' LOCK IN SHARE MODE';
-                }
-            }
-            // MariaDB 10.6+ locking modifiers
-            if (lockType === 'UPDATE' || lockType === 'SHARE') {
-                if (skipLocked) {
-                    sql += ' SKIP LOCKED';
-                }
-                else if (noWait) {
-                    sql += ' NOWAIT';
-                }
-            }
-        }
+        // Handle row-level locking (MariaDB 10.6+). The shared helper parses
+        // every documented `lock` shape - including `{ level, nowait }`, which this dialect only understood
+        // under its own `{ mode, noWait }` spelling and otherwise compiled to no
+        // lock at all. Both spellings are still accepted. A shared lock uses the
+        // legacy `LOCK IN SHARE MODE` unless a modifier is requested, since only
+        // `FOR SHARE` accepts SKIP LOCKED / NOWAIT.
+        sql += (0, lock_clause_helper_1.appendLockClause)(options.lock, lock_clause_helper_1.MARIADB_LOCK_SPEC);
         // Build UNION/EXCEPT/INTERSECT clause if provided
         // MariaDB 10.3+ supports EXCEPT/EXCEPT ALL/INTERSECT/INTERSECT ALL in
         // addition to UNION/UNION ALL.

package/dist/dialects/mssql/index.js

@@ -8,9 +8,12 @@ exports.MSSQLDialect = void 0;
 exports.createMSSQLDialect = createMSSQLDialect;
 const mssql_1 = require("mssql");
 const operators_1 = require("../../operators");
+const partial_index_1 = require("../partial-index");
 const types_1 = require("../../types");
 const query_stream_helper_1 = require("../query-stream-helper");
+const lock_clause_helper_1 = require("../lock-clause-helper");
 const prorm_1 = require("../../prorm");
+const order_expression_helper_1 = require("../order-expression-helper");
 /**
  * Default retry options for connection
  */
@@ -975,10 +978,15 @@ class MSSQLDialect {
         if (options?.using)
             sql += ` USING ${options.using}`;
         // Filtered index predicate (a real, commonly-used MSSQL feature) - was
-        // previously accepted by createIndex() but silently dropped here.
+        // previously accepted by createIndex() but silently dropped here. The
+        // ordinary WHERE builder emits `@p1`-style placeholders and this DDL is
+        // executed without a parameter list, so the predicate is compiled with its
+        // values inlined as escaped literals.
         if (options?.where) {
-            const whereClause = this.buildWhereClause(options.where);
-            sql += ` WHERE ${whereClause.sql}`;
+            const predicate = (0, partial_index_1.buildPartialIndexPredicate)(options.where, this.name, this);
+            if (predicate) {
+                sql += ` WHERE ${predicate}`;
+            }
         }
         await this.query(sql);
     }
@@ -1333,6 +1341,12 @@ class MSSQLDialect {
             return '';
         const orderParts = [];
         const processOrder = (orderItem) => {
+            // Order helpers: asc('name') / desc('name') / random()
+            const orderExpr = (0, order_expression_helper_1.renderOrderExpressionItem)(this, orderItem);
+            if (orderExpr !== null) {
+                orderParts.push(orderExpr);
+                return;
+            }
             if (typeof orderItem === 'string') {
                 const parts = orderItem.split(' ');
                 if (parts.length === 1) {
@@ -1342,6 +1356,16 @@ class MSSQLDialect {
                     orderParts.push(`${this.escapeId(parts[0])} ${parts[1].toUpperCase()}`);
                 }
             }
+            else if (Array.isArray(orderItem)) {
+                // Tuple form — `['name', 'DESC']` / `['name']`, the elements of the
+                // primary documented `[['name', 'DESC'], ['id', 'ASC']]` shape. An
+                // array is also an object, so without this branch each tuple fell
+                // through to the map branch below and its *indices* were emitted as
+                // column names (`ORDER BY [0] NAME, [1] DESC`).
+                const [field, direction] = orderItem;
+                const column = typeof field === 'string' ? this.escapeId(field) : String(field);
+                orderParts.push(direction ? `${column} ${String(direction).toUpperCase()}` : column);
+            }
             else if (typeof orderItem === 'object' && orderItem !== null) {
                 for (const [key, value] of Object.entries(orderItem)) {
                     if (key === '$raw') {
@@ -1569,6 +1593,13 @@ class MSSQLDialect {
         else if (options.temporalAll) {
             sql += ' FOR SYSTEM_TIME ALL';
         }
+        // Row-level locking. T-SQL has no `FOR UPDATE`; a lock is requested with a
+        // table hint on the table reference, which has to sit immediately after it
+        // (and after any FOR SYSTEM_TIME clause). See lock-clause-helper.ts.
+        const lockHint = (0, lock_clause_helper_1.buildSqlServerLockHint)(options.lock, options.tableName);
+        if (lockHint) {
+            sql += ` ${lockHint}`;
+        }
         if (options.include && options.include.length > 0) {
             for (const include of options.include) {
                 // CROSS APPLY / OUTER APPLY — a lateral join, needed for anything an

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

@@ -711,7 +711,7 @@ export declare class MySQLDialect implements Dialect {
         type?: string;
         using?: string;
         fields: string[];
-        where?: WhereOptions;
+        where?: WhereOptions | string;
         expression?: string;
         include?: string[];
         invisible?: boolean;

package/dist/dialects/mysql/index.js

@@ -12,6 +12,8 @@ const promise_1 = __importDefault(require("mysql2/promise"));
 const prorm_1 = require("../../prorm");
 const operators_1 = require("../../operators");
 const operators_2 = require("../../operators");
+const lock_clause_helper_1 = require("../lock-clause-helper");
+const order_expression_helper_1 = require("../order-expression-helper");
 /**
  * Default retry options for connection
  */
@@ -2881,12 +2883,18 @@ class MySQLDialect {
      * Build an ORDER BY clause
      */
     buildOrderClause(order, options) {
-        const orderArray = order;
-        if (!orderArray || !Array.isArray(orderArray) || orderArray.length === 0) {
+        const orderArray = (0, order_expression_helper_1.normalizeOrderItems)(order);
+        if (orderArray.length === 0) {
             return '';
         }
         const orderParts = [];
         for (const item of orderArray) {
+            // Order helpers: asc('name') / desc('name') / random()
+            const orderExpr = (0, order_expression_helper_1.renderOrderExpressionItem)(this, item);
+            if (orderExpr !== null) {
+                orderParts.push(orderExpr);
+                continue;
+            }
             if (Array.isArray(item)) {
                 const field = typeof item[0] === 'string' ? this.escapeId(item[0]) : item[0];
                 const direction = item[1] ? ` ${item[1]}` : '';
@@ -3483,49 +3491,13 @@ class MySQLDialect {
         // Build LIMIT/OFFSET clause
         sql += this.buildLimitOffset(options.limit, options.offset);
         // Handle row-level locking
-        if (options.lock) {
-            // lock: true is equivalent to 'UPDATE'
-            let lockType;
-            let nowait = false;
-            let skipLocked = false;
-            if (options.lock === true) {
-                lockType = 'UPDATE';
-            }
-            else if (typeof options.lock === 'string') {
-                lockType = options.lock;
-            }
-            else if (typeof options.lock === 'object') {
-                // Handle { level: 'UPDATE', nowait: true } or { level: 'UPDATE', skipLocked: true }
-                lockType = options.lock.level || (options.lock.of ? 'UPDATE' : undefined);
-                nowait = options.lock.nowait === true;
-                skipLocked = options.lock.skipLocked === true;
-            }
-            if (lockType === 'UPDATE') {
-                sql += ' FOR UPDATE';
-                // MySQL 8.0+ supports table-scoped locking via `FOR UPDATE OF <table>`
-                if (typeof options.lock === 'object' && options.lock.of) {
-                    const model = options.lock.of;
-                    if (model.tableName) {
-                        sql += ` OF ${this.escapeId(model.tableName)}`;
-                    }
-                }
-                // MySQL 8.0+ supports NOWAIT and SKIP LOCKED
-                if (nowait) {
-                    sql += ' NOWAIT';
-                }
-                else if (skipLocked) {
-                    sql += ' SKIP LOCKED';
-                }
-            }
-            else if (lockType === 'SHARE') {
-                sql += ' LOCK IN SHARE MODE';
-                // MySQL 8.0+ supports NOWAIT for SHARE mode
-                if (nowait) {
-                    sql += ' NOWAIT';
-                }
-                // MySQL doesn't support SKIP LOCKED for LOCK IN SHARE MODE
-            }
-        }
+        // `FOR UPDATE [OF tbl] [NOWAIT | SKIP LOCKED]` / `LOCK IN SHARE MODE`, with
+        // every documented `lock` shape parsed by the shared helper. A shared lock
+        // switches to the MySQL 8.0 `FOR SHARE` spelling when a NOWAIT/SKIP LOCKED
+        // modifier is requested, since `LOCK IN SHARE MODE` accepts neither (it
+        // used to emit an invalid `LOCK IN SHARE MODE NOWAIT`, and drop SKIP LOCKED
+        // on the floor). See src/dialects/lock-clause-helper.ts.
+        sql += (0, lock_clause_helper_1.appendLockClause)(options.lock, lock_clause_helper_1.MYSQL_LOCK_SPEC, (id) => this.escapeId(id));
         // Build UNION clause if provided
         if (options.union && options.union.length > 0) {
             const unionType = options.unionType || 'UNION';

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[];