synstate 3.4.0 → 4.1.0

package/src/core/combine/combine.mts

@@ -1,6 +1,12 @@
+// 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 { createSyncChildObservable } from '../base/index.mjs';
+import { SyncChildObservableClass } from '../class/index.mjs';
 import { source } from '../create/index.mjs';
 import { withInitialValue } from '../operators/index.mjs';
 import type {
@@ -11,6 +17,7 @@ import type {
   NonEmptyUnknownList,
   Observable,
   SyncChildObservable,
+  UpdateToken,
   Wrap,
 } from '../types/index.mjs';
 
@@ -75,7 +82,9 @@ export const combine = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): CombineObservableRefined<OS> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  createCombineObservable(parents) as unknown as CombineObservableRefined<OS>;
+  new CombineObservableClass(
+    parents,
+  ) as unknown as CombineObservableRefined<OS>;
 
 /**
  * Alias for `combine`.
@@ -83,61 +92,64 @@ export const combine = <const OS extends NonEmptyTuple<Observable<unknown>>>(
  */
 export const combineLatest = combine;
 
-const createCombineObservable = <const A extends NonEmptyUnknownList>(
-  parents: Wrap<A>,
-): CombineObservable<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;
-
-  return createSyncChildObservable<A, A>(
-    {
+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,
-    },
-    ({ setNext }) =>
-      (updateToken) => {
-        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,
-        );
-
-        setNext(nextValue, updateToken);
-      },
-  );
-};
+    });
+
+    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', () => {

package/src/core/combine/merge.mts

@@ -1,6 +1,12 @@
+// 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 { Optional, expectType } from 'ts-data-forge';
 import type { ArrayElement, NonEmptyTuple } from 'ts-type-forge';
-import { createSyncChildObservable } from '../base/index.mjs';
+import { SyncChildObservableClass } from '../class/index.mjs';
 import { source } from '../create/index.mjs';
 import type {
   MergeObservable,
@@ -8,6 +14,7 @@ import type {
   NonEmptyUnknownList,
   Observable,
   SyncChildObservable,
+  UpdateToken,
   Wrap,
 } from '../types/index.mjs';
 
@@ -63,34 +70,37 @@ export const merge = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): MergeObservableRefined<OS> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  createMergeObservable(parents) as MergeObservableRefined<OS>;
+  new MergeObservableClass(parents) as MergeObservableRefined<OS>;
 
-const createMergeObservable = <const P extends NonEmptyUnknownList>(
-  parents: Wrap<P>,
-): MergeObservable<P> =>
-  createSyncChildObservable<ArrayElement<P>, P>(
-    {
+class MergeObservableClass<const P extends NonEmptyUnknownList>
+  extends SyncChildObservableClass<ArrayElement<P>, P>
+  implements MergeObservable<P>
+{
+  constructor(parents: Wrap<P>) {
+    super({
       parents,
       initialValue: Optional.none,
-    },
-    ({ setNext }) =>
-      (updateToken) => {
-        const parentToUse = parents.find(
-          (o) =>
-            o.updateToken === updateToken && Optional.isSome(o.getSnapshot()),
-        );
+    });
 
-        if (parentToUse === undefined) {
-          return;
-        }
+    this.attach();
+  }
 
-        const nextValue =
-          // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-          Optional.unwrap(parentToUse.getSnapshot()) as ArrayElement<P>;
+  override tryUpdate(updateToken: UpdateToken): void {
+    const parentToUse = this.parents.find(
+      (o) => o.updateToken === updateToken && Optional.isSome(o.getSnapshot()),
+    );
 
-        setNext(nextValue, updateToken);
-      },
-  );
+    if (parentToUse === undefined) {
+      return;
+    }
+
+    const nextValue =
+      // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+      Optional.unwrap(parentToUse.getSnapshot()) as ArrayElement<P>;
+
+    this.setNext(nextValue, updateToken);
+  }
+}
 
 if (import.meta.vitest !== undefined) {
   test('type test', () => {

package/src/core/combine/zip.mts

@@ -1,6 +1,13 @@
+// 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, createQueue, expectType } from 'ts-data-forge';
 import type { NonEmptyTuple, Tuple } from 'ts-type-forge';
-import { createSyncChildObservable } from '../base/index.mjs';
+import { SyncChildObservableClass } from '../class/index.mjs';
 import { source } from '../create/index.mjs';
 import { withInitialValue } from '../operators/index.mjs';
 import type {
@@ -71,90 +78,97 @@ export const zip = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): ZipObservableRefined<OS> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  createZipObservable(parents) as unknown as ZipObservableRefined<OS>;
-
-const createZipObservable = <const A extends NonEmptyUnknownList>(
-  parents: Wrap<A>,
-): ZipObservable<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;
-
-  const queues: TupleToQueueTuple<A> = Arr.map(parents, () => createQueue());
-
-  // The token of each parent's latest value that zip has taken in, so that a
-  // value a parent emits in the update it completes in — its `tryComplete`
-  // reaches zip before its `tryUpdate` does — still counts as queued.
-  const mut_takenTokens: UpdateToken[] = Array.from(
-    parents,
-    (p) => p.updateToken,
-  );
-
-  // No tuple can be completed any more once a completed source has nothing
-  // left to pair (#2343).
-  const canEmitNoMore = (): boolean =>
-    parents.some(
+  new ZipObservableClass(parents) as unknown as ZipObservableRefined<OS>;
+
+class ZipObservableClass<const A extends NonEmptyUnknownList>
+  extends SyncChildObservableClass<A, A>
+  implements ZipObservable<A>
+{
+  readonly #queues: TupleToQueueTuple<A>;
+
+  /**
+   * The token of each parent's latest value that zip has taken in, so that a
+   * value a parent emits in the update it completes in — its `tryComplete`
+   * reaches zip before its `tryUpdate` does — still counts as queued.
+   * Written in place, one slot per parent, on every update that reaches zip.
+   */
+  // @sumi-expect-error readonly/require-readonly-type
+  readonly #mut_takenTokens: UpdateToken[];
+
+  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.#queues = Arr.map(parents, () => createQueue());
+
+    this.#mut_takenTokens = Array.from(parents, (p) => p.updateToken);
+
+    this.attach();
+  }
+
+  override tryUpdate(updateToken: UpdateToken): void {
+    const queues = this.#queues;
+
+    for (const [index, par] of this.parents.entries()) {
+      const sn = par.getSnapshot();
+
+      if (!(par.updateToken === updateToken && Optional.isSome(sn))) {
+        continue;
+      }
+
+      queues[index]?.enqueue(sn.value);
+
+      this.#mut_takenTokens[index] = updateToken;
+    }
+
+    if (queues.some((list) => list.isEmpty)) {
+      return;
+    }
+
+    const nextValue =
+      // `Arr.map` has a single result element type, so it reports
+      // `A[number] | undefined` per position rather than `A[P]`.
+      // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+      Arr.map(queues, (q) => Optional.unwrap(q.dequeue())) as A;
+
+    this.setNext(nextValue, updateToken);
+
+    if (this.canEmitNoMore()) {
+      this.complete();
+    }
+  }
+
+  /**
+   * No tuple can be completed any more once a completed source has nothing
+   * left to pair (#2343).
+   */
+  override canEmitNoMore(): boolean {
+    return this.parents.some(
       (par, index) =>
         par.isCompleted &&
-        queues[index]?.isEmpty === true &&
-        (par.updateToken === mut_takenTokens[index] ||
+        this.#queues[index]?.isEmpty === true &&
+        (par.updateToken === this.#mut_takenTokens[index] ||
           Optional.isNone(par.getSnapshot())),
     );
-
-  return createSyncChildObservable<A, A>(
-    {
-      parents,
-      initialValue,
-      canEmitNoMore,
-    },
-    ({ setNext, complete }) =>
-      (updateToken) => {
-        for (const [index, par] of parents.entries()) {
-          const sn = par.getSnapshot();
-
-          if (!(par.updateToken === updateToken && Optional.isSome(sn))) {
-            continue;
-          }
-
-          queues[index]?.enqueue(sn.value);
-
-          mut_takenTokens[index] = updateToken;
-        }
-
-        if (queues.some((list) => list.isEmpty)) {
-          return;
-        }
-
-        const nextValue =
-          // `Arr.map` has a single result element type, so it reports
-          // `A[number] | undefined` per position rather than `A[P]`.
-          // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-          Arr.map(queues, (q) => Optional.unwrap(q.dequeue())) as A;
-
-        setNext(nextValue, updateToken);
-
-        if (canEmitNoMore()) {
-          complete();
-        }
-      },
-  );
-};
+  }
+}
 
 if (import.meta.vitest !== undefined) {
   test('type test', () => {

package/src/core/create/counter.mts

@@ -1,6 +1,13 @@
+// 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 { asSafeUint, Optional, SafeUint } from 'ts-data-forge';
 import type { PositiveSafeIntWithSmallInt } from 'ts-type-forge';
-import { createRootObservable } from '../base/index.mjs';
+import { RootObservableClass } from '../class/index.mjs';
 import type { CounterObservable, TimerId } from '../types/index.mjs';
 
 /**
@@ -65,78 +72,101 @@ export const counter = (
     times?: PositiveSafeIntWithSmallInt;
   }>,
 ): CounterObservable => {
-  let mut_counter: SafeUint = asSafeUint(0);
+  const observable = new CounterObservableClass(
+    intervalMilliSeconds,
+    options?.emitInitial ?? true,
+    options?.times,
+  );
+
+  if (!(options?.startManually ?? false)) {
+    observable.start();
+  }
+
+  return observable;
+};
+
+class CounterObservableClass
+  extends RootObservableClass<SafeUint>
+  implements CounterObservable
+{
+  readonly #intervalMilliSeconds: number;
+  readonly #emitInitial: boolean;
+  readonly #times: PositiveSafeIntWithSmallInt | undefined;
+  #mut_counter: SafeUint;
+  #mut_emittedCount: number;
+  #mut_timerId0: TimerId | undefined;
+  #mut_timerId: TimerId | undefined;
+  #mut_isStarted: boolean;
 
-  let mut_timerId0: TimerId | undefined = undefined;
+  constructor(
+    intervalMilliSeconds: number,
+    emitInitial: boolean,
+    times: PositiveSafeIntWithSmallInt | undefined,
+  ) {
+    super({ initialValue: Optional.none });
 
-  let mut_timerId: TimerId | undefined = undefined;
+    this.#intervalMilliSeconds = intervalMilliSeconds;
 
-  let mut_isStarted = false;
+    this.#emitInitial = emitInitial;
 
-  let mut_emittedCount = 0;
+    this.#times = times;
 
-  const resetTimer = (): void => {
-    if (mut_timerId0 !== undefined) {
-      clearTimeout(mut_timerId0);
+    this.#mut_counter = asSafeUint(0);
+
+    this.#mut_emittedCount = 0;
+
+    this.#mut_timerId0 = undefined;
+
+    this.#mut_timerId = undefined;
+
+    this.#mut_isStarted = false;
+  }
+
+  #emit(value: SafeUint): void {
+    this.startUpdate(value);
+
+    this.#mut_emittedCount += 1;
+
+    if (this.#times !== undefined && this.#mut_emittedCount >= this.#times) {
+      this.complete();
     }
+  }
 
-    if (mut_timerId !== undefined) {
-      clearInterval(mut_timerId);
+  start(): void {
+    if (this.#mut_isStarted) {
+      console.warn('cannot start twice');
+
+      return;
     }
-  };
-
-  const observable = createRootObservable<
-    SafeUint,
-    Readonly<{ start: () => void }>
-  >(
-    { initialValue: Optional.none, onComplete: resetTimer },
-    ({ startUpdate, isCompleted, complete }) => ({
-      start: () => {
-        if (mut_isStarted) {
-          console.warn('cannot start twice');
-
-          return;
-        }
-
-        mut_isStarted = true;
-
-        if (isCompleted()) {
-          console.warn('cannot restart stopped CounterObservable');
-
-          return;
-        }
-
-        const emit = (value: SafeUint): void => {
-          startUpdate(value);
-
-          mut_emittedCount += 1;
-
-          if (
-            options?.times !== undefined &&
-            mut_emittedCount >= options.times
-          ) {
-            complete();
-          }
-        };
-
-        if (options?.emitInitial ?? true) {
-          mut_timerId0 = setTimeout(() => {
-            emit(mut_counter);
-          }, 0);
-        }
-
-        mut_timerId = setInterval(() => {
-          mut_counter = SafeUint.add(1, mut_counter);
-
-          emit(mut_counter);
-        }, intervalMilliSeconds);
-      },
-    }),
-  );
 
-  if (!(options?.startManually ?? false)) {
-    observable.start();
+    this.#mut_isStarted = true;
+
+    if (this.isCompleted) {
+      console.warn('cannot restart stopped CounterObservable');
+
+      return;
+    }
+
+    if (this.#emitInitial) {
+      this.#mut_timerId0 = setTimeout(() => {
+        this.#emit(this.#mut_counter);
+      }, 0);
+    }
+
+    this.#mut_timerId = setInterval(() => {
+      this.#mut_counter = SafeUint.add(1, this.#mut_counter);
+
+      this.#emit(this.#mut_counter);
+    }, this.#intervalMilliSeconds);
   }
 
-  return observable;
-};
+  protected override teardown(): void {
+    if (this.#mut_timerId0 !== undefined) {
+      clearTimeout(this.#mut_timerId0);
+    }
+
+    if (this.#mut_timerId !== undefined) {
+      clearInterval(this.#mut_timerId);
+    }
+  }
+}

package/src/core/create/empty.mts

@@ -0,0 +1,42 @@
+import { Optional } from 'ts-data-forge';
+import { RootObservableClass } from '../class/index.mjs';
+import type { RootObservable } from '../types/index.mjs';
+
+/**
+ * Creates an Observable that holds no value and is already completed, so it
+ * never passes anything on (almost equivalent to RxJS `EMPTY`). Useful inside
+ * `switchMap` for the branch that should follow nothing, where a `source()`
+ * would offer a `next` that nothing calls.
+ *
+ * @template A - The type of the values it would carry
+ * @returns An Observable with no value that is already completed
+ *
+ * @example
+ * ```ts
+ * const nothing$ = empty<number>();
+ *
+ * const valueHistory: number[] = [];
+ *
+ * nothing$.subscribe(
+ *   (value) => {
+ *     valueHistory.push(value);
+ *   },
+ *   () => {
+ *     // onComplete — called immediately since empty() completes right away
+ *   },
+ * );
+ *
+ * assert.deepStrictEqual(valueHistory, []);
+ *
+ * assert.strictEqual(nothing$.isCompleted, true);
+ * ```
+ */
+export const empty = <A,>(): RootObservable<A> => {
+  const obs = new RootObservableClass<A>({
+    initialValue: Optional.none,
+  });
+
+  obs.complete();
+
+  return obs;
+};