synstate 0.1.0

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

@@ -0,0 +1,101 @@
+import { Optional } from 'ts-data-forge';
+import { AsyncChildObservableClass } from '../class/index.mjs';
+import {
+  type DropInitialValueOperator,
+  type Observable,
+  type Subscription,
+  type SwitchMapOperatorObservable,
+  type UpdaterSymbol,
+} from '../types/index.mjs';
+
+/**
+ * Projects each source value to an observable, subscribes to it, and emits its values.
+ * When a new value arrives from the source, the previous inner observable is unsubscribed.
+ *
+ * @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 switches to new observables
+ *
+ * @example
+ * ```ts
+ * const searchQuery$ = source<string>();
+ *
+ * const results$ = searchQuery$.pipe(
+ *   switchMap((query) => fromPromise(fetchResults(query))),
+ * );
+ *
+ * results$.subscribe((results) => {
+ *   console.log(results);
+ * });
+ * // Only the latest search results are emitted, previous searches are cancelled
+ *
+ * const fetchResults = async (_query: string): Promise<readonly unknown[]> => [];
+ * ```
+ *
+ * @note To improve code readability, consider using `createState` instead of `switchMap`,
+ * subscribe to `parentObservable` and call `setState` within it.
+ */
+export const switchMap =
+  <A, B>(
+    mapToObservable: (curr: A) => Observable<B>,
+  ): DropInitialValueOperator<A, B> =>
+  (parentObservable) =>
+    new SwitchMapObservableClass(parentObservable, mapToObservable);
+
+class SwitchMapObservableClass<A, B>
+  extends AsyncChildObservableClass<B, readonly [A]>
+  implements SwitchMapOperatorObservable<A, B>
+{
+  readonly #mapToObservable: (curr: A) => Observable<B>;
+  #mut_observable: Observable<B> | undefined;
+  #mut_subscription: Subscription | undefined;
+
+  constructor(
+    parentObservable: Observable<A>,
+    mapToObservable: (curr: A) => Observable<B>,
+  ) {
+    super({
+      parents: [parentObservable],
+      initialValue: Optional.none,
+    });
+
+    this.#mapToObservable = mapToObservable;
+
+    this.#mut_observable = undefined;
+
+    this.#mut_subscription = undefined;
+  }
+
+  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_observable?.complete();
+
+    this.#mut_subscription?.unsubscribe();
+
+    const observable = this.#mapToObservable(sn.value);
+
+    this.#mut_observable = observable;
+
+    const subscription = observable.subscribe((curr) => {
+      this.startUpdate(curr);
+    });
+
+    this.#mut_subscription = subscription;
+  }
+
+  override complete(): void {
+    this.#mut_subscription?.unsubscribe();
+
+    this.#mut_observable?.complete();
+
+    super.complete();
+  }
+}

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

@@ -0,0 +1,80 @@
+import { Optional } from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import {
+  type KeepInitialValueOperator,
+  type Observable,
+  type TakeUntilOperatorObservable,
+  type UpdaterSymbol,
+} from '../types/index.mjs';
+
+/**
+ * Emits values from the source until the notifier observable emits.
+ * When the notifier emits, this observable completes.
+ *
+ * @template A - The type of values from the source
+ * @param notifier - An observable that signals when to complete
+ * @returns An operator that takes values until notifier emits
+ *
+ * @example
+ * ```ts
+ * const num$ = source<number>();
+ *
+ * const [stopNotifier, stop_] = createEventEmitter();
+ *
+ * const limited$ = num$.pipe(takeUntil(stopNotifier));
+ *
+ * limited$.subscribe((x) => {
+ *   console.log(x);
+ * });
+ *
+ * num$.next(1); // logs: 1
+ *
+ * num$.next(2); // logs: 2
+ *
+ * stop_();
+ *
+ * num$.next(3); // nothing logged (completed)
+ * ```
+ */
+export const takeUntil = <A,>(
+  notifier: Observable<unknown>,
+): KeepInitialValueOperator<A, A> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  ((parentObservable) =>
+    new TakeUntilObservableClass(
+      parentObservable,
+      notifier,
+    )) as KeepInitialValueOperator<A, A>;
+
+class TakeUntilObservableClass<A>
+  extends SyncChildObservableClass<A, readonly [A]>
+  implements TakeUntilOperatorObservable<A>
+{
+  constructor(parentObservable: Observable<A>, notifier: Observable<unknown>) {
+    super({
+      parents: [parentObservable],
+      initialValue: parentObservable.getSnapshot(),
+    });
+
+    notifier.subscribe(
+      () => {
+        this.complete();
+      },
+      () => {
+        this.complete();
+      },
+    );
+  }
+
+  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.setNext(sn.value, updaterSymbol);
+  }
+}

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

