synstate 0.1.2 → 1.0.1

package/src/core/create/source.mts

@@ -25,39 +25,35 @@ import {
  *
  * const count$ = source<number>();
  *
- * const mut_history: number[] = [];
+ * const valueHistory: number[] = [];
  *
  * count$.subscribe((value) => {
- *   mut_history.push(value);
+ *   valueHistory.push(value);
  * });
  *
  * count$.next(1); // logs: 1
  *
- * assert.deepStrictEqual(mut_history, [1]);
+ * assert.deepStrictEqual(valueHistory, [1]);
  *
  * count$.next(2); // logs: 2
  *
- * assert.deepStrictEqual(mut_history, [1, 2]);
+ * assert.deepStrictEqual(valueHistory, [1, 2]);
  *
  * count$.next(3); // logs: 3
  *
- * assert.deepStrictEqual(mut_history, [1, 2, 3]);
+ * assert.deepStrictEqual(valueHistory, [1, 2, 3]);
  * ```
  */
-export function source<A>(initialValue: A): InitializedSourceObservable<A>;
+export function source<const A>(
+  initialValue: A,
+): InitializedSourceObservable<A>;
 
-export function source<A>(): SourceObservable<A>;
+export function source<const A>(): SourceObservable<A>;
 
-export function source<A>(...args: readonly A[]): SourceObservable<A> {
+export function source<const A>(...args: readonly A[]): SourceObservable<A> {
   return new SourceObservableClass<A>(...args);
 }
 
-/**
- * Alias for `source`. Creates a new Observable source.
- * @see source
- */
-export const subject = source;
-
 class SourceObservableClass<A>
   extends RootObservableClass<A>
   implements SourceObservable<A>

package/src/core/create/timer.mts

@@ -1,6 +1,6 @@
 import { Optional } from 'ts-data-forge';
 import { RootObservableClass } from '../class/index.mjs';
-import { type TimerObservable } from '../types/index.mjs';
+import { type TimerId, type TimerObservable } from '../types/index.mjs';
 
 /**
  * Creates an observable that emits 0 after a specified delay and then completes.
@@ -22,12 +22,12 @@ import { type TimerObservable } from '../types/index.mjs';
  *
  * const delayed$ = timer(100);
  *
- * const mut_history: number[] = [];
+ * const valueHistory: number[] = [];
  *
  * await new Promise<void>((resolve) => {
  *   delayed$.subscribe(
  *     () => {
- *       mut_history.push(1);
+ *       valueHistory.push(1);
  *     },
  *     () => {
  *       resolve();
@@ -35,13 +35,16 @@ import { type TimerObservable } from '../types/index.mjs';
  *   );
  * });
  *
- * assert.deepStrictEqual(mut_history, [1]);
+ * assert.deepStrictEqual(valueHistory, [1]);
  * ```
  */
 export const timer = (
   milliSeconds: number,
-  startManually: boolean = false,
-): TimerObservable => new TimerObservableClass(milliSeconds, startManually);
+  options?: Readonly<{
+    startManually?: boolean;
+  }>,
+): TimerObservable =>
+  new TimerObservableClass(milliSeconds, options?.startManually ?? false);
 
 class TimerObservableClass
   extends RootObservableClass<0>
@@ -65,11 +68,11 @@ class TimerObservableClass
     }
   }
 
-  start(): this {
+  start(): void {
     if (this.#mut_isStarted) {
       console.warn('cannot start twice');
 
-      return this;
+      return;
     }
 
     this.#mut_isStarted = true;
@@ -77,7 +80,7 @@ class TimerObservableClass
     if (this.isCompleted) {
       console.warn('cannot restart stopped TimerObservable');
 
-      return this;
+      return;
     }
 
     this.#mut_timerId = setTimeout(() => {
@@ -85,8 +88,6 @@ class TimerObservableClass
 
       this.complete();
     }, this.#milliSeconds);
-
-    return this;
   }
 
   #resetTimer(): void {

package/src/core/index.mts

@@ -4,4 +4,3 @@ export * from './create/index.mjs';
 export * from './operators/index.mjs';
 export * from './predefined/index.mjs';
 export * from './types/index.mjs';
