ts-prorm-orm 1.1.0 → 1.2.0

package/dist/nosql/surrealdb/index.js

@@ -18,8 +18,14 @@
  * `require` is skipped entirely.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SurrealStore = void 0;
+exports.SurrealStore = exports.PushdownUnsupported = exports.compileOrder = exports.compileWhere = void 0;
 const errors_1 = require("../../errors");
+const query_compiler_1 = require("./query-compiler");
+const where_match_1 = require("../rocksdb/where-match");
+var query_compiler_2 = require("./query-compiler");
+Object.defineProperty(exports, "compileWhere", { enumerable: true, get: function () { return query_compiler_2.compileWhere; } });
+Object.defineProperty(exports, "compileOrder", { enumerable: true, get: function () { return query_compiler_2.compileOrder; } });
+Object.defineProperty(exports, "PushdownUnsupported", { enumerable: true, get: function () { return query_compiler_2.PushdownUnsupported; } });
 /**
  * `SurrealStore` wraps the `surrealdb` driver's `Surreal` client, exposing
  * record CRUD (`create`/`select`/`update`/`merge`/`delete`) and raw
@@ -174,6 +180,173 @@ class SurrealStore {
     async query(surql, vars) {
         return this.exec('query', (db) => db.query(surql, vars));
     }
+    // ---------------------------------------------------------------------
+    // ORM model layer (SurrealQL generation - no hand-written SurrealQL)
+    // ---------------------------------------------------------------------
+    //
+    // These map the ORM model API onto SurrealQL. `where`/`order`/`limit`/
+    // `offset` are compiled to a bound `SELECT ... WHERE ... ORDER BY ... LIMIT
+    // ... START` statement; operators SurrealQL can't express fall back to
+    // client-side evaluation with the shared matcher (see ./query-compiler.ts),
+    // so every standard query succeeds without the caller writing SurrealQL.
+    /** Unwrap the driver's per-statement query result into a row array. */
+    static rows(res, index = 0) {
+        const arr = Array.isArray(res) ? res : [res];
+        let entry = arr[index];
+        // Older drivers wrap results as `{ status, result, time }`.
+        if (entry && typeof entry === 'object' && 'result' in entry) {
+            entry = entry.result;
+        }
+        if (entry == null)
+            return [];
+        return (Array.isArray(entry) ? entry : [entry]);
+    }
+    /**
+     * ORM `findAll`. Compiles `where`/`order`/`limit`/`offset` to a bound
+     * SurrealQL `SELECT`; on an un-pushable operator it selects the table and
+     * filters/sorts/paginates client-side, so the result is always correct.
+     */
+    async findAll(table, options = {}) {
+        const { where, order, limit, offset, fetch } = options;
+        try {
+            const vars = { tb: table };
+            let surql = `SELECT * FROM type::table($tb)`;
+            if (where) {
+                const compiled = (0, query_compiler_1.compileWhere)(where);
+                Object.assign(vars, compiled.vars);
+                surql += ` WHERE ${compiled.clause}`;
+            }
+            if (order)
+                surql += ` ORDER BY ${(0, query_compiler_1.compileOrder)(order)}`;
+            if (typeof limit === 'number')
+                surql += ` LIMIT ${Math.trunc(limit)}`;
+            if (typeof offset === 'number' && offset > 0)
+                surql += ` START ${Math.trunc(offset)}`;
+            if (fetch && fetch.length > 0) {
+                // FETCH targets are interpolated, not bound — restrict to identifier
+                // paths (field / dotted link) to avoid SurrealQL injection.
+                for (const f of fetch) {
+                    if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(f)) {
+                        throw new errors_1.DatabaseError(`SurrealDB: invalid FETCH target "${f}"`);
+                    }
+                }
+                surql += ` FETCH ${fetch.join(', ')}`;
+            }
+            const res = await this.query(surql, vars);
+            return SurrealStore.rows(res);
+        }
+        catch (error) {
+            if (error instanceof query_compiler_1.PushdownUnsupported) {
+                return this.findAllClientSide(table, options);
+            }
+            throw error;
+        }
+    }
+    /** Client-side fallback: fetch the table, then filter/sort/page in memory. */
+    async findAllClientSide(table, options) {
+        let rows = SurrealStore.rows(await this.query(`SELECT * FROM type::table($tb)`, { tb: table }));
+        if (options.where)
+            rows = rows.filter((r) => (0, where_match_1.matchWhere)(r, options.where));
+        if (options.order)
+            rows = (0, where_match_1.applyOrder)(rows, options.order);
+        if (options.offset && options.offset > 0)
+            rows = rows.slice(options.offset);
+        if (typeof options.limit === 'number')
+            rows = rows.slice(0, options.limit);
+        return rows;
+    }
+    /** ORM `findOne`: the first row matching `where` (respecting order). */
+    async findOne(table, options = {}) {
+        const rows = await this.findAll(table, { ...options, limit: 1 });
+        return rows.length > 0 ? rows[0] : null;
+    }
+    /** ORM `findByPk`: select a single `table:id` record, or `null`. */
+    async findByPk(table, id) {
+        const thing = String(id).includes(':') ? String(id) : `${table}:${id}`;
+        const res = await this.select(thing);
+        const rows = Array.isArray(res) ? res : res == null ? [] : [res];
+        return rows.length > 0 ? rows[0] : null;
+    }
+    /** ORM `count`: number of records matching `where`. */
+    async count(table, where) {
+        try {
+            const vars = { tb: table };
+            let surql = `SELECT count() AS count FROM type::table($tb)`;
+            if (where) {
+                const compiled = (0, query_compiler_1.compileWhere)(where);
+                Object.assign(vars, compiled.vars);
+                surql += ` WHERE ${compiled.clause}`;
+            }
+            surql += ` GROUP ALL`;
+            const rows = SurrealStore.rows(await this.query(surql, vars));
+            return rows.length > 0 ? Number(rows[0].count) : 0;
+        }
+        catch (error) {
+            if (error instanceof query_compiler_1.PushdownUnsupported) {
+                return (await this.findAllClientSide(table, { where })).length;
+            }
+            throw error;
+        }
+    }
+    /** ORM `bulkCreate`: insert many records in one `INSERT` statement. */
+    async bulkCreate(table, rows) {
+        const res = await this.query(`INSERT INTO type::table($tb) $rows`, { tb: table, rows });
+        return SurrealStore.rows(res);
+    }
+    /**
+     * ORM `update`: merge `values` into every record matching `where` (or the
+     * whole table when `where` is omitted). Returns the updated records.
+     */
+    async updateWhere(table, values, where) {
+        const vars = { tb: table, values };
+        let surql = `UPDATE type::table($tb) MERGE $values`;
+        if (where) {
+            const compiled = (0, query_compiler_1.compileWhere)(where);
+            Object.assign(vars, compiled.vars);
+            surql += ` WHERE ${compiled.clause}`;
+        }
+        const res = await this.query(surql, vars);
+        return SurrealStore.rows(res);
+    }
+    /**
+     * ORM `destroy`: delete every record matching `where` (or the whole table
+     * when `where` is omitted). Returns the number of records deleted.
+     */
+    async destroy(table, where) {
+        const vars = { tb: table };
+        let surql = `DELETE type::table($tb)`;
+        if (where) {
+            const compiled = (0, query_compiler_1.compileWhere)(where);
+            Object.assign(vars, compiled.vars);
+            surql += ` WHERE ${compiled.clause}`;
+        }
+        surql += ` RETURN BEFORE`;
+        const res = await this.query(surql, vars);
+        return SurrealStore.rows(res).length;
+    }
+    /** ORM `truncate`: delete every record in a table. */
+    async truncate(table) {
+        return this.destroy(table);
+    }
+    /**
+     * Create a graph edge (association) between two records:
+     * `RELATE $from->edge->$to CONTENT $data`. This is how many-to-many /
+     * graph associations are expressed in SurrealDB, exposed through the ORM
+     * API so callers never hand-write the `RELATE` themselves.
+     */
+    async relate(from, edge, to, data) {
+        // `edge` is interpolated directly into the query (from/to/data are bound as
+        // $params), so it must be a bare identifier — reject anything else to avoid
+        // SurrealQL injection.
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(edge)) {
+            throw new errors_1.DatabaseError(`SurrealDB: invalid edge name "${edge}"`);
+        }
+        const surql = data
+            ? `RELATE type::thing($from)->${edge}->type::thing($to) CONTENT $data`
+            : `RELATE type::thing($from)->${edge}->type::thing($to)`;
+        const res = await this.query(surql, { from, to, data });
+        return SurrealStore.rows(res)[0];
+    }
 }
 exports.SurrealStore = SurrealStore;
 exports.default = SurrealStore;