@@ -0,0 +1,103 @@
+import {
+  Optional,
+  SafeUint,
+  asSafeUint,
+  expectType,
+  pipe,
+} from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import { source } from '../create/index.mjs';
+import {
+  type DropInitialValueOperator,
+  type InitializedObservable,
+  type Observable,
+  type TakeWhileOperatorObservable,
+  type UpdaterSymbol,
+} from '../types/index.mjs';
+import { withInitialValue } from './with-initial-value.mjs';
+
+export const takeWhile =
+  <A,>(
+    predicate: (value: A, index: SafeUint | -1) => boolean,
+  ): DropInitialValueOperator<A, A> =>
+  (parentObservable) =>
+    new TakeWhileObservableClass(parentObservable, predicate);
+
+/* Specialized operators */
+
+export const take = <A,>(
+  n: PositiveSafeIntWithSmallInt,
+): DropInitialValueOperator<A, A> => takeWhile((_, index) => index + 1 <= n);
+
+/* implementation */
+
+class TakeWhileObservableClass<A>
+  extends SyncChildObservableClass<A, readonly [A]>
+  implements TakeWhileOperatorObservable<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((par) =>
+        Optional.isNone(par)
+          ? Optional.none
+          : predicate(par.value, -1)
+            ? par
+            : Optional.none,
+      ).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);
+    } else {
+      this.complete();
+    }
+  }
+}
+
+if (import.meta.vitest !== undefined) {
+  test('type test', () => {
+    expect(1).toBe(1); // dummy
+  });
+
+  {
+    const s: Observable<number> = source<number>();
+
+    const _d1 = s.pipe(take(3));
+
+    expectType<typeof _d1, Observable<number>>('=');
+  }
+
+  {
+    const s = source<number>();
+
+    const m: InitializedObservable<number> = s.pipe(withInitialValue(0));
+
+    const _d = m.pipe(take(3));
+
+    expectType<typeof _d, Observable<number>>('=');
+  }
+}

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

@@ -0,0 +1,95 @@
+import { Optional } from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import {
+  type KeepInitialValueOperator,
+  type Observable,
+  type ThrottleTimeOperatorObservable,
+  type UpdaterSymbol,
+} from '../types/index.mjs';
+
+/**
+ * Emits the first value, then ignores subsequent values for a specified duration.
+ * After the duration, the next emission is allowed through.
+ *
+ * @template A - The type of values from the source
+ * @param milliSeconds - The throttle duration in milliseconds
+ * @returns An operator that throttles emissions
+ *
+ * @example
+ * ```ts
+ * const scroll$ = source<Event>();
+ *
+ * const throttled$ = scroll$.pipe(throttleTime(1000));
+ *
+ * throttled$.subscribe((event_) => {
+ *   console.log(event_);
+ * });
+ * // Emits at most once per second
+ * ```
+ */
+export const throttleTime = <A,>(
+  milliSeconds: number,
+): KeepInitialValueOperator<A, A> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  ((parentObservable) =>
+    new ThrottleTimeObservableClass(
+      parentObservable,
+      milliSeconds,
+    )) as KeepInitialValueOperator<A, A>;
+
+class ThrottleTimeObservableClass<A>
+  extends SyncChildObservableClass<A, readonly [A]>
+  implements ThrottleTimeOperatorObservable<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_timerId = undefined;
+
+    this.#mut_isSkipping = false;
+
+    this.#milliSeconds = milliSeconds;
+  }
+
+  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);
+
+    this.#mut_isSkipping = true;
+
+    // set timer
+    this.#mut_timerId = setTimeout(() => {
+      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/with-buffered-from.mts

@@ -0,0 +1,68 @@
+import { Arr, Optional, pipe } from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import {
+  type KeepInitialValueOperator,
+  type Observable,
+  type UpdaterSymbol,
+  type WithBufferedFromOperatorObservable,
+} from '../types/index.mjs';
+import { maxDepth } from '../utils/index.mjs';
+
+export const withBufferedFrom = <A, B>(
+  observable: Observable<B>,
+): KeepInitialValueOperator<A, readonly [A, readonly B[]]> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  ((parentObservable) =>
+    new WithBufferedFromObservableClass(
+      parentObservable,
+      observable,
+    )) as KeepInitialValueOperator<A, readonly [A, readonly B[]]>;
+
+export const withBuffered = withBufferedFrom; // alias
+
+class WithBufferedFromObservableClass<A, B>
+  extends SyncChildObservableClass<readonly [A, readonly B[]], readonly [A]>
+  implements WithBufferedFromOperatorObservable<A, B>
+{
+  #mut_bufferedValues: readonly B[] = [];
+
+  constructor(parentObservable: Observable<A>, observable: Observable<B>) {
+    super({
+      parents: [parentObservable],
+      depth: 1 + maxDepth([parentObservable, observable]),
+      initialValue: pipe({
+        par: parentObservable.getSnapshot(),
+        me: observable.getSnapshot(),
+      }).map(({ par, me }) =>
+        Optional.isNone(par)
+          ? Optional.none
+          : Optional.some([
+              par.value,
+              Optional.isNone(me) ? [] : [me.value],
+            ] as const),
+      ).value,
+    });
+
+    observable.subscribe((value) => {
+      this.#mut_bufferedValues = Arr.toPushed(this.#mut_bufferedValues, value);
+    });
+  }
+
+  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.setNext([sn.value, this.#mut_bufferedValues], updaterSymbol);
+
+    this.#clearBuffer();
+  }
+
+  #clearBuffer(): void {
+    this.#mut_bufferedValues = [];
+  }
+}

