synstate 3.0.6 → 3.2.0

package/src/core/base/create-child-observable.mts

@@ -1,6 +1,6 @@
 import { Arr, type Optional, type Some } from 'ts-data-forge';
 import { panic } from 'ts-std-forge';
-import { type MutableSet } from 'ts-type-forge';
+import type { MutableSet } from 'ts-type-forge';
 import {
   isChildObservable,
   isManagerObservable,
@@ -161,7 +161,6 @@ export const createInitializedSyncChildObservable = <
     // `getSnapshot` always returns `Some` here: `initialValue` is a `Some` and
     // `setNext` only ever stores a `Some`.
     // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
     observable as InitializedSyncChildObservable<A, P>
   );
 };

package/src/core/base/create-observable-base.mts

@@ -1,23 +1,19 @@
 import { Arr, Optional } from 'ts-data-forge';
 import { unreachable } from 'ts-std-forge';
-import {
-  type MutableMap,
-  type MutableSet,
-  type ReadonlyRecord,
-} from 'ts-type-forge';
-import {
-  type ChildObservable,
-  type InitializedObservable,
-  type Observable,
-  type ObservableBase,
-  type ObservableId,
-  type ObservableKind,
-  type Operator,
-  type Subscriber,
-  type SubscriberId,
-  type Subscription,
-  type UpdateToken,
-  type WithInitialValueOperator,
+import type { MutableMap, MutableSet, ReadonlyRecord } from 'ts-type-forge';
+import type {
+  ChildObservable,
+  InitializedObservable,
+  Observable,
+  ObservableBase,
+  ObservableId,
+  ObservableKind,
+  Operator,
+  Subscriber,
+  SubscriberId,
+  Subscription,
+  UpdateToken,
+  WithInitialValueOperator,
 } from '../types/index.mjs';
 import {
   binarySearch,
@@ -393,12 +389,14 @@ export const assembleObservable = <
     operator: WithInitialValueOperator<A, B>,
   ): InitializedObservable<B>;
 
+  // A `WithInitialValueOperator` is also an `Operator`: nothing at run time
+  // tells the two apart, so this set only refines the return type (#1952).
+  // @sumi-expect-error functions/no-refinement-overload
   function pipe<B>(operator: Operator<A, B>): Observable<B>;
 
   function pipe<B>(operator: Operator<A, B>): Observable<B> {
     return operator(
       // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
       mut_observable as unknown as InitializedObservable<A>,
     );
   }

package/src/core/base/create-root-observable.mts

@@ -1,5 +1,5 @@
 import { Optional } from 'ts-data-forge';
-import { type ReadonlyRecord } from 'ts-type-forge';
+import type { ReadonlyRecord } from 'ts-type-forge';
 import { isRootObservable, type RootObservable } from '../types/index.mjs';
 import {
   assembleObservable,

package/src/core/base/observable-base.test.mts

@@ -1,11 +1,11 @@
 import { expectType, Optional } from 'ts-data-forge';
-import {
-  type AsyncChildObservable,
-  type ChildObservable,
-  type Observable,
-  type ObservableBase,
-  type RootObservable,
-  type SyncChildObservable,
+import type {
+  AsyncChildObservable,
+  ChildObservable,
+  Observable,
+  ObservableBase,
+  RootObservable,
+  SyncChildObservable,
 } from '../types/index.mjs';
 import {
   createAsyncChildObservable,

package/src/core/combine/combine.mts

@@ -1,17 +1,17 @@
 import { Arr, expectType, Optional } from 'ts-data-forge';
-import { type NonEmptyTuple, type Tuple } from 'ts-type-forge';
+import type { NonEmptyTuple, Tuple } from 'ts-type-forge';
 import { createSyncChildObservable } from '../base/index.mjs';
 import { source } from '../create/index.mjs';
 import { withInitialValue } from '../operators/index.mjs';
-import {
-  type CombineObservable,
-  type CombineObservableRefined,
-  type InitializedObservable,
-  type InitializedSyncChildObservable,
-  type NonEmptyUnknownList,
-  type Observable,
-  type SyncChildObservable,
-  type Wrap,
+import type {
+  CombineObservable,
+  CombineObservableRefined,
+  InitializedObservable,
+  InitializedSyncChildObservable,
+  NonEmptyUnknownList,
+  Observable,
+  SyncChildObservable,
+  Wrap,
 } from '../types/index.mjs';
 
 /**
@@ -75,7 +75,6 @@ export const combine = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): CombineObservableRefined<OS> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   createCombineObservable(parents) as unknown as CombineObservableRefined<OS>;
 
 /**

package/src/core/combine/merge.mts

@@ -1,14 +1,14 @@
 import { Optional, expectType } from 'ts-data-forge';
-import { type ArrayElement, type NonEmptyTuple } from 'ts-type-forge';
+import type { ArrayElement, NonEmptyTuple } from 'ts-type-forge';
 import { createSyncChildObservable } from '../base/index.mjs';
 import { source } from '../create/index.mjs';
-import {
-  type MergeObservable,
-  type MergeObservableRefined,
-  type NonEmptyUnknownList,
-  type Observable,
-  type SyncChildObservable,
-  type Wrap,
+import type {
+  MergeObservable,
+  MergeObservableRefined,
+  NonEmptyUnknownList,
+  Observable,
+  SyncChildObservable,
+  Wrap,
 } from '../types/index.mjs';
 
 /**
@@ -66,7 +66,6 @@ export const merge = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): MergeObservableRefined<OS> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   createMergeObservable(parents) as MergeObservableRefined<OS>;
 
 const createMergeObservable = <const P extends NonEmptyUnknownList>(
@@ -90,7 +89,6 @@ const createMergeObservable = <const P extends NonEmptyUnknownList>(
 
         const nextValue =
           // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
           Optional.unwrap(parentToUse.getSnapshot()) as ArrayElement<P>;
 
         setNext(nextValue, updateToken);

package/src/core/combine/zip.mts

@@ -1,18 +1,18 @@
 import { Arr, Optional, createQueue, expectType } from 'ts-data-forge';
-import { type NonEmptyTuple, type Tuple } from 'ts-type-forge';
+import type { NonEmptyTuple, Tuple } from 'ts-type-forge';
 import { createSyncChildObservable } from '../base/index.mjs';
 import { source } from '../create/index.mjs';
 import { withInitialValue } from '../operators/index.mjs';
-import {
-  type InitializedObservable,
-  type InitializedSyncChildObservable,
-  type NonEmptyUnknownList,
-  type Observable,
-  type SyncChildObservable,
-  type TupleToQueueTuple,
-  type Wrap,
-  type ZipObservable,
-  type ZipObservableRefined,
+import type {
+  InitializedObservable,
+  InitializedSyncChildObservable,
+  NonEmptyUnknownList,
+  Observable,
+  SyncChildObservable,
+  TupleToQueueTuple,
+  Wrap,
+  ZipObservable,
+  ZipObservableRefined,
 } from '../types/index.mjs';
 
 /**
@@ -68,7 +68,6 @@ export const zip = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): ZipObservableRefined<OS> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   createZipObservable(parents) as unknown as ZipObservableRefined<OS>;
 
 const createZipObservable = <const A extends NonEmptyUnknownList>(
@@ -119,7 +118,6 @@ const createZipObservable = <const A extends NonEmptyUnknownList>(
           // `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
-          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
           Arr.map(queues, (q) => Optional.unwrap(q.dequeue())) as A;
 
         setNext(nextValue, updateToken);

package/src/core/create/counter.mts

@@ -1,13 +1,20 @@
 import { asSafeUint, Optional, SafeUint } from 'ts-data-forge';
 import { createRootObservable } from '../base/index.mjs';
-import { type CounterObservable, type TimerId } from '../types/index.mjs';
+import type { CounterObservable, TimerId } from '../types/index.mjs';
 
 /**
  * Creates an observable that emits incremental numbers at a specified interval.
- * Starts with 0 immediately after subscription, then emits 1, 2, 3, ... every interval.
+ * Emits 0 in the macrotask right after `start()` (which runs at creation
+ * unless `startManually` is set), then 1, 2, 3, ... every interval. A
+ * subscriber added after that 0 has been emitted does not receive it.
  *
  * @param intervalMilliSeconds - The interval duration in milliseconds
- * @param startManually - If true, waits for manual start (default: false)
+ * @param options - Optional settings
+ * @param options.startManually - If true, waits for `start()` instead of
+ *   starting at creation (default: false)
+ * @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)
  * @returns An observable that emits sequential numbers
  *
  * @example
@@ -49,6 +56,7 @@ export const counter = (
   intervalMilliSeconds: number,
   options?: Readonly<{
     startManually?: boolean;
+    emitInitial?: boolean;
   }>,
 ): CounterObservable => {
   let mut_counter: SafeUint = asSafeUint(0);
@@ -60,13 +68,13 @@ export const counter = (
   let mut_isStarted = false;
 
   const resetTimer = (): void => {
-    if (mut_timerId0 === undefined || mut_timerId === undefined) {
-      return;
+    if (mut_timerId0 !== undefined) {
+      clearTimeout(mut_timerId0);
     }
 
-    clearInterval(mut_timerId0);
-
-    clearInterval(mut_timerId);
+    if (mut_timerId !== undefined) {
+      clearInterval(mut_timerId);
+    }
   };
 
   const observable = createRootObservable<
@@ -90,9 +98,11 @@ export const counter = (
           return;
         }
 
-        mut_timerId0 = setTimeout(() => {
-          startUpdate(mut_counter);
-        }, 0);
+        if (options?.emitInitial ?? true) {
+          mut_timerId0 = setTimeout(() => {
+            startUpdate(mut_counter);
+          }, 0);
+        }
 
         mut_timerId = setInterval(() => {
           mut_counter = SafeUint.add(1, mut_counter);

package/src/core/create/counter.test.mts

@@ -1,3 +1,4 @@
+import { Arr } from 'ts-data-forge';
 import { counter } from './counter.mjs';
 
 describe(counter, () => {
@@ -8,4 +9,186 @@ describe(counter, () => {
 
     assert.isTrue(counter$.isCompleted);
   });
+
+  test('emits 0 right after start(), then 1, 2, … every interval', () => {
+    vi.useFakeTimers();
+
+    const start = Date.now();
+
+    const counter$ = counter(100);
+
+    const mut_history: number[] = [];
+
+    counter$.subscribe((n) => {
+      mut_history.push(n);
+    });
+
+    vi.advanceTimersToNextTimer();
+
+    assert.deepStrictEqual(mut_history, [0]);
+
+    assert.strictEqual(vi.getMockedSystemTime()?.getTime(), start);
+
+    vi.advanceTimersToNextTimer().advanceTimersToNextTimer();
+
+    assert.deepStrictEqual(mut_history, [0, 1, 2]);
+
+    counter$.complete();
+
+    vi.useRealTimers();
+  });
+
+  test('emitInitial: false skips the 0 and starts with 1 after one interval', () => {
+    vi.useFakeTimers();
+
+    const start = Date.now();
+
+    const counter$ = counter(100, { emitInitial: false });
+
+    const mut_history: number[] = [];
+
+    counter$.subscribe((n) => {
+      mut_history.push(n);
+    });
+
+    vi.advanceTimersToNextTimer();
+
+    assert.deepStrictEqual(mut_history, [1]);
+
+    assert.strictEqual(vi.getMockedSystemTime()?.getTime(), start + 100);
+
+    vi.advanceTimersToNextTimer().advanceTimersToNextTimer();
+
+    assert.deepStrictEqual(mut_history, [1, 2, 3]);
+
+    counter$.complete();
+
+    vi.useRealTimers();
+  });
+
+  test('emitInitial: false still clears the interval on complete', () => {
+    vi.useFakeTimers();
+
+    const counter$ = counter(100, { emitInitial: false });
+
+    const mut_history: number[] = [];
+
+    counter$.subscribe((n) => {
+      mut_history.push(n);
+    });
+
+    vi.advanceTimersToNextTimer();
+
+    counter$.complete();
+
+    assert.strictEqual(vi.getTimerCount(), 0);
+
+    assert.deepStrictEqual(mut_history, [1]);
+
+    vi.useRealTimers();
+  });
+
+  test.each([
+    { emitInitial: true, expected: [0, 1, 2], firstAt: 0 },
+    { emitInitial: false, expected: [1, 2, 3], firstAt: 100 },
+  ] as const)(
+    'startManually: false, emitInitial: $emitInitial starts at creation',
+    ({ emitInitial, expected, firstAt }) => {
+      vi.useFakeTimers();
+
+      const start = Date.now();
+
+      const counter$ = counter(100, { startManually: false, emitInitial });
+
+      const mut_history: number[] = [];
+
+      counter$.subscribe((n) => {
+        mut_history.push(n);
+      });
+
+      vi.advanceTimersToNextTimer();
+
+      assert.deepStrictEqual<readonly number[]>(
+        mut_history,
+        Arr.take(expected, 1),
+      );
+
+      assert.strictEqual(vi.getMockedSystemTime()?.getTime(), start + firstAt);
+
+      vi.advanceTimersToNextTimer().advanceTimersToNextTimer();
+
+      assert.deepStrictEqual<readonly number[]>(mut_history, expected);
+
+      counter$.complete();
+
+      vi.useRealTimers();
+    },
+  );
+
+  test.each([
+    { emitInitial: true, expected: [0, 1, 2], firstAt: 0 },
+    { emitInitial: false, expected: [1, 2, 3], firstAt: 100 },
+  ] as const)(
+    'startManually: true, emitInitial: $emitInitial waits for start()',
+    ({ emitInitial, expected, firstAt }) => {
+      vi.useFakeTimers();
+
+      const counter$ = counter(100, { startManually: true, emitInitial });
+
+      const mut_history: number[] = [];
+
+      counter$.subscribe((n) => {
+        mut_history.push(n);
+      });
+
+      assert.strictEqual(vi.getTimerCount(), 0);
+
+      vi.setSystemTime(Date.now() + 1000);
+
+      const start = Date.now();
+
+      counter$.start();
+
+      vi.advanceTimersToNextTimer();
+
+      assert.deepStrictEqual<readonly number[]>(
+        mut_history,
+        Arr.take(expected, 1),
+      );
+
+      assert.strictEqual(vi.getMockedSystemTime()?.getTime(), start + firstAt);
+
+      vi.advanceTimersToNextTimer().advanceTimersToNextTimer();
+
+      assert.deepStrictEqual<readonly number[]>(mut_history, expected);
+
+      counter$.complete();
+
+      assert.strictEqual(vi.getTimerCount(), 0);
+
+      vi.useRealTimers();
+    },
+  );
+
+  test('completing before the first emission cancels the pending 0', () => {
+    vi.useFakeTimers();
+
+    const counter$ = counter(100);
+
+    const mut_history: number[] = [];
+
+    counter$.subscribe((n) => {
+      mut_history.push(n);
+    });
+
+    counter$.complete();
+
+    assert.strictEqual(vi.getTimerCount(), 0);
+
+    vi.runAllTimers();
+
+    assert.deepStrictEqual(mut_history, []);
+
+    vi.useRealTimers();
+  });
 });

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

@@ -1,6 +1,6 @@
 import { Optional, Result } from 'ts-data-forge';
 import { createRootObservable } from '../base/index.mjs';
-import { type FromPromiseObservable } from '../types/index.mjs';
+import type { FromPromiseObservable } from '../types/index.mjs';
 
 /**
  * Creates an observable from a Promise factory that receives an `AbortSignal`.
@@ -71,7 +71,6 @@ import { type FromPromiseObservable } from '../types/index.mjs';
  */
 export const fromAbortablePromise = <A, E = unknown>(
   // @sumi-expect-error readonly/require-readonly-parameter
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
   factory: (signal: AbortSignal) => Promise<A>,
 ): FromPromiseObservable<A, E> => {
   const abortController = new AbortController();
@@ -108,7 +107,6 @@ export const fromAbortablePromise = <A, E = unknown>(
           startUpdate(
             Result.err(
               // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-              // eslint-disable-next-line total-functions/no-unsafe-type-assertion
               error as E,
             ),
           );

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

@@ -1,6 +1,6 @@
 import { Optional, Result } from 'ts-data-forge';
 import { createRootObservable } from '../base/index.mjs';
-import { type FromPromiseObservable } from '../types/index.mjs';
+import type { FromPromiseObservable } from '../types/index.mjs';
 
 /**
  * Creates an observable from a Promise.
@@ -71,7 +71,6 @@ export const fromPromise = <A, E = unknown>(
           startUpdate(
             Result.err(
               // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-              // eslint-disable-next-line total-functions/no-unsafe-type-assertion
               error as E,
             ),
           );

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

@@ -1,8 +1,8 @@
 import { Optional, Result } from 'ts-data-forge';
 import { createRootObservable } from '../base/index.mjs';
-import {
-  type FromSubscribableObservable,
-  type Subscribable,
+import type {
+  FromSubscribableObservable,
+  Subscribable,
 } from '../types/index.mjs';
 
 /**
@@ -77,7 +77,6 @@ export const fromSubscribable = <A, E = unknown>(
           startUpdate(
             Result.err(
               // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-              // eslint-disable-next-line total-functions/no-unsafe-type-assertion
               error as E,
             ),
           );

package/src/core/create/just.mts

@@ -1,6 +1,6 @@
 import { Optional } from 'ts-data-forge';
 import { createRootObservable } from '../base/index.mjs';
-import { type InitializedRootObservable } from '../types/index.mjs';
+import type { InitializedRootObservable } from '../types/index.mjs';
 
 /**
  * Creates an Observable that holds a single static value and immediately
@@ -40,6 +40,5 @@ export const just = <const A,>(value: A): InitializedRootObservable<A> => {
   obs.complete();
 
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   return obs as InitializedRootObservable<A>;
 };

package/src/core/create/source.mts

@@ -1,8 +1,8 @@
 import { Arr, Optional } from 'ts-data-forge';
 import { createRootObservable } from '../base/index.mjs';
-import {
-  type InitializedSourceObservable,
-  type SourceObservable,
+import type {
+  InitializedSourceObservable,
+  SourceObservable,
 } from '../types/index.mjs';
 
 /**

package/src/core/create/timer.mts

@@ -1,6 +1,6 @@
 import { Optional } from 'ts-data-forge';
 import { createRootObservable } from '../base/index.mjs';
-import { type TimerId, type TimerObservable } from '../types/index.mjs';
+import type { TimerId, TimerObservable } from '../types/index.mjs';
 
 /**
  * Creates an observable that emits 0 after a specified delay and then completes.

package/src/core/operators/audit.mts

@@ -1,10 +1,10 @@
 import { Optional } from 'ts-data-forge';
 import { createAsyncChildObservable } from '../base/index.mjs';
-import {
-  type AuditOperatorObservable,
-  type KeepInitialValueOperator,
-  type Observable,
-  type TimerId,
+import type {
+  AuditOperatorObservable,
+  KeepInitialValueOperator,
+  Observable,
+  TimerId,
 } from '../types/index.mjs';
 
 /**
@@ -105,7 +105,6 @@ export const audit = <A,>(
   milliSeconds: number,
 ): KeepInitialValueOperator<A, A> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   ((parentObservable) =>
     createAuditObservable(
       parentObservable,

package/src/core/operators/debounce.mts

@@ -1,10 +1,10 @@
 import { Optional } from 'ts-data-forge';
 import { createAsyncChildObservable } from '../base/index.mjs';
-import {
-  type DebounceOperatorObservable,
-  type KeepInitialValueOperator,
-  type Observable,
-  type TimerId,
+import type {
+  DebounceOperatorObservable,
+  KeepInitialValueOperator,
+  Observable,
+  TimerId,
 } from '../types/index.mjs';
 
 /**
@@ -96,7 +96,6 @@ export const debounce = <A,>(
   milliSeconds: number,
 ): KeepInitialValueOperator<A, A> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   ((parentObservable) =>
     createDebounceObservable(
       parentObservable,