ts-prorm-orm 1.1.0 → 1.2.1

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

@@ -0,0 +1,539 @@
+"use strict";
+/**
+ * BaseGraphDialect — shared implementation of the SQL-shaped `Dialect`
+ * contract for graph/object databases.
+ *
+ * The ORM's `Model` layer talks to every backend through the `Dialect`
+ * interface (connect/query/transaction + `build*Query` codegen + DDL). This
+ * class implements that whole surface **once** for graph stores, translating:
+ *
+ *   - a table            -> a node label (vertex type)
+ *   - a row              -> a node
+ *   - an INSERT          -> CREATE node
+ *   - a SELECT           -> MATCH node (+ traversals for `include`)
+ *   - a WHERE            -> a graph predicate (via {@link normalizeWhere})
+ *   - an association     -> a graph edge/relationship
+ *   - an `include`       -> a graph walk over that edge
+ *   - "DDL"              -> node-label / edge-type / index / constraint mgmt
+ *
+ * Each concrete dialect (Neo4j / Gremlin / Dgraph) only implements the
+ * connection lifecycle and a small set of language-specific `compile*`
+ * codegen primitives; everything else is centralized here. Genuinely
+ * relational-only features (partitions, materialized views, RLS, stored
+ * procedures, foreign-data wrappers, arbitrary SQL joins) throw a typed
+ * {@link GraphCapabilityError} rather than silently doing the wrong thing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseGraphDialect = void 0;
+const stream_1 = require("stream");
+const dialect_1 = require("../dialects/dialect");
+const types_1 = require("./types");
+class BaseGraphDialect extends dialect_1.BaseDialect {
+    constructor(options = {}) {
+        super();
+        /** In-memory registry of node/edge models defined through the builder. */
+        this.nodeModels = new Map();
+        this.edgeModels = new Map();
+        this.options = options;
+    }
+    // =====================================================================
+    // Connection / util
+    // =====================================================================
+    getConnection() {
+        return this._connection;
+    }
+    isConnected() {
+        return this._connected;
+    }
+    /**
+     * Object-mode streaming: runs the query and pushes one row (or mapped
+     * model instance) per chunk. Graph drivers don't share a common cursor
+     * API, so this buffers the driver result and re-emits it — correct and
+     * dialect-agnostic, matching the `Model.findAllStream()` contract.
+     */
+    queryStream(statement, options) {
+        return stream_1.Readable.from(this.streamGen(statement, options));
+    }
+    async *streamGen(statement, options) {
+        const result = await this.query(statement, options);
+        for (const row of result.rows || []) {
+            yield row;
+        }
+    }
+    /** Values are parameterized, so `escape` is only a defensive fallback. */
+    escape(value) {
+        if (value === null || value === undefined)
+            return 'null';
+        if (typeof value === 'number' || typeof value === 'boolean')
+            return String(value);
+        return JSON.stringify(value);
+    }
+    escapeId(identifier) {
+        return (0, types_1.safeIdent)(identifier);
+    }
+    quoteIdentifier(identifier) {
+        return (0, types_1.safeIdent)(identifier);
+    }
+    quoteTable(tableName, _schema) {
+        return (0, types_1.safeIdent)(tableName);
+    }
+    /** Coarse property-type name; graph stores are largely schemaless. */
+    getDataTypeSql(dataType) {
+        const key = String(dataType?.key ?? dataType ?? '').toUpperCase();
+        if (/INT|SERIAL|DECIMAL|NUMER|FLOAT|DOUBLE|REAL/.test(key))
+            return 'number';
+        if (/BOOL/.test(key))
+            return 'boolean';
+        if (/DATE|TIME/.test(key))
+            return 'datetime';
+        if (/JSON/.test(key))
+            return 'object';
+        return 'string';
+    }
+    /** Run a compiled statement, forwarding its params as query bindings. */
+    async run(stmt, options) {
+        return this.query(stmt.text, {
+            ...options,
+            bind: { ...(options?.bind || {}), ...stmt.params },
+        });
+    }
+    /** Positional param array for the SQL-shaped `{ sql, values }` contract. */
+    paramValues(stmt) {
+        return Object.values(stmt.params);
+    }
+    /** Tolerant `Order` -> `[field, dir][]` normalizer. */
+    normalizeOrder(order) {
+        if (!order)
+            return [];
+        const out = [];
+        const arr = Array.isArray(order) ? order : [order];
+        for (const item of arr) {
+            if (typeof item === 'string') {
+                out.push([item, 'ASC']);
+            }
+            else if (Array.isArray(item)) {
+                const rawField = item[0];
+                const field = String(rawField && rawField.$col ? rawField.$col : rawField);
+                const dir = String(item[1] ?? 'ASC').toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
+                out.push([field, dir]);
+            }
+            else if (item && typeof item === 'object' && (item.$col || item.column)) {
+                out.push([String(item.$col || item.column), 'ASC']);
+            }
+        }
+        return out;
+    }
+    /** Map ORM `include` entries into graph traversal steps. */
+    mapIncludes(include) {
+        if (!include || !Array.isArray(include))
+            return [];
+        const steps = [];
+        for (const inc of include) {
+            if (!inc || typeof inc !== 'object')
+                continue;
+            const model = inc.model || inc.association?.target;
+            const edge = (0, types_1.deriveAssociationEdge)({
+                associationType: inc.association?.associationType || inc.associationType,
+                as: inc.as || model?.name || model?.tableName,
+                target: model?.name || model?.tableName || inc.as,
+                edgeLabel: inc.edgeLabel,
+            });
+            steps.push({
+                edgeLabel: edge.edgeLabel,
+                direction: edge.direction === 'in' ? 'in' : 'out',
+                targetLabel: edge.target,
+                as: edge.as,
+                where: inc.where,
+            });
+        }
+        return steps;
+    }
+    // =====================================================================
+    // Query builders (Dialect interface) — delegate to compile* primitives.
+    // =====================================================================
+    buildWhereClause(where, _options) {
+        const params = new types_1.ParamBag();
+        const pred = (0, types_1.normalizeWhere)(where);
+        const sql = this.renderPredicate(pred, { nodeVar: this.defaultNodeVar, params });
+        return { sql, values: params.toArray() };
+    }
+    buildOrderClause(order, _options) {
+        return this.normalizeOrder(order)
+            .map(([field, dir]) => `${this.defaultNodeVar}.${(0, types_1.safeIdent)(field)} ${dir}`)
+            .join(', ');
+    }
+    buildLimitOffset(limit, offset) {
+        const parts = [];
+        if (offset !== undefined && offset !== null && String(offset) !== '')
+            parts.push(`SKIP ${offset}`);
+        if (limit !== undefined && limit !== null && String(limit) !== '')
+            parts.push(`LIMIT ${limit}`);
+        return parts.join(' ');
+    }
+    buildInsertQuery(tableName, values, _options) {
+        const stmt = this.compileCreateNode(tableName, values);
+        return { sql: stmt.text, values: this.paramValues(stmt) };
+    }
+    buildUpdateQuery(tableName, values, where, _options) {
+        const stmt = this.compileUpdateNodes(tableName, where, values);
+        return { sql: stmt.text, values: this.paramValues(stmt) };
+    }
+    buildDeleteQuery(tableName, where, options) {
+        // A delete on a graph node detaches its relationships too, unless the
+        // caller explicitly opts out via `truncate: false`-style semantics.
+        const detach = options?.truncate !== false;
+        const stmt = this.compileDeleteNodes(tableName, where, detach);
+        return { sql: stmt.text, values: this.paramValues(stmt) };
+    }
+    buildSelectQuery(options) {
+        const spec = {
+            label: options.tableName,
+            where: options.where,
+            attributes: options.attributes,
+            order: this.normalizeOrder(options.order),
+            limit: options.limit,
+            offset: options.offset,
+            include: this.mapIncludes(options.include),
+            distinct: options.distinct,
+        };
+        const stmt = this.compileMatch(spec);
+        return { sql: stmt.text, values: this.paramValues(stmt) };
+    }
+    buildUpsertQuery(tableName, values, options) {
+        const conflictKeys = options?.conflictFields && options.conflictFields.length
+            ? options.conflictFields
+            : this.identityKeys(tableName);
+        const stmt = this.compileUpsertNode(tableName, values, conflictKeys);
+        return { sql: stmt.text, values: this.paramValues(stmt) };
+    }
+    buildIncrementQuery(tableName, fields, where, options) {
+        const stmt = this.compileIncrement(tableName, fields, where, options?.by ?? 1);
+        return { sql: stmt.text, values: this.paramValues(stmt) };
+    }
+    /** Identity property/properties for a label (defaults to `id`). */
+    identityKeys(label) {
+        const model = this.nodeModels.get(label);
+        if (model?.primaryKey)
+            return [model.primaryKey];
+        if (model?.properties) {
+            const pk = Object.entries(model.properties)
+                .filter(([, def]) => def.primaryKey)
+                .map(([name]) => name);
+            if (pk.length)
+                return pk;
+        }
+        return ['id'];
+    }
+    // =====================================================================
+    // DDL-equivalent: node labels, edges, indexes, constraints.
+    // =====================================================================
+    /**
+     * "CREATE TABLE" for a graph store = declare a node label and materialize
+     * its schema hints: unique/primary-key columns become uniqueness
+     * constraints, `references` columns become association edges, and indexed
+     * columns become property indexes. Nodes themselves stay schemaless.
+     */
+    async createTable(tableName, columns, _options) {
+        const props = {};
+        const associations = [];
+        let primaryKey;
+        for (const [name, def] of Object.entries(columns)) {
+            props[name] = {
+                type: this.getDataTypeSql(def.type),
+                unique: def.unique === true || typeof def.unique === 'string',
+                required: def.allowNull === false,
+                primaryKey: def.primaryKey === true,
+            };
+            if (def.primaryKey)
+                primaryKey = name;
+            if (def.references) {
+                associations.push((0, types_1.deriveAssociationEdge)({
+                    type: 'belongsTo',
+                    as: name.replace(/_?id$/i, '') || name,
+                    target: def.references.table,
+                }));
+            }
+        }
+        this.nodeModels.set(tableName, { label: tableName, properties: props, primaryKey, associations });
+        if (this.isConnected()) {
+            for (const [name, def] of Object.entries(columns)) {
+                if (def.primaryKey) {
+                    await this.run(this.compileCreateConstraint(tableName, [name], 'key'));
+                }
+                else if (def.unique) {
+                    await this.run(this.compileCreateConstraint(tableName, [name], 'unique'));
+                }
+            }
+        }
+    }
+    async dropTable(tableName, _options) {
+        this.nodeModels.delete(tableName);
+        if (this.isConnected()) {
+            await this.run(this.compileDeleteNodes(tableName, undefined, true));
+        }
+    }
+    async addIndex(tableName, indexName, fields, _options) {
+        await this.run(this.compileCreateIndex(tableName, fields, indexName));
+    }
+    async createIndex(tableName, indexDef) {
+        await this.run(this.compileCreateIndex(tableName, indexDef.fields, indexDef.name));
+    }
+    async removeIndex(tableName, indexName) {
+        await this.run(this.compileDropIndex(tableName, indexName));
+    }
+    async dropIndex(tableName, indexName, _options) {
+        await this.run(this.compileDropIndex(tableName, indexName));
+    }
+    async createConstraint(tableName, constraintDef) {
+        const kind = constraintDef.type === 'PRIMARY KEY' ? 'key' : constraintDef.type === 'UNIQUE' ? 'unique' : 'exists';
+        await this.run(this.compileCreateConstraint(tableName, constraintDef.fields || [], kind, constraintDef.name));
+    }
+    async dropConstraint(tableName, constraintName, _options) {
+        await this.run(this.compileDropConstraint(tableName, constraintName));
+    }
+    async addConstraint(tableName, options) {
+        if (options.type === 'FOREIGN KEY' || options.type === 'CHECK') {
+            // Foreign keys are modelled as edges, not constraints; CHECK has no
+            // graph equivalent. Both are no-ops here rather than hard failures.
+            return;
+        }
+        const kind = options.type === 'PRIMARY KEY' ? 'key' : 'unique';
+        await this.run(this.compileCreateConstraint(tableName, options.fields, kind, options.name));
+    }
+    async removeConstraint(tableName, constraintName) {
+        await this.run(this.compileDropConstraint(tableName, constraintName));
+    }
+    async showTables() {
+        const result = await this.run(this.compileShowLabels());
+        return (result.rows || [])
+            .map((r) => (typeof r === 'string' ? r : (r?.label ?? r?.name ?? Object.values(r || {})[0])))
+            .filter((v) => typeof v === 'string');
+    }
+    async showViews() {
+        return [];
+    }
+    async showMaterializedViews() {
+        return [];
+    }
+    async showConstraints(_tableName) {
+        return [];
+    }
+    async showIndexes(_tableName) {
+        return [];
+    }
+    async describeTable(_tableName) {
+        // Graph nodes are schemaless; describe from the registered model if any.
+        const model = this.nodeModels.get(_tableName);
+        const desc = {};
+        if (model?.properties) {
+            for (const [name, def] of Object.entries(model.properties)) {
+                desc[name] = {
+                    type: def.type || 'string',
+                    allowNull: !def.required,
+                    defaultValue: null,
+                    primaryKey: !!def.primaryKey,
+                    autoIncrement: false,
+                };
+            }
+        }
+        return desc;
+    }
+    // Schema/namespace: graph stores use a single database/namespace. These are
+    // no-ops (or single-entry) rather than emulated SQL schemas.
+    async createSchema(_schema) {
+        /* no-op: graph stores have no sub-schemas */
+    }
+    async dropSchema(_schema, _options) {
+        /* no-op */
+    }
+    async showAllSchemas() {
+        return this.options.database ? [this.options.database] : [];
+    }
+    // Schemaless: adding/removing/changing a property is a per-node write, so
+    // there's no label-level column DDL to run here.
+    async addColumn(_tableName, _columnName, _definition) {
+        /* no-op: node properties are dynamic */
+    }
+    async removeColumn(tableName, columnName) {
+        // Emulate DROP COLUMN by removing the property from every node.
+        if (this.isConnected()) {
+            await this.run(this.compileUpdateNodes(tableName, undefined, { [columnName]: undefined }));
+        }
+    }
+    async changeColumn(_tableName, _columnName, _definition) {
+        /* no-op: node properties are dynamic and untyped */
+    }
+    async commentTable(_tableName, _comment) {
+        /* no-op: comments have no graph equivalent */
+    }
+    async commentColumn(_tableName, _columnName, _comment) {
+        /* no-op */
+    }
+    // =====================================================================
+    // Graph-native builder API (association -> edge, traversal, CRUD).
+    // =====================================================================
+    /** Register a node model (label + property schema + associations). */
+    defineNode(def) {
+        this.nodeModels.set(def.label, def);
+    }
+    /** Register an edge/relationship model between two node labels. */
+    defineEdge(def) {
+        this.edgeModels.set(def.label, def);
+    }
+    /** Create a node and return the driver result. */
+    async createNode(label, data) {
+        return this.run(this.compileCreateNode(label, data));
+    }
+    /** Find nodes matching a spec, returning the driver rows. */
+    async findNodes(spec) {
+        const result = await this.run(this.compileMatch(spec));
+        return result.rows || [];
+    }
+    /** Update nodes matching a filter. */
+    async updateNodes(label, where, values) {
+        return this.run(this.compileUpdateNodes(label, where, values));
+    }
+    /** Delete nodes matching a filter (detaching their edges). */
+    async destroyNodes(label, where) {
+        return this.run(this.compileDeleteNodes(label, where, true));
+    }
+    /**
+     * Materialize an ORM association write as a graph edge: matches the two
+     * endpoints by filter and connects them with the association's edge label.
+     */
+    async relate(spec) {
+        return this.run(this.compileCreateEdge(spec));
+    }
+    /** Walk an association/edge from matching start node(s) — an `include`/join as a graph traversal. */
+    async traverse(spec) {
+        const result = await this.run(this.compileTraverse(spec));
+        return result.rows || [];
+    }
+    // =====================================================================
+    // Relational-only features with no graph equivalent -> typed errors.
+    // =====================================================================
+    unsupported(feature) {
+        throw new types_1.GraphCapabilityError(feature, this.name);
+    }
+    createPartitionedTable() {
+        return this.unsupported('partitioned tables');
+    }
+    createPartition(_options) {
+        return this.unsupported('partitions');
+    }
+    attachPartition(_options) {
+        return this.unsupported('partitions');
+    }
+    detachPartition(_options) {
+        return this.unsupported('partitions');
+    }
+    dropPartition() {
+        return this.unsupported('partitions');
+    }
+    createView(_viewName, _query, _options) {
+        return this.unsupported('views');
+    }
+    dropView(_viewName, _options) {
+        return this.unsupported('views');
+    }
+    createMaterializedView(_options) {
+        return this.unsupported('materialized views');
+    }
+    refreshMaterializedView(_viewName, _options) {
+        return this.unsupported('materialized views');
+    }
+    dropMaterializedView(_viewName, _options) {
+        return this.unsupported('materialized views');
+    }
+    hasMaterializedView(_viewName) {
+        return this.unsupported('materialized views');
+    }
+    createStoredProcedure(_options) {
+        return this.unsupported('stored procedures');
+    }
+    dropStoredProcedure(_procedureName, _options) {
+        return this.unsupported('stored procedures');
+    }
+    executeStoredProcedure(_options) {
+        return this.unsupported('stored procedures');
+    }
+    hasStoredProcedure(_procedureName, _schema) {
+        return this.unsupported('stored procedures');
+    }
+    createTrigger(_options) {
+        return this.unsupported('triggers');
+    }
+    dropTrigger(_triggerName, _tableName, _options) {
+        return this.unsupported('triggers');
+    }
+    hasTrigger(_triggerName, _tableName) {
+        return this.unsupported('triggers');
+    }
+    createSequence(_options) {
+        return this.unsupported('sequences');
+    }
+    dropSequence(_sequenceName, _options) {
+        return this.unsupported('sequences');
+    }
+    nextSequenceValue(_sequenceName) {
+        return this.unsupported('sequences');
+    }
+    hasSequence(_sequenceName) {
+        return this.unsupported('sequences');
+    }
+    createPolicy(_options) {
+        return this.unsupported('row-level-security policies');
+    }
+    dropPolicy(_policyName, _tableName, _options) {
+        return this.unsupported('row-level-security policies');
+    }
+    enableRLS(_tableName, _schema) {
+        return this.unsupported('row-level-security');
+    }
+    disableRLS(_tableName, _schema) {
+        return this.unsupported('row-level-security');
+    }
+    hasPolicy(_policyName, _tableName) {
+        return this.unsupported('row-level-security policies');
+    }
+    createPartialIndex() {
+        return this.unsupported('partial indexes');
+    }
+    createExpressionIndex() {
+        return this.unsupported('expression indexes');
+    }
+    createIdentityColumn() {
+        return this.unsupported('identity columns');
+    }
+    createComputedColumn() {
+        return this.unsupported('computed columns');
+    }
+    renameTable(_oldName, _newName) {
+        return this.unsupported('renaming a node label');
+    }
+    changeOwner(_newOwner, _tableName) {
+        return this.unsupported('ownership changes');
+    }
+    createForeignDataWrapper() {
+        return this.unsupported('foreign data wrappers');
+    }
+    dropForeignDataWrapper() {
+        return this.unsupported('foreign data wrappers');
+    }
+    createForeignServer() {
+        return this.unsupported('foreign servers');
+    }
+    dropForeignServer() {
+        return this.unsupported('foreign servers');
+    }
+    createForeignTable() {
+        return this.unsupported('foreign tables');
+    }
+    createSecurityPolicy() {
+        return this.unsupported('security policies');
+    }
+    dropSecurityPolicy() {
+        return this.unsupported('security policies');
+    }
+}
+exports.BaseGraphDialect = BaseGraphDialect;

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

