grafeo-ogm 2.5.3 → 2.6.0

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
@@ -110,9 +112,10 @@ export class MutationCompiler {
                     reason: 'no-permissive-matched',
                 });
         }
-        // Abstract (interface / union) targets get a CASE over their concrete
-        // members' own clauses — pre-2.3.0 only the abstract type's own
-        // policies (usually none) were applied.
+        // Abstract (interface / union) targets get a conjunction over their
+        // concrete members' own clauses — every member label the node carries
+        // must pass (v2.5.4; pre-2.5.4 a first-match CASE) — pre-2.3.0 only
+        // the abstract type's own policies (usually none) were applied.
         const clause = this.getPolicyWhereCompiler().compileTargetPolicyClause(targetNodeDef.typeName, targetVar, op, policyContext, counter);
         if (clause.preludes.length > 0)
             throw new OGMError(`Policy on "${targetNodeDef.typeName}" requires @cypher field ` +
@@ -277,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.
@@ -570,6 +635,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 = [];
@@ -620,6 +698,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)
@@ -643,9 +726,10 @@ export class MutationCompiler {
         if (updateSets.length > 0)
             lines.push(`ON MATCH SET ${updateSets.join(', ')}`);
         // Extra labels
-        if (labels && labels.length > 0) {
+        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 };
@@ -795,6 +879,9 @@ 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.
+            if (this.strictMode.strict && labels && labels.length > 0)
+                onCreateSets.push(`n:${labels.map((l) => assertSafeLabel(l)).join(':')}`);
             if (onCreateSets.length > 0)
                 lines.push(`ON CREATE SET ${onCreateSets.join(', ')}`);
         }
@@ -814,9 +901,13 @@ export class MutationCompiler {
             lines.push(`CREATE (n:${labelStr} { ${propParts.join(', ')} })`);
         }
         // Extra labels
-        if (labels && labels.length > 0) {
+        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 };
@@ -966,6 +1057,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
@@ -1104,6 +1196,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);
@@ -1230,6 +1327,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;
@@ -1371,21 +1470,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({
@@ -1424,6 +1527,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))
@@ -1514,6 +1644,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.
@@ -1530,18 +1662,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 {
@@ -1649,6 +1783,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({
@@ -1719,6 +1854,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)
@@ -1866,6 +2002,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',