synstate 3.1.0 → 3.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synstate",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "Type-safe State Management Library for TypeScript/JavaScript",
   "repository": {
     "type": "git",
@@ -34,25 +34,25 @@
     "ts-type-forge": "^9.2.2"
   },
   "devDependencies": {
-    "@reduxjs/toolkit": "2.12.0",
+    "@reduxjs/toolkit": "2.13.0",
     "@sumi-lang/cli": "0.0.5",
     "@types/react": "19.3.0",
-    "@vitest/browser-playwright": "5.0.2",
+    "@vitest/browser-playwright": "5.0.3",
     "argparse": "3.0.2",
-    "eslint-config-typed": "5.17.0",
-    "eslint-plugin-ts-data-forge": "0.8.3",
-    "eslint-plugin-ts-fortress": "1.3.0",
-    "eslint-plugin-ts-type-forge": "0.8.5",
-    "jotai": "3.0.0",
-    "mobx": "7.0.5",
-    "playwright": "1.63.0",
+    "eslint-config-typed": "5.17.4",
+    "eslint-plugin-ts-data-forge": "0.8.6",
+    "eslint-plugin-ts-fortress": "1.3.3",
+    "eslint-plugin-ts-type-forge": "0.8.8",
+    "jotai": "3.0.1",
+    "mobx": "7.0.6",
+    "playwright": "1.64.0",
     "prettier": "3.9.9",
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-packagejson": "3.0.2",
     "react": "19.3.0",
     "rxjs": "7.8.2",
-    "synstate-react-hooks": "3.1.0",
-    "synstate-react-hooks-compat": "3.1.0",
+    "synstate-react-hooks": "3.2.1",
+    "synstate-react-hooks-compat": "3.2.1",
     "ts-repo-utils": "10.7.1",
     "valtio": "2.3.2",
     "zustand": "5.0.15"
@@ -68,7 +68,7 @@
   "scripts": {
     "build": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/build.mts",
     "check:ext": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/check-ext.mts",
-    "check:lint": "eslint .",
+    "check:lint": "oxlint . && eslint .",
     "check:sumi": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../languages/sumi/cli/src/cmd/sumi.mts check ./tsconfig.sumi.json",
     "check:test": "pnpm run z:vitest:node run",
     "check:test:browser": "pnpm run z:vitest --project='Browser' run",
@@ -79,7 +79,7 @@
     "fix:fmt": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-uncommitted.mts --cwd .",
     "fix:fmt:diff": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-diff-from.mts origin/main --cwd .",
     "fix:fmt:full": "pnpm run z:prettier .",
-    "fix:lint": "eslint . --fix",
+    "fix:lint": "oxlint . --fix && eslint . --fix",
     "fmt": "pnpm run fix:fmt",
     "gen": "run-s gen:index gen:readme gen:jsdoc gen:sample-diffs",
     "gen:index": "run-s gen:index:src fix:fmt",

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

@@ -98,11 +98,25 @@ export const createSyncChildObservable = <A, P extends NonEmptyUnknownList>(
 ): SyncChildObservable<A, P> => {
   const handle = createObservableBaseHandle<A>(initialValue);
 
+  /** Set once assembled; see {@link unregisterChild}. */
+  let mut_self: ChildObservable<A> | undefined = undefined;
+
   const complete = (): void => {
+    // A completed node is reached again through every parent and child that
+    // completes after it; running again would repeat the teardown and the
+    // ancestor walk in `unregisterChild` for each of them.
+    if (handle.isCompleted()) {
+      return;
+    }
+
     onComplete?.();
 
     handle.completeBase();
 
+    if (mut_self !== undefined) {
+      unregisterChild(mut_self, parents);
+    }
+
     // propagate to parents
     for (const par of parents) {
       par.tryComplete();
@@ -110,6 +124,10 @@ export const createSyncChildObservable = <A, P extends NonEmptyUnknownList>(
   };
 
   const tryComplete = (): void => {
+    if (handle.isCompleted()) {
+      return;
+    }
+
     tryCompleteChild({
       hasSubscriber: handle.hasSubscriber(),
       hasActiveChild: handle.hasActiveChild(),
@@ -136,6 +154,8 @@ export const createSyncChildObservable = <A, P extends NonEmptyUnknownList>(
 
   registerChild(observable, parents);
 
+  mut_self = observable;
+
   return observable;
 };
 
@@ -161,7 +181,6 @@ export const createInitializedSyncChildObservable = <
     // `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>
   );
 };
@@ -184,13 +203,28 @@ export const createAsyncChildObservable = <A, P extends NonEmptyUnknownList>(
 ): AsyncChildObservable<A, P> => {
   const handle = createObservableBaseHandle<A>(initialValue);
 
-  const { addDescendant, startUpdate } = createManagerObservableParts(handle);
+  const { addDescendant, deleteDescendant, startUpdate } =
+    createManagerObservableParts(handle);
+
+  /** Set once assembled; see {@link unregisterChild}. */
+  let mut_self: ChildObservable<A> | undefined = undefined;
 
   const complete = (): void => {
+    // A completed node is reached again through every parent and child that
+    // completes after it; running again would repeat the teardown and the
+    // ancestor walk in `unregisterChild` for each of them.
+    if (handle.isCompleted()) {
+      return;
+    }
+
     onComplete?.();
 
     handle.completeBase();
 
+    if (mut_self !== undefined) {
+      unregisterChild(mut_self, parents);
+    }
+
     // propagate to parents
     for (const par of parents) {
       par.tryComplete();
@@ -198,6 +232,10 @@ export const createAsyncChildObservable = <A, P extends NonEmptyUnknownList>(
   };
 
   const tryComplete = (): void => {
+    if (handle.isCompleted()) {
+      return;
+    }
+
     tryCompleteChild({
       hasSubscriber: handle.hasSubscriber(),
       hasActiveChild: handle.hasActiveChild(),
@@ -220,11 +258,13 @@ export const createAsyncChildObservable = <A, P extends NonEmptyUnknownList>(
     tryUpdate,
     tryComplete,
     complete,
-    extra: { parents, addDescendant },
+    extra: { parents, addDescendant, deleteDescendant },
   });
 
   registerChild(observable, parents);
 
+  mut_self = observable;
+
   return observable;
 };
 
@@ -322,6 +362,41 @@ const registerChild = <A,>(
   }
 };
 
+/**
+ * Undoes {@link registerChild} for a completed child: its parents forget it, and
+ * every manager it registered to stops propagating updates to it. Without this
+ * a completed node stayed reachable for as long as its root lived, and ran its
+ * `tryUpdate` on every update (#2134).
+ *
+ * A completion that happens while the child is still being constructed (from
+ * a leaf factory's `createTryUpdate`) precedes its registration, so there is
+ * nothing to undo; `mut_self` is still `undefined` then.
+ */
+const unregisterChild = <A,>(
+  child: ChildObservable<A>,
+  parents: ChildObservable<A>['parents'],
+): void => {
+  for (const p of parents) {
+    p.deleteChild(child);
+  }
+
+  const mut_rest = Array.from(parents);
+
+  while (Arr.isNonEmpty(mut_rest)) {
+    const p = mut_rest.pop();
+
+    if (p === undefined) {
+      break;
+    }
+
+    if (isManagerObservable(p)) {
+      p.deleteDescendant(child);
+    } else {
+      mut_rest.push(...p.parents);
+    }
+  }
+};
+
 const tryCompleteChild = <A,>({
   hasSubscriber,
   hasActiveChild,

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

@@ -72,6 +72,12 @@ export type ObservableBaseHandle<A> = Readonly<{
 
   addChild: <B>(child: ChildObservable<B>) => void;
 
+  /**
+   * Forgets `child`, which a completed child calls on each of its parents so
+   * that nothing keeps a reference to it (#2134).
+   */
+  deleteChild: <B>(child: ChildObservable<B>) => void;
+
   getSnapshot: () => Optional<A>;
 
   isCompleted: () => boolean;
@@ -115,7 +121,9 @@ export const createObservableBaseHandle = <A,>(
 ): ObservableBaseHandle<A> => {
   const id = issueObservableId();
 
-  let mut_children: readonly ChildObservable<unknown>[] = [];
+  // A set, not an array: a completed child removes itself, and that has to be
+  // O(1) for a UI that creates and completes derived nodes on every mount.
+  const mut_children: MutableSet<ChildObservable<unknown>> = new Set();
 
   const mut_subscribers: MutableMap<SubscriberId, Subscriber<A>> = new Map();
 
@@ -142,7 +150,7 @@ export const createObservableBaseHandle = <A,>(
 
     writers.setHasSubscriber(mut_subscribers.size > 0);
 
-    writers.setHasChild(Arr.isNonEmpty(mut_children));
+    writers.setHasChild(mut_children.size > 0);
   };
 
   const addSubscriber = (s: Subscriber<A>): SubscriberId => {
@@ -163,15 +171,17 @@ export const createObservableBaseHandle = <A,>(
   };
 
   const addChild = <B,>(child: ChildObservable<B>): void => {
-    mut_children = Arr.toPushed(
-      mut_children,
-
-      child as ChildObservable<unknown>,
-    );
+    mut_children.add(child);
 
     mut_writers?.setHasChild(true);
   };
 
+  const deleteChild = <B,>(child: ChildObservable<B>): void => {
+    mut_children.delete(child);
+
+    mut_writers?.setHasChild(mut_children.size > 0);
+  };
+
   const getSnapshot = (): Optional<A> => mut_currentValue;
 
   const isCompleted = (): boolean => mut_isCompleted;
@@ -180,8 +190,15 @@ export const createObservableBaseHandle = <A,>(
 
   const hasSubscriber = (): boolean => mut_subscribers.size > 0;
 
-  const hasActiveChild = (): boolean =>
-    mut_children.some((c) => !c.isCompleted);
+  const hasActiveChild = (): boolean => {
+    for (const c of mut_children) {
+      if (!c.isCompleted) {
+        return true;
+      }
+    }
+
+    return false;
+  };
 
   const setNext = (nextValue: A, nextUpdateToken: UpdateToken): void => {
     mut_updateToken = nextUpdateToken;
@@ -215,7 +232,8 @@ export const createObservableBaseHandle = <A,>(
 
     mut_writers?.setHasSubscriber(false);
 
-    // propagate to children
+    // Propagate to children. A child that completes removes itself from
+    // `mut_children` during this loop, which iterating a `Set` tolerates.
     for (const o of mut_children) {
       o.tryComplete();
     }
@@ -255,6 +273,7 @@ export const createObservableBaseHandle = <A,>(
     id,
     attach,
     addChild,
+    deleteChild,
     getSnapshot,
     isCompleted,
     updateToken,
@@ -273,41 +292,98 @@ export const createObservableBaseHandle = <A,>(
 export type ManagerObservableParts<A> = Readonly<{
   addDescendant: <B>(child: ChildObservable<B>) => void;
 
+  /**
+   * Takes `child` out of the propagation order, which a completed child calls
+   * on every manager it registered to (#2134).
+   */
+  deleteDescendant: <B>(child: ChildObservable<B>) => void;
+
   /** Emits `nextValue` and propagates the update to all descendants. */
   startUpdate: (nextValue: A) => void;
 }>;
 
 /**
  * Builds the manager half of a root or async-child observable. Both start their
- * own update propagation, so both keep a descendant set and a depth-ordered
- * propagation list; this is the single implementation of that pair (the class
- * version duplicated it across `RootObservableClass` and
- * `AsyncChildObservableClass`).
+ * own update propagation, so both keep a depth-ordered propagation list; this
+ * is the single implementation of it (the class version duplicated it across
+ * `RootObservableClass` and `AsyncChildObservableClass`).
+ *
+ * The descendants are kept in one insertion-ordered set per depth, so adding
+ * and removing one is O(1) apart from the first node of a new depth. The flat
+ * array `startUpdate` walks is rebuilt only when an update finds it stale: it
+ * used to be copied on every `addDescendant`, which made creating n nodes under
+ * one root O(n²). Rebuilding at the start of an update also keeps the walk a
+ * snapshot, as the copy-on-write array was — a node created or completed while
+ * an update is propagating does not change which nodes that update visits.
  */
 export const createManagerObservableParts = <A,>(
   handle: ObservableBaseHandle<A>,
 ): ManagerObservableParts<A> => {
-  let mut_propagationOrder: readonly ChildObservable<unknown>[] = [];
+  const mut_buckets: MutableMap<
+    number,
+    MutableSet<ChildObservable<unknown>>
+  > = new Map();
+
+  /** The keys of `mut_buckets`, ascending. */
+  let mut_depths: readonly number[] = [];
 
-  const mut_descendantsIdSet: MutableSet<ObservableId> = new Set();
+  /** `undefined` while stale. */
+  let mut_propagationOrder: readonly ChildObservable<unknown>[] | undefined =
+    [];
 
   const addDescendant = <B,>(child: ChildObservable<B>): void => {
-    if (mut_descendantsIdSet.has(child.id)) {
-      return;
+    const mut_bucket = mut_buckets.get(child.depth);
+
+    if (mut_bucket === undefined) {
+      mut_buckets.set(child.depth, new Set<ChildObservable<unknown>>([child]));
+
+      mut_depths = Arr.toInserted(
+        mut_depths,
+        binarySearch(mut_depths, child.depth),
+        child.depth,
+      );
+    } else {
+      if (mut_bucket.has(child)) {
+        return;
+      }
+
+      mut_bucket.add(child);
     }
 
-    mut_descendantsIdSet.add(child.id);
+    mut_propagationOrder = undefined;
+  };
 
-    const insertPos = binarySearch(
-      mut_propagationOrder.map((a) => a.depth),
-      child.depth,
-    );
+  const deleteDescendant = <B,>(child: ChildObservable<B>): void => {
+    // An emptied bucket stays, so that its depth is not inserted again.
+    const mut_bucket = mut_buckets.get(child.depth);
 
-    mut_propagationOrder = Arr.toInserted(
-      mut_propagationOrder,
-      insertPos,
-      child,
-    );
+    if (mut_bucket?.delete(child) === true) {
+      mut_propagationOrder = undefined;
+    }
+  };
+
+  const getPropagationOrder = (): readonly ChildObservable<unknown>[] => {
+    if (mut_propagationOrder !== undefined) {
+      return mut_propagationOrder;
+    }
+
+    const mut_order: ChildObservable<unknown>[] = [];
+
+    for (const depth of mut_depths) {
+      const bucket = mut_buckets.get(depth);
+
+      if (bucket !== undefined) {
+        // Not `push(...bucket)`: a spread passes every element as an argument,
+        // which overflows the stack for a bucket of a few hundred thousand.
+        for (const c of bucket) {
+          mut_order.push(c);
+        }
+      }
+    }
+
+    mut_propagationOrder = mut_order;
+
+    return mut_order;
   };
 
   const startUpdate = (nextValue: A): void => {
@@ -315,12 +391,12 @@ export const createManagerObservableParts = <A,>(
 
     handle.setNext(nextValue, updateToken);
 
-    for (const p of mut_propagationOrder) {
+    for (const p of getPropagationOrder()) {
       p.tryUpdate(updateToken);
     }
   };
 
-  return { addDescendant, startUpdate };
+  return { addDescendant, deleteDescendant, startUpdate };
 };
 
 /** Default `tryUpdate` for observables that never receive parent updates. */
@@ -389,12 +465,14 @@ export const assembleObservable = <
     operator: WithInitialValueOperator<A, B>,
   ): InitializedObservable<B>;
 
+  // A `WithInitialValueOperator` is also an `Operator`: nothing at run time
+  // tells the two apart, so this set only refines the return type (#1952).
+  // @sumi-expect-error functions/no-refinement-overload
   function pipe<B>(operator: Operator<A, B>): Observable<B>;
 
   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
       mut_observable as unknown as InitializedObservable<A>,
     );
   }
@@ -415,6 +493,8 @@ export const assembleObservable = <
 
     addChild: handle.addChild,
 
+    deleteChild: handle.deleteChild,
+
     getSnapshot: handle.getSnapshot,
 
     isCompleted: false,

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

@@ -59,7 +59,8 @@ export const createRootObservable = <
 ): Extension & RootObservable<A> => {
   const handle = createObservableBaseHandle<A>(initialValue);
 
-  const { addDescendant, startUpdate } = createManagerObservableParts(handle);
+  const { addDescendant, deleteDescendant, startUpdate } =
+    createManagerObservableParts(handle);
 
   const complete = (): void => {
     onComplete?.();
@@ -89,6 +90,7 @@ export const createRootObservable = <
     extra: {
       ...extension,
       addDescendant,
+      deleteDescendant,
     },
   });
 };

package/src/core/combine/combine.mts

@@ -75,7 +75,6 @@ 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>;
 
 /**

package/src/core/combine/merge.mts

@@ -66,7 +66,6 @@ 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>;
 
 const createMergeObservable = <const P extends NonEmptyUnknownList>(
@@ -90,7 +89,6 @@ const createMergeObservable = <const P extends NonEmptyUnknownList>(
 
         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>;
 
         setNext(nextValue, updateToken);

package/src/core/combine/zip.mts

@@ -68,7 +68,6 @@ 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>;
 
 const createZipObservable = <const A extends NonEmptyUnknownList>(
@@ -119,7 +118,6 @@ const createZipObservable = <const A extends NonEmptyUnknownList>(
           // `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/counter.mts

@@ -4,10 +4,17 @@ import type { CounterObservable, TimerId } from '../types/index.mjs';
 
 /**
  * Creates an observable that emits incremental numbers at a specified interval.
- * Starts with 0 immediately after subscription, then emits 1, 2, 3, ... every interval.
+ * Emits 0 in the macrotask right after `start()` (which runs at creation
+ * unless `startManually` is set), then 1, 2, 3, ... every interval. A
+ * subscriber added after that 0 has been emitted does not receive it.
  *
  * @param intervalMilliSeconds - The interval duration in milliseconds
- * @param startManually - If true, waits for manual start (default: false)
+ * @param options - Optional settings
+ * @param options.startManually - If true, waits for `start()` instead of
+ *   starting at creation (default: false)
+ * @param options.emitInitial - If false, skips the 0 emitted right after
+ *   `start()`, so the first value is 1, one interval later — like RxJS
+ *   `interval` rather than `timer(0, ms)` (default: true)
  * @returns An observable that emits sequential numbers
  *
  * @example
@@ -49,6 +56,7 @@ export const counter = (
   intervalMilliSeconds: number,
   options?: Readonly<{
     startManually?: boolean;
+    emitInitial?: boolean;
   }>,
 ): CounterObservable => {
   let mut_counter: SafeUint = asSafeUint(0);
@@ -60,13 +68,13 @@ export const counter = (
   let mut_isStarted = false;
 
   const resetTimer = (): void => {
-    if (mut_timerId0 === undefined || mut_timerId === undefined) {
-      return;
+    if (mut_timerId0 !== undefined) {
+      clearTimeout(mut_timerId0);
     }
 
-    clearInterval(mut_timerId0);
-
-    clearInterval(mut_timerId);
+    if (mut_timerId !== undefined) {
+      clearInterval(mut_timerId);
+    }
   };
 
   const observable = createRootObservable<
@@ -90,9 +98,11 @@ export const counter = (
           return;
         }
 
-        mut_timerId0 = setTimeout(() => {
-          startUpdate(mut_counter);
-        }, 0);
+        if (options?.emitInitial ?? true) {
+          mut_timerId0 = setTimeout(() => {
+            startUpdate(mut_counter);
+          }, 0);
+        }
 
         mut_timerId = setInterval(() => {
           mut_counter = SafeUint.add(1, mut_counter);