grafeo-ogm 2.5.4 → 2.6.1

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

@@ -4,6 +4,7 @@ import { NO_ROOT_POLICY } from '../policy/types';
 import { buildRelPattern, getTargetLabelString, resolveTargetDef, } from '../schema/utils';
 import { assertSafeIdentifier, assertSafeLabel, assertSafePropertyName, escapeIdentifier, isPlainObject, mergeParams, } from '../utils/validation';
 import { coerceWriteValue, resolveDefaultWriteValue, wrapListItemExpr, wrapWhereParam, wrapWriteExpr, } from '../utils/write-coercion';
+import { lenientStrictMode } from '../utils/strict-mode';
 import { WhereCompiler } from './where.compiler';
 /** The root node `n` of an update — the pre-2.4.8 names, unprefixed. */
 const TOP_SCOPE = {
@@ -60,6 +61,7 @@ export class MutationCompiler {
         this.narrowedRelDefs = new WeakSet();
         this.logger = options?.logger;
         this.policyWhereCompiler = options?.whereCompiler;
+        this.strictMode = options?.strictMode ?? lenientStrictMode();
     }
     /**
      * Resolve and compile the TARGET type's `read` policy predicate for a
@@ -278,6 +280,68 @@ export class MutationCompiler {
             throw new OGMError(`Cannot resolve the target type "${relDef.target}" of relationship "${relDef.fieldName}".`);
         return targetNodeDef;
     }
+    /**
+     * v2.6.0 — keys of a connect / disconnect item that the compiler does not
+     * read. Pre-2.6.0 (and still by default) they are ignored, so a typo such
+     * as `{ wehre: … }` compiles to an item with NO filter: a connect links
+     * every target node, a disconnect unlinks every related one. Default: one
+     * warning per OGM; strict: `OGMError`, like an unknown write field.
+     */
+    checkLinkItemKeys(item, kind, relDef) {
+        const allowed = kind === 'connect' ? CONNECT_ITEM_KEYS : DISCONNECT_ITEM_KEYS;
+        const unknown = Object.keys(item).filter((k) => item[k] !== undefined && !allowed.has(k));
+        if (unknown.length === 0)
+            return;
+        const list = unknown.map((k) => `"${k}"`).join(', ');
+        const allowedList = [...allowed].map((k) => `"${k}"`).join(', ');
+        if (this.strictMode.strict)
+            throw new OGMError(`Unknown key(s) ${list} in a ${kind} item on "${relDef.fieldName}". Allowed: ${allowedList}.`);
+        const unfiltered = item.where == null;
+        this.strictMode.warn(`${kind}-unknown-key`, `${relDef.fieldName}\u0000${unknown.join(',')}`, `Unknown key(s) ${list} in a ${kind} item on "${relDef.fieldName}" ` +
+            `${unknown.length > 1 ? 'are' : 'is'} ignored` +
+            (unfiltered
+                ? `; with no "where", the item ${kind === 'connect'
+                    ? `connects EVERY "${relDef.target}" node`
+                    : `unlinks EVERY related "${relDef.target}" node`}.`
+                : '.') +
+            ` Allowed: ${allowedList}.`, `throw an OGMError for unknown ${kind} item keys`);
+    }
+    /**
+     * v2.6.0 — `labels` on a MERGE path (upsert, createMany with
+     * skipDuplicates) are SET after the MERGE, so they are also added to an
+     * EXISTING node it matched. Default: unchanged, one warning; strict: the
+     * labels go in `ON CREATE SET`, onto newly created nodes only.
+     */
+    labelsOnMatchedNodes(nodeDef, op) {
+        const call = op === 'upsert' ? 'upsert' : 'createMany with skipDuplicates';
+        this.strictMode.warn('labels-on-matched-nodes', `${nodeDef.typeName}\u0000${op}`, `"labels" on ${call} (${nodeDef.typeName}) are added to every node the MERGE returns, so an existing node ` +
+            `it matched is relabelled too.`, 'apply "labels" only to the nodes it creates');
+    }
+    /**
+     * v2.6.0 — `edge` keys that are not properties of the relationship's
+     * `@relationshipProperties` type. Pre-2.6.0 (and still by default) each
+     * is written to the relationship as a stray property. Default: one
+     * warning per OGM; strict: `OGMError` (`Unknown field …`).
+     */
+    checkEdgeKeys(relDef, edge, input) {
+        if (!isPlainObject(edge))
+            return;
+        const declared = relDef.properties
+            ? this.schema.relationshipProperties.get(relDef.properties)?.properties
+            : undefined;
+        for (const key of Object.keys(edge)) {
+            if (edge[key] === undefined || declared?.has(key))
+                continue;
+            const owner = relDef.properties
+                ? `the relationship properties type "${relDef.properties}"`
+                : `the relationship, which declares no @relationshipProperties`;
+            if (this.strictMode.strict)
+                throw new OGMError(`Unknown field "${key}" in the edge input (${input}) of "${relDef.fieldName}": it is not a property of ` +
+                    `${owner}. Declare it in the schema, or fix the key.`);
+            this.strictMode.warn('edge-unknown-key', `${relDef.fieldName}\u0000${key}`, `Unknown field "${key}" in the edge input of "${relDef.fieldName}" is not a property of ${owner}; ` +
+                `it is written to the relationship as a stray property.`, `throw an OGMError for unknown edge fields`);
+        }
+    }
     /**
      * Generate CREATE Cypher for one or more nodes.
      * Handles scalar properties, nested relationship creates, and connects.
@@ -532,8 +596,14 @@ export class MutationCompiler {
     /**
      * Generate MERGE (upsert) Cypher with ON CREATE SET / ON MATCH SET.
      * Scalar properties only — nested relationship ops are not supported.
+     *
+     * v2.6.1 — `updateGuard` is the root type's `update` row filter on `n`
+     * (compiled by the caller with `preserveVars: ['__matched']`). When it
+     * is non-empty, an EXISTING node is updated only when it passes the
+     * guard, exactly like a direct `update`; one that fails it is left
+     * untouched and no row is returned. See `buildGuardedMerge`.
      */
-    compileMerge(where, create, update, nodeDef, labels) {
+    compileMerge(where, create, update, nodeDef, labels, updateGuard) {
         const labelStr = this.getCachedLabelString(nodeDef);
         const lines = [];
         const params = {};
@@ -571,6 +641,19 @@ export class MutationCompiler {
         if (mergeProps.length === 0)
             throw new OGMError(`upsert requires at least one scalar property in "where" for MERGE key: ` +
                 `an @id or @unique field of ${nodeDef.typeName}.`);
+        // v2.6.0 — MERGE matches ALL its keys together, so `{ id, email }`
+        // misses a node that has the email under another id and creates a
+        // duplicate beside it (or fails on the unique constraint). Default:
+        // compiled as before, with one warning; strict: exactly one key.
+        if (mergeKeyNames.length > 1) {
+            const keys = mergeKeyNames.map((k) => `"${k}"`).join(', ');
+            if (this.strictMode.strict)
+                throw new OGMError(`upsert "where" must name exactly one @id / @unique field of ${nodeDef.typeName}; got ${keys}. ` +
+                    `MERGE matches all of them together, so a node that has one but not the others is not found ` +
+                    `and a duplicate is created. Pass a single unique key.`);
+            this.strictMode.warn('upsert-multiple-unique-keys', `${nodeDef.typeName}\u0000${mergeKeyNames.join(',')}`, `upsert on ${nodeDef.typeName} with several unique keys in "where" (${keys}) MERGEs on all of them ` +
+                `together: a node that has one but not the others is not matched and a duplicate is created.`, 'require exactly one unique key in an upsert "where"');
+        }
         lines.push(`MERGE (n:${labelStr} { ${mergeProps.join(', ')} })`);
         // ON CREATE SET — all properties from create input (scalar only)
         const createSets = [];
@@ -621,6 +704,11 @@ export class MutationCompiler {
                 continue;
             createSets.push(`n.${escapeIdentifier(propDef.name)} = randomUUID()`);
         }
+        // v2.6.0 — strict: runtime labels go on the node only when MERGE creates
+        // it (see `labelsOnMatchedNodes`).
+        const labelsOnCreate = this.strictMode.strict && labels && labels.length > 0;
+        if (labelsOnCreate)
+            createSets.push(`n:${labels.map((l) => assertSafeLabel(l)).join(':')}`);
         if (createSets.length > 0)
             lines.push(`ON CREATE SET ${createSets.join(', ')}`);
         // ON MATCH SET — all properties from update input (scalar only)
@@ -641,12 +729,19 @@ export class MutationCompiler {
             updateSets.push(`n.${escapeIdentifier(key)} = ${valueExpr}`);
             params[paramName] = coerceWriteValue(value, propDef);
         }
-        if (updateSets.length > 0)
+        if (updateGuard !== undefined && updateGuard.cypher !== '') {
+            const guarded = buildGuardedMerge(labelStr, mergeProps, updateGuard, updateSets, params);
+            lines.unshift(...guarded.before);
+            lines.push(...guarded.after);
+        }
+        else if (updateSets.length > 0)
             lines.push(`ON MATCH SET ${updateSets.join(', ')}`);
-        // Extra labels
-        if (labels && labels.length > 0) {
+        // Extra labels. v2.6.1 — with an update guard, the rows that reach this
+        // SET are the created node and an existing node that passed the guard.
+        if (labels && labels.length > 0 && !labelsOnCreate) {
             const validatedLabels = labels.map((l) => assertSafeLabel(l)).join(':');
             lines.push(`SET n:${validatedLabels}`);
+            this.labelsOnMatchedNodes(nodeDef, 'upsert');
         }
         lines.push('RETURN n');
         return { cypher: lines.join('\n'), params };
@@ -692,7 +787,15 @@ export class MutationCompiler {
      * Scalar properties only — no nested relationship operations.
      * Returns count of created nodes.
      */
-    compileCreateMany(data, nodeDef, skipDuplicates, labels) {
+    compileCreateMany(data, nodeDef, skipDuplicates, labels, 
+    /**
+     * v2.6.1 — the root type's `update` row filter on `n`. With
+     * `skipDuplicates` and default-mode `labels`, an EXISTING node the
+     * MERGE matched is relabelled only when it passes this guard (a label
+     * change is an update, as `setLabels` enforces); created nodes get the
+     * labels in `ON CREATE SET`.
+     */
+    updateGuard) {
         if (data.length === 0)
             return { cypher: 'RETURN 0 AS count', params: {} };
         const labelStr = this.getCachedLabelString(nodeDef);
@@ -765,6 +868,12 @@ export class MutationCompiler {
         });
         params.items = sanitizedItems;
         lines.push('UNWIND $items AS item');
+        const guardedLabels = Boolean(skipDuplicates) &&
+            !this.strictMode.strict &&
+            labels !== undefined &&
+            labels.length > 0 &&
+            updateGuard !== undefined &&
+            updateGuard.cypher !== '';
         if (skipDuplicates) {
             // MERGE key: the unique/id fields EVERY item supplies — an item
             // missing one would MERGE on null, which Neo4j rejects.
@@ -796,6 +905,13 @@ export class MutationCompiler {
                 onCreateSets.push(`n.${escapeIdentifier(propDef.name)} = ${wrapWriteExpr(`$${paramName}`, bound, propDef)}`);
                 params[paramName] = bound;
             }
+            // v2.6.0 — strict: labels only on the nodes MERGE creates.
+            // v2.6.1 — also with an update guard: the matched nodes are
+            // relabelled below, only where the guard passes.
+            if ((this.strictMode.strict || guardedLabels) &&
+                labels &&
+                labels.length > 0)
+                onCreateSets.push(`n:${labels.map((l) => assertSafeLabel(l)).join(':')}`);
             if (onCreateSets.length > 0)
                 lines.push(`ON CREATE SET ${onCreateSets.join(', ')}`);
         }
@@ -815,9 +931,26 @@ export class MutationCompiler {
             lines.push(`CREATE (n:${labelStr} { ${propParts.join(', ')} })`);
         }
         // Extra labels
-        if (labels && labels.length > 0) {
+        if (guardedLabels) {
+            // v2.6.1 — matched nodes are relabelled only where the update guard
+            // passes. Pre-2.6.1 `SET n:<labels>` ran on every node the MERGE
+            // returned, so an existing node the context could not update was
+            // relabelled. FOREACH keeps one row per item (invariant 2).
+            const validatedLabels = labels.map((l) => assertSafeLabel(l)).join(':');
+            mergeParams(params, updateGuard.params);
+            lines.push('WITH n');
+            if (updateGuard.preludes && updateGuard.preludes.length > 0)
+                lines.push(...updateGuard.preludes);
+            lines.push(`FOREACH (__l IN CASE WHEN ${updateGuard.cypher} THEN [1] ELSE [] END | SET n:${validatedLabels})`);
+            this.labelsOnMatchedNodes(nodeDef, 'createMany');
+        }
+        else if (labels &&
+            labels.length > 0 &&
+            !(skipDuplicates && this.strictMode.strict)) {
             const validatedLabels = labels.map((l) => assertSafeLabel(l)).join(':');
             lines.push(`SET n:${validatedLabels}`);
+            if (skipDuplicates)
+                this.labelsOnMatchedNodes(nodeDef, 'createMany');
         }
         lines.push('RETURN count(n) AS count');
         return { cypher: lines.join('\n'), params };
@@ -967,6 +1100,7 @@ export class MutationCompiler {
                 mergeParams(params, propParams);
                 lines.push(`CREATE ${relPattern}`);
                 // Set edge properties if present
+                this.checkEdgeKeys(relDef, edgeInput, 'nested create');
                 if (edgeInput && Object.keys(edgeInput).length > 0) {
                     const relVar = `r_edge_${startCounter + counter - 1}`;
                     // Re-match the relationship to set edge props
@@ -1105,6 +1239,11 @@ export class MutationCompiler {
                         scope,
                     }));
             else {
+                // Every item is a plain object here (fast-path eligibility).
+                for (const item of spec) {
+                    this.checkLinkItemKeys(item, 'connect', relDef);
+                    this.checkEdgeKeys(relDef, item.edge, 'connect');
+                }
                 const targetVar = `${varPrefix}target`;
                 const relVar = `${varPrefix}r`;
                 const targetLabelStr = this.getCachedLabelString(targetNodeDef);
@@ -1231,6 +1370,8 @@ export class MutationCompiler {
         // compiling it would MATCH, and link, every target node.
         if (!isPlainObject(connectSpec))
             throw new OGMError(`A connect item on "${relDef.fieldName}" must be an object such as { where: { node: { … } } }; got ${connectSpec === null ? 'null' : typeof connectSpec}.`);
+        this.checkLinkItemKeys(connectSpec, 'connect', relDef);
+        this.checkEdgeKeys(relDef, connectSpec.edge, 'connect');
         const lines = [];
         const whereSpec = connectSpec.where;
         const edgeInput = connectSpec.edge;
@@ -1372,21 +1513,25 @@ export class MutationCompiler {
                 const predicate = targetNodeDef
                     ? this.buildTargetPolicyPredicate(targetNodeDef, blanketTarget, params, policyContext, paramCounter)
                     : undefined;
+                const { labelRaw, labelPredicate } = this.blanketRestriction(relDef, targetNodeDef, blanketTarget);
                 const pattern = buildRelPattern({
                     sourceVar,
                     relDef,
-                    targetVar: predicate ? blanketTarget : '',
+                    targetVar: predicate || labelPredicate ? blanketTarget : '',
                     edgeVar: relVar,
-                    targetLabelRaw: this.blanketTargetLabel(relDef),
+                    targetLabelRaw: labelRaw,
                 });
                 lines.push(`OPTIONAL MATCH ${pattern}`);
-                if (predicate)
-                    lines.push(`WHERE ${predicate}`);
+                const blanketConditions = [labelPredicate, predicate].filter(Boolean);
+                if (blanketConditions.length > 0)
+                    lines.push(`WHERE ${blanketConditions.join(' AND ')}`);
                 lines.push(`DELETE ${relVar}`);
             }
             else {
                 // Specific disconnect with conditions
                 const disconnectSpec = item;
+                if (isPlainObject(disconnectSpec))
+                    this.checkLinkItemKeys(disconnectSpec, 'disconnect', relDef);
                 const whereSpec = disconnectSpec.where;
                 const targetVar = `${varPrefix}target_${tag}_${si}`;
                 const pattern = buildRelPattern({
@@ -1425,6 +1570,33 @@ export class MutationCompiler {
         this.narrowedRelDefs.add(narrowed);
         return narrowed;
     }
+    /**
+     * v2.6.0 — how a blanket disconnect (`null` / `{}`) restricts its target.
+     *
+     * Default (v2.5.3): only a relationship narrowed to a union / interface
+     * member keeps that member's label; otherwise the target is anonymous,
+     * so with two fields on one relationship type and direction
+     * (`pets: [Pet]`, `toys: [Toy]`, both `HAS`) a blanket disconnect of one
+     * also unlinks the other's nodes (warned once at OGM construction).
+     *
+     * Strict: the field's own target type — its label, or for an abstract
+     * target a predicate over its members' labels on `targetVar`.
+     */
+    blanketRestriction(relDef, targetNodeDef, targetVar) {
+        const narrowed = this.blanketTargetLabel(relDef);
+        if (narrowed || !this.strictMode.strict || !targetNodeDef)
+            return { labelRaw: narrowed, labelPredicate: null };
+        if (abstractTarget(targetNodeDef.typeName, this.schema))
+            return {
+                labelRaw: undefined,
+                labelPredicate: this.targetMatch(targetNodeDef, targetVar)
+                    .labelPredicate,
+            };
+        return {
+            labelRaw: this.getCachedLabelString(targetNodeDef),
+            labelPredicate: null,
+        };
+    }
     /** The label a blanket disconnect over `relDef` must keep (see above). */
     blanketTargetLabel(relDef) {
         if (!this.narrowedRelDefs.has(relDef))
@@ -1515,6 +1687,8 @@ export class MutationCompiler {
                         : [item.disconnect];
                     for (let di = 0; di < disconnectItems.length; di++) {
                         const disconnectSpec = disconnectItems[di];
+                        if (isPlainObject(disconnectSpec))
+                            this.checkLinkItemKeys(disconnectSpec, 'disconnect', relDef);
                         const whereSpec = disconnectSpec.where;
                         // A nested `disconnect` needs the target bound, so an item that
                         // carries one is never the anonymous blanket form.
@@ -1531,18 +1705,20 @@ export class MutationCompiler {
                             // disconnect: only unlink targets the caller can read.
                             const blanketTarget = `${sourceVar}_disc${varCounter}`;
                             const predicate = this.buildTargetPolicyPredicate(targetNodeDef, blanketTarget, params, policyContext, paramCounter);
-                            if (predicate)
+                            const { labelRaw, labelPredicate } = this.blanketRestriction(relDef, targetNodeDef, blanketTarget);
+                            if (predicate || labelPredicate)
                                 varCounter++;
                             const pattern = buildRelPattern({
                                 sourceVar,
                                 relDef,
-                                targetVar: predicate ? blanketTarget : '',
+                                targetVar: predicate || labelPredicate ? blanketTarget : '',
                                 edgeVar: relVar,
-                                targetLabelRaw: this.blanketTargetLabel(relDef),
+                                targetLabelRaw: labelRaw,
                             });
                             lines.push(`OPTIONAL MATCH ${pattern}`);
-                            if (predicate)
-                                lines.push(`WHERE ${predicate}`);
+                            const blanketConditions = [labelPredicate, predicate].filter(Boolean);
+                            if (blanketConditions.length > 0)
+                                lines.push(`WHERE ${blanketConditions.join(' AND ')}`);
                             lines.push(`DELETE ${relVar}`);
                         }
                         else {
@@ -1650,6 +1826,7 @@ export class MutationCompiler {
                         // create() accepts. Pre-2.4.5 this path never read
                         // `createSpec.edge`, so they were silently dropped.
                         const edgeInput = createSpec.edge;
+                        this.checkEdgeKeys(relDef, edgeInput, 'nested create');
                         const edgeEntries = Object.entries(edgeInput ?? {}).filter(([, v]) => v !== undefined);
                         const edgeVar = edgeEntries.length ? `${createVar}_e` : undefined;
                         const relPattern = buildRelPattern({
@@ -1720,6 +1897,7 @@ export class MutationCompiler {
                     // Pre-compute SET clauses for edge (relationship) properties
                     const edgeClauses = [];
                     const edgeParams = {};
+                    this.checkEdgeKeys(relDef, edgeUpdate, 'nested update');
                     if (edgeUpdate)
                         for (const [prop, val] of Object.entries(edgeUpdate)) {
                             if (val === undefined)
@@ -1867,6 +2045,21 @@ MutationCompiler.OPERATOR_SUFFIXES = [
  * path to validate that every item shares the same shape; mismatched
  * shapes silently drop keys from the compiled WHERE / SET.
  */
+/**
+ * v2.6.0 — the keys a connect / disconnect item is compiled from. `overwrite`
+ * is offered by the generated `ConnectFieldInput` and accepted as before
+ * (MERGE + SET always overwrites the edge properties it is given).
+ */
+const CONNECT_ITEM_KEYS = new Set([
+    'where',
+    'edge',
+    'overwrite',
+    'connect',
+]);
+const DISCONNECT_ITEM_KEYS = new Set([
+    'where',
+    'disconnect',
+]);
 /** Keys that make a nested-mutation `where` connection-shaped. */
 const CONNECTION_WHERE_KEYS = new Set([
     'node',
@@ -2039,6 +2232,47 @@ function upsertRelationshipError(nodeDef, key, branch) {
     return new OGMError(`upsert does not support relationship fields: "${key}" in "${branch}" (${nodeDef.typeName}). ` +
         `Use create() / update() for nested relationship operations.`);
 }
+/**
+ * v2.6.1 — the lines around an upsert MERGE that apply the root type's
+ * `update` row filter to the node it MATCHES, as a direct `update` does:
+ *
+ *   OPTIONAL MATCH (__existing:L { key })        ┐ before
+ *   WITH count(__existing) > 0 AS __matched      ┘
+ *   MERGE (n:L { key })
+ *   ON CREATE SET …
+ *   WITH n, __matched                            ┐ after
+ *   [@cypher preludes of the guard]              │
+ *   WHERE NOT __matched OR (<guard>)             │
+ *   FOREACH (__u IN CASE WHEN __matched THEN [1] ELSE [] END | SET …)
+ *
+ * A created node passes untouched by the update sets; an existing node is
+ * updated only when it passes the guard; one that fails it is neither
+ * updated nor returned (and the MERGE created nothing). Pre-2.6.1 the
+ * update went in `ON MATCH SET` with no row filter, so any context the
+ * WITH CHECK admitted rewrote any existing node — even its owner field.
+ *
+ * `count()` keeps one row before the MERGE whether 0, 1 or several nodes
+ * match (invariant 2); FOREACH needs no subquery after the write
+ * (invariant 1). Under a race, a node created between the OPTIONAL MATCH
+ * and the MERGE is matched with `__matched = false`: its properties are
+ * not updated (default-mode runtime `labels`, SET after this, still are).
+ */
+function buildGuardedMerge(labelStr, mergeProps, guard, updateSets, params) {
+    mergeParams(params, guard.params);
+    const after = ['WITH n, __matched'];
+    if (guard.preludes && guard.preludes.length > 0)
+        after.push(...guard.preludes);
+    after.push(`WHERE NOT __matched OR (${guard.cypher})`);
+    if (updateSets.length > 0)
+        after.push(`FOREACH (__u IN CASE WHEN __matched THEN [1] ELSE [] END | SET ${updateSets.join(', ')})`);
+    return {
+        before: [
+            `OPTIONAL MATCH (__existing:${labelStr} { ${mergeProps.join(', ')} })`,
+            'WITH count(__existing) > 0 AS __matched',
+        ],
+        after,
+    };
+}
 /** `null` / `{}`: the whole-relationship (blanket) form, never per member. */
 function isBlanketSpec(spec) {
     if (spec == null)