synstate 0.1.2 → 1.0.0

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

@@ -4,7 +4,7 @@ import {
   type KeepInitialValueOperator,
   type Observable,
   type SkipIfNoChangeOperatorObservable,
-  type UpdaterSymbol,
+  type UpdateToken,
 } from '../types/index.mjs';
 
 /**
@@ -19,8 +19,8 @@ import {
  * ```ts
  * //  Timeline:
  * //
- * //  num$      1     1     2     2     2     3
- * //  distinct$ 1           2                 3
+ * //  num$      1     1     2     2     1     2     3     2
+ * //  distinct$ 1           2           1     2     3     2
  * //
  * //  Explanation:
  * //  - skipIfNoChange filters out consecutive duplicate values
@@ -31,29 +31,41 @@ import {
  *
  * const distinct$ = num$.pipe(skipIfNoChange());
  *
- * const mut_history: number[] = [];
+ * const valueHistory: number[] = [];
  *
  * distinct$.subscribe((x) => {
- *   mut_history.push(x);
+ *   valueHistory.push(x);
  * });
  *
  * num$.next(1); // logs: 1
  *
- * assert.deepStrictEqual(mut_history, [1]);
+ * assert.deepStrictEqual(valueHistory, [1]);
  *
  * num$.next(1); // nothing logged
  *
- * assert.deepStrictEqual(mut_history, [1]);
+ * assert.deepStrictEqual(valueHistory, [1]);
  *
  * num$.next(2); // logs: 2
  *
- * assert.deepStrictEqual(mut_history, [1, 2]);
+ * assert.deepStrictEqual(valueHistory, [1, 2]);
  *
  * num$.next(2); // nothing logged
  *
+ * num$.next(1); // logs: 1
+ *
+ * assert.deepStrictEqual(valueHistory, [1, 2, 1]);
+ *
+ * num$.next(2); // logs: 2
+ *
+ * assert.deepStrictEqual(valueHistory, [1, 2, 1, 2]);
+ *
  * num$.next(3); // logs: 3
  *
- * assert.deepStrictEqual(mut_history, [1, 2, 3]);
+ * assert.deepStrictEqual(valueHistory, [1, 2, 1, 2, 3]);
+ *
+ * num$.next(2); // logs: 2
+ *
+ * assert.deepStrictEqual(valueHistory, [1, 2, 1, 2, 3, 2]);
  * ```
  */
 export const skipIfNoChange = <A,>(
@@ -92,12 +104,12 @@ class SkipIfNoChangeObservableClass<A>
     this.#eq = eq;
   }
 
-  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
     }
 
@@ -109,7 +121,7 @@ class SkipIfNoChangeObservableClass<A>
     this.#mut_previousValue = sn;
 
     if (cond) {
-      this.setNext(sn.value, updaterSymbol);
+      this.setNext(sn.value, updateToken);
     }
   }
 }

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

@@ -4,7 +4,7 @@ import {
   type DropInitialValueOperator,
   type Observable,
   type SkipUntilOperatorObservable,
-  type UpdaterSymbol,
+  type UpdateToken,
 } from '../types/index.mjs';
 
 /**
@@ -34,27 +34,27 @@ import {
  *
  * const skipped$ = num$.pipe(skipUntil(startNotifier));
  *
- * const mut_history: number[] = [];
+ * const valueHistory: number[] = [];
  *
  * skipped$.subscribe((x) => {
- *   mut_history.push(x);
+ *   valueHistory.push(x);
  * });
  *
  * num$.next(1); // nothing logged
  *
  * num$.next(2); // nothing logged
  *
- * assert.deepStrictEqual(mut_history, []);
+ * assert.deepStrictEqual(valueHistory, []);
  *
  * start_();
  *
  * num$.next(4); // logs: 4
  *
- * assert.deepStrictEqual(mut_history, [4]);
+ * assert.deepStrictEqual(valueHistory, [4]);
  *
  * num$.next(5); // logs: 5
  *
- * assert.deepStrictEqual(mut_history, [4, 5]);
+ * assert.deepStrictEqual(valueHistory, [4, 5]);
  * ```
  */
 export const skipUntil =
@@ -86,19 +86,19 @@ class SkipUntilObservableClass<A>
     );
   }
 
-  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+  override tryUpdate(updateToken: UpdateToken): void {
     const par = this.parents[0];
 
     const sn = par.getSnapshot();
 
     if (
-      par.updaterSymbol !== updaterSymbol ||
+      par.updateToken !== updateToken ||
       Optional.isNone(sn) ||
       this.#mut_isSkipping
     ) {
       return; // skip update
     }
 
-    this.setNext(sn.value, updaterSymbol);
+    this.setNext(sn.value, updateToken);
   }
 }

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

