synstate 0.1.0 → 0.1.2

package/src/core/operators/audit-time.mts

@@ -7,6 +7,65 @@ import {
   type UpdaterSymbol,
 } from '../types/index.mjs';
 
+/**
+ * Emits the last value from the source observable after a specified time window has passed.
+ * Unlike throttleTime which emits the first value, auditTime emits the last value.
+ *
+ * @template A - The type of values from the source
+ * @param milliSeconds - The audit time window in milliseconds
+ * @returns An operator that audits emissions from the observable
+ *
+ * @example
+ * ```ts
+ * //  Timeline (1000ms audit):
+ * //
+ * //  Time(ms)  0    100   200   300   400   ...   1000  1100
+ * //  input$    e1   e2    e3    e4    e5
+ * //  audited$                                      e5 (emitted at end of window)
+ * //            |-------1000ms window------>        ^
+ * //
+ * //  Explanation:
+ * //  - auditTime emits the LAST value received during each time window
+ * //  - Unlike throttleTime (which emits the FIRST value), audit emits the LAST
+ * //  - At 0-1000ms: e1-e5 are received
+ * //  - At 1000ms: e5 (the last value in the window) is emitted
+ * //  - Useful when you want the most recent value after a burst of events
+ *
+ * const input$ = source<number>();
+ *
+ * const audited$ = input$.pipe(auditTime(200));
+ *
+ * const mut_history: number[] = [];
+ *
+ * audited$.subscribe((value) => {
+ *   mut_history.push(value);
+ * });
+ *
+ * input$.next(1);
+ *
+ * input$.next(2);
+ *
+ * input$.next(3);
+ *
+ * assert.deepStrictEqual(mut_history, []);
+ *
+ * await new Promise((resolve) => {
+ *   setTimeout(resolve, 250);
+ * });
+ *
+ * assert.deepStrictEqual(mut_history, [3]);
+ *
+ * input$.next(4);
+ *
+ * input$.next(5);
+ *
+ * await new Promise((resolve) => {
+ *   setTimeout(resolve, 250);
+ * });
+ *
+ * assert.deepStrictEqual(mut_history, [3, 5]);
+ * ```
+ */
 export const auditTime = <A,>(
   milliSeconds: number,
 ): KeepInitialValueOperator<A, A> =>

package/src/core/operators/debounce-time.mts

