synstate 0.1.0

package/src/core/create/interval.mts

@@ -0,0 +1,99 @@
+import { asSafeUint, Optional, SafeUint } from 'ts-data-forge';
+import { RootObservableClass } from '../class/index.mjs';
+import { type IntervalObservable } from '../types/index.mjs';
+
+/**
+ * Creates an observable that emits incremental numbers at a specified interval.
+ * Starts with 0 immediately after subscription, then emits 1, 2, 3, ... every interval.
+ *
+ * @param milliSeconds - The interval duration in milliseconds
+ * @param startManually - If true, waits for manual start (default: false)
+ * @returns An observable that emits sequential numbers
+ *
+ * @example
+ * ```ts
+ * const tick$ = interval(1000);
+ *
+ * tick$.subscribe((count) => {
+ *   console.log(count);
+ * });
+ * // logs: 0, 1, 2, 3, ... every second
+ * ```
+ */
+export const interval = (
+  milliSeconds: number,
+  startManually?: boolean,
+): IntervalObservable =>
+  new IntervalObservableClass(milliSeconds, startManually);
+
+class IntervalObservableClass
+  extends RootObservableClass<SafeUint>
+  implements IntervalObservable
+{
+  readonly #milliSeconds: number;
+  #mut_counter: SafeUint;
+  #mut_timerId0: TimerId | undefined;
+  #mut_timerId: TimerId | undefined;
+  #mut_isStarted: boolean;
+
+  constructor(milliSeconds: number, startManually?: boolean) {
+    super({ initialValue: Optional.none });
+
+    this.#milliSeconds = milliSeconds;
+
+    this.#mut_counter = asSafeUint(0);
+
+    this.#mut_timerId0 = undefined;
+
+    this.#mut_timerId = undefined;
+
+    this.#mut_isStarted = false;
+
+    if (startManually !== true) {
+      this.start();
+    }
+  }
+
+  start(): this {
+    if (this.#mut_isStarted) {
+      console.warn('cannot start twice');
+
+      return this;
+    }
+
+    this.#mut_isStarted = true;
+
+    if (this.isCompleted) {
+      console.warn('cannot restart stopped IntervalObservable');
+
+      return this;
+    }
+
+    // emit zero
+    this.#mut_timerId0 = setTimeout(() => {
+      this.startUpdate(this.#mut_counter);
+    }, 0);
+
+    this.#mut_timerId = setInterval(() => {
+      this.#mut_counter = SafeUint.add(1, this.#mut_counter);
+
+      this.startUpdate(this.#mut_counter);
+    }, this.#milliSeconds);
+
+    return this;
+  }
+
+  #resetTimer(): void {
+    if (this.#mut_timerId0 !== undefined && this.#mut_timerId !== undefined) {
+      clearInterval(this.#mut_timerId0);
+
+      clearInterval(this.#mut_timerId);
+    }
+  }
+
+  override complete(): void {
+    this.#resetTimer();
+
+    super.complete();
+  }
+}

package/src/core/create/of.mts

