@dxos/app-graph 0.8.4-main.72ec0f3 → 0.8.4-main.74a063c4e0

package/src/util.ts

@@ -0,0 +1,95 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+
+import * as Node from './node';
+
+// PRIMARY separates top-level components (e.g., node ID from relation) in compound string keys used within the app-graph package.
+const PRIMARY = '\u0001';
+
+// SECONDARY separates sub-components within an encoded value (e.g., relation kind from direction) in the same context.
+const SECONDARY = '\u0002';
+
+// PATH separates segments in qualified node IDs (e.g., parent path from local segment).
+const PATH = '/';
+
+/** Join parts with the primary separator. */
+export const primaryKey = (...parts: string[]): string => parts.join(PRIMARY);
+
+/** Split a key on the primary separator. */
+export const primaryParts = (key: string): string[] => key.split(PRIMARY);
+
+/** Join parts with the secondary separator. */
+export const secondaryKey = (...parts: string[]): string => parts.join(SECONDARY);
+
+/** Split a key on the secondary separator. */
+export const secondaryParts = (key: string): string[] => key.split(SECONDARY);
+
+/**
+ * Normalize a relation input to a full Relation object.
+ */
+export const normalizeRelation = (relation?: Node.RelationInput): Node.Relation =>
+  relation == null ? Node.childRelation() : typeof relation === 'string' ? Node.relation(relation) : relation;
+
+/**
+ * Shallow-compare two values: same reference, or same own-keys with === values.
+ */
+export const shallowEqual = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true;
+  if (a == null || b == null || typeof a !== 'object' || typeof b !== 'object') return false;
+  const keysA = Object.keys(a as Record<string, unknown>);
+  const keysB = Object.keys(b as Record<string, unknown>);
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+  return keysA.every((k) => (a as Record<string, unknown>)[k] === (b as Record<string, unknown>)[k]);
+};
+
+/**
+ * Returns true if two NodeArg arrays are semantically identical (same id, type, data, properties per index).
+ */
+export const nodeArgsUnchanged = (prev: Node.NodeArg<any>[], next: Node.NodeArg<any>[]): boolean => {
+  if (prev.length !== next.length) {
+    return false;
+  }
+
+  return prev.every((prevNode, idx) => {
+    const nextNode = next[idx];
+    return (
+      prevNode.id === nextNode.id &&
+      prevNode.type === nextNode.type &&
+      shallowEqual(prevNode.data, nextNode.data) &&
+      shallowEqual(prevNode.properties, nextNode.properties)
+    );
+  });
+};
+
+/**
+ * Build a qualified node ID by joining path segments.
+ */
+export const qualifyId = (parentId: string, ...segmentIds: string[]): string => [parentId, ...segmentIds].join(PATH);
+
+/**
+ * Validate that a segment ID does not contain the path separator.
+ */
+export const validateSegmentId = (id: string): void => {
+  invariant(!id.includes(PATH), `Node segment ID must not contain '${PATH}': ${id}`);
+};
+
+/**
+ * Extract the parent qualified ID (everything before the last path separator).
+ * Returns undefined for IDs with no parent (single segment).
+ */
+export const getParentId = (qualifiedId: string): string | undefined => {
+  const lastSlash = qualifiedId.lastIndexOf(PATH);
+  return lastSlash > 0 ? qualifiedId.slice(0, lastSlash) : undefined;
+};
+
+/**
+ * Extract the last segment of a qualified ID.
+ */
+export const getSegmentId = (qualifiedId: string): string => {
+  return qualifiedId.split(PATH).pop() ?? qualifiedId;
+};

package/dist/types/src/experimental/graph-projections.test.d.ts

@@ -1,25 +0,0 @@
-type Cb = () => void;
-interface Query {
-    id?: string[];
-    typename?: string[];
-}
-/**
- * Lazy query result that can be executed.
- * Does not run without the run function being called.
- */
-interface QueryResult<T> {
-    /**
-     * Execute the query and subscribe to the result.
-     * @param next Called at least once with the first value (maybe synchronously) and then for every subsequent update.
-     * @param error Called on error. `next` is never called after that.
-     * @returns Function to dispose the query and unsubscribe.
-     */
-    run(onData: (value?: T[]) => void, onError: (err: Error) => void): Cb;
-}
-declare const QueryResult: Readonly<{
-    fromPromise: <T>(run: (onDispose: (cb: Cb) => void) => Promise<T[]>) => QueryResult<T>;
-}>;
-interface _Resolver<T> {
-    query(query: Query): QueryResult<T>;
-}
-//# sourceMappingURL=graph-projections.test.d.ts.map

package/dist/types/src/experimental/graph-projections.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"graph-projections.test.d.ts","sourceRoot":"","sources":["../../../../src/experimental/graph-projections.test.ts"],"names":[],"mappings":"AAIA,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC;AAErB,UAAU,KAAK;IACb,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;GAGG;AACH,UAAU,WAAW,CAAC,CAAC;IACrB;;;;;OAKG;IACH,GAAG,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,KAAK,IAAI,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,EAAE,CAAC;CACvE;AAED,QAAA,MAAM,WAAW;kBACD,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,IAAI,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,KAAG,WAAW,CAAC,CAAC,CAAC;EAyBpF,CAAC;AAEH,UAAU,SAAS,CAAC,CAAC;IACnB,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;CACrC"}

package/dist/types/src/signals-integration.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=signals-integration.test.d.ts.map

package/dist/types/src/signals-integration.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"signals-integration.test.d.ts","sourceRoot":"","sources":["../../../src/signals-integration.test.ts"],"names":[],"mappings":""}

package/dist/types/src/testing.d.ts

@@ -1,5 +0,0 @@
-import { Atom } from '@effect-atom/atom-react';
-import { type AnyEchoObject } from '@dxos/echo/internal';
-import { type QueryResult } from '@dxos/echo-db';
-export declare const atomFromQuery: <T extends AnyEchoObject>(query: QueryResult<T>) => Atom.Atom<T[]>;
-//# sourceMappingURL=testing.d.ts.map

package/dist/types/src/testing.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../../src/testing.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAE/C,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,aAAa,EAAE,OAAO,WAAW,CAAC,CAAC,CAAC,KAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAU3F,CAAC"}

package/src/experimental/graph-projections.test.ts

@@ -1,56 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-type Cb = () => void;
-
-interface Query {
-  id?: string[];
-  typename?: string[];
-}
-
-/**
- * Lazy query result that can be executed.
- * Does not run without the run function being called.
- */
-interface QueryResult<T> {
-  /**
-   * Execute the query and subscribe to the result.
-   * @param next Called at least once with the first value (maybe synchronously) and then for every subsequent update.
-   * @param error Called on error. `next` is never called after that.
-   * @returns Function to dispose the query and unsubscribe.
-   */
-  run(onData: (value?: T[]) => void, onError: (err: Error) => void): Cb;
-}
-
-const QueryResult = Object.freeze({
-  fromPromise: <T>(run: (onDispose: (cb: Cb) => void) => Promise<T[]>): QueryResult<T> => {
-    return {
-      run: (onData, onError) => {
-        const cbs: Cb[] = [];
-        let disposed = false;
-        const dispose = () => {
-          cbs.forEach((cb) => cb());
-          disposed = true;
-        };
-        run((cb) => (disposed ? cb() : cbs.push(cb))).then(
-          (data) => {
-            if (disposed) {
-              return;
-            }
-            onData(data);
-          },
-          (err) => {
-            dispose();
-            onError(err);
-          },
-        );
-        return dispose;
-      },
-    };
-  },
-});
-
-interface _Resolver<T> {
-  query(query: Query): QueryResult<T>;
-}

package/src/signals-integration.test.ts

@@ -1,219 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { Atom, Registry } from '@effect-atom/atom-react';
-import { signal } from '@preact/signals-core';
-import { afterEach, beforeEach, describe, expect, onTestFinished, test } from 'vitest';
-
-import { Trigger } from '@dxos/async';
-import { Obj, Type } from '@dxos/echo';
-import { Ref } from '@dxos/echo/internal';
-import { Filter } from '@dxos/echo-db';
-import { EchoTestBuilder } from '@dxos/echo-db/testing';
-import { registerSignalsRuntime } from '@dxos/echo-signals';
-
-import { ROOT_ID } from './graph';
-import { GraphBuilder, atomFromSignal, createExtension } from './graph-builder';
-import { atomFromQuery } from './testing';
-
-registerSignalsRuntime();
-
-const EXAMPLE_TYPE = 'dxos.org/type/example';
-
-describe('signals integration', () => {
-  test('creating atom from signal', () => {
-    const registry = Registry.make();
-    const state = signal<number>(0);
-    const value = atomFromSignal(() => state.value);
-    const inline = Atom.make((get) => {
-      // NOTE: This will create a new atom instance each time.
-      // This test is verifying that this behaves the same as using a stable atom instance.
-      // The parent will remain subscribed to one instance until the new one is created.
-      // The old one will then be garbage collected because it is no longer referenced.
-      const atom = atomFromSignal(() => get(value));
-      return get(atom);
-    });
-
-    let count = 0;
-    const cancel = registry.subscribe(value, (value) => {
-      count = value;
-    });
-    onTestFinished(() => cancel());
-
-    let inlineCount = 0;
-    const inlineCancel = registry.subscribe(inline, (value) => {
-      inlineCount = value;
-    });
-    onTestFinished(() => inlineCancel());
-
-    registry.get(value);
-    registry.get(inline);
-    expect(count).to.eq(0);
-    expect(inlineCount).to.eq(0);
-
-    state.value = 1;
-    expect(count).to.eq(1);
-    expect(inlineCount).to.eq(1);
-
-    state.value = 2;
-    expect(count).to.eq(2);
-    expect(inlineCount).to.eq(2);
-  });
-
-  describe('echo', () => {
-    let dbBuilder: EchoTestBuilder;
-
-    beforeEach(async () => {
-      dbBuilder = await new EchoTestBuilder().open();
-    });
-
-    afterEach(async () => {
-      await dbBuilder.close();
-    });
-
-    test('atom references are loaded lazily and receive signal notifications', async () => {
-      const registry = Registry.make();
-      await using peer = await dbBuilder.createPeer();
-
-      let outerId: string;
-      {
-        await using db = await peer.createDatabase();
-        const inner = db.add({ name: 'inner' });
-        const outer = db.add({ inner: Ref.make(inner) });
-        outerId = outer.id;
-        await db.flush();
-      }
-
-      await peer.reload();
-      {
-        await using db = await peer.openLastDatabase();
-        const outer = (await db.query(Filter.ids(outerId)).first()) as any;
-        const innerAtom = atomFromSignal(() => outer.inner.target);
-        const loaded = new Trigger();
-
-        let count = 0;
-        const cancel = registry.subscribe(innerAtom, (inner) => {
-          count++;
-          if (inner) {
-            loaded.wake();
-          }
-        });
-
-        onTestFinished(() => cancel());
-
-        expect(registry.get(innerAtom)).to.eq(undefined);
-        expect(count).to.eq(1);
-
-        await loaded.wait();
-        expect(registry.get(innerAtom)).to.include({ name: 'inner' });
-        expect(count).to.eq(2);
-      }
-    });
-
-    test('references graph builder', async () => {
-      const registry = Registry.make();
-      await using peer = await dbBuilder.createPeer();
-
-      let outerId, innerId: string;
-      {
-        await using db = await peer.createDatabase();
-        const inner = db.add({ name: 'inner' });
-        const outer = db.add({ inner: Ref.make(inner) });
-        innerId = inner.id;
-        outerId = outer.id;
-        await db.flush();
-      }
-
-      await peer.reload();
-
-      {
-        await using db = await peer.openLastDatabase();
-        const outer = (await db.query(Filter.ids(outerId)).first()) as any;
-        const innerAtom = atomFromSignal(() => outer.inner.target);
-        const inner = registry.get(innerAtom);
-        expect(inner).to.eq(undefined);
-
-        const builder = new GraphBuilder({ registry });
-        builder.addExtension(
-          createExtension({
-            id: 'outbound-connector',
-            connector: () =>
-              Atom.make((get) => {
-                const inner = get(innerAtom) as any;
-                return inner ? [{ id: inner.id, type: EXAMPLE_TYPE, data: inner.name }] : [];
-              }),
-          }),
-        );
-
-        const graph = builder.graph;
-
-        const loaded = new Trigger();
-        let count = 0;
-        const cancel = registry.subscribe(graph.connections(ROOT_ID), (nodes) => {
-          count++;
-          if (nodes.length > 0) {
-            loaded.wake();
-          }
-        });
-        onTestFinished(() => cancel());
-        registry.get(graph.connections(ROOT_ID));
-        expect(count).to.eq(1);
-
-        graph.expand(ROOT_ID);
-        await loaded.wait();
-        expect(count).to.eq(2);
-
-        const nodes = registry.get(graph.connections(ROOT_ID));
-        expect(nodes).has.length(1);
-        expect(nodes[0].id).to.eq(innerId);
-        expect(nodes[0].data).to.eq('inner');
-      }
-    });
-
-    test('query graph builder', async () => {
-      const registry = Registry.make();
-      await using peer = await dbBuilder.createPeer();
-      await using db = await peer.createDatabase();
-      db.add(Obj.make(Type.Expando, { name: 'a' }));
-      db.add(Obj.make(Type.Expando, { name: 'b' }));
-
-      const builder = new GraphBuilder({ registry });
-      builder.addExtension(
-        createExtension({
-          id: 'expando',
-          connector: () => {
-            const query = db.query(Filter.type(Type.Expando));
-
-            return Atom.make((get) => {
-              const objects = get(atomFromQuery(query));
-              return objects.map((object) => ({ id: object.id, type: EXAMPLE_TYPE, data: object.name }));
-            });
-          },
-        }),
-      );
-
-      const graph = builder.graph;
-      let count = 0;
-      const cancel = registry.subscribe(graph.connections(ROOT_ID), (nodes) => {
-        count = nodes.length;
-      });
-      onTestFinished(() => cancel());
-
-      registry.get(graph.connections(ROOT_ID));
-      expect(count).to.eq(0);
-
-      graph.expand(ROOT_ID);
-      expect(count).to.eq(2);
-
-      const object = db.add(Obj.make(Type.Expando, { name: 'c' }));
-      await db.flush();
-      expect(count).to.eq(3);
-
-      // NOTE: This graph builder is not reactive to the object update.
-      object.name = 'updated';
-      await db.flush();
-      expect(count).to.eq(3);
-    });
-  });
-});

package/src/testing.ts

@@ -1,20 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { Atom } from '@effect-atom/atom-react';
-
-import { type AnyEchoObject } from '@dxos/echo/internal';
-import { type QueryResult } from '@dxos/echo-db';
-
-export const atomFromQuery = <T extends AnyEchoObject>(query: QueryResult<T>): Atom.Atom<T[]> => {
-  return Atom.make((get) => {
-    const unsubscribe = query.subscribe((result) => {
-      get.setSelf(result.objects);
-    });
-
-    get.addFinalizer(() => unsubscribe());
-
-    return query.objects;
-  });
-};