synstate 0.1.1 → 1.0.0

package/src/core/operators/debounce.mts

@@ -0,0 +1,154 @@
+import { Optional } from 'ts-data-forge';
+import { AsyncChildObservableClass } from '../class/index.mjs';
+import {
+  type DebounceOperatorObservable,
+  type KeepInitialValueOperator,
+  type Observable,
+  type TimerId,
+  type UpdateToken,
+} from '../types/index.mjs';
+
+/**
+ * Delays emissions from the source observable until a specified time has passed without another emission.
+ * Useful for handling user input events like typing or scrolling.
+ *
+ * @template A - The type of values from the source
+ * @param milliSeconds - The debounce duration in milliseconds
+ * @returns An operator that debounces the observable
+ *
+ * @example
+ * ```ts
+ * //  Timeline (250ms debounce):
+ * //
+ * //  Time(x50ms)  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0
+ * //
+ * //  input$       0       2   3                   9   10  11  12  13  14
+ * //                               |- 250ms ->                         |- 250ms ->
+ * //  debounced$                   3                                             14   (emitted after 250ms silence)
+ * //
+ * //  Explanation:
+ * //  - debounce emits the latest value AFTER a quiet period with no new emissions
+ * //  - Unlike audit (which uses a fixed window), debounce resets the timer on every emission
+ * //  - Useful for search-as-you-type and form validation
+ *
+ * const input$ = source<number>();
+ *
+ * const debounced$ = input$.pipe(debounce(250));
+ *
+ * const valueHistory: number[] = [];
+ *
+ * debounced$.subscribe((value) => {
+ *   valueHistory.push(value);
+ * });
+ *
+ * const sleep = (ms: number): Promise<void> =>
+ *   new Promise((resolve) => {
+ *     setTimeout(resolve, ms);
+ *   });
+ *
+ * input$.next(0);
+ *
+ * await sleep(200);
+ *
+ * input$.next(2);
+ *
+ * await sleep(100);
+ *
+ * input$.next(3);
+ *
+ * assert.deepStrictEqual(valueHistory, []);
+ *
+ * await sleep(300);
+ *
+ * assert.deepStrictEqual(valueHistory, [3]);
+ *
+ * await sleep(300);
+ *
+ * input$.next(9);
+ *
+ * await sleep(100);
+ *
+ * input$.next(10);
+ *
+ * await sleep(100);
+ *
+ * input$.next(11);
+ *
+ * await sleep(100);
+ *
+ * input$.next(12);
+ *
+ * await sleep(100);
+ *
+ * input$.next(13);
+ *
+ * await sleep(100);
+ *
+ * input$.next(14);
+ *
+ * assert.deepStrictEqual(valueHistory, [3]);
+ *
+ * await sleep(300);
+ *
+ * assert.deepStrictEqual(valueHistory, [3, 14]);
+ * ```
+ */
+export const debounce = <A,>(
+  milliSeconds: number,
+): KeepInitialValueOperator<A, A> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  ((parentObservable) =>
+    new DebounceObservableClass(
+      parentObservable,
+      milliSeconds,
+    )) as KeepInitialValueOperator<A, A>;
+
+class DebounceObservableClass<A>
+  extends AsyncChildObservableClass<A, readonly [A]>
+  implements DebounceOperatorObservable<A>
+{
+  readonly #milliSeconds: number;
+  #mut_timerId: TimerId | undefined;
+
+  constructor(parentObservable: Observable<A>, milliSeconds: number) {
+    super({
+      parents: [parentObservable],
+      initialValue: parentObservable.getSnapshot(),
+    });
+
+    this.#mut_timerId = undefined;
+
+    this.#milliSeconds = milliSeconds;
+  }
+
+  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.#resetTimer();
+
+    // set timer
+    this.#mut_timerId = setTimeout(() => {
+      if (Optional.isNone(sn)) return;
+
+      this.startUpdate(sn.value);
+    }, this.#milliSeconds);
+  }
+
+  #resetTimer(): void {
+    if (this.#mut_timerId !== undefined) {
+      clearTimeout(this.#mut_timerId);
+    }
+  }
+
+  override complete(): void {
+    this.#resetTimer();
+
+    super.complete();
+  }
+}

