synstate 0.1.0

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

@@ -0,0 +1,168 @@
+import {
+  Optional,
+  Result,
+  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 MapWithIndexOperatorObservable,
+  type Observable,
+  type UpdaterSymbol,
+} 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
+ * const num$ = source<number>();
+ *
+ * const indexed$ = num$.pipe(mapWithIndex((x, i) => `${i}: ${x}`));
+ *
+ * indexed$.subscribe((s) => {
+ *   console.log(s);
+ * });
+ *
+ * num$.next(10); // logs: 0: 10
+ *
+ * num$.next(20); // logs: 1: 20
+ * ```
+ */
+export const mapWithIndex = <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(
+      parentObservable,
+      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>
+  extends SyncChildObservableClass<B, readonly [A]>
+  implements MapWithIndexOperatorObservable<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(updaterSymbol: UpdaterSymbol): void {
+    const par = this.parents[0];
+
+    const sn = par.getSnapshot();
+
+    if (par.updaterSymbol !== updaterSymbol || 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);
+  }
+}
+
+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) => x + 1));
+
+    expectType<typeof _d1, Observable<number>>('=');
+  }
+
+  {
+    const s = source<number>();
+
+    const m: InitializedObservable<number> = s.pipe(withInitialValue(0));
+
+    const _d = m.pipe(map((x) => x + 1));
+
+    expectType<typeof _d, InitializedObservable<number>>('=');
+  }
+}

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

@@ -0,0 +1,108 @@
+import { Arr, Optional } from 'ts-data-forge';
+import { AsyncChildObservableClass } from '../class/index.mjs';
+import {
+  type DropInitialValueOperator,
+  type MergeMapOperatorObservable,
+  type Observable,
+  type Subscription,
+  type UpdaterSymbol,
+} from '../types/index.mjs';
+
+/**
+ * Projects each source value to an observable and merges all inner observables.
+ * Unlike `switchMap`, does not cancel previous inner observables.
+ *
+ * @template A - The type of values from the source
+ * @template B - The type of values from the projected observable
+ * @param mapToObservable - A function that maps each source value to an observable
+ * @returns An operator that merges mapped observables
+ *
+ * @example
+ * ```ts
+ * const ids$ = source<number>();
+ *
+ * const users$ = ids$.pipe(mergeMap((id) => fromPromise(fetchUser(id))));
+ *
+ * users$.subscribe((user) => {
+ *   console.log(user);
+ * });
+ * // All requests run in parallel, results merged as they arrive
+ *
+ * const fetchUser = async (id: number): Promise<unknown> => ({ id });
+ * ```
+ *
+ * @note To improve code readability, consider using `createState` instead of `mergeMap`,
+ * subscribing to `parentObservable` and calling `setState` within it.
+ */
+export const mergeMap =
+  <A, B>(
+    mapToObservable: (curr: A) => Observable<B>,
+  ): DropInitialValueOperator<A, B> =>
+  (parentObservable) =>
+    new MergeMapObservableClass(parentObservable, mapToObservable);
+
+/**
+ * Alias for `mergeMap()`.
+ * @see mergeMap
+ */
+export const flatMap = mergeMap;
+
+class MergeMapObservableClass<A, B>
+  extends AsyncChildObservableClass<B, readonly [A]>
+  implements MergeMapOperatorObservable<A, B>
+{
+  readonly #mapToObservable: (curr: A) => Observable<B>;
+  #mut_observables: readonly Observable<B>[];
+  #mut_subscriptions: readonly Subscription[];
+
+  constructor(
+    parentObservable: Observable<A>,
+    mapToObservable: (curr: A) => Observable<B>,
+  ) {
+    super({
+      parents: [parentObservable],
+      initialValue: Optional.none,
+    });
+
+    this.#mapToObservable = mapToObservable;
+
+    this.#mut_observables = [];
+
+    this.#mut_subscriptions = [];
+  }
+
+  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+    const par = this.parents[0];
+
+    const sn = par.getSnapshot();
+
+    if (par.updaterSymbol !== updaterSymbol || Optional.isNone(sn)) {
+      return; // skip update
+    }
+
+    const observable = this.#mapToObservable(sn.value);
+
+    this.#mut_observables = Arr.toPushed(this.#mut_observables, observable);
+
+    const subscription = observable.subscribe((curr) => {
+      this.startUpdate(curr);
+    });
+
+    this.#mut_subscriptions = Arr.toPushed(
+      this.#mut_subscriptions,
+      subscription,
+    );
+  }
+
+  override complete(): void {
+    for (const s of this.#mut_subscriptions) {
+      s.unsubscribe();
+    }
+
+    for (const o of this.#mut_observables) {
+      o.complete();
+    }
+
+    super.complete();
+  }
+}

package/src/core/operators/pairwise.mts

@@ -0,0 +1,77 @@
+import { Optional } from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import {
+  type DropInitialValueOperator,
+  type Observable,
+  type PairwiseOperatorObservable,
+  type UpdaterSymbol,
+} from '../types/index.mjs';
+
+/**
+ * Emits the previous and current values as a pair.
+ * Does not emit until the source has emitted at least twice.
+ *
+ * @template A - The type of values from the source
+ * @returns An operator that pairs consecutive values
+ *
+ * @example
+ * ```ts
+ * const num$ = source<number>();
+ *
+ * const pairs$ = num$.pipe(pairwise());
+ *
+ * pairs$.subscribe(([prev, curr]) => {
+ *   console.log(prev, curr);
+ * });
+ *
+ * num$.next(1); // nothing logged
+ *
+ * num$.next(2); // logs: 1, 2
+ *
+ * num$.next(3); // logs: 2, 3
+ * ```
+ */
+export const pairwise = <A,>(): DropInitialValueOperator<A, readonly [A, A]> =>
+  f;
+
+const f = <A,>(parentObservable: Observable<A>): Observable<readonly [A, A]> =>
+  new PairwiseObservableClass(parentObservable);
+
+class PairwiseObservableClass<A>
+  extends SyncChildObservableClass<readonly [A, A], readonly [A]>
+  implements PairwiseOperatorObservable<A>
+{
+  #mut_previousValue: Optional<A>;
+
+  constructor(parentObservable: Observable<A>) {
+    super({
+      parents: [parentObservable],
+      initialValue: Optional.none,
+    });
+
+    // parentObservable.snapshot has value
+    // if parentObservable is InitializedObservable
+    this.#mut_previousValue = parentObservable.getSnapshot();
+  }
+
+  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+    const par = this.parents[0];
+
+    const sn = par.getSnapshot();
+
+    if (par.updaterSymbol !== updaterSymbol || Optional.isNone(sn)) {
+      return; // skip update
+    }
+
+    const prev = this.#mut_previousValue;
+
+    const cond = !Optional.isNone(prev);
+
+    // NOTE: Must update before setNext, otherwise Optional.isNone(prev) remains true when tryUpdate is called consecutively
+    this.#mut_previousValue = par.getSnapshot();
+
+    if (cond) {
+      this.setNext([prev.value, sn.value], updaterSymbol);
+    }
+  }
+}

package/src/core/operators/scan.mts

@@ -0,0 +1,81 @@
+import { Optional } from 'ts-data-forge';
+import { InitializedSyncChildObservableClass } from '../class/index.mjs';
+import {
+  type Observable,
+  type ScanOperatorObservable,
+  type UpdaterSymbol,
+  type WithInitialValueOperator,
+} from '../types/index.mjs';
+
+/**
+ * Applies an accumulator function over the source observable and emits each intermediate result.
+ * Similar to Array.reduce but emits accumulated value after each source emission.
+ *
+ * @template A - The type of values from the source
+ * @template B - The type of the accumulated value
+ * @param reducer - The accumulator function
+ * @param initialValue - The initial accumulated value (seed)
+ * @returns An operator that accumulates values
+ *
+ * @example
+ * ```ts
+ * const num$ = source<number>();
+ *
+ * const sum$ = num$.pipe(scan((acc, curr) => acc + curr, 0));
+ *
+ * sum$.subscribe((x) => {
+ *   console.log(x);
+ * });
+ *
+ * num$.next(1); // logs: 1
+ *
+ * num$.next(2); // logs: 3
+ *
+ * num$.next(3); // logs: 6
+ * ```
+ */
+export const scan =
+  <A, B>(
+    reducer: (acc: B, curr: A) => B,
+    initialValue: B,
+  ): WithInitialValueOperator<A, B> =>
+  (parentObservable) =>
+    new ScanObservableClass(parentObservable, reducer, initialValue);
+
+class ScanObservableClass<A, B>
+  extends InitializedSyncChildObservableClass<B, readonly [A]>
+  implements ScanOperatorObservable<A, B>
+{
+  readonly #reducer: (acc: B, curr: A) => B;
+
+  constructor(
+    parentObservable: Observable<A>,
+    reducer: (acc: B, curr: A) => B,
+    initialValue: B,
+  ) {
+    super({
+      parents: [parentObservable],
+      initialValue: Optional.some(initialValue),
+    });
+
+    this.#reducer = reducer;
+  }
+
+  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+    const par = this.parents[0];
+
+    const psn = par.getSnapshot();
+
+    const sn = this.getSnapshot();
+
+    if (
+      par.updaterSymbol !== updaterSymbol ||
+      Optional.isNone(psn) ||
+      Optional.isNone(sn)
+    ) {
+      return; // skip update
+    }
+
+    this.setNext(this.#reducer(sn.value, psn.value), updaterSymbol);
+  }
+}

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

@@ -0,0 +1,91 @@
+import { Optional } from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import {
+  type KeepInitialValueOperator,
+  type Observable,
+  type SkipIfNoChangeOperatorObservable,
+  type UpdaterSymbol,
+} from '../types/index.mjs';
+
+/**
+ * Skips emissions if the value hasn't changed from the previous emission.
+ * Uses a custom equality function or Object.is by default.
+ *
+ * @template A - The type of values from the source
+ * @param eq - Equality comparison function (default: Object.is)
+ * @returns An operator that skips duplicate consecutive values
+ *
+ * @example
+ * ```ts
+ * const num$ = source<number>();
+ *
+ * const distinct$ = num$.pipe(skipIfNoChange());
+ *
+ * distinct$.subscribe((x) => {
+ *   console.log(x);
+ * });
+ *
+ * num$.next(1); // logs: 1
+ *
+ * num$.next(1); // nothing logged
+ *
+ * num$.next(2); // logs: 2
+ * ```
+ */
+export const skipIfNoChange = <A,>(
+  eq: (x: A, y: A) => boolean = (x, y) => Object.is(x, y),
+): KeepInitialValueOperator<A, A> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  ((parentObservable) =>
+    new SkipIfNoChangeObservableClass(
+      parentObservable,
+      eq,
+    )) as KeepInitialValueOperator<A, A>;
+
+/**
+ * Alias for `skipIfNoChange()`.
+ * @see skipIfNoChange
+ */
+export const distinctUntilChanged = skipIfNoChange; // alias
+
+class SkipIfNoChangeObservableClass<A>
+  extends SyncChildObservableClass<A, readonly [A]>
+  implements SkipIfNoChangeOperatorObservable<A>
+{
+  readonly #eq: (x: A, y: A) => boolean;
+  #mut_previousValue: Optional<A>;
+
+  constructor(parentObservable: Observable<A>, eq: (x: A, y: A) => boolean) {
+    super({
+      parents: [parentObservable],
+      initialValue: parentObservable.getSnapshot(),
+    });
+
+    // parentObservable.snapshot has value
+    // if parentObservable is InitializedObservable
+    this.#mut_previousValue = parentObservable.getSnapshot();
+
+    this.#eq = eq;
+  }
+
+  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+    const par = this.parents[0];
+
+    const sn = par.getSnapshot();
+
+    if (par.updaterSymbol !== updaterSymbol || Optional.isNone(sn)) {
+      return; // skip update
+    }
+
+    const prev = this.#mut_previousValue;
+
+    const cond = Optional.isNone(prev) || !this.#eq(prev.value, sn.value);
+
+    // NOTE: Must update before setNext, otherwise Optional.isNone(prev) remains true when tryUpdate is called consecutively
+    this.#mut_previousValue = sn;
+
+    if (cond) {
+      this.setNext(sn.value, updaterSymbol);
+    }
+  }
+}

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

@@ -0,0 +1,54 @@
+import { Optional } from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import {
+  type DropInitialValueOperator,
+  type Observable,
+  type SkipUntilOperatorObservable,
+  type UpdaterSymbol,
+} from '../types/index.mjs';
+
+export const skipUntil =
+  <A,>(notifier: Observable<unknown>): DropInitialValueOperator<A, A> =>
+  (parentObservable) =>
+    new SkipUntilObservableClass(parentObservable, notifier);
+
+class SkipUntilObservableClass<A>
+  extends SyncChildObservableClass<A, readonly [A]>
+  implements SkipUntilOperatorObservable<A>
+{
+  #mut_isSkipping: boolean;
+
+  constructor(parentObservable: Observable<A>, notifier: Observable<unknown>) {
+    super({
+      parents: [parentObservable],
+      initialValue: Optional.none,
+    });
+
+    this.#mut_isSkipping = true;
+
+    notifier.subscribe(
+      () => {
+        this.#mut_isSkipping = false;
+      },
+      () => {
+        this.#mut_isSkipping = false;
+      },
+    );
+  }
+
+  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+    const par = this.parents[0];
+
+    const sn = par.getSnapshot();
+
+    if (
+      par.updaterSymbol !== updaterSymbol ||
+      Optional.isNone(sn) ||
+      this.#mut_isSkipping
+    ) {
+      return; // skip update
+    }
+
+    this.setNext(sn.value, updaterSymbol);
+  }
+}

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

@@ -0,0 +1,77 @@
+import {
+  Optional,
+  PositiveSafeInt,
+  SafeUint,
+  asSafeUint,
+  pipe,
+} from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import {
+  type DropInitialValueOperator,
+  type Observable,
+  type SkipWhileOperatorObservable,
+  type UpdaterSymbol,
+} from '../types/index.mjs';
+
+export const skipWhile =
+  <A,>(
+    predicate: (value: A, index: SafeUint | -1) => boolean,
+  ): DropInitialValueOperator<A, A> =>
+  (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>
+  extends SyncChildObservableClass<A, readonly [A]>
+  implements SkipWhileOperatorObservable<A>
+{
+  readonly #predicate: (value: A, index: SafeUint | -1) => boolean;
+  #mut_index: SafeUint | -1;
+
+  constructor(
+    parentObservable: Observable<A>,
+    predicate: (value: A, index: SafeUint | -1) => boolean,
+  ) {
+    super({
+      parents: [parentObservable],
+      initialValue: pipe(parentObservable.getSnapshot()).map((sn) =>
+        Optional.isNone(sn)
+          ? Optional.none
+          : predicate(sn.value, -1)
+            ? Optional.none
+            : sn,
+      ).value,
+    });
+
+    this.#mut_index = -1;
+
+    this.#predicate = predicate;
+  }
+
+  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+    const par = this.parents[0];
+
+    const sn = par.getSnapshot();
+
+    if (par.updaterSymbol !== updaterSymbol || Optional.isNone(sn)) {
+      return; // skip update
+    }
+
+    this.#mut_index =
+      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);
+    }
+  }
+}