grafeo-ogm 2.0.0 → 2.1.1

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

@@ -1,6 +1,7 @@
 import { OGMError } from '../errors';
 import { buildRelPattern, getTargetLabelString, resolveTargetDef, } from '../schema/utils';
 import { assertSafeIdentifier, assertSafeLabel, assertSafePropertyName, escapeIdentifier, mergeParams, } from '../utils/validation';
+import { coerceWriteValue, resolveDefaultWriteValue, wrapListItemExpr, wrapWhereParam, wrapWriteExpr, } from '../utils/write-coercion';
 import { WhereCompiler } from './where.compiler';
 /**
  * Relationship filter suffixes that require EXISTS subquery patterns.
@@ -179,9 +180,11 @@ export class MutationCompiler {
                 if (value === undefined)
                     continue;
                 assertSafePropertyName(key, 'update property');
+                const propDef = nodeDef.properties.get(key);
                 const paramName = `update_${key}`;
-                setClauses.push(`n.${escapeIdentifier(key)} = $${paramName}`);
-                params[paramName] = value;
+                const valueExpr = wrapWriteExpr(`$${paramName}`, value, propDef);
+                setClauses.push(`n.${escapeIdentifier(key)} = ${valueExpr}`);
+                params[paramName] = coerceWriteValue(value, propDef);
             }
             if (setClauses.length > 0)
                 lines.push(`SET ${setClauses.join(', ')}`);
@@ -259,10 +262,12 @@ export class MutationCompiler {
             if (key.includes('_') && !nodeDef.properties.has(key))
                 continue;
             assertSafePropertyName(key, 'merge key');
+            const propDef = nodeDef.properties.get(key);
             const paramName = `merge_${key}`;
-            mergeProps.push(`${escapeIdentifier(key)}: $${paramName}`);
+            const valueExpr = wrapWriteExpr(`$${paramName}`, value, propDef);
+            mergeProps.push(`${escapeIdentifier(key)}: ${valueExpr}`);
             mergeKeyNames.push(key);
-            params[paramName] = value;
+            params[paramName] = coerceWriteValue(value, propDef);
         }
         if (mergeProps.length === 0)
             throw new OGMError('upsert requires at least one scalar property in "where" for MERGE key');
@@ -298,9 +303,29 @@ export class MutationCompiler {
             if (nodeDef.relationships.has(key))
                 continue;
             assertSafePropertyName(key, 'create property');
+            const propDef = nodeDef.properties.get(key);
             const paramName = `onCreate_${key}`;
-            createSets.push(`n.${escapeIdentifier(key)} = $${paramName}`);
-            params[paramName] = value;
+            const valueExpr = wrapWriteExpr(`$${paramName}`, value, propDef);
+            createSets.push(`n.${escapeIdentifier(key)} = ${valueExpr}`);
+            params[paramName] = coerceWriteValue(value, propDef);
+        }
+        // `@default` values apply to the ON CREATE branch — a defaulted
+        // property not supplied in `create` and not already fixed by the
+        // MERGE key gets its default, mirroring create().
+        for (const [, propDef] of nodeDef.properties) {
+            if (propDef.defaultValue === undefined)
+                continue;
+            if (propDef.isGenerated || propDef.isCypher)
+                continue;
+            if (create[propDef.name] !== undefined)
+                continue;
+            if (mergeKeyNames.includes(propDef.name))
+                continue;
+            const paramName = `onCreate_${propDef.name}`;
+            const bound = resolveDefaultWriteValue(propDef);
+            const valueExpr = wrapWriteExpr(`$${paramName}`, bound, propDef);
+            createSets.push(`n.${escapeIdentifier(propDef.name)} = ${valueExpr}`);
+            params[paramName] = bound;
         }
         if (createSets.length > 0)
             lines.push(`ON CREATE SET ${createSets.join(', ')}`);
@@ -312,9 +337,11 @@ export class MutationCompiler {
             if (nodeDef.relationships.has(key))
                 continue;
             assertSafePropertyName(key, 'update property');
+            const propDef = nodeDef.properties.get(key);
             const paramName = `onMatch_${key}`;
-            updateSets.push(`n.${escapeIdentifier(key)} = $${paramName}`);
-            params[paramName] = value;
+            const valueExpr = wrapWriteExpr(`$${paramName}`, value, propDef);
+            updateSets.push(`n.${escapeIdentifier(key)} = ${valueExpr}`);
+            params[paramName] = coerceWriteValue(value, propDef);
         }
         if (updateSets.length > 0)
             lines.push(`ON MATCH SET ${updateSets.join(', ')}`);
@@ -386,12 +413,24 @@ export class MutationCompiler {
         for (const [, propDef] of nodeDef.properties)
             if (propDef.isGenerated && !scalarKeys.includes(propDef.name))
                 generatedFields.push(propDef.name);
+        // Whole-column `@default`s: applied only when NO item supplies the
+        // field. Per-item gaps inside a provided column stay null — one
+        // createMany batch shares a single Cypher text, and a per-item
+        // default would need coalesce(), which would also override explicit
+        // nulls.
+        const defaultedProps = [];
+        for (const [, propDef] of nodeDef.properties)
+            if (propDef.defaultValue !== undefined &&
+                !propDef.isGenerated &&
+                !propDef.isCypher &&
+                !scalarKeys.includes(propDef.name))
+                defaultedProps.push(propDef);
         // Build sanitized items (strip undefined values)
         const sanitizedItems = data.map((item) => {
             const sanitized = {};
             for (const key of scalarKeys)
                 if (item[key] !== undefined)
-                    sanitized[key] = item[key];
+                    sanitized[key] = coerceWriteValue(item[key], nodeDef.properties.get(key));
             return sanitized;
         });
         params.items = sanitizedItems;
@@ -408,16 +447,22 @@ export class MutationCompiler {
                 throw new OGMError('createMany with skipDuplicates requires at least one @id or @unique field in data');
             // MERGE on unique key(s)
             const mergeProps = mergeKeys
-                .map((k) => `${escapeIdentifier(k)}: item.${escapeIdentifier(k)}`)
+                .map((k) => `${escapeIdentifier(k)}: ${wrapListItemExpr(`item.${escapeIdentifier(k)}`, data.map((d) => d[k]), nodeDef.properties.get(k))}`)
                 .join(', ');
             lines.push(`MERGE (n:${labelStr} { ${mergeProps} })`);
             // ON CREATE SET — remaining fields + generated IDs
             const onCreateSets = [];
             for (const key of scalarKeys)
                 if (!mergeKeys.includes(key))
-                    onCreateSets.push(`n.${escapeIdentifier(key)} = item.${escapeIdentifier(key)}`);
+                    onCreateSets.push(`n.${escapeIdentifier(key)} = ${wrapListItemExpr(`item.${escapeIdentifier(key)}`, data.map((d) => d[key]), nodeDef.properties.get(key))}`);
             for (const field of generatedFields)
                 onCreateSets.push(`n.${escapeIdentifier(field)} = randomUUID()`);
+            for (const propDef of defaultedProps) {
+                const paramName = `default_${propDef.name}`;
+                const bound = resolveDefaultWriteValue(propDef);
+                onCreateSets.push(`n.${escapeIdentifier(propDef.name)} = ${wrapWriteExpr(`$${paramName}`, bound, propDef)}`);
+                params[paramName] = bound;
+            }
             if (onCreateSets.length > 0)
                 lines.push(`ON CREATE SET ${onCreateSets.join(', ')}`);
         }
@@ -427,7 +472,13 @@ export class MutationCompiler {
             for (const field of generatedFields)
                 propParts.push(`${escapeIdentifier(field)}: randomUUID()`);
             for (const key of scalarKeys)
-                propParts.push(`${escapeIdentifier(key)}: item.${escapeIdentifier(key)}`);
+                propParts.push(`${escapeIdentifier(key)}: ${wrapListItemExpr(`item.${escapeIdentifier(key)}`, data.map((d) => d[key]), nodeDef.properties.get(key))}`);
+            for (const propDef of defaultedProps) {
+                const paramName = `default_${propDef.name}`;
+                const bound = resolveDefaultWriteValue(propDef);
+                propParts.push(`${escapeIdentifier(propDef.name)}: ${wrapWriteExpr(`$${paramName}`, bound, propDef)}`);
+                params[paramName] = bound;
+            }
             lines.push(`CREATE (n:${labelStr} { ${propParts.join(', ')} })`);
         }
         // Extra labels
@@ -439,6 +490,19 @@ export class MutationCompiler {
         return { cypher: lines.join('\n'), params };
     }
     // ─── Private helpers ──────────────────────────────────────────────
+    /**
+     * Resolve the PropertyDefinition of an edge (relationship) property so
+     * Int/BigInt edge writes get the same Integer coercion as node writes.
+     * Returns undefined when the relationship declares no properties type
+     * (the coercion then passes the value through untouched).
+     */
+    getEdgePropDef(relDef, propName) {
+        if (!relDef.properties)
+            return undefined;
+        return this.schema.relationshipProperties
+            .get(relDef.properties)
+            ?.properties.get(propName);
+    }
     buildCreateProperties(input, nodeDef, prefix) {
         const parts = [];
         const propParams = {};
@@ -453,9 +517,28 @@ export class MutationCompiler {
             if (value === undefined)
                 continue;
             assertSafePropertyName(key, 'create property');
+            const propDef = nodeDef.properties.get(key);
             const paramName = `${prefix}_${key}`;
-            parts.push(`${escapeIdentifier(key)}: $${paramName}`);
-            propParams[paramName] = value;
+            const valueExpr = wrapWriteExpr(`$${paramName}`, value, propDef);
+            parts.push(`${escapeIdentifier(key)}: ${valueExpr}`);
+            propParams[paramName] = coerceWriteValue(value, propDef);
+        }
+        // `@default` values — applied for any property with a default that the
+        // input leaves undefined. Explicit null is respected as null: the user
+        // asked for null, a default would override intent. Generated (@id) and
+        // @cypher (computed, not stored) properties never take defaults.
+        for (const [, propDef] of nodeDef.properties) {
+            if (propDef.defaultValue === undefined)
+                continue;
+            if (propDef.isGenerated || propDef.isCypher)
+                continue;
+            if (input[propDef.name] !== undefined)
+                continue;
+            const paramName = `${prefix}_${propDef.name}`;
+            const bound = resolveDefaultWriteValue(propDef);
+            const valueExpr = wrapWriteExpr(`$${paramName}`, bound, propDef);
+            parts.push(`${escapeIdentifier(propDef.name)}: ${valueExpr}`);
+            propParams[paramName] = bound;
         }
         return { propString: parts.join(', '), propParams };
     }