@@ -0,0 +1,54 @@
+import { Optional } from 'ts-data-forge';
+import { RootObservableClass } from '../class/index.mjs';
+import { type OfObservable } from '../types/index.mjs';
+
+/**
+ * Creates an observable that emits a single value and then completes.
+ *
+ * @template A - The type of the value
+ * @param value - The value to emit
+ * @param startManually - If true, waits for manual start (default: false)
+ * @returns An observable that emits the value
+ *
+ * @example
+ * ```ts
+ * const num$ = of(42);
+ *
+ * num$.subscribe((x) => {
+ *   console.log(x);
+ * }); // logs: 42
+ * ```
+ */
+export const of = <A,>(
+  value: A,
+  startManually: boolean = false,
+): OfObservable<A> => new OfObservableClass<A>(value, startManually);
+
+class OfObservableClass<A>
+  extends RootObservableClass<A>
+  implements OfObservable<A>
+{
+  readonly #value: A;
+
+  constructor(value: A, startManually: boolean = false) {
+    super({ initialValue: Optional.none });
+
+    this.#value = value;
+
+    if (!startManually) {
+      setTimeout(() => {
+        this.emit();
+      }, 0);
+    }
+  }
+
+  emit(): this {
+    if (this.isCompleted) return this;
+
+    this.startUpdate(this.#value);
+
+    this.complete();
+
+    return this;
+  }
+}

package/src/core/create/source.mts

@@ -0,0 +1,59 @@
+import { Arr, Optional } from 'ts-data-forge';
+import { RootObservableClass } from '../class/index.mjs';
+import {
+  type InitializedSourceObservable,
+  type SourceObservable,
+} from '../types/index.mjs';
+
+/**
+ * Creates a new Observable source that can manually emit values.
+ * This is the primary way to create root observables that start reactive chains.
+ *
+ * @template A - The type of values emitted by the source
+ * @returns A SourceObservable that can emit values via `.next()` method
+ *
+ * @example
+ * ```ts
+ * const count$ = source<number>();
+ *
+ * count$.subscribe((value) => {
+ *   console.log(value);
+ * });
+ *
+ * count$.next(1); // logs: 1
+ *
+ * count$.next(2); // logs: 2
+ * ```
+ */
+export function source<A>(initialValue: A): InitializedSourceObservable<A>;
+
+export function source<A>(): SourceObservable<A>;
+
+export function source<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; // alias
+
+class SourceObservableClass<A>
+  extends RootObservableClass<A>
+  implements SourceObservable<A>
+{
+  constructor(...args: readonly A[]) {
+    super({
+      initialValue: Arr.isNonEmpty(args)
+        ? Optional.some(args[0])
+        : Optional.none,
+    });
+  }
+
+  next(nextValue: A): void {
+    if (this.isCompleted) return;
+
+    this.startUpdate(nextValue);
+  }
+}

package/src/core/create/timer.mts

@@ -0,0 +1,84 @@
+import { Optional } from 'ts-data-forge';
+import { RootObservableClass } from '../class/index.mjs';
+import { type TimerObservable } from '../types/index.mjs';
+
+/**
+ * Creates an observable that emits 0 after a specified delay and then completes.
+ *
+ * @param milliSeconds - The delay in milliseconds before emission
+ * @param startManually - If true, waits for manual start (default: false)
+ * @returns An observable that emits after delay
+ *
+ * @example
+ * ```ts
+ * const delayed$ = timer(1000);
+ *
+ * delayed$.subscribe(() => {
+ *   console.log('1 second passed');
+ * });
+ * // After 1 second, logs: 1 second passed
+ * ```
+ */
+export const timer = (
+  milliSeconds: number,
+  startManually: boolean = false,
+): TimerObservable => new TimerObservableClass(milliSeconds, startManually);
+
+class TimerObservableClass
+  extends RootObservableClass<0>
+  implements TimerObservable
+{
+  readonly #milliSeconds: number;
+  #mut_timerId: TimerId | undefined;
+  #mut_isStarted: boolean;
+
+  constructor(milliSeconds: number, startManually: boolean) {
+    super({ initialValue: Optional.none });
+
+    this.#milliSeconds = milliSeconds;
+
+    this.#mut_timerId = undefined;
+
+    this.#mut_isStarted = false;
+
+    if (!startManually) {
+      this.start();
+    }
+  }
+
+  start(): this {
+    if (this.#mut_isStarted) {
+      console.warn('cannot start twice');
+
+      return this;
+    }
+
+    this.#mut_isStarted = true;
+
+    if (this.isCompleted) {
+      console.warn('cannot restart stopped TimerObservable');
+
+      return this;
+    }
+
+    this.#mut_timerId = setTimeout(() => {
+      this.startUpdate(0);
+
+      this.complete();
+    }, this.#milliSeconds);
+
+    return this;
+  }
+
+  #resetTimer(): void {
+    if (this.#mut_timerId !== undefined) {
+      clearTimeout(this.#mut_timerId);
+    }
+  }
+
+  override complete(): void {
+    this.#resetTimer();
+
+    super.complete();
+  }
+}

package/src/core/index.mts

@@ -0,0 +1,6 @@
+export * from './class/index.mjs';
+export * from './combine/index.mjs';
+export * from './create/index.mjs';
+export * from './operators/index.mjs';
+export * from './types/index.mjs';
+export * from './utils/index.mjs';

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