@@ -17,12 +17,27 @@ import {
  *
  * @example
  * ```ts
+ * //  Timeline (300ms debounce):
+ * //
+ * //  Time(ms)  0     100    200    300    400    500    600   ...   900   1000
+ * //  input$    'h'   'he'   'hel'  'hello'
+ * //  debounced$                                         'hello' (emitted after 300ms silence)
+ * //
+ * //  Explanation:
+ * //  - At 0ms: 'h' is emitted, timer starts
+ * //  - At 100ms: 'he' is emitted, timer resets
+ * //  - At 200ms: 'hel' is emitted, timer resets
+ * //  - At 300ms: 'hello' is emitted, timer resets
+ * //  - At 600ms: No new emission for 300ms, 'hello' is finally emitted
+ *
  * const input$ = source<string>();
  *
  * const debounced$ = input$.pipe(debounceTime(300));
  *
+ * const mut_history: string[] = [];
+ *
  * debounced$.subscribe((value) => {
- *   console.log(value);
+ *   mut_history.push(value);
  * });
  *
  * input$.next('h');
@@ -32,7 +47,12 @@ import {
  * input$.next('hel');
  *
  * input$.next('hello');
- * // After 300ms of silence, logs: hello
+ *
+ * await new Promise((resolve) => {
+ *   setTimeout(resolve, 400);
+ * });
+ *
+ * assert.deepStrictEqual(mut_history, ['hello']);
  * ```
  */
 export const debounceTime = <A,>(

package/src/core/operators/filter.mts

@@ -27,17 +27,42 @@ import { withInitialValue } from './with-initial-value.mjs';
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  num$          1     2     3     4     5     6
+ * //  even$               2           4           6
+ * //
+ * //  Explanation:
+ * //  - filter passes through only values that satisfy the predicate
+ * //  - Only even numbers (2, 4, 6) are emitted
+ *
  * const num$ = source<number>();
  *
  * const even$ = num$.pipe(filter((x) => x % 2 === 0));
  *
+ * const mut_history: number[] = [];
+ *
  * even$.subscribe((x) => {
- *   console.log(x);
+ *   mut_history.push(x);
  * });
  *
  * num$.next(1); // nothing logged
  *
  * num$.next(2); // logs: 2
+ *
+ * assert.deepStrictEqual(mut_history, [2]);
+ *
+ * num$.next(3); // nothing logged
+ *
+ * num$.next(4); // logs: 4
+ *
+ * assert.deepStrictEqual(mut_history, [2, 4]);
+ *
+ * num$.next(5);
+ *
+ * num$.next(6);
+ *
+ * assert.deepStrictEqual(mut_history, [2, 4, 6]);
  * ```
  */
 export function filter<A, B extends A>(

package/src/core/operators/map-with-index.mts

@@ -1,10 +1,4 @@
-import {
-  Optional,
-  Result,
-  SafeUint,
-  asSafeUint,
-  expectType,
-} from 'ts-data-forge';
+import { Optional, SafeUint, asSafeUint, expectType } from 'ts-data-forge';
 import { SyncChildObservableClass } from '../class/index.mjs';
 import { source } from '../create/index.mjs';
 import {
@@ -26,17 +20,32 @@ import { withInitialValue } from './with-initial-value.mjs';
  *
  * @example
  * ```ts
- * const num$ = source<number>();
+ * //  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(mapWithIndex((x, i) => `${i}: ${x}`));
  *
+ * const mut_history: string[] = [];
+ *
  * indexed$.subscribe((s) => {
- *   console.log(s);
+ *   mut_history.push(s);
  * });
  *
- * num$.next(10); // logs: 0: 10
+ * num$.next('a'); // 0: a
+ *
+ * num$.next('b'); // 1: b
+ *
+ * num$.next('c'); // 2: c
  *
- * num$.next(20); // logs: 1: 20
+ * assert.deepStrictEqual(mut_history, ['0: a', '1: b', '2: c']);
  * ```
  */
 export const mapWithIndex = <A, B>(
@@ -49,59 +58,6 @@ export const mapWithIndex = <A, B>(
       mapFn,
     )) as KeepInitialValueOperator<A, B>;
 
-/* Specialized operators */
-
-export const map = <A, B>(mapFn: (x: A) => B): KeepInitialValueOperator<A, B> =>
-  mapWithIndex(mapFn);
-
-export const mapTo = <A, B>(value: B): KeepInitialValueOperator<A, B> =>
-  map(() => value);
-
-export const pluck = <A, K extends keyof A>(
-  key: K,
-): KeepInitialValueOperator<A, A[K]> => map((a) => a[key]);
-
-export const getKey = pluck; // alias
-
-export const attachIndex = <A,>(): KeepInitialValueOperator<
-  A,
-  readonly [SafeUint | -1, A]
-> => mapWithIndex((a, i) => [i, a] as const);
-
-export const withIndex = attachIndex; // alias
-
-export const unwrapOptional = <
-  O extends UnknownOptional,
->(): KeepInitialValueOperator<O, Optional.Unwrap<O> | undefined> =>
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  map(Optional.unwrap as Fn<O, Optional.Unwrap<O> | undefined>);
-
-export const unwrapResultOk = <
-  R extends UnknownResult,
->(): KeepInitialValueOperator<R, Result.UnwrapOk<R> | undefined> =>
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  map(Result.unwrapOk as Fn<R, Result.UnwrapOk<R> | undefined>);
-
-export const unwrapResultErr = <
-  R extends UnknownResult,
->(): KeepInitialValueOperator<R, Result.UnwrapErr<R> | undefined> =>
-  map(Result.unwrapErr as Fn<R, Result.UnwrapErr<R> | undefined>);
-
-export const mapOptional = <O extends UnknownOptional, B>(
-  mapFn: (x: Optional.Unwrap<O>) => B,
-): KeepInitialValueOperator<O, Optional<B>> =>
-  map((a) => Optional.map(a, mapFn));
-
-export const mapResultOk = <R extends UnknownResult, S2>(
-  mapFn: (x: Result.UnwrapOk<R>) => S2,
-): KeepInitialValueOperator<R, Result<S2, Result.UnwrapErr<R>>> =>
-  map((a) => Result.map(a, mapFn));
-
-export const mapResultErr = <R extends UnknownResult, E2>(
-  mapFn: (x: Result.UnwrapErr<R>) => E2,
-): KeepInitialValueOperator<R, Result<Result.UnwrapOk<R>, E2>> =>
-  map((a) => Result.mapErr(a, mapFn));
-
 /* implementation */
 
 class MapWithIndexObservableClass<A, B>
@@ -151,7 +107,7 @@ if (import.meta.vitest !== undefined) {
   {
     const s: Observable<number> = source<number>();
 
-    const _d1 = s.pipe(map((x) => x + 1));
+    const _d1 = s.pipe(mapWithIndex((x, i) => x + i));
 
     expectType<typeof _d1, Observable<number>>('=');
   }
@@ -161,7 +117,7 @@ if (import.meta.vitest !== undefined) {
 
     const m: InitializedObservable<number> = s.pipe(withInitialValue(0));
 
-    const _d = m.pipe(map((x) => x + 1));
+    const _d = m.pipe(mapWithIndex((x, i) => x + i));
 
     expectType<typeof _d, InitializedObservable<number>>('=');
   }

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

@@ -19,16 +19,58 @@ import {
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  ids$          1               2               3
+ * //  requests      fetch(1)        fetch(2)        fetch(3)
+ * //  users$        result1         result2         result3
+ * //                (parallel)      (parallel)      (parallel)
+ * //
+ * //  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
+ *
  * const ids$ = source<number>();
  *
- * const users$ = ids$.pipe(mergeMap((id) => fromPromise(fetchUser(id))));
+ * const users$ = ids$.pipe(
+ *   mergeMap((id) => {
+ *     const result$ = source<{ id: number }>();
+ *
+ *     setTimeout(() => {
+ *       result$.next({ id });
+ *
+ *       result$.complete();
+ *     }, 10);
+ *
+ *     return result$;
+ *   }),
+ * );
  *
- * users$.subscribe((user) => {
- *   console.log(user);
+ * const mut_history: { id: number }[] = [];
+ *
+ * users$.subscribe((value) => {
+ *   mut_history.push(value);
  * });
- * // All requests run in parallel, results merged as they arrive
  *
- * const fetchUser = async (id: number): Promise<unknown> => ({ id });
+ * ids$.next(1);
+ *
+ * ids$.next(2);
+ *
+ * ids$.next(3);
+ *
+ * await new Promise((resolve) => {
+ *   setTimeout(resolve, 200);
+ * });
+ *
+ * assert.deepStrictEqual(mut_history.length, 3);
+ *
+ * assert.isTrue(mut_history.some((u) => u.id === 1));
+ *
+ * assert.isTrue(mut_history.some((u) => u.id === 2));
+ *
+ * assert.isTrue(mut_history.some((u) => u.id === 3));
  * ```
  *
  * @note To improve code readability, consider using `createState` instead of `mergeMap`,
@@ -42,7 +84,7 @@ export const mergeMap =
     new MergeMapObservableClass(parentObservable, mapToObservable);
 
 /**
- * Alias for `mergeMap()`.
+ * Alias for `mergeMap`.
  * @see mergeMap
  */
 export const flatMap = mergeMap;

package/src/core/operators/pairwise.mts

@@ -16,19 +16,48 @@ import {
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  num$      1     2     3     4
+ * //  pairs$          [1,2] [2,3] [3,4]
+ * //
+ * //  Explanation:
+ * //  - pairwise emits the current and previous values as a tuple
+ * //  - Nothing is emitted for the first value (no previous value yet)
+ * //  - Useful for tracking changes between consecutive values
+ *
  * const num$ = source<number>();
  *
  * const pairs$ = num$.pipe(pairwise());
  *
+ * const mut_history: (readonly [number, number])[] = [];
+ *
  * pairs$.subscribe(([prev, curr]) => {
- *   console.log(prev, curr);
+ *   mut_history.push([prev, curr]);
  * });
  *
  * num$.next(1); // nothing logged
  *
+ * assert.deepStrictEqual(mut_history, []);
+ *
  * num$.next(2); // logs: 1, 2
  *
+ * assert.deepStrictEqual(mut_history, [[1, 2]]);
+ *
  * num$.next(3); // logs: 2, 3
+ *
+ * assert.deepStrictEqual(mut_history, [
+ *   [1, 2],
+ *   [2, 3],
+ * ]);
+ *
+ * num$.next(4); // logs: 3, 4
+ *
+ * assert.deepStrictEqual(mut_history, [
+ *   [1, 2],
+ *   [2, 3],
+ *   [3, 4],
+ * ]);
  * ```
  */
 export const pairwise = <A,>(): DropInitialValueOperator<A, readonly [A, A]> =>

package/src/core/operators/scan.mts

@@ -19,19 +19,41 @@ import {
  *
  * @example
  * ```ts
+ * //  Timeline (accumulating sum):
+ * //
+ * //  num$    1     2     3     4     5
+ * //  sum$    1     3     6     10    15
+ * //          |     |     |     |     |
+ * //          0+1   1+2   3+3   6+4   10+5
+ * //
+ * //  Explanation:
+ * //  - scan accumulates values over time using a reducer function
+ * //  - Starting with seed value 0, each emission adds to the accumulator
+ * //  - Similar to Array.reduce, but for streams
+ *
  * const num$ = source<number>();
  *
  * const sum$ = num$.pipe(scan((acc, curr) => acc + curr, 0));
  *
+ * const mut_history: number[] = [];
+ *
  * sum$.subscribe((x) => {
- *   console.log(x);
+ *   mut_history.push(x);
  * });
  *
+ * assert.deepStrictEqual(mut_history, [0]);
+ *
  * num$.next(1); // logs: 1
  *
+ * assert.deepStrictEqual(mut_history, [0, 1]);
+ *
  * num$.next(2); // logs: 3
  *
+ * assert.deepStrictEqual(mut_history, [0, 1, 3]);
+ *
  * num$.next(3); // logs: 6
+ *
+ * assert.deepStrictEqual(mut_history, [0, 1, 3, 6]);
  * ```
  */
 export const scan =

package/src/core/operators/skip-if-no-change.mts

@@ -17,19 +17,43 @@ import {
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  num$      1     1     2     2     2     3
+ * //  distinct$ 1           2                 3
+ * //
+ * //  Explanation:
+ * //  - skipIfNoChange filters out consecutive duplicate values
+ * //  - Uses strict equality (===) for comparison
+ * //  - Only emits when the value actually changes
+ *
  * const num$ = source<number>();
  *
  * const distinct$ = num$.pipe(skipIfNoChange());
  *
+ * const mut_history: number[] = [];
+ *
  * distinct$.subscribe((x) => {
- *   console.log(x);
+ *   mut_history.push(x);
  * });
  *
  * num$.next(1); // logs: 1
  *
+ * assert.deepStrictEqual(mut_history, [1]);
+ *
  * num$.next(1); // nothing logged
  *
+ * assert.deepStrictEqual(mut_history, [1]);
+ *
  * num$.next(2); // logs: 2
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2]);
+ *
+ * num$.next(2); // nothing logged
+ *
+ * num$.next(3); // logs: 3
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2, 3]);
  * ```
  */
 export const skipIfNoChange = <A,>(
@@ -43,10 +67,10 @@ export const skipIfNoChange = <A,>(
     )) as KeepInitialValueOperator<A, A>;
 
 /**
- * Alias for `skipIfNoChange()`.
+ * Alias for `skipIfNoChange`.
  * @see skipIfNoChange
  */
-export const distinctUntilChanged = skipIfNoChange; // alias
+export const distinctUntilChanged = skipIfNoChange;
 
 class SkipIfNoChangeObservableClass<A>
   extends SyncChildObservableClass<A, readonly [A]>

package/src/core/operators/skip-until.mts

@@ -7,6 +7,56 @@ import {
   type UpdaterSymbol,
 } from '../types/index.mjs';
 
+/**
+ * Skips all values from the source observable until the notifier observable emits.
+ *
+ * @template A - The type of values from the source
+ * @param notifier - An observable that signals when to start emitting
+ * @returns An operator that skips values until the notifier emits
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  num$          1     2     3     start   4     5     6
+ * //  startNotifier                   X
+ * //  skipped$                                4     5     6
+ * //                |------ skipped -------|
+ * //
+ * //  Explanation:
+ * //  - skipUntil ignores all values until the notifier emits
+ * //  - After the notifier emits, all subsequent values are passed through
+ * //  - Opposite of takeUntil (which completes when notifier emits)
+ *
+ * const num$ = source<number>();
+ *
+ * const [startNotifier, start_] = createEventEmitter();
+ *
+ * const skipped$ = num$.pipe(skipUntil(startNotifier));
+ *
+ * const mut_history: number[] = [];
+ *
+ * skipped$.subscribe((x) => {
+ *   mut_history.push(x);
+ * });
+ *
+ * num$.next(1); // nothing logged
+ *
+ * num$.next(2); // nothing logged
+ *
+ * assert.deepStrictEqual(mut_history, []);
+ *
+ * start_();
+ *
+ * num$.next(4); // logs: 4
+ *
+ * assert.deepStrictEqual(mut_history, [4]);
+ *
+ * num$.next(5); // logs: 5
+ *
+ * assert.deepStrictEqual(mut_history, [4, 5]);
+ * ```
+ */
 export const skipUntil =
   <A,>(notifier: Observable<unknown>): DropInitialValueOperator<A, A> =>
   (parentObservable) =>

package/src/core/operators/skip-while.mts

@@ -1,10 +1,4 @@
-import {
-  Optional,
-  PositiveSafeInt,
-  SafeUint,
-  asSafeUint,
-  pipe,
-} from 'ts-data-forge';
+import { Optional, SafeUint, asSafeUint, pipe } from 'ts-data-forge';
 import { SyncChildObservableClass } from '../class/index.mjs';
 import {
   type DropInitialValueOperator,
@@ -13,6 +7,54 @@ import {
   type UpdaterSymbol,
 } from '../types/index.mjs';
 
+/**
+ * Skips values from the source observable while the predicate returns true.
+ * Once the predicate returns false, all subsequent values pass through.
+ *
+ * @template A - The type of values from the source
+ * @param predicate - Function to test each value
+ * @returns An operator that skips values while the predicate is true
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  num$        1     2     3     4     5     6     7
+ * //  skipped$                      5     6     7
+ * //              |---- skip -----|
+ * //
+ * //  Explanation:
+ * //  - skipWhile skips values while the predicate returns true
+ * //  - Once the predicate returns false, all subsequent values pass through
+ * //  - Unlike filter, the predicate is never checked again after the first false
+ *
+ * const num$ = source<number>();
+ *
+ * const skipped$ = num$.pipe(skipWhile((x) => x < 5));
+ *
+ * const mut_history: number[] = [];
+ *
+ * skipped$.subscribe((x) => {
+ *   mut_history.push(x);
+ * });
+ *
+ * num$.next(1); // nothing logged
+ *
+ * num$.next(2); // nothing logged
+ *
+ * num$.next(5); // logs: 5
+ *
+ * assert.deepStrictEqual(mut_history, [5]);
+ *
+ * num$.next(6); // logs: 6
+ *
+ * assert.deepStrictEqual(mut_history, [5, 6]);
+ *
+ * num$.next(7); // logs: 7
+ *
+ * assert.deepStrictEqual(mut_history, [5, 6, 7]);
+ * ```
+ */
 export const skipWhile =
   <A,>(
     predicate: (value: A, index: SafeUint | -1) => boolean,
@@ -20,15 +62,6 @@ export const skipWhile =
   (parentObservable) =>
     new SkipWhileObservableClass(parentObservable, predicate);
 
-/* Specialized operators */
-
-export const skip = <A,>(
-  n: PositiveSafeIntWithSmallInt,
-): DropInitialValueOperator<A, A> =>
-  !PositiveSafeInt.is(n) ? idFn : skipWhile((_, index) => index + 1 <= n);
-
-const idFn = <T,>(value: T): T => value;
-
 /* implementation */
 
 class SkipWhileObservableClass<A>

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

@@ -19,18 +19,52 @@ import {
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  searchQuery$  "a"       "ab"      "abc"
+ * //  requests      fetch1    fetch2    fetch3
+ * //  results$                cancel    cancel    result3
+ * //                          fetch1    fetch2
+ * //
+ * //  Explanation:
+ * //  - switchMap cancels previous inner observables when a new value arrives
+ * //  - Only the result from the latest search query is emitted
+ * //  - Previous ongoing requests are cancelled
+ * //  - Ideal for search-as-you-type scenarios
+ *
  * const searchQuery$ = source<string>();
  *
  * const results$ = searchQuery$.pipe(
- *   switchMap((query) => fromPromise(fetchResults(query))),
+ *   switchMap((query) => {
+ *     const result$ = source<string[]>();
+ *
+ *     setTimeout(() => {
+ *       result$.next([query]);
+ *
+ *       result$.complete();
+ *     }, 10);
+ *
+ *     return result$;
+ *   }),
  * );
  *
- * results$.subscribe((results) => {
- *   console.log(results);
+ * const mut_history: string[][] = [];
+ *
+ * results$.subscribe((value) => {
+ *   mut_history.push(value);
+ * });
+ *
+ * searchQuery$.next('a');
+ *
+ * searchQuery$.next('ab');
+ *
+ * searchQuery$.next('abc');
+ *
+ * await new Promise((resolve) => {
+ *   setTimeout(resolve, 200);
  * });
- * // Only the latest search results are emitted, previous searches are cancelled
  *
- * const fetchResults = async (_query: string): Promise<readonly unknown[]> => [];
+ * assert.deepStrictEqual(mut_history, [['abc']]);
  * ```
  *
  * @note To improve code readability, consider using `createState` instead of `switchMap`,