synstate 3.4.0 → 4.0.0

package/src/core/utils/current-scope.mts

@@ -0,0 +1,61 @@
+import type { Scope } from '../types/index.mjs';
+
+/** What a scope owns: an observable, as far as the scope needs to know it. */
+export type ScopeMember = Readonly<{
+  isCompleted: boolean;
+  dispose: () => void;
+}>;
+
+/**
+ * The side of a scope the rest of the core talks to, on top of its public
+ * face {@link Scope}. Kept out of the public API (`core/utils/**` is excluded
+ * from index generation), so that only `createScope` and its siblings decide
+ * what a scope owns.
+ */
+export type ScopeInternals = Scope &
+  Readonly<{
+    /** Takes `node` into the scope. */
+    adopt: (node: ScopeMember) => void;
+
+    /**
+     * Tells the scope that one of the nodes it adopted completed on its own,
+     * so that the scope can drop it and keep no reference to it. The node is
+     * completed (`isCompleted`) by the time it calls this.
+     */
+    release: () => void;
+
+    addCleanup: (cleanup: () => void) => void;
+  }>;
+
+/**
+ * The scope whose `run` is executing. A field rather than a module-level
+ * `let`, so that the one place writing it is visibly this object.
+ */
+const mut_slot: { current: ScopeInternals | undefined } = {
+  current: undefined,
+};
+
+export const getCurrentScopeInternals = (): ScopeInternals | undefined =>
+  mut_slot.current;
+
+/**
+ * Calls `body` with `scope` as the current scope (`undefined`: none) and
+ * restores the previous one afterwards, also when `body` throws.
+ */
+export const runWithScope = <R,>(
+  scope: ScopeInternals | undefined,
+  body: () => R,
+): R => {
+  const prev = mut_slot.current;
+
+  mut_slot.current = scope;
+
+  // `finally` is the point: an exception from `body` must not leave its scope
+  // current for whatever runs next. Nothing is caught.
+  // @sumi-expect-error exceptions/no-try
+  try {
+    return body();
+  } finally {
+    mut_slot.current = prev;
+  }
+};

package/src/core/utils/id-maker.mts

@@ -1,31 +1,21 @@
-import type {
-  ObservableId,
-  SubscriberId,
-  UpdateToken,
-} from '../types/index.mjs';
-
-function* idMaker<T extends symbol>(): Generator<T, T, T> {
-  let mut_i = 0;
-
-  while (true) {
-    // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-    yield Symbol(mut_i.toString()) as T;
-
-    mut_i += 1;
-  }
-}
-
-const observableIdMaker = idMaker<ObservableId>();
-
-const subscriberIdMaker = idMaker<SubscriberId>();
-
-const updateTokenMaker = idMaker<UpdateToken>();
-
-export const issueObservableId = (): ObservableId =>
-  observableIdMaker.next().value;
-
-export const issueSubscriberId = (): SubscriberId =>
-  subscriberIdMaker.next().value;
-
+import type { UpdateToken } from '../types/index.mjs';
+
+/**
+ * The token of a new update, which the update's root or async child passes to
+ * every node it reaches. A `Symbol` with no description, issued once per
+ * update and never per node, so its cost is spread over every node the
+ * update reaches. Unique without any counter, so the tokens of two copies of
+ * synstate in one program never coincide, and nothing is kept in a global.
+ */
 export const issueUpdateToken = (): UpdateToken =>
-  updateTokenMaker.next().value;
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+  Symbol() as UpdateToken;
+
+/**
+ * The token a node holds before its first update: one value shared by every
+ * node of this copy, since no update is ever issued it, so creating a node
+ * issues nothing.
+ */
+export const notUpdatedYet: UpdateToken =
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+  Symbol('synstate/not-updated-yet') as UpdateToken;

package/src/core/utils/index.mts

@@ -1,4 +1,5 @@
+export * from './current-scope.mjs';
 export * from './id-maker.mjs';
 export * from './max-depth.mjs';
+export * from './observable-brand.mjs';
 export * from './observable-utils.mjs';
-export * from './utils.mjs';

package/src/core/utils/max-depth.mts

@@ -1,11 +1,14 @@
-import { Arr, Optional, pipe } from 'ts-data-forge';
 import type { Observable } from '../types/index.mjs';
 
