synstate 2.0.1 → 3.0.0

package/src/core/base/circular-dependency.test.mts

@@ -0,0 +1,322 @@
+/* eslint-disable functional/immutable-data */
+import { Optional } from 'ts-data-forge';
+import { combine, merge } from '../combine/index.mjs';
+import { source } from '../create/index.mjs';
+import { map } from '../operators/index.mjs';
+import {
+  createAsyncChildObservable,
+  createSyncChildObservable,
+} from './create-child-observable.mjs';
+import { createTryUpdateNotImplemented } from './create-observable-base.mjs';
+import { createRootObservable } from './create-root-observable.mjs';
+
+describe('circular dependency detection', () => {
+  describe('cycle in ancestor graph', () => {
+    test('should throw when parent chain contains a cycle (A -> B -> A)', () => {
+      const root = createRootObservable(
+        { initialValue: Optional.some(0) },
+        () => ({}),
+      );
+
+      const childA = createSyncChildObservable(
+        {
+          parents: [root],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      const childB = createSyncChildObservable(
+        {
+          parents: [childA],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      // Mutate childA.parents to create a cycle: childA -> childB -> childA
+      Object.defineProperty(childA, 'parents', {
+        value: [childB],
+        writable: false,
+        configurable: true,
+      });
+
+      expect(() => {
+        createSyncChildObservable(
+          {
+            parents: [childA],
+            initialValue: Optional.some(0),
+          },
+          createTryUpdateNotImplemented,
+        );
+      }).toThrow(
+        'Circular dependency detected in observable graph: a child observable cannot be its own ancestor.',
+      );
+    });
+
+    test('should throw when AsyncChildObservable parent chain contains a cycle', () => {
+      const root = createRootObservable(
+        { initialValue: Optional.some(0) },
+        () => ({}),
+      );
+
+      const childA = createAsyncChildObservable(
+        {
+          parents: [root],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      const childB = createSyncChildObservable(
+        {
+          parents: [childA],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      // Create cycle: childA -> childB -> childA
+      Object.defineProperty(childA, 'parents', {
+        value: [childB],
+        writable: false,
+        configurable: true,
+      });
+
+      expect(() => {
+        createAsyncChildObservable(
+          {
+            parents: [childA],
+            initialValue: Optional.some(0),
+          },
+          createTryUpdateNotImplemented,
+        );
+      }).toThrow(
+        'Circular dependency detected in observable graph: a child observable cannot be its own ancestor.',
+      );
+    });
+
+    test('should throw when a cycle exists through a chain of 3 observables', () => {
+      const root = createRootObservable(
+        { initialValue: Optional.some(0) },
+        () => ({}),
+      );
+
+      const childA = createSyncChildObservable(
+        {
+          parents: [root],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      const childB = createSyncChildObservable(
+        {
+          parents: [childA],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      const childC = createSyncChildObservable(
+        {
+          parents: [childB],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      // Create cycle: childA -> childC -> childB -> childA
+      Object.defineProperty(childA, 'parents', {
+        value: [childC],
+        writable: false,
+        configurable: true,
+      });
+
+      expect(() => {
+        createSyncChildObservable(
+          {
+            parents: [childA],
+            initialValue: Optional.some(0),
+          },
+          createTryUpdateNotImplemented,
+        );
+      }).toThrow(
+        'Circular dependency detected in observable graph: a child observable cannot be its own ancestor.',
+      );
+    });
+
+    test('should throw when the new child itself appears as an ancestor', () => {
+      const root = createRootObservable(
+        { initialValue: Optional.some(0) },
+        () => ({}),
+      );
+
+      const childA = createSyncChildObservable(
+        {
+          parents: [root],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      // Make childA's parents reference childA itself (self-loop)
+      Object.defineProperty(childA, 'parents', {
+        value: [childA],
+        writable: false,
+        configurable: true,
+      });
+
+      expect(() => {
+        createSyncChildObservable(
+          {
+            parents: [childA],
+            initialValue: Optional.some(0),
+          },
+          createTryUpdateNotImplemented,
+        );
+      }).toThrow(
+        'Circular dependency detected in observable graph: a child observable cannot be its own ancestor.',
+      );
+    });
+  });
+
+  describe('valid DAG patterns should not throw', () => {
+    test('diamond dependency is not a cycle', () => {
+      const root = createRootObservable(
+        { initialValue: Optional.some(0) },
+        () => ({}),
+      );
+
+      const left = createSyncChildObservable(
+        {
+          parents: [root],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      const right = createSyncChildObservable(
+        {
+          parents: [root],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      // Diamond: root -> left -> combined, root -> right -> combined
+      expect(() => {
+        createSyncChildObservable(
+          {
+            parents: [left, right],
+            initialValue: Optional.some(0),
+          },
+          createTryUpdateNotImplemented,
+        );
+      }).not.toThrow();
+    });
+
+    test('linear chain is not a cycle', () => {
+      const root = createRootObservable(
+        { initialValue: Optional.some(0) },
+        () => ({}),
+      );
+
+      const a = createSyncChildObservable(
+        {
+          parents: [root],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      const b = createSyncChildObservable(
+        {
+          parents: [a],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      expect(() => {
+        createSyncChildObservable(
+          {
+            parents: [b],
+            initialValue: Optional.some(0),
+          },
+          createTryUpdateNotImplemented,
+        );
+      }).not.toThrow();
+    });
+
+    test('multiple roots converging is not a cycle', () => {
+      const root1 = createRootObservable(
+        { initialValue: Optional.some(1) },
+        () => ({}),
+      );
+
+      const root2 = createRootObservable(
+        { initialValue: Optional.some(2) },
+        () => ({}),
+      );
+
+      const child1 = createSyncChildObservable(
+        {
+          parents: [root1],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      const child2 = createSyncChildObservable(
+        {
+          parents: [root2],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      expect(() => {
+        createSyncChildObservable(
+          {
+            parents: [child1, child2],
+            initialValue: Optional.some(0),
+          },
+          createTryUpdateNotImplemented,
+        );
+      }).not.toThrow();
+    });
+
+    test('combine with source observables works', () => {
+      const a$ = source<number>();
+
+      const b$ = source<string>();
+
+      expect(() => {
+        combine([a$, b$]);
+      }).not.toThrow();
+    });
+
+    test('combine with derived observables works', () => {
+      const a$ = source<number>();
+
+      const b$ = source<number>();
+
+      const mapped$ = a$.pipe(map((x) => x * 2));
+
+      expect(() => {
+        combine([mapped$, b$]);
+      }).not.toThrow();
+    });
+
+    test('merge with source observables works', () => {
+      const a$ = source<number>();
+
+      const b$ = source<number>();
+
+      expect(() => {
+        merge([a$, b$]);
+      }).not.toThrow();
+    });
+  });
+});

package/src/core/base/create-child-observable.mts

@@ -0,0 +1,340 @@
+import { Arr, type Optional, type Some } from 'ts-data-forge';
+import { type MutableSet } from 'ts-type-forge';
+import {
+  isChildObservable,
+  isManagerObservable,
+  type AsyncChildObservable,
+  type ChildObservable,
+  type InitializedSyncChildObservable,
+  type NonEmptyUnknownList,
+  type Observable,
+  type ObservableId,
+  type SyncChildObservable,
+  type UpdateToken,
+  type Wrap,
+} from '../types/index.mjs';
+import { maxDepth } from '../utils/index.mjs';
+import {
+  assembleObservable,
+  createManagerObservableParts,
+  createObservableBaseHandle,
+} from './create-observable-base.mjs';
+
+/**
+ * The internal tools a sync-child leaf factory (`map`, `filter`, `zip`, …)
+ * receives — the replacement for the `protected` methods a subclass of
+ * `SyncChildObservableClass` used to inherit.
+ */
+export type SyncChildObservableTools<A> = Readonly<{
+  /** Emits `nextValue` under `updateToken` and notifies subscribers. */
+  setNext: (nextValue: A, updateToken: UpdateToken) => void;
+
+  getSnapshot: () => Optional<A>;
+
+  /** Completes this observable (leaf teardown included). */
+  complete: () => void;
+}>;
+
+/**
+ * The internal tools an async-child leaf factory (`debounce`, `switchMap`, …)
+ * receives. Async children additionally start their own update propagation.
+ */
+export type AsyncChildObservableTools<A> = Readonly<{
+  /** Emits `nextValue` and propagates the update to all descendants. */
+  startUpdate: (nextValue: A) => void;
+}> &
+  SyncChildObservableTools<A>;
+
+type ChildObservableConfigBase<P extends NonEmptyUnknownList> = Readonly<{
+  parents: Wrap<P>;
+
+  depth?: number;
+
+  /**
+   * Leaf teardown (clear timers, unsubscribe inner observables, …), run at
+   * the beginning of `complete()` — the closure replacement for
+   * `override complete() { teardown(); super.complete(); }`.
+   */
+  onComplete?: () => void;
+}>;
+
+export type ChildObservableConfig<
+  A,
+  P extends NonEmptyUnknownList,
+> = ChildObservableConfigBase<P> &
+  Readonly<{
+    initialValue: Optional<A>;
+  }>;
+
+export type InitializedChildObservableConfig<
+  A,
+  P extends NonEmptyUnknownList,
+> = ChildObservableConfigBase<P> &
+  Readonly<{
+    initialValue: Some<A>;
+  }>;
+
+/**
+ * Creates a sync-child observable — the classless replacement for extending
+ * `SyncChildObservableClass`.
+ *
+ * `createTryUpdate` receives the internal tools and returns the `tryUpdate`
+ * implementation (the former `override tryUpdate`). It runs during
+ * construction, before the observable is registered to its parents; leaf
+ * state can live either in the enclosing factory scope or inside the
+ * `createTryUpdate` closure.
+ */
+export const createSyncChildObservable = <A, P extends NonEmptyUnknownList>(
+  {
+    parents,
+    depth = 1 + maxDepth(parents),
+    initialValue,
+    onComplete,
+  }: ChildObservableConfig<A, P>,
+  createTryUpdate: (
+    tools: SyncChildObservableTools<A>,
+  ) => (updateToken: UpdateToken) => void,
+): SyncChildObservable<A, P> => {
+  const handle = createObservableBaseHandle<A>(initialValue);
+
+  const complete = (): void => {
+    onComplete?.();
+
+    handle.completeBase();
+
+    // propagate to parents
+    for (const par of parents) {
+      par.tryComplete();
+    }
+  };
+
+  const tryComplete = (): void => {
+    tryCompleteChild({
+      hasSubscriber: handle.hasSubscriber(),
+      hasActiveChild: handle.hasActiveChild(),
+      parents,
+      complete,
+    });
+  };
+
+  const tryUpdate = createTryUpdate({
+    setNext: handle.setNext,
+    getSnapshot: handle.getSnapshot,
+    complete,
+  });
+
+  const observable: SyncChildObservable<A, P> = assembleObservable({
+    kind: 'sync child',
+    depth,
+    handle,
+    tryUpdate,
+    tryComplete,
+    complete,
+    extra: { parents },
+  });
+
+  registerChild(observable, parents);
+
+  return observable;
+};
+
+/**
+ * Creates a sync-child observable that always holds a value.
+ *
+ * Runtime-wise this is exactly `createSyncChildObservable`; only the types of
+ * `getSnapshot` and `pipe` are narrowed, which is what the
+ * `InitializedSyncChildObservableClass` overrides existed for.
+ */
+export const createInitializedSyncChildObservable = <
+  A,
+  P extends NonEmptyUnknownList,
+>(
+  config: InitializedChildObservableConfig<A, P>,
+  createTryUpdate: (
+    tools: SyncChildObservableTools<A>,
+  ) => (updateToken: UpdateToken) => void,
+): InitializedSyncChildObservable<A, P> => {
+  const observable = createSyncChildObservable<A, P>(config, createTryUpdate);
+
+  return (
+    // `getSnapshot` always returns `Some` here: `initialValue` is a `Some` and
+    // `setNext` only ever stores a `Some`.
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    observable as InitializedSyncChildObservable<A, P>
+  );
+};
+
+/**
+ * Creates an async-child observable — the classless replacement for extending
+ * `AsyncChildObservableClass`. See {@link createSyncChildObservable} for the
+ * `createTryUpdate` contract.
+ */
+export const createAsyncChildObservable = <A, P extends NonEmptyUnknownList>(
+  {
+    parents,
+    depth = 1 + maxDepth(parents),
+    initialValue,
+    onComplete,
+  }: ChildObservableConfig<A, P>,
+  createTryUpdate: (
+    tools: AsyncChildObservableTools<A>,
+  ) => (updateToken: UpdateToken) => void,
+): AsyncChildObservable<A, P> => {
+  const handle = createObservableBaseHandle<A>(initialValue);
+
+  const { addDescendant, startUpdate } = createManagerObservableParts(handle);
+
+  const complete = (): void => {
+    onComplete?.();
+
+    handle.completeBase();
+
+    // propagate to parents
+    for (const par of parents) {
+      par.tryComplete();
+    }
+  };
+
+  const tryComplete = (): void => {
+    tryCompleteChild({
+      hasSubscriber: handle.hasSubscriber(),
+      hasActiveChild: handle.hasActiveChild(),
+      parents,
+      complete,
+    });
+  };
+
+  const tryUpdate = createTryUpdate({
+    setNext: handle.setNext,
+    getSnapshot: handle.getSnapshot,
+    complete,
+    startUpdate,
+  });
+
+  const observable: AsyncChildObservable<A, P> = assembleObservable({
+    kind: 'async child',
+    depth,
+    handle,
+    tryUpdate,
+    tryComplete,
+    complete,
+    extra: { parents, addDescendant },
+  });
+
+  registerChild(observable, parents);
+
+  return observable;
+};
+
+/* helpers */
+
+/**
+ * Detects circular dependencies by walking the full ancestor chain of the
+ * given parents and checking whether `child` already appears among them.
+ *
+ * @throws {Error} if a circular dependency is detected
+ */
+const hasCircularDependencyFrom = (
+  node: Observable<unknown>,
+  mut_visited: MutableSet<ObservableId>,
+  mut_inPath: MutableSet<ObservableId>,
+): boolean => {
+  if (mut_inPath.has(node.id)) return true;
+
+  if (mut_visited.has(node.id)) return false;
+
+  mut_visited.add(node.id);
+
+  mut_inPath.add(node.id);
+
+  if (isChildObservable(node)) {
+    for (const parent of node.parents) {
+      if (hasCircularDependencyFrom(parent, mut_visited, mut_inPath)) {
+        return true;
+      }
+    }
+  }
+
+  mut_inPath.delete(node.id);
+
+  return false;
+};
+
+const detectCircularDependency = (
+  child: ChildObservable<unknown>,
+  parents: readonly Observable<unknown>[],
+): void => {
+  const mut_visited = new Set<ObservableId>();
+
+  const mut_inPath = new Set<ObservableId>([child.id]);
+
+  for (const parent of parents) {
+    if (hasCircularDependencyFrom(parent, mut_visited, mut_inPath)) {
+      throw new Error(
+        'Circular dependency detected in observable graph: a child observable cannot be its own ancestor.',
+      );
+    }
+  }
+};
+
+/**
+ * Registers `child` to its parents and to all reachable manager observables.
+ * Runs after the child object is fully assembled, so parents only ever hold a
+ * reference to the final composed object (the class version registered `this`
+ * from inside the constructor instead).
+ */
+const registerChild = <A,>(
+  child: ChildObservable<A>,
+  parents: ChildObservable<A>['parents'],
+): void => {
+  detectCircularDependency(child, parents);
+
+  for (const p of parents) {
+    p.addChild(child);
+  }
+
+  // register child to all reachable ManagerObservables
+  const mut_rest = Array.from(parents);
+
+  while (Arr.isNonEmpty(mut_rest)) {
+    const p = mut_rest.pop();
+
+    if (p === undefined) break;
+
+    if (isManagerObservable(p)) {
+      p.addDescendant(child);
+    } else {
+      // trace back dependency graph
+      mut_rest.push(...p.parents);
+    }
+  }
+};
+
+const tryCompleteChild = <A,>({
+  hasSubscriber,
+  hasActiveChild,
+  parents,
+  complete,
+}: Readonly<{
+  hasSubscriber: boolean;
+  hasActiveChild: boolean;
+  parents: ChildObservable<A>['parents'];
+  complete: () => void;
+}>): void => {
+  // If there is no working parent node
+  if (parents.every((r) => r.isCompleted)) {
+    complete();
+
+    return;
+  }
+
+  // If there are no active child node
+  if (!hasSubscriber && !hasActiveChild) {
+    complete();
+  }
+
+  // propagate to parents
+  for (const par of parents) {
+    par.tryComplete();
+  }
+};