@@ -4,7 +4,7 @@ import {
   type DropInitialValueOperator,
   type Observable,
   type SkipWhileOperatorObservable,
-  type UpdaterSymbol,
+  type UpdateToken,
 } from '../types/index.mjs';
 
 /**
@@ -19,9 +19,9 @@ import {
  * ```ts
  * //  Timeline:
  * //
- * //  num$        1     2     3     4     5     6     7
- * //  skipped$                      5     6     7
- * //              |---- skip -----|
+ * //  num$        1     2     3     4     5     6     7     1     2
+ * //  skipped$                            5     6     7     1     2
+ * //              |-------- skip --------|
  * //
  * //  Explanation:
  * //  - skipWhile skips values while the predicate returns true
@@ -32,27 +32,37 @@ import {
  *
  * const skipped$ = num$.pipe(skipWhile((x) => x < 5));
  *
- * const mut_history: number[] = [];
+ * const valueHistory: number[] = [];
  *
  * skipped$.subscribe((x) => {
- *   mut_history.push(x);
+ *   valueHistory.push(x);
  * });
  *
  * num$.next(1); // nothing logged
  *
  * num$.next(2); // nothing logged
  *
+ * num$.next(3); // nothing logged
+ *
+ * num$.next(4); // nothing logged
+ *
  * num$.next(5); // logs: 5
  *
- * assert.deepStrictEqual(mut_history, [5]);
+ * assert.deepStrictEqual(valueHistory, [5]);
  *
  * num$.next(6); // logs: 6
  *
- * assert.deepStrictEqual(mut_history, [5, 6]);
+ * assert.deepStrictEqual(valueHistory, [5, 6]);
  *
  * num$.next(7); // logs: 7
  *
- * assert.deepStrictEqual(mut_history, [5, 6, 7]);
+ * assert.deepStrictEqual(valueHistory, [5, 6, 7]);
+ *
+ * num$.next(1); // logs: 1
+ *
+ * num$.next(2); // logs: 2
+ *
+ * assert.deepStrictEqual(valueHistory, [5, 6, 7, 1, 2]);
  * ```
  */
 export const skipWhile =
@@ -70,6 +80,7 @@ class SkipWhileObservableClass<A>
 {
   readonly #predicate: (value: A, index: SafeUint | -1) => boolean;
   #mut_index: SafeUint | -1;
+  #mut_skipping: boolean;
 
   constructor(
     parentObservable: Observable<A>,
@@ -89,14 +100,16 @@ class SkipWhileObservableClass<A>
     this.#mut_index = -1;
 
     this.#predicate = predicate;
+
+    this.#mut_skipping = true;
   }
 
-  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
     }
 
@@ -104,7 +117,11 @@ class SkipWhileObservableClass<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.#mut_skipping = false;
+    }
+
+    if (!this.#mut_skipping) {
+      this.setNext(sn.value, updateToken);
     }
   }
 }

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

