synstate 5.0.1 → 6.1.0

package/src/core/combine/derive.test.mts

@@ -0,0 +1,190 @@
+import { Optional, expectType } from 'ts-data-forge';
+import { source } from '../create/index.mjs';
+import { map, withInitialValue } from '../operators/index.mjs';
+import type {
+  InitializedObservable,
+  InitializedSyncChildObservable,
+  Observable,
+  SyncChildObservable,
+} from '../types/index.mjs';
+import { derive } from './derive.mjs';
+
+describe(derive, () => {
+  test('emits the projection of the latest values, once every parent has one', () => {
+    const a$ = source<number>();
+
+    const b$ = source<string>();
+
+    const label$ = derive([a$, b$], (a, b) => `${b}${a.toString()}`);
+
+    const mut_history: string[] = [];
+
+    label$.subscribe((v) => {
+      mut_history.push(v);
+    });
+
+    a$.next(1);
+
+    assert.deepStrictEqual(mut_history, []);
+
+    b$.next('x');
+
+    a$.next(2);
+
+    b$.next('y');
+
+    assert.deepStrictEqual(mut_history, ['x1', 'x2', 'y2']);
+  });
+
+  test('is one observable: a diamond updates it once per write', () => {
+    const counter$ = source<number>(0);
+
+    const doubled$ = counter$.pipe(map((x) => x * 2));
+
+    const tripled$ = counter$.pipe(map((x) => x * 3));
+
+    let mut_calls = 0;
+
+    const sum$ = derive([doubled$, tripled$], (d, t) => {
+      mut_calls += 1;
+
+      return d + t;
+    });
+
+    const mut_history: number[] = [];
+
+    sum$.subscribe((v) => {
+      mut_history.push(v);
+    });
+
+    counter$.next(1);
+
+    counter$.next(2);
+
+    assert.deepStrictEqual(mut_history, [0, 5, 10]);
+
+    assert.strictEqual(mut_calls, 3);
+
+    assert.deepStrictEqual(sum$.parents, [doubled$, tripled$]);
+  });
+
+  test('computes the initial value when every parent has one', () => {
+    const a$ = source<number>(1);
+
+    const b$ = source<number>(2);
+
+    const sum$ = derive([a$, b$], (a, b) => a + b);
+
+    assert.deepStrictEqual(sum$.getSnapshot(), Optional.some(3));
+
+    const c$ = source<number>();
+
+    const partial$ = derive([a$, c$], (a, c) => a + c);
+
+    assert.isTrue(Optional.isNone(partial$.getSnapshot()));
+  });
+
+  test('a result equal by Object.is to the one held is not emitted', () => {
+    const a$ = source<number>(1);
+
+    const b$ = source<number>(2);
+
+    const parity$ = derive([a$, b$], (a, b) => (a + b) % 2);
+
+    const mut_history: number[] = [];
+
+    parity$.subscribe((v) => {
+      mut_history.push(v);
+    });
+
+    a$.next(3);
+
+    b$.next(4);
+
+    a$.next(4);
+
+    assert.deepStrictEqual(mut_history, [1, 0]);
+  });
+
+  test('`equals` replaces Object.is', () => {
+    const a$ = source<number>(1);
+
+    const b$ = source<number>(2);
+
+    const pair$ = derive([a$, b$], (a, b) => ({ total: a + b }), {
+      equals: (x, y) => x.total === y.total,
+    });
+
+    const mut_history: number[] = [];
+
+    pair$.subscribe(({ total }) => {
+      mut_history.push(total);
+    });
+
+    a$.next(2);
+
+    // A new object with the same total: equal by `equals`, not by Object.is.
+    a$.next(2);
+
+    b$.next(1);
+
+    b$.next(5);
+
+    assert.deepStrictEqual(mut_history, [3, 4, 3, 7]);
+  });
+
+  test('a write from one parent does not reuse a value another update left', () => {
+    const a$ = source<number>(1);
+
+    const b$ = source<number>(10);
+
+    const xs$ = derive([a$, b$], (...values) => values);
+
+    const mut_history: (readonly number[])[] = [];
+
+    xs$.subscribe((v) => {
+      mut_history.push(v);
+    });
+
+    a$.next(2);
+
+    b$.next(20);
+
+    assert.deepStrictEqual(mut_history, [
+      [1, 10],
+      [2, 10],
+      [2, 20],
+    ]);
+
+    // Each emission is its own array, so a held value is never changed by a
+    // later update.
+    assert.notStrictEqual(mut_history[0], mut_history[1]);
+  });
+
+  test('types', () => {
+    const s1: Observable<1> = source<1>();
+
+    const s2: InitializedObservable<2> = source<2>().pipe(withInitialValue(2));
+
+    const p = derive([s1, s2], (a, b) => {
+      expectType<typeof a, 1>('=');
+
+      expectType<typeof b, 2>('=');
+
+      return 'x' as const;
+    });
+
+    expectType<typeof p, SyncChildObservable<'x', readonly [1, 2]>>('=');
+
+    const s3: InitializedObservable<3> = source<3>().pipe(withInitialValue(3));
+
+    const _q = derive([s2, s3], (a, b) => a + b);
+
+    expectType<
+      typeof _q,
+      InitializedSyncChildObservable<number, readonly [2, 3]>
+    >('=');
+
+    expect(p).toBeDefined();
+  });
+});

package/src/core/combine/index.mts

@@ -1,3 +1,4 @@
 export * from './combine.mjs';
+export * from './derive.mjs';
 export * from './merge.mjs';
 export * from './zip.mjs';

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/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 });