synstate 6.2.1 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synstate",
-  "version": "6.2.1",
+  "version": "7.0.0",
   "description": "Type-safe State Management Library for TypeScript/JavaScript",
   "repository": {
     "type": "git",
@@ -29,21 +29,22 @@
     "LICENSE"
   ],
   "dependencies": {
-    "ts-data-forge": "^14.10.2",
-    "ts-std-forge": "^0.5.2",
+    "ts-data-forge": "^14.11.0",
+    "ts-std-forge": "^0.5.3",
     "ts-type-forge": "^9.2.2"
   },
   "devDependencies": {
     "@preact/signals-core": "1.14.4",
     "@reduxjs/toolkit": "2.13.0",
-    "@sumi-lang/cli": "0.1.5",
+    "@sumi-lang/cli": "0.1.6",
     "@types/react": "19.3.0",
     "@vitest/browser-playwright": "5.0.5",
     "argparse": "3.0.3",
-    "eslint-config-typed": "7.3.1",
-    "eslint-plugin-ts-data-forge": "0.10.8",
-    "eslint-plugin-ts-fortress": "1.3.12",
-    "eslint-plugin-ts-type-forge": "0.8.17",
+    "eslint": "10.13.0",
+    "eslint-config-typed": "7.4.0",
+    "eslint-plugin-ts-data-forge": "0.10.9",
+    "eslint-plugin-ts-fortress": "1.3.13",
+    "eslint-plugin-ts-type-forge": "0.8.18",
     "jotai": "3.0.1",
     "mobx": "7.1.0",
     "playwright": "1.64.1",
@@ -53,9 +54,9 @@
     "react": "19.3.1",
     "rxjs": "7.8.2",
     "solid-js": "1.9.17",
-    "synstate-react-hooks": "6.2.1",
-    "synstate-react-hooks-compat": "6.2.1",
-    "ts-repo-utils": "10.7.1",
+    "synstate-react-hooks": "7.0.0",
+    "synstate-react-hooks-compat": "7.0.0",
+    "ts-repo-utils": "10.7.2",
     "valtio": "2.3.2",
     "zustand": "5.0.15"
   },

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

@@ -2,7 +2,7 @@
 // @sumi-expect-error-file banned-syntax/no-this
 // @sumi-expect-error-file functions/prefer-arrow-function
 // @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
-import { hasKey, isRecord, type Optional, type Some } from 'ts-data-forge';
+import { hasKey, isRecord, Optional, type Some } from 'ts-data-forge';
 import { panic } from 'ts-std-forge';
 import type { MutableSet } from 'ts-type-forge';
 import type {
@@ -20,7 +20,7 @@ import type {
   WithInitialValueOperator,
   Wrap,
 } from '../types/index.mjs';
-import { maxDepth } from '../utils/index.mjs';
+import { issueUnqueuedToken, maxDepth } from '../utils/index.mjs';
 import { ManagerObservableClass } from './manager-observable-class.mjs';
 import { ObservableBaseClass } from './observable-base-class.mjs';
 import { toNode, type ChildNode } from './observable-node.mjs';
@@ -198,6 +198,45 @@ export class AsyncChildObservableClass<A, const P extends NonEmptyUnknownList>
     });
   }
 
+  /**
+   * `attach`, then projects the value `parent` holds when `switchMap` /
+   * `mergeMap` is created, as `map` and `filter` start from it; a completed
+   * parent is not projected. Nothing observes the operator yet, so a value the
+   * inner observable emits while it is subscribed is only stored: the token is
+   * one no update is queued with.
+   *
+   * If the projection throws, the operator is disposed, which disposes what the
+   * projection made and takes the operator off its parent, and the exception
+   * goes on to the caller of `pipe`.
+   */
+  protected attachProjectingHeldValue<V>(
+    parent: Observable<V>,
+    project: (value: V, updateToken: UpdateToken) => void,
+  ): void {
+    this.attach();
+
+    const sn = parent.getSnapshot();
+
+    if (this.isCompleted || Optional.isNone(sn)) {
+      return;
+    }
+
+    // A flag and `finally` rather than `catch` and rethrow: Sumi bans
+    // `try..catch`, and the exception is never caught on its way to `pipe`.
+    let mut_projected = false;
+
+    // @sumi-expect-error exceptions/no-try
+    try {
+      project(sn.value, issueUnqueuedToken());
+
+      mut_projected = true;
+    } finally {
+      if (!mut_projected) {
+        this.dispose();
+      }
+    }
+  }
+
   /**
    * Subscribes to the inner observable that the projection of `switchMap` /
    * `mergeMap` returned.
@@ -212,10 +251,13 @@ export class AsyncChildObservableClass<A, const P extends NonEmptyUnknownList>
    * glitch), and would emit twice.
    *
    * Values the inner observable emits later start updates of their own.
+   * `onComplete` is called when it completes, which may be while it is being
+   * subscribed, before this returns.
    */
   protected subscribeInner(
     inner: Observable<A>,
     updateToken: UpdateToken,
+    onComplete?: () => void,
   ): Subscription {
     let mut_isSubscribing = true;
 
@@ -225,7 +267,7 @@ export class AsyncChildObservableClass<A, const P extends NonEmptyUnknownList>
       } else {
         this.startUpdate(value);
       }