@@ -5,7 +5,7 @@ import {
   type Observable,
   type Subscription,
   type SwitchMapOperatorObservable,
-  type UpdaterSymbol,
+  type UpdateToken,
 } from '../types/index.mjs';
 
 /**
@@ -21,50 +21,81 @@ import {
  * ```ts
  * //  Timeline:
  * //
- * //  searchQuery$  "a"       "ab"      "abc"
- * //  requests      fetch1    fetch2    fetch3
- * //  results$                cancel    cancel    result3
- * //                          fetch1    fetch2
+ * //  input$      A                          B              C
+ * //  inner A     A1    A2    A3
+ * //  inner B                                B1    B2      (switched!)
+ * //  inner C                                              C1    C2    C3
+ * //  result$     A1    A2    A3              B1    B2      C1    C2    C3
  * //
  * //  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
+ * //  - switchMap creates an inner observable for each source value
+ * //  - When a new source value arrives, the previous inner is unsubscribed
+ * //  - A's inner completes normally (all 3 values emitted)
+ * //  - B's inner is interrupted by C (only 2 values emitted)
+ * //  - C's inner completes normally (all 3 values emitted)
  *
- * const searchQuery$ = source<string>();
+ * const input$ = source<string>();
  *
- * const results$ = searchQuery$.pipe(
- *   switchMap((query) => {
- *     const result$ = source<string[]>();
+ * const result$ = input$.pipe(
+ *   switchMap((letter) => {
+ *     const inner$ = source<string>();
  *
  *     setTimeout(() => {
- *       result$.next([query]);
- *
- *       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: string[][] = [];
+ * const valueHistory: string[] = [];
  *
- * results$.subscribe((value) => {
- *   mut_history.push(value);
+ * result$.subscribe((value) => {
+ *   valueHistory.push(value);
  * });
  *
- * searchQuery$.next('a');
+ * const sleep = (ms: number): Promise<void> =>
+ *   new Promise((resolve) => {
+ *     setTimeout(resolve, ms);
+ *   });
  *
- * searchQuery$.next('ab');
+ * // Emit A - inner emits A1, A2, A3 at 10ms, 110ms, 210ms
+ * input$.next('A');
  *
- * searchQuery$.next('abc');
+ * 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(valueHistory, ['A1', 'A2', 'A3', 'B1', 'B2']);
+ *
+ * // Emit C - switches away from B (B3 cancelled), C's inner starts
+ * input$.next('C');
+ *
+ * await sleep(250);
  *
- * assert.deepStrictEqual(mut_history, [['abc']]);
+ * assert.deepStrictEqual(valueHistory, [
+ *   'A1',
+ *   'A2',
+ *   'A3',
+ *   'B1',
+ *   'B2',
+ *   'C1',
+ *   'C2',
+ *   'C3',
+ * ]);
  * ```
  *
  * @note To improve code readability, consider using `createState` instead of `switchMap`,
@@ -101,12 +132,12 @@ class SwitchMapObservableClass<A, B>
     this.#mut_subscription = undefined;
   }
 
-  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/take-until.mts

@@ -4,7 +4,7 @@ import {
   type KeepInitialValueOperator,
   type Observable,
   type TakeUntilOperatorObservable,
-  type UpdaterSymbol,
+  type UpdateToken,
 } from '../types/index.mjs';
 
 /**
@@ -34,25 +34,25 @@ import {
  *
  * const limited$ = num$.pipe(takeUntil(stopNotifier));
  *
- * const mut_history: number[] = [];
+ * const valueHistory: number[] = [];
  *
  * limited$.subscribe((x) => {
- *   mut_history.push(x);
+ *   valueHistory.push(x);
  * });
  *
  * num$.next(1); // logs: 1
  *
- * assert.deepStrictEqual(mut_history, [1]);
+ * assert.deepStrictEqual(valueHistory, [1]);
  *
  * num$.next(2); // logs: 2
  *
- * assert.deepStrictEqual(mut_history, [1, 2]);
+ * assert.deepStrictEqual(valueHistory, [1, 2]);
  *
  * stop_();
  *
  * num$.next(3); // nothing logged (completed)
  *
- * assert.deepStrictEqual(mut_history, [1, 2]);
+ * assert.deepStrictEqual(valueHistory, [1, 2]);
  * ```
  */
 export const takeUntil = <A,>(
@@ -85,15 +85,15 @@ class TakeUntilObservableClass<A>
     );
   }
 
-  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
     }
 
-    this.setNext(sn.value, updaterSymbol);
+    this.setNext(sn.value, updateToken);
   }
 }

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

@@ -12,7 +12,7 @@ import {
   type InitializedObservable,
   type Observable,
   type TakeWhileOperatorObservable,
-  type UpdaterSymbol,
+  type UpdateToken,
 } from '../types/index.mjs';
 import { withInitialValue } from './with-initial-value.mjs';
 
@@ -28,7 +28,7 @@ import { withInitialValue } from './with-initial-value.mjs';
  * ```ts
  * //  Timeline:
  * //
- * //  num$      1     2     3     4     5     6 (ignored)
+ * //  num$      1     2     3     4     5     6     1     2 (ignored)
  * //  taken$    1     2     3     4     | (completes)
  * //
  * //  Explanation:
@@ -40,27 +40,35 @@ import { withInitialValue } from './with-initial-value.mjs';
  *
  * const taken$ = num$.pipe(takeWhile((x) => x < 5));
  *
- * const mut_history: number[] = [];
+ * const valueHistory: number[] = [];
  *
  * taken$.subscribe((x) => {
- *   mut_history.push(x);
+ *   valueHistory.push(x);
  * });
  *
  * num$.next(1); // logs: 1
  *
- * assert.deepStrictEqual(mut_history, [1]);
+ * assert.deepStrictEqual(valueHistory, [1]);
  *
  * num$.next(2); // logs: 2
  *
- * assert.deepStrictEqual(mut_history, [1, 2]);
+ * num$.next(3); // logs: 3
+ *
+ * num$.next(4); // logs: 4
+ *
+ * assert.deepStrictEqual(valueHistory, [1, 2, 3, 4]);
  *
  * num$.next(5); // nothing logged (completes)
  *
- * assert.deepStrictEqual(mut_history, [1, 2]);
+ * assert.deepStrictEqual(valueHistory, [1, 2, 3, 4]);
  *
  * num$.next(6); // nothing logged (already completed)
  *
- * assert.deepStrictEqual(mut_history, [1, 2]);
+ * assert.deepStrictEqual(valueHistory, [1, 2, 3, 4]);
+ *
+ * num$.next(1); // logs: 1
+ *
+ * assert.deepStrictEqual(valueHistory, [1, 2, 3, 4]);
  * ```
  */
 export const takeWhile =