package/dist/nosql/surrealdb/query-compiler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Compiles the ORM `where`/`order` shape into SurrealQL, so callers query
+ * SurrealDB through the model API instead of hand-writing SurrealQL for
+ * standard CRUD/reads.
+ *
+ * Every operand is emitted as a bound `$paramN` parameter (never string-
+ * interpolated) to keep the generated query injection-safe. Not every ORM
+ * operator has a first-class SurrealQL form; when {@link compileWhere} meets
+ * one it cannot push down safely it throws {@link PushdownUnsupported}, which
+ * the store catches to fall back to client-side filtering with the shared
+ * in-memory matcher - so the operation still succeeds, just evaluated locally.
+ */
+import type { WhereClause, OrderSpec } from '../rocksdb/where-match';
+/** Thrown when a where clause cannot be fully translated to SurrealQL. */
+export declare class PushdownUnsupported extends Error {
+    constructor(message: string);
+}
+/** Result of compiling a where clause: a SurrealQL boolean expr + its bound vars. */
+export interface CompiledWhere {
+    clause: string;
+    vars: Record<string, unknown>;
+}
+/** Compile a where clause to a SurrealQL boolean expression plus bound vars. */
+export declare function compileWhere(where: WhereClause): CompiledWhere;
+/** Compile an `order` spec to a SurrealQL `ORDER BY` list (without the keyword). */
+export declare function compileOrder(order: OrderSpec): string;

