ts-prorm-orm 1.1.0 → 1.2.0

package/dist/graph/neo4j/index.js

@@ -0,0 +1,462 @@
+"use strict";
+/**
+ * Neo4j graph dialect — Cypher generation for the ORM builder API.
+ *
+ * Maps the ORM model API onto Cypher: node labels for tables, `MATCH`/
+ * `CREATE`/`MERGE`/`SET`/`DELETE` for CRUD, relationships for associations,
+ * and variable-length patterns for traversals. Everything is parameterized
+ * (`$p0`, `$props`, ...). Users never hand-write Cypher for standard
+ * operations.
+ *
+ * The `neo4j-driver` package is loaded lazily so importing this module never
+ * forces the optional dependency; a pre-built driver can be injected via
+ * `options.client` for tests/connection reuse.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Neo4jGraphDialect = void 0;
+const index_1 = require("../../errors/index");
+const types_1 = require("../../types");
+const base_graph_dialect_1 = require("../base-graph-dialect");
+const types_2 = require("../types");
+function stripUndefined(data) {
+    const out = {};
+    for (const [k, v] of Object.entries(data)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+/** Translate a SQL LIKE pattern into a Java/Cypher regex for `=~`. */
+function likeToRegex(pattern, caseInsensitive = false) {
+    const escaped = String(pattern).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = escaped.replace(/%/g, '.*').replace(/_/g, '.');
+    return `${caseInsensitive ? '(?i)' : ''}${regex}`;
+}
+class Neo4jGraphDialect extends base_graph_dialect_1.BaseGraphDialect {
+    constructor(options = {}) {
+        super(options);
+        this.name = 'neo4j';
+        this.library = 'neo4j-driver';
+        this.driver = null;
+        this.txns = new Map();
+        this.dialectName = 'neo4j';
+    }
+    get defaultNodeVar() {
+        return 'n';
+    }
+    // -------------------------------------------------------------------
+    // Connection lifecycle
+    // -------------------------------------------------------------------
+    async connect() {
+        if (this._connected && this.driver)
+            return;
+        try {
+            let driver = this.options.client;
+            if (!driver) {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const neo4j = require('neo4j-driver');
+                const url = this.options.url || `bolt://${this.options.host || 'localhost'}:${this.options.port || 7687}`;
+                const auth = this.options.username !== undefined
+                    ? neo4j.auth.basic(this.options.username, this.options.password || '')
+                    : undefined;
+                driver = neo4j.driver(url, auth, this.options.driverOptions);
+            }
+            // Fail fast on bad connection details.
+            if (typeof driver.verifyConnectivity === 'function') {
+                await driver.verifyConnectivity();
+            }
+            this.driver = driver;
+            this._connection = driver;
+            this._connected = true;
+        }
+        catch (error) {
+            this.driver = null;
+            this._connection = null;
+            this._connected = false;
+            throw new index_1.ConnectionError('Failed to connect to Neo4j', {
+                parent: error instanceof Error ? error : undefined,
+                database: this.options.database,
+            });
+        }
+    }
+    async disconnect() {
+        const driver = this.driver;
+        this.driver = null;
+        this._connection = null;
+        this._connected = false;
+        if (driver && typeof driver.close === 'function') {
+            await driver.close();
+        }
+    }
+    requireDriver() {
+        if (!this.driver || !this._connected) {
+            throw new index_1.ConnectionError('Neo4jGraphDialect is not connected. Call connect() first.', {
+                database: this.options.database,
+            });
+        }
+        return this.driver;
+    }
+    async query(statement, options) {
+        const params = options?.bind || {};
+        const txId = options?.transaction?.id;
+        try {
+            let records;
+            if (txId && this.txns.has(txId)) {
+                const res = await this.txns.get(txId).tx.run(statement, params);
+                records = res.records;
+            }
+            else {
+                const driver = this.requireDriver();
+                const session = driver.session(this.options.database ? { database: this.options.database } : undefined);
+                try {
+                    const res = await session.run(statement, params);
+                    records = res.records;
+                }
+                finally {
+                    await session.close();
+                }
+            }
+            const rows = records.map((r) => (typeof r.toObject === 'function' ? r.toObject() : r));
+            return { rows, rowCount: rows.length, fields: [] };
+        }
+        catch (error) {
+            throw new index_1.DatabaseError('Neo4j query failed', {
+                code: 'QUERY_ERROR',
+                parent: error instanceof Error ? error : undefined,
+                original: error instanceof Error ? error.message : String(error),
+                sql: statement,
+            });
+        }
+    }
+    async getDatabaseVersion() {
+        try {
+            const res = await this.query('CALL dbms.components() YIELD versions RETURN versions[0] AS version');
+            return String(res.rows[0]?.version ?? 'unknown');
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    // -------------------------------------------------------------------
+    // Transactions
+    // -------------------------------------------------------------------
+    async startTransaction(options) {
+        const driver = this.requireDriver();
+        const session = driver.session(this.options.database ? { database: this.options.database } : undefined);
+        const tx = session.beginTransaction();
+        const transaction = new types_1.Transaction(options);
+        this.txns.set(transaction.id, { session, tx });
+        return transaction;
+    }
+    async commitTransaction(transaction) {
+        const entry = this.txns.get(transaction.id);
+        if (!entry)
+            return;
+        try {
+            await entry.tx.commit();
+        }
+        finally {
+            await entry.session.close();
+            this.txns.delete(transaction.id);
+        }
+    }
+    async rollbackTransaction(transaction) {
+        const entry = this.txns.get(transaction.id);
+        if (!entry)
+            return;
+        try {
+            await entry.tx.rollback();
+        }
+        finally {
+            await entry.session.close();
+            this.txns.delete(transaction.id);
+        }
+    }
+    // -------------------------------------------------------------------
+    // Predicate rendering
+    // -------------------------------------------------------------------
+    renderPredicate(pred, ctx) {
+        switch (pred.kind) {
+            case 'true':
+                return 'true';
+            case 'and':
+                return pred.items.length
+                    ? `(${pred.items.map((p) => this.renderPredicate(p, ctx)).join(' AND ')})`
+                    : 'true';
+            case 'or':
+                return pred.items.length
+                    ? `(${pred.items.map((p) => this.renderPredicate(p, ctx)).join(' OR ')})`
+                    : 'true';
+            case 'not':
+                return `NOT (${this.renderPredicate(pred.item, ctx)})`;
+            case 'cmp':
+                return this.renderComparison(pred, ctx);
+        }
+    }
+    renderComparison(pred, ctx) {
+        const ref = `${ctx.nodeVar}.${(0, types_2.safeIdent)(pred.field)}`;
+        const p = (v) => `$${ctx.params.add(v)}`;
+        switch (pred.op) {
+            case 'eq':
+                return `${ref} = ${p(pred.value)}`;
+            case 'ne':
+                return `${ref} <> ${p(pred.value)}`;
+            case 'gt':
+                return `${ref} > ${p(pred.value)}`;
+            case 'gte':
+                return `${ref} >= ${p(pred.value)}`;
+            case 'lt':
+                return `${ref} < ${p(pred.value)}`;
+            case 'lte':
+                return `${ref} <= ${p(pred.value)}`;
+            case 'in':
+                return `${ref} IN ${p(pred.value)}`;
+            case 'notIn':
+                return `NOT ${ref} IN ${p(pred.value)}`;
+            case 'isNull':
+                return `${ref} IS NULL`;
+            case 'isNotNull':
+                return `${ref} IS NOT NULL`;
+            case 'like':
+                return `${ref} =~ ${p(likeToRegex(String(pred.value)))}`;
+            case 'notLike':
+                return `NOT ${ref} =~ ${p(likeToRegex(String(pred.value)))}`;
+            case 'iLike':
+            case 'notILike': {
+                const rx = `${ref} =~ ${p(likeToRegex(String(pred.value), true))}`;
+                return pred.op === 'notILike' ? `NOT ${rx}` : rx;
+            }
+            case 'startsWith':
+                return `${ref} STARTS WITH ${p(pred.value)}`;
+            case 'notStartsWith':
+                return `NOT ${ref} STARTS WITH ${p(pred.value)}`;
+            case 'endsWith':
+                return `${ref} ENDS WITH ${p(pred.value)}`;
+            case 'notEndsWith':
+                return `NOT ${ref} ENDS WITH ${p(pred.value)}`;
+            case 'substring':
+                return `${ref} CONTAINS ${p(pred.value)}`;
+            case 'notSubstring':
+                return `NOT ${ref} CONTAINS ${p(pred.value)}`;
+            case 'regexp':
+                return `${ref} =~ ${p(pred.value)}`;
+            case 'notRegexp':
+                return `NOT ${ref} =~ ${p(pred.value)}`;
+            case 'between': {
+                const [lo, hi] = Array.isArray(pred.value) ? pred.value : [undefined, undefined];
+                return `(${ref} >= ${p(lo)} AND ${ref} <= ${p(hi)})`;
+            }
+            case 'notBetween': {
+                const [lo, hi] = Array.isArray(pred.value) ? pred.value : [undefined, undefined];
+                return `NOT (${ref} >= ${p(lo)} AND ${ref} <= ${p(hi)})`;
+            }
+            default:
+                return `${ref} = ${p(pred.value)}`;
+        }
+    }
+    where(where, nodeVar, params) {
+        const sql = this.renderPredicate((0, types_2.normalizeWhere)(where), { nodeVar, params });
+        return sql && sql !== 'true' ? sql : '';
+    }
+    // -------------------------------------------------------------------
+    // Codegen
+    // -------------------------------------------------------------------
+    compileMatch(spec) {
+        const params = new types_2.ParamBag();
+        const v = this.defaultNodeVar;
+        const label = (0, types_2.safeIdent)(spec.label);
+        let text = `MATCH (${v}:${label})`;
+        const whereSql = this.where(spec.where, v, params);
+        if (whereSql)
+            text += `\nWHERE ${whereSql}`;
+        const includeReturns = [];
+        for (const step of spec.include || []) {
+            const alias = (0, types_2.safeIdent)(step.as || step.targetLabel || step.edgeLabel);
+            const edge = (0, types_2.safeIdent)(step.edgeLabel);
+            const targetLabel = step.targetLabel ? `:${(0, types_2.safeIdent)(step.targetLabel)}` : '';
+            const rel = step.direction === 'in' ? `<-[:${edge}]-` : `-[:${edge}]->`;
+            text += `\nOPTIONAL MATCH (${v})${rel}(${alias}${targetLabel})`;
+            const stepWhere = this.where(step.where, alias, params);
+            if (stepWhere)
+                text += ` WHERE ${stepWhere}`;
+            includeReturns.push(`collect(DISTINCT ${alias}) AS ${alias}`);
+        }
+        if (spec.count) {
+            text += `\nRETURN count(${v}) AS count`;
+            return { text, params: params.params };
+        }
+        const attrs = Array.isArray(spec.attributes) ? spec.attributes : undefined;
+        const projection = attrs && attrs.length
+            ? `${v}{${attrs.map((a) => `.${(0, types_2.safeIdent)(a)}`).join(', ')}}`
+            : v;
+        const distinct = spec.distinct ? 'DISTINCT ' : '';
+        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(', ')}`;
+        }
+        if (spec.offset !== undefined && spec.offset !== null && String(spec.offset) !== '') {
+            text += `\nSKIP ${Number(spec.offset)}`;
+        }
+        if (spec.limit !== undefined && spec.limit !== null && String(spec.limit) !== '') {
+            text += `\nLIMIT ${Number(spec.limit)}`;
+        }
+        return { text, params: params.params };
+    }
+    compileCreateNode(label, data) {
+        const params = new types_2.ParamBag('props');
+        const name = params.add(stripUndefined(data));
+        return {
+            text: `CREATE (n:${(0, types_2.safeIdent)(label)} $${name})\nRETURN n`,
+            params: params.params,
+        };
+    }
+    compileUpdateNodes(label, where, values) {
+        const params = new types_2.ParamBag();
+        const v = this.defaultNodeVar;
+        let text = `MATCH (${v}:${(0, types_2.safeIdent)(label)})`;
+        const whereSql = this.where(where, v, params);
+        if (whereSql)
+            text += `\nWHERE ${whereSql}`;
+        const setValues = stripUndefined(values);
+        const removeFields = Object.keys(values).filter((k) => values[k] === undefined);
+        const clauses = [];
+        if (Object.keys(setValues).length) {
+            const pname = params.add(setValues);
+            clauses.push(`SET ${v} += $${pname}`);
+        }
+        if (removeFields.length) {
+            clauses.push(`REMOVE ${removeFields.map((f) => `${v}.${(0, types_2.safeIdent)(f)}`).join(', ')}`);
+        }
+        if (clauses.length)
+            text += `\n${clauses.join('\n')}`;
+        text += `\nRETURN ${v}`;
+        return { text, params: params.params };
+    }
+    compileDeleteNodes(label, where, detach) {
+        const params = new types_2.ParamBag();
+        const v = this.defaultNodeVar;
+        let text = `MATCH (${v}:${(0, types_2.safeIdent)(label)})`;
+        const whereSql = this.where(where, v, params);
+        if (whereSql)
+            text += `\nWHERE ${whereSql}`;
+        text += `\n${detach ? 'DETACH DELETE' : 'DELETE'} ${v}`;
+        return { text, params: params.params };
+    }
+    compileUpsertNode(label, data, conflictKeys) {
+        const params = new types_2.ParamBag();
+        const v = this.defaultNodeVar;
+        const keys = conflictKeys.length ? conflictKeys : ['id'];
+        const mergeProps = keys
+            .map((k) => `${(0, types_2.safeIdent)(k)}: $${params.add(data[k])}`)
+            .join(', ');
+        const pname = params.add(stripUndefined(data));
+        return {
+            text: `MERGE (${v}:${(0, types_2.safeIdent)(label)} {${mergeProps}})\nSET ${v} += $${pname}\nRETURN ${v}`,
+            params: params.params,
+        };
+    }
+    compileIncrement(label, fields, where, by) {
+        const params = new types_2.ParamBag();
+        const v = this.defaultNodeVar;
+        let text = `MATCH (${v}:${(0, types_2.safeIdent)(label)})`;
+        const whereSql = this.where(where, v, params);
+        if (whereSql)
+            text += `\nWHERE ${whereSql}`;
+        const map = typeof fields === 'string'
+            ? { [fields]: by }
+            : Array.isArray(fields)
+                ? Object.fromEntries(fields.map((f) => [f, by]))
+                : fields;
+        const sets = Object.entries(map).map(([f, amt]) => {
+            const ref = `${v}.${(0, types_2.safeIdent)(f)}`;
+            return `${ref} = coalesce(${ref}, 0) + $${params.add(amt)}`;
+        });
+        text += `\nSET ${sets.join(', ')}\nRETURN ${v}`;
+        return { text, params: params.params };
+    }
+    compileCreateEdge(spec) {
+        const params = new types_2.ParamBag();
+        let text = `MATCH (a:${(0, types_2.safeIdent)(spec.fromLabel)})`;
+        const fromWhere = this.where(spec.fromWhere, 'a', params);
+        if (fromWhere)
+            text += ` WHERE ${fromWhere}`;
+        text += `\nMATCH (b:${(0, types_2.safeIdent)(spec.toLabel)})`;
+        const toWhere = this.where(spec.toWhere, 'b', params);
+        if (toWhere)
+            text += ` WHERE ${toWhere}`;
+        text += `\nMERGE (a)-[r:${(0, types_2.safeIdent)(spec.edgeLabel)}]->(b)`;
+        if (spec.props && Object.keys(spec.props).length) {
+            text += `\nSET r += $${params.add(stripUndefined(spec.props))}`;
+        }
+        text += `\nRETURN r`;
+        return { text, params: params.params };
+    }
+    compileTraverse(spec) {
+        const params = new types_2.ParamBag();
+        const v = this.defaultNodeVar;
+        let text = `MATCH (${v}:${(0, types_2.safeIdent)(spec.label)})`;
+        const startWhere = this.where(spec.where, v, params);
+        if (startWhere)
+            text += `\nWHERE ${startWhere}`;
+        const edge = spec.edgeLabel ? `:${(0, types_2.safeIdent)(spec.edgeLabel)}` : '';
+        const min = spec.minDepth ?? 1;
+        const max = spec.maxDepth ?? 1;
+        const varLen = min === 1 && max === 1 ? '' : `*${min}..${max}`;
+        const targetLabel = spec.targetLabel ? `:${(0, types_2.safeIdent)(spec.targetLabel)}` : '';
+        const rel = spec.direction === 'in'
+            ? `<-[${edge}${varLen}]-`
+            : spec.direction === 'both'
+                ? `-[${edge}${varLen}]-`
+                : `-[${edge}${varLen}]->`;
+        text += `\nMATCH (${v})${rel}(m${targetLabel})`;
+        const targetWhere = this.where(spec.targetWhere, 'm', params);
+        if (targetWhere)
+            text += `\nWHERE ${targetWhere}`;
+        text += `\nRETURN DISTINCT m`;
+        if (spec.limit !== undefined)
+            text += `\nLIMIT ${Number(spec.limit)}`;
+        return { text, params: params.params };
+    }
+    compileCreateConstraint(label, fields, kind, name) {
+        const v = 'n';
+        const l = (0, types_2.safeIdent)(label);
+        const cname = (0, types_2.safeIdent)(name || `c_${label}_${fields.join('_')}`);
+        const props = fields.map((f) => `${v}.${(0, types_2.safeIdent)(f)}`);
+        let requirement;
+        if (kind === 'key') {
+            requirement = `(${props.join(', ')}) IS NODE KEY`;
+        }
+        else if (kind === 'exists') {
+            requirement = `${props[0]} IS NOT NULL`;
+        }
+        else {
+            requirement = props.length > 1 ? `(${props.join(', ')}) IS UNIQUE` : `${props[0]} IS UNIQUE`;
+        }
+        return {
+            text: `CREATE CONSTRAINT ${cname} IF NOT EXISTS FOR (${v}:${l}) REQUIRE ${requirement}`,
+            params: {},
+        };
+    }
+    compileDropConstraint(_label, name) {
+        return { text: `DROP CONSTRAINT ${(0, types_2.safeIdent)(name)} IF EXISTS`, params: {} };
+    }
+    compileCreateIndex(label, fields, name) {
+        const v = 'n';
+        const l = (0, types_2.safeIdent)(label);
+        const iname = (0, types_2.safeIdent)(name || `idx_${label}_${fields.join('_')}`);
+        const props = fields.map((f) => `${v}.${(0, types_2.safeIdent)(f)}`).join(', ');
+        return {
+            text: `CREATE INDEX ${iname} IF NOT EXISTS FOR (${v}:${l}) ON (${props})`,
+            params: {},
+        };
+    }
+    compileDropIndex(_label, name) {
+        return { text: `DROP INDEX ${(0, types_2.safeIdent)(name)} IF EXISTS`, params: {} };
+    }
+    compileShowLabels() {
+        return { text: 'CALL db.labels() YIELD label RETURN label', params: {} };
+    }
+}
+exports.Neo4jGraphDialect = Neo4jGraphDialect;
+exports.default = Neo4jGraphDialect;

package/dist/graph/types.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Shared types and helpers for the ORM's graph/object-database dialects
+ * (Neo4j, Gremlin/TinkerPop/Neptune, Dgraph).
+ *
+ * These live under `src/graph/` and are intentionally self-contained: the
+ * graph dialects reuse the SQL-shaped `Dialect` contract (so the same
+ * `Model` builder API drives them) but express everything as graph
+ * primitives — node labels, edges/relationships, and traversals — instead
+ * of tables and joins. Nothing here edits shared base files.
+ */
+import { DatabaseError } from '../errors/index';
+import type { WhereOptions } from '../types';
+/**
+ * Connection options accepted by every graph dialect. Superset of the
+ * SQL `DialectOptions` (host/port/database/username/password) plus a graph
+ * endpoint `url` and an escape hatch for injecting a pre-built driver/client
+ * (used by tests and connection reuse, mirroring the NoSQL stores).
+ */
+export interface GraphConnectionOptions {
+    /** Full endpoint URL, e.g. `bolt://localhost:7687`, `ws://host:8182/gremlin`, `http://localhost:8080`. */
+    url?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    username?: string;
+    password?: string;
+    /** Extra driver-specific options passed straight through. */
+    driverOptions?: Record<string, unknown>;
+    /** Pre-built native client/driver to use instead of constructing one. */
+    client?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * A compiled graph statement: the query text in the target graph language
+ * (Cypher / Gremlin / DQL) plus its named parameter bindings. All standard
+ * operations are parameterized — values never get string-interpolated into
+ * the statement text.
+ */
+export interface GraphStatement {
+    text: string;
+    params: Record<string, unknown>;
+}
+/**
+ * Canonical comparison operators, normalized from both the `Op.*` symbol
+ * operators and the `$and`/`$or`/`$not` string keys so each dialect only has
+ * to render one small, stable set.
+ */
+export type CanonOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'like' | 'notLike' | 'iLike' | 'notILike' | 'between' | 'notBetween' | 'isNull' | 'isNotNull' | 'startsWith' | 'notStartsWith' | 'endsWith' | 'notEndsWith' | 'substring' | 'notSubstring' | 'regexp' | 'notRegexp';
+/**
+ * Normalized WHERE predicate tree. Each dialect walks this and renders it in
+ * its own language rather than re-parsing the raw `WhereOptions`.
+ */
+export type GraphPredicate = {
+    kind: 'and';
+    items: GraphPredicate[];
+} | {
+    kind: 'or';
+    items: GraphPredicate[];
+} | {
+    kind: 'not';
+    item: GraphPredicate;
+} | {
+    kind: 'cmp';
+    field: string;
+    op: CanonOp;
+    value: unknown;
+} | {
+    kind: 'true';
+};
+/** ORM association kinds, mapped onto graph edges. */
+export type GraphAssociationType = 'hasMany' | 'hasOne' | 'belongsTo' | 'belongsToMany';
+/**
+ * How an ORM association becomes a graph edge. `hasMany`/`hasOne` become an
+ * OUTBOUND edge from the source node; `belongsTo` becomes an INBOUND edge
+ * (the inverse); `belongsToMany` becomes an OUTBOUND edge over the join
+ * relationship. The edge label defaults to a derived name but can be set
+ * explicitly.
+ */
+export interface GraphAssociationSpec {
+    type: GraphAssociationType;
+    /** Association name as used in `include`, e.g. `posts`. */
+    as: string;
+    /** Target node label, e.g. `Post`. */
+    target: string;
+    /** Relationship/edge type/label, e.g. `HAS_POST`. */
+    edgeLabel: string;
+    /** Edge direction from the source node's perspective. */
+    direction: 'out' | 'in';
+}
+/** Property/attribute definition for a node or edge model (schemaless-friendly). */
+export interface GraphPropertyDefinition {
+    type?: string;
+    unique?: boolean;
+    index?: boolean;
+    required?: boolean;
+    primaryKey?: boolean;
+}
+/** A node model: a labelled vertex type with optional property schema + associations. */
+export interface NodeModelDefinition {
+    label: string;
+    properties?: Record<string, GraphPropertyDefinition>;
+    /** Property used as the node's stable identity (defaults to `id`). */
+    primaryKey?: string;
+    associations?: GraphAssociationSpec[];
+}
+/** An edge model: a relationship type connecting two node labels. */
+export interface EdgeModelDefinition {
+    label: string;
+    from: string;
+    to: string;
+    properties?: Record<string, GraphPropertyDefinition>;
+}
+/** Direction of a graph traversal relative to the start node. */
+export type GraphTraversalDirection = 'out' | 'in' | 'both';
+/** A single hop / edge match used when building a traversal or `include`. */
+export interface GraphTraversalStep {
+    /** Edge label to traverse, e.g. `HAS_POST`. */
+    edgeLabel: string;
+    direction: GraphTraversalDirection;
+    /** Target node label reached by this hop, if known. */
+    targetLabel?: string;
+    /** Association name this hop represents (used as the result key). */
+    as?: string;
+    /** Filter applied to the reached nodes. */
+    where?: WhereOptions;
+}
+/** Spec for a variable-length / multi-hop traversal from a start node. */
+export interface GraphTraversalSpec {
+    /** Start node label. */
+    label: string;
+    /** Filter selecting the start node(s). */
+    where?: WhereOptions;
+    /** Single edge label (shorthand) or an explicit chain of steps. */
+    edgeLabel?: string;
+    direction?: GraphTraversalDirection;
+    targetLabel?: string;
+    /** Minimum traversal depth (1 = direct neighbours). Default 1. */
+    minDepth?: number;
+    /** Maximum traversal depth. Default 1. */
+    maxDepth?: number;
+    /** Filter applied to reached nodes. */
+    targetWhere?: WhereOptions;
+    limit?: number;
+}
+/** Options for a node find/match. */
+export interface NodeMatchSpec {
+    label: string;
+    where?: WhereOptions;
+    attributes?: string[] | {
+        include?: string[];
+        exclude?: string[];
+    };
+    order?: Array<[string, 'ASC' | 'DESC']> | string[];
+    limit?: number | string;
+    offset?: number | string;
+    /** Associations to co-fetch as graph walks. */
+    include?: GraphTraversalStep[];
+    /** Return only a count. */
+    count?: boolean;
+    /** DISTINCT results. */
+    distinct?: boolean;
+}
+/**
+ * Typed error thrown when a relational feature has no meaningful graph
+ * equivalent and cannot be emulated via traversal (e.g. arbitrary SQL joins
+ * on a pure graph, materialized views, row-level-security policies).
+ */
+export declare class GraphCapabilityError extends DatabaseError {
+    readonly feature: string;
+    readonly dialect: string;
+    constructor(feature: string, dialect: string);
+}
+/**
+ * Allocates unique, ordered parameter names and collects their values.
+ * Produces both a named-param map (for Cypher `$p0` / DQL `$p0` / Gremlin
+ * bindings) and, via {@link toArray}, a positional array for the SQL-shaped
+ * `{ sql, values }` return contract.
+ */
+export declare class ParamBag {
+    private readonly prefix;
+    private index;
+    readonly params: Record<string, unknown>;
+    private readonly names;
+    constructor(prefix?: string);
+    add(value: unknown): string;
+    toArray(): unknown[];
+}
+/**
+ * Normalize an ORM `WhereOptions` (mixing `Op.*` symbols, `$and`/`$or`/
+ * `$not`, and plain equality) into a {@link GraphPredicate} tree. Returns a
+ * `{ kind: 'true' }` node for an empty/absent filter.
+ */
+export declare function normalizeWhere(where?: WhereOptions | null): GraphPredicate;
+/**
+ * Derive a graph edge from an ORM association descriptor (as produced by
+ * `Model.hasMany`/`belongsTo`/etc.). Accepts a loose shape so it works with
+ * either the ORM's association objects or a plain {@link GraphAssociationSpec}.
+ */
+export declare function deriveAssociationEdge(assoc: {
+    associationType?: string;
+    type?: string;
+    as?: string;
+    target?: {
+        name?: string;
+        label?: string;
+    } | string;
+    edgeLabel?: string;
+    direction?: 'out' | 'in';
+}): GraphAssociationSpec;
+/** Default edge label for an association name, e.g. `posts` -> `HAS_POSTS`. */
+export declare function defaultEdgeLabel(as: string): string;
+/** Sanitize an identifier (label/property/edge) to a safe `[A-Za-z0-9_]` token. */
+export declare function safeIdent(name: string): string;