-export * from './utils/index.mjs';

package/src/core/operators/audit.mts

@@ -0,0 +1,172 @@
+import { Optional } from 'ts-data-forge';
+import { AsyncChildObservableClass } from '../class/index.mjs';
+import {
+  type AuditOperatorObservable,
+  type KeepInitialValueOperator,
+  type Observable,
+  type TimerId,
+  type UpdateToken,
+} from '../types/index.mjs';
+
+/**
+ * Ignores source values for duration milliseconds, then emits the most recent value from the source Observable, then repeats this process.
+ *
+ * Unlike `throttle` which emits the first value, `audit` 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 (250ms audit):
+ * //
+ * //  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 ->
+ * //  audited$               2           3                   11          14   (emitted at end of window)
+ * //
+ * //  Explanation:
+ * //  - audit emits the LAST value received during each time window
+ * //  - Unlike throttle (which emits the FIRST value), audit emits the LAST
+ * //  - Useful when you want the most recent value after a burst of events
+ *
+ * const input$ = source<number>();
+ *
+ * const audited$ = input$.pipe(audit(250));
+ *
+ * const valueHistory: number[] = [];
+ *
+ * audited$.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);
+ *
+ * assert.deepStrictEqual(valueHistory, []);
+ *
+ * await sleep(100);
+ *
+ * assert.deepStrictEqual(valueHistory, [2]);
+ *
+ * input$.next(3);
+ *
+ * await sleep(300);
+ *
+ * assert.deepStrictEqual(valueHistory, [2, 3]);
+ *
+ * await sleep(300);
+ *
+ * input$.next(9);
+ *
+ * await sleep(100);
+ *
+ * input$.next(10);
+ *
+ * await sleep(100);
+ *
+ * input$.next(11);
+ *
+ * assert.deepStrictEqual(valueHistory, [2, 3]);
+ *
+ * await sleep(100);
+ *
+ * assert.deepStrictEqual(valueHistory, [2, 3, 11]);
+ *
+ * input$.next(12);
+ *
+ * await sleep(100);
+ *
+ * input$.next(13);
+ *
+ * assert.deepStrictEqual(valueHistory, [2, 3, 11]);
+ *
+ * await sleep(100);
+ *
+ * input$.next(14);
+ *
+ * assert.deepStrictEqual(valueHistory, [2, 3, 11]);
+ *
+ * await sleep(100);
+ *
+ * assert.deepStrictEqual(valueHistory, [2, 3, 11, 14]);
+ * ```
+ */
+export const audit = <A,>(
+  milliSeconds: number,
+): KeepInitialValueOperator<A, A> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  ((parentObservable) =>
+    new AuditObservableClass(
+      parentObservable,
+      milliSeconds,
+    )) as KeepInitialValueOperator<A, A>;
+
+class AuditObservableClass<A>
+  extends AsyncChildObservableClass<A, readonly [A]>
+  implements AuditOperatorObservable<A>
+{
+  readonly #milliSeconds: number;
+  #mut_timerId: TimerId | undefined;
+  #mut_isSkipping: boolean;
+
+  constructor(parentObservable: Observable<A>, milliSeconds: number) {
+    super({
+      parents: [parentObservable],
+      initialValue: parentObservable.getSnapshot(),
+    });
+
+    this.#mut_isSkipping = false;
+
+    this.#mut_timerId = undefined;
+
+    this.#milliSeconds = milliSeconds;
+  }
+
+  override tryUpdate(updateToken: UpdateToken): void {
+    const par = this.parents[0];
+
+    if (
+      par.updateToken !== updateToken ||
+      Optional.isNone(par.getSnapshot()) ||
+      this.#mut_isSkipping
+    ) {
+      return; // skip update
+    }
+
+    // set timer
+    this.#mut_isSkipping = true;
+
+    this.#mut_timerId = setTimeout(() => {
+      const sn = par.getSnapshot();
+
+      if (Optional.isNone(sn)) return;
+
+      this.startUpdate(sn.value);
+
+      this.#mut_isSkipping = false;
+    }, this.#milliSeconds);
+  }
+
+  #resetTimer(): void {
+    if (this.#mut_timerId !== undefined) {
+      clearTimeout(this.#mut_timerId);
+    }
+  }
+
+  override complete(): void {
+    this.#resetTimer();
+
+    super.complete();
+  }
+}

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-with-index.mts → map.mts}