-export const maxDepth = (parents: readonly Observable<unknown>[]): number =>
-  pipe(Arr.maxBy(parents, (p) => p.depth))
-    // Explicit return type + non-curried `Optional.unwrapOr` call: TypeScript
-    // 7 (native)'s inference for this chained generic call resolves to
-    // `unknown` without them, even though TypeScript <= 6.0's checker
-    // resolves this fine.
-    .mapOptional((o): number => o.depth)
-    .map(Optional.unwrapOr(0)).value;
+/** The greatest `depth` among `parents`, or 0 when there are none. */
+export const maxDepth = (parents: readonly Observable<unknown>[]): number => {
+  let mut_max = 0;
+
+  for (const p of parents) {
+    if (p.depth > mut_max) {
+      mut_max = p.depth;
+    }
+  }
+
+  return mut_max;
+};

package/src/core/utils/observable-brand.mts

@@ -0,0 +1,12 @@
+/**
+ * The key every observable carries, set to `true` by `assembleObservable`. It
+ * lets `isObservable` tell an observable from any other value at run time —
+ * a `subscribe` method is not enough, since plain values may have one — and,
+ * as a type, makes the public observable types impossible to satisfy with an
+ * object literal: an imitation passed to an operator would lack the internal
+ * members propagation reads and fail at run time instead of at compile time.
+ *
+ * `Symbol.for`, so that an observable made by another copy of synstate in the
+ * same program is still recognized.
+ */
+export const observableBrand: unique symbol = Symbol.for('synstate/observable');

package/src/utils/create-boolean-state.mts

@@ -7,8 +7,8 @@ import { createState } from './create-state.mjs';
  * Extends `createState` with boolean-specific helpers like `toggle`, `setTrue`, and `setFalse`.
  *
  * @param initialState - The initial boolean value
- * @param options - {@link StateOptions}: `equals`, to pass on only the
- *   updates that change the state
+ * @param options - {@link StateOptions}: `equals` (default `Object.is`),
+ *   to pass on only the updates that change the state
  * @returns A 2-element tuple: `[state, { setTrue, setFalse, toggle, setState, updateState, resetState, getSnapshot, initialState }]`
  *
  * @example

package/src/utils/create-boolean-state.test.mts

