grafeo-ogm 2.4.8 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 2.5.0 (2026-10-18) — breaking fixes from the bug scan
+
+> **Minor release. Every item below changes behaviour that callers may depend on.** Each change fixes a confirmed bug, and the old behaviour was wrong (see each entry). The non-breaking fixes from the same scan shipped in **2.4.8**.
+
+### Upgrade checklist
+
+Use this to check whether you're affected. If none of these apply, 2.5.0 is a drop-in upgrade.
+
+| If you… | Then… |
+|---|---|
+| use `InterfaceModel` | it now finds implementor nodes **without** the interface label, so result counts can grow (see below) |
+| put arguments or aliases in `selectionSet` strings (`posts(where: …)`, `r: rank`) | they now take effect, and unsupported ones throw |
+| pass non-`@id`/`@unique` keys in `upsert` `where` | they now throw |
+| rely on `createMany({ skipDuplicates: true })` counting the skipped duplicates | it now returns the created count |
+| write keys that aren't in the schema | they now throw `Unknown field …` |
+| pass relationship fields in a later `createMany` item | they now throw |
+| filter list fields with element-typed operators (`tags: 'x'`, `tags_CONTAINS`) | those no longer compile (they never matched) |
+| use `CypherAssert` or `Neo4jRecordFactory.dateTime` in tests | stricter assertions may expose tests that passed by accident |
+| use `cloneSubgraph` / `deleteSubgraph` | traversal is now outgoing-only by default, and the root is matched by label |
+
+### Reads
+
+- **`InterfaceModel` matches implementors, not the interface label.** `find`, `count` and `aggregate` used to `MATCH (n:<Interface>)`. Nodes created with `Model.create` never carry that label, so these methods found nothing for nodes the OGM itself wrote. They now `MATCH (n:(A|B|…))` over the implementors, as `@neo4j/graphql` does. Per-member policies, `__typename` and the `labels` filter work as before.
+  - **What to do:** nodes carrying *only* the interface label, with no implementor label, are no longer returned; give them their concrete label. Recheck counts and pagination that depended on the old, smaller result. Listing the interface in `@node(labels: [...])` still works but is no longer needed.
+- **`selectionSet` arguments and aliases take effect.** They were silently ignored, so `posts(where: …)` and `posts(options: { sort, limit, offset })` returned every related node, `r: rank` came back as `rank`, and two aliases of one field collapsed into one key. Now relationship fields honour `where` (with the target `read` policy applied) and `options` (`sort` needs APOC; `limit` and `offset` are bound parameters). Connection fields honour `where`, and aliases name the output keys.
+  - **Now throw `OGMError`:** any other argument, an unknown option or sort field, `options` on a singular relationship, GraphQL `$variables`, and arguments on a field reached through a union-typed parent.
+  - **What to do:** search for `selectionSet` strings with arguments or aliases. Their results now match what they ask for: filtered, paged and re-keyed.
+
+### Writes
+
+- **`upsert` `where` accepts only `@id` / `@unique` fields.** A plain key used to join the `MERGE` pattern, so `where: { email, name: 'Bob' }` against an existing `{ email, name: 'Alice' }` created a **duplicate** with the same email. An operator key (`name_CONTAINS`) was silently dropped, which widened the match so the **wrong row** could be updated. These now throw `OGMError`: a plain, operator, logical or unknown key, and a `null` value. At least one unique key is required.
+  - **What to do:** keep only unique keys in `where` and move the other fields into `create` / `update`. For a non-unique match, use `findFirst()` followed by `create()` / `update()`.
+- **Unknown keys in write input throw.** A key that is neither a property nor a relationship of the type (a typo like `nmae`) was written as a stray property, and the intended field was left unchanged. It now throws `Unknown field …`, in `create`, `update`, `updateMany`, `createMany`, `upsert`, and nested creates and updates at any depth.
+  - **What to do:** declare every property you write in the schema.
+- **`createMany({ skipDuplicates: true })` returns the number of nodes created.** It used to include the duplicates it skipped. It now matches Prisma. Calls without `skipDuplicates` are unchanged.
+- **`createMany` rejects relationship fields in every item.** Only `data[0]` used to be checked; later items were created without their relationship input. The error names the item, e.g. `"tags" in data[1]`. Use `create()` for nested relationship writes.
+
+### Generated types
+
+- **List-scalar where operators are typed as lists (compile-time only).** For `tags: [String!]`, equality and `_NOT` take `Array<T>`, and `_IN` / `_NOT_IN` take `Array<Array<T>>`. String and comparison operators are no longer generated for list fields. The old element-typed forms (`{ tags: 'x' }`, `tags_CONTAINS`) compiled but **never matched**, while the working form `{ tags: ['x', 'y'] }` didn't compile. Runtime behaviour is unchanged.
+
+### Testing helpers
+
+- **`CypherAssert.assertContainsClause` looks for the pattern inside the clause.** The clause and the pattern were checked independently, so `assertContainsClause(q, 'WHERE', 'n { .name }')` passed when the pattern was in the `RETURN`. `'SET'` also matched `$offset`. Keywords now match whole words, outside strings, names and comments, and the pattern must sit within that clause.
+- **`CypherAssert.normalize` and `assertStructurallyEqual` keep string literals and backticked names verbatim.** `'a  b'` used to equal `'a b'`, and a `$name` inside a string was renamed as a parameter.
+- **`Neo4jRecordFactory.dateTime` reads an offset-less string as UTC**, as Neo4j does. It used to use the machine's local zone, so results differed between a laptop and CI. A string that isn't a date now throws a `TypeError`.
+
+Assertions that only passed by accident will now fail.
+
+### Subgraph operations (APOC)
+
+- **Owned relationships are followed outgoing by default.** A bare type was expanded in **both** directions. With two books sharing a chapter, `deleteSubgraph(bookA)` climbed back up the shared chapter and **deleted book B**, `deleteSubgraph(chapter)` deleted its parent book, and `cloneSubgraph` pulled in the other parents. Now a bare `'TYPE'` is outgoing, `'<TYPE'` is incoming, and `'<TYPE>'` is both directions (the old behaviour).
+  - **What to do:** mark relationships you traverse backwards as `'<TYPE'` or `'<TYPE>'`.
+- **The root is matched by label, and owned nodes without an `id` are refused.** The root was matched by `id` alone, so any node with that id became a root, found by scanning every node. It's now `(:rootLabel {id})`. The new optional `SubgraphConfig.rootLabel` defaults to `ownedLabels[0]`. `cloneSubgraph` now aborts before writing anything if an owned node has no `id` or shares one with another owned node; previously those nodes collapsed onto one mapping entry.
+  - **What to do:** set `rootLabel` if your root isn't of the first owned label.
+
+Every entry above has a regression test, live wherever behaviour depends on the server. The subgraph changes are verified against Neo4j 5.26 with APOC 5.26.
+
 ## 2.4.8 (2026-10-18) — bug-scan fixes across reads, writes, codegen, CLI and testing helpers
 
 > **A large patch release. Upgrading is safe, with no breaking changes.** Most of these bugs were found by a third, multi-area bug scan. Each fix was reproduced on Neo4j 5.26 before it was fixed, and is pinned by a regression test, live wherever behaviour depends on the server. The breaking fixes from the same scan ship separately in **2.5.0**. Cypher for queries the fixes don't touch is unchanged; the policy byte-identical suite pins this.

package/README.md

@@ -397,7 +397,7 @@ grafeo-ogm uses standard GraphQL SDL with Neo4j directives to define your graph
 
 | Directive | Target | Description |
 |---|---|---|
-| `@node` | Type | Marks a type as a Neo4j node. Optional `labels` argument for multi-label nodes (implementors of an interface must include the interface name, see [Interfaces](#interfaces)) |
+| `@node` | Type | Marks a type as a Neo4j node. Optional `labels` argument for multi-label nodes (implementors of an interface no longer need to include the interface name since v2.5.0, see [Interfaces](#interfaces)) |
 | `@relationship` | Field | Defines a relationship with `type`, `direction` (exactly `IN` or `OUT`; anything else is a schema error), and optional `properties` |
 | `@declareRelationship` | Interface field | Declares a relationship on an interface. Its `type`, `direction` and `properties` come from the implementors' `@relationship`, which must all agree |
 | `@relationshipProperties` | Type | Marks a type as relationship properties (edge data) |
@@ -483,7 +483,7 @@ type Resource @node {
 
 Interface types can be queried polymorphically via `ogm.interfaceModel('Entity')`. Results include `__typename` to discriminate concrete types.
 
-- The interface model matches nodes by the **interface label** (`MATCH (n:Entity)`), so every implementor must carry it: list the interface name in `@node(labels: [...])`. An implementor declared with a bare `@node` is stored with only its own label and never appears in interface queries.
+- The interface model matches nodes by their **implementors' labels** (`MATCH (n:(User|Organization))`), so a node created with `ogm.model('User').create(...)` appears in interface queries with no extra labels. Since v2.5.0 an implementor does **not** need to carry the interface name; before v2.5.0 it had to list it in `@node(labels: [...])`, which still works.
 - A `@declareRelationship` field takes its relationship `type`, `direction` and `properties` from the implementors. They must all declare the same ones; if they disagree, or an implementor has no `@relationship` on that field, `parseSchema` throws.
 
 ### Enums
@@ -587,6 +587,15 @@ const book = await Book.findUniqueOrThrow({
 | `_NOT_ENDS_WITH` | `NOT ENDS WITH` | `{ name_NOT_ENDS_WITH: 'x' }` |
 | `_MATCHES` | `=~` (regex) | `{ name_MATCHES: '^A.*' }` |
 
+**List fields** (`tags: [String!]`) are compared as a whole list, so only these operators exist for them:
+
+| Operator | Matches when | Example |
+|---|---|---|
+| *(equality)* | the stored list equals the given list | `{ tags: ['a', 'b'] }` |
+| `_NOT` | the stored list differs from the given list | `{ tags_NOT: ['a'] }` |
+| `_IN` | the stored list equals one of the given lists | `{ tags_IN: [['a'], ['b', 'c']] }` |
+| `_NOT_IN` | the stored list equals none of the given lists | `{ tags_NOT_IN: [['a']] }` |
+
 **Relationship quantifiers:**
 
 | Operator | Meaning | Example |
@@ -1044,6 +1053,10 @@ The compiler reads `OR`, then `AND`, then `NOT`, and stops at the first one it f
 
 Clone or delete entire subgraphs using APOC procedures. Requires the APOC plugin installed in Neo4j.
 
+The traversal starts at the root and follows `ownedRelationships` into nodes carrying one of `ownedLabels`. A bare type such as `'HAS_CHAPTER'` is followed **outgoing only**; write `'<CHILD_OF'` to follow a relationship incoming, or `'<LINKED>'` to follow it both ways. Before v2.5.0 a bare type was followed both ways, so deleting one book could climb from a chapter it shared with another book up to that book and delete it too; add `<…>` to keep the old behavior for a type.
+
+The root is matched as `(:rootLabel {id: rootId})`, with `rootLabel` defaulting to the first entry of `ownedLabels` (v2.5.0; before, a node of any label with that id was a root). Set `rootLabel` when the root is not of that label — a delete whose root isn't found deletes nothing and returns `deletedCount: 0`. `cloneSubgraph` maps every owned node by its `id`, so it refuses, before cloning anything, a subgraph in which an owned node has no `id` or shares one with another owned node.
+
 ```typescript
 import { cloneSubgraph, deleteSubgraph } from 'grafeo-ogm';
 
@@ -1069,12 +1082,13 @@ const cloneResult = await cloneSubgraph(
 // v1.13.0+ — post-process only the nodes of one label, no broad-IN filtering:
 const chapterIds = cloneResult.nodesByLabel.get('Chapter') ?? [];
 
-// Delete a subgraph
+// Delete a subgraph rooted at a Chapter: its sections, not its Book
 const deleteResult = await deleteSubgraph(
-  'root-node-id',
+  'chapter-node-id',
   {
-    ownedLabels: ['Book', 'Chapter'],
-    ownedRelationships: ['HAS_CHAPTER'],
+    rootLabel: 'Chapter', // v2.5.0+ — defaults to ownedLabels[0]
+    ownedLabels: ['Chapter', 'Section'],
+    ownedRelationships: ['HAS_SECTION'], // outgoing; '<TYPE' incoming, '<TYPE>' both
     maxLevel: 5,
     referenceRelationships: [],
   },

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

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

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

@@ -283,8 +283,10 @@ class MutationCompiler {
             const input = inputs[i];
             const prefix = `create${i}`;
             const nodeVar = i === 0 ? 'n' : `n_${i}`;
-            const { propString, propParams } = this.buildCreateProperties(input, nodeDef, prefix);
+            // Labels first: an unsafe label must fail as such, before any
+            // input-key check (v2.5.0 rejects unknown keys).
             const labelStr = this.getCachedLabelString(nodeDef);
+            const { propString, propParams } = this.buildCreateProperties(input, nodeDef, prefix);
             lines.push(`CREATE (${nodeVar}:${labelStr} { ${propString} })`);
             (0, validation_1.mergeParams)(params, propParams);
             createdVars.push(nodeVar);
@@ -359,6 +361,7 @@ class MutationCompiler {
                 if (value === undefined)
                     continue;
                 (0, validation_1.assertSafePropertyName)(key, 'update property');
+                assertKnownField(nodeDef, key, 'update');
                 const propDef = nodeDef.properties.get(key);
                 const paramName = `update_${key}`;
                 const valueExpr = (0, write_coercion_1.wrapWriteExpr)(`$${paramName}`, value, propDef);
@@ -510,19 +513,31 @@ class MutationCompiler {
         const labelStr = this.getCachedLabelString(nodeDef);
         const lines = [];
         const params = {};
-        // Build MERGE key properties from where clause (scalar only)
+        // MERGE key: the `@id` / `@unique` fields of `where`, and nothing else
+        // (v2.5.0). Any other key throws:
+        //   - a plain field (`{ email, name }`) became part of the MERGE
+        //     pattern, so an existing node with that email but another name did
+        //     not match — MERGE created a DUPLICATE beside it;
+        //   - an operator key (`name_CONTAINS`) was dropped, silently widening
+        //     the match to the remaining keys;
+        //   - a typo (`usernme`) became a phantom property on the new node.
+        // Pre-1.7.4 any key set was accepted; 1.7.4 required at least one
+        // unique key but still let the others through.
         const mergeProps = [];
         const mergeKeyNames = [];
         for (const [key, value] of Object.entries(where)) {
-            if (value === undefined || value === null)
-                continue;
-            // Skip relationship suffixes and operators
-            if (key === 'AND' || key === 'OR' || key === 'NOT')
-                continue;
-            if (key.includes('_') && !nodeDef.properties.has(key))
+            if (value === undefined)
                 continue;
-            (0, validation_1.assertSafePropertyName)(key, 'merge key');
             const propDef = nodeDef.properties.get(key);
+            if (!propDef ||
+                propDef.isCypher ||
+                !(propDef.isUnique || propDef.isGenerated))
+                throw new errors_1.OGMError(`upsert "where" accepts only @id / @unique fields of ${nodeDef.typeName}; "${key}" is not one. ` +
+                    `MERGE matches on exactly these keys — put other fields in "create" / "update", ` +
+                    `or use findFirst() + create() / update() for a non-unique match.`);
+            if (value === null)
+                throw new errors_1.OGMError(`upsert "where.${key}" is null; a MERGE key must have a value.`);
+            (0, validation_1.assertSafePropertyName)(key, 'merge key');
             const paramName = `merge_${key}`;
             const valueExpr = (0, write_coercion_1.wrapWriteExpr)(`$${paramName}`, value, propDef);
             mergeProps.push(`${(0, validation_1.escapeIdentifier)(key)}: ${valueExpr}`);
@@ -530,30 +545,8 @@ class MutationCompiler {
             params[paramName] = (0, write_coercion_1.coerceWriteValue)(value, propDef);
         }
         if (mergeProps.length === 0)
-            throw new errors_1.OGMError('upsert requires at least one scalar property in "where" for MERGE key');
-        // Validate that the MERGE key set contains at least one `@unique` or
-        // `@id` property. Pre-1.7.4 we accepted any key set, so:
-        //   - A typo in `where` (e.g. `usernme`) became a phantom MERGE
-        //     property — Neo4j happily created a node with that mis-named
-        //     attribute on first use.
-        //   - A non-unique `where` (e.g. `where: { country: 'AR' }`) matched
-        //     multiple existing nodes; MERGE then fans out across all of
-        //     them, applying ON MATCH SET to every match. Almost always a
-        //     bug, never the developer's intent.
-        // Requiring at least one unique/id key forces MERGE to target at
-        // most one row.
-        const hasUniqueOrId = mergeKeyNames.some((name) => {
-            const prop = nodeDef.properties.get(name);
-            // `isGenerated` is the parser's flag for the `@id` directive;
-            // `isUnique` is the flag for `@unique`. Either is sufficient
-            // to guarantee the MERGE pattern targets at most one row.
-            return prop !== undefined && (prop.isUnique || prop.isGenerated);
-        });
-        if (!hasUniqueOrId)
-            throw new errors_1.OGMError(`upsert "where" must contain at least one property marked with @id or @unique. ` +
-                `Got [${mergeKeyNames.map((n) => `"${n}"`).join(', ')}] — none of these are unique on ${nodeDef.typeName}. ` +
-                `Without a unique key, MERGE can fan out across multiple existing nodes (applying ON MATCH SET to each) ` +
-                `or create phantom properties on typo. If you really want a non-unique merge, use create() + update().`);
+            throw new errors_1.OGMError(`upsert requires at least one scalar property in "where" for MERGE key: ` +
+                `an @id or @unique field of ${nodeDef.typeName}.`);
         lines.push(`MERGE (n:${labelStr} { ${mergeProps.join(', ')} })`);
         // ON CREATE SET — all properties from create input (scalar only)
         const createSets = [];
@@ -566,6 +559,7 @@ class MutationCompiler {
                 throw upsertRelationshipError(nodeDef, key, 'create');
             }
             (0, validation_1.assertSafePropertyName)(key, 'create property');
+            assertKnownField(nodeDef, key, 'create');
             const propDef = nodeDef.properties.get(key);
             const paramName = `onCreate_${key}`;
             const valueExpr = (0, write_coercion_1.wrapWriteExpr)(`$${paramName}`, value, propDef);
@@ -616,6 +610,7 @@ class MutationCompiler {
                 throw upsertRelationshipError(nodeDef, key, 'update');
             }
             (0, validation_1.assertSafePropertyName)(key, 'update property');
+            assertKnownField(nodeDef, key, 'update');
             const propDef = nodeDef.properties.get(key);
             const paramName = `onMatch_${key}`;
             const valueExpr = (0, write_coercion_1.wrapWriteExpr)(`$${paramName}`, value, propDef);
@@ -689,16 +684,13 @@ class MutationCompiler {
             for (const key of Object.keys(item)) {
                 if (item[key] === undefined || scalarKeys.includes(key))
                     continue;
-                if (nodeDef.relationships.has(key)) {
-                    // Only the first item's relationship fields have ever been
-                    // rejected; in later items they were (and still are) skipped
-                    // unwritten. Rejecting them everywhere would make calls that
-                    // succeed today throw — tracked as a separate, breaking change.
-                    if (index > 0)
-                        continue;
-                    throw new errors_1.OGMError(`createMany does not support relationship fields. Found: "${key}". Use create() for nested operations.`);
-                }
+                // v2.5.0 — rejected in EVERY item. Pre-2.5.0 only the first item's
+                // relationship fields were; in later items the nested input was
+                // skipped unwritten.
+                if (nodeDef.relationships.has(key))
+                    throw new errors_1.OGMError(`createMany does not support relationship fields. Found: "${key}" in data[${index}]. Use create() for nested operations.`);
                 (0, validation_1.assertSafePropertyName)(key, 'createMany property');
+                assertKnownField(nodeDef, key, 'createMany');
                 scalarKeys.push(key);
             }
         // Identify @id (generated) fields that are NOT provided in data
@@ -830,6 +822,7 @@ class MutationCompiler {
             if (value === undefined)
                 continue;
             (0, validation_1.assertSafePropertyName)(key, 'create property');
+            assertKnownField(nodeDef, key, 'create');
             const propDef = nodeDef.properties.get(key);
             const paramName = `${prefix}_${key}`;
             const valueExpr = (0, write_coercion_1.wrapWriteExpr)(`$${paramName}`, value, propDef);
@@ -1674,6 +1667,7 @@ class MutationCompiler {
                         if (val === undefined)
                             continue;
                         (0, validation_1.assertSafePropertyName)(prop, 'nested update property');
+                        assertKnownField(targetNodeDef, prop, 'nested update');
                         const nodePropDef = targetNodeDef.properties.get(prop);
                         const paramName = `${itemPrefix}_set_${prop}`;
                         setClauses.push(`${updateVar}.${(0, validation_1.escapeIdentifier)(prop)} = ${(0, write_coercion_1.wrapWriteExpr)(`$${paramName}`, val, nodePropDef)}`);
@@ -1977,6 +1971,18 @@ function unwrapAbstractCreateNode(nodeSpec, target, fieldName) {
             `e.g. { node: { ${target.members[0] ?? 'Member'}: { … } } }. Allowed: ${target.members.map((m) => `"${m}"`).join(', ')}.`);
     return [keys[0], nodeSpec[keys[0]]];
 }
+/**
+ * Reject a write key that is neither a property nor a relationship of the
+ * type (v2.5.0). Pre-2.5.0 only its spelling was checked, so a typo
+ * (`nmae`) was stored as a stray property and the intended field was left
+ * untouched — at every depth (nested creates and updates included).
+ */
+function assertKnownField(nodeDef, key, input) {
+    if (nodeDef.properties.has(key) || nodeDef.relationships.has(key))
+        return;
+    throw new errors_1.OGMError(`Unknown field "${key}" in the ${input} input of ${nodeDef.typeName}: it is neither a property nor a ` +
+        `relationship of the type. Declare it in the schema, or fix the key.`);
+}
 /**
  * MERGE writes scalars only. Pre-2.4.8 a relationship field in an upsert's
  * `create` / `update` was skipped, so its nested connect / create never