synstate 0.1.2 → 1.0.1

package/src/core/class/child-observable-class.mts

@@ -1,5 +1,7 @@
-import { Arr } from 'ts-data-forge';
+import { Arr, type Some } from 'ts-data-forge';
+import { type MutableSet } from 'ts-type-forge';
 import {
+  isChildObservable,
   isManagerObservable,
   type AsyncChildObservable,
   type ChildObservable,
@@ -14,13 +16,64 @@ import {
   type WithInitialValueOperator,
   type Wrap,
 } from '../types/index.mjs';
-import { binarySearch, issueUpdaterSymbol, maxDepth } from '../utils/index.mjs';
+import { binarySearch, issueUpdateToken, maxDepth } from '../utils/index.mjs';
 import { ObservableBaseClass } from './observable-base-class.mjs';
 
+/**
+ * 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.',
+      );
+    }
+  }
+};
+
 const registerChild = <A,>(
   child: ChildObservable<A>,
   parents: ChildObservable<A>['parents'],
 ): void => {
+  detectCircularDependency(child, parents);
+
   for (const p of parents) {
     p.addChild(child);
   }
@@ -76,7 +129,7 @@ export class AsyncChildObservableClass<A, const P extends NonEmptyUnknownList>
   implements AsyncChildObservable<A, P>
 {
   readonly parents;
-  #mut_procedure: readonly ChildObservable<unknown>[];
+  #mut_propagationOrder: readonly ChildObservable<unknown>[];
   protected readonly descendantsIdSet: MutableSet<ObservableId>;
 
   constructor({
@@ -96,7 +149,7 @@ export class AsyncChildObservableClass<A, const P extends NonEmptyUnknownList>
 
     this.parents = parents;
 
-    this.#mut_procedure = [];
+    this.#mut_propagationOrder = [];
 
     this.descendantsIdSet = new Set<ObservableId>();
 
@@ -110,20 +163,24 @@ export class AsyncChildObservableClass<A, const P extends NonEmptyUnknownList>
     this.descendantsIdSet.add(child.id);
 
     const insertPos = binarySearch(
-      this.#mut_procedure.map((a) => a.depth),
+      this.#mut_propagationOrder.map((a) => a.depth),
       child.depth,
     );
 
-    this.#mut_procedure = Arr.toInserted(this.#mut_procedure, insertPos, child);
+    this.#mut_propagationOrder = Arr.toInserted(
+      this.#mut_propagationOrder,
+      insertPos,
+      child,
+    );
   }
 
   startUpdate(nextValue: A): void {
-    const updaterSymbol = issueUpdaterSymbol();
+    const updateToken = issueUpdateToken();
 
-    this.setNext(nextValue, updaterSymbol);
+    this.setNext(nextValue, updateToken);
 
-    for (const p of this.#mut_procedure) {
-      p.tryUpdate(updaterSymbol);
+    for (const p of this.#mut_propagationOrder) {
+      p.tryUpdate(updateToken);
     }
   }
 
@@ -224,9 +281,6 @@ export class InitializedSyncChildObservableClass<
 
   override pipe<B>(operator: Operator<A, B>): Observable<B>;
   override pipe<B>(operator: Operator<A, B>): Observable<B> {
-    return operator(
-      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-      this as unknown as InitializedObservable<A>,
-    );
+    return operator(this);
   }
 }

package/src/core/class/circular-dependency-comparison.test.mts

@@ -0,0 +1,142 @@
+/**
+ * Comparison tests: how SynState, RxJS, and Jotai handle circular dependencies.
+ *
+ * - SynState: detects cycles at construction time and throws a clear error.
+ * - RxJS: pipe() always returns a new Observable, so static cycles cannot be
+ *   expressed through the public API. No detection is needed or provided.
+ * - Jotai: circular atom definitions are silently accepted. A cycle manifests
+ *   only at read time as a `Maximum call stack size exceeded` error.
+ */
+/* eslint-disable functional/immutable-data */
+/* eslint-disable no-new */
+import { type Atom, atom, createStore } from 'jotai';
+import { BehaviorSubject, combineLatest, map as rxMap } from 'rxjs';
+import { Optional } from 'ts-data-forge';
+import { combine } from '../combine/index.mjs';
+import { source } from '../create/index.mjs';
+import { map } from '../operators/index.mjs';
+import { SyncChildObservableClass } from './child-observable-class.mjs';
+import { RootObservableClass } from './root-observable-class.mjs';
+
+describe('circular dependency comparison', () => {
+  describe('SynState', () => {
+    test('detects cycle at construction time with a clear error message', () => {
+      const root = new RootObservableClass({
+        initialValue: Optional.some(0),
+      });
+
+      const childA = new SyncChildObservableClass({
+        parents: [root],
+        initialValue: Optional.some(0),
+      });
+
+      const childB = new SyncChildObservableClass({
+        parents: [childA],
+        initialValue: Optional.some(0),
+      });
+
+      // Simulate a cycle: childA → childB → childA
+      // In normal usage this is impossible — the check runs in every
+      // child constructor before the reference becomes available.
+      Object.defineProperty(childA, 'parents', {
+        value: [childB],
+        writable: false,
+        configurable: true,
+      });
+
+      expect(() => {
+        new SyncChildObservableClass({
+          parents: [childA],
+          initialValue: Optional.some(0),
+        });
+      }).toThrow(
+        'Circular dependency detected in observable graph: a child observable cannot be its own ancestor.',
+      );
+    });
+
+    test('accepts valid DAG (diamond dependency)', () => {
+      const a$ = source(0);
+
+      const b$ = a$.pipe(map((x) => x * 10));
+
+      const c$ = a$.pipe(map((x) => x * 1000));
+
+      expect(() => {
+        combine([b$, c$]);
+      }).not.toThrow();
+    });
+  });
+
+  describe('RxJS', () => {
+    test('cannot express static graph cycles — pipe() always creates new instances', () => {
+      // RxJS pipe() returns a brand-new Observable each time, so there is no
+      // way to construct a cycle through the public API.  This test documents
+      // that behavior rather than asserting error detection.
+      const a$ = new BehaviorSubject(0);
+
+      const b$ = a$.pipe(rxMap((x) => x + 1));
+
+      // b$ is a wholly separate object; there is no "parents" link back to a$.
+      expect(a$).not.toBe(b$);
+
+      // A diamond dependency works but produces glitches (intermediate states).
+      const left$ = a$.pipe(rxMap((x) => x * 10));
+
+      const right$ = a$.pipe(rxMap((x) => x * 1000));
+
+      const combined$ = combineLatest([left$, right$]).pipe(
+        rxMap(([l, r]) => l + r),
+      );
+
+      const mut_values: number[] = [];
+
+      combined$.subscribe((v) => {
+        mut_values.push(v);
+      });
+
+      a$.next(1);
+
+      a$.next(2);
+
+      // Glitch values (10, 1020) appear between the correct values.
+      assert.deepStrictEqual(mut_values, [0, 10, 1010, 1020, 2020]);
+    });
+  });
+
+  describe('Jotai', () => {
+    test('does not detect circular atom definitions — crashes on read', () => {
+      const store = createStore();
+
+      // Two atoms that depend on each other — an obvious cycle.
+      // Explicit type annotations are required because TypeScript cannot infer
+      // the type of mutually-recursive initializers.
+      const atomA: Atom<number> = atom((get) => get(atomB) + 1);
+
+      const atomB: Atom<number> = atom((get) => get(atomA) + 1);
+
+      // Definition succeeds without any error.
+      // Reading triggers infinite recursion.
+      expect(() => {
+        store.get(atomA);
+      }).toThrow('Maximum call stack size exceeded');
+    });
+
+    test('handles valid DAG (diamond dependency) correctly', () => {
+      const store = createStore();
+
+      const base = atom(1);
+
+      const left = atom((get) => get(base) * 10);
+
+      const right = atom((get) => get(base) * 1000);
+
+      const combined = atom((get) => get(left) + get(right));
+
+      expect(store.get(combined)).toBe(1010);
+
+      store.set(base, 2);
+
+      expect(store.get(combined)).toBe(2020);
+    });
+  });
+});

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

@@ -0,0 +1,251 @@
+/* eslint-disable functional/immutable-data */
+/* eslint-disable no-new */
+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 {
+  AsyncChildObservableClass,
+  SyncChildObservableClass,
+} from './child-observable-class.mjs';
+import { RootObservableClass } from './root-observable-class.mjs';
+
+describe('circular dependency detection', () => {
+  describe('cycle in ancestor graph', () => {
+    test('should throw when parent chain contains a cycle (A -> B -> A)', () => {
+      const root = new RootObservableClass({
+        initialValue: Optional.some(0),
+      });
+
+      const childA = new SyncChildObservableClass({
+        parents: [root],
+        initialValue: Optional.some(0),
+      });
+
+      const childB = new SyncChildObservableClass({
+        parents: [childA],
+        initialValue: Optional.some(0),
+      });
+
+      // Mutate childA.parents to create a cycle: childA -> childB -> childA
+      Object.defineProperty(childA, 'parents', {
+        value: [childB],
+        writable: false,
+        configurable: true,
+      });
+
+      expect(() => {
+        new SyncChildObservableClass({
+          parents: [childA],
+          initialValue: Optional.some(0),
+        });
+      }).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 = new RootObservableClass({
+        initialValue: Optional.some(0),
+      });
+
+      const childA = new AsyncChildObservableClass({
+        parents: [root],
+        initialValue: Optional.some(0),
+      });
+
+      const childB = new SyncChildObservableClass({
+        parents: [childA],
+        initialValue: Optional.some(0),
+      });
+
+      // Create cycle: childA -> childB -> childA
+      Object.defineProperty(childA, 'parents', {
+        value: [childB],
+        writable: false,
+        configurable: true,
+      });
+
+      expect(() => {
+        new AsyncChildObservableClass({
+          parents: [childA],
+          initialValue: Optional.some(0),
+        });
+      }).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 = new RootObservableClass({
+        initialValue: Optional.some(0),
+      });
+
+      const childA = new SyncChildObservableClass({
+        parents: [root],
+        initialValue: Optional.some(0),
+      });
+
+      const childB = new SyncChildObservableClass({
+        parents: [childA],
+        initialValue: Optional.some(0),
+      });
+
+      const childC = new SyncChildObservableClass({
+        parents: [childB],
+        initialValue: Optional.some(0),
+      });
+
+      // Create cycle: childA -> childC -> childB -> childA
+      Object.defineProperty(childA, 'parents', {
+        value: [childC],
+        writable: false,
+        configurable: true,
+      });
+
+      expect(() => {
+        new SyncChildObservableClass({
+          parents: [childA],
+          initialValue: Optional.some(0),
+        });
+      }).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 = new RootObservableClass({
+        initialValue: Optional.some(0),
+      });
+
+      const childA = new SyncChildObservableClass({
+        parents: [root],
+        initialValue: Optional.some(0),
+      });
+
+      // Make childA's parents reference childA itself (self-loop)
+      Object.defineProperty(childA, 'parents', {
+        value: [childA],
+        writable: false,
+        configurable: true,
+      });
+
+      expect(() => {
+        new SyncChildObservableClass({
+          parents: [childA],
+          initialValue: Optional.some(0),
+        });
+      }).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 = new RootObservableClass({
+        initialValue: Optional.some(0),
+      });
+
+      const left = new SyncChildObservableClass({
+        parents: [root],
+        initialValue: Optional.some(0),
+      });
+
+      const right = new SyncChildObservableClass({
+        parents: [root],
+        initialValue: Optional.some(0),
+      });
+
+      // Diamond: root -> left -> combined, root -> right -> combined
+      expect(() => {
+        new SyncChildObservableClass({
+          parents: [left, right],
+          initialValue: Optional.some(0),
+        });
+      }).not.toThrow();
+    });
+
+    test('linear chain is not a cycle', () => {
+      const root = new RootObservableClass({
+        initialValue: Optional.some(0),
+      });
+
+      const a = new SyncChildObservableClass({
+        parents: [root],
+        initialValue: Optional.some(0),
+      });
+
+      const b = new SyncChildObservableClass({
+        parents: [a],
+        initialValue: Optional.some(0),
+      });
+
+      expect(() => {
+        new SyncChildObservableClass({
+          parents: [b],
+          initialValue: Optional.some(0),
+        });
+      }).not.toThrow();
+    });
+
+    test('multiple roots converging is not a cycle', () => {
+      const root1 = new RootObservableClass({
+        initialValue: Optional.some(1),
+      });
+
+      const root2 = new RootObservableClass({
+        initialValue: Optional.some(2),
+      });
+
+      const child1 = new SyncChildObservableClass({
+        parents: [root1],
+        initialValue: Optional.some(0),
+      });
+
+      const child2 = new SyncChildObservableClass({
+        parents: [root2],
+        initialValue: Optional.some(0),
+      });
+
+      expect(() => {
+        new SyncChildObservableClass({
+          parents: [child1, child2],
+          initialValue: Optional.some(0),
+        });
+      }).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/class/observable-base-class.mts

@@ -1,4 +1,5 @@
 import { Arr, Optional } from 'ts-data-forge';
+import { type MutableMap } from 'ts-type-forge';
 import {
   type ChildObservable,
   type InitializedObservable,
@@ -8,13 +9,13 @@ import {
   type Subscriber,
   type SubscriberId,
   type Subscription,
-  type UpdaterSymbol,
+  type UpdateToken,
   type WithInitialValueOperator,
 } from '../types/index.mjs';
 import {
   issueObservableId,
   issueSubscriberId,
-  issueUpdaterSymbol,
+  issueUpdateToken,
   toSubscriber,
 } from '../utils/index.mjs';
 
@@ -30,7 +31,7 @@ export class ObservableBaseClass<
   readonly #subscribers: MutableMap<SubscriberId, Subscriber<A>>;
   #mut_currentValue: ReturnType<ObservableBase<A>['getSnapshot']>;
   #mut_isCompleted: ObservableBase<A>['isCompleted'];
-  #mut_updaterSymbol: ObservableBase<A>['updaterSymbol'];
+  #mut_updateToken: ObservableBase<A>['updateToken'];
 
   constructor({
     kind,
@@ -55,7 +56,7 @@ export class ObservableBaseClass<
 
     this.#mut_isCompleted = false;
 
-    this.#mut_updaterSymbol = issueUpdaterSymbol();
+    this.#mut_updateToken = issueUpdateToken();
   }
 
   addChild<B>(child: ChildObservable<B>): void {
@@ -78,8 +79,8 @@ export class ObservableBaseClass<
     return this.#mut_isCompleted;
   }
 
-  get updaterSymbol(): UpdaterSymbol {
-    return this.#mut_updaterSymbol;
+  get updateToken(): UpdateToken {
+    return this.#mut_updateToken;
   }
 
   get hasSubscriber(): boolean {
@@ -94,8 +95,8 @@ export class ObservableBaseClass<
     return this.#mut_children.some((c) => !c.isCompleted);
   }
 
-  protected setNext(nextValue: A, updaterSymbol: UpdaterSymbol): void {
-    this.#mut_updaterSymbol = updaterSymbol;
+  protected setNext(nextValue: A, updateToken: UpdateToken): void {
+    this.#mut_updateToken = updateToken;
 
     this.#mut_currentValue = Optional.some(nextValue);
 
@@ -105,7 +106,7 @@ export class ObservableBaseClass<
   }
 
   // eslint-disable-next-line @typescript-eslint/class-methods-use-this
-  tryUpdate(_updaterSymbol: UpdaterSymbol): void {
+  tryUpdate(_updateToken: UpdateToken): void {
     throw new Error('not implemented');
   }
 

package/src/core/class/root-observable-class.mts

@@ -1,24 +1,25 @@
 import { Arr, Optional } from 'ts-data-forge';
+import { type MutableSet } from 'ts-type-forge';
 import {
   isRootObservable,
   type ChildObservable,
   type ObservableId,
   type RootObservable,
 } from '../types/index.mjs';
-import { binarySearch, issueUpdaterSymbol } from '../utils/index.mjs';
+import { binarySearch, issueUpdateToken } from '../utils/index.mjs';
 import { ObservableBaseClass } from './observable-base-class.mjs';
 
 export class RootObservableClass<A>
   extends ObservableBaseClass<A, 'root', 0>
   implements RootObservable<A>
 {
-  #mut_procedure: readonly ChildObservable<unknown>[];
+  #mut_propagationOrder: readonly ChildObservable<unknown>[];
   protected readonly _descendantsIdSet: MutableSet<ObservableId>;
 
   constructor({
     initialValue,
   }: Readonly<{
-    initialValue: ReturnType<RootObservable<A>['getSnapshot']>;
+    initialValue: Optional<A>;
   }>) {
     super({
       kind: 'root',
@@ -26,7 +27,7 @@ export class RootObservableClass<A>
       initialValue,
     });
 
-    this.#mut_procedure = [];
+    this.#mut_propagationOrder = [];
 
     this._descendantsIdSet = new Set<ObservableId>();
   }
@@ -37,20 +38,24 @@ export class RootObservableClass<A>
     this._descendantsIdSet.add(child.id);
 
     const insertPos = binarySearch(
-      this.#mut_procedure.map((a) => a.depth),
+      this.#mut_propagationOrder.map((a) => a.depth),
       child.depth,
     );
 
-    this.#mut_procedure = Arr.toInserted(this.#mut_procedure, insertPos, child);
+    this.#mut_propagationOrder = Arr.toInserted(
+      this.#mut_propagationOrder,
+      insertPos,
+      child,
+    );
   }
 
   startUpdate(nextValue: A): void {
-    const updaterSymbol = issueUpdaterSymbol();
+    const updateToken = issueUpdateToken();
 
-    this.setNext(nextValue, updaterSymbol);
+    this.setNext(nextValue, updateToken);
 
-    for (const p of this.#mut_procedure) {
-      p.tryUpdate(updaterSymbol);
+    for (const p of this.#mut_propagationOrder) {
+      p.tryUpdate(updateToken);
     }
   }
 }