synstate 5.0.0 → 6.0.0

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

@@ -14,7 +14,9 @@ import type {
   NonEmptyUnknownList,
   Observable,
   Operator,
+  Subscription,
   SyncChildObservable,
+  UpdateToken,
   WithInitialValueOperator,
   Wrap,
 } from '../types/index.mjs';
@@ -196,6 +198,40 @@ export class AsyncChildObservableClass<A, const P extends NonEmptyUnknownList>
       this.complete();
     });
   }
+
+  /**
+   * Subscribes to the inner observable that the projection of `switchMap` /
+   * `mergeMap` returned.
+   *
+   * If the inner observable already holds a value (`just(x)`, a state), it
+   * emits that value synchronously while being subscribed. That first value
+   * is emitted with `updateToken`, the token of the update that ran the
+   * projection, so it joins the propagation in progress like a sync
+   * operator's value would. Starting an update of its own instead would
+   * reach the nodes below before the current update reached this
+   * observable's siblings: a node reading both would see the new inner value
+   * beside stale sibling values (a glitch), and would emit twice.
+   *
+   * Values the inner observable emits later start updates of their own.
+   */
+  protected subscribeInner(
+    inner: Observable<A>,
+    updateToken: UpdateToken,
+  ): Subscription {
+    let mut_isSubscribing = true;
+
+    const subscription = inner.subscribe((value) => {
+      if (mut_isSubscribing) {
+        this.setNext(value, updateToken);
+      } else {
+        this.startUpdate(value);
+      }
+    });
+
+    mut_isSubscribing = false;
+
+    return subscription;
+  }
 }
 
 /**
@@ -273,12 +309,15 @@ const isDevelopmentProcess = (): boolean => {
 };
 
 /**
- * Whether {@link registerChild} checks for a circular dependency: everywhere
- * but in a process whose `NODE_ENV` is `production`. A child's parents exist
- * before it and cannot be changed afterwards, so only code that rewrites an
- * observable's readonly `parents` can make a cycle, while the walk over every
- * ancestor is paid on every creation. Where there is no `process` (a browser
- * bundle) the check is off.
+ * Whether {@link registerChild} checks for a circular dependency: on in
+ * development, off in production. The public API cannot make a cycle — a
+ * child's parents exist before it and cannot be changed afterwards — so the
+ * check is a safety net for what propagation assumes (a DAG, a depth for every
+ * node) against code that rewrites an observable's readonly `parents`, and
+ * development is where that code runs first. It walks every ancestor of each
+ * new observable, a cost production does not pay: the check is off when
+ * `NODE_ENV` is `production`, and where there is no `process` (a browser
+ * bundle).
  */
 export const checksCircularDependency: boolean = isDevelopmentProcess();
 

package/src/core/operators/flat-map-sync-inner.test.mts

@@ -0,0 +1,90 @@
+import type { FixedLengthTuple } from 'ts-type-forge';
+import { combine } from '../combine/index.mjs';
+import { just, source } from '../create/index.mjs';
+import { map } from './map.mjs';
+import { mergeMap } from './merge-map.mjs';
+import { switchMap } from './switch-map.mjs';
+
+describe('an inner observable that holds a value is passed on in the update that projected it', () => {
+  test('switchMap: a sibling read with it is never stale', () => {
+    const a$ = source<number>(1);
+
+    // Created before `m$`, so the update visits it first.
+    const s$ = a$.pipe(switchMap((x) => just(`s${x.toString()}`)));
+
+    const m$ = a$.pipe(map((x) => `m${x.toString()}`));
+
+    const mut_history: string[] = [];
+
+    combine([m$, s$]).subscribe(([m, s]) => {
+      mut_history.push(`${m},${s}`);
+    });
+
+    a$.next(2);
+
+    a$.next(3);
+
+    assert.deepStrictEqual(mut_history, ['m2,s2', 'm3,s3']);
+  });
+
+  test('switchMap: a child of both it and its parent emits once per update', () => {
+    const a$ = source<number>(1);
+
+    const s$ = a$.pipe(switchMap((x) => just(x * 10)));
+
+    const mut_history: FixedLengthTuple<2, number>[] = [];
+
+    combine([a$, s$]).subscribe((pair) => {
+      mut_history.push(pair);
+    });
+
+    a$.next(2);
+
+    a$.next(3);
+
+    assert.deepStrictEqual(mut_history, [
+      [2, 20],
+      [3, 30],
+    ]);
+  });
+
+  test('switchMap: an inner that emits later still starts an update of its own', () => {
+    const a$ = source<number>();
+
+    const inner$ = source<number>();
+
+    const s$ = a$.pipe(switchMap(() => inner$));
+
+    const mut_history: number[] = [];
+
+    s$.subscribe((v) => {
+      mut_history.push(v);
+    });
+
+    a$.next(1);
+
+    inner$.next(5);
+
+    inner$.next(6);
+
+    assert.deepStrictEqual(mut_history, [5, 6]);
+  });
+
+  test('mergeMap: a sibling read with it is never stale', () => {
+    const a$ = source<number>(1);
+
+    const s$ = a$.pipe(mergeMap((x) => just(`s${x.toString()}`)));
+
+    const m$ = a$.pipe(map((x) => `m${x.toString()}`));
+
+    const mut_history: string[] = [];
+
+    combine([m$, s$]).subscribe(([m, s]) => {
+      mut_history.push(`${m},${s}`);
+    });
+
+    a$.next(2);
+
+    assert.deepStrictEqual(mut_history, ['m2,s2']);
+  });
+});

package/src/core/operators/keep-equal-parts.mts

@@ -59,9 +59,7 @@ import type {
  *
  * const board$ = message$.pipe(keepEqualParts());
  *
- * const firstCard$ = board$
- *   .pipe(map((board) => board.cards[0]))
- *   .pipe(skipIfNoChange());
+ * const firstCard$ = board$.pipe(map((board) => board.cards[0]));
  *
  * const boardHistory: Board[] = [];
  *

package/src/core/operators/map-cut-off.test.mts

@@ -0,0 +1,215 @@
+import { expectType } from 'ts-data-forge';
+import { combine } from '../combine/index.mjs';
+import { source } from '../create/index.mjs';
+import { mapTo, withIndex } from '../predefined/index.mjs';
+import type { Observable } from '../types/index.mjs';
+import { map } from './map.mjs';
+
+describe('map stops a result equal to the one it holds', () => {
+  test('a result equal by Object.is is not emitted', () => {
+    const a$ = source<number>();
+
+    const parity$ = a$.pipe(map((x) => x % 2));
+
+    const mut_history: number[] = [];
+
+    parity$.subscribe((p) => {
+      mut_history.push(p);
+    });
+
+    a$.next(1);
+
+    a$.next(3);
+
+    a$.next(4);
+
+    a$.next(6);
+
+    a$.next(7);
+
+    assert.deepStrictEqual(mut_history, [1, 0, 1]);
+  });
+
+  test('the value computed from an initial value counts as the one held', () => {
+    const a$ = source<number>(1);
+
+    const parity$ = a$.pipe(map((x) => x % 2));
+
+    const mut_history: number[] = [];
+
+    parity$.subscribe((p) => {
+      mut_history.push(p);
+    });
+
+    a$.next(3);
+
+    a$.next(4);
+
+    assert.deepStrictEqual(mut_history, [1, 0]);
+  });
+
+  test('a node below is not woken when the result is equal', () => {
+    const a$ = source<number>(1);
+
+    const parity$ = a$.pipe(map((x) => x % 2));
+
+    let mut_calls = 0;
+
+    const label$ = parity$.pipe(
+      map((p) => {
+        mut_calls += 1;
+
+        return p === 0 ? 'even' : 'odd';
+      }),
+    );
+
+    label$.subscribe(() => {});
+
+    const callsAfterSetup = mut_calls;
+
+    a$.next(3);
+
+    a$.next(5);
+
+    assert.strictEqual(mut_calls, callsAfterSetup);
+
+    a$.next(6);
+
+    assert.strictEqual(mut_calls, callsAfterSetup + 1);
+  });
+
+  test('a node reading a stopped map and another parent still updates once', () => {
+    const a$ = source<number>(1);
+
+    const parity$ = a$.pipe(map((x) => x % 2));
+
+    const mut_history: string[] = [];
+
+    combine([a$, parity$]).subscribe(([a, p]) => {
+      mut_history.push(`${a.toString()},${p.toString()}`);
+    });
+
+    a$.next(3);
+
+    a$.next(4);
+
+    assert.deepStrictEqual(mut_history, ['1,1', '3,1', '4,0']);
+  });
+
+  test('NaN equals NaN, and 0 differs from -0, as Object.is says', () => {
+    const a$ = source<number>();
+
+    const r$ = a$.pipe(map((x) => x));
+
+    const mut_history: number[] = [];
+
+    r$.subscribe((v) => {
+      mut_history.push(v);
+    });
+
+    a$.next(Number.NaN);
+
+    a$.next(Number.NaN);
+
+    a$.next(0);
+
+    a$.next(-0);
+
+    assert.deepStrictEqual(mut_history, [Number.NaN, 0, -0]);
+  });
+
+  test('`equals` replaces Object.is', () => {
+    const a$ = source<Readonly<{ id: number; name: string }>>();
+
+    const id$ = a$.pipe(
+      map((x) => ({ id: x.id }), { equals: (p, q) => p.id === q.id }),
+    );
+
+    const mut_history: number[] = [];
+
+    id$.subscribe(({ id }) => {
+      mut_history.push(id);
+    });
+
+    a$.next({ id: 1, name: 'a' });
+
+    a$.next({ id: 1, name: 'b' });
+
+    a$.next({ id: 2, name: 'b' });
+
+    assert.deepStrictEqual(mut_history, [1, 2]);
+  });
+
+  test('`equals: () => false` emits every result', () => {
+    const click$ = source<undefined>();
+
+    const one$ = click$.pipe(map(() => 1, { equals: () => false }));
+
+    const mut_history: number[] = [];
+
+    one$.subscribe((v) => {
+      mut_history.push(v);
+    });
+
+    click$.next(undefined);
+
+    click$.next(undefined);
+
+    assert.deepStrictEqual(mut_history, [1, 1]);
+  });
+
+  test('the mapping function no longer receives an index', () => {
+    const a$ = source<number>();
+
+    // @ts-expect-error `map` passes the value alone; use `withIndex`.
+    const r$ = a$.pipe(map((x: number, i: number) => x + i));
+
+    expect(r$).toBeDefined();
+  });
+});
+
+describe('operators that turn events into values emit every event', () => {
+  test('mapTo emits its value on every event', () => {
+    const reset$ = source<undefined>();
+
+    const action$ = reset$.pipe(mapTo('reset'));
+
+    expectType<typeof action$, Observable<'reset'>>('=');
+
+    const mut_history: string[] = [];
+
+    action$.subscribe((v) => {
+      mut_history.push(v);
+    });
+
+    reset$.next(undefined);
+
+    reset$.next(undefined);
+
+    assert.deepStrictEqual(mut_history, ['reset', 'reset']);
+  });
+
+  test('withIndex counts from 0, and gives -1 to an initial value', () => {
+    const a$ = source<string>('init');
+
+    const indexed$ = a$.pipe(withIndex());
+
+    assert.deepStrictEqual(indexed$.getSnapshot().value, [-1, 'init']);
+
+    const mut_history: (readonly [number, string])[] = [];
+
+    indexed$.subscribe((v) => {
+      mut_history.push(v);
+    });
+
+    a$.next('x');
+
+    a$.next('x');
+
+    assert.deepStrictEqual(mut_history, [
+      [-1, 'init'],
+      [0, 'x'],
+      [1, 'x'],
+    ]);
+  });
+});

package/src/core/operators/map.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 { Optional, SafeUint, asSafeUint, expectType } from 'ts-data-forge';
+import { Optional, expectType } from 'ts-data-forge';
 import { SyncChildObservableClass } from '../class/index.mjs';
 import { source } from '../create/index.mjs';
 import type {
@@ -18,51 +18,64 @@ import type {
 import { withInitialValue } from './with-initial-value.mjs';
 
 /**
- * Transforms each value emitted by the source using a mapping function that also receives the emission index.
+ * Transforms each value emitted by the source with a mapping function, and
+ * emits the result unless it equals the one already held.
+ *
+ * The comparison is `Object.is` unless `equals` says otherwise, so a result
+ * that did not change wakes nothing below. To pass on every result — an event
+ * turned into a value, say — give `equals: () => false`, or use `mapTo`. The
+ * mapping function receives the value alone; `withIndex` attaches an index.
  *
  * @template A - The type of values from the source
  * @template B - The type of mapped values
- * @param mapFn - A function that maps each value (receives value and index)
- * @returns An operator that maps values with index
+ * @param mapFn - A function that maps each value
+ * @param options - `equals` compares a result with the one held
+ * @returns An operator that maps values
  *
  * @example
  * ```ts
  * //  Timeline:
  * //
- * //  num$      "A"      "B"      "C"
- * //  indexed$  "0: A"   "1: B"   "2: C"
+ * //  num$      1   3   4   6   7
+ * //  parity$   1       0       1
  * //
  * //  Explanation:
- * //  - mapWithIndex transforms each value along with its index
- * //  - Index starts at 0 and increments with each emission
+ * //  - map transforms each value
+ * //  - A result equal to the one held is not emitted
  *
- * const num$ = source<string>();
+ * const num$ = source<number>();
  *
- * const indexed$ = num$.pipe(map((x, i) => `${i}: ${x}`));
+ * const parity$ = num$.pipe(map((x) => x % 2));
  *
- * const valueHistory: string[] = [];
+ * const valueHistory: number[] = [];
  *
- * indexed$.subscribe((s) => {
- *   valueHistory.push(s);
+ * parity$.subscribe((p) => {
+ *   valueHistory.push(p);
  * });
  *
- * num$.next('A'); // 0: A
+ * num$.next(1); // 1
+ *
+ * num$.next(3); // still 1: not emitted
  *
- * num$.next('B'); // 1: B
+ * num$.next(4); // 0
  *
- * num$.next('C'); // 2: C
+ * num$.next(6); // still 0: not emitted
  *
- * assert.deepStrictEqual(valueHistory, ['0: A', '1: B', '2: C']);
+ * num$.next(7); // 1
+ *
+ * assert.deepStrictEqual(valueHistory, [1, 0, 1]);
  * ```
  */
 export const map = <A, B>(
-  mapFn: (x: A, index: SafeUint | -1) => B,
+  mapFn: (x: A) => B,
+  options?: Readonly<{ equals?: (x: B, y: B) => boolean }>,
 ): KeepInitialValueOperator<A, B> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
   ((parentObservable) =>
     new MapObservableClass(
       parentObservable,
       mapFn,
+      options?.equals ?? Object.is,
     )) as KeepInitialValueOperator<A, B>;
 
 /* implementation */
@@ -71,24 +84,23 @@ class MapObservableClass<A, B>
   extends SyncChildObservableClass<B, readonly [A]>
   implements MapOperatorObservable<A, B>
 {
-  readonly #mapFn: (x: A, index: SafeUint | -1) => B;
-  #mut_index: SafeUint | -1;
+  readonly #mapFn: (x: A) => B;
+  readonly #equals: (x: B, y: B) => boolean;
 
   constructor(
     parentObservable: Observable<A>,
-    mapFn: (x: A, index: SafeUint | -1) => B,
+    mapFn: (x: A) => B,
+    equals: (x: B, y: B) => boolean,
   ) {
     super({
       parents: [parentObservable],
-      initialValue: Optional.map(parentObservable.getSnapshot(), (x) =>
-        mapFn(x, -1),
-      ),
+      initialValue: Optional.map(parentObservable.getSnapshot(), mapFn),
     });
 
-    this.#mut_index = -1;
-
     this.#mapFn = mapFn;
 
+    this.#equals = equals;
+
     this.attach();
   }
 
@@ -101,10 +113,15 @@ class MapObservableClass<A, B>
       return; // skip update
     }
 
-    this.#mut_index =
-      this.#mut_index === -1 ? asSafeUint(0) : SafeUint.add(1, this.#mut_index);
+    const next = this.#mapFn(sn.value);
+
+    const held = this.getSnapshot();
+
+    if (Optional.isSome(held) && this.#equals(held.value, next)) {
+      return; // the result did not change
+    }
 
-    this.setNext(this.#mapFn(sn.value, this.#mut_index), updateToken);
+    this.setNext(next, updateToken);
   }
 }
 
@@ -116,7 +133,7 @@ if (import.meta.vitest !== undefined) {
   {
     const s: Observable<number> = source<number>();
 
-    const _d1 = s.pipe(map((x, i) => x + i));
+    const _d1 = s.pipe(map((x) => x + 1));
 
     expectType<typeof _d1, Observable<number>>('=');
   }
@@ -126,7 +143,7 @@ if (import.meta.vitest !== undefined) {
 
     const m: InitializedObservable<number> = s.pipe(withInitialValue(0));
 
-    const _d = m.pipe(map((x, i) => x + i));
+    const _d = m.pipe(map((x) => x + 1));
 
     expectType<typeof _d, InitializedObservable<number>>('=');
   }

package/src/core/operators/merge-map.mts

@@ -174,9 +174,7 @@ class MergeMapObservableClass<A, B>
 
     const observable = innerScope.run(() => this.#mapToObservable(sn.value));
 
-    const subscription = observable.subscribe((curr) => {
-      this.startUpdate(curr);
-    });
+    const subscription = this.subscribeInner(observable, updateToken);
 
     this.#mut_subscriptions = Arr.toPushed(
       this.#mut_subscriptions,

package/src/core/operators/switch-map.mts

@@ -179,9 +179,7 @@ class SwitchMapObservableClass<A, B>
 
     const observable = innerScope.run(() => this.#mapToObservable(sn.value));
 
-    this.#mut_subscription = observable.subscribe((curr) => {
-      this.startUpdate(curr);
-    });
+    this.#mut_subscription = this.subscribeInner(observable, updateToken);
   }
 
   protected override teardown(): void {

package/src/core/predefined/operators/attach-index.mts

@@ -1,10 +1,23 @@
-import type { SafeUint } from 'ts-type-forge';
-import { map } from '../../operators/index.mjs';
-import type { KeepInitialValueOperator } from '../../types/index.mjs';
+// Sumi bans classes, `this`, method syntax and writes to `this` outside a
+// `mut_` binding; an observable is a class (`ObservableBaseClass` says why),
+// so those rules are waived here (D-63).
+// @sumi-expect-error-file classes/no-class
+// @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 { Optional, SafeUint, asSafeUint } from 'ts-data-forge';
+import { SyncChildObservableClass } from '../../class/index.mjs';
+import type {
+  KeepInitialValueOperator,
+  Observable,
+  UpdateToken,
+} from '../../types/index.mjs';
 
 /**
  * Attaches a sequential index to each emitted value, producing `[index, value]` tuples.
- * Index starts at 0 and increments with each emission.
+ * Index starts at 0 and increments with each emission; a value the source
+ * already holds when this is applied gets -1. Use it where `map` used to
+ * receive an index.
  *
  * @template A - The type of values from the source
  * @returns An operator that emits `[index, value]` tuples
@@ -54,10 +67,54 @@ import type { KeepInitialValueOperator } from '../../types/index.mjs';
 export const withIndex = <A,>(): KeepInitialValueOperator<
   A,
   readonly [SafeUint | -1, A]
-> => map((a, i) => [i, a] as const);
+> =>
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+  ((parentObservable) =>
+    new WithIndexObservableClass(parentObservable)) as KeepInitialValueOperator<
+    A,
+    readonly [SafeUint | -1, A]
+  >;
 
 /**
  * Alias for `withIndex`.
  * @see withIndex
  */
 export const attachIndex = withIndex;
+
+/* implementation */
+
+class WithIndexObservableClass<A> extends SyncChildObservableClass<
+  readonly [SafeUint | -1, A],
+  readonly [A]
+> {
+  #mut_index: SafeUint | -1;
+
+  constructor(parentObservable: Observable<A>) {
+    super({
+      parents: [parentObservable],
+      initialValue: Optional.map(
+        parentObservable.getSnapshot(),
+        (a) => [-1, a] as const,
+      ),
+    });
+
+    this.#mut_index = -1;
+
+    this.attach();
+  }
+
+  override tryUpdate(updateToken: UpdateToken): void {
+    const par = this.parents[0];
+
+    const sn = par.getSnapshot();
+
+    if (par.updateToken !== updateToken || Optional.isNone(sn)) {
+      return; // skip update
+    }
+
+    this.#mut_index =
+      this.#mut_index === -1 ? asSafeUint(0) : SafeUint.add(1, this.#mut_index);
+
+    this.setNext([this.#mut_index, sn.value], updateToken);
+  }
+}

package/src/core/predefined/operators/map-to.mts

@@ -3,7 +3,11 @@ import type { KeepInitialValueOperator } from '../../types/index.mjs';
 
 /**
  * Maps all emitted values to a constant value, ignoring the source values.
- * Equivalent to `map(() => value)`.
+ * Emits on every source value although the value never changes — where
+ * `map(() => value)` would stop every result after the first as equal — so
+ * it is the one for turning events into a value. The value's type is
+ * inferred as written, as with `as const`: `mapTo('reset')` gives
+ * `'reset'`, not `string`.
  *
  * @template A - The type of values from the source
  * @template B - The type of the constant value
@@ -41,5 +45,5 @@ import type { KeepInitialValueOperator } from '../../types/index.mjs';
  * assert.deepStrictEqual(valueHistory, [1, 1, 1]);
  * ```
  */
-export const mapTo = <A, B>(value: B): KeepInitialValueOperator<A, B> =>
-  map(() => value);
+export const mapTo = <A, const B>(value: B): KeepInitialValueOperator<A, B> =>
+  map(() => value, { equals: () => false });

package/src/utils/create-reducer.mts

@@ -150,7 +150,7 @@ export type StateOptions<S> = Readonly<{
    * written, and every part of it deeply equal to the same part of the
    * current state is replaced by that part (`replaceEqualDeep` of
    * ts-data-forge): a reader of an unchanged part keeps the object it has, so
-   * `skipIfNoChange()` with `Object.is` stops it. When the whole next state is
+   * `map`, comparing with `Object.is`, stops there. When the whole next state is
    * deeply equal, the current state is kept and nothing is passed on, so
    * `equals` can stay `Object.is`.
    *