package/src/core/operators/with-current-value-from.mts

@@ -0,0 +1,58 @@
+import { Optional, pipe } from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import {
+  type DropInitialValueOperator,
+  type Observable,
+  type UpdaterSymbol,
+  type WithCurrentValueFromOperatorObservable,
+} from '../types/index.mjs';
+import { maxDepth } from '../utils/index.mjs';
+
+export const withCurrentValueFrom =
+  <A, B>(
+    observable: Observable<B>,
+  ): DropInitialValueOperator<A, readonly [A, B]> =>
+  (parentObservable) =>
+    new WithCurrentValueFromObservableClass(parentObservable, observable);
+
+export const withLatestFrom = withCurrentValueFrom; // alias
+
+class WithCurrentValueFromObservableClass<A, B>
+  extends SyncChildObservableClass<readonly [A, B], readonly [A]>
+  implements WithCurrentValueFromOperatorObservable<A, B>
+{
+  readonly #observable: Observable<B>;
+
+  constructor(parentObservable: Observable<A>, observable: Observable<B>) {
+    super({
+      parents: [parentObservable],
+      depth: 1 + maxDepth([parentObservable, observable]),
+      initialValue: pipe({
+        par: parentObservable.getSnapshot(),
+        me: observable.getSnapshot(),
+      }).map(({ me, par }) =>
+        Optional.isNone(par) || Optional.isNone(me)
+          ? Optional.none
+          : Optional.some([par.value, me.value] as const),
+      ).value,
+    });
+
+    this.#observable = observable;
+  }
+
+  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+    const par = this.parents[0];
+
+    const ps = par.getSnapshot();
+
+    if (par.updaterSymbol !== updaterSymbol || Optional.isNone(ps)) {
+      return; // skip update
+    }
+
+    const curr = this.#observable.getSnapshot();
+
+    if (Optional.isNone(curr)) return; // skip update
+
+    this.setNext([ps.value, curr.value], updaterSymbol);
+  }
+}

package/src/core/operators/with-initial-value.mts

@@ -0,0 +1,76 @@
+import { expectType, Optional } from 'ts-data-forge';
+import { InitializedSyncChildObservableClass } from '../class/index.mjs';
+import { source } from '../create/index.mjs';
+import {
+  type InitializedObservable,
+  type Observable,
+  type UpdaterSymbol,
+  type WithInitialValueOperator,
+  type WithInitialValueOperatorObservable,
+} from '../types/index.mjs';
+
+/**
+ * Provides an initial value for an observable that doesn't have one.
+ * The resulting observable will immediately emit the initial value upon subscription,
+ * and then emit all subsequent values from the source.
+ *
+ * @template A - The type of values from the source
+ * @template I - The type of the initial value (defaults to A)
+ * @param initialValue - The initial value to emit
+ * @returns An operator that sets the initial value
+ *
+ * @example
+ * ```ts
+ * const num$ = source<number>();
+ *
+ * const initialized$ = num$.pipe(withInitialValue(0));
+ *
+ * initialized$.subscribe((x) => {
+ *   console.log(x);
+ * }); // immediately logs: 0
+ *
+ * num$.next(1); // logs: 1
+ * ```
+ */
+export const withInitialValue =
+  <A, I = A>(initialValue: I): WithInitialValueOperator<A, A | I> =>
+  (parentObservable) =>
+    new WithInitialValueObservableClass(parentObservable, initialValue);
+
+class WithInitialValueObservableClass<A, I>
+  extends InitializedSyncChildObservableClass<A | I, readonly [A]>
+  implements WithInitialValueOperatorObservable<A, I>
+{
+  constructor(parentObservable: Observable<A>, initialValue: I) {
+    super({
+      parents: [parentObservable],
+      initialValue: Optional.some(initialValue),
+    });
+  }
+
+  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.setNext(sn.value, updaterSymbol);
+  }
+}
+
+if (import.meta.vitest !== undefined) {
+  test('type test', () => {
+    expect(1).toBe(1); // dummy
+  });
+
+  {
+    const s = source<number>();
+
+    const _d: InitializedObservable<number> = s.pipe(withInitialValue(0));
+
+    expectType<typeof _d, InitializedObservable<number>>('=');
+  }
+}

package/src/core/types/id.mts

@@ -0,0 +1,5 @@
+export type ObservableId = Brand<symbol, 'observable-id'>;
+
+export type SubscriberId = Brand<symbol, 'subscriber-id'>;
+
+export type UpdaterSymbol = Brand<symbol, 'updater-symbol'>;

package/src/core/types/index.mts

@@ -0,0 +1,5 @@
+export * from './id.mjs';
+export * from './observable-family.mjs';
+export * from './observable-kind.mjs';
+export * from './observable.mjs';
+export * from './types.mjs';