ts-prorm-orm 1.2.3 → 2.1.0

package/dist/dialects/redshift/index.js

@@ -74,6 +74,7 @@ const prorm_1 = require("../../prorm");
 const index_1 = require("../../errors/index");
 const index_2 = require("../../utils/index");
 const operators_1 = require("../../operators");
+const order_expression_helper_1 = require("../order-expression-helper");
 const DEFAULT_RETRY_OPTIONS = {
     max: 3,
     timeout: 1000,
@@ -1564,11 +1565,17 @@ class RedshiftDialect {
         return { sql: buildCondition(where), values };
     }
     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]}` : '';

package/dist/dialects/snowflake/index.js

@@ -46,6 +46,7 @@ function loadSnowflake() {
 const types_1 = require("../../types");
 const query_stream_helper_1 = require("../query-stream-helper");
 const prorm_1 = require("../../prorm");
+const order_expression_helper_1 = require("../order-expression-helper");
 /**
  * Default retry options for connection/query errors
  */
@@ -1090,6 +1091,12 @@ class SnowflakeDialect {
             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) {
@@ -1099,6 +1106,16 @@ class SnowflakeDialect {
                     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') {

package/dist/dialects/spanner/index.js

@@ -106,6 +106,7 @@ const { Spanner } = require('@google-cloud/spanner');
 const types_1 = require("../../types");
 const query_stream_helper_1 = require("../query-stream-helper");
 const prorm_1 = require("../../prorm");
+const order_expression_helper_1 = require("../order-expression-helper");
 /**
  * A Spanner read-write transaction, bridging the driver's callback-based
  * `database.runTransaction()` API to the imperative
@@ -1490,10 +1491,14 @@ class SpannerDialect {
         return { sql, values };
     }
     buildOrderClause(order) {
-        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 parts = orderArray.map((item) => {
+            // Order helpers: asc('name') / desc('name') / random()
+            const orderExpr = (0, order_expression_helper_1.renderOrderExpressionItem)(this, item);
+            if (orderExpr !== null)
+                return orderExpr;
             if (Array.isArray(item)) {
                 const field = typeof item[0] === 'string' ? this.escapeId(item[0]) : item[0];
                 const direction = item[1] ? ` ${item[1]}` : '';

package/dist/dialects/sqlite/driver.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Runtime-appropriate SQLite driver.
+ *
+ * Node uses `better-sqlite3`, a native addon. Bun ships its own SQLite as the
+ * built-in `bun:sqlite`, which is faster there and needs no native build step —
+ * and under Bun the `better-sqlite3` addon may not be installable at all.
+ *
+ * The two APIs were designed to look alike, so the dialect can talk to either
+ * one unchanged. They differ in exactly one place: better-sqlite3 has
+ * `db.pragma()`, and bun:sqlite does not. This module adds it, so the dialect
+ * has a single shape to code against and no `if (isBun)` branches leak into the
+ * SQL layer.
+ *
+ * The driver is loaded lazily on first connect, so importing the ORM never
+ * dlopens a native binding or touches a `bun:` module on Node.
+ */
+/** The slice of better-sqlite3's Statement the dialect relies on. */
+export interface SqliteStatement {
+    all(...params: unknown[]): unknown[];
+    get(...params: unknown[]): unknown;
+    run(...params: unknown[]): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+    iterate(...params: unknown[]): IterableIterator<unknown>;
+}
+/** The slice of better-sqlite3's Database the dialect relies on. */
+export interface SqliteDatabase {
+    prepare(sql: string): SqliteStatement;
+    exec(sql: string): unknown;
+    pragma(source: string, options?: {
+        simple?: boolean;
+    }): unknown;
+    close(): void;
+}
+export interface SqliteDriverOptions {
+    readonly?: boolean;
+    fileMustExist?: boolean;
+    timeout?: number;
+    verbose?: ((message?: unknown, ...args: unknown[]) => void) | undefined;
+}
+/** True when running under Bun. */
+export declare function isBun(): boolean;
+type DatabaseCtor = new (filename: string, options?: SqliteDriverOptions) => SqliteDatabase;
+/**
+ * Resolve the SQLite driver for the current runtime.
+ *
+ * Under Bun this prefers `bun:sqlite` but falls back to `better-sqlite3` if it
+ * is installed and the built-in cannot be loaded, so an existing Bun project
+ * that already depends on better-sqlite3 keeps working.
+ */
+export declare function loadSqliteDriver(): DatabaseCtor;
+/** Test seam: forget the resolved driver. */
+export declare function resetSqliteDriver(): void;
+export {};

package/dist/dialects/sqlite/driver.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Runtime-appropriate SQLite driver.
+ *
+ * Node uses `better-sqlite3`, a native addon. Bun ships its own SQLite as the
+ * built-in `bun:sqlite`, which is faster there and needs no native build step —
+ * and under Bun the `better-sqlite3` addon may not be installable at all.
+ *
+ * The two APIs were designed to look alike, so the dialect can talk to either
+ * one unchanged. They differ in exactly one place: better-sqlite3 has
+ * `db.pragma()`, and bun:sqlite does not. This module adds it, so the dialect
+ * has a single shape to code against and no `if (isBun)` branches leak into the
+ * SQL layer.
+ *
+ * The driver is loaded lazily on first connect, so importing the ORM never
+ * dlopens a native binding or touches a `bun:` module on Node.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBun = isBun;
+exports.loadSqliteDriver = loadSqliteDriver;
+exports.resetSqliteDriver = resetSqliteDriver;
+/** True when running under Bun. */
+function isBun() {
+    return typeof process !== 'undefined' && typeof process.versions?.bun === 'string';
+}
+/**
+ * Give a bun:sqlite Database the `pragma()` method better-sqlite3 has.
+ *
+ * better-sqlite3's contract: `pragma('foreign_keys = ON')` sets and returns the
+ * resulting rows; `pragma('user_version', { simple: true })` returns the first
+ * column of the first row. `PRAGMA name = value` returns no rows, so a `simple`
+ * read of an assignment yields undefined in both drivers.
+ */
+function withPragma(db) {
+    const wrapped = db;
+    if (typeof db.pragma === 'function')
+        return wrapped;
+    wrapped.pragma = (source, options) => {
+        const rows = db.prepare(`PRAGMA ${source}`).all();
+        if (!options?.simple)
+            return rows;
+        const first = rows[0];
+        return first ? Object.values(first)[0] : undefined;
+    };
+    return wrapped;
+}
+let cached = null;
+/**
+ * Resolve the SQLite driver for the current runtime.
+ *
+ * Under Bun this prefers `bun:sqlite` but falls back to `better-sqlite3` if it
+ * is installed and the built-in cannot be loaded, so an existing Bun project
+ * that already depends on better-sqlite3 keeps working.
+ */
+function loadSqliteDriver() {
+    if (cached)
+        return cached;
+    const attempts = [];
+    if (isBun()) {
+        attempts.push({
+            name: 'bun:sqlite',
+            load: () => {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { Database } = require('bun:sqlite');
+                // bun:sqlite ignores better-sqlite3's `verbose`/`timeout`; pass through
+                // only what it understands so an unknown option can't throw.
+                return class BunDatabase {
+                    constructor(filename, options) {
+                        return withPragma(new Database(filename, {
+                            readonly: options?.readonly ?? false,
+                            create: !(options?.fileMustExist ?? false),
+                        }));
+                    }
+                };
+            },
+        });
+    }
+    attempts.push({
+        name: 'better-sqlite3',
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        load: () => require('better-sqlite3'),
+    });
+    const failures = [];
+    for (const attempt of attempts) {
+        try {
+            cached = attempt.load();
+            return cached;
+        }
+        catch (err) {
+            failures.push(`${attempt.name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    throw new Error('No SQLite driver could be loaded for the SQLite dialect. Tried ' +
+        attempts.map((a) => a.name).join(', ') +
+        '. On Node install better-sqlite3 (`npm install better-sqlite3`); on Bun the built-in ' +
+        '`bun:sqlite` is used and needs no install. Underlying errors — ' +
+        failures.join(' | '));
+}
+/** Test seam: forget the resolved driver. */
+function resetSqliteDriver() {
+    cached = null;
+}

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