package/dist/nosql/surrealdb/query-compiler.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Compiles the ORM `where`/`order` shape into SurrealQL, so callers query
+ * SurrealDB through the model API instead of hand-writing SurrealQL for
+ * standard CRUD/reads.
+ *
+ * Every operand is emitted as a bound `$paramN` parameter (never string-
+ * interpolated) to keep the generated query injection-safe. Not every ORM
+ * operator has a first-class SurrealQL form; when {@link compileWhere} meets
+ * one it cannot push down safely it throws {@link PushdownUnsupported}, which
+ * the store catches to fall back to client-side filtering with the shared
+ * in-memory matcher - so the operation still succeeds, just evaluated locally.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PushdownUnsupported = void 0;
+exports.compileWhere = compileWhere;
+exports.compileOrder = compileOrder;
+/** Thrown when a where clause cannot be fully translated to SurrealQL. */
+class PushdownUnsupported extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PushdownUnsupported';
+    }
+}
+exports.PushdownUnsupported = PushdownUnsupported;
+function opName(key) {
+    if (typeof key === 'symbol')
+        return key.description ?? '';
+    return key.startsWith('$') ? key.slice(1) : key;
+}
+/** Escape a field path into a SurrealQL identifier (dotted paths preserved). */
+function ident(field) {
+    return field
+        .split('.')
+        .map((part) => (/^[A-Za-z_][A-Za-z0-9_]*$/.test(part) ? part : '`' + part.replace(/`/g, '\\`') + '`'))
+        .join('.');
+}
+class Compiler {
+    constructor() {
+        this.counter = 0;
+        this.vars = {};
+    }
+    bind(value) {
+        const name = `p${this.counter++}`;
+        this.vars[name] = value;
+        return `$${name}`;
+    }
+    compileClause(where) {
+        const parts = [];
+        for (const key of Reflect.ownKeys(where)) {
+            const op = opName(key);
+            const value = where[key];
+            if (op === 'and') {
+                const arr = Array.isArray(value) ? value : [value];
+                parts.push('(' + arr.map((s) => this.compileClause(s)).join(' AND ') + ')');
+            }
+            else if (op === 'or') {
+                const arr = Array.isArray(value) ? value : [value];
+                parts.push('(' + arr.map((s) => this.compileClause(s)).join(' OR ') + ')');
+            }
+            else if (op === 'not') {
+                const arr = Array.isArray(value) ? value : [value];
+                parts.push('!(' + arr.map((s) => this.compileClause(s)).join(' AND ') + ')');
+            }
+            else if (typeof key === 'symbol') {
+                // A symbol operator at clause level with no field: unsupported.
+                throw new PushdownUnsupported(`operator ${op} without a field`);
+            }
+            else {
+                parts.push(this.compileField(key, value));
+            }
+        }
+        return parts.length > 1 ? '(' + parts.join(' AND ') + ')' : parts[0] ?? 'true';
+    }
+    compileField(field, condition) {
+        const id = ident(field);
+        if (condition === null ||
+            typeof condition !== 'object' ||
+            condition instanceof Date ||
+            Array.isArray(condition)) {
+            return `${id} = ${this.bind(condition)}`;
+        }
+        const clauses = [];
+        for (const key of Reflect.ownKeys(condition)) {
+            const op = opName(key);
+            const operand = condition[key];
+            clauses.push(this.compileOperator(id, op, operand));
+        }
+        return clauses.length > 1 ? '(' + clauses.join(' AND ') + ')' : clauses[0] ?? 'true';
+    }
+    compileOperator(id, op, operand) {
+        switch (op) {
+            case 'eq':
+            case 'is':
+                return operand === null ? `${id} = NONE` : `${id} = ${this.bind(operand)}`;
+            case 'ne':
+                return operand === null ? `${id} != NONE` : `${id} != ${this.bind(operand)}`;
+            case 'gt':
+                return `${id} > ${this.bind(operand)}`;
+            case 'gte':
+                return `${id} >= ${this.bind(operand)}`;
+            case 'lt':
+                return `${id} < ${this.bind(operand)}`;
+            case 'lte':
+                return `${id} <= ${this.bind(operand)}`;
+            case 'in':
+                return `${id} IN ${this.bind(operand)}`;
+            case 'notIn':
+                return `${id} NOT IN ${this.bind(operand)}`;
+            case 'between': {
+                const [a, b] = operand;
+                return `(${id} >= ${this.bind(a)} AND ${id} <= ${this.bind(b)})`;
+            }
+            case 'notBetween': {
+                const [a, b] = operand;
+                return `!(${id} >= ${this.bind(a)} AND ${id} <= ${this.bind(b)})`;
+            }
+            case 'isNull':
+                return operand === false ? `${id} != NONE` : `${id} = NONE`;
+            case 'isNotNull':
+                return operand === false ? `${id} = NONE` : `${id} != NONE`;
+            case 'startsWith':
+                return `string::starts_with(${id}, ${this.bind(operand)})`;
+            case 'notStartsWith':
+                return `!string::starts_with(${id}, ${this.bind(operand)})`;
+            case 'endsWith':
+                return `string::ends_with(${id}, ${this.bind(operand)})`;
+            case 'notEndsWith':
+                return `!string::ends_with(${id}, ${this.bind(operand)})`;
+            case 'substring':
+                return `string::contains(${id}, ${this.bind(operand)})`;
+            case 'notSubstring':
+                return `!string::contains(${id}, ${this.bind(operand)})`;
+            case 'like':
+            case 'notLike':
+            case 'iLike':
+            case 'notILike':
+                return this.compileLike(id, op, String(operand));
+            case 'arrayContains':
+            case 'contains':
+                return `${id} CONTAINSALL ${this.bind(Array.isArray(operand) ? operand : [operand])}`;
+            case 'arrayOverlaps':
+                return `${id} CONTAINSANY ${this.bind(operand)}`;
+            case 'arrayContainedBy':
+                return `${id} ALLINSIDE ${this.bind(operand)}`;
+            default:
+                // Push the rest (regexp, json-path ops, etc.) to client-side eval.
+                throw new PushdownUnsupported(`operator ${op}`);
+        }
+    }
+    /** Translate simple LIKE patterns to SurrealDB `string::` calls; else fall back. */
+    compileLike(id, op, pattern) {
+        const negate = op === 'notLike' || op === 'notILike';
+        // Only prefix/suffix/contains patterns push down cleanly. Anything with
+        // internal wildcards or `_` is left to client-side evaluation.
+        const inner = pattern.slice(1, -1);
+        if (inner.includes('%') || inner.includes('_') || pattern.includes('_')) {
+            throw new PushdownUnsupported('complex LIKE pattern');
+        }
+        let expr;
+        if (pattern.startsWith('%') && pattern.endsWith('%')) {
+            expr = `string::contains(${id}, ${this.bind(inner)})`;
+        }
+        else if (pattern.endsWith('%')) {
+            expr = `string::starts_with(${id}, ${this.bind(pattern.slice(0, -1))})`;
+        }
+        else if (pattern.startsWith('%')) {
+            expr = `string::ends_with(${id}, ${this.bind(pattern.slice(1))})`;
+        }
+        else {
+            expr = `${id} = ${this.bind(pattern)}`;
+        }
+        return negate ? `!${expr}` : expr;
+    }
+}
+/** Compile a where clause to a SurrealQL boolean expression plus bound vars. */
+function compileWhere(where) {
+    const c = new Compiler();
+    const clause = c.compileClause(where);
+    return { clause, vars: c.vars };
+}
+/** Compile an `order` spec to a SurrealQL `ORDER BY` list (without the keyword). */
+function compileOrder(order) {
+    const entries = typeof order === 'string' ? [order] : order;
+    return entries
+        .map((entry) => {
+        if (typeof entry === 'string')
+            return `${ident(entry)} ASC`;
+        const [field, dir] = entry;
+        return `${ident(field)} ${String(dir).toUpperCase() === 'DESC' ? 'DESC' : 'ASC'}`;
+    })
+        .join(', ');
+}

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

@@ -0,0 +1,95 @@
+/**
+ * TerminusDB store implementation.
+ *
+ * TerminusDB is an immutable, versioned document/graph database with a
+ * git-like data model: every write produces a new commit on a branch, and
+ * the full commit history is retained, so past states are always
+ * reconstructable and the store is effectively append-only/auditable.
+ * Documents are typed JSON objects; queries are expressed in WOQL (the Web
+ * Object Query Language).
+ *
+ * TerminusDB is not a SQL `Dialect`, so this class implements the minimal
+ * `NoSqlStore` marker interface plus the shared ledger surface:
+ *  - `append(table, data)` -> `addDocument` of `{ '@type': table, ...data }`.
+ *  - `get(table, id)`      -> `getDocument` by `<table>/<id>`.
+ *  - `history(table, id)`  -> commit-log WOQL query for the document.
+ *  - `verify(table, id)`   -> fetch the document + report existence (its
+ *    presence in the immutable commit graph is its provenance).
+ *  - `query(woql)`         -> raw WOQL passthrough.
+ *
+ * ## Lazy driver loading
+ *
+ * `@terminusdb/terminusdb-client` is loaded lazily inside `connect()`. Tests
+ * inject a pre-built, already-connected `WOQLClient` via
+ * `TerminusdbStoreOptions.client`, bypassing the `require`.
+ */
+import { NoSqlStore } from '../store';
+/** The subset of a `@terminusdb/terminusdb-client` `WOQLClient` this store uses. */
+export interface TerminusClientLike {
+    connect?(): Promise<unknown>;
+    db?(dbName: string): unknown;
+    organization?(org: string): unknown;
+    addDocument(document: unknown, params?: unknown, dbId?: string, message?: string): Promise<any>;
+    getDocument(query: unknown, params?: unknown): Promise<any>;
+    updateDocument?(document: unknown, params?: unknown): Promise<any>;
+    deleteDocument?(query: unknown, params?: unknown): Promise<any>;
+    query(woql: unknown, commitMsg?: string): Promise<any>;
+}
+/** Connection options for `TerminusdbStore`. */
+export interface TerminusdbStoreOptions {
+    /** TerminusDB server URL, e.g. `'http://localhost:6363'`. */
+    url?: string;
+    user?: string;
+    /** API key / password. */
+    key?: string;
+    organization?: string;
+    /** Database (data product) to operate against. */
+    db?: string;
+    /** A pre-built `WOQLClient` to use instead of the lazy `require`. */
+    client?: TerminusClientLike;
+}
+/**
+ * `TerminusdbStore` wraps a `WOQLClient` behind the shared ledger surface.
+ */
+export declare class TerminusdbStore implements NoSqlStore {
+    readonly name = "terminusdb";
+    readonly library = "@terminusdb/terminusdb-client";
+    private readonly options;
+    private client;
+    private connected;
+    constructor(options?: TerminusdbStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `WOQLClient` for anything not wrapped here. */
+    getClient(): TerminusClientLike;
+    private requireClient;
+    private fullId;
+    private run;
+    /**
+     * Insert `data` as a new document of type `table` (a new commit). Returns
+     * whatever `addDocument` reports (typically the inserted document id(s)).
+     */
+    append(table: string, data: Record<string, unknown>): Promise<unknown>;
+    /** Fetch the current revision of document `<table>/<id>`. */
+    get(table: string, id: string): Promise<unknown>;
+    /**
+     * Return the commit history for document `<table>/<id>` via a WOQL query
+     * over the commit graph. Every past revision lives in the immutable commit
+     * chain, so this surfaces the document's provenance.
+     */
+    history(table: string, id: string): Promise<unknown>;
+    /**
+     * Verify document `<table>/<id>` by reading it back from the immutable
+     * store. Returns `{ id, exists, document }` - existence in the commit graph
+     * is the provenance guarantee (TerminusDB never mutates past commits).
+     */
+    verify(table: string, id: string): Promise<{
+        id: string;
+        exists: boolean;
+        document: unknown;
+    }>;
+    /** Run a raw WOQL query object. */
+    query(woql: unknown, commitMsg?: string): Promise<unknown>;
+}
+export default TerminusdbStore;