synstate 6.0.0 → 6.1.1

package/src/core/combine/combine.mts

@@ -1,12 +1,5 @@
-// 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
-import { Arr, expectType, Optional } from 'ts-data-forge';
-import type { NonEmptyTuple, Tuple } from 'ts-type-forge';
-import { SyncChildObservableClass } from '../class/index.mjs';
+import { expectType } from 'ts-data-forge';
+import type { NonEmptyTuple } from 'ts-type-forge';
 import { source } from '../create/index.mjs';
 import { withInitialValue } from '../operators/index.mjs';
 import type {
@@ -14,12 +7,10 @@ import type {
   CombineObservableRefined,
   InitializedObservable,
   InitializedSyncChildObservable,
-  NonEmptyUnknownList,
   Observable,
   SyncChildObservable,
-  UpdateToken,
-  Wrap,
 } from '../types/index.mjs';
+import { derive } from './derive.mjs';
 
 /**
  * Combines multiple observables into a single observable that emits an array of their latest values.
@@ -81,9 +72,12 @@ import type {
 export const combine = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): CombineObservableRefined<OS> =>
+  // `derive` collecting the values into a new array on every update, which is
+  // never `Object.is` the one before, so every update is passed on.
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  new CombineObservableClass(
+  derive(
     parents,
+    (...values) => values,
   ) as unknown as CombineObservableRefined<OS>;
 
 /**
@@ -92,65 +86,6 @@ export const combine = <const OS extends NonEmptyTuple<Observable<unknown>>>(
  */
 export const combineLatest = combine;
 
-class CombineObservableClass<const A extends NonEmptyUnknownList>
-  extends SyncChildObservableClass<A, A>
-  implements CombineObservable<A>
-{
-  constructor(parents: Wrap<A>) {
-    const parentsValues: Tuple.MapTo<Optional<A[number]>, A> = Arr.map(
-      parents,
-      (p) => p.getSnapshot(),
-    );
-
-    // The annotation on `initialValue` is what replaces the type assertion.
-    // `Arr.map` carries a single result element type, so it reports `A[number]`
-    // at every position, and `Tuple.MapTo<A[number], A>` — the uniform mapping
-    // — is *not* assignable back to `A`. The positional
-    // `Readonly<{ [K in keyof A]: A[K] }>` is, and TypeScript accepts the
-    // uniform result into it because the two mapped types share `keyof A`. So
-    // it is the annotation, not an assertion, that records the position-wise
-    // fact the checker cannot derive on its own.
-    const initialValue: Optional<Readonly<{ [K in keyof A]: A[K] }>> =
-      Arr.every(parentsValues, Optional.isSome)
-        ? Optional.some(Arr.map(parentsValues, (c) => c.value))
-        : Optional.none;
-
-    super({
-      parents,
-      initialValue,
-    });
-
-    this.attach();
-  }
-
-  override tryUpdate(updateToken: UpdateToken): void {
-    const parents = this.parents;
-
-    if (parents.every((o) => o.updateToken !== updateToken)) {
-      return; // all parents are skipped
-    }
-
-    // Same shape-preserving chain as the initial value: `Arr.map` (not the
-    // native one, which drops the tuple shape) into the uniform
-    // `Tuple.MapTo`, then a positional annotation to get back to `A`.
-    const parentValues: Tuple.MapTo<Optional<A[number]>, A> = Arr.map(
-      parents,
-      (a) => a.getSnapshot(),
-    );
-
-    if (!Arr.every(parentValues, Optional.isSome)) {
-      return;
-    }
-
-    const nextValue: Readonly<{ [K in keyof A]: A[K] }> = Arr.map(
-      parentValues,
-      (a) => a.value,
-    );
-
-    this.setNext(nextValue, updateToken);
-  }
-}
-
 if (import.meta.vitest !== undefined) {
   test('type test', () => {
     expect(1).toBe(1); // dummy

package/src/core/combine/derive.mts

@@ -0,0 +1,172 @@
+// 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 { Arr, Optional } from 'ts-data-forge';
+import type { NonEmptyTuple } from 'ts-type-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import type {
+  DeriveObservable,
+  DeriveObservableRefined,
+  NonEmptyUnknownList,
+  Observable,
+  Unwrap,
+  UpdateToken,
+  Wrap,
+} from '../types/index.mjs';
+
+/**
+ * Derives one value from the latest values of several observables: one
+ * observable that calls `project` with them, as arguments, and emits the
+ * result unless it equals the one already held.
+ *
+ * It emits once every parent has a value, and then whenever any of them
+ * emits, as `combine` does; but where `combine(parents).pipe(map(fn))` is two
+ * observables and a tuple per update, `derive` is one, and passes the values
+ * as arguments (a rest parameter in `project` collects them into an array
+ * again).
+ * The comparison is `Object.is` unless `equals` says otherwise.
+ *
+ * @template OS - Tuple type of the parent observables
+ * @template B - The type of the derived value
+ * @param parents - The observables to derive from
+ * @param project - Computes the value from the parents' values, in order
+ * @param options - `equals` compares a result with the one held
+ * @returns An observable of the derived value, initialized when every parent is
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  price$     100         120
+ * //  quantity$        2            3
+ * //  total$           200   240    360
+ * //
+ * //  Explanation:
+ * //  - derive waits for every parent to have a value
+ * //  - Then calls the projection with their latest values whenever one emits
+ *
+ * const price$ = source<number>();
+ *
+ * const quantity$ = source<number>();
+ *
+ * const total$ = derive(
+ *   [price$, quantity$],
+ *   (price, quantity) => price * quantity,
+ * );
+ *
+ * const totalHistory: number[] = [];
+ *
+ * total$.subscribe((total) => {
+ *   totalHistory.push(total);
+ * });
+ *
+ * price$.next(100); // nothing yet: quantity$ has no value
+ *
+ * quantity$.next(2); // 200
+ *
+ * price$.next(120); // 240
+ *
+ * quantity$.next(3); // 360
+ *
+ * assert.deepStrictEqual(totalHistory, [200, 240, 360]);
+ * ```
+ */
+export const derive = <const OS extends NonEmptyTuple<Observable<unknown>>, B>(
+  parents: OS,
+  project: (...values: Unwrap<OS>) => B,
+  options?: Readonly<{ equals?: (x: B, y: B) => boolean }>,
+): DeriveObservableRefined<B, OS> =>
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+  new DeriveObservableClass(
+    parents,
+    // `project` is called with the values of `parents`, position by
+    // position, which the checker cannot follow through an index.
+    // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+    project as (...values: readonly unknown[]) => B,
+    options?.equals ?? Object.is,
+  ) as unknown as DeriveObservableRefined<B, OS>;
+
+class DeriveObservableClass<const A extends NonEmptyUnknownList, B>
+  extends SyncChildObservableClass<B, A>
+  implements DeriveObservable<B, A>
+{
+  readonly #project: (...values: readonly unknown[]) => B;
+  readonly #equals: (x: B, y: B) => boolean;
+
+  /**
+   * The parents' values, rewritten by every update. `project` receives them
+   * spread, as arguments of its own, so nothing it is given changes later and
+   * no array is built per update.
+   */
+  // @sumi-expect-error readonly/require-readonly-type
+  readonly #mut_values: unknown[];
+
+  constructor(
+    parents: Wrap<A>,
+    project: (...values: readonly unknown[]) => B,
+    equals: (x: B, y: B) => boolean,
+  ) {
+    const snapshots = Arr.map(parents, (p) => p.getSnapshot());
+
+    const mut_values = Array.from(snapshots, (s): unknown =>
+      Optional.isSome(s) ? s.value : undefined,
+    );
+
+    super({
+      parents,
+      initialValue: Arr.every(snapshots, Optional.isSome)
+        ? Optional.some(project(...mut_values))
+        : Optional.none,
+    });
+
+    this.#project = project;
+
+    this.#equals = equals;
+
+    this.#mut_values = mut_values;
+
+    this.attach();
+  }
+
+  override tryUpdate(updateToken: UpdateToken): void {
+    const mut_values = this.#mut_values;
+
+    let mut_updated = false;
+
+    let mut_index = 0;
+
+    for (const parent of this.parents) {
+      const snapshot = parent.getSnapshot();
+
+      if (Optional.isNone(snapshot)) {
+        return; // a parent has no value yet
+      }
+
+      mut_values[mut_index] = snapshot.value;
+
+      mut_index += 1;
+
+      if (parent.updateToken === updateToken) {
+        mut_updated = true;
+      }
+    }
+
+    if (!mut_updated) {
+      return; // all parents are skipped
+    }
+
+    const next = this.#project(...mut_values);
+
+    const held = this.getSnapshot();
+
+    if (Optional.isSome(held) && this.#equals(held.value, next)) {
+      return; // the result did not change
+    }
+
+    this.setNext(next, updateToken);
+  }
+}

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/types/id.mts

@@ -2,6 +2,7 @@ import type { Brand, UnknownRecord } from 'ts-type-forge';
 
 /**
  * Identifies one update. Opaque: an object issued per update, which is also
- * that update's queue.
+ * that update's queue — except for a write nothing observes, which opens no
+ * update and is issued a token with no queue behind it.
  */
 export type UpdateToken = Brand<UnknownRecord, 'update-token'>;

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

@@ -109,6 +109,14 @@ namespace SynStateInternals {
       ? InitializedCombineObservableImpl<Cast<Unwrap<OS>>>
       : CombineObservableImpl<Unwrap<OS>>;
 
+  export type DeriveObservableRefinedImpl<
+    B,
+    OS extends NonEmptyTuple<Observable<unknown>>,
+  > =
+    EveryInitialized<OS> extends true
+      ? InitializedSyncChildObservable<B, Cast<Unwrap<OS>>>
+      : SyncChildObservable<B, Unwrap<OS>>;
+
   type InitializedZipObservableImpl<A extends NonEmptyUnknownList> =
     InitializedSyncChildObservable<A, A>;
 
@@ -189,6 +197,16 @@ export type CombineObservableRefined<
   OS extends NonEmptyTuple<Observable<unknown>>,
 > = SynStateInternals.CombineObservableRefinedImpl<OS>;
 
+export type DeriveObservable<
+  B,
+  A extends NonEmptyUnknownList,
+> = SyncChildObservable<B, A>;
+
+export type DeriveObservableRefined<
+  B,
+  OS extends NonEmptyTuple<Observable<unknown>>,
+> = SynStateInternals.DeriveObservableRefinedImpl<B, OS>;
+
 export type ZipObservable<A extends NonEmptyUnknownList> =
   SynStateInternals.ZipObservableImpl<A>;
 

package/src/core/types/observable.mts

@@ -44,7 +44,8 @@ type CreateObservableType<A, Kind extends ObservableKind> = Readonly<{
    * 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`.
+   * store it, or pass the one `tryUpdate` received on to `setNext`. A write
+   * nothing observes opens no update, and its token has no queue behind it.
    */
   updateToken: UpdateToken;
 

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

@@ -8,3 +8,13 @@ import type { UpdateToken } from '../types/index.mjs';
 export const notUpdatedYet: UpdateToken =
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
   Object.freeze({}) as UpdateToken;
+
+/**
+ * Issues the token of a write that opens no update, because nothing observes
+ * the observable written to (`setNextIfUnobserved`). Nothing is ever queued
+ * with it, so it is a token and not a queue, unlike the tokens
+ * `openUpdate` issues.
+ */
+export const issueUnqueuedToken = (): UpdateToken =>
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+  ({}) as UpdateToken;

package/src/utils/create-reducer.mts

@@ -1,6 +1,7 @@
-import { replaceEqualDeep, type ReplaceEqualDeepOptions } from 'ts-data-forge';
+import type { ReplaceEqualDeepOptions } from 'ts-data-forge';
 import type { Reducer } from 'ts-type-forge';
-import { source, type InitializedObservable } from '../core/index.mjs';
+import type { InitializedObservable } from '../core/index.mjs';
+import { createStateSource } from './state-source.mjs';
 
 /**
  * Creates a reducer-based state management container following the Redux pattern.
@@ -91,33 +92,17 @@ export const createReducer = <S, A>(
     initialState: S;
   }>,
 ] => {
-  const state = source<S>(initialState);
-
-  const equals = options?.equals ?? Object.is;
-
-  const keepEqualParts = options?.keepEqualParts ?? false;
-
-  const keepOptions =
-    typeof keepEqualParts === 'boolean' ? undefined : keepEqualParts;
+  const { state, getSnapshot, commit } = createStateSource(
+    initialState,
+    options,
+  );
 
   const dispatch = (action: A): S => {
-    const currentState = state.getSnapshot().value;
+    const currentState = getSnapshot();
 
-    const reduced = reducer(currentState, action);
-
-    const nextState =
-      keepEqualParts === false
-        ? reduced
-        : replaceEqualDeep(currentState, reduced, keepOptions);
-
-    // Once completed, `next` keeps the state held and returns it.
-    return equals(currentState, nextState)
-      ? currentState
-      : state.next(nextState);
+    return commit(currentState, reducer(currentState, action));
   };
 
-  const getSnapshot = (): S => state.getSnapshot().value;
-
   return [state, dispatch, { getSnapshot, initialState }] as const;
 };
 

package/src/utils/create-state.mts

@@ -1,26 +1,6 @@
 import type { InitializedObservable } from '../core/index.mjs';
-import { createReducer, type StateOptions } from './create-reducer.mjs';
-
-type Action<S> = Readonly<
-  | {
-      type: 'set';
-      nextState: S;
-    }
-  | {
-      type: 'update';
-      updateFn: (a: S) => S;
-    }
->;
-
-const reducer = <S,>(state: S, action: Action<S>): S => {
-  switch (action.type) {
-    case 'set':
-      return action.nextState;
-
-    case 'update':
-      return action.updateFn(state);
-  }
-};
+import type { StateOptions } from './create-reducer.mjs';
+import { createStateSource } from './state-source.mjs';
 
 /**
  * Creates a reactive state container with getter and setter methods.
@@ -161,19 +141,22 @@ export const createState = <S,>(
     initialState: S;
   }>,
 ] => {
-  const [state, dispatch, { getSnapshot }] = createReducer<S, Action<S>>(
-    reducer,
+  const { state, getSnapshot, commit } = createStateSource(
     initialState,
     options,
   );
 
-  const updateState = (updateFn: (prev: S) => S): S =>
-    dispatch({ type: 'update', updateFn });
+  // Each compares with the state the write started from, as `dispatch`
+  // does, and builds nothing on the way.
+  const updateState = (updateFn: (prev: S) => S): S => {
+    const currentState = getSnapshot();
+
+    return commit(currentState, updateFn(currentState));
+  };
 
-  const setState = (nextState: S): S => dispatch({ type: 'set', nextState });
+  const setState = (nextState: S): S => commit(getSnapshot(), nextState);
 
-  const resetState = (): S =>
-    dispatch({ type: 'set', nextState: initialState });
+  const resetState = (): S => commit(getSnapshot(), initialState);
 
   return [
     state,

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

@@ -77,6 +77,24 @@ describe(createState, () => {
     assert.deepStrictEqual(seen, [held]);
   });
 
+  test('updateState compares the result with the state updateFn was given', () => {
+    const [state, setState, { updateState }] = createState(0);
+
+    const seen = record(state);
+
+    // updateFn writes the state itself, then returns what it was given:
+    // equal to that, so nothing more is written and 5 stays.
+    updateState((prev) => {
+      setState(5);
+
+      return prev;
+    });
+
+    assert.deepStrictEqual(seen, [0, 5]);
+
+    assert.strictEqual(state.getSnapshot().value, 5);
+  });
+
   describe('keepEqualParts', () => {
     type Report = Readonly<{
       summary: Readonly<{ open: number }>;