synstate 0.1.1 → 1.0.0

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

@@ -8,13 +8,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 +30,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 +55,7 @@ export class ObservableBaseClass<
 
     this.#mut_isCompleted = false;
 
-    this.#mut_updaterSymbol = issueUpdaterSymbol();
+    this.#mut_updateToken = issueUpdateToken();
   }
 
   addChild<B>(child: ChildObservable<B>): void {
@@ -78,8 +78,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 +94,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 +105,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

@@ -5,20 +5,20 @@ import {
   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 +26,7 @@ export class RootObservableClass<A>
       initialValue,
     });
 
-    this.#mut_procedure = [];
+    this.#mut_propagationOrder = [];
 
     this._descendantsIdSet = new Set<ObservableId>();
   }
@@ -37,20 +37,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);
     }
   }
 }

package/src/core/combine/combine.mts

@@ -1,6 +1,6 @@
 import { Arr, Optional, expectType } from 'ts-data-forge';
 import { SyncChildObservableClass } from '../class/index.mjs';
-import { fromArray, source } from '../create/index.mjs';
+import { source } from '../create/index.mjs';
 import { withInitialValue } from '../operators/index.mjs';
 import {
   type CombineObservable,
@@ -10,7 +10,7 @@ import {
   type NonEmptyUnknownList,
   type Observable,
   type SyncChildObservable,
-  type UpdaterSymbol,
+  type UpdateToken,
   type Wrap,
 } from '../types/index.mjs';
 
@@ -41,30 +41,30 @@ import {
  *
  * const user$ = combine([name$, age$]);
  *
- * const mut_history: (readonly [string, number])[] = [];
+ * const userHistory: (readonly [string, number])[] = [];
  *
  * user$.subscribe(([name_, age]) => {
- *   mut_history.push([name_, age]);
+ *   userHistory.push([name_, age]);
  * });
  *
  * name$.next('Alice'); // nothing logged (age$ hasn't emitted yet)
  *
- * assert.deepStrictEqual(mut_history, []);
+ * assert.deepStrictEqual(userHistory, []);
  *
  * age$.next(25); // logs: { name: 'Alice', age: 25 }
  *
- * assert.deepStrictEqual(mut_history, [['Alice', 25]]);
+ * assert.deepStrictEqual(userHistory, [['Alice', 25]]);
  *
  * name$.next('Bob'); // logs: { name: 'Bob', age: 25 }
  *
- * assert.deepStrictEqual(mut_history, [
+ * assert.deepStrictEqual(userHistory, [
  *   ['Alice', 25],
  *   ['Bob', 25],
  * ]);
  *
  * age$.next(30); // logs: { name: 'Bob', age: 30 }
  *
- * assert.deepStrictEqual(mut_history, [
+ * assert.deepStrictEqual(userHistory, [
  *   ['Alice', 25],
  *   ['Bob', 25],
  *   ['Bob', 30],
@@ -80,10 +80,10 @@ export const combine = <const OS extends NonEmptyArray<Observable<unknown>>>(
   ) as unknown as CombineObservableRefined<OS>;
 
 /**
- * Alias for `combine()`.
+ * Alias for `combine`.
  * @see combine
  */
-export const combineLatest = combine; // alias
+export const combineLatest = combine;
 
 class CombineObservableClass<const A extends NonEmptyUnknownList>
   extends SyncChildObservableClass<A, A>
@@ -103,8 +103,8 @@ class CombineObservableClass<const A extends NonEmptyUnknownList>
     });
   }
 
-  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
-    if (this.parents.every((o) => o.updaterSymbol !== updaterSymbol)) return; // all parents are skipped
+  override tryUpdate(updateToken: UpdateToken): void {
+    if (this.parents.every((o) => o.updateToken !== updateToken)) return; // all parents are skipped
 
     const parentValues = this.parents.map((a) => a.getSnapshot());
 
@@ -113,7 +113,7 @@ class CombineObservableClass<const A extends NonEmptyUnknownList>
         // eslint-disable-next-line total-functions/no-unsafe-type-assertion
         Arr.map(parentValues, (a) => a.value) as A;
 
-      this.setNext(nextValue, updaterSymbol);
+      this.setNext(nextValue, updateToken);
     }
   }
 }
@@ -154,9 +154,9 @@ class CombineObservableClass<const A extends NonEmptyUnknownList>
     expectType<typeof _d, InitializedObservable<readonly [1, 2]>>('<=');
   }
 
-  const r1 = fromArray([1, 2, 3]);
+  const r1 = source(1);
 
-  const r2 = fromArray(['a', 'b', 'c']);
+  const r2 = source('a');
 
   const _c = combine([r1, r2]);
 

package/src/core/combine/merge.mts

@@ -1,13 +1,13 @@
 import { Optional, expectType } from 'ts-data-forge';
 import { SyncChildObservableClass } from '../class/index.mjs';
-import { fromArray } from '../create/index.mjs';
+import { source } from '../create/index.mjs';
 import {
   type MergeObservable,
   type MergeObservableRefined,
   type NonEmptyUnknownList,
   type Observable,
   type SyncChildObservable,
-  type UpdaterSymbol,
+  type UpdateToken,
   type Wrap,
 } from '../types/index.mjs';
 
@@ -23,7 +23,7 @@ import {
  * ```ts
  * //  Timeline:
  * //
- * //  clicks$   c1          c2                    c3
+ * //  clicks$   c1              c2                c3
  * //  keys$               k1          k2                    k3
  * //  events$   c1        k1    c2    k2          c3        k3
  * //
@@ -38,25 +38,25 @@ import {
  *
  * const events$ = merge([clicks$, keys$]);
  *
- * const mut_history: string[] = [];
+ * const valueHistory: string[] = [];
  *
  * events$.subscribe((event_) => {
- *   mut_history.push(event_);
+ *   valueHistory.push(event_);
  * });
  *
  * clicks$.next('c1');
  *
- * assert.deepStrictEqual(mut_history, ['c1']);
+ * assert.deepStrictEqual(valueHistory, ['c1']);
  *
  * keys$.next('k1');
  *
- * assert.deepStrictEqual(mut_history, ['c1', 'k1']);
+ * assert.deepStrictEqual(valueHistory, ['c1', 'k1']);
  *
  * clicks$.next('c2');
  *
  * keys$.next('k2');
  *
- * assert.deepStrictEqual(mut_history, ['c1', 'k1', 'c2', 'k2']);
+ * assert.deepStrictEqual(valueHistory, ['c1', 'k1', 'c2', 'k2']);
  * ```
  *
  * @note To improve code readability, consider using `createState` instead of `merge`,
@@ -79,10 +79,9 @@ class MergeObservableClass<const P extends NonEmptyUnknownList>
     });
   }
 