@@ -99,12 +107,12 @@ class TakeWhileObservableClass<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
     }
 
@@ -112,7 +120,7 @@ class TakeWhileObservableClass<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);
     } else {
       this.complete();
     }

package/src/core/operators/{throttle-time.mts → throttle.mts}

@@ -3,8 +3,9 @@ import { SyncChildObservableClass } from '../class/index.mjs';
 import {
   type KeepInitialValueOperator,
   type Observable,
-  type ThrottleTimeOperatorObservable,
-  type UpdaterSymbol,
+  type ThrottleOperatorObservable,
+  type TimerId,
+  type UpdateToken,
 } from '../types/index.mjs';
 
 /**
@@ -17,68 +18,87 @@ import {
  *
  * @example
  * ```ts
- * //  Timeline (1000ms throttle):
+ * //  Timeline (250ms 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------>
+ * //  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 ->         |- 250ms ->    |- 250ms ->
+ * //  throttled$   0           3                   9          12           (emitted at start of window)
  * //
  * //  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)
+ * //  - throttle emits the FIRST value received, then ignores subsequent values
+ * //    for the specified duration (250ms)
+ * //  - Unlike audit (which emits the LAST value), throttle emits the FIRST
+ * //  - Useful for rate-limiting scroll/resize events
  *
- * const scroll$ = source<number>();
+ * const input$ = source<number>();
  *
- * const throttled$ = scroll$.pipe(throttleTime(200));
+ * const throttled$ = input$.pipe(throttle(250));
  *
- * const mut_history: number[] = [];
+ * const valueHistory: number[] = [];
  *
  * throttled$.subscribe((value) => {
- *   mut_history.push(value);
+ *   valueHistory.push(value);
  * });
  *
- * scroll$.next(1);
+ * const sleep = (ms: number): Promise<void> =>
+ *   new Promise((resolve) => {
+ *     setTimeout(resolve, ms);
+ *   });
  *
- * assert.deepStrictEqual(mut_history, [1]);
+ * input$.next(0);
  *
- * await new Promise((resolve) => {
- *   setTimeout(resolve, 50);
- * });
+ * assert.deepStrictEqual(valueHistory, [0]);
  *
- * scroll$.next(2);
+ * await sleep(200);
  *
- * scroll$.next(3);
+ * input$.next(2);
  *
- * assert.deepStrictEqual(mut_history, [1]);
+ * assert.deepStrictEqual(valueHistory, [0]);
  *
- * await new Promise((resolve) => {
- *   setTimeout(resolve, 200);
- * });
+ * await sleep(100);
+ *
+ * input$.next(3);
+ *
+ * assert.deepStrictEqual(valueHistory, [0, 3]);
+ *
+ * await sleep(300);
+ *
+ * input$.next(9);
+ *
+ * assert.deepStrictEqual(valueHistory, [0, 3, 9]);
+ *
+ * await sleep(100);
+ *
+ * input$.next(10);
+ *
+ * await sleep(100);
+ *
+ * input$.next(11);
+ *
+ * assert.deepStrictEqual(valueHistory, [0, 3, 9]);
+ *
+ * await sleep(100);
  *
- * scroll$.next(4);
+ * input$.next(12);
  *
- * assert.deepStrictEqual(mut_history, [1, 4]);
+ * assert.deepStrictEqual(valueHistory, [0, 3, 9, 12]);
  * ```
  */
-export const throttleTime = <A,>(
+export const throttle = <A,>(
   milliSeconds: number,
 ): KeepInitialValueOperator<A, A> =>
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   ((parentObservable) =>
-    new ThrottleTimeObservableClass(
+    new ThrottleObservableClass(
       parentObservable,
       milliSeconds,
     )) as KeepInitialValueOperator<A, A>;
 
-class ThrottleTimeObservableClass<A>
+class ThrottleObservableClass<A>
   extends SyncChildObservableClass<A, readonly [A]>
-  implements ThrottleTimeOperatorObservable<A>
+  implements ThrottleOperatorObservable<A>
 {
   readonly #milliSeconds: number;
   #mut_timerId: TimerId | undefined;
@@ -97,20 +117,20 @@ class ThrottleTimeObservableClass<A>
     this.#milliSeconds = milliSeconds;
   }
 
-  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+  override tryUpdate(updateToken: UpdateToken): void {
     const par = this.parents[0];
 
     const sn = par.getSnapshot();
 
     if (
-      par.updaterSymbol !== updaterSymbol ||
+      par.updateToken !== updateToken ||
       Optional.isNone(sn) ||
       this.#mut_isSkipping
     ) {
       return; // skip update
     }
 
-    this.setNext(sn.value, updaterSymbol);
+    this.setNext(sn.value, updateToken);
 
     this.#mut_isSkipping = true;