ts-prorm-orm 1.1.0 → 1.2.0

package/dist/nosql/rethinkdb/index.d.ts

@@ -0,0 +1,194 @@
+/**
+ * RethinkDB store implementation.
+ *
+ * RethinkDB is a document store whose queries are built by chaining methods
+ * on a term-builder (`r`) and executed with a trailing `.run()` - e.g.
+ * `r.table('users').filter({ active: true }).run(conn)`. That fluent,
+ * function-composition query model is nothing like the SQL-shaped `Dialect`
+ * interface (no `query(sql)`, no identifier escaping, no relational DDL), so
+ * this class implements the minimal `NoSqlStore` marker interface for
+ * connection lifecycle and otherwise exposes RethinkDB's real surface
+ * directly: document CRUD, ReQL `filter` predicates, table/database
+ * creation, and a `run()` escape hatch for arbitrary ReQL terms.
+ *
+ * Uses the `rethinkdb-ts` driver. The driver is lazily `require`d inside
+ * `connect()` so importing this module never forces `rethinkdb-ts` to be
+ * installed; the term-builder (`r`) and/or a `connection` can also be
+ * injected via the constructor options (used by the tests, and handy when a
+ * pool is managed elsewhere), in which case `connect()` skips the require.
+ */
+import { NoSqlStore } from '../store';
+/**
+ * Connection options for `RethinkDBStore`.
+ *
+ * `host`/`port`/`db` configure the connection made by the lazily-required
+ * `rethinkdb-ts` driver. Alternatively, an already-built term-builder (`r`)
+ * and/or an established `connection` can be injected: when `r` is provided,
+ * `connect()` uses it as-is and does not `require('rethinkdb-ts')`; when
+ * `connection` is provided, queries run against it (single-connection mode)
+ * instead of a driver-managed pool.
+ */
+export interface RethinkDBStoreOptions {
+    /** RethinkDB host. Defaults to `'localhost'`. */
+    host?: string;
+    /** RethinkDB client-driver port. Defaults to `28015`. */
+    port?: number;
+    /** Default database queries run against. Defaults to `'test'`. */
+    db?: string;
+    /**
+     * Injected `rethinkdb-ts` term-builder. When provided, `connect()` uses
+     * it directly and skips `require('rethinkdb-ts')` (used by tests to inject
+     * a mock, and to share an `r` configured elsewhere).
+     */
+    r?: any;
+    /**
+     * Injected connection. When provided, queries `.run(connection)` against
+     * it (single-connection mode) rather than relying on the driver's pool.
+     */
+    connection?: any;
+}
+/** One `[field, direction]` ordering term, e.g. `['createdAt', 'DESC']`. */
+export type OrderTerm = [string, 'ASC' | 'DESC'] | string;
+/** Options for {@link RethinkDBStore.findAll}/{@link RethinkDBStore.findOne}. */
+export interface RethinkFindOptions {
+    /** Ordering terms applied in sequence. A bare string sorts ascending. */
+    order?: OrderTerm | OrderTerm[];
+    /** Maximum number of documents to return. */
+    limit?: number;
+    /** Number of leading documents to skip (offset). */
+    offset?: number;
+}
+/** A group-aggregation request for {@link RethinkDBStore.aggregate}. */
+export interface RethinkAggregateOptions {
+    /** ORM `where` filter applied before grouping. */
+    where?: Record<string | symbol, unknown>;
+    /** Field(s) to group by. Omit for a single whole-table group. */
+    groupBy?: string | string[];
+    /** Emit a `count` per group. */
+    count?: boolean;
+    /** Fields to `sum` per group, keyed by output name → source field. */
+    sum?: Record<string, string>;
+    /** Fields to `avg` per group, keyed by output name → source field. */
+    avg?: Record<string, string>;
+    /** Fields to `min` per group, keyed by output name → source field. */
+    min?: Record<string, string>;
+    /** Fields to `max` per group, keyed by output name → source field. */
+    max?: Record<string, string>;
+}
+/**
+ * `RethinkDBStore` wraps the `rethinkdb-ts` term-builder (`r`) in a small,
+ * promise-based convenience layer over document CRUD, ReQL `filter`
+ * queries, and table/database creation, plus a `run()` escape hatch for
+ * arbitrary ReQL terms.
+ */
+export declare class RethinkDBStore implements NoSqlStore {
+    readonly name = "rethinkdb";
+    readonly library = "rethinkdb-ts";
+    private readonly options;
+    /** The `rethinkdb-ts` term-builder (`r`) once connected. */
+    private r;
+    /** A single connection, when in single-connection (injected) mode. */
+    private connection;
+    private connected;
+    constructor(options?: RethinkDBStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `rethinkdb-ts` term-builder (`r`). */
+    getClient(): unknown;
+    private requireR;
+    /**
+     * Execute a built ReQL query. In single-connection mode the connection is
+     * passed to `.run(connection)`; with a driver-managed pool `.run()` needs
+     * no argument.
+     */
+    private runQuery;
+    private exec;
+    /** Insert a document (or array of documents) into `table`. */
+    insert<T = any>(table: string, doc: Record<string, unknown> | Record<string, unknown>[]): Promise<T>;
+    /** Fetch a single document from `table` by its primary key. Resolves to `null` if not found. */
+    get<T = any>(table: string, id: unknown): Promise<T | null>;
+    /** Partially update the document with primary key `id` in `table`, merging `patch`. */
+    update<T = any>(table: string, id: unknown, patch: Record<string, unknown>): Promise<T>;
+    /** Delete the document with primary key `id` from `table`. */
+    delete<T = any>(table: string, id: unknown): Promise<T>;
+    /**
+     * Return all documents in `table` matching `predicate` as an array.
+     * `predicate` is any ReQL `filter` argument - a match object
+     * (`{ active: true }`) or a predicate function (`row => row('age').gt(18)`).
+     * The result is materialized (cursor drained to an array) before returning.
+     */
+    filter<T = any>(table: string, predicate: unknown): Promise<T[]>;
+    /** Drain a ReQL cursor to an array (arrays and plain values are passed through). */
+    private toArray;
+    private applyOrderLimit;
+    /**
+     * Fetch all documents in `table` matching an ORM `where` clause, with
+     * optional ordering, offset, and limit. The `where` object accepts the full
+     * ORM operator surface (`Op.gt`, `Op.in`, `Op.like`, `Op.and`/`Op.or`, ...),
+     * translated to a native ReQL `filter` predicate - so standard queries never
+     * require hand-written ReQL.
+     */
+    findAll<T = any>(table: string, where?: Record<string | symbol, unknown>, options?: RethinkFindOptions): Promise<T[]>;
+    /** Fetch the first document in `table` matching an ORM `where` clause (respecting `order`), or `null`. */
+    findOne<T = any>(table: string, where?: Record<string | symbol, unknown>, options?: Omit<RethinkFindOptions, 'limit'>): Promise<T | null>;
+    /** Count documents in `table` matching an ORM `where` clause. */
+    count(table: string, where?: Record<string | symbol, unknown>): Promise<number>;
+    /** Update every document in `table` matching an ORM `where` clause, merging `patch`. */
+    updateWhere<T = any>(table: string, where: Record<string | symbol, unknown>, patch: Record<string, unknown>): Promise<T>;
+    /** Delete every document in `table` matching an ORM `where` clause. */
+    deleteWhere<T = any>(table: string, where: Record<string | symbol, unknown>): Promise<T>;
+    /**
+     * Insert `doc`, updating (or replacing) the existing row on a primary-key
+     * conflict - RethinkDB's native upsert via `insert(..., { conflict })`.
+     */
+    upsert<T = any>(table: string, doc: Record<string, unknown> | Record<string, unknown>[], conflict?: 'update' | 'replace'): Promise<T>;
+    /** Distinct values of `field` across `table` (optionally over a secondary index). */
+    distinct<T = any>(table: string, field?: string, index?: string): Promise<T[]>;
+    /** Fetch documents whose key (or secondary-index value) is one of `keys`. */
+    getAll<T = any>(table: string, keys: unknown[], index?: string): Promise<T[]>;
+    /**
+     * Grouped aggregation over `table` using ReQL's native `group`/reduction
+     * chain (`count`/`sum`/`avg`/`min`/`max`), with an optional ORM `where`
+     * pre-filter. Returns one entry per group: `{ group, ...aggregates }`.
+     */
+    aggregate(table: string, options?: RethinkAggregateOptions): Promise<Array<Record<string, unknown>>>;
+    /** Create a secondary index on `table`. `indexer` may be a field name, list of fields (compound), or a ReQL function. */
+    indexCreate<T = any>(table: string, name: string, indexer?: unknown, options?: Record<string, unknown>): Promise<T>;
+    /** Drop a secondary index from `table`. */
+    indexDrop<T = any>(table: string, name: string): Promise<T>;
+    /** List secondary index names on `table`. */
+    indexList(table: string): Promise<string[]>;
+    /** Wait for one or all secondary indexes on `table` to finish building. */
+    indexWait<T = any>(table: string, ...names: string[]): Promise<T>;
+    /**
+     * Create a table. Pass a single `name` to create it in the connection's
+     * default database, or `(db, name)` to create it in a specific database.
+     */
+    createTable<T = any>(dbOrName: string, name?: string): Promise<T>;
+    /** Drop a table. Pass a single `name`, or `(db, name)` for a specific database. */
+    dropTable<T = any>(dbOrName: string, name?: string): Promise<T>;
+    /** List tables in the default (or given) database. */
+    listTables(db?: string): Promise<string[]>;
+    /** Create a database. */
+    createDatabase<T = any>(name: string): Promise<T>;
+    /** Drop a database. */
+    dropDatabase<T = any>(name: string): Promise<T>;
+    /** List all databases. */
+    listDatabases(): Promise<string[]>;
+    /**
+     * RethinkDB has no multi-document transactions. Single-document writes are
+     * atomic, and {@link updateWhere}/{@link deleteWhere} apply atomically per
+     * document, but there is no way to commit changes across documents/tables
+     * as a unit. This throws a clear, typed capability error rather than
+     * silently pretending to provide isolation.
+     */
+    withTransaction<T>(_fn: (store: this) => Promise<T>): Promise<never>;
+    /**
+     * Run an arbitrary ReQL `query` term (built from `getClient()`), for
+     * operations not wrapped here. In single-connection mode the store's
+     * connection is supplied to `.run()` automatically.
+     */
+    run<T = any>(query: any): Promise<T>;
+}
+export default RethinkDBStore;

package/dist/nosql/rethinkdb/index.js

@@ -21,9 +21,113 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RethinkDBStore = void 0;
 const errors_1 = require("../../errors");
+const operators_1 = require("../../operators");
+const where_1 = require("./where");
 const DEFAULT_HOST = 'localhost';
 const DEFAULT_PORT = 28015;
 const DEFAULT_DB = 'test';
+/** Whether `order` is a single `[field, direction]` tuple rather than a list of terms. */
+function isSingleOrderTerm(order) {
+    return (order.length === 2 &&
+        typeof order[0] === 'string' &&
+        (order[1] === 'ASC' || order[1] === 'DESC'));
+}
+/** Access a possibly-dotted field path on a ReQL `row`, e.g. `a.b` → `row('a')('b')`. */
+function reqlField(row, field) {
+    const parts = field.split('.');
+    let acc = row(parts[0]);
+    for (let i = 1; i < parts.length; i++)
+        acc = acc(parts[i]);
+    return acc;
+}
+/**
+ * Render a {@link WhereNode} into a ReQL predicate function
+ * (`row => booleanTerm`) using the term-builder `r`. Covers the standard ORM
+ * comparison and logical operators so callers never hand-write ReQL filters.
+ */
+function buildReqlPredicate(r, node) {
+    switch (node.kind) {
+        case 'true':
+            return () => r.expr(true);
+        case 'and': {
+            const parts = node.nodes.map((n) => buildReqlPredicate(r, n));
+            return (row) => parts.slice(1).reduce((acc, p) => acc.and(p(row)), parts[0] ? parts[0](row) : r.expr(true));
+        }
+        case 'or': {
+            const parts = node.nodes.map((n) => buildReqlPredicate(r, n));
+            return (row) => parts.slice(1).reduce((acc, p) => acc.or(p(row)), parts[0] ? parts[0](row) : r.expr(false));
+        }
+        case 'not': {
+            const inner = buildReqlPredicate(r, node.node);
+            return (row) => inner(row).not();
+        }
+        case 'cmp':
+            return (row) => buildReqlCmp(r, row, node.field, node.op, node.value);
+    }
+}
+function buildReqlCmp(r, row, field, op, value) {
+    const f = reqlField(row, field);
+    switch (op) {
+        case operators_1.Op.eq:
+            return value === null ? f.eq(null).or(r.not(row.hasFields(field))) : f.eq(value);
+        case operators_1.Op.ne:
+            return value === null ? f.eq(null).not().and(row.hasFields(field)) : f.ne(value);
+        case operators_1.Op.gt:
+            return f.gt(value);
+        case operators_1.Op.gte:
+            return f.ge(value);
+        case operators_1.Op.lt:
+            return f.lt(value);
+        case operators_1.Op.lte:
+            return f.le(value);
+        case operators_1.Op.in:
+            return r.expr(value).contains(f);
+        case operators_1.Op.notIn:
+            return r.expr(value).contains(f).not();
+        case operators_1.Op.between: {
+            const [lo, hi] = value;
+            return f.ge(lo).and(f.le(hi));
+        }
+        case operators_1.Op.notBetween: {
+            const [lo, hi] = value;
+            return f.ge(lo).and(f.le(hi)).not();
+        }
+        case operators_1.Op.isNull:
+            return f.eq(null).or(r.not(row.hasFields(field)));
+        case operators_1.Op.isNotNull:
+            return row.hasFields(field).and(f.eq(null).not());
+        case operators_1.Op.like:
+            return f.match((0, where_1.likeToRegex)(String(value)));
+        case operators_1.Op.notLike:
+            return f.match((0, where_1.likeToRegex)(String(value))).not();
+        case operators_1.Op.iLike:
+            return f.match((0, where_1.likeToRegex)(String(value), true));
+        case operators_1.Op.notILike:
+            return f.match((0, where_1.likeToRegex)(String(value), true)).not();
+        case operators_1.Op.startsWith:
+            return f.match(`^${escapeReqlRegex(String(value))}`);
+        case operators_1.Op.endsWith:
+            return f.match(`${escapeReqlRegex(String(value))}$`);
+        case operators_1.Op.substring:
+        case operators_1.Op.contains:
+            return f.match(escapeReqlRegex(String(value)));
+        case operators_1.Op.regexp:
+            return f.match(String(value));
+        case operators_1.Op.notRegexp:
+            return f.match(String(value)).not();
+        case operators_1.Op.iRegexp:
+            return f.match(`(?i)${String(value)}`);
+        case operators_1.Op.notIRegexp:
+            return f.match(`(?i)${String(value)}`).not();
+        default:
+            throw new errors_1.DatabaseError(`RethinkDB: unsupported where operator "${op.toString()}"`, {
+                code: errors_1.ErrorCodes.QUERY_ERROR,
+            });
+    }
+}
+function escapeReqlRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 function wrapConnectionError(err, host) {
     const parent = err instanceof Error ? err : new Error(String(err));
     const message = /econnrefused/i.test(parent.message)
@@ -189,6 +293,159 @@ class RethinkDBStore {
         return result == null ? [] : [result];
     }
     // ---------------------------------------------------------------------
+    // ORM-shaped queries (no hand-written ReQL required)
+    // ---------------------------------------------------------------------
+    applyOrderLimit(r, query, options = {}) {
+        let q = query;
+        if (options.order !== undefined) {
+            const terms = Array.isArray(options.order) && !isSingleOrderTerm(options.order)
+                ? options.order
+                : [options.order];
+            const reqlTerms = terms.map((term) => {
+                if (typeof term === 'string')
+                    return r.asc(term);
+                const [field, dir] = term;
+                return dir === 'DESC' ? r.desc(field) : r.asc(field);
+            });
+            q = q.orderBy(...reqlTerms);
+        }
+        if (typeof options.offset === 'number')
+            q = q.skip(options.offset);
+        if (typeof options.limit === 'number')
+            q = q.limit(options.limit);
+        return q;
+    }
+    /**
+     * Fetch all documents in `table` matching an ORM `where` clause, with
+     * optional ordering, offset, and limit. The `where` object accepts the full
+     * ORM operator surface (`Op.gt`, `Op.in`, `Op.like`, `Op.and`/`Op.or`, ...),
+     * translated to a native ReQL `filter` predicate - so standard queries never
+     * require hand-written ReQL.
+     */
+    async findAll(table, where = {}, options = {}) {
+        const result = await this.exec((r) => {
+            const pred = buildReqlPredicate(r, (0, where_1.parseWhere)(where));
+            return this.applyOrderLimit(r, r.table(table).filter(pred), options);
+        }, 'findAll');
+        return this.toArray(result);
+    }
+    /** Fetch the first document in `table` matching an ORM `where` clause (respecting `order`), or `null`. */
+    async findOne(table, where = {}, options = {}) {
+        const rows = await this.findAll(table, where, { ...options, limit: 1 });
+        return rows.length > 0 ? rows[0] : null;
+    }
+    /** Count documents in `table` matching an ORM `where` clause. */
+    async count(table, where = {}) {
+        return this.exec((r) => {
+            const pred = buildReqlPredicate(r, (0, where_1.parseWhere)(where));
+            return r.table(table).filter(pred).count();
+        }, 'count');
+    }
+    /** Update every document in `table` matching an ORM `where` clause, merging `patch`. */
+    async updateWhere(table, where, patch) {
+        return this.exec((r) => {
+            const pred = buildReqlPredicate(r, (0, where_1.parseWhere)(where));
+            return r.table(table).filter(pred).update(patch);
+        }, 'updateWhere');
+    }
+    /** Delete every document in `table` matching an ORM `where` clause. */
+    async deleteWhere(table, where) {
+        return this.exec((r) => {
+            const pred = buildReqlPredicate(r, (0, where_1.parseWhere)(where));
+            return r.table(table).filter(pred).delete();
+        }, 'deleteWhere');
+    }
+    /**
+     * Insert `doc`, updating (or replacing) the existing row on a primary-key
+     * conflict - RethinkDB's native upsert via `insert(..., { conflict })`.
+     */
+    async upsert(table, doc, conflict = 'update') {
+        return this.exec((r) => r.table(table).insert(doc, { conflict }), 'upsert');
+    }
+    /** Distinct values of `field` across `table` (optionally over a secondary index). */
+    async distinct(table, field, index) {
+        const result = await this.exec((r) => {
+            let q = r.table(table);
+            if (index)
+                return q.distinct({ index });
+            if (field)
+                q = q.getField(field);
+            return q.distinct();
+        }, 'distinct');
+        return this.toArray(result);
+    }
+    /** Fetch documents whose key (or secondary-index value) is one of `keys`. */
+    async getAll(table, keys, index) {
+        const result = await this.exec((r) => index ? r.table(table).getAll(...keys, { index }) : r.table(table).getAll(...keys), 'getAll');
+        return this.toArray(result);
+    }
+    /**
+     * Grouped aggregation over `table` using ReQL's native `group`/reduction
+     * chain (`count`/`sum`/`avg`/`min`/`max`), with an optional ORM `where`
+     * pre-filter. Returns one entry per group: `{ group, ...aggregates }`.
+     */
+    async aggregate(table, options = {}) {
+        const result = await this.exec((r) => {
+            let q = r.table(table);
+            if (options.where)
+                q = q.filter(buildReqlPredicate(r, (0, where_1.parseWhere)(options.where)));
+            const groupFields = options.groupBy
+                ? Array.isArray(options.groupBy)
+                    ? options.groupBy
+                    : [options.groupBy]
+                : [];
+            const grouped = groupFields.length > 0 ? q.group(...groupFields) : q.group(() => r.expr(null));
+            const aggregates = {};
+            if (options.count)
+                aggregates.count = grouped.count();
+            for (const [out, src] of Object.entries(options.sum ?? {}))
+                aggregates[out] = grouped.sum(src);
+            for (const [out, src] of Object.entries(options.avg ?? {}))
+                aggregates[out] = grouped.avg(src);
+            for (const [out, src] of Object.entries(options.min ?? {}))
+                aggregates[out] = grouped.min(src)(src);
+            for (const [out, src] of Object.entries(options.max ?? {}))
+                aggregates[out] = grouped.max(src)(src);
+            if (Object.keys(aggregates).length === 0)
+                aggregates.count = grouped.count();
+            // Ungroup each aggregate stream and merge by group key on the client.
+            const streams = Object.entries(aggregates).map(([name, agg]) => agg.ungroup().map((row) => ({ group: row('group'), name, value: row('reduction') })));
+            return r.union(...streams).coerceTo('array');
+        }, 'aggregate');
+        const rows = await this.toArray(result);
+        const byGroup = new Map();
+        for (const row of rows) {
+            const key = JSON.stringify(row.group);
+            const entry = byGroup.get(key) ?? { group: row.group };
+            entry[row.name] = row.value;
+            byGroup.set(key, entry);
+        }
+        return Array.from(byGroup.values());
+    }
+    // ---------------------------------------------------------------------
+    // Secondary indexes
+    // ---------------------------------------------------------------------
+    /** Create a secondary index on `table`. `indexer` may be a field name, list of fields (compound), or a ReQL function. */
+    async indexCreate(table, name, indexer, options) {
+        return this.exec((r) => {
+            if (indexer === undefined)
+                return r.table(table).indexCreate(name, options);
+            return r.table(table).indexCreate(name, indexer, options);
+        }, 'indexCreate');
+    }
+    /** Drop a secondary index from `table`. */
+    async indexDrop(table, name) {
+        return this.exec((r) => r.table(table).indexDrop(name), 'indexDrop');
+    }
+    /** List secondary index names on `table`. */
+    async indexList(table) {
+        return this.exec((r) => r.table(table).indexList(), 'indexList');
+    }
+    /** Wait for one or all secondary indexes on `table` to finish building. */
+    async indexWait(table, ...names) {
+        return this.exec((r) => (names.length > 0 ? r.table(table).indexWait(...names) : r.table(table).indexWait()), 'indexWait');
+    }
+    // ---------------------------------------------------------------------
     // Schema / administration
     // ---------------------------------------------------------------------
     /**
@@ -201,10 +458,43 @@ class RethinkDBStore {
         }
         return this.exec((r) => r.tableCreate(dbOrName), 'createTable');
     }
+    /** Drop a table. Pass a single `name`, or `(db, name)` for a specific database. */
+    async dropTable(dbOrName, name) {
+        if (name !== undefined) {
+            return this.exec((r) => r.db(dbOrName).tableDrop(name), 'dropTable');
+        }
+        return this.exec((r) => r.tableDrop(dbOrName), 'dropTable');
+    }
+    /** List tables in the default (or given) database. */
+    async listTables(db) {
+        return this.exec((r) => (db ? r.db(db).tableList() : r.tableList()), 'listTables');
+    }
     /** Create a database. */
     async createDatabase(name) {
         return this.exec((r) => r.dbCreate(name), 'createDatabase');
     }
+    /** Drop a database. */
+    async dropDatabase(name) {
+        return this.exec((r) => r.dbDrop(name), 'dropDatabase');
+    }
+    /** List all databases. */
+    async listDatabases() {
+        return this.exec((r) => r.dbList(), 'listDatabases');
+    }
+    // ---------------------------------------------------------------------
+    // Transactions (unsupported)
+    // ---------------------------------------------------------------------
+    /**
+     * RethinkDB has no multi-document transactions. Single-document writes are
+     * atomic, and {@link updateWhere}/{@link deleteWhere} apply atomically per
+     * document, but there is no way to commit changes across documents/tables
+     * as a unit. This throws a clear, typed capability error rather than
+     * silently pretending to provide isolation.
+     */
+    async withTransaction(_fn) {
+        throw new errors_1.DatabaseError('RethinkDB does not support multi-document transactions. Single-document writes are atomic; ' +
+            'for cross-document atomicity model the data in one document or use conditional (compare-and-set) updates.', { code: errors_1.ErrorCodes.QUERY_ERROR });
+    }
     // ---------------------------------------------------------------------
     // Escape hatch
     // ---------------------------------------------------------------------

package/dist/nosql/rethinkdb/where.d.ts

@@ -0,0 +1,38 @@
+/** A single field comparison, e.g. `age >= 18`. */
+export interface CmpNode {
+    kind: 'cmp';
+    field: string;
+    op: symbol;
+    value: unknown;
+}
+/** A normalized boolean tree produced by {@link parseWhere}. */
+export type WhereNode = CmpNode | {
+    kind: 'and';
+    nodes: WhereNode[];
+} | {
+    kind: 'or';
+    nodes: WhereNode[];
+} | {
+    kind: 'not';
+    node: WhereNode;
+} | {
+    kind: 'true';
+};
+/**
+ * Parse an ORM `where` object into a {@link WhereNode} tree.
+ *
+ * - String keys are field conditions: a scalar means equality, an array means
+ *   `Op.in`, and a nested `{ [Op.*]: value }` object expands to one comparison
+ *   per operator.
+ * - `Op.and`/`Op.or` take an array of sub-`where` objects; `Op.not` negates a
+ *   single sub-`where`.
+ */
+export declare function parseWhere(where: Record<string | symbol, unknown> | undefined | null): WhereNode;
+/** Escape a string for safe inclusion in a regular expression. */
+export declare function escapeRegex(s: string): string;
+/**
+ * Translate a SQL `LIKE`/`ILIKE` pattern into an anchored regular expression
+ * (`%` → `.*`, `_` → `.`), so stores that only speak regex can honor ORM
+ * `Op.like` queries without the caller hand-writing a pattern.
+ */
+export declare function likeToRegex(pattern: string, caseInsensitive?: boolean): string;

package/dist/nosql/rethinkdb/where.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseWhere = parseWhere;
+exports.escapeRegex = escapeRegex;
+exports.likeToRegex = likeToRegex;
+/**
+ * ORM where-clause parser for the RethinkDB store.
+ *
+ * Turns the ORM's `where` shape (plain-object field conditions, `Op.*`
+ * comparison symbols, and `Op.and`/`Op.or`/`Op.not` logical symbols) into a
+ * small, store-agnostic {@link WhereNode} tree that the store then renders to
+ * a ReQL `filter` predicate. This is what lets callers write standard ORM
+ * queries (`{ age: { [Op.gte]: 18 } }`) instead of hand-building ReQL row
+ * predicates.
+ */
+const operators_1 = require("../../operators");
+/** Whether `v` is a plain object carrying `Op.*` comparison symbols (e.g. `{ [Op.gt]: 5 }`). */
+function hasOpSymbols(v) {
+    return (v !== null &&
+        typeof v === 'object' &&
+        !Array.isArray(v) &&
+        Object.getOwnPropertySymbols(v).length > 0);
+}
+/**
+ * Parse an ORM `where` object into a {@link WhereNode} tree.
+ *
+ * - String keys are field conditions: a scalar means equality, an array means
+ *   `Op.in`, and a nested `{ [Op.*]: value }` object expands to one comparison
+ *   per operator.
+ * - `Op.and`/`Op.or` take an array of sub-`where` objects; `Op.not` negates a
+ *   single sub-`where`.
+ */
+function parseWhere(where) {
+    if (!where)
+        return { kind: 'true' };
+    const nodes = [];
+    for (const sym of Object.getOwnPropertySymbols(where)) {
+        const val = where[sym];
+        if (sym === operators_1.Op.and) {
+            nodes.push({ kind: 'and', nodes: asArray(val).map(parseWhere) });
+        }
+        else if (sym === operators_1.Op.or) {
+            nodes.push({ kind: 'or', nodes: asArray(val).map(parseWhere) });
+        }
+        else if (sym === operators_1.Op.not) {
+            nodes.push({ kind: 'not', node: parseWhere(val) });
+        }
+    }
+    for (const field of Object.keys(where)) {
+        const val = where[field];
+        if (hasOpSymbols(val)) {
+            for (const opSym of Object.getOwnPropertySymbols(val)) {
+                nodes.push({ kind: 'cmp', field, op: opSym, value: val[opSym] });
+            }
+            continue;
+        }
+        if (Array.isArray(val)) {
+            nodes.push({ kind: 'cmp', field, op: operators_1.Op.in, value: val });
+        }
+        else {
+            nodes.push({ kind: 'cmp', field, op: operators_1.Op.eq, value: val });
+        }
+    }
+    if (nodes.length === 0)
+        return { kind: 'true' };
+    if (nodes.length === 1)
+        return nodes[0];
+    return { kind: 'and', nodes };
+}
+function asArray(v) {
+    return (Array.isArray(v) ? v : [v]);
+}
+/** Escape a string for safe inclusion in a regular expression. */
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Translate a SQL `LIKE`/`ILIKE` pattern into an anchored regular expression
+ * (`%` → `.*`, `_` → `.`), so stores that only speak regex can honor ORM
+ * `Op.like` queries without the caller hand-writing a pattern.
+ */
+function likeToRegex(pattern, caseInsensitive = false) {
+    let out = '';
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === '%')
+            out += '.*';
+        else if (ch === '_')
+            out += '.';
+        else
+            out += escapeRegex(ch);
+    }
+    return `${caseInsensitive ? '(?i)' : ''}^${out}$`;
+}