-  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+  override tryUpdate(updateToken: UpdateToken): void {
     const parentToUse = this.parents.find(
-      (o) =>
-        o.updaterSymbol === updaterSymbol && Optional.isSome(o.getSnapshot()),
+      (o) => o.updateToken === updateToken && Optional.isSome(o.getSnapshot()),
     );
 
     if (parentToUse === undefined) return;
@@ -91,7 +90,7 @@ class MergeObservableClass<const P extends NonEmptyUnknownList>
       // eslint-disable-next-line total-functions/no-unsafe-type-assertion
       Optional.unwrap(parentToUse.getSnapshot()) as ArrayElement<P>;
 
-    this.setNext(nextValue, updaterSymbol);
+    this.setNext(nextValue, updateToken);
   }
 }
 
@@ -100,9 +99,9 @@ if (import.meta.vitest !== undefined) {
     expect(1).toBe(1); // dummy
   });
 
-  const r1 = fromArray([1, 2, 3]);
+  const r1 = source(1);
 
-  const r2 = fromArray(['a', 'b', 'c']);
+  const r2 = source('a');
 
   const _m = merge([r1, r2] as const);
 

package/src/core/combine/zip.mts

@@ -1,6 +1,6 @@
 import { Arr, Optional, createQueue, expectType } from 'ts-data-forge';
 import { SyncChildObservableClass } from '../class/index.mjs';
