synstate 3.3.0 → 4.0.0

package/src/core/create/counter.mts

@@ -1,5 +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 { createRootObservable } from '../base/index.mjs';
+import type { PositiveSafeIntWithSmallInt } from 'ts-type-forge';
+import { RootObservableClass } from '../class/index.mjs';
 import type { CounterObservable, TimerId } from '../types/index.mjs';
 
 /**
@@ -15,6 +23,10 @@ import type { CounterObservable, TimerId } from '../types/index.mjs';
  * @param options.emitInitial - If false, skips the 0 emitted right after
  *   `start()`, so the first value is 1, one interval later — like RxJS
  *   `interval` rather than `timer(0, ms)` (default: true)
+ * @param options.times - If set, completes right after the `times`-th
+ *   emission and clears its timers. Completion does not travel upstream, so
+ *   `counter(ms).pipe(take(n))` leaves the counter running; pass `times` to
+ *   the counter instead (default: unlimited)
  * @returns An observable that emits sequential numbers
  *
  * @example
@@ -45,11 +57,11 @@ import type { CounterObservable, TimerId } from '../types/index.mjs';
  *
  * assert.isTrue(Arr.isMinLengthArray(3, valueHistory));
  *
- * assert.deepStrictEqual(valueHistory[0], 0);
+ * assert.strictEqual(valueHistory[0], 0);
  *
- * assert.deepStrictEqual(valueHistory[1], 1);
+ * assert.strictEqual(valueHistory[1], 1);
  *
- * assert.deepStrictEqual(valueHistory[2], 2);
+ * assert.strictEqual(valueHistory[2], 2);
  * ```
  */
 export const counter = (
@@ -57,65 +69,104 @@ export const counter = (
   options?: Readonly<{
     startManually?: boolean;
     emitInitial?: boolean;
+    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;
+
+  constructor(
+    intervalMilliSeconds: number,
+    emitInitial: boolean,
+    times: PositiveSafeIntWithSmallInt | undefined,
+  ) {
+    super({ initialValue: Optional.none });
+
+    this.#intervalMilliSeconds = intervalMilliSeconds;
+
+    this.#emitInitial = emitInitial;
+
+    this.#times = times;
+
+    this.#mut_counter = asSafeUint(0);
+
+    this.#mut_emittedCount = 0;
+
+    this.#mut_timerId0 = undefined;
+
+    this.#mut_timerId = undefined;
+
+    this.#mut_isStarted = false;
+  }
 
-  let mut_timerId0: TimerId | undefined = undefined;
+  #emit(value: SafeUint): void {
+    this.startUpdate(value);
 
-  let mut_timerId: TimerId | undefined = undefined;
+    this.#mut_emittedCount += 1;
 
-  let mut_isStarted = false;
+    if (this.#times !== undefined && this.#mut_emittedCount >= this.#times) {
+      this.complete();
+    }
+  }
 
-  const resetTimer = (): void => {
-    if (mut_timerId0 !== undefined) {
-      clearTimeout(mut_timerId0);
+  start(): void {
+    if (this.#mut_isStarted) {
+      console.warn('cannot start twice');
+
+      return;
     }
 
-    if (mut_timerId !== undefined) {
-      clearInterval(mut_timerId);
+    this.#mut_isStarted = true;
+
+    if (this.isCompleted) {
+      console.warn('cannot restart stopped CounterObservable');
+
+      return;
     }
-  };
-
-  const observable = createRootObservable<
-    SafeUint,
-    Readonly<{ start: () => void }>
-  >(
-    { initialValue: Optional.none, onComplete: resetTimer },
-    ({ startUpdate, isCompleted }) => ({
-      start: () => {
-        if (mut_isStarted) {
-          console.warn('cannot start twice');
-
-          return;
-        }
-
-        mut_isStarted = true;
-
-        if (isCompleted()) {
-          console.warn('cannot restart stopped CounterObservable');
-
-          return;
-        }
-
-        if (options?.emitInitial ?? true) {
-          mut_timerId0 = setTimeout(() => {
-            startUpdate(mut_counter);
-          }, 0);
-        }
-
-        mut_timerId = setInterval(() => {
-          mut_counter = SafeUint.add(1, mut_counter);
-
-          startUpdate(mut_counter);
-        }, intervalMilliSeconds);
-      },
-    }),
-  );
 
-  if (!(options?.startManually ?? false)) {
-    observable.start();
+    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/counter.test.mts

@@ -1,4 +1,5 @@
 import { Arr } from 'ts-data-forge';
+import { map } from '../operators/index.mjs';
 import { counter } from './counter.mjs';
 
 describe(counter, () => {
@@ -191,4 +192,85 @@ describe(counter, () => {
 
     vi.useRealTimers();
   });
+
+  test.each([
+    { emitInitial: true, expected: [0, 1, 2] },
+    { emitInitial: false, expected: [1, 2, 3] },
+  ] as const)(
+    'times: 3, emitInitial: $emitInitial completes right after the third emission',
+    ({ emitInitial, expected }) => {
+      vi.useFakeTimers();
+
+      const counter$ = counter(100, { times: 3, emitInitial });
+
+      const mut_history: number[] = [];
+
+      counter$.subscribe((n) => {
+        mut_history.push(n);
+      });
+
+      vi.advanceTimersToNextTimer().advanceTimersToNextTimer();
+
+      assert.deepStrictEqual<readonly number[]>(
+        mut_history,
+        Arr.take(expected, 2),
+      );
+
+      assert.isFalse(counter$.isCompleted);
+
+      vi.advanceTimersToNextTimer();
+
+      assert.deepStrictEqual<readonly number[]>(mut_history, expected);
+
+      assert.isTrue(counter$.isCompleted);
+
+      assert.strictEqual(vi.getTimerCount(), 0);
+
+      vi.useRealTimers();
+    },
+  );
+
+  test('times: 1 emits only the 0 and clears the interval', () => {
+    vi.useFakeTimers();
+
+    const counter$ = counter(100, { times: 1 });
+
+    const mut_history: number[] = [];
+
+    counter$.subscribe((n) => {
+      mut_history.push(n);
+    });
+
+    vi.advanceTimersToNextTimer();
+
+    assert.deepStrictEqual(mut_history, [0]);
+
+    assert.isTrue(counter$.isCompleted);
+
+    assert.strictEqual(vi.getTimerCount(), 0);
+
+    vi.useRealTimers();
+  });
+
+  test('times completes the downstream after the last value reaches it', () => {
+    vi.useFakeTimers();
+
+    const counter$ = counter(100, { times: 2 });
+
+    const doubled$ = counter$.pipe(map((n) => n * 2));
+
+    const mut_history: number[] = [];
+
+    doubled$.subscribe((n) => {
+      mut_history.push(n);
+    });
+
+    vi.advanceTimersToNextTimer().advanceTimersToNextTimer();
+
+    assert.deepStrictEqual(mut_history, [0, 2]);
+
+    assert.isTrue(doubled$.isCompleted);
+
+    vi.useRealTimers();
+  });
 });

package/src/core/create/from-abortable-promise.mts

@@ -1,5 +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
+// @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
 import { Optional, Result } from 'ts-data-forge';
-import { createRootObservable } from '../base/index.mjs';
+import { RootObservableClass } from '../class/index.mjs';
 import type { FromPromiseObservable } from '../types/index.mjs';
 
 /**
@@ -72,50 +79,55 @@ import type { FromPromiseObservable } from '../types/index.mjs';
 export const fromAbortablePromise = <A, E = unknown>(
   // @sumi-expect-error readonly/require-readonly-parameter
   factory: (signal: AbortSignal) => Promise<A>,
-): FromPromiseObservable<A, E> => {
-  const abortController = new AbortController();
+): FromPromiseObservable<A, E> =>
+  new FromAbortablePromiseObservableClass(factory);
 
-  return createRootObservable<Result<A, E>>(
-    {
-      initialValue: Optional.none,
-      onComplete: () => {
-        abortController.abort();
-      },
-    },
-    ({ startUpdate, isCompleted, complete }) => {
-      const promise = factory(abortController.signal);
+class FromAbortablePromiseObservableClass<A, E = unknown>
+  extends RootObservableClass<Result<A, E>>
+  implements FromPromiseObservable<A, E>
+{
+  readonly #abortController: AbortController;
 
-      promise
-        .then((value) => {
-          if (isCompleted()) {
-            return;
-          }
+  // @sumi-expect-error readonly/require-readonly-parameter
+  constructor(factory: (signal: AbortSignal) => Promise<A>) {
+    super({ initialValue: Optional.none });
+
+    this.#abortController = new AbortController();
+
+    const promise = factory(this.#abortController.signal);
+
+    promise
+      .then((value) => {
+        if (this.isCompleted) {
+          return;
+        }
 
-          startUpdate(Result.ok(value));
-        })
-        .catch((error: unknown) => {
-          if (isCompleted()) {
-            return;
-          }
+        this.startUpdate(Result.ok(value));
+      })
+      .catch((error: unknown) => {
+        if (this.isCompleted) {
+          return;
+        }
 
-          // Silently ignore AbortError — it means the observable was
-          // intentionally completed (e.g., by switchMap).
-          if (error instanceof DOMException && error.name === 'AbortError') {
-            return;
-          }
+        // Silently ignore AbortError — it means the observable was
+        // intentionally completed (e.g., by switchMap).
+        if (error instanceof DOMException && error.name === 'AbortError') {
+          return;
+        }
 
-          startUpdate(
-            Result.err(
-              // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-              error as E,
-            ),
-          );
-        })
-        .finally(() => {
-          complete();
-        });
+        this.startUpdate(
+          Result.err(
+            // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+            error as E,
+          ),
+        );
+      })
+      .finally(() => {
+        this.complete();
+      });
+  }
 
-      return {};
-    },
-  );
-};
+  protected override teardown(): void {
+    this.#abortController.abort();
+  }
+}

package/src/core/create/from-promise.mts

@@ -1,5 +1,11 @@
+// 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, Result } from 'ts-data-forge';
-import { createRootObservable } from '../base/index.mjs';
+import { RootObservableClass } from '../class/index.mjs';
 import type { FromPromiseObservable } from '../types/index.mjs';
 
 /**
@@ -51,34 +57,37 @@ import type { FromPromiseObservable } from '../types/index.mjs';
  */
 export const fromPromise = <A, E = unknown>(
   promise: Promise<A>,
-): FromPromiseObservable<A, E> =>
-  createRootObservable<Result<A, E>>(
-    { initialValue: Optional.none },
-    ({ startUpdate, isCompleted, complete }) => {
-      promise
-        .then((value) => {
-          if (isCompleted()) {
-            return;
-          }
+): FromPromiseObservable<A, E> => new FromPromiseObservableClass(promise);
 
-          startUpdate(Result.ok(value));
-        })
-        .catch((error: unknown) => {
-          if (isCompleted()) {
-            return;
-          }
+class FromPromiseObservableClass<A, E = unknown>
+  extends RootObservableClass<Result<A, E>>
+  implements FromPromiseObservable<A, E>
+{
+  constructor(promise: Promise<A>) {
+    super({ initialValue: Optional.none });
 
-          startUpdate(
-            Result.err(
-              // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-              error as E,
-            ),
-          );
-        })
-        .finally(() => {
-          complete();
-        });
+    promise
+      .then((value) => {
+        if (this.isCompleted) {
+          return;
+        }
 
-      return {};
-    },
-  );
+        this.startUpdate(Result.ok(value));
+      })
+      .catch((error: unknown) => {
+        if (this.isCompleted) {
+          return;
+        }
+
+        this.startUpdate(
+          Result.err(
+            // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+            error as E,
+          ),
+        );
+      })
+      .finally(() => {
+        this.complete();
+      });
+  }
+}

package/src/core/create/from-subscribable.mts

@@ -1,8 +1,16 @@
+// 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, Result } from 'ts-data-forge';
-import { createRootObservable } from '../base/index.mjs';
+import { RootObservableClass } from '../class/index.mjs';
 import type {
   FromSubscribableObservable,
   Subscribable,
+  Subscription,
 } from '../types/index.mjs';
 
 /**
@@ -66,26 +74,63 @@ import type {
 export const fromSubscribable = <A, E = unknown>(
   subscribable: Subscribable<A>,
 ): FromSubscribableObservable<A, E> =>
-  createRootObservable<Result<A, E>>(
-    { initialValue: Optional.none },
-    ({ startUpdate, complete }) => {
-      subscribable.subscribe(
-        (nextValue) => {
-          startUpdate(Result.ok(nextValue));
-        },
-        (error?: unknown) => {
-          startUpdate(
-            Result.err(
-              // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-              error as E,
-            ),
-          );
-        },
-        () => {
-          complete();
-        },
-      );
+  new FromSubscribableObservableClass(subscribable);
 
-      return {};
-    },
-  );
+class FromSubscribableObservableClass<A, E = unknown>
+  extends RootObservableClass<Result<A, E>>
+  implements FromSubscribableObservable<A, E>
+{
+  readonly #mut_subscription: Subscription | undefined;
+
+  /**
+   * Set once the subscribable has completed: its subscription is over, so
+   * completing this observable must not unsubscribe from it again.
+   */
+  #mut_isSourceCompleted: boolean;
+
+  constructor(subscribable: Subscribable<A>) {
+    super({ initialValue: Optional.none });
+
+    this.#mut_subscription = undefined;
+
+    this.#mut_isSourceCompleted = false;
+
+    const subscription = subscribable.subscribe(
+      (nextValue) => {
+        this.startUpdate(Result.ok(nextValue));
+      },
+      (error?: unknown) => {
+        this.startUpdate(
+          Result.err(
+            // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+            error as E,
+          ),
+        );
+      },
+      () => {
+        this.#mut_isSourceCompleted = true;
+
+        this.complete();
+      },
+    );
+
+    // `subscribe` may have completed this observable already.
+    if (this.isCompleted) {
+      this.#unsubscribe(subscription);
+    } else {
+      this.#mut_subscription = subscription;
+    }
+  }
+
+  #unsubscribe(subscription: Subscription): void {
+    if (!this.#mut_isSourceCompleted) {
+      subscription.unsubscribe();
+    }
+  }
+
+  protected override teardown(): void {
+    if (this.#mut_subscription !== undefined) {
+      this.#unsubscribe(this.#mut_subscription);
+    }
+  }
+}