@@ -560,9 +643,10 @@ export class MutationCompiler {
                         if (val === undefined)
                             continue;
                         assertSafePropertyName(prop, 'edge property');
+                        const edgePropDef = this.getEdgePropDef(relDef, prop);
                         const paramName = `${prefix}_create${ci}_edge_${prop}`;
-                        setItems.push(`${relVar}.${escapeIdentifier(prop)} = $${paramName}`);
-                        params[paramName] = val;
+                        setItems.push(`${relVar}.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, edgePropDef)}`);
+                        params[paramName] = coerceWriteValue(val, edgePropDef);
                     }
                     if (setItems.length > 0)
                         lines.push(`SET ${setItems.join(', ')}`);
@@ -612,9 +696,10 @@ export class MutationCompiler {
                         if (val === undefined)
                             continue;
                         assertSafePropertyName(prop, 'edge property');
+                        const edgePropDef = this.getEdgePropDef(relDef, prop);
                         const paramName = `${prefix}_conn${ci}_edge_${prop}`;
-                        setItems.push(`r_conn_${startCounter + counter - 1}.${escapeIdentifier(prop)} = $${paramName}`);
-                        params[paramName] = val;
+                        setItems.push(`r_conn_${startCounter + counter - 1}.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, edgePropDef)}`);
+                        params[paramName] = coerceWriteValue(val, edgePropDef);
                     }
                     if (setItems.length > 0)
                         lines.push(`SET ${setItems.join(', ')}`);