-import { fromArray, source } from '../create/index.mjs';
+import { source } from '../create/index.mjs';
 import { withInitialValue } from '../operators/index.mjs';
 import {
   type InitializedObservable,
@@ -9,7 +9,7 @@ import {
   type Observable,
   type SyncChildObservable,
   type TupleToQueueTuple,
-  type UpdaterSymbol,
+  type UpdateToken,
   type Wrap,
   type ZipObservable,
   type ZipObservableRefined,
@@ -28,38 +28,39 @@ import {
  * ```ts
  * //  Timeline:
  * //
- * //  letters$  'a'       'b'       'c'
+ * //  letters$  'A'       'B'       'C'
  * //  numbers$  1         2         3
- * //  zipped$   ['a',1]   ['b',2]   ['c',3]
+ * //  zipped$   ['A',1]   ['B',2]   ['C',3]
  * //
  * //  Explanation:
  * //  - zip pairs values by their index from multiple sources
  * //  - Waits for all sources to emit at the same index
  * //  - Completes when any source completes
  *
- * const letters$ = fromArray(['a', 'b', 'c']);
+ * const [letters$, setLetter] = createState<string>('A');
  *
- * const numbers$ = fromArray([1, 2, 3]);
+ * const [numbers$, setNumber] = createState<number>(1);
  *
  * const zipped$ = zip([letters$, numbers$]);
  *
- * const mut_history: (readonly [string, number])[] = [];
+ * const valueHistory: (readonly [string, number])[] = [];
  *
- * await new Promise<void>((resolve) => {
- *   zipped$.subscribe(
- *     ([letter, num]) => {
- *       mut_history.push([letter, num]);
- *     },
- *     () => {
- *       resolve();
- *     },
- *   );
+ * zipped$.subscribe(([letter, num]) => {
+ *   valueHistory.push([letter, num]);
  * });
  *
- * assert.deepStrictEqual(mut_history, [
- *   ['a', 1],
- *   ['b', 2],
- *   ['c', 3],
+ * for (const letter of ['B', 'C']) {
+ *   setLetter(letter);
+ * }
+ *
+ * for (const num of [2, 3]) {
+ *   setNumber(num);
+ * }
+ *
+ * assert.deepStrictEqual(valueHistory, [
+ *   ['A', 1],
+ *   ['B', 2],
+ *   ['C', 3],
  * ]);
  * ```
  */
@@ -93,13 +94,13 @@ class ZipObservableClass<const A extends NonEmptyUnknownList>
     ) satisfies TupleToQueueTuple<A>;
   }
 
-  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+  override tryUpdate(updateToken: UpdateToken): void {
     const queues = this.#queues;
 
     for (const [index, par] of this.parents.entries()) {
       const sn = par.getSnapshot();
 
-      if (par.updaterSymbol === updaterSymbol && Optional.isSome(sn)) {
+      if (par.updateToken === updateToken && Optional.isSome(sn)) {
         queues[index]?.enqueue(sn.value);
       }
     }
@@ -109,7 +110,7 @@ class ZipObservableClass<const A extends NonEmptyUnknownList>
         // eslint-disable-next-line total-functions/no-unsafe-type-assertion
         Arr.map(queues, (q) => Optional.unwrap(q.dequeue())) as A;
 
-      this.setNext(nextValue, updaterSymbol);
+      this.setNext(nextValue, updateToken);
     }
   }
 }
@@ -154,9 +155,9 @@ if (import.meta.vitest !== undefined) {
     expectType<typeof _d, InitializedObservable<readonly [1, 2]>>('<=');
   }
 
-  const r1 = fromArray([1, 2, 3]);
+  const r1 = source(1);
 
-  const r2 = fromArray(['a', 'b', 'c']);
+  const r2 = source('a');
 
   const _z = zip([r1, r2] as const);