@@ -0,0 +1,65 @@
+/**
+ * Dgraph graph dialect — DQL (GraphQL+-) queries + JSON mutations for the
+ * ORM builder API.
+ *
+ * Maps the ORM model API onto Dgraph's uid/predicate/edge model: node labels
+ * become `dgraph.type` values, finds become DQL `func: type(...)` blocks with
+ * `@filter(...)` and `expand(_all_)`, associations become edge predicates
+ * (reverse edges via `~pred` for inbound), and writes become JSON
+ * set/delete mutations (upserts resolve uids first, then mutate). Reads are
+ * parameterized with typed DQL vars (`$p0`); mutations carry structured JSON
+ * data (no string interpolation). Users never hand-write DQL/GraphQL for
+ * standard operations.
+ *
+ * Built on the optional `dgraph-js` gRPC driver, loaded lazily; a pre-built
+ * client can be injected via `options.client`.
+ */
+import { Transaction } from '../../types';
+import type { QueryOptions, QueryResult, TransactionOptions, WhereOptions } from '../../types';
+import { BaseGraphDialect, type EdgeCreateSpec, type NodeConstraintKind, type WhereRenderContext } from '../base-graph-dialect';
+import { type GraphConnectionOptions, type GraphPredicate, type GraphStatement, type GraphTraversalSpec, type NodeMatchSpec } from '../types';
+export declare class DgraphGraphDialect extends BaseGraphDialect {
+    readonly name = "dgraph";
+    readonly library = "dgraph-js";
+    private client;
+    private stub;
+    private readonly activeTxns;
+    private currentTxnId;
+    constructor(options?: GraphConnectionOptions);
+    protected get defaultNodeVar(): string;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private requireClient;
+    query(statement: string, options?: QueryOptions): Promise<QueryResult>;
+    private extractRows;
+    private toStringVars;
+    getDatabaseVersion(): Promise<string>;
+    private currentTxn;
+    startTransaction(options?: TransactionOptions): Promise<Transaction>;
+    commitTransaction(transaction: Transaction): Promise<void>;
+    rollbackTransaction(transaction: Transaction): Promise<void>;
+    private mutate;
+    private resolveData;
+    private resolveRows;
+    private runMutation;
+    renderPredicate(pred: GraphPredicate, ctx: WhereRenderContext): string;
+    /** Render a predicate; with `params` uses typed DQL vars, else inlines literals. */
+    private renderDql;
+    private renderComparison;
+    private varDefs;
+    compileMatch(spec: NodeMatchSpec): GraphStatement;
+    compileCreateNode(label: string, data: Record<string, unknown>): GraphStatement;
+    compileUpdateNodes(label: string, where: WhereOptions | undefined, values: Record<string, unknown>): GraphStatement;
+    compileDeleteNodes(label: string, where: WhereOptions | undefined, _detach: boolean): GraphStatement;
+    compileUpsertNode(label: string, data: Record<string, unknown>, conflictKeys: string[]): GraphStatement;
+    compileIncrement(label: string, fields: string | string[] | Record<string, number>, where: WhereOptions | undefined, by: number): GraphStatement;
+    compileCreateEdge(spec: EdgeCreateSpec): GraphStatement;
+    compileTraverse(spec: GraphTraversalSpec): GraphStatement;
+    private uidQuery;
+    compileCreateConstraint(label: string, fields: string[], _kind: NodeConstraintKind, _name?: string): GraphStatement;
+    compileDropConstraint(_label: string, _name: string): GraphStatement;
+    compileCreateIndex(_label: string, fields: string[], _name?: string): GraphStatement;
+    compileDropIndex(_label: string, _name: string): GraphStatement;
+    compileShowLabels(): GraphStatement;
+}
+export default DgraphGraphDialect;