synstate 3.0.4 → 3.0.6

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

@@ -7,7 +7,6 @@
  * - 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 */
 import { type Atom, atom, createStore } from 'jotai';
 import { BehaviorSubject, combineLatest, map as rxMap } from 'rxjs';
 import { Optional } from 'ts-data-forge';
@@ -26,7 +25,7 @@ describe('circular dependency comparison', () => {
         () => ({}),
       );
 
-      const childA = createSyncChildObservable(
+      const mut_childA = createSyncChildObservable(
         {
           parents: [root],
           initialValue: Optional.some(0),
@@ -36,16 +35,16 @@ describe('circular dependency comparison', () => {
 
       const childB = createSyncChildObservable(
         {
-          parents: [childA],
+          parents: [mut_childA],
           initialValue: Optional.some(0),
         },
         createTryUpdateNotImplemented,
       );
 
-      // Simulate a cycle: childA → childB → childA
+      // Simulate a cycle: mut_childA → childB → mut_childA
       // In normal usage this is impossible — the check runs in every
       // child constructor before the reference becomes available.
-      Object.defineProperty(childA, 'parents', {
+      Object.defineProperty(mut_childA, 'parents', {
         value: [childB],
         writable: false,
         configurable: true,
@@ -54,7 +53,7 @@ describe('circular dependency comparison', () => {
       expect(() => {
         createSyncChildObservable(
           {
-            parents: [childA],
+            parents: [mut_childA],
             initialValue: Optional.some(0),
           },
           createTryUpdateNotImplemented,

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

@@ -1,4 +1,3 @@
-/* eslint-disable functional/immutable-data */
 import { Optional } from 'ts-data-forge';
 import { combine, merge } from '../combine/index.mjs';
 import { source } from '../create/index.mjs';
@@ -18,7 +17,7 @@ describe('circular dependency detection', () => {
         () => ({}),
       );
 
-      const childA = createSyncChildObservable(
+      const mut_childA = createSyncChildObservable(
         {
           parents: [root],
           initialValue: Optional.some(0),
@@ -28,14 +27,14 @@ describe('circular dependency detection', () => {
 
       const childB = createSyncChildObservable(
         {
-          parents: [childA],
+          parents: [mut_childA],
           initialValue: Optional.some(0),
         },
         createTryUpdateNotImplemented,
       );
 
-      // Mutate childA.parents to create a cycle: childA -> childB -> childA
-      Object.defineProperty(childA, 'parents', {
+      // Mutate mut_childA.parents to create a cycle: mut_childA -> childB -> mut_childA
+      Object.defineProperty(mut_childA, 'parents', {
         value: [childB],
         writable: false,
         configurable: true,
@@ -44,7 +43,7 @@ describe('circular dependency detection', () => {
       expect(() => {
         createSyncChildObservable(
           {
-            parents: [childA],
+            parents: [mut_childA],
             initialValue: Optional.some(0),
           },
           createTryUpdateNotImplemented,
@@ -60,7 +59,7 @@ describe('circular dependency detection', () => {
         () => ({}),
       );
 
-      const childA = createAsyncChildObservable(
+      const mut_childA = createAsyncChildObservable(
         {
           parents: [root],
           initialValue: Optional.some(0),
@@ -70,14 +69,14 @@ describe('circular dependency detection', () => {
 
       const childB = createSyncChildObservable(
         {
-          parents: [childA],
+          parents: [mut_childA],
           initialValue: Optional.some(0),
         },
         createTryUpdateNotImplemented,
       );
 
-      // Create cycle: childA -> childB -> childA
-      Object.defineProperty(childA, 'parents', {
+      // Create cycle: mut_childA -> childB -> mut_childA
+      Object.defineProperty(mut_childA, 'parents', {
         value: [childB],
         writable: false,
         configurable: true,
@@ -86,7 +85,7 @@ describe('circular dependency detection', () => {
       expect(() => {
         createAsyncChildObservable(
           {
-            parents: [childA],
+            parents: [mut_childA],
             initialValue: Optional.some(0),
           },
           createTryUpdateNotImplemented,
@@ -102,7 +101,7 @@ describe('circular dependency detection', () => {
         () => ({}),
       );
 
-      const childA = createSyncChildObservable(
+      const mut_childA = createSyncChildObservable(
         {
           parents: [root],
           initialValue: Optional.some(0),
@@ -112,7 +111,7 @@ describe('circular dependency detection', () => {
 
       const childB = createSyncChildObservable(
         {
-          parents: [childA],
+          parents: [mut_childA],
           initialValue: Optional.some(0),
         },
         createTryUpdateNotImplemented,
@@ -126,8 +125,8 @@ describe('circular dependency detection', () => {
         createTryUpdateNotImplemented,
       );
 
-      // Create cycle: childA -> childC -> childB -> childA
-      Object.defineProperty(childA, 'parents', {
+      // Create cycle: mut_childA -> childC -> childB -> mut_childA
+      Object.defineProperty(mut_childA, 'parents', {
         value: [childC],
         writable: false,
         configurable: true,
@@ -136,7 +135,7 @@ describe('circular dependency detection', () => {
       expect(() => {
         createSyncChildObservable(
           {
-            parents: [childA],
+            parents: [mut_childA],
             initialValue: Optional.some(0),
           },
           createTryUpdateNotImplemented,
@@ -152,7 +151,7 @@ describe('circular dependency detection', () => {
         () => ({}),
       );
 
-      const childA = createSyncChildObservable(
+      const mut_childA = createSyncChildObservable(
         {
           parents: [root],
           initialValue: Optional.some(0),
@@ -160,9 +159,9 @@ describe('circular dependency detection', () => {
         createTryUpdateNotImplemented,
       );
 
-      // Make childA's parents reference childA itself (self-loop)
-      Object.defineProperty(childA, 'parents', {
-        value: [childA],
+      // Make mut_childA's parents reference mut_childA itself (self-loop)
+      Object.defineProperty(mut_childA, 'parents', {
+        value: [mut_childA],
         writable: false,
         configurable: true,
       });
@@ -170,7 +169,7 @@ describe('circular dependency detection', () => {
       expect(() => {
         createSyncChildObservable(
           {
-            parents: [childA],
+            parents: [mut_childA],
             initialValue: Optional.some(0),
           },
           createTryUpdateNotImplemented,

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

@@ -160,6 +160,7 @@ export const createInitializedSyncChildObservable = <
   return (
     // `getSnapshot` always returns `Some` here: `initialValue` is a `Some` and
     // `setNext` only ever stores a `Some`.
+    // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
     // eslint-disable-next-line total-functions/no-unsafe-type-assertion
     observable as InitializedSyncChildObservable<A, P>
   );
@@ -240,9 +241,13 @@ const hasCircularDependencyFrom = (
   mut_visited: MutableSet<ObservableId>,
   mut_inPath: MutableSet<ObservableId>,
 ): boolean => {
-  if (mut_inPath.has(node.id)) return true;
+  if (mut_inPath.has(node.id)) {
+    return true;
+  }
 
-  if (mut_visited.has(node.id)) return false;
+  if (mut_visited.has(node.id)) {
+    return false;
+  }
 
   mut_visited.add(node.id);
 
@@ -304,7 +309,9 @@ const registerChild = <A,>(
   while (Arr.isNonEmpty(mut_rest)) {
     const p = mut_rest.pop();
 
-    if (p === undefined) break;
+    if (p === undefined) {
+      break;
+    }
 
     if (isManagerObservable(p)) {
       p.addDescendant(child);

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

@@ -42,6 +42,38 @@ import {
 export type ObservableBaseHandle<A> = Readonly<{
   id: ObservableId;
 
+  /**
+   * Registers the public object {@link assembleObservable} built from this
+   * handle, so that its four state flags (`isCompleted`, `updateToken`,
+   * `hasSubscriber`, `hasChild`) can be mirrored onto it as plain data
+   * properties.
+   *
+   * They used to be getters delegating to this handle's closures, and that
+   * costs more than it looks. Reading one was an accessor call plus a closure
+   * call where a field read would do — `updateToken` is read once per child
+   * per update, so the propagation path paid it on every step — and an object
+   * literal carrying accessors is far more expensive to create than one
+   * carrying data, which is most of what building a graph costs. Measured on
+   * one machine with `pnpm run benchmark`: the derived chain's 100,000 updates
+   * 16.7 ms -> 13.6 ms, and the cascaded diamond at N=20, whose measurement is
+   * dominated by graph construction, 587 ms -> 362 ms.
+   *
+   * Every write below therefore has to keep the mirror in step; that is the
+   * price of not reading through a closure on the hot path. It is paid in
+   * clarity too, and on purpose: `hasSubscriber` and `hasChild` are derived
+   * from `mut_subscribers` and `mut_children`, which a getter stated once and
+   * declaratively, whereas the mirror restates it at every write.
+   *
+   * Nor can the rarely read flags alone go back to getters while `updateToken`
+   * stays data. A single accessor in the literal is enough to lose nearly all
+   * of the gain: measured on Node 26 with the `...extra` spread followed by
+   * these properties, one getter among data properties made the literal about
+   * 10x slower to create than all data (four getters: about 15x) and gave
+   * every instance its own hidden class (`%HaveSameMap` false). Keep all four
+   * as data, or measure again before changing that.
+   */
+  attach: (writers: ObservableStateWriters) => void;
+
   addChild: <B>(child: ChildObservable<B>) => void;
 
   getSnapshot: () => Optional<A>;
@@ -52,8 +84,6 @@ export type ObservableBaseHandle<A> = Readonly<{
 
   hasSubscriber: () => boolean;
 
-  hasChild: () => boolean;
-
   hasActiveChild: () => boolean;
 
   subscribe: (onNext: (v: A) => void, onComplete?: () => void) => Subscription;
@@ -70,6 +100,20 @@ export type ObservableBaseHandle<A> = Readonly<{
   completeBase: () => void;
 }>;
 
+/**
+ * How the handle writes the four state flags onto the public object. The
+ * writers are closures over that object rather than the object itself, because
+ * a parameter this side could mutate has to be a mutable type, which
+ * `@typescript-eslint/prefer-readonly-parameter-types` rejects — and the object
+ * is `Readonly` to everyone else.
+ */
+type ObservableStateWriters = Readonly<{
+  setIsCompleted: (value: boolean) => void;
+  setUpdateToken: (value: UpdateToken) => void;
+  setHasSubscriber: (value: boolean) => void;
+  setHasChild: (value: boolean) => void;
+}>;
+
 export const createObservableBaseHandle = <A,>(
   initialValue: Optional<A>,
 ): ObservableBaseHandle<A> => {
@@ -85,17 +129,41 @@ export const createObservableBaseHandle = <A,>(
 
   let mut_updateToken: UpdateToken = issueUpdateToken();
 
+  /**
+   * Set once {@link assembleObservable} has built the public object. It does
+   * not exist while a leaf factory's `init` callback runs — that callback may
+   * already subscribe or complete — so every write below is optional, and
+   * `attach` copies the state as it stands rather than assuming defaults.
+   */
+  let mut_writers: ObservableStateWriters | undefined;
+
+  const attach = (writers: ObservableStateWriters): void => {
+    mut_writers = writers;
+
+    writers.setIsCompleted(mut_isCompleted);
+
+    writers.setUpdateToken(mut_updateToken);
+
+    writers.setHasSubscriber(mut_subscribers.size > 0);
+
+    writers.setHasChild(Arr.isNonEmpty(mut_children));
+  };
+
   const addSubscriber = (s: Subscriber<A>): SubscriberId => {
     // return the id of added subscriber
     const subscriberId = issueSubscriberId();
 
     mut_subscribers.set(subscriberId, s);
 
+    mut_writers?.setHasSubscriber(true);
+
     return subscriberId;
   };
 
   const removeSubscriber = (subscriberId: SubscriberId): void => {
     mut_subscribers.delete(subscriberId);
+
+    mut_writers?.setHasSubscriber(mut_subscribers.size > 0);
   };
 
   const addChild = <B,>(child: ChildObservable<B>): void => {
@@ -104,6 +172,8 @@ export const createObservableBaseHandle = <A,>(
 
       child as ChildObservable<unknown>,
     );
+
+    mut_writers?.setHasChild(true);
   };
 
   const getSnapshot = (): Optional<A> => mut_currentValue;
@@ -114,14 +184,14 @@ export const createObservableBaseHandle = <A,>(
 
   const hasSubscriber = (): boolean => mut_subscribers.size > 0;
 
-  const hasChild = (): boolean => Arr.isNonEmpty(mut_children);
-
   const hasActiveChild = (): boolean =>
     mut_children.some((c) => !c.isCompleted);
 
   const setNext = (nextValue: A, nextUpdateToken: UpdateToken): void => {
     mut_updateToken = nextUpdateToken;
 
+    mut_writers?.setUpdateToken(nextUpdateToken);
+
     mut_currentValue = Optional.some(nextValue);
 
     for (const s of mut_subscribers.values()) {
@@ -130,11 +200,15 @@ export const createObservableBaseHandle = <A,>(
   };
 
   const completeBase = (): void => {
-    if (mut_isCompleted) return; // terminate only once
+    if (mut_isCompleted) {
+      return; // terminate only once
+    }
 
     // change state
     mut_isCompleted = true;
 
+    mut_writers?.setIsCompleted(true);
+
     // run subscribers for the current value
     for (const s of mut_subscribers.values()) {
       s.onComplete();
@@ -143,6 +217,8 @@ export const createObservableBaseHandle = <A,>(
     // remove all subscribers
     mut_subscribers.clear();
 
+    mut_writers?.setHasSubscriber(false);
+
     // propagate to children
     for (const o of mut_children) {
       o.tryComplete();
@@ -181,12 +257,12 @@ export const createObservableBaseHandle = <A,>(
 
   return {
     id,
+    attach,
     addChild,
     getSnapshot,
     isCompleted,
     updateToken,
     hasSubscriber,
-    hasChild,
     hasActiveChild,
     subscribe,
     setNext,
@@ -220,7 +296,9 @@ export const createManagerObservableParts = <A,>(
   const mut_descendantsIdSet: MutableSet<ObservableId> = new Set();
 
   const addDescendant = <B,>(child: ChildObservable<B>): void => {
-    if (mut_descendantsIdSet.has(child.id)) return;
+    if (mut_descendantsIdSet.has(child.id)) {
+      return;
+    }
 
     mut_descendantsIdSet.add(child.id);
 
@@ -270,7 +348,7 @@ type AssembleObservableArgs<
   Extra extends ReadonlyRecord<string, unknown>,
 > = Readonly<{
   kind: Kind;
-  depth: number;
+  depth: Kind extends 'root' ? 0 : number;
   handle: ObservableBaseHandle<A>;
   tryUpdate: (updateToken: UpdateToken) => void;
   tryComplete: () => void;
@@ -278,8 +356,9 @@ type AssembleObservableArgs<
   /**
    * Kind-specific public members (`parents`, `addDescendant`) and leaf
    * extensions (`next`, `start`). They are merged here, in the one place the
-   * final object literal is created, because the public getters below must not
-   * be copied by a spread (spreading would freeze their current values).
+   * final object literal is created, because the handle keeps the state flags
+   * up to date on that object alone: a copy made by spreading it afterwards
+   * would freeze their current values.
    */
   extra: Extra;
 }>;
@@ -287,9 +366,10 @@ type AssembleObservableArgs<
 /**
  * Builds the public observable object from a base handle. This replaces the
  * implicit assembly a `class` performs: state stays in the handle's closures,
- * `isCompleted` / `updateToken` / `hasSubscriber` / `hasChild` become getters
- * delegating to the handle, and the kind-specific behavior (`tryUpdate`,
- * `tryComplete`, `complete`) is passed in already composed.
+ * `isCompleted` / `updateToken` / `hasSubscriber` / `hasChild` become data
+ * properties the handle keeps in step through `attach`, and the kind-specific
+ * behavior (`tryUpdate`, `tryComplete`, `complete`) is passed in already
+ * composed.
  */
 export const assembleObservable = <
   A,
@@ -305,7 +385,10 @@ export const assembleObservable = <
   extra,
 }: AssembleObservableArgs<A, Kind, Extra>): Extra &
   ObservableBase<A> &
-  Readonly<{ kind: Kind }> => {
+  Readonly<{
+    kind: Kind;
+    depth: AssembleObservableArgs<A, Kind, Extra>['depth'];
+  }> => {
   function pipe<B>(
     operator: WithInitialValueOperator<A, B>,
   ): InitializedObservable<B>;
@@ -314,12 +397,18 @@ export const assembleObservable = <
 
   function pipe<B>(operator: Operator<A, B>): Observable<B> {
     return operator(
+      // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
       // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-      observable as unknown as InitializedObservable<A>,
+      mut_observable as unknown as InitializedObservable<A>,
     );
   }
 
-  const observable = {
+  // The four state flags are plain data properties kept in step by the handle,
+  // not getters delegating to it — see `ObservableBaseHandle.attach` for the
+  // measurements that decided this. `updateToken` in particular is read once
+  // per child per update, and `tryUpdate` reading a field rather than calling
+  // through an accessor is most of what the change buys.
+  const mut_observable = {
     ...extra,
 
     id: handle.id,
@@ -332,21 +421,13 @@ export const assembleObservable = <
 
     getSnapshot: handle.getSnapshot,
 
-    get isCompleted(): boolean {
-      return handle.isCompleted();
-    },
+    isCompleted: false,
 
-    get updateToken(): UpdateToken {
-      return handle.updateToken();
-    },
+    updateToken: handle.updateToken(),
 
-    get hasSubscriber(): boolean {
-      return handle.hasSubscriber();
-    },
+    hasSubscriber: false,
 
-    get hasChild(): boolean {
-      return handle.hasChild();
-    },
+    hasChild: false,
 
     hasActiveChild: handle.hasActiveChild,
 
@@ -359,7 +440,25 @@ export const assembleObservable = <
     subscribe: handle.subscribe,
 
     pipe,
-  } as const;
+  };
+
+  handle.attach({
+    setIsCompleted: (value) => {
+      mut_observable.isCompleted = value;
+    },
+
+    setUpdateToken: (value) => {
+      mut_observable.updateToken = value;
+    },
+
+    setHasSubscriber: (value) => {
+      mut_observable.hasSubscriber = value;
+    },
+
+    setHasChild: (value) => {
+      mut_observable.hasChild = value;
+    },
+  });
 
-  return observable;
+  return mut_observable;
 };

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

@@ -47,6 +47,8 @@ export type RootObservableConfig<A> = Readonly<{
  */
 export const createRootObservable = <
   A,
+  // The default is deliberately empty: a root leaf without `init` adds no members.
+  // eslint-disable-next-line @typescript-eslint/no-generated-empty-object-type
   Extension extends ReadonlyRecord<string, unknown> = ReadonlyRecord<
     never,
     never

package/src/core/combine/combine.mts

@@ -74,6 +74,7 @@ import {
 export const combine = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): CombineObservableRefined<OS> =>
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   createCombineObservable(parents) as unknown as CombineObservableRefined<OS>;
 
@@ -113,7 +114,9 @@ const createCombineObservable = <const A extends NonEmptyUnknownList>(
     },
     ({ setNext }) =>
       (updateToken) => {
-        if (parents.every((o) => o.updateToken !== updateToken)) return; // all parents are skipped
+        if (parents.every((o) => o.updateToken !== updateToken)) {
+          return; // all parents are skipped
+        }
 
         // Same shape-preserving chain as the initial value: `Arr.map` (not the
         // native one, which drops the tuple shape) into the uniform
@@ -123,14 +126,16 @@ const createCombineObservable = <const A extends NonEmptyUnknownList>(
           (a) => a.getSnapshot(),
         );
 
-        if (Arr.every(parentValues, Optional.isSome)) {
-          const nextValue: Readonly<{ [K in keyof A]: A[K] }> = Arr.map(
-            parentValues,
-            (a) => a.value,
-          );
-
-          setNext(nextValue, updateToken);
+        if (!Arr.every(parentValues, Optional.isSome)) {
+          return;
         }
+
+        const nextValue: Readonly<{ [K in keyof A]: A[K] }> = Arr.map(
+          parentValues,
+          (a) => a.value,
+        );
+
+        setNext(nextValue, updateToken);
       },
   );
 };

package/src/core/combine/merge.mts

@@ -65,6 +65,7 @@ import {
 export const merge = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): MergeObservableRefined<OS> =>
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   createMergeObservable(parents) as MergeObservableRefined<OS>;
 
@@ -83,9 +84,12 @@ const createMergeObservable = <const P extends NonEmptyUnknownList>(
             o.updateToken === updateToken && Optional.isSome(o.getSnapshot()),
         );
 
-        if (parentToUse === undefined) return;
+        if (parentToUse === undefined) {
+          return;
+        }
 
         const nextValue =
+          // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
           // eslint-disable-next-line total-functions/no-unsafe-type-assertion
           Optional.unwrap(parentToUse.getSnapshot()) as ArrayElement<P>;
 

package/src/core/combine/zip.mts

@@ -67,6 +67,7 @@ import {
 export const zip = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): ZipObservableRefined<OS> =>
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   createZipObservable(parents) as unknown as ZipObservableRefined<OS>;
 
@@ -110,15 +111,18 @@ const createZipObservable = <const A extends NonEmptyUnknownList>(
           }
         }
 
-        if (queues.every((list) => !list.isEmpty)) {
-          const nextValue =
-            // `Arr.map` has a single result element type, so it reports
-            // `A[number] | undefined` per position rather than `A[P]`.
-            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-            Arr.map(queues, (q) => Optional.unwrap(q.dequeue())) as A;
-
-          setNext(nextValue, updateToken);
+        if (queues.some((list) => list.isEmpty)) {
+          return;
         }
+
+        const nextValue =
+          // `Arr.map` has a single result element type, so it reports
+          // `A[number] | undefined` per position rather than `A[P]`.
+          // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+          Arr.map(queues, (q) => Optional.unwrap(q.dequeue())) as A;
+
+        setNext(nextValue, updateToken);
       },
   );
 };

package/src/core/create/from-abortable-promise.mts

@@ -70,6 +70,7 @@ import { type FromPromiseObservable } from '../types/index.mjs';
  * ```
  */
 export const fromAbortablePromise = <A, E = unknown>(
+  // @sumi-expect-error readonly/require-readonly-parameter
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
   factory: (signal: AbortSignal) => Promise<A>,
 ): FromPromiseObservable<A, E> => {
@@ -87,12 +88,16 @@ export const fromAbortablePromise = <A, E = unknown>(
 
       promise
         .then((value) => {
-          if (isCompleted()) return;
+          if (isCompleted()) {
+            return;
+          }
 
           startUpdate(Result.ok(value));
         })
         .catch((error: unknown) => {
-          if (isCompleted()) return;
+          if (isCompleted()) {
+            return;
+          }
 
           // Silently ignore AbortError — it means the observable was
           // intentionally completed (e.g., by switchMap).
@@ -102,6 +107,7 @@ export const fromAbortablePromise = <A, E = unknown>(
 
           startUpdate(
             Result.err(
+              // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
               // eslint-disable-next-line total-functions/no-unsafe-type-assertion
               error as E,
             ),