synstate 3.3.0 → 4.0.0

package/src/core/types/index.mts

@@ -2,5 +2,6 @@ export * from './id.mjs';
 export * from './observable-family.mjs';
 export * from './observable-kind.mjs';
 export * from './observable.mjs';
+export * from './scope.mjs';
 export * from './timer.mjs';
 export * from './types.mjs';

package/src/core/types/observable-family.mts

@@ -20,7 +20,11 @@ import type { NonEmptyUnknownList } from './types.mjs';
 // RootObservable
 
 export type InitializedSourceObservable<A> = Readonly<{
-  next: (value: A) => void;
+  /**
+   * Passes `value` on and returns it. Once completed, passes nothing on and
+   * returns the value held.
+   */
+  next: (value: A) => A;
 }> &
   InitializedRootObservable<A>;
 
@@ -206,6 +210,8 @@ export type PairwiseOperatorObservable<A> = SyncChildObservable<
   readonly [A]
 >;
 
+export type TakeOperatorObservable<A> = SyncChildObservable<A, readonly [A]>;
+
 export type TakeWhileOperatorObservable<A> = SyncChildObservable<
   A,
   readonly [A]

package/src/core/types/observable.mts

@@ -1,6 +1,13 @@
-import { expectType, type Optional, type Some } from 'ts-data-forge';
+import {
+  expectType,
+  hasKey,
+  isRecord,
+  type Optional,
+  type Some,
+} from 'ts-data-forge';
 import type { FixedLengthTuple, StrictOmit } from 'ts-type-forge';
-import type { ObservableId, UpdateToken } from './id.mjs';
+import { observableBrand } from '../utils/index.mjs';
+import type { UpdateToken } from './id.mjs';
 import type { ObservableKind } from './observable-kind.mjs';
 import type { NonEmptyUnknownList, Subscription } from './types.mjs';
 
@@ -19,42 +26,37 @@ import type { NonEmptyUnknownList, Subscription } from './types.mjs';
  */
 
 type CreateObservableType<A, Kind extends ObservableKind> = Readonly<{
-  id: ObservableId;
+  [observableBrand]: true;
+
   kind: Kind;
 
-  // reactive dependency tree structure
+  /**
+   * One more than the deepest observable this one is derived from; 0 for a
+   * root. An update reaches observables in ascending depth, so every parent
+   * has emitted before its child reads it.
+   */
   depth: Kind extends 'root' ? 0 : number;
-  addChild: <B>(child: ChildObservable<B>) => void;
-  deleteChild: <B>(child: ChildObservable<B>) => void;
 
-  // state
   getSnapshot: () => Optional<A>;
   isCompleted: boolean;
-  updateToken: UpdateToken;
-  hasSubscriber: boolean;
-  hasChild: boolean;
-  hasActiveChild: () => boolean;
 
   /**
-   * Whether this observable completes itself once nothing uses it any more —
-   * once it has neither subscribers nor live children when one of its children
-   * completes. True when completing it would release something: it has a
-   * teardown of its own (a timer, an inner subscription) or a parent with
-   * `autoComplete`. A `source` or `createState` and everything derived from
-   * it alone are never completed this way, so completing a derived observable
-   * cannot end a state that something else may still read (#2133).
+   * The token of the update in which this observable last emitted. A child's
+   * `tryUpdate` receives the token of the update now propagating; a parent
+   * whose token differs did not emit in it. The token is opaque: compare it,
+   * store it, or pass it on to `setNext`.
    */
-  autoComplete: boolean;
+  updateToken: UpdateToken;
 
-  tryUpdate: (updateToken: UpdateToken) => void;
-  tryComplete: () => void;
   complete: () => void;
 
   /**
-   * Completes this observable and takes it out of the graph, without telling
-   * its parents: unlike `complete()`, it never completes an upstream
-   * observable, whatever its `autoComplete`. Its descendants are completed as
-   * by `complete()` once none of their parents is live.
+   * Completes this observable and takes it out of the graph, for whoever owns
+   * it (a scope) to release it. Neither this nor `complete()` reaches upstream:
+   * a child completing never completes its parents, which may be shared
+   * (#2133). Its descendants complete once none of their parents is live.
+   * Unlike `complete()`, it passes on nothing the observable still holds: a
+   * `debounce` or `audit` drops its pending value instead of emitting it.
    */
   dispose: () => void;
   subscribe: (onNext: (v: A) => void, onComplete?: () => void) => Subscription;
@@ -97,15 +99,6 @@ namespace ObservableTypeConverter {
     Readonly<{
       parents: Wrap<P>;
     }>;
-
-  export type ToManager<
-    A,
-    O extends CreateObservableType<A, 'async child' | 'root'>,
-  > = O &
-    Readonly<{
-      addDescendant: <B>(child: ChildObservable<B>) => void;
-      deleteDescendant: <B>(child: ChildObservable<B>) => void;
-    }>;
 }
 
 export type SyncChildObservable<
@@ -125,9 +118,10 @@ export type InitializedSyncChildObservable<
 export type AsyncChildObservable<
   A,
   P extends NonEmptyUnknownList = NonEmptyUnknownList,
-> = ObservableTypeConverter.ToManager<
+> = ObservableTypeConverter.ToChild<
   A,
-  ObservableTypeConverter.ToChild<A, CreateObservableType<A, 'async child'>, P>
+  CreateObservableType<A, 'async child'>,
+  P
 >;
 
 export type InitializedAsyncChildObservable<
@@ -140,10 +134,7 @@ export type ChildObservable<
   P extends NonEmptyUnknownList = NonEmptyUnknownList,
 > = AsyncChildObservable<A, P> | SyncChildObservable<A, P>;
 
-export type RootObservable<A> = ObservableTypeConverter.ToManager<
-  A,
-  CreateObservableType<A, 'root'>
->;
+export type RootObservable<A> = CreateObservableType<A, 'root'>;
 
 export type InitializedRootObservable<A> =
   ObservableTypeConverter.ToInitialized<A, RootObservable<A>>;
@@ -180,6 +171,27 @@ export type Operator<A, B> =
   | DropInitialValueOperator<A, B>
   | KeepInitialValueOperator<A, B>;
 
+/**
+ * Tells an observable made by synstate from any other value, by the brand
+ * every observable carries. Checking for a `subscribe` method instead would
+ * also accept plain values that happen to have one.
+ *
+ * @example
+ *
+ * ```ts
+ * const [count$] = createState(0);
+ *
+ * assert.isTrue(isObservable(count$));
+ *
+ * // A `subscribe` method alone does not make an observable.
+ * assert.isFalse(isObservable({ subscribe: () => {} }));
+ *
+ * assert.isFalse(isObservable(0));
+ * ```
+ */
+export const isObservable = (value: unknown): value is Observable<unknown> =>
+  isRecord(value) && hasKey(value, observableBrand);
+
 export const isManagerObservable = <A,>(
   obs: Observable<A>,
 ): obs is ManagerObservable<A> => obs.kind !== 'sync child';
@@ -210,9 +222,32 @@ export type WrapInitialized<A extends readonly unknown[]> = Readonly<{
 // type GetDestTypeOfOperator<Op extends Operator<unknown, unknown>> =
 //   Op extends Operator<unknown, infer B> ? B : never;
 
-expectType<keyof AsyncChildObservable<unknown>, 'addDescendant'>('>=');
+// Only the members meant for users are public; the rest live on the
+// internal node types in `core/class` (#2117).
+expectType<
+  keyof Observable<unknown>,
+  | typeof observableBrand
+  | 'kind'
+  | 'depth'
+  | 'getSnapshot'
+  | 'isCompleted'
+  | 'updateToken'
+  | 'complete'
+  | 'dispose'
+  | 'subscribe'
+  | 'pipe'
+>('=');
 
-expectType<keyof RootObservable<unknown>, 'addDescendant'>('>=');
+expectType<
+  keyof ChildObservable<unknown>,
+  keyof Observable<unknown> | 'parents'
+>('=');
+
+// Everything but the brand is not enough to pass for an observable.
+expectType<
+  StrictOmit<RootObservable<unknown>, typeof observableBrand>,
+  Observable<unknown>
+>('!<=');
 
 expectType<RootObservable<unknown>['depth'], 0>('=');
 

package/src/core/types/scope.mts

@@ -0,0 +1,27 @@
+/**
+ * A unit of ownership: the observables created while {@link Scope.run} is
+ * running belong to the scope, and {@link Scope.dispose} releases them all at
+ * once. Create one with `createScope`.
+ *
+ * For authors of libraries built on synstate (a UI binding mounts and unmounts
+ * by scope); application code that defines its state at module level does not
+ * need it.
+ */
+export type Scope = Readonly<{
+  /**
+   * Calls `body` with this scope as the current one and returns what it
+   * returns. Only what `body` creates synchronously joins the scope: by the time
+   * code after an `await` or in a callback runs, `run` has already returned.
+   *
+   * On a disposed scope it warns, still calls `body`, and nothing created there
+   * belongs to any scope.
+   */
+  run: <R>(body: () => R) => R;
+
+  /**
+   * Disposes the child scopes (newest first), calls the functions registered
+   * with `onScopeDispose` (newest first), disposes the owned observables
+   * (newest first) and leaves the parent scope. Calling it again does nothing.
+   */
+  dispose: () => void;
+}>;

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-event-emitter.mts

@@ -18,13 +18,13 @@ import { source, type Observable } from '../core/index.mjs';
  *
  * emitClick(); // logs: Clicked!
  *
- * assert.deepStrictEqual(mut_clickCount.value, 1);
+ * assert.strictEqual(mut_clickCount.value, 1);
  *
  * emitClick();
  *
  * emitClick();
  *
- * assert.deepStrictEqual(mut_clickCount.value, 3);
+ * assert.strictEqual(mut_clickCount.value, 3);
  * ```
  */
 export const createEventEmitter = (): readonly [

package/src/utils/create-reducer.mts

@@ -9,9 +9,11 @@ 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
- * @returns A 3-element tuple: `[state, dispatch, { getSnapshot, initialState }]`
+ * @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.
  *
  * @example
  * ```ts
@@ -52,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[] = [];
@@ -61,12 +63,19 @@ 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
+ * update is propagating: the write propagates immediately, so subscribers can
+ * see an intermediate state, and it logs a `console.warn` (once per
+ * observable). Derive the value from its source instead —
+ * `const b$ = a$.pipe(map((a) => a * 2))` rather than
+ * `a$.subscribe((a) => { setB(a * 2); })`.
  */
 export const createReducer = <S, A>(
   reducer: Reducer<S, A>,
@@ -82,20 +91,17 @@ 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;
 
     const nextState = reducer(currentState, action);
 
-    if (equals?.(currentState, nextState) === true) {
-      return currentState;
-    }
-
-    state.next(nextState);
-
-    return nextState;
+    // Once completed, `next` keeps the state held and returns it.
+    return equals(currentState, nextState)
+      ? currentState
+      : state.next(nextState);
   };
 
   const getSnapshot = (): S => state.getSnapshot().value;
@@ -118,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', () => {
@@ -65,6 +82,18 @@ describe(createReducer, () => {
 
     assert.deepStrictEqual(mut_asked, [[0, 5]]);
   });
+
+  test('once the state is completed, a dispatch returns the current state', () => {
+    const [state, dispatch, { getSnapshot }] = createReducer(keepOrAdd, 0);
+
+    dispatch({ type: 'add', amount: 1 });
+
+    state.complete();
+
+    assert.strictEqual(dispatch({ type: 'add', amount: 2 }), 1);
+
+    assert.strictEqual(getSnapshot(), 1);
+  });
 });
 
 type Count = Readonly<{ count: number }>;

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
@@ -88,6 +88,13 @@ const reducer = <S,>(state: S, action: Action<S>): S => {
  *   'label:bug page:2',
  * ]);
  * ```
+ *
+ * @note Do not call `setState`, `updateState` or `resetState` from a subscriber or a projection while another
+ * update is propagating: the write propagates immediately, so subscribers can
+ * see an intermediate state, and it logs a `console.warn` (once per
+ * observable). Derive the value from its source instead —
+ * `const b$ = a$.pipe(map((a) => a * 2))` rather than
+ * `a$.subscribe((a) => { setB(a * 2); })`.
  */
 export const createState = <S,>(
   initialState: S,