-    });
+    }, onComplete);
 
     mut_isSubscribing = false;
 

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

@@ -2,7 +2,8 @@
 // @sumi-expect-error-file banned-syntax/no-this
 // @sumi-expect-error-file functions/prefer-arrow-function
 // @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
-import { Arr, type Optional, type Some } from 'ts-data-forge';
+import type { Optional, Some } from 'ts-data-forge';
+import * as Arr from 'ts-data-forge/array';
 import { unreachable } from 'ts-std-forge';
 import type {
   AsyncChildObservable,
@@ -300,7 +301,9 @@ class CustomAsyncChildObservableClass<
   const P extends NonEmptyUnknownList,
 > extends AsyncChildObservableClass<A, P> {
   #mut_teardowns: readonly (() => void)[] | undefined;
-  readonly #hooks: AsyncChildObservableHooks;
+  // Undefined until `init` returns, which may complete the observable first;
+  // `complete` then calls `flush` before there is a hook to call.
+  readonly #hooks: AsyncChildObservableHooks | undefined;
 
   constructor(
     config: ChildObservableConfig<A, P>,
@@ -344,15 +347,15 @@ class CustomAsyncChildObservableClass<
   }
 
   override tryUpdate(updateToken: UpdateToken): void {
-    this.#hooks.tryUpdate(updateToken);
+    this.#hooks?.tryUpdate(updateToken);
   }
 
   override canEmitNoMore(): boolean {
-    return this.#hooks.canEmitNoMore?.() === true;
+    return this.#hooks?.canEmitNoMore?.() === true;
   }
 
   protected override flush(): void {
-    this.#hooks.flush?.();
+    this.#hooks?.flush?.();
   }
 
   protected override teardown(): void {

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

@@ -2,7 +2,8 @@
 // @sumi-expect-error-file banned-syntax/no-this
 // @sumi-expect-error-file functions/prefer-arrow-function
 // @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
-import { Arr, type Optional } from 'ts-data-forge';
+import type { Optional } from 'ts-data-forge';
+import * as Arr from 'ts-data-forge/array';
 import type { ReadonlyRecord } from 'ts-type-forge';
 import type { RootObservable } from '../types/index.mjs';
 import { RootObservableClass } from './root-observable-class.mjs';

package/src/core/class/propagation-state.mts

@@ -11,7 +11,7 @@
  * costs about twice as much per access as a module binding, on a path every
  * update takes.
  */
-import { Arr } from 'ts-data-forge';
+import * as Arr from 'ts-data-forge/array';
 import { panic } from 'ts-std-forge';
 import type { MutableSet } from 'ts-type-forge';
 import type { UpdateToken } from '../types/index.mjs';

package/src/core/class/write-during-propagation.test.mts

@@ -4,7 +4,12 @@ import type { FixedLengthTuple } from 'ts-type-forge';
 import { createState } from '../../utils/index.mjs';
 import { combine } from '../combine/index.mjs';
 import { fromSubscribable, source } from '../create/index.mjs';
-import { map, switchMap } from '../operators/index.mjs';
+import {
+  map,
+  switchMap,
+  throttle,
+  withBufferedFrom,
+} from '../operators/index.mjs';
 import { writeDuringPropagationWarning } from './root-observable-class.mjs';
 
 describe('a write to a root observable while an update is propagating (#2336)', () => {
@@ -156,7 +161,8 @@ describe('a write to a root observable while an update is propagating (#2336)',
 
     assert.deepStrictEqual(warn, []);
 
-    assert.deepStrictEqual(mut_history, [10]);
+    // 0 from the value `outer$` held when `switchMap` was created.
+    assert.deepStrictEqual(mut_history, [0, 10]);
   });
 
   test('does not warn when a root created during propagation emits while it is created', async () => {
@@ -188,7 +194,8 @@ describe('a write to a root observable while an update is propagating (#2336)',
 
     assert.deepStrictEqual(warn, []);
 
-    assert.deepStrictEqual(mut_history, [10]);
+    // 0 from the value `outer$` held when `switchMap` was created.
+    assert.deepStrictEqual(mut_history, [0, 10]);
   });
 
   test('a subscriber that throws does not leave the propagation flag set', async () => {
@@ -214,12 +221,76 @@ describe('a write to a root observable while an update is propagating (#2336)',
   });
 });
 
+describe('a stateful operator updates its state before setNext, which a write from a subscriber re-enters', () => {
+  test('withBufferedFrom keeps a value written to the buffered observable for the next batch', async () => {
+    const [data$, setData] = createState('a');
+
+    const [trigger$, setTrigger] = createState(0);
+
+    const result$ = trigger$.pipe(withBufferedFrom(data$));
+
+    const mut_history: (readonly [number, readonly string[]])[] = [];
+
+    result$.subscribe((v) => {
+      mut_history.push(v);
+
+      if (v[0] === 1) {
+        setData('b');
+      }
+    });
+
+    await captureWarnings(() => {
+      setTrigger(1);
+    });
+
+    setTrigger(2);
+
+    assert.deepStrictEqual(mut_history, [
+      [0, ['a']],
+      [1, []],
+      [2, ['b']],
+    ]);
+  });
+
+  test('throttle drops a value a subscriber writes to the parent inside the window, and keeps one timer', async () => {
+    vi.useFakeTimers();
+
+    onTestFinished(() => {
+      vi.useRealTimers();
+    });
+
+    const [src$, setSrc] = createState(0);
+
+    const throttled$ = src$.pipe(throttle(1000));
+
+    const mut_history: number[] = [];
+
+    throttled$.subscribe((v) => {
+      mut_history.push(v);
+
+      if (v === 1) {
+        setSrc(2);
+      }
+    });
+
+    await captureWarnings(() => {
+      setSrc(1);
+    });
+
+    assert.deepStrictEqual(mut_history, [0, 1]);
+
+    throttled$.complete();
+
+    assert.strictEqual(vi.getTimerCount(), 0);
+  });
+});
+
 /**
  * Runs `run` with `console.warn` replaced by a mock, and returns the messages
  * it was called with.
  */
 const captureWarnings = async (
-  run: () => Promise<void> | void,
+  run: () => Promise<void> | undefined,
 ): Promise<readonly unknown[]> => {
   const warn = vi.fn();
 

package/src/core/combine/derive.mts

@@ -5,7 +5,8 @@
 // @sumi-expect-error-file banned-syntax/no-this
 // @sumi-expect-error-file functions/prefer-arrow-function
 // @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
-import { Arr, Optional } from 'ts-data-forge';
+import { Optional } from 'ts-data-forge';
+import * as Arr from 'ts-data-forge/array';
 import type { NonEmptyTuple } from 'ts-type-forge';
 import { SyncChildObservableClass } from '../class/index.mjs';
 import type {

package/src/core/combine/zip.mts

@@ -5,7 +5,8 @@
 // @sumi-expect-error-file banned-syntax/no-this
 // @sumi-expect-error-file functions/prefer-arrow-function
 // @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
-import { Arr, Optional, createQueue, expectType } from 'ts-data-forge';
+import { Optional, createQueue, expectType } from 'ts-data-forge';
+import * as Arr from 'ts-data-forge/array';
 import type { NonEmptyTuple, Tuple } from 'ts-type-forge';
 import { SyncChildObservableClass } from '../class/index.mjs';
 import { source } from '../create/index.mjs';
@@ -150,8 +151,10 @@ class ZipObservableClass<const A extends NonEmptyUnknownList>
 
     this.setNext(nextValue, updateToken);
 
+    // After the update has reached what is derived from it, as in `take`
+    // (#2371).
     if (this.canEmitNoMore()) {
-      this.complete();
+      this.completeAfterPropagation();
     }
   }
 

package/src/core/create/counter.mts

@@ -5,7 +5,7 @@
 // @sumi-expect-error-file banned-syntax/no-this
 // @sumi-expect-error-file functions/prefer-arrow-function
 // @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
-import { asSafeUint, Optional, SafeUint } from 'ts-data-forge';
+import { asSafeUint, Optional, type SafeUint } from 'ts-data-forge';
 import type { PositiveSafeIntWithSmallInt } from 'ts-type-forge';
 import { RootObservableClass } from '../class/index.mjs';
 import type { CounterObservable, TimerId } from '../types/index.mjs';
@@ -154,7 +154,7 @@ class CounterObservableClass
     }
 
     this.#mut_timerId = setInterval(() => {
-      this.#mut_counter = SafeUint.add(1, this.#mut_counter);
+      this.#mut_counter = asSafeUint(this.#mut_counter + 1);
 
       this.#emit(this.#mut_counter);
     }, this.#intervalMilliSeconds);

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

@@ -8,6 +8,7 @@
 import { Optional, Result } from 'ts-data-forge';
 import { RootObservableClass } from '../class/index.mjs';
 import type { FromPromiseObservable } from '../types/index.mjs';
+import { rethrowOutOfPromise } from '../utils/index.mjs';
 
 /**
  * Creates an observable from a Promise factory that receives an `AbortSignal`.
@@ -96,35 +97,44 @@ class FromAbortablePromiseObservableClass<A, E = unknown>
 
     const promise = factory(this.#abortController.signal);
 
+    // `onRejected` beside `onFulfilled`, so that only the promise's own
+    // rejection becomes an Err: what a subscriber throws on the Ok value is not
+    // the promise's (#2931). A `.catch` after `.then` would take both, and is
+    // also a step later.
     promise
-      .then((value) => {
-        if (this.isCompleted) {
-          return;
-        }
+      // eslint-disable-next-line unicorn/prefer-then-catch -- its suggestion, `.then(onFulfilled).catch(onRejected)`, would take what a subscriber throws too
+      .then(
+        (value) => {
+          if (this.isCompleted) {
+            return;
+          }
 
-        this.startUpdate(Result.ok(value));
-      })
-      .catch((error: unknown) => {
-        if (this.isCompleted) {
-          return;
-        }
+          this.startUpdate(Result.ok(value));
+        },
+        (error: unknown) => {
+          if (this.isCompleted) {
+            return;
+          }
 
-        // Silently ignore AbortError — it means the observable was
-        // intentionally completed (e.g., by switchMap).
-        if (error instanceof DOMException && error.name === 'AbortError') {
-          return;
-        }
+          // Silently ignore AbortError — it means the observable was
+          // intentionally completed (e.g., by switchMap).
+          if (error instanceof DOMException && error.name === 'AbortError') {
+            return;
+          }
 
-        this.startUpdate(
-          Result.err(
-            // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-            error as E,
-          ),
-        );
-      })
+          this.startUpdate(
+            Result.err(
+              // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+              error as E,
+            ),
+          );
+        },
+      )
+      .catch(rethrowOutOfPromise)
       .finally(() => {
         this.complete();
-      });
+      })
+      .catch(rethrowOutOfPromise);
   }
 
   protected override teardown(): void {

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

@@ -7,6 +7,7 @@
 import { Optional, Result } from 'ts-data-forge';
 import { RootObservableClass } from '../class/index.mjs';
 import type { FromPromiseObservable } from '../types/index.mjs';
+import { rethrowOutOfPromise } from '../utils/index.mjs';
 
 /**
  * Creates an observable from a Promise.
@@ -66,28 +67,37 @@ class FromPromiseObservableClass<A, E = unknown>
   constructor(promise: Promise<A>) {
     super({ initialValue: Optional.none });
 
+    // `onRejected` beside `onFulfilled`, so that only the promise's own
+    // rejection becomes an Err: what a subscriber throws on the Ok value is not
+    // the promise's (#2931). A `.catch` after `.then` would take both, and is
+    // also a step later.
     promise
-      .then((value) => {
-        if (this.isCompleted) {
-          return;
-        }
+      // eslint-disable-next-line unicorn/prefer-then-catch -- its suggestion, `.then(onFulfilled).catch(onRejected)`, would take what a subscriber throws too
+      .then(
+        (value) => {
+          if (this.isCompleted) {
+            return;
+          }
 
-        this.startUpdate(Result.ok(value));
-      })
-      .catch((error: unknown) => {
-        if (this.isCompleted) {
-          return;
-        }
+          this.startUpdate(Result.ok(value));
+        },
+        (error: unknown) => {
+          if (this.isCompleted) {
+            return;
+          }
 
-        this.startUpdate(
-          Result.err(
-            // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-            error as E,
-          ),
-        );
-      })
+          this.startUpdate(
+            Result.err(
+              // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+              error as E,
+            ),
+          );
+        },
+      )
+      .catch(rethrowOutOfPromise)
       .finally(() => {
         this.complete();
-      });
+      })
+      .catch(rethrowOutOfPromise);
   }
 }

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

@@ -0,0 +1,97 @@
+import { Optional, Result } from 'ts-data-forge';
+import { panic } from 'ts-std-forge';
+import { fromAbortablePromise } from './from-abortable-promise.mjs';
+import { fromPromise } from './from-promise.mjs';
+
+describe('fromPromise and fromAbortablePromise report only the promise’s own rejection as an Err (#2931)', () => {
+  test.each([
+    ['fromPromise', () => fromPromise(Promise.resolve(1))],
+    [
+      'fromAbortablePromise',
+      () => fromAbortablePromise(() => Promise.resolve(1)),
+    ],
+  ] as const)(
+    '%s: a subscriber that throws on the Ok value gets no Err',
+    async (_, create) => {
+      vi.useFakeTimers();
+
+      onTestFinished(() => {
+        vi.useRealTimers();
+      });
+
+      const mut_events: string[] = [];
+
+      const result$ = create();
+
+      result$.subscribe(
+        (r) => {
+          mut_events.push(Result.isOk(r) ? `ok ${r.value}` : 'err');
+
+          if (Result.isOk(r)) {
+            panic('bug in a subscriber');
+          }
+        },
+        () => {
+          mut_events.push('complete');
+        },
+      );
+
+      await settlePromises();
+
+      assert.deepStrictEqual(mut_events, ['ok 1', 'complete']);
+
+      // The subscriber's exception is not swallowed: it is thrown again from a
+      // task of its own.
+      expect(() => {
+        vi.runOnlyPendingTimers();
+      }).toThrow('bug in a subscriber');
+    },
+  );
+
+  const rejection = new Error('rejected');
+
+  test.each([
+    ['fromPromise', () => fromPromise(Promise.reject(rejection))],
+    [
+      'fromAbortablePromise',
+      () => fromAbortablePromise(() => Promise.reject(rejection)),
+    ],
+  ] as const)('%s: a rejection is an Err', async (_, create) => {
+    const result$ = create();
+
+    const mut_events: string[] = [];
+
+    result$.subscribe(
+      (r) => {
+        mut_events.push(
+          Result.isErr(r) && r.value === rejection ? 'err rejected' : 'ok',
+        );
+      },
+      () => {
+        mut_events.push('complete');
+      },
+    );
+
+    await settlePromises();
+
+    assert.deepStrictEqual(mut_events, ['err rejected', 'complete']);
+  });
+
+  test('fromPromise holds the value by the time an await of the same promise resumes', async () => {
+    const promise = Promise.resolve(1);
+
+    const result$ = fromPromise(promise);
+
+    await promise;
+
+    assert.deepStrictEqual(result$.getSnapshot(), Optional.some(Result.ok(1)));
+  });
+});
+
+/** Lets the promise chains already started run to their end. */
+const settlePromises = async (): Promise<void> => {
+  for (const _ of Array.from({ length: 10 })) {
+    // eslint-disable-next-line no-await-in-loop -- each await lets the chains take one more step
+    await Promise.resolve();
+  }
+};

package/src/core/create/source.mts

@@ -4,7 +4,8 @@
 // @sumi-expect-error-file classes/no-class
 // @sumi-expect-error-file banned-syntax/no-this
 // @sumi-expect-error-file functions/prefer-arrow-function
-import { Arr, Optional } from 'ts-data-forge';
+import { Optional } from 'ts-data-forge';
+import * as Arr from 'ts-data-forge/array';
 import { RootObservableClass } from '../class/index.mjs';
 import type {
   InitializedSourceObservable,

package/src/core/operators/filter.mts

@@ -12,7 +12,7 @@ import {
   isString,
   Optional,
   pipe,
-  SafeUint,
+  type SafeUint,
 } from 'ts-data-forge';
 import { SyncChildObservableClass } from '../class/index.mjs';
 import { source } from '../create/index.mjs';
@@ -132,8 +132,7 @@ class FilterObservableClass<A>
       return; // skip update
     }
 
-    this.#mut_index =
-      this.#mut_index === -1 ? asSafeUint(0) : SafeUint.add(1, this.#mut_index);
+    this.#mut_index = asSafeUint(this.#mut_index + 1);
 
     if (this.#predicate(sn.value, this.#mut_index)) {
       this.setNext(sn.value, updateToken);