@@ -1,10 +1,8 @@
 import { createBooleanState } from './create-boolean-state.mjs';
 
 describe(createBooleanState, () => {
-  test('with `equals`, setting what it already holds passes nothing on', () => {
-    const [state, { setTrue, setFalse }] = createBooleanState(false, {
-      equals: Object.is,
-    });
+  test('setting what it already holds passes nothing on when no `equals` is given', () => {
+    const [state, { setTrue, setFalse }] = createBooleanState(false);
 
     const mut_seen: boolean[] = [];
 
@@ -20,4 +18,20 @@ describe(createBooleanState, () => {
 
     assert.deepStrictEqual(mut_seen, [false, true]);
   });
+
+  test('passes on every update, equal or not, with `equals: () => false`', () => {
+    const [state, { setTrue }] = createBooleanState(true, {
+      equals: () => false,
+    });
+
+    const mut_seen: boolean[] = [];
+
+    state.subscribe((value) => {
+      mut_seen.push(value);
+    });
+
+    setTrue();
+
+    assert.deepStrictEqual(mut_seen, [true, true]);
+  });
 });

package/src/utils/create-reducer.mts

@@ -9,8 +9,8 @@ import { source, type InitializedObservable } from '../core/index.mjs';
  * @template A - The type of actions
  * @param reducer - A pure function that takes current state and action, returns new state
  * @param initialState - The initial value of the state
- * @param options - {@link StateOptions}: `equals`, to pass on only the
- *   dispatches that change the state
+ * @param options - {@link StateOptions}: `equals` (default `Object.is`),
+ *   to pass on only the dispatches that change the state
  * @returns A 3-element tuple: `[state, dispatch, { getSnapshot, initialState }]`.
  *   `dispatch` returns the state it leaves; once `state` is completed, that
  *   is the state held.
@@ -54,7 +54,7 @@ import { source, type InitializedObservable } from '../core/index.mjs';
  *   (s, action: Readonly<{ type: 'add'; amount: number }>) =>
  *     s + action.amount,
  *   0,
- *   { equals: Object.is },
+ *   { equals: () => false },
  * );
  *
  * const countHistory: number[] = [];
@@ -63,11 +63,11 @@ import { source, type InitializedObservable } from '../core/index.mjs';
  *   countHistory.push(value);
  * });
  *
- * dispatch({ type: 'add', amount: 0 }); // 0 again: nothing is passed on
+ * dispatch({ type: 'add', amount: 0 }); // 0 again, passed on all the same
  *
  * dispatch({ type: 'add', amount: 2 });
  *
- * assert.deepStrictEqual(countHistory, [0, 2]);
+ * assert.deepStrictEqual(countHistory, [0, 0, 2]);
  * ```
  *
  * @note Do not call `dispatch` from a subscriber or a projection while another
@@ -91,7 +91,7 @@ export const createReducer = <S, A>(
 ] => {
   const state = source<S>(initialState);
 
-  const equals = options?.equals;
+  const equals = options?.equals ?? Object.is;
 
   const dispatch = (action: A): S => {
     const currentState = state.getSnapshot().value;
@@ -99,7 +99,7 @@ export const createReducer = <S, A>(
     const nextState = reducer(currentState, action);
 
     // Once completed, `next` keeps the state held and returns it.
-    return equals?.(currentState, nextState) === true
+    return equals(currentState, nextState)
       ? currentState
       : state.next(nextState);
   };
@@ -124,8 +124,8 @@ export type StateOptions<S> = Readonly<{
    * `skipIfNoChange`: an update passed on here reaches whatever reads the
    * state directly before any operator can thin it out.
    *
-   * When omitted, every update is passed on, equal or not. That default is
-   * stocked in `NEXT_MAJOR.md` to become `Object.is`.
+   * Defaults to `Object.is`, so writing the value already held passes
+   * nothing on. Pass `() => false` to pass on every update, equal or not.
    *
    * @param current - The state held now
    * @param next - The state the update would set

package/src/utils/create-reducer.test.mts

@@ -2,34 +2,51 @@ import type { FixedLengthTuple } from 'ts-type-forge';
 import { createReducer } from './create-reducer.mjs';
 
 describe(createReducer, () => {
-  test('passes on every dispatch when no `equals` is given, equal or not', () => {
-    const [state, dispatch] = createReducer(keepOrAdd, 0);
+  test('does not pass on a dispatch whose next state is `Object.is`-equal to the current one when no `equals` is given', () => {
+    const [state, dispatch, { getSnapshot }] = createReducer(keepOrAdd, 0);
 
     const seen = record(state);
 
-    dispatch({ type: 'keep' });
+    assert.strictEqual(dispatch({ type: 'keep' }), 0);
 
-    dispatch({ type: 'add', amount: 1 });
+    assert.strictEqual(dispatch({ type: 'add', amount: 1 }), 1);
 
-    assert.deepStrictEqual(seen, [0, 0, 1]);
+    assert.strictEqual(dispatch({ type: 'add', amount: 0 }), 1);
+
+    assert.deepStrictEqual(seen, [0, 1]);
+
+    assert.strictEqual(getSnapshot(), 1);
   });
 
-  test('with `equals`, does not pass on a dispatch whose next state is equal to the current one', () => {
-    const [state, dispatch, { getSnapshot }] = createReducer(keepOrAdd, 0, {
-      equals: Object.is,
-    });
+  test('compares with `Object.is` by default, so `NaN` equals itself and `-0` differs from `0`', () => {
+    const [state, dispatch] = createReducer(
+      (_current: number, next: number) => next,
+      0,
+    );
 
     const seen = record(state);
 
-    assert.strictEqual(dispatch({ type: 'keep' }), 0);
+    dispatch(-0);
 
-    assert.strictEqual(dispatch({ type: 'add', amount: 1 }), 1);
+    dispatch(Number.NaN);
 
-    assert.strictEqual(dispatch({ type: 'add', amount: 0 }), 1);
+    dispatch(Number.NaN);
 
-    assert.deepStrictEqual(seen, [0, 1]);
+    assert.deepStrictEqual(seen, [0, -0, Number.NaN]);
+  });
 
-    assert.strictEqual(getSnapshot(), 1);
+  test('passes on every dispatch, equal or not, with `equals: () => false`', () => {
+    const [state, dispatch] = createReducer(keepOrAdd, 0, {
+      equals: () => false,
+    });
+
+    const seen = record(state);
+
+    dispatch({ type: 'keep' });
+
+    dispatch({ type: 'add', amount: 1 });
+
+    assert.deepStrictEqual(seen, [0, 0, 1]);
   });
 
   test('keeps the current object when `equals` finds the next one equal to it', () => {

package/src/utils/create-state.mts

@@ -28,8 +28,8 @@ const reducer = <S,>(state: S, action: Action<S>): S => {
  *
  * @template S - The type of the state
  * @param initialState - The initial value of the state
- * @param options - {@link StateOptions}: `equals`, to pass on only the
- *   updates that change the state
+ * @param options - {@link StateOptions}: `equals` (default `Object.is`),
+ *   to pass on only the updates that change the state
  * @returns A 3-element tuple: `[state, setState, { updateState, resetState, getSnapshot, initialState }]`
  *
  * @example

package/src/utils/create-state.test.mts

@@ -1,20 +1,8 @@
 import { createState } from './create-state.mjs';
 
 describe(createState, () => {
-  test('passes on every update when no `equals` is given, equal or not', () => {
-    const [state, setState] = createState(0);
-
-    const seen = record(state);
-
-    setState(0);
-
-    assert.deepStrictEqual(seen, [0, 0]);
-  });
-
-  test('with `equals`, setState, updateState and resetState do not pass on a value equal to the current one', () => {
-    const [state, setState, { updateState, resetState }] = createState(0, {
-      equals: Object.is,
-    });
+  test('setState, updateState and resetState do not pass on a value `Object.is`-equal to the current one when no `equals` is given', () => {
+    const [state, setState, { updateState, resetState }] = createState(0);
 
     const seen = record(state);
 
@@ -54,6 +42,16 @@ describe(createState, () => {
     assert.strictEqual(getSnapshot(), 1);
   });
 
+  test('passes on every update, equal or not, with `equals: () => false`', () => {
+    const [state, setState] = createState(0, { equals: () => false });
+
+    const seen = record(state);
+
+    setState(0);
+
+    assert.deepStrictEqual(seen, [0, 0]);
+  });
+
   // What `equals` is for: whatever reads the state, directly or through
   // anything derived from it, is told only of a real change, and an equal
   // value written over the current one leaves the object that is there.

package/dist/core/base/create-child-observable.d.mts

@@ -1,72 +0,0 @@
-import { type Optional, type Some } from 'ts-data-forge';
-import { type AsyncChildObservable, type InitializedSyncChildObservable, type NonEmptyUnknownList, type SyncChildObservable, type UpdateToken, type Wrap } from '../types/index.mjs';
-/**
- * The internal tools a sync-child leaf factory (`map`, `filter`, `zip`, …)
- * receives — the replacement for the `protected` methods a subclass of
- * `SyncChildObservableClass` used to inherit.
- */
-export type SyncChildObservableTools<A> = Readonly<{
-    /** Emits `nextValue` under `updateToken` and notifies subscribers. */
-    setNext: (nextValue: A, updateToken: UpdateToken) => void;
-    getSnapshot: () => Optional<A>;
-    /** Completes this observable (leaf teardown included). */
-    complete: () => void;
-}>;
-/**
- * The internal tools an async-child leaf factory (`debounce`, `switchMap`, …)
- * receives. Async children additionally start their own update propagation.
- */
-export type AsyncChildObservableTools<A> = Readonly<{
-    /** Emits `nextValue` and propagates the update to all descendants. */
-    startUpdate: (nextValue: A) => void;
-}> & SyncChildObservableTools<A>;
-type ChildObservableConfigBase<P extends NonEmptyUnknownList> = Readonly<{
-    parents: Wrap<P>;
-    depth?: number;
-    /**
-     * Leaf teardown (clear timers, unsubscribe inner observables, …), run at
-     * the beginning of `complete()` — the closure replacement for
-     * `override complete() { teardown(); super.complete(); }`.
-     */
-    onComplete?: () => void;
-    /**
-     * Whether this observable can emit nothing more although some parent is
-     * still live, asked whenever a parent completes. `true` completes it then,
-     * as all parents completing does (`zip` once a completed source's queue is
-     * empty).
-     */
-    canEmitNoMore?: () => boolean;
-}>;
-export type ChildObservableConfig<A, P extends NonEmptyUnknownList> = ChildObservableConfigBase<P> & Readonly<{
-    initialValue: Optional<A>;
-}>;
-export type InitializedChildObservableConfig<A, P extends NonEmptyUnknownList> = ChildObservableConfigBase<P> & Readonly<{
-    initialValue: Some<A>;
-}>;
-/**
- * Creates a sync-child observable — the classless replacement for extending
- * `SyncChildObservableClass`.
- *
- * `createTryUpdate` receives the internal tools and returns the `tryUpdate`
- * implementation (the former `override tryUpdate`). It runs during
- * construction, before the observable is registered to its parents; leaf
- * state can live either in the enclosing factory scope or inside the
- * `createTryUpdate` closure.
- */
-export declare const createSyncChildObservable: <A, P extends NonEmptyUnknownList>({ parents, depth, initialValue, onComplete, canEmitNoMore, }: ChildObservableConfig<A, P>, createTryUpdate: (tools: SyncChildObservableTools<A>) => (updateToken: UpdateToken) => void) => SyncChildObservable<A, P>;
-/**
- * Creates a sync-child observable that always holds a value.
- *
- * Runtime-wise this is exactly `createSyncChildObservable`; only the types of
- * `getSnapshot` and `pipe` are narrowed, which is what the
- * `InitializedSyncChildObservableClass` overrides existed for.
- */
-export declare const createInitializedSyncChildObservable: <A, P extends NonEmptyUnknownList>(config: InitializedChildObservableConfig<A, P>, createTryUpdate: (tools: SyncChildObservableTools<A>) => (updateToken: UpdateToken) => void) => InitializedSyncChildObservable<A, P>;
-/**
- * Creates an async-child observable — the classless replacement for extending
- * `AsyncChildObservableClass`. See {@link createSyncChildObservable} for the
- * `createTryUpdate` contract.
- */
-export declare const createAsyncChildObservable: <A, P extends NonEmptyUnknownList>({ parents, depth, initialValue, onComplete, canEmitNoMore, }: ChildObservableConfig<A, P>, createTryUpdate: (tools: AsyncChildObservableTools<A>) => (updateToken: UpdateToken) => void) => AsyncChildObservable<A, P>;
-export {};
-//# sourceMappingURL=create-child-observable.d.mts.map

package/dist/core/base/create-child-observable.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"create-child-observable.d.mts","sourceRoot":"","sources":["../../../src/core/base/create-child-observable.mts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,QAAQ,EAAE,KAAK,IAAI,EAAE,MAAM,eAAe,CAAC;AAG9D,OAAO,EAGL,KAAK,oBAAoB,EAEzB,KAAK,8BAA8B,EACnC,KAAK,mBAAmB,EAGxB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,IAAI,EACV,MAAM,oBAAoB,CAAC;AAQ5B;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI,QAAQ,CAAC;IACjD,sEAAsE;IACtE,OAAO,EAAE,CAAC,SAAS,EAAE,CAAC,EAAE,WAAW,EAAE,WAAW,KAAK,IAAI,CAAC;IAE1D,WAAW,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC;IAE/B,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,yBAAyB,CAAC,CAAC,IAAI,QAAQ,CAAC;IAClD,sEAAsE;IACtE,WAAW,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,IAAI,CAAC;CACrC,CAAC,GACA,wBAAwB,CAAC,CAAC,CAAC,CAAC;AAE9B,KAAK,yBAAyB,CAAC,CAAC,SAAS,mBAAmB,IAAI,QAAQ,CAAC;IACvE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAEjB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IAExB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC;CAC/B,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,CAC/B,CAAC,EACD,CAAC,SAAS,mBAAmB,IAC3B,yBAAyB,CAAC,CAAC,CAAC,GAC9B,QAAQ,CAAC;IACP,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;CAC3B,CAAC,CAAC;AAEL,MAAM,MAAM,gCAAgC,CAC1C,CAAC,EACD,CAAC,SAAS,mBAAmB,IAC3B,yBAAyB,CAAC,CAAC,CAAC,GAC9B,QAAQ,CAAC;IACP,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;CACvB,CAAC,CAAC;AAEL;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GAAI,CAAC,EAAE,CAAC,SAAS,mBAAmB,gEAOrE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,mBACb,CACf,KAAK,EAAE,wBAAwB,CAAC,CAAC,CAAC,KAC/B,CAAC,WAAW,EAAE,WAAW,KAAK,IAAI,KACtC,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAoF1B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC,GAC/C,CAAC,EACD,CAAC,SAAS,mBAAmB,UAErB,gCAAgC,CAAC,CAAC,EAAE,CAAC,CAAC,mBAC7B,CACf,KAAK,EAAE,wBAAwB,CAAC,CAAC,CAAC,KAC/B,CAAC,WAAW,EAAE,WAAW,KAAK,IAAI,KACtC,8BAA8B,CAAC,CAAC,EAAE,CAAC,CASrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,GAAI,CAAC,EAAE,CAAC,SAAS,mBAAmB,gEAOtE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,mBACb,CACf,KAAK,EAAE,yBAAyB,CAAC,CAAC,CAAC,KAChC,CAAC,WAAW,EAAE,WAAW,KAAK,IAAI,KACtC,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAwF3B,CAAC"}