@@ -768,7 +768,7 @@ export declare class SQLiteDialect implements Dialect {
         type?: string;
         using?: string;
         fields: string[];
-        where?: WhereOptions;
+        where?: WhereOptions | string;
         expression?: string;
     }): Promise<void>;
     /**

package/dist/dialects/sqlite/index.js

@@ -6,27 +6,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SQLiteTransaction = exports.SQLiteDialect = void 0;
 exports.createSQLiteDialect = createSQLiteDialect;
 const operators_1 = require("../../operators");
-// Lazily-loaded `better-sqlite3` driver. This native addon is only loaded the
-// first time a connection is opened, so importing this ORM never dlopens the
-// better-sqlite3 native binding.
-let betterSqlite3Ctor = null;
-function loadBetterSqlite3() {
-    if (!betterSqlite3Ctor) {
-        try {
-            betterSqlite3Ctor = require('better-sqlite3');
-        }
-        catch (err) {
-            throw new Error("The 'better-sqlite3' package is required to use the SQLite dialect but could not be loaded. " +
-                'Install it with `npm install better-sqlite3`. Original error: ' +
-                (err instanceof Error ? err.message : String(err)));
-        }
-    }
-    return betterSqlite3Ctor;
-}
+const partial_index_1 = require("../partial-index");
+// The SQLite driver is resolved per runtime and loaded lazily on first connect:
+// `better-sqlite3` on Node, the built-in `bun:sqlite` on Bun. See
+// ./driver.ts — importing this ORM never dlopens a native binding, and no
+// runtime branch leaks past that module.
+const driver_1 = require("./driver");
 const stream_1 = require("stream");
 const prorm_1 = require("../../prorm");
 const operators_2 = require("../../operators");
 const sqlite_advanced_1 = require("../../sqlite-advanced");
+const order_expression_helper_1 = require("../order-expression-helper");
 /**
  * SQLite dialect class that implements the Dialect interface
  */