@@ -4,9 +4,9 @@ import { source } from '../create/index.mjs';
 import {
   type InitializedObservable,
   type KeepInitialValueOperator,
-  type MapWithIndexOperatorObservable,
+  type MapOperatorObservable,
   type Observable,
-  type UpdaterSymbol,
+  type UpdateToken,
 } from '../types/index.mjs';
 import { withInitialValue } from './with-initial-value.mjs';
 
@@ -22,8 +22,8 @@ import { withInitialValue } from './with-initial-value.mjs';
  * ```ts
  * //  Timeline:
  * //
- * //  num$      "a"      "b"      "c"
- * //  indexed$  "0: a"   "1: b"   "2: c"
+ * //  num$      "A"      "B"      "C"
+ * //  indexed$  "0: A"   "1: B"   "2: C"
  * //
  * //  Explanation:
  * //  - mapWithIndex transforms each value along with its index
@@ -31,38 +31,38 @@ import { withInitialValue } from './with-initial-value.mjs';
  *
  * const num$ = source<string>();
  *
- * const indexed$ = num$.pipe(mapWithIndex((x, i) => `${i}: ${x}`));
+ * const indexed$ = num$.pipe(map((x, i) => `${i}: ${x}`));
  *
- * const mut_history: string[] = [];
+ * const valueHistory: string[] = [];
  *
  * indexed$.subscribe((s) => {
- *   mut_history.push(s);
+ *   valueHistory.push(s);
  * });
  *
- * num$.next('a'); // 0: a
+ * num$.next('A'); // 0: A
  *
- * num$.next('b'); // 1: b
+ * num$.next('B'); // 1: B
  *
- * num$.next('c'); // 2: c
+ * num$.next('C'); // 2: C
  *
- * assert.deepStrictEqual(mut_history, ['0: a', '1: b', '2: c']);
+ * assert.deepStrictEqual(valueHistory, ['0: A', '1: B', '2: C']);
  * ```
  */
-export const mapWithIndex = <A, B>(
+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 MapWithIndexObservableClass(
+    new MapObservableClass(
       parentObservable,
       mapFn,
     )) as KeepInitialValueOperator<A, B>;
 
 /* implementation */
 
-class MapWithIndexObservableClass<A, B>
+class MapObservableClass<A, B>
   extends SyncChildObservableClass<B, readonly [A]>
-  implements MapWithIndexOperatorObservable<A, B>
+  implements MapOperatorObservable<A, B>
 {
   readonly #mapFn: (x: A, index: SafeUint | -1) => B;
   #mut_index: SafeUint | -1;
@@ -83,19 +83,19 @@ class MapWithIndexObservableClass<A, B>
     this.#mapFn = mapFn;
   }
 
-  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.#mut_index =
       this.#mut_index === -1 ? asSafeUint(0) : SafeUint.add(1, this.#mut_index);
 
-    this.setNext(this.#mapFn(sn.value, this.#mut_index), updaterSymbol);
+    this.setNext(this.#mapFn(sn.value, this.#mut_index), updateToken);
   }
 }
 
@@ -107,7 +107,7 @@ if (import.meta.vitest !== undefined) {
   {
     const s: Observable<number> = source<number>();
 
-    const _d1 = s.pipe(mapWithIndex((x, i) => x + i));
+    const _d1 = s.pipe(map((x, i) => x + i));
 
     expectType<typeof _d1, Observable<number>>('=');
   }
@@ -117,7 +117,7 @@ if (import.meta.vitest !== undefined) {
 
     const m: InitializedObservable<number> = s.pipe(withInitialValue(0));
 
-    const _d = m.pipe(mapWithIndex((x, i) => x + i));
+    const _d = m.pipe(map((x, i) => x + i));
 
     expectType<typeof _d, InitializedObservable<number>>('=');
   }