synstate 0.1.0 → 0.1.1

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

@@ -26,17 +26,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>(

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`,

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,>(

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

@@ -13,6 +13,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,

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`,

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

@@ -17,23 +17,42 @@ import {
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  num$          1         2         stop      3 (ignored)
+ * //  stopNotifier                      X
+ * //  limited$      1         2         |------- (completed)
+ * //
+ * //  Explanation:
+ * //  - takeUntil completes the observable when the notifier emits
+ * //  - After stop() is called, no further values are emitted
+ * //  - Useful for cleanup and cancellation patterns
+ *
  * const num$ = source<number>();
  *
  * const [stopNotifier, stop_] = createEventEmitter();
  *
  * const limited$ = num$.pipe(takeUntil(stopNotifier));
  *
+ * const mut_history: number[] = [];
+ *
  * limited$.subscribe((x) => {
- *   console.log(x);
+ *   mut_history.push(x);
  * });
  *
  * num$.next(1); // logs: 1
  *
+ * assert.deepStrictEqual(mut_history, [1]);
+ *
  * num$.next(2); // logs: 2
  *
+ * assert.deepStrictEqual(mut_history, [1, 2]);
+ *
  * stop_();
  *
  * num$.next(3); // nothing logged (completed)
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2]);
  * ```
  */
 export const takeUntil = <A,>(

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

@@ -16,6 +16,53 @@ import {
 } from '../types/index.mjs';
 import { withInitialValue } from './with-initial-value.mjs';
 
+/**
+ * Emits values from the source observable while the predicate returns true.
+ * Completes immediately when the predicate returns false.
+ *
+ * @template A - The type of values from the source
+ * @param predicate - Function to test each value
+ * @returns An operator that takes values while the predicate is true
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  num$      1     2     3     4     5     6 (ignored)
+ * //  taken$    1     2     3     4     | (completes)
+ * //
+ * //  Explanation:
+ * //  - takeWhile emits values while the predicate returns true
+ * //  - Completes immediately when the predicate returns false
+ * //  - No further values are emitted after completion
+ *
+ * const num$ = source<number>();
+ *
+ * const taken$ = num$.pipe(takeWhile((x) => x < 5));
+ *
+ * const mut_history: number[] = [];
+ *
+ * taken$.subscribe((x) => {
+ *   mut_history.push(x);
+ * });
+ *
+ * num$.next(1); // logs: 1
+ *
+ * assert.deepStrictEqual(mut_history, [1]);
+ *
+ * num$.next(2); // logs: 2
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2]);
+ *
+ * num$.next(5); // nothing logged (completes)
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2]);
+ *
+ * num$.next(6); // nothing logged (already completed)
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2]);
+ * ```
+ */
 export const takeWhile =
   <A,>(
     predicate: (value: A, index: SafeUint | -1) => boolean,

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

@@ -17,14 +17,53 @@ import {
  *
  * @example
  * ```ts
- * const scroll$ = source<Event>();
+ * //  Timeline (1000ms throttle):
+ * //
+ * //  Time(ms)  0    100   200   300   ...   1000  1100  1200  ...   2000  2100
+ * //  scroll$   e1   e2    e3    e4          e5    e6    e7          e8    e9
+ * //  throttled$ e1                          e5                      e8
+ * //             |-------1000ms------>       |------1000ms------>    |------1000ms------>
+ * //
+ * //  Explanation:
+ * //  - throttleTime emits the first value immediately, then ignores subsequent values
+ * //    for the specified duration (1000ms)
+ * //  - At 0ms: e1 is emitted immediately
+ * //  - At 100-300ms: e2, e3, e4 are ignored (within 1000ms window)
+ * //  - At 1000ms: e5 is emitted (1000ms has passed since e1)
+ * //  - At 1100-1200ms: e6, e7 are ignored
+ * //  - At 2000ms: e8 is emitted (1000ms has passed since e5)
  *
- * const throttled$ = scroll$.pipe(throttleTime(1000));
+ * const scroll$ = source<number>();
  *
- * throttled$.subscribe((event_) => {
- *   console.log(event_);
+ * const throttled$ = scroll$.pipe(throttleTime(200));
+ *
+ * const mut_history: number[] = [];
+ *
+ * throttled$.subscribe((value) => {
+ *   mut_history.push(value);
  * });
- * // Emits at most once per second
+ *
+ * scroll$.next(1);
+ *
+ * assert.deepStrictEqual(mut_history, [1]);
+ *
+ * await new Promise((resolve) => {
+ *   setTimeout(resolve, 50);
+ * });
+ *
+ * scroll$.next(2);
+ *
+ * scroll$.next(3);
+ *
+ * assert.deepStrictEqual(mut_history, [1]);
+ *
+ * await new Promise((resolve) => {
+ *   setTimeout(resolve, 200);
+ * });
+ *
+ * scroll$.next(4);
+ *
+ * assert.deepStrictEqual(mut_history, [1, 4]);
  * ```
  */
 export const throttleTime = <A,>(

package/src/core/operators/with-buffered-from.mts

@@ -8,6 +8,59 @@ import {
 } from '../types/index.mjs';
 import { maxDepth } from '../utils/index.mjs';
 
+/**
+ * Buffers values from the source observable and emits them along with the parent value
+ * when the parent emits. The buffer is cleared after each emission.
+ *
+ * @template A - The type of values from the parent observable
+ * @template B - The type of values from the source observable
+ * @param observable - The observable whose values will be buffered
+ * @returns An operator that emits tuples of [parentValue, bufferedValues]
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  data$       d1    d2    d3    d4    d5    d6    d7    d8
+ * //  trigger$                T1                T2                T3
+ * //  result$                 [T1,[d1,d2,d3]]   [T2,[d4,d5,d6]]   [T3,[d7,d8]]
+ * //
+ * //  Explanation:
+ * //  - withBufferedFrom collects values from the source observable
+ * //  - When the trigger emits, it emits a tuple of [triggerValue, bufferedValues]
+ * //  - Buffer is cleared after each emission
+ * //  - Useful for batching data collection triggered by events
+ *
+ * const data$ = source<string>();
+ *
+ * const trigger$ = source<number>();
+ *
+ * const result$ = trigger$.pipe(withBufferedFrom(data$));
+ *
+ * const mut_history: (readonly [number, readonly string[]])[] = [];
+ *
+ * result$.subscribe(([triggerValue, bufferedData]) => {
+ *   mut_history.push([triggerValue, bufferedData]);
+ * });
+ *
+ * data$.next('a');
+ *
+ * data$.next('b');
+ *
+ * trigger$.next(1);
+ *
+ * assert.deepStrictEqual(mut_history, [[1, ['a', 'b']]]);
+ *
+ * data$.next('c');
+ *
+ * trigger$.next(2);
+ *
+ * assert.deepStrictEqual(mut_history, [
+ *   [1, ['a', 'b']],
+ *   [2, ['c']],
+ * ]);
+ * ```
+ */
 export const withBufferedFrom = <A, B>(
   observable: Observable<B>,
 ): KeepInitialValueOperator<A, readonly [A, readonly B[]]> =>