@@ -54,7 +44,7 @@ class SQLiteDialect {
                 timeout: this.config.timeout || 5000,
                 verbose: this.config.verbose || undefined,
             };
-            this.connection = new (loadBetterSqlite3())(this.config.storage, options);
+            this.connection = new ((0, driver_1.loadSqliteDriver)())(this.config.storage, options);
             this._isConnected = true;
             // Enable foreign keys by default
             this.connection.pragma('foreign_keys = ON');
@@ -160,8 +150,15 @@ class SQLiteDialect {
             }
             const sqlUpper = sql.trim().toUpperCase();
             // EXPLAIN / EXPLAIN QUERY PLAN and WITH (CTE) statements also return rows.
+            //
+            // `PRAGMA name` is a query and returns a row; `PRAGMA name = value` is an
+            // assignment and returns nothing, and better-sqlite3 throws "This
+            // statement does not return data. Use run() instead" if you call .all()
+            // on it. Every PRAGMA was treated as a reader, so the assignment form -
+            // which is how disableForeignKeyChecks(), enableForeignKeyChecks() and
+            // setIsolationLevel() are implemented on SQLite - failed on every call.
             const isSelect = sqlUpper.startsWith('SELECT') ||
-                sqlUpper.startsWith('PRAGMA') ||
+                (sqlUpper.startsWith('PRAGMA') && !sqlUpper.includes('=')) ||
                 sqlUpper.startsWith('EXPLAIN') ||
                 sqlUpper.startsWith('WITH');
             const stmt = this.connection.prepare(sql);
@@ -706,6 +703,16 @@ class SQLiteDialect {
         if (options?.initialAutoIncrement) {
             console.warn(`SQLite: initialAutoIncrement option is not supported in CREATE TABLE`);
         }
+        // Create the unique keys collected above.
+        //
+        // SQLite has no `ALTER TABLE ... ADD CONSTRAINT`, so a unique key that is
+        // not part of the CREATE TABLE text has to become a `CREATE UNIQUE INDEX`
+        // instead - which enforces exactly the same rule. This list was built and
+        // then never used, so `createTable(..., { uniqueKeys })` produced no SQL at
+        // all and the constraint the caller declared was never enforced.
+        for (const uk of uniqueKeysToCreate) {
+            await this.addIndex(tableName, uk.name, uk.fields, { unique: true });
+        }
         // Create indexes after table creation
         if (options?.indexes) {
             for (const index of options.indexes) {
@@ -1849,10 +1856,16 @@ class SQLiteDialect {
         else {
             sql += ` (${fields.map((f) => this.escapeId(f)).join(', ')})`;
         }
-        // Add partial index WHERE clause (SQLite 3.8.0+)
+        // Add partial index WHERE clause (SQLite 3.8.0+). The ordinary WHERE
+        // builder is deliberately not used here: it emits bound placeholders, and
+        // this DDL is executed without a value list, so SQLite rejected it with
+        // "parameters prohibited in partial index WHERE clauses". The predicate is
+        // compiled with its values inlined as escaped literals instead.
         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);
     }
@@ -1892,9 +1905,12 @@ class SQLiteDialect {
         if (indexDef.using) {
             sql += ` USING ${indexDef.using}`;
         }
-        if (indexDef.where && Object.keys(indexDef.where).length > 0) {
-            const whereClause = this.buildWhereClause(indexDef.where);
-            sql += ` WHERE ${whereClause.sql}`;
+        // Partial index predicate - inlined literals, not placeholders. See addIndex.
+        if (indexDef.where) {
+            const predicate = (0, partial_index_1.buildPartialIndexPredicate)(indexDef.where, this.name, this);
+            if (predicate) {
+                sql += ` WHERE ${predicate}`;
+            }
         }
         await this.query(sql);
     }
@@ -2352,12 +2368,18 @@ class SQLiteDialect {
      * 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]}` : '';

package/dist/external-fields/decorator.d.ts

@@ -9,6 +9,7 @@
  *
  *   prorm.registerStore('assets', s3Store, { defaultBucket: 'avatars' });
  *
+ * ```ts
  *   @Table()
  *   class User extends Model {
  *     @Column(DataTypes.STRING) declare name: string;
@@ -21,6 +22,7 @@
  *   await user.loadAvatar();        // GET, populates user.avatar
  *   user.avatar = newBytes;
  *   await user.save();              // PUT, then persists the key column
+ * ```
  *
  * The key column (`avatarKey` by default) is registered automatically, so it
  * does not need its own `@Column`.

package/dist/external-fields/decorator.js

@@ -10,6 +10,7 @@
  *
  *   prorm.registerStore('assets', s3Store, { defaultBucket: 'avatars' });
  *
+ * ```ts
  *   @Table()
  *   class User extends Model {
  *     @Column(DataTypes.STRING) declare name: string;
@@ -22,6 +23,7 @@
  *   await user.loadAvatar();        // GET, populates user.avatar
  *   user.avatar = newBytes;
  *   await user.save();              // PUT, then persists the key column
+ * ```
  *
  * The key column (`avatarKey` by default) is registered automatically, so it
  * does not need its own `@Column`.

package/dist/graph/base-graph-dialect.d.ts

@@ -25,7 +25,7 @@
 import { Readable } from 'stream';
 import { BaseDialect, type ColumnDefinition, type ConstraintDefinition, type DropConstraintOptions, type DropIndexOptions, type DropSchemaOptions, type DropTableOptions, type DropViewOptions, type IndexDefinition, type IndexOptions, type InsertOptions, type TableDescription, type TableOptions, type UpdateOptions, type DeleteOptions, type SelectOptions, type UpsertQueryOptions, type ViewOptions, type BuildOptions } from '../dialects/dialect';
 import type { DataType, Order, QueryOptions, QueryResult, StreamOptions, Transaction, TransactionOptions, WhereOptions, MaterializedViewOptions, RefreshOptions, DropMaterializedViewOptions, StoredProcedureOptions, DropStoredProcedureOptions, ExecuteStoredProcedureOptions, TriggerOptions, DropTriggerOptions, SequenceOptions, DropSequenceOptions, PolicyOptions, DropPolicyOptions, CreatePartitionOptions, AttachPartitionOptions, DetachPartitionOptions } from '../types';
-import { ParamBag, type GraphConnectionOptions, type GraphPredicate, type GraphStatement, type GraphTraversalSpec, type GraphTraversalStep, type NodeMatchSpec, type NodeModelDefinition, type EdgeModelDefinition } from './types';
+import { ParamBag, type GraphConnectionOptions, type GraphPredicate, type GraphStatement, type GraphTraversalSpec, type GraphTraversalStep, type GraphOrderTerm, type NodeMatchSpec, type NodeModelDefinition, type EdgeModelDefinition } from './types';
 /** Context passed to {@link BaseGraphDialect.renderPredicate}. */
 export interface WhereRenderContext {
     /** Variable the predicate's properties are addressed through (e.g. `n`). */
@@ -110,8 +110,29 @@ export declare abstract class BaseGraphDialect extends BaseDialect {
     protected run(stmt: GraphStatement, options?: QueryOptions): Promise<QueryResult>;
     /** Positional param array for the SQL-shaped `{ sql, values }` contract. */
     protected paramValues(stmt: GraphStatement): unknown[];
-    /** Tolerant `Order` -> `[field, dir][]` normalizer. */
-    protected normalizeOrder(order?: Order): Array<[string, 'ASC' | 'DESC']>;
+    /**
+     * The engine-native term that shuffles results, or `null` when this graph
+     * engine has no random ordering at all.
+     *
+     * Cypher has `rand()` and Gremlin has `order().by(shuffle)`; Dgraph DQL's
+     * `orderasc`/`orderdesc` only take a predicate, so it keeps the `null`
+     * default and {@link requireRandomOrderTerm} raises the typed capability
+     * error instead of emitting something that would silently not shuffle.
+     */
+    protected randomOrderTerm(): string | null;
+    /** {@link randomOrderTerm}, raising `GraphCapabilityError` when unsupported. */
+    protected requireRandomOrderTerm(): string;
+    /**
+     * Tolerant `Order` -> `[field, dir][]` normalizer.
+     *
+     * Also understands the `asc()` / `desc()` / `random()` order helpers from
+     * `src/operators.ts`. They arrive as plain `OrderExpression` objects, so
+     * without an explicit branch they fell through the `$col`/`column` check
+     * below and were dropped silently — the helpers simply did nothing on
+     * every graph dialect. `random()` becomes a `'RANDOM'` term with no field,
+     * which each `compile*` translates (or refuses) in its own language.
+     */
+    protected normalizeOrder(order?: Order): GraphOrderTerm[];
     /** Map ORM `include` entries into graph traversal steps. */
     protected mapIncludes(include?: any[]): GraphTraversalStep[];
     buildWhereClause(where: WhereOptions, _options?: BuildOptions): {

package/dist/graph/base-graph-dialect.js

@@ -28,6 +28,7 @@ exports.BaseGraphDialect = void 0;
 const stream_1 = require("stream");
 const dialect_1 = require("../dialects/dialect");
 const types_1 = require("./types");
+const operators_1 = require("../operators");
 class BaseGraphDialect extends dialect_1.BaseDialect {
     constructor(options = {}) {
         super();
@@ -101,7 +102,36 @@ class BaseGraphDialect extends dialect_1.BaseDialect {
     paramValues(stmt) {
         return Object.values(stmt.params);
     }
-    /** Tolerant `Order` -> `[field, dir][]` normalizer. */
+    /**
+     * The engine-native term that shuffles results, or `null` when this graph
+     * engine has no random ordering at all.
+     *
+     * Cypher has `rand()` and Gremlin has `order().by(shuffle)`; Dgraph DQL's
+     * `orderasc`/`orderdesc` only take a predicate, so it keeps the `null`
+     * default and {@link requireRandomOrderTerm} raises the typed capability
+     * error instead of emitting something that would silently not shuffle.
+     */
+    randomOrderTerm() {
+        return null;
+    }
+    /** {@link randomOrderTerm}, raising `GraphCapabilityError` when unsupported. */
+    requireRandomOrderTerm() {
+        const term = this.randomOrderTerm();
+        if (term === null) {
+            throw new types_1.GraphCapabilityError('random ordering', this.name);
+        }
+        return term;
+    }
+    /**
+     * Tolerant `Order` -> `[field, dir][]` normalizer.
+     *
+     * Also understands the `asc()` / `desc()` / `random()` order helpers from
+     * `src/operators.ts`. They arrive as plain `OrderExpression` objects, so
+     * without an explicit branch they fell through the `$col`/`column` check
+     * below and were dropped silently — the helpers simply did nothing on
+     * every graph dialect. `random()` becomes a `'RANDOM'` term with no field,
+     * which each `compile*` translates (or refuses) in its own language.
+     */
     normalizeOrder(order) {
         if (!order)
             return [];
@@ -111,6 +141,15 @@ class BaseGraphDialect extends dialect_1.BaseDialect {
             if (typeof item === 'string') {
                 out.push([item, 'ASC']);
             }
+            else if ((0, operators_1.isOrderExpression)(item)) {
+                const dir = String(item.direction || 'ASC').toUpperCase();
+                if (dir === 'RANDOM') {
+                    out.push(['', 'RANDOM']);
+                }
+                else {
+                    out.push([item.field, dir === 'DESC' ? 'DESC' : 'ASC']);
+                }
+            }
             else if (Array.isArray(item)) {
                 const rawField = item[0];
                 const field = String(rawField && rawField.$col ? rawField.$col : rawField);
@@ -159,7 +198,9 @@ class BaseGraphDialect extends dialect_1.BaseDialect {
     }
     buildOrderClause(order, _options) {
         return this.normalizeOrder(order)
-            .map(([field, dir]) => `${this.defaultNodeVar}.${(0, types_1.safeIdent)(field)} ${dir}`)
+            .map(([field, dir]) => dir === 'RANDOM'
+            ? this.requireRandomOrderTerm()
+            : `${this.defaultNodeVar}.${(0, types_1.safeIdent)(field)} ${dir}`)
             .join(', ');
     }
     buildLimitOffset(limit, offset) {

package/dist/graph/dgraph/index.js

@@ -404,6 +404,12 @@ class DgraphGraphDialect extends base_graph_dialect_1.BaseGraphDialect {
         const filter = this.renderDql((0, types_2.normalizeWhere)(spec.where), params);
         const funcArgs = [`func: type(${label})`];
         const order = spec.order || [];
+        // DQL's `orderasc`/`orderdesc` only take a predicate name — Dgraph has no
+        // random ordering at all, so `random()` raises the typed capability error
+        // instead of quietly ordering by whatever else was asked for.
+        if (order.some(([, d]) => d === 'RANDOM')) {
+            this.requireRandomOrderTerm();
+        }
         if (order.length) {
             const [f, d] = order[0];
             funcArgs.push(`${d === 'DESC' ? 'orderdesc' : 'orderasc'}: ${(0, types_2.safeIdent)(f)}`);

package/dist/graph/gremlin/index.d.ts

@@ -28,6 +28,12 @@ export declare class GremlinGraphDialect extends BaseGraphDialect {
     readonly library = "gremlin";
     private client;
     constructor(options?: GraphConnectionOptions);
+    /**
+     * TinkerPop shuffles with `order().by(shuffle)` — `shuffle` is a
+     * comparator token, not a property name, so it is emitted as a bare
+     * `.by(shuffle)` step (never quoted like a property key).
+     */
+    protected randomOrderTerm(): string;
     protected get defaultNodeVar(): string;
     connect(): Promise<void>;
     disconnect(): Promise<void>;

package/dist/graph/gremlin/index.js

@@ -36,6 +36,14 @@ class GremlinGraphDialect extends base_graph_dialect_1.BaseGraphDialect {
         this.client = null;
         this.dialectName = 'gremlin';
     }
+    /**
+     * TinkerPop shuffles with `order().by(shuffle)` — `shuffle` is a
+     * comparator token, not a property name, so it is emitted as a bare
+     * `.by(shuffle)` step (never quoted like a property key).
+     */
+    randomOrderTerm() {
+        return 'shuffle';
+    }
     get defaultNodeVar() {
         return 'it';
     }
@@ -220,7 +228,10 @@ class GremlinGraphDialect extends base_graph_dialect_1.BaseGraphDialect {
         if (order.length) {
             text += '.order()';
             for (const [f, d] of order) {
-                text += `.by(${gremlinStr(f)}, ${d === 'DESC' ? 'desc' : 'asc'})`;
+                text +=
+                    d === 'RANDOM'
+                        ? `.by(${this.requireRandomOrderTerm()})`
+                        : `.by(${gremlinStr(f)}, ${d === 'DESC' ? 'desc' : 'asc'})`;
             }
         }
         const offset = spec.offset !== undefined && spec.offset !== null ? Number(spec.offset) : 0;

package/dist/graph/index.d.ts

@@ -28,7 +28,7 @@ export { Neo4jGraphDialect } from './neo4j';
 export { GremlinGraphDialect } from './gremlin';
 export { DgraphGraphDialect } from './dgraph';
 export { GraphCapabilityError, ParamBag, normalizeWhere, deriveAssociationEdge, defaultEdgeLabel, safeIdent, } from './types';
-export type { GraphConnectionOptions, GraphStatement, GraphPredicate, CanonOp, GraphAssociationType, GraphAssociationSpec, GraphPropertyDefinition, NodeModelDefinition, EdgeModelDefinition, GraphTraversalDirection, GraphTraversalStep, GraphTraversalSpec, NodeMatchSpec, } from './types';
+export type { GraphConnectionOptions, GraphStatement, GraphPredicate, CanonOp, GraphAssociationType, GraphAssociationSpec, GraphPropertyDefinition, NodeModelDefinition, EdgeModelDefinition, GraphTraversalDirection, GraphTraversalStep, GraphTraversalSpec, GraphOrderDirection, GraphOrderTerm, NodeMatchSpec, } from './types';
 /** The graph dialects keyed by the name they should register under. */
 export declare const GRAPH_DIALECTS: {
     readonly neo4j: typeof Neo4jGraphDialect;

package/dist/graph/neo4j/index.d.ts

@@ -22,6 +22,8 @@ export declare class Neo4jGraphDialect extends BaseGraphDialect {
     private readonly txns;
     constructor(options?: GraphConnectionOptions);
     protected get defaultNodeVar(): string;
+    /** Cypher shuffles with the built-in `rand()` function. */
+    protected randomOrderTerm(): string;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     private requireDriver;

package/dist/graph/neo4j/index.js

@@ -44,6 +44,10 @@ class Neo4jGraphDialect extends base_graph_dialect_1.BaseGraphDialect {
     get defaultNodeVar() {
         return 'n';
     }
+    /** Cypher shuffles with the built-in `rand()` function. */
+    randomOrderTerm() {
+        return 'rand()';
+    }
     // -------------------------------------------------------------------
     // Connection lifecycle
     // -------------------------------------------------------------------
@@ -293,7 +297,8 @@ class Neo4jGraphDialect extends base_graph_dialect_1.BaseGraphDialect {
         text += `\nRETURN ${distinct}${projection}${includeReturns.length ? ', ' + includeReturns.join(', ') : ''}`;
         const order = spec.order || [];
         if (order.length) {
-            text += `\nORDER BY ${order.map(([f, d]) => `${v}.${(0, types_2.safeIdent)(f)} ${d}`).join(', ')}`;
+            const terms = order.map(([f, d]) => d === 'RANDOM' ? this.requireRandomOrderTerm() : `${v}.${(0, types_2.safeIdent)(f)} ${d}`);
+            text += `\nORDER BY ${terms.join(', ')}`;
         }
         if (spec.offset !== undefined && spec.offset !== null && String(spec.offset) !== '') {
             text += `\nSKIP ${Number(spec.offset)}`;