@@ -0,0 +1,77 @@
+import { Optional } from 'ts-data-forge';
+import { AsyncChildObservableClass } from '../class/index.mjs';
+import {
+  type AuditTimeOperatorObservable,
+  type KeepInitialValueOperator,
+  type Observable,
+  type UpdaterSymbol,
+} from '../types/index.mjs';
+
+export const auditTime = <A,>(
+  milliSeconds: number,
+): KeepInitialValueOperator<A, A> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  ((parentObservable) =>
+    new AuditTimeObservableClass(
+      parentObservable,
+      milliSeconds,
+    )) as KeepInitialValueOperator<A, A>;
+
+class AuditTimeObservableClass<A>
+  extends AsyncChildObservableClass<A, readonly [A]>
+  implements AuditTimeOperatorObservable<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(updaterSymbol: UpdaterSymbol): void {
+    const par = this.parents[0];
+
+    if (
+      par.updaterSymbol !== updaterSymbol ||
+      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-time.mts

@@ -0,0 +1,96 @@
+import { Optional } from 'ts-data-forge';
+import { AsyncChildObservableClass } from '../class/index.mjs';
+import {
+  type DebounceTimeOperatorObservable,
+  type KeepInitialValueOperator,
+  type Observable,
+  type UpdaterSymbol,
+} 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
+ * const input$ = source<string>();
+ *
+ * const debounced$ = input$.pipe(debounceTime(300));
+ *
+ * debounced$.subscribe((value) => {
+ *   console.log(value);
+ * });
+ *
+ * input$.next('h');
+ *
+ * input$.next('he');
+ *
+ * input$.next('hel');
+ *
+ * input$.next('hello');
+ * // After 300ms of silence, logs: hello
+ * ```
+ */
+export const debounceTime = <A,>(
+  milliSeconds: number,
+): KeepInitialValueOperator<A, A> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  ((parentObservable) =>
+    new DebounceTimeObservableClass(
+      parentObservable,
+      milliSeconds,
+    )) as KeepInitialValueOperator<A, A>;
+
+class DebounceTimeObservableClass<A>
+  extends AsyncChildObservableClass<A, readonly [A]>
+  implements DebounceTimeOperatorObservable<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(updaterSymbol: UpdaterSymbol): void {
+    const par = this.parents[0];
+
+    const sn = par.getSnapshot();
+
+    if (par.updaterSymbol !== updaterSymbol || 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

@@ -0,0 +1,125 @@
+import {
+  asSafeUint,
+  expectType,
+  Optional,
+  pipe,
+  SafeUint,
+} from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import { source } from '../create/index.mjs';
+import {
+  type DropInitialValueOperator,
+  type FilterOperatorObservable,
+  type InitializedObservable,
+  type Observable,
+  type UpdaterSymbol,
+} from '../types/index.mjs';
+import { withInitialValue } from './with-initial-value.mjs';
+
+/**
+ * Filters values emitted by the source observable based on a predicate function.
+ * Only values that satisfy the predicate will be emitted by the resulting observable.
+ *
+ * @template A - The type of values from the source
+ * @template B - The narrowed type when using type guard
+ * @param predicate - A function that tests each value (receives value and index)
+ * @returns An operator that filters the observable
+ *
+ * @example
+ * ```ts
+ * const num$ = source<number>();
+ *
+ * const even$ = num$.pipe(filter((x) => x % 2 === 0));
+ *
+ * even$.subscribe((x) => {
+ *   console.log(x);
+ * });
+ *
+ * num$.next(1); // nothing logged
+ *
+ * num$.next(2); // logs: 2
+ * ```
+ */
+export function filter<A, B extends A>(
+  predicate: (value: A, index: SafeUint | -1) => value is B,
+): DropInitialValueOperator<A, B>;
+
+export function filter<A>(
+  predicate: (value: A, index: SafeUint | -1) => boolean,
+): DropInitialValueOperator<A, A>;
+
+export function filter<A>(
+  predicate: (value: A, index: SafeUint | -1) => boolean,
+): DropInitialValueOperator<A, A> {
+  return (parentObservable) =>
+    new FilterObservableClass(parentObservable, predicate);
+}
+
+class FilterObservableClass<A>
+  extends SyncChildObservableClass<A, readonly [A]>
+  implements FilterOperatorObservable<A>
+{
+  readonly #predicate: (x: A, index: SafeUint | -1) => boolean;
+  #mut_index: SafeUint | -1;
+
+  constructor(
+    parentObservable: Observable<A>,
+    predicate: (x: A, index: SafeUint | -1) => boolean,
+  ) {
+    super({
+      parents: [parentObservable],
+      initialValue: pipe(parentObservable.getSnapshot()).map((sn) =>
+        Optional.isNone(sn)
+          ? Optional.none
+          : predicate(sn.value, -1)
+            ? sn
+            : 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);
+    }
+  }
+}
+
+if (import.meta.vitest !== undefined) {
+  test('type test', () => {
+    expect(1).toBe(1); // dummy
+  });
+
+  {
+    const s: Observable<number> = source<number>();
+
+    const _d1 = s.pipe(filter((x) => x % 2 === 0));
+
+    expectType<typeof _d1, Observable<number>>('=');
+  }
+
+  {
+    const s = source<number>();
+
+    const m: InitializedObservable<number> = s.pipe(withInitialValue(0));
+
+    const _d = m.pipe(filter((x) => x % 2 === 0));
+
+    expectType<typeof _d, Observable<number>>('=');
+  }
+}

package/src/core/operators/index.mts

@@ -0,0 +1,17 @@
+export * from './audit-time.mjs';
+export * from './debounce-time.mjs';
+export * from './filter.mjs';
+export * from './map-with-index.mjs';
+export * from './merge-map.mjs';
+export * from './pairwise.mjs';
+export * from './scan.mjs';
+export * from './skip-if-no-change.mjs';
+export * from './skip-until.mjs';
+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 './with-buffered-from.mjs';
+export * from './with-current-value-from.mjs';
+export * from './with-initial-value.mjs';