ts-prorm-orm 1.1.0

package/dist/nosql/neo4j/index.js

@@ -0,0 +1,450 @@
+"use strict";
+/**
+ * Neo4j store implementation.
+ *
+ * Neo4j is a graph database: data is modeled as labeled nodes and typed
+ * relationships (both carrying arbitrary properties) instead of rows in
+ * tables, and queried with Cypher instead of SQL. It has no `Dialect`-shaped
+ * `query(sql)`/identifier-escaping/DDL surface, so this class implements the
+ * minimal `NoSqlStore` marker interface and exposes Neo4j's real primitives
+ * — sessions, (managed and explicit) transactions, and raw parameterized
+ * Cypher — plus a thin layer of Cypher-generating convenience helpers for
+ * common node/relationship CRUD, rather than forcing a graph database into
+ * a `query(sql)` shape.
+ *
+ * Uses the official `neo4j-driver` (Bolt protocol) driver.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Neo4jStore = void 0;
+exports.intToNumber = intToNumber;
+const neo4j_driver_1 = __importDefault(require("neo4j-driver"));
+const errors_1 = require("../../errors");
+function wrapConnectionError(err, host) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return new errors_1.ConnectionError(`Unable to connect to Neo4j: ${parent.message}`, {
+        parent,
+        database: 'neo4j',
+        host,
+    });
+}
+function wrapDatabaseError(err, message) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    // Keep the `action` context but don't discard the real Neo4j error text
+    // (e.g. a Cypher syntax error, or a constraint violation) - append it so
+    // callers inspecting `err.message` still see what actually went wrong.
+    const combined = message ? `${message}: ${parent.message}` : parent.message;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+/**
+ * Unwrap a single Neo4j `Integer` (its 64-bit integer type, used for
+ * identities, counts, and any Cypher `INTEGER` value) into a JS `number`.
+ * Values outside `Number.MAX_SAFE_INTEGER` lose precision on this
+ * conversion - see "Known limitations" in the README for the lossless
+ * alternative (`neo4j-driver`'s `disableLosslessIntegers`/`useBigInt`
+ * config, passed through via `Neo4jStoreOptions.config`).
+ */
+function intToNumber(value) {
+    return value.toNumber();
+}
+/**
+ * Recursively convert a raw value coming back from the driver (an
+ * `Integer`, a `Node`, a `Relationship`, an array/map containing any of
+ * those, or a plain scalar) into plain JS values/objects. This is what
+ * turns `Record.toObject()` output into the `GraphNode`/`GraphRelationship`
+ * shapes used throughout this store.
+ */
+function mapValue(value) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (neo4j_driver_1.default.isInt(value)) {
+        return intToNumber(value);
+    }
+    if (neo4j_driver_1.default.isNode(value)) {
+        const node = value;
+        const mapped = {
+            elementId: node.elementId,
+            identity: intToNumber(node.identity),
+            labels: [...node.labels],
+            properties: mapValue(node.properties),
+        };
+        return mapped;
+    }
+    if (neo4j_driver_1.default.isRelationship(value)) {
+        const rel = value;
+        const mapped = {
+            elementId: rel.elementId,
+            identity: intToNumber(rel.identity),
+            type: rel.type,
+            startElementId: rel.startNodeElementId,
+            endElementId: rel.endNodeElementId,
+            start: intToNumber(rel.start),
+            end: intToNumber(rel.end),
+            properties: mapValue(rel.properties),
+        };
+        return mapped;
+    }
+    if (Array.isArray(value)) {
+        return value.map(mapValue);
+    }
+    if (typeof value === 'object') {
+        const out = {};
+        for (const [key, v] of Object.entries(value)) {
+            out[key] = mapValue(v);
+        }
+        return out;
+    }
+    return value;
+}
+/** Convert a single `Record` into a plain object, mapping every field's value (see `mapValue`). */
+function mapRecord(record) {
+    return mapValue(record.toObject());
+}
+/** Convert a `ResultSummary` into the plain-number `CypherSummary` shape. */
+function mapSummary(summary) {
+    const counters = summary.counters.updates();
+    return {
+        queryType: summary.queryType,
+        nodesCreated: counters.nodesCreated,
+        nodesDeleted: counters.nodesDeleted,
+        relationshipsCreated: counters.relationshipsCreated,
+        relationshipsDeleted: counters.relationshipsDeleted,
+        propertiesSet: counters.propertiesSet,
+        labelsAdded: counters.labelsAdded,
+        labelsRemoved: counters.labelsRemoved,
+    };
+}
+/** Build a Cypher label clause (`:Label1:Label2`) from a label or list of labels. */
+function labelClause(labels) {
+    if (!labels)
+        return '';
+    const list = Array.isArray(labels) ? labels : [labels];
+    return list.map((label) => `:${label}`).join('');
+}
+/** Build an `AND`-joined `WHERE` clause (`alias.k1 = $k1 AND alias.k2 = $k2`) from an equality-match object. */
+function whereClause(alias, where) {
+    const keys = Object.keys(where);
+    if (keys.length === 0)
+        return '';
+    return ` WHERE ${keys.map((key) => `${alias}.${key} = $${key}`).join(' AND ')}`;
+}
+/**
+ * `Neo4jStore` wraps a `neo4j-driver` `Driver` and exposes:
+ *  - raw parameterized Cypher (`run()`) - the general escape hatch,
+ *  - session management (`session()`),
+ *  - transaction functions with automatic retry (`executeRead()`/`executeWrite()`),
+ *  - explicit begin/commit/rollback transactions (`beginTransaction()`),
+ *  - and Cypher-generating node/relationship CRUD convenience helpers
+ *    (`createNode()`, `findNodes()`, `createRelationship()`, etc) built on
+ *    top of `run()` - these are thin Cypher generators, not a separate
+ *    query engine, so anything they don't cover is one `run()` call away.
+ */
+class Neo4jStore {
+    constructor(options) {
+        this.name = 'neo4j';
+        this.library = 'neo4j-driver';
+        this.driverInstance = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    resolveAuth() {
+        if (this.options.auth) {
+            return this.options.auth;
+        }
+        if (this.options.username !== undefined || this.options.password !== undefined) {
+            return neo4j_driver_1.default.auth.basic(this.options.username ?? '', this.options.password ?? '');
+        }
+        return undefined;
+    }
+    async connect() {
+        if (this.connected && this.driverInstance) {
+            return;
+        }
+        let candidate = null;
+        try {
+            candidate = neo4j_driver_1.default.driver(this.options.uri, this.resolveAuth(), this.options.config);
+            await candidate.verifyConnectivity(this.options.database ? { database: this.options.database } : undefined);
+            this.driverInstance = candidate;
+            this.connected = true;
+        }
+        catch (err) {
+            // Don't leak the failed driver's connection pool - we're about to
+            // drop our only reference to it.
+            if (candidate) {
+                await candidate.close().catch(() => undefined);
+            }
+            this.driverInstance = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.uri);
+        }
+    }
+    async disconnect() {
+        if (this.driverInstance) {
+            await this.driverInstance.close();
+            this.driverInstance = null;
+        }
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.driverInstance !== null;
+    }
+    /** Returns the underlying `neo4j-driver` `Driver` for anything not wrapped here. */
+    getClient() {
+        return this.requireDriver();
+    }
+    requireDriver() {
+        if (!this.driverInstance) {
+            throw new errors_1.ConnectionError('Not connected to Neo4j', { database: 'neo4j' });
+        }
+        return this.driverInstance;
+    }
+    // ---------------------------------------------------------------------
+    // Sessions
+    // ---------------------------------------------------------------------
+    /**
+     * Open a new `Session`. Sessions are lightweight and disposable - open
+     * one per logical unit of work and close it when done (`run()`,
+     * `executeRead()`/`executeWrite()`, and `beginTransaction()` all do this
+     * for you; call this directly only if you need the raw `Session`, e.g.
+     * for `session.run()`'s streaming `subscribe()` API).
+     */
+    session(options = {}) {
+        const driver = this.requireDriver();
+        return driver.session({
+            database: options.database ?? this.options.database,
+            defaultAccessMode: options.defaultAccessMode === 'READ' ? neo4j_driver_1.default.session.READ : neo4j_driver_1.default.session.WRITE,
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Raw Cypher (the general escape hatch)
+    // ---------------------------------------------------------------------
+    /**
+     * Run a single parameterized Cypher statement as an auto-commit query,
+     * on a session opened and closed for just this call. Always parameterize
+     * user-supplied values (`$name`, not string concatenation) - the driver
+     * sends `params` separately from the query text, the same protection
+     * bind parameters give you against SQL injection.
+     */
+    async run(cypher, params = {}, options = {}) {
+        const session = this.session(options);
+        try {
+            const result = await session.run(cypher, params);
+            return {
+                records: result.records.map((record) => mapRecord(record)),
+                keys: result.records.length > 0 ? result.records[0].keys.map(String) : [],
+                summary: mapSummary(result.summary),
+            };
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'Neo4j query failed');
+        }
+        finally {
+            await session.close();
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Transaction functions (automatic retry on transient errors)
+    // ---------------------------------------------------------------------
+    /**
+     * Run `work` inside a managed read transaction. The driver automatically
+     * retries `work` on transient errors (e.g. deadlocks, leader switches in
+     * a cluster) - `work` may run more than once, so it must be idempotent
+     * and side-effect-free outside of the transaction it's given.
+     */
+    async executeRead(work, options = {}) {
+        const session = this.session({ ...options, defaultAccessMode: 'READ' });
+        try {
+            return await session.executeRead(work);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'Neo4j executeRead failed');
+        }
+        finally {
+            await session.close();
+        }
+    }
+    /** Like `executeRead()`, but for a managed write transaction (`defaultAccessMode: 'WRITE'`). */
+    async executeWrite(work, options = {}) {
+        const session = this.session({ ...options, defaultAccessMode: 'WRITE' });
+        try {
+            return await session.executeWrite(work);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'Neo4j executeWrite failed');
+        }
+        finally {
+            await session.close();
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Explicit transactions (caller-driven begin/commit/rollback)
+    // ---------------------------------------------------------------------
+    /**
+     * Begin an explicit transaction spanning multiple `run()` calls, on a
+     * session held open until `commit()`/`rollback()`. Unlike
+     * `executeRead()`/`executeWrite()`, this is never retried automatically
+     * - use it when you need multiple round trips with logic in between, or
+     * full manual control over commit/rollback.
+     */
+    async beginTransaction(options = {}) {
+        const session = this.session(options);
+        let tx;
+        try {
+            tx = await session.beginTransaction();
+        }
+        catch (err) {
+            await session.close();
+            throw wrapConnectionError(err, this.options.uri);
+        }
+        let closed = false;
+        const finish = async (op) => {
+            try {
+                await tx[op]();
+            }
+            catch (err) {
+                throw wrapDatabaseError(err, `Neo4j transaction ${op} failed`);
+            }
+            finally {
+                closed = true;
+                await session.close();
+            }
+        };
+        return {
+            run: async (cypher, params = {}) => {
+                try {
+                    const result = await tx.run(cypher, params);
+                    return {
+                        records: result.records.map((record) => mapRecord(record)),
+                        keys: result.records.length > 0 ? result.records[0].keys.map(String) : [],
+                        summary: mapSummary(result.summary),
+                    };
+                }
+                catch (err) {
+                    throw wrapDatabaseError(err, 'Neo4j transaction run failed');
+                }
+            },
+            commit: () => finish('commit'),
+            rollback: () => finish('rollback'),
+            isOpen: () => !closed && tx.isOpen(),
+        };
+    }
+    // ---------------------------------------------------------------------
+    // Node CRUD (Cypher generated under the hood - see README)
+    // ---------------------------------------------------------------------
+    /** `CREATE (n:Label1:Label2) SET n = $properties RETURN n` */
+    async createNode(labels, properties = {}) {
+        const cypher = `CREATE (n${labelClause(labels)}) SET n = $properties RETURN n`;
+        const result = await this.run(cypher, { properties });
+        return result.records[0].n;
+    }
+    /** `MATCH (n) WHERE elementId(n) = $elementId RETURN n` */
+    async getNodeByElementId(elementId) {
+        const cypher = 'MATCH (n) WHERE elementId(n) = $elementId RETURN n';
+        const result = await this.run(cypher, { elementId });
+        return result.records[0]?.n ?? null;
+    }
+    /**
+     * `MATCH (n:Label) WHERE n.k1 = $k1 AND ... RETURN n [SKIP $skip] [LIMIT $limit]`
+     *
+     * `where` is an equality-only match on node properties (no operators,
+     * ranges, or `OR`) - use `run()` directly for anything more expressive.
+     */
+    async findNodes(labels = [], where = {}, options = {}) {
+        let cypher = `MATCH (n${labelClause(labels)})${whereClause('n', where)} RETURN n`;
+        const params = { ...where };
+        if (options.skip !== undefined) {
+            cypher += ' SKIP $skip';
+            params.skip = neo4j_driver_1.default.int(options.skip);
+        }
+        if (options.limit !== undefined) {
+            cypher += ' LIMIT $limit';
+            params.limit = neo4j_driver_1.default.int(options.limit);
+        }
+        const result = await this.run(cypher, params);
+        return result.records.map((record) => record.n);
+    }
+    /** `MATCH (n) WHERE elementId(n) = $elementId SET n += $properties RETURN n` (merges, does not replace, existing properties) */
+    async updateNode(elementId, properties) {
+        const cypher = 'MATCH (n) WHERE elementId(n) = $elementId SET n += $properties RETURN n';
+        const result = await this.run(cypher, { elementId, properties });
+        return result.records[0]?.n ?? null;
+    }
+    /**
+     * `MATCH (n) WHERE elementId(n) = $elementId [DETACH] DELETE n`
+     *
+     * Without `options.detach`, deleting a node that still has relationships
+     * fails (Neo4j refuses to leave dangling relationships) - the underlying
+     * error surfaces as a `DatabaseError`. Returns whether a node was
+     * actually deleted (based on the query's `nodesDeleted` counter).
+     */
+    async deleteNode(elementId, options = {}) {
+        const cypher = `MATCH (n) WHERE elementId(n) = $elementId ${options.detach ? 'DETACH DELETE n' : 'DELETE n'}`;
+        const result = await this.run(cypher, { elementId });
+        return result.summary.nodesDeleted > 0;
+    }
+    /** `MATCH (n:Label) WHERE ... RETURN count(n) AS count` */
+    async countNodes(labels = [], where = {}) {
+        const cypher = `MATCH (n${labelClause(labels)})${whereClause('n', where)} RETURN count(n) AS count`;
+        const result = await this.run(cypher, { ...where });
+        return result.records[0]?.count ?? 0;
+    }
+    // ---------------------------------------------------------------------
+    // Relationship CRUD
+    // ---------------------------------------------------------------------
+    /**
+     * `MATCH (a), (b) WHERE elementId(a) = $fromElementId AND elementId(b) = $toElementId`
+     * `CREATE (a)-[r:TYPE]->(b) SET r = $properties RETURN r`
+     */
+    async createRelationship(fromElementId, toElementId, type, properties = {}) {
+        const cypher = 'MATCH (a), (b) WHERE elementId(a) = $fromElementId AND elementId(b) = $toElementId ' +
+            `CREATE (a)-[r:${type}]->(b) SET r = $properties RETURN r`;
+        const result = await this.run(cypher, {
+            fromElementId,
+            toElementId,
+            properties,
+        });
+        if (result.records.length === 0) {
+            throw wrapDatabaseError(new Error(`fromElementId "${fromElementId}" or toElementId "${toElementId}" not found`), 'Neo4j createRelationship failed');
+        }
+        return result.records[0].r;
+    }
+    /** `MATCH ()-[r]->() WHERE elementId(r) = $elementId RETURN r` */
+    async getRelationshipByElementId(elementId) {
+        const cypher = 'MATCH (a)-[r]->(b) WHERE elementId(r) = $elementId RETURN r';
+        const result = await this.run(cypher, { elementId });
+        return result.records[0]?.r ?? null;
+    }
+    /**
+     * `MATCH (a)-[r:TYPE]->(b) WHERE r.k1 = $k1 AND ... RETURN r [SKIP $skip] [LIMIT $limit]`
+     *
+     * Omit `type` to match relationships of any type.
+     */
+    async findRelationships(type, where = {}, options = {}) {
+        let cypher = `MATCH (a)-[r${type ? `:${type}` : ''}]->(b)${whereClause('r', where)} RETURN r`;
+        const params = { ...where };
+        if (options.skip !== undefined) {
+            cypher += ' SKIP $skip';
+            params.skip = neo4j_driver_1.default.int(options.skip);
+        }
+        if (options.limit !== undefined) {
+            cypher += ' LIMIT $limit';
+            params.limit = neo4j_driver_1.default.int(options.limit);
+        }
+        const result = await this.run(cypher, params);
+        return result.records.map((record) => record.r);
+    }
+    /** `MATCH (a)-[r]->(b) WHERE elementId(r) = $elementId DELETE r` - returns whether a relationship was actually deleted. */
+    async deleteRelationship(elementId) {
+        const cypher = 'MATCH (a)-[r]->(b) WHERE elementId(r) = $elementId DELETE r';
+        const result = await this.run(cypher, { elementId });
+        return result.summary.relationshipsDeleted > 0;
+    }
+}
+exports.Neo4jStore = Neo4jStore;
+exports.default = Neo4jStore;