@@ -683,9 +768,10 @@ export class MutationCompiler {
                                 if (val === undefined)
                                     continue;
                                 assertSafePropertyName(prop, 'edge property');
+                                const edgePropDef = this.getEdgePropDef(relDef, prop);
                                 const paramName = `connect_${fieldName}_${ci}_edge_${prop}`;
-                                setItems.push(`${relVar}.${escapeIdentifier(prop)} = $${paramName}`);
-                                params[paramName] = val;
+                                setItems.push(`${relVar}.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, edgePropDef)}`);
+                                params[paramName] = coerceWriteValue(val, edgePropDef);
                             }
                             if (setItems.length > 0)
                                 lines.push(`SET ${setItems.join(', ')}`);
@@ -713,7 +799,7 @@ export class MutationCompiler {
                         const cleaned = {};
                         for (const [k, v] of Object.entries(edge))
                             if (v !== undefined)
-                                cleaned[k] = v;
+                                cleaned[k] = coerceWriteValue(v, this.getEdgePropDef(relDef, k));
                         return { ...item, edge: cleaned };
                     });
                     lines.push('WITH n');
@@ -737,7 +823,7 @@ export class MutationCompiler {
                                 `silently dropped. Split into separate connect calls, or normalise the items ` +
                                 `to share the same shape.`);
                     }
-                    const whereConditions = this.extractConnectWhereConditions(firstItem, 'target', 'connItem');
+                    const whereConditions = this.extractConnectWhereConditions(firstItem, 'target', 'connItem', targetNodeDef);
                     const policyPredicate = this.buildTargetPolicyPredicate(targetNodeDef, 'target', params, policyContext, paramCounter);
                     const unwindConditions = policyPredicate
                         ? [...whereConditions, policyPredicate]
@@ -762,7 +848,7 @@ export class MutationCompiler {
                         // Replace MERGE line with one that has a variable
                         lines[lines.length - 1] = `MERGE ${mergeWithVar}`;
                         // r.prop is relationship property (escape), connItem.edge.prop is parameter map (no escape)
-                        const setItems = edgeProps.map((p) => `r.${escapeIdentifier(p)} = connItem.edge.${p}`);
+                        const setItems = edgeProps.map((p) => `r.${escapeIdentifier(p)} = ${wrapListItemExpr(`connItem.edge.${p}`, spec.map((it) => it.edge?.[p]), this.getEdgePropDef(relDef, p))}`);
                         lines.push(`SET ${setItems.join(', ')}`);
                     }
                 }
@@ -793,9 +879,10 @@ export class MutationCompiler {
                     for (const [prop, val] of Object.entries(edgeInput)) {
                         if (val === undefined)
                             continue;
+                        const edgePropDef = this.getEdgePropDef(relDef, prop);
                         const paramName = `connect_${fieldName}_edge_${prop}`;
-                        setItems.push(`r.${escapeIdentifier(prop)} = $${paramName}`);
-                        params[paramName] = val;
+                        setItems.push(`r.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, edgePropDef)}`);
+                        params[paramName] = coerceWriteValue(val, edgePropDef);
                     }
                     if (setItems.length > 0)
                         lines.push(`SET ${setItems.join(', ')}`);
@@ -1108,9 +1195,10 @@ export class MutationCompiler {
                                 if (val === undefined)
                                     continue;
                                 assertSafePropertyName(prop, 'edge property');
+                                const edgePropDef = this.getEdgePropDef(relDef, prop);
                                 const paramName = `${itemPrefix}_conn${ci}_edge_${prop}`;
-                                setItems.push(`r_conn_${key}_${ci}.${escapeIdentifier(prop)} = $${paramName}`);
-                                params[paramName] = val;
+                                setItems.push(`r_conn_${key}_${ci}.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, edgePropDef)}`);
+                                params[paramName] = coerceWriteValue(val, edgePropDef);
                             }
                             if (setItems.length > 0)
                                 lines.push(`SET ${setItems.join(', ')}`);
@@ -1146,9 +1234,10 @@ export class MutationCompiler {
                         if (val === undefined)
                             continue;
                         assertSafePropertyName(prop, 'nested update property');
+                        const nodePropDef = targetNodeDef.properties.get(prop);
                         const paramName = `${itemPrefix}_set_${prop}`;
-                        setClauses.push(`${updateVar}.${escapeIdentifier(prop)} = $${paramName}`);
-                        setParams[paramName] = val;
+                        setClauses.push(`${updateVar}.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, nodePropDef)}`);
+                        setParams[paramName] = coerceWriteValue(val, nodePropDef);
                     }
                     // Pre-compute SET clauses for edge (relationship) properties
                     const edgeClauses = [];
@@ -1158,9 +1247,10 @@ export class MutationCompiler {
                             if (val === undefined)
                                 continue;
                             assertSafePropertyName(prop, 'edge update property');
+                            const edgePropDef = this.getEdgePropDef(relDef, prop);
                             const paramName = `${itemPrefix}_edge_${prop}`;
-                            edgeClauses.push(`${relVar}.${escapeIdentifier(prop)} = $${paramName}`);
-                            edgeParams[paramName] = val;
+                            edgeClauses.push(`${relVar}.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, edgePropDef)}`);
+                            edgeParams[paramName] = coerceWriteValue(val, edgePropDef);
                         }
                     // Pre-compute nested relationship operations
                     const nestedParams = {};
@@ -1246,15 +1336,16 @@ export class MutationCompiler {
                     assertSafePropertyName(baseProp, 'where property');
                     const paramName = `${prefix}_NOT_${notProp}`;
                     const escapedProp = escapeIdentifier(baseProp);
+                    const paramRef = wrapWhereParam(`$${paramName}`, notVal, targetNodeDef?.properties.get(baseProp), notProp.slice(baseProp.length));
                     let expr;
                     if (template === '%v = $%p')
                         // Simple equality → negate to <>
-                        expr = `${targetVar}.${escapedProp} <> $${paramName}`;
+                        expr = `${targetVar}.${escapedProp} <> ${paramRef}`;
                     else {
                         // Operator suffix — wrap with NOT if not already negated
                         const resolved = template
                             .replace('%v', `${targetVar}.${escapedProp}`)
-                            .replace('$%p', `$${paramName}`);
+                            .replace('$%p', paramRef);
                         expr = resolved.startsWith('NOT ') ? resolved : `NOT ${resolved}`;
                     }
                     conditions.push(expr);
@@ -1271,9 +1362,10 @@ export class MutationCompiler {
                 const { baseProp, template } = this.parseOperatorSuffix(prop);
                 assertSafePropertyName(baseProp, 'where property');
                 const paramName = `${prefix}_${prop}`;
+                const paramRef = wrapWhereParam(`$${paramName}`, val, targetNodeDef?.properties.get(baseProp), prop.slice(baseProp.length));
                 conditions.push(template
                     .replace('%v', `${targetVar}.${escapeIdentifier(baseProp)}`)
-                    .replace('$%p', `$${paramName}`));
+                    .replace('$%p', paramRef));
                 params[paramName] = val;
             }
         return conditions;
@@ -1438,7 +1530,7 @@ export class MutationCompiler {
         }
         return false;
     }
-    extractConnectWhereConditions(item, targetVar, itemVar) {
+    extractConnectWhereConditions(item, targetVar, itemVar, targetNodeDef) {
         const conditions = [];
         const whereSpec = item.where;
         if (!whereSpec)
@@ -1449,7 +1541,9 @@ export class MutationCompiler {
             assertSafePropertyName(baseProp, 'connect where property');
             // Replace template placeholders with dynamic UNWIND references
             // Note: itemVar map access is NOT escaped (parameter map keys, not Cypher identifiers)
-            const valueRef = `${itemVar}.where.node.${key}`;
+            // Temporal wrap keys off the FIRST item's value type — the UNWIND
+            // fast path already requires shape-homogeneous items.
+            const valueRef = wrapWhereParam(`${itemVar}.where.node.${key}`, nodeWhere[key], targetNodeDef?.properties.get(baseProp), key.slice(baseProp.length));
             conditions.push(template
                 .replace('%v', `${targetVar}.${escapeIdentifier(baseProp)}`)
                 .replace('$%p', valueRef));