package/src/core/operators/filter.mts

@@ -12,7 +12,7 @@ import {
   type FilterOperatorObservable,
   type InitializedObservable,
   type Observable,
-  type UpdaterSymbol,
+  type UpdateToken,
 } from '../types/index.mjs';
 import { withInitialValue } from './with-initial-value.mjs';
 
@@ -40,29 +40,29 @@ import { withInitialValue } from './with-initial-value.mjs';
  *
  * const even$ = num$.pipe(filter((x) => x % 2 === 0));
  *
- * const mut_history: number[] = [];
+ * const valueHistory: number[] = [];
  *
  * even$.subscribe((x) => {
- *   mut_history.push(x);
+ *   valueHistory.push(x);
  * });
  *
  * num$.next(1); // nothing logged
  *
  * num$.next(2); // logs: 2
  *
- * assert.deepStrictEqual(mut_history, [2]);
+ * assert.deepStrictEqual(valueHistory, [2]);
  *
  * num$.next(3); // nothing logged
  *
  * num$.next(4); // logs: 4
  *
- * assert.deepStrictEqual(mut_history, [2, 4]);
+ * assert.deepStrictEqual(valueHistory, [2, 4]);
  *
  * num$.next(5);
  *
  * num$.next(6);
  *
- * assert.deepStrictEqual(mut_history, [2, 4, 6]);
+ * assert.deepStrictEqual(valueHistory, [2, 4, 6]);
  * ```
  */
 export function filter<A, B extends A>(
@@ -107,12 +107,12 @@ class FilterObservableClass<A>
     this.#predicate = predicate;
   }
 
-  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+  override tryUpdate(updateToken: UpdateToken): void {
     const par = this.parents[0];
 
     const sn = par.getSnapshot();
 
-    if (par.updaterSymbol !== updaterSymbol || Optional.isNone(sn)) {
+    if (par.updateToken !== updateToken || Optional.isNone(sn)) {
       return; // skip update
     }
 
@@ -120,7 +120,7 @@ class FilterObservableClass<A>
       this.#mut_index === -1 ? asSafeUint(0) : SafeUint.add(1, this.#mut_index);
 
     if (this.#predicate(sn.value, this.#mut_index)) {
-      this.setNext(sn.value, updaterSymbol);
+      this.setNext(sn.value, updateToken);
     }
   }
 }

package/src/core/operators/index.mts

@@ -1,7 +1,7 @@
-export * from './audit-time.mjs';
-export * from './debounce-time.mjs';
+export * from './audit.mjs';
+export * from './debounce.mjs';
 export * from './filter.mjs';
-export * from './map-with-index.mjs';
+export * from './map.mjs';
 export * from './merge-map.mjs';
 export * from './pairwise.mjs';
 export * from './scan.mjs';
@@ -11,7 +11,7 @@ export * from './skip-while.mjs';
 export * from './switch-map.mjs';
 export * from './take-until.mjs';
 export * from './take-while.mjs';
-export * from './throttle-time.mjs';
+export * from './throttle.mjs';
 export * from './with-buffered-from.mjs';
 export * from './with-current-value-from.mjs';
 export * from './with-initial-value.mjs';

package/src/core/operators/map.mts

@@ -0,0 +1,124 @@
+import { Optional, SafeUint, asSafeUint, expectType } from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import { source } from '../create/index.mjs';
+import {
+  type InitializedObservable,
+  type KeepInitialValueOperator,
+  type MapOperatorObservable,
+  type Observable,
+  type UpdateToken,
+} from '../types/index.mjs';
+import { withInitialValue } from './with-initial-value.mjs';
+
+/**
+ * Transforms each value emitted by the source using a mapping function that also receives the emission 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
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  num$      "A"      "B"      "C"
+ * //  indexed$  "0: A"   "1: B"   "2: C"
+ * //
+ * //  Explanation:
+ * //  - mapWithIndex transforms each value along with its index
+ * //  - Index starts at 0 and increments with each emission
+ *
+ * const num$ = source<string>();
+ *
+ * const indexed$ = num$.pipe(map((x, i) => `${i}: ${x}`));
+ *
+ * const valueHistory: string[] = [];
+ *
+ * indexed$.subscribe((s) => {
+ *   valueHistory.push(s);
+ * });
+ *
+ * num$.next('A'); // 0: A
+ *
+ * num$.next('B'); // 1: B
+ *
+ * num$.next('C'); // 2: C
+ *
+ * assert.deepStrictEqual(valueHistory, ['0: A', '1: B', '2: C']);
+ * ```
+ */
+export const map = <A, B>(
+  mapFn: (x: A, index: SafeUint | -1) => B,
+): KeepInitialValueOperator<A, B> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  ((parentObservable) =>
+    new MapObservableClass(
+      parentObservable,
+      mapFn,
+    )) as KeepInitialValueOperator<A, B>;
+
+/* implementation */
+
+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;
+
+  constructor(
+    parentObservable: Observable<A>,
+    mapFn: (x: A, index: SafeUint | -1) => B,
+  ) {
+    super({
+      parents: [parentObservable],
+      initialValue: Optional.map(parentObservable.getSnapshot(), (x) =>
+        mapFn(x, -1),
+      ),
+    });
+
+    this.#mut_index = -1;
+
+    this.#mapFn = mapFn;
+  }
+
+  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.#mapFn(sn.value, this.#mut_index), updateToken);
+  }
+}
+
+if (import.meta.vitest !== undefined) {
+  test('type test', () => {
+    expect(1).toBe(1); // dummy
+  });
+
+  {
+    const s: Observable<number> = source<number>();
+
+    const _d1 = s.pipe(map((x, i) => x + i));
+
+    expectType<typeof _d1, Observable<number>>('=');
+  }
+
+  {
+    const s = source<number>();
+
+    const m: InitializedObservable<number> = s.pipe(withInitialValue(0));
+
+    const _d = m.pipe(map((x, i) => x + i));
+
+    expectType<typeof _d, InitializedObservable<number>>('=');
+  }
+}

package/src/core/operators/merge-map.mts

@@ -5,7 +5,7 @@ import {
   type MergeMapOperatorObservable,
   type Observable,
   type Subscription,
-  type UpdaterSymbol,
+  type UpdateToken,
 } from '../types/index.mjs';
 
 /**
@@ -21,56 +21,83 @@ import {
  * ```ts
  * //  Timeline:
  * //
- * //  ids$          1               2               3
- * //  requests      fetch(1)        fetch(2)        fetch(3)
- * //  users$        result1         result2         result3
- * //                (parallel)      (parallel)      (parallel)
+ * //  input$      A                          B              C
+ * //  inner A     A1    A2    A3
+ * //  inner B                                B1    B2             B3
+ * //  inner C                                              C1         C2    C3
+ * //  result$     A1    A2    A3              B1    B2      C1    B3   C2    C3
  * //
  * //  Explanation:
- * //  - mergeMap runs all inner observables in parallel
- * //  - Results are emitted as they arrive (may be out of order)
- * //  - Does NOT cancel previous requests
- * //  - All requests run concurrently and all results are emitted
+ * //  - mergeMap creates an inner observable for each source value
+ * //  - Unlike switchMap, previous inner observables are NOT cancelled
+ * //  - B's inner continues even after C arrives (B3 is still emitted)
+ * //  - All inner observables run concurrently and their results are merged
  *
- * const ids$ = source<number>();
+ * const input$ = source<string>();
  *
- * const users$ = ids$.pipe(
- *   mergeMap((id) => {
- *     const result$ = source<{ id: number }>();
+ * const result$ = input$.pipe(
+ *   mergeMap((letter) => {
+ *     const inner$ = source<string>();
  *
  *     setTimeout(() => {
- *       result$.next({ id });
- *
- *       result$.complete();
+ *       inner$.next(`${letter}1`);
  *     }, 10);
  *
- *     return result$;
+ *     setTimeout(() => {
+ *       inner$.next(`${letter}2`);
+ *     }, 110);
+ *
+ *     setTimeout(() => {
+ *       inner$.next(`${letter}3`);
+ *     }, 210);
+ *
+ *     return inner$;
  *   }),
  * );
  *
- * const mut_history: { id: number }[] = [];
+ * const valueHistory: string[] = [];
  *
- * users$.subscribe((value) => {
- *   mut_history.push(value);
+ * result$.subscribe((value) => {
+ *   valueHistory.push(value);
  * });
  *
- * ids$.next(1);
+ * const sleep = (ms: number): Promise<void> =>
+ *   new Promise((resolve) => {
+ *     setTimeout(resolve, ms);
+ *   });
  *
- * ids$.next(2);
+ * // Emit A - inner emits A1, A2, A3 at 10ms, 110ms, 210ms
+ * input$.next('A');
  *
- * ids$.next(3);
+ * await sleep(250);
  *
- * await new Promise((resolve) => {
- *   setTimeout(resolve, 200);
- * });
+ * assert.deepStrictEqual(valueHistory, ['A1', 'A2', 'A3']);
+ *
+ * // Emit B - inner starts emitting B1, B2 at 10ms, 110ms
+ * input$.next('B');
+ *
+ * await sleep(150);
  *
- * assert.deepStrictEqual(mut_history.length, 3);
+ * assert.deepStrictEqual(valueHistory, ['A1', 'A2', 'A3', 'B1', 'B2']);
  *
- * assert.isTrue(mut_history.some((u) => u.id === 1));
+ * // Emit C while B's inner is still running (B3 at 210ms not yet fired)
+ * // Unlike switchMap, B's inner is NOT cancelled
+ * input$.next('C');
  *
- * assert.isTrue(mut_history.some((u) => u.id === 2));
+ * await sleep(250);
  *
- * assert.isTrue(mut_history.some((u) => u.id === 3));
+ * // B3 appears between C1 and C2, showing the merge behavior
+ * assert.deepStrictEqual(valueHistory, [
+ *   'A1',
+ *   'A2',
+ *   'A3',
+ *   'B1',
+ *   'B2',
+ *   'C1',
+ *   'B3',
+ *   'C2',
+ *   'C3',
+ * ]);
  * ```
  *
  * @note To improve code readability, consider using `createState` instead of `mergeMap`,
@@ -84,7 +111,7 @@ export const mergeMap =
     new MergeMapObservableClass(parentObservable, mapToObservable);
 
 /**
- * Alias for `mergeMap()`.
+ * Alias for `mergeMap`.
  * @see mergeMap
  */
 export const flatMap = mergeMap;
