grafeo-ogm 1.0.0

package/dist/esm/compilers/fulltext.compiler.js

@@ -0,0 +1,250 @@
+import { OGMError } from '../errors';
+import { isFulltextLeaf, isFulltextIndexEntry, } from '../model';
+import { assertSafeIdentifier, escapeIdentifier } from '../utils/validation';
+/** Maximum recursion depth for nested fulltext logical operators */
+const MAX_DEPTH = 10;
+/**
+ * Compiles fulltext search input into Cypher CALL clauses using
+ * db.index.fulltext.queryNodes and db.index.fulltext.queryRelationships.
+ *
+ * Supports logical operators:
+ * - **Leaf (node index)**: `{ IndexName: { phrase, score? } }` → `queryNodes`
+ * - **Leaf (relationship index)**: `{ relField: { IndexName: { phrase, score? } } }` → `queryRelationships`
+ * - **OR**: `CALL { ... UNION ... }` combining multiple branches
+ * - **AND**: Sequential correlated subqueries with node identity matching
+ * - **NOT**: `WHERE NOT EXISTS { ... }` exclusion pattern (Neo4j 5+)
+ */
+export class FulltextCompiler {
+    constructor(schema) {
+        this.schema = schema;
+    }
+    /**
+     * Compile fulltext input to Cypher CALL clause(s).
+     * Handles flat leaves AND recursive OR/AND/NOT expressions.
+     */
+    compile(fulltext, nodeDef, nodeVar = 'n') {
+        assertSafeIdentifier(nodeVar, 'node variable');
+        const paramCounter = { count: 0 };
+        const result = this.compileNode(fulltext, nodeDef, nodeVar, paramCounter);
+        // For simple leaf inputs, normalize param names for backward compat
+        // with model.ts which references `$ft_phrase` and `$ft_score` in WHERE.
+        if (isFulltextLeaf(fulltext))
+            for (const key of Object.keys(result.params))
+                if (key.startsWith('ft_phrase_')) {
+                    result.params.ft_phrase = result.params[key];
+                    delete result.params[key];
+                    result.cypher = result.cypher.replace(`$${key}`, '$ft_phrase');
+                }
+                else if (key.startsWith('ft_score_')) {
+                    result.params.ft_score = result.params[key];
+                    delete result.params[key];
+                }
+        return result;
+    }
+    /**
+     * Compile fulltext input for a relationship index into a Cypher CALL clause.
+     * Uses db.index.fulltext.queryRelationships.
+     */
+    compileRelationship(fulltext, relIndex, relVar = 'r') {
+        assertSafeIdentifier(relVar, 'relationship variable');
+        const keys = Object.keys(fulltext);
+        if (keys.length === 0)
+            throw new OGMError('Fulltext input must contain at least one index entry');
+        const indexName = keys[0];
+        assertSafeIdentifier(indexName, 'fulltext index name');
+        const input = fulltext[indexName];
+        if (!input.phrase || input.phrase.trim().length === 0)
+            throw new OGMError('Fulltext phrase must not be empty');
+        if (relIndex.name !== indexName)
+            throw new OGMError(`Unknown relationship fulltext index "${indexName}". Expected "${relIndex.name}".`);
+        const lines = [
+            `CALL db.index.fulltext.queryRelationships('${indexName}', $ft_phrase)`,
+            `YIELD relationship AS ${relVar}, score`,
+        ];
+        const params = { ft_phrase: input.phrase };
+        const result = {
+            cypher: lines.join('\n'),
+            params,
+        };
+        if (input.score !== undefined) {
+            params.ft_score = input.score;
+            result.scoreThreshold = input.score;
+        }
+        return result;
+    }
+    // ---------------------------------------------------------------------------
+    // Private recursive compilation
+    // ---------------------------------------------------------------------------
+    compileNode(input, nodeDef, nodeVar, paramCounter, depth = 0) {
+        if (depth > MAX_DEPTH)
+            throw new OGMError(`Fulltext logical nesting exceeds maximum depth of ${MAX_DEPTH}`);
+        if (isFulltextLeaf(input))
+            return this.compileLeaf(input, nodeDef, nodeVar, paramCounter);
+        if ('OR' in input)
+            return this.compileOr(input.OR, nodeDef, nodeVar, paramCounter, depth + 1);
+        if ('AND' in input)
+            return this.compileAnd(input.AND, nodeDef, nodeVar, paramCounter, depth + 1);
+        if ('NOT' in input)
+            return this.compileNot(input.NOT, nodeDef, nodeVar, paramCounter, depth + 1);
+        throw new OGMError('Invalid fulltext input: must be a leaf, OR, AND, or NOT');
+    }
+    /**
+     * Compile a leaf entry. Two shapes:
+     * - Node index: `{ IndexName: { phrase, score? } }` — value has `phrase`
+     * - Relationship index: `{ relField: { IndexName: { phrase, score? } } }` — value is nested
+     */
+    compileLeaf(leaf, nodeDef, nodeVar, paramCounter) {
+        const keys = Object.keys(leaf);
+        if (keys.length === 0)
+            throw new OGMError('Fulltext input must contain at least one index entry');
+        const key = keys[0];
+        assertSafeIdentifier(key, 'fulltext index or relationship name');
+        const value = leaf[key];
+        // If value has `phrase`, it's a direct node index entry
+        if (isFulltextIndexEntry(value))
+            return this.compileNodeIndex(key, value, nodeDef, nodeVar, paramCounter);
+        // Otherwise it's a relationship field → nested index entry
+        return this.compileRelationshipIndex(key, value, nodeDef, nodeVar, paramCounter);
+    }
+    /** Compile a node-level fulltext index: `{ IndexName: { phrase, score? } }` */
+    compileNodeIndex(indexName, input, nodeDef, nodeVar, paramCounter) {
+        if (!input.phrase || input.phrase.trim().length === 0)
+            throw new OGMError('Fulltext phrase must not be empty');
+        const nodeIndex = nodeDef.fulltextIndexes.find((idx) => idx.name === indexName);
+        if (!nodeIndex)
+            throw new OGMError(`Unknown fulltext index "${indexName}" for node "${nodeDef.typeName}"`);
+        const paramName = `ft_phrase_${paramCounter.count++}`;
+        const params = { [paramName]: input.phrase };
+        const cypher = [
+            `CALL db.index.fulltext.queryNodes('${indexName}', $${paramName})`,
+            `YIELD node AS ${nodeVar}, score`,
+        ].join('\n');
+        const result = { cypher, params };
+        if (input.score !== undefined) {
+            const scoreName = `ft_score_${paramCounter.count - 1}`;
+            params[scoreName] = input.score;
+            result.scoreThreshold = input.score;
+        }
+        return result;
+    }
+    /**
+     * Compile a relationship fulltext index:
+     * `{ relFieldName: { IndexName: { phrase, score? } } }`
+     *
+     * Validates that the relationship field exists on the node and that the
+     * index belongs to its @relationshipProperties type.
+     */
+    compileRelationshipIndex(relFieldName, inner, nodeDef, nodeVar, paramCounter) {
+        // Validate relationship field exists on node
+        const relDef = nodeDef.relationships.get(relFieldName);
+        if (!relDef)
+            throw new OGMError(`Unknown relationship field "${relFieldName}" on node "${nodeDef.typeName}"`);
+        if (!relDef.properties)
+            throw new OGMError(`Relationship "${relFieldName}" on "${nodeDef.typeName}" has no @relationshipProperties`);
+        // Validate index exists on the relationship properties type
+        const relProps = this.schema.relationshipProperties.get(relDef.properties);
+        if (!relProps)
+            throw new OGMError(`@relationshipProperties type "${relDef.properties}" not found`);
+        const innerKeys = Object.keys(inner);
+        if (innerKeys.length === 0)
+            throw new OGMError('Relationship fulltext entry must contain an index name');
+        const indexName = innerKeys[0];
+        assertSafeIdentifier(indexName, 'fulltext index name');
+        const input = inner[indexName];
+        const ftIndex = (relProps.fulltextIndexes ?? []).find((idx) => idx.name === indexName);
+        if (!ftIndex)
+            throw new OGMError(`Unknown fulltext index "${indexName}" on @relationshipProperties "${relDef.properties}"`);
+        if (!input.phrase || input.phrase.trim().length === 0)
+            throw new OGMError('Fulltext phrase must not be empty');
+        const paramName = `ft_phrase_${paramCounter.count++}`;
+        const params = { [paramName]: input.phrase };
+        const cypher = [
+            `CALL db.index.fulltext.queryRelationships('${indexName}', $${paramName})`,
+            `YIELD relationship AS rel, score`,
+            `WITH startNode(rel) AS ${nodeVar}, score`,
+        ].join('\n');
+        const result = { cypher, params };
+        if (input.score !== undefined) {
+            const scoreName = `ft_score_${paramCounter.count - 1}`;
+            params[scoreName] = input.score;
+            result.scoreThreshold = input.score;
+        }
+        return result;
+    }
+    /**
+     * OR: wrap branches in `CALL { ... UNION ... }` with max(score) deduplication.
+     */
+    compileOr(branches, nodeDef, nodeVar, paramCounter, depth) {
+        if (branches.length === 0)
+            throw new OGMError('OR must contain at least one branch');
+        if (branches.length === 1)
+            return this.compileNode(branches[0], nodeDef, nodeVar, paramCounter, depth);
+        const allParams = {};
+        const unionBranches = [];
+        for (const branch of branches) {
+            const result = this.compileNode(branch, nodeDef, nodeVar, paramCounter, depth);
+            Object.assign(allParams, result.params);
+            unionBranches.push([
+                `  ${result.cypher.split('\n').join('\n  ')}`,
+                `  RETURN ${nodeVar}, score`,
+            ].join('\n'));
+        }
+        const cypher = [
+            `CALL {`,
+            unionBranches.join('\n  UNION\n'),
+            `}`,
+            `WITH ${nodeVar}, max(score) AS score`,
+        ].join('\n');
+        return { cypher, params: allParams };
+    }
+    /**
+     * AND: sequential correlated subqueries.
+     * First branch yields nodes, subsequent branches filter to matching nodes.
+     */
+    compileAnd(branches, nodeDef, nodeVar, paramCounter, depth) {
+        if (branches.length === 0)
+            throw new OGMError('AND must contain at least one branch');
+        if (branches.length === 1)
+            return this.compileNode(branches[0], nodeDef, nodeVar, paramCounter, depth);
+        const allParams = {};
+        const cypherParts = [];
+        // First branch: yields nodes normally
+        const first = this.compileNode(branches[0], nodeDef, nodeVar, paramCounter, depth);
+        Object.assign(allParams, first.params);
+        cypherParts.push(first.cypher);
+        // Subsequent branches: correlated subqueries that filter to matching nodes
+        for (let i = 1; i < branches.length; i++) {
+            const branch = this.compileNode(branches[i], nodeDef, 'm', paramCounter, depth);
+            Object.assign(allParams, branch.params);
+            cypherParts.push([
+                `CALL {`,
+                `  WITH ${nodeVar}`,
+                `  ${branch.cypher.split('\n').join('\n  ')}`,
+                `  WHERE m = ${nodeVar}`,
+                `  RETURN score`,
+                `}`,
+            ].join('\n'));
+        }
+        cypherParts.push(`WITH ${nodeVar}, score`);
+        const cypher = cypherParts.join('\n');
+        return { cypher, params: allParams };
+    }
+    /**
+     * NOT: produces a WHERE NOT EXISTS { ... } clause.
+     * When used standalone, wraps in a MATCH-all then filters out.
+     */
+    compileNot(inner, nodeDef, nodeVar, paramCounter, depth) {
+        const innerResult = this.compileNode(inner, nodeDef, 'excluded', paramCounter, depth);
+        const allParams = { ...innerResult.params };
+        const cypher = [
+            `MATCH (${nodeVar}:${escapeIdentifier(nodeDef.label)})`,
+            `WHERE NOT EXISTS {`,
+            `  ${innerResult.cypher.split('\n').join('\n  ')}`,
+            `  WHERE excluded = ${nodeVar}`,
+            `}`,
+            `WITH ${nodeVar}, 0 AS score`,
+        ].join('\n');
+        return { cypher, params: allParams };
+    }
+}
+//# sourceMappingURL=fulltext.compiler.js.map

package/dist/esm/compilers/fulltext.compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fulltext.compiler.js","sourceRoot":"","sources":["../../../src/compilers/fulltext.compiler.ts"],"names":[],"mappings":"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"}

package/dist/esm/compilers/mutation.compiler.d.ts

@@ -0,0 +1,126 @@
+import { NodeDefinition, SchemaMetadata } from '../schema/types';
+export interface MutationResult {
+    cypher: string;
+    params: Record<string, unknown>;
+}
+/**
+ * Compiles create, update, delete, and label mutations into Cypher + params.
+ */
+export declare class MutationCompiler {
+    private schema;
+    /**
+     * Cache of computed label strings per type name.
+     * Bounded by the number of node types in the schema (~50-100 entries).
+     */
+    private labelCache;
+    constructor(schema: SchemaMetadata);
+    /** Clear internal caches. Useful in tests to prevent cross-test pollution. */
+    clearCaches(): void;
+    private getCachedLabelString;
+    /**
+     * Generate CREATE Cypher for one or more nodes.
+     * Handles scalar properties, nested relationship creates, and connects.
+     */
+    compileCreate(inputs: Record<string, unknown>[], nodeDef: NodeDefinition, labels?: string[]): MutationResult;
+    /**
+     * Generate UPDATE Cypher (SET properties + connect/disconnect).
+     */
+    compileUpdate(_where: Record<string, unknown>, update: Record<string, unknown> | undefined, connect: Record<string, unknown> | undefined, disconnect: Record<string, unknown> | undefined, nodeDef: NodeDefinition, whereResult: {
+        cypher: string;
+        params: Record<string, unknown>;
+    }, labels?: string[], returnMode?: 'node' | 'count'): MutationResult;
+    /**
+     * Generate DELETE Cypher with optional cascade.
+     */
+    compileDelete(nodeDef: NodeDefinition, whereResult: {
+        cypher: string;
+        params: Record<string, unknown>;
+    }, deleteInput?: Record<string, unknown>): MutationResult;
+    /**
+     * Generate MERGE (upsert) Cypher with ON CREATE SET / ON MATCH SET.
+     * Scalar properties only — nested relationship ops are not supported.
+     */
+    compileMerge(where: Record<string, unknown>, create: Record<string, unknown>, update: Record<string, unknown>, nodeDef: NodeDefinition, labels?: string[]): MutationResult;
+    /**
+     * Generate SET/REMOVE labels Cypher.
+     */
+    compileSetLabels(nodeDef: NodeDefinition, whereResult: {
+        cypher: string;
+        params: Record<string, unknown>;
+    }, addLabels?: string[], removeLabels?: string[]): MutationResult;
+    /**
+     * Generate batch CREATE (or MERGE for skipDuplicates) Cypher via UNWIND.
+     * Scalar properties only — no nested relationship operations.
+     * Returns count of created nodes.
+     */
+    compileCreateMany(data: Record<string, unknown>[], nodeDef: NodeDefinition, skipDuplicates?: boolean, labels?: string[]): MutationResult;
+    private buildCreateProperties;
+    private buildCreateRelationships;
+    /**
+     * Process create/connect operations for a specific target node type.
+     * Used by buildCreateRelationships for both union-member and non-union targets.
+     */
+    private buildCreateRelationshipsForTarget;
+    private buildConnects;
+    private buildDisconnects;
+    /**
+     * Process nested relationship operations within an update input.
+     * Handles: create, connect, disconnect, update, and arrays of these.
+     */
+    private buildUpdateRelationships;
+    /**
+     * Operator suffixes supported in connect/disconnect WHERE conditions.
+     * Maps suffix → Cypher operator template (use %v for variable, %p for param).
+     */
+    private static readonly OPERATOR_SUFFIXES;
+    /**
+     * Parse a property key that may contain an operator suffix (e.g. `id_IN`, `name_CONTAINS`).
+     * Returns the base property name and the Cypher expression template.
+     */
+    private parseOperatorSuffix;
+    /**
+     * Build WHERE conditions for connect/disconnect operations.
+     * Handles operator suffixes (_IN, _NOT, _NOT_IN, _CONTAINS, etc.),
+     * NOT blocks, and relationship filters (_SOME, _NONE, _ALL, _SINGLE).
+     *
+     * @param targetNodeDef - Optional node definition for the target node.
+     *   Required to resolve relationship filters like `configurations_SOME`.
+     *   When omitted, relationship filters are silently skipped.
+     */
+    private buildNodeWhereConditions;
+    /**
+     * Build WHERE conditions from a connection-level WHERE spec.
+     * Handles `node`, `NOT`, `AND`, `OR` at the connection level.
+     *
+     * Connection WHERE format: `{ node: {...}, NOT: { node: {...} }, AND: [...], OR: [...] }`
+     */
+    private buildConnectionWhereConditions;
+    /** Counter for unique relationship filter variables within a single WHERE clause. */
+    private relFilterCounter;
+    /**
+     * Try to compile a relationship filter condition (_SOME, _NONE, _ALL, _SINGLE).
+     * Returns the Cypher expression string or null if the key is not a relationship filter.
+     */
+    private tryBuildRelationshipFilter;
+    /**
+     * Build a Cypher relationship pattern string.
+     *
+     * @param sourceVar - Cypher variable for the source node
+     * @param relDef - Relationship definition
+     * @param targetVar - Cypher variable for the target node (empty string for anonymous)
+     * @param relVar - Optional relationship variable (omit for anonymous `[:TYPE]`)
+     * @param targetLabel - Target label override. Pass explicit label, `'auto'` to use
+     *   `relDef.target`, or omit for no label on the target node.
+     */
+    private buildRelPattern;
+    private buildGeneratedIdClause;
+    private getCascadeVarName;
+    /**
+     * Check if any item in an array connect spec has relationship filters in its WHERE clause.
+     * Relationship filters require EXISTS subqueries which can't use UNWIND param references.
+     */
+    private arrayConnectHasRelationshipFilters;
+    private extractConnectWhereConditions;
+    private extractEdgeProperties;
+}
+//# sourceMappingURL=mutation.compiler.d.ts.map

package/dist/esm/compilers/mutation.compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation.compiler.d.ts","sourceRoot":"","sources":["../../../src/compilers/mutation.compiler.ts"],"names":[],"mappings":"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"}