Auto-inversing and no flatten node reference

compulim · compulim · commit 7b01ed3d8cd8 · 2025-11-05T21:57:02.000Z
diff --git a/packages/core-graph/src/private/SlantGraph.spec.ts b/packages/core-graph/src/private/SlantGraph.spec.ts
@@ -159,7 +159,7 @@ scenario('SlantGraph auto-inversing', bdd => {
           },
           {
             '@id': '_:m1',
-            '@type': 'Message',
+            '@type': 'MessageLike',
             text: 'Hello, World!'
           }
         )
@@ -177,7 +177,7 @@ scenario('SlantGraph auto-inversing', bdd => {
             },
             '_:m1': {
               '@id': '_:m1',
-              '@type': ['Message'],
+              '@type': ['MessageLike'],
               isPartOf: [{ '@id': '_:c1' }],
               text: ['Hello, World!']
             }
@@ -198,7 +198,7 @@ scenario('SlantGraph auto-inversing', bdd => {
           },
           {
             '@id': '_:m1',
-            '@type': 'Message',
+            '@type': 'MessageLike',
             isPartOf: [{ '@id': '_:c1' }],
             text: 'Hello, World!'
           }
@@ -217,7 +217,7 @@ scenario('SlantGraph auto-inversing', bdd => {
             },
             '_:m1': {
               '@id': '_:m1',
-              '@type': ['Message'],
+              '@type': ['MessageLike'],
               isPartOf: [{ '@id': '_:c1' }],
               text: ['Hello, World!']
             }
@@ -226,28 +226,3 @@ scenario('SlantGraph auto-inversing', bdd => {
       )
     );
 });
-
-scenario('SlantGraph empty node', bdd => {
-  bdd
-    .given('a SlantGraph', () => new SlantGraph())
-    .when('upserting a node with @id and @type only', graph =>
-      graph.act(graph =>
-        graph.upsert({
-          '@id': '_:c1',
-          '@type': 'Conversation'
-        })
-      )
-    )
-    .then('should be upserted', graph =>
-      expect(graph.getState()).toEqual(
-        new Map(
-          Object.entries({
-            '_:c1': {
-              '@id': '_:c1',
-              '@type': ['Conversation']
-            }
-          })
-        )
-      )
-    );
-});
diff --git a/packages/core-graph/src/private/SlantGraph.ts b/packages/core-graph/src/private/SlantGraph.ts
@@ -1,10 +1,11 @@
-import { assert } from 'valibot';
+import { array, assert, fallback, parse } from 'valibot';
 import Graph, { type GraphMiddleware } from './Graph2';
 import colorNode, { SlantNodeSchema, type SlantNode } from './schemas/colorNode';
 import flattenNodeObject from './schemas/flattenNodeObject';
 import type { Identifier } from './schemas/Identifier';
 import isOfType from './schemas/isOfType';
 import { MessageNodeSchema } from './schemas/MessageNode';
+import { NodeReferenceSchema, type NodeReference } from './schemas/NodeReference';
 
 type AnyNode = Record<string, unknown> & {
   readonly '@id': Identifier;
@@ -13,7 +14,7 @@ type AnyNode = Record<string, unknown> & {
 
 const VALIDATION_SCHEMAS_BY_TYPE = new Map([['Message', MessageNodeSchema]]);
 
-const color: GraphMiddleware<AnyNode, SlantNode> = () => () => upsertingNodeMap => {
+const color: GraphMiddleware<AnyNode, SlantNode> = () => next => upsertingNodeMap => {
   const nextUpsertingNodeMap = new Map<Identifier, SlantNode>();
 
   for (const node of upsertingNodeMap.values()) {
@@ -22,10 +23,10 @@ const color: GraphMiddleware<AnyNode, SlantNode> = () => () => upsertingNodeMap
     }
   }
 
-  return nextUpsertingNodeMap;
+  return next(nextUpsertingNodeMap);
 };
 
-const validateSlantNode: GraphMiddleware<AnyNode, SlantNode> = () => () => upsertingNodeMap => {
+const validateSlantNode: GraphMiddleware<AnyNode, SlantNode> = () => next => upsertingNodeMap => {
   for (const node of upsertingNodeMap.values()) {
     assert(SlantNodeSchema, node);
 
@@ -34,12 +35,160 @@ const validateSlantNode: GraphMiddleware<AnyNode, SlantNode> = () => () => upser
     }
   }
 
-  return upsertingNodeMap as ReadonlyMap<Identifier, SlantNode>;
+  return next(upsertingNodeMap as ReadonlyMap<Identifier, SlantNode>);
 };
 
+function nodeReferenceListToIdentifierSet(nodeReferences: readonly NodeReference[]): Set<Identifier> {
+  return new Set(nodeReferences.map(ref => ref['@id']));
+}
+
+function identifierSetToNodeReferenceList(identifierSet: ReadonlySet<Identifier>): readonly NodeReference[] {
+  return Object.freeze(
+    Array.from(identifierSet.values().map(identifier => parse(NodeReferenceSchema, { '@id': identifier })))
+  );
+}
+
+const NodeReferenceListSchema = fallback(array(NodeReferenceSchema), []);
+
+// eslint-disable-next-line complexity
+function setTriplet(
+  subject: SlantNode,
+  linkType: 'hasPart' | 'isPartOf',
+  object: SlantNode,
+  operation: 'add' | 'delete'
+): readonly SlantNode[] {
+  const objectId = object['@id'];
+  const subjectId = subject['@id'];
+
+  let nextObject: SlantNode | undefined;
+  let nextSubject: SlantNode | undefined;
+
+  const objectHasPart = nodeReferenceListToIdentifierSet(object.hasPart || []);
+  const objectIsPartOf = nodeReferenceListToIdentifierSet(object.isPartOf || []);
+  const subjectHasPart = nodeReferenceListToIdentifierSet(subject.hasPart || []);
+  const subjectIsPartOf = nodeReferenceListToIdentifierSet(subject.isPartOf || []);
+
+  if (linkType === 'hasPart') {
+    if (operation === 'add') {
+      if (!subjectHasPart.has(objectId)) {
+        subjectHasPart.add(objectId);
+        nextSubject = { ...subject, hasPart: identifierSetToNodeReferenceList(subjectHasPart) };
+      }
+
+      if (!objectIsPartOf.has(subjectId)) {
+        objectIsPartOf.add(subjectId);
+        nextObject = { ...object, isPartOf: identifierSetToNodeReferenceList(objectIsPartOf) };
+      }
+    } else if (operation === 'delete') {
+      if (subjectHasPart.has(objectId)) {
+        subjectHasPart.delete(objectId);
+        nextSubject = { ...subject, hasPart: identifierSetToNodeReferenceList(subjectHasPart) };
+      }
+
+      if (objectIsPartOf.has(subjectId)) {
+        objectIsPartOf.delete(subjectId);
+        nextObject = { ...object, isPartOf: identifierSetToNodeReferenceList(objectIsPartOf) };
+      }
+    } else {
+      operation satisfies never;
+    }
+  } else if (linkType === 'isPartOf') {
+    if (operation === 'add') {
+      if (!subjectIsPartOf.has(objectId)) {
+        subjectIsPartOf.add(objectId);
+        nextSubject = { ...subject, isPartOf: identifierSetToNodeReferenceList(subjectIsPartOf) };
+      }
+
+      if (!objectHasPart.has(subjectId)) {
+        objectHasPart.add(subjectId);
+        nextObject = { ...object, hasPart: identifierSetToNodeReferenceList(objectHasPart) };
+      }
+    } else if (operation === 'delete') {
+      if (subjectIsPartOf.has(objectId)) {
+        subjectIsPartOf.delete(objectId);
+        nextSubject = { ...subject, isPartOf: identifierSetToNodeReferenceList(subjectIsPartOf) };
+      }
+
+      if (objectHasPart.has(subjectId)) {
+        objectHasPart.delete(subjectId);
+        nextObject = { ...object, hasPart: identifierSetToNodeReferenceList(objectHasPart) };
+      }
+    } else {
+      operation satisfies never;
+    }
+  } else {
+    linkType satisfies never;
+  }
+
+  return Object.freeze([nextObject, nextSubject].filter(Boolean as unknown as (node: unknown) => node is SlantNode));
+}
+
+// TODO: [P*] Review this auto-inversing middleware.
+const autoInversion: GraphMiddleware<AnyNode, SlantNode> =
+  ({ getState }) =>
+  () =>
+  upsertingNodeMap => {
+    const state = getState();
+    const nextUpsertingNodeMap = new Map<Identifier, SlantNode>(upsertingNodeMap as any);
+
+    function addToResult(...nodes: readonly SlantNode[]) {
+      for (const node of nodes) {
+        nextUpsertingNodeMap.set(node['@id'], node);
+      }
+    }
+
+    function getDirty(id: Identifier) {
+      const node = (nextUpsertingNodeMap.get(id) as SlantNode | undefined) ?? state.get(id);
+
+      if (!node) {
+        throw new Error(`Cannot find node with @id "${id}"`);
+      }
+
+      return node;
+    }
+
+    for (const [_key, node] of upsertingNodeMap) {
+      const id = node['@id'];
+
+      const existingNode = getDirty(id);
+
+      // Remove hasPart/isPartOf if the existing node does not match the upserted node.
+      if (existingNode) {
+        const removedHasPartIdSet = nodeReferenceListToIdentifierSet(existingNode.hasPart ?? []).difference(
+          nodeReferenceListToIdentifierSet(parse(NodeReferenceListSchema, node['hasPart']))
+        );
+
+        for (const removedHasPartId of removedHasPartIdSet) {
+          addToResult(...setTriplet(existingNode, 'hasPart', getDirty(removedHasPartId)!, 'delete'));
+        }
+
+        const removedIsPartOfIdSet = nodeReferenceListToIdentifierSet(existingNode.isPartOf ?? []).difference(
+          nodeReferenceListToIdentifierSet(parse(NodeReferenceListSchema, node['isPartOf']))
+        );
+
+        for (const removedIsPartOfId of removedIsPartOfIdSet) {
+          addToResult(...setTriplet(existingNode, 'isPartOf', getDirty(removedIsPartOfId)!, 'delete'));
+        }
+      }
+    }
+
+    // Add hasPart/isPartOf.
+    for (const [_, node] of upsertingNodeMap) {
+      for (const { '@id': childId } of parse(NodeReferenceListSchema, node['hasPart'])) {
+        addToResult(...setTriplet(node as SlantNode, 'hasPart', getDirty(childId), 'add'));
+      }
+
+      for (const { '@id': parentId } of parse(NodeReferenceListSchema, node['isPartOf'])) {
+        addToResult(...setTriplet(node as SlantNode, 'isPartOf', getDirty(parentId), 'add'));
+      }
+    }
+
+    return nextUpsertingNodeMap;
+  };
+
 class SlantGraph extends Graph<AnyNode, SlantNode> {
   constructor() {
-    super(color, validateSlantNode);
+    super(color, validateSlantNode, autoInversion);
   }
 }
 
diff --git a/packages/core-graph/src/private/schemas/NodeReference.ts b/packages/core-graph/src/private/schemas/NodeReference.ts
@@ -1,4 +1,4 @@
-import { array, minLength, optional, pipe, safeParse, strictObject, string, union, type InferOutput } from 'valibot';
+import { array, is, minLength, optional, pipe, strictObject, string, union, type InferOutput } from 'valibot';
 
 import { IdentifierSchema } from './Identifier';
 import freeze from './private/freeze';
@@ -26,8 +26,6 @@ const NodeReferenceSchema = pipe(
 
 type NodeReference = InferOutput<typeof NodeReferenceSchema>;
 
-function isNodeReference(nodeObject: NodeReference): nodeObject is NodeReference {
-  return safeParse(NodeReferenceSchema, nodeObject).success;
-}
+const isNodeReference = is.bind(undefined, NodeReferenceSchema);
 
 export { isNodeReference, NodeReferenceSchema, type NodeReference };
diff --git a/packages/core-graph/src/private/schemas/colorNode.ts b/packages/core-graph/src/private/schemas/colorNode.ts
@@ -141,6 +141,7 @@ const SlantNodeWithFixSchema = pipe(
  *       - `@value` could be null, if unwrapped, will be confusing as we removed nulls
  *    - Do not handle full JSON-LD spec: `@context` is an opaque string and its schema is not honored
  *    - Node reference only has `@id` and it should not contain `@type`
+ *    - Reduce confusion: node reference must not appear at the root of the flattened graph
  * - Auto-linking for Schema.org: `hasPart` and `isPartOf` are auto-inversed
  * - Keep its root: every node is compliant to JSON-LD, understood by standard parsers
  * - Debuggability: must have at least one `@type`
diff --git a/packages/core-graph/src/private/schemas/flattenNodeObject.spec.ts b/packages/core-graph/src/private/schemas/flattenNodeObject.spec.ts
@@ -195,3 +195,31 @@ scenario('flattenNodeObject()', bdd => {
       }).toThrow('Only literals, JSON literals, and plain object can be flattened');
     });
 });
+
+scenario('Reduce confusion: node reference must not appear at the root of the flattened graph', bdd => {
+  bdd
+    .given(
+      'a node with @id and @type only',
+      () =>
+        ({
+          '@id': '_:c1',
+          '@type': 'Conversation'
+        }) as const
+    )
+    .when('colored', node => {
+      try {
+        flattenNodeObject(node);
+      } catch (error) {
+        return error;
+      }
+
+      return undefined;
+    })
+    .then('should throw', (_, error) => {
+      expect(() => {
+        if (error) {
+          throw error;
+        }
+      }).toThrow('Node reference cannot be flattened');
+    });
+});
diff --git a/packages/core-graph/src/private/schemas/flattenNodeObject.ts b/packages/core-graph/src/private/schemas/flattenNodeObject.ts
@@ -1,12 +1,12 @@
 // TODO: [P0] This flattening can probably fold into `colorNode()` as it has slanted view of the system.
 
-import { check, object, optional, parse, pipe, safeParse } from 'valibot';
+import { assert, check, looseObject, object, optional, parse, pipe, safeParse } from 'valibot';
 
 import { FlatNodeObjectSchema, type FlatNodeObject, type FlatNodeObjectPropertyValue } from './FlatNodeObject';
-import { IdentifierSchema } from './Identifier';
+import { IdentifierSchema, type Identifier } from './Identifier';
 import { JSONLiteralSchema, type JSONLiteral } from './JSONLiteral';
 import { LiteralSchema, type Literal } from './Literal';
-import { NodeReferenceSchema, type NodeReference } from './NodeReference';
+import { isNodeReference, NodeReferenceSchema, type NodeReference } from './NodeReference';
 import isPlainObject from './private/isPlainObject';
 
 type FlattenNodeObjectInput = Literal | (object & { '@id'?: string });
@@ -155,9 +155,15 @@ type FlattenNodeObjectReturnValue = {
  * @returns {FlattenNodeObjectReturnValue} A graph and a node reference.
  */
 function flattenNodeObject(input: FlattenNodeObjectInput): FlattenNodeObjectReturnValue {
-  parse(object({}), input);
+  assert(
+    pipe(
+      looseObject({}),
+      check(value => !isNodeReference(value), 'Node reference cannot be flattened')
+    ),
+    input
+  );
 
-  const graph = new Map<string, FlatNodeObject>();
+  const graph = new Map<Identifier, FlatNodeObject>();
   const refMap = new Map<object, NodeReference>();
   const output = flattenNodeObject_(input, graph, refMap);
 