@@ -113,12 +140,12 @@ class MergeMapObservableClass<A, B>
     this.#mut_subscriptions = [];
   }
 
-  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+  override tryUpdate(updateToken: UpdateToken): void {
     const par = this.parents[0];
 
     const sn = par.getSnapshot();
 
-    if (par.updaterSymbol !== updaterSymbol || Optional.isNone(sn)) {
+    if (par.updateToken !== updateToken || Optional.isNone(sn)) {
       return; // skip update
     }
 

package/src/core/operators/pairwise.mts

@@ -4,7 +4,7 @@ import {
   type DropInitialValueOperator,
   type Observable,
   type PairwiseOperatorObservable,
-  type UpdaterSymbol,
+  type UpdateToken,
 } from '../types/index.mjs';
 
 /**
@@ -30,30 +30,30 @@ import {
  *
  * const pairs$ = num$.pipe(pairwise());
  *
- * const mut_history: (readonly [number, number])[] = [];
+ * const valueHistory: (readonly [number, number])[] = [];
  *
  * pairs$.subscribe(([prev, curr]) => {
- *   mut_history.push([prev, curr]);
+ *   valueHistory.push([prev, curr]);
  * });
  *
  * num$.next(1); // nothing logged
  *
- * assert.deepStrictEqual(mut_history, []);
+ * assert.deepStrictEqual(valueHistory, []);
  *
  * num$.next(2); // logs: 1, 2
  *
- * assert.deepStrictEqual(mut_history, [[1, 2]]);
+ * assert.deepStrictEqual(valueHistory, [[1, 2]]);
  *
  * num$.next(3); // logs: 2, 3
  *
- * assert.deepStrictEqual(mut_history, [
+ * assert.deepStrictEqual(valueHistory, [
  *   [1, 2],
  *   [2, 3],
  * ]);
  *
  * num$.next(4); // logs: 3, 4
  *
- * assert.deepStrictEqual(mut_history, [
+ * assert.deepStrictEqual(valueHistory, [
  *   [1, 2],
  *   [2, 3],
  *   [3, 4],
@@ -83,12 +83,12 @@ class PairwiseObservableClass<A>
     this.#mut_previousValue = parentObservable.getSnapshot();
   }
 
-  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+  override tryUpdate(updateToken: UpdateToken): void {
     const par = this.parents[0];
 
     const sn = par.getSnapshot();
 
-    if (par.updaterSymbol !== updaterSymbol || Optional.isNone(sn)) {
+    if (par.updateToken !== updateToken || Optional.isNone(sn)) {
       return; // skip update
     }
 
@@ -100,7 +100,7 @@ class PairwiseObservableClass<A>
     this.#mut_previousValue = par.getSnapshot();
 
     if (cond) {
-      this.setNext([prev.value, sn.value], updaterSymbol);
+      this.setNext([prev.value, sn.value], updateToken);
     }
   }
 }

package/src/core/operators/scan.mts

@@ -3,7 +3,7 @@ import { InitializedSyncChildObservableClass } from '../class/index.mjs';
 import {
   type Observable,
   type ScanOperatorObservable,
-  type UpdaterSymbol,
+  type UpdateToken,
   type WithInitialValueOperator,
 } from '../types/index.mjs';
 
@@ -35,25 +35,25 @@ import {
  *
  * const sum$ = num$.pipe(scan((acc, curr) => acc + curr, 0));
  *
- * const mut_history: number[] = [];
+ * const valueHistory: number[] = [];
  *
  * sum$.subscribe((x) => {
- *   mut_history.push(x);
+ *   valueHistory.push(x);
  * });
  *
- * assert.deepStrictEqual(mut_history, [0]);
+ * assert.deepStrictEqual(valueHistory, [0]);
  *
  * num$.next(1); // logs: 1
  *
- * assert.deepStrictEqual(mut_history, [0, 1]);
+ * assert.deepStrictEqual(valueHistory, [0, 1]);
  *
  * num$.next(2); // logs: 3
  *
- * assert.deepStrictEqual(mut_history, [0, 1, 3]);
+ * assert.deepStrictEqual(valueHistory, [0, 1, 3]);
  *
  * num$.next(3); // logs: 6
  *
- * assert.deepStrictEqual(mut_history, [0, 1, 3, 6]);
+ * assert.deepStrictEqual(valueHistory, [0, 1, 3, 6]);
  * ```
  */
 export const scan =
@@ -83,7 +83,7 @@ class ScanObservableClass<A, B>
     this.#reducer = reducer;
   }
 
-  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+  override tryUpdate(updateToken: UpdateToken): void {
     const par = this.parents[0];
 
     const psn = par.getSnapshot();
@@ -91,13 +91,13 @@ class ScanObservableClass<A, B>
     const sn = this.getSnapshot();
 
     if (
-      par.updaterSymbol !== updaterSymbol ||
+      par.updateToken !== updateToken ||
       Optional.isNone(psn) ||
       Optional.isNone(sn)
     ) {
       return; // skip update
     }
 
-    this.setNext(this.#reducer(sn.value, psn.value), updaterSymbol);
+    this.setNext(this.#reducer(sn.value, psn.value), updateToken);
   }
 }