synstate 0.1.0

package/src/core/class/observable.class.test.mts

@@ -0,0 +1,89 @@
+import { expectType, Optional } from 'ts-data-forge';
+import {
+  type AsyncChildObservable,
+  type ChildObservable,
+  type Observable,
+  type ObservableBase,
+  type RootObservable,
+  type SyncChildObservable,
+} from '../types/index.mjs';
+import {
+  AsyncChildObservableClass,
+  SyncChildObservableClass,
+} from './child-observable-class.mjs';
+import { RootObservableClass } from './root-observable-class.mjs';
+
+/**
+ * Inheritance
+ *
+ * ```txt
+ * ObservableBase
+ *   |
+ *   +- SyncChildObservable    \                       \
+ *   |                          +-- ChildObservable     \
+ *   +- AsyncChildObservable   X                         +-- Observable
+ *   |                          +-- ManagerObservable   /
+ *   +- RootObservableType     /                       /
+ * ```
+ */
+
+// type tests
+
+expectType<Observable<number>, Observable<number>>('=');
+
+expectType<Observable<string>, Observable<number>>('!<=');
+
+// inheritance
+expectType<ChildObservable<number>, ObservableBase<number>>('<=');
+
+expectType<SyncChildObservable<number>, ChildObservable<number>>('<=');
+
+expectType<AsyncChildObservable<number>, ChildObservable<number>>('<=');
+
+expectType<RootObservable<number>, ObservableBase<number>>('<=');
+
+expectType<SyncChildObservable<number>, ChildObservable<number>>('<=');
+
+expectType<Observable<number>, ObservableBase<number>>('<=');
+
+expectType<ObservableBase<number>, Observable<number>>('!<=');
+
+expectType<ChildObservable<number>, Observable<number>>('<=');
+
+// ObservableBase is covariant
+expectType<ObservableBase<1>, ObservableBase<number>>('<=');
+
+expectType<ObservableBase<number>, ObservableBase<1>>('!<=');
+
+// Observable is covariant
+expectType<Observable<1>, Observable<number>>('<=');
+
+expectType<Observable<number>, Observable<1>>('!<=');
+
+const root = new RootObservableClass({
+  initialValue: Optional.some(0),
+});
+
+expectType<typeof root, RootObservable<number>>('<=');
+
+const syncChild = new SyncChildObservableClass({
+  parents: [root],
+  initialValue: Optional.some(0),
+});
+
+expectType<typeof syncChild, SyncChildObservable<number>>('<=');
+
+const asyncChild = new AsyncChildObservableClass({
+  parents: [root],
+  initialValue: Optional.some(0),
+});
+
+expectType<typeof asyncChild, AsyncChildObservable<number>>('<=');
+
+test('SyncChildObservableClass', () => {
+  expect(syncChild.depth).toBe(1);
+});
+
+test('AsyncChildObservableClass', () => {
+  expect(asyncChild.depth).toBe(1);
+});

package/src/core/class/root-observable-class.mts

@@ -0,0 +1,68 @@
+import { Arr, Optional } from 'ts-data-forge';
+import {
+  isRootObservable,
+  type ChildObservable,
+  type ObservableId,
+  type RootObservable,
+} from '../types/index.mjs';
+import { binarySearch, issueUpdaterSymbol } from '../utils/index.mjs';
+import { ObservableBaseClass } from './observable-base-class.mjs';
+
+export class RootObservableClass<A>
+  extends ObservableBaseClass<A, 'root', 0>
+  implements RootObservable<A>
+{
+  #mut_procedure: readonly ChildObservable<unknown>[];
+  protected readonly _descendantsIdSet: MutableSet<ObservableId>;
+
+  constructor({
+    initialValue,
+  }: Readonly<{
+    initialValue: ReturnType<RootObservable<A>['getSnapshot']>;
+  }>) {
+    super({
+      kind: 'root',
+      depth: 0,
+      initialValue,
+    });
+
+    this.#mut_procedure = [];
+
+    this._descendantsIdSet = new Set<ObservableId>();
+  }
+
+  addDescendant<B>(child: ChildObservable<B>): void {
+    if (this._descendantsIdSet.has(child.id)) return;
+
+    this._descendantsIdSet.add(child.id);
+
+    const insertPos = binarySearch(
+      this.#mut_procedure.map((a) => a.depth),
+      child.depth,
+    );
+
+    this.#mut_procedure = Arr.toInserted(this.#mut_procedure, insertPos, child);
+  }
+
+  startUpdate(nextValue: A): void {
+    const updaterSymbol = issueUpdaterSymbol();
+
+    this.setNext(nextValue, updaterSymbol);
+
+    for (const p of this.#mut_procedure) {
+      p.tryUpdate(updaterSymbol);
+    }
+  }
+}
+
+if (import.meta.vitest !== undefined) {
+  test('isRootObservable', () => {
+    assert.isTrue(
+      isRootObservable(
+        new RootObservableClass({
+          initialValue: Optional.some(0),
+        }),
+      ),
+    );
+  });
+}

package/src/core/combine/combine.mts

@@ -0,0 +1,144 @@
+import { Arr, Optional, expectType } from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import { fromArray, source } from '../create/index.mjs';
+import { withInitialValue } from '../operators/index.mjs';
+import {
+  type CombineObservable,
+  type CombineObservableRefined,
+  type InitializedObservable,
+  type InitializedSyncChildObservable,
+  type NonEmptyUnknownList,
+  type Observable,
+  type SyncChildObservable,
+  type UpdaterSymbol,
+  type Wrap,
+} from '../types/index.mjs';
+
+/**
+ * Combines multiple observables into a single observable that emits an array of their latest values.
+ * Emits whenever any of the source observables emit, but only after all sources have emitted at least once.
+ *
+ * @template OS - Tuple type of source observables
+ * @param parents - Array of observables to combine
+ * @returns A combined observable emitting tuples of values
+ *
+ * @example
+ * ```ts
+ * const name$ = source<string>();
+ *
+ * const age$ = source<number>();
+ *
+ * const user$ = combine([name$, age$]);
+ *
+ * user$.subscribe(([name_, age]) => {
+ *   console.log({ name: name_, age });
+ * });
+ *
+ * name$.next('Alice');
+ *
+ * age$.next(25); // logs: { name: 'Alice', age: 25 }
+ *
+ * name$.next('Bob'); // logs: { name: 'Bob', age: 25 }
+ * ```
+ */
+export const combine = <const OS extends NonEmptyArray<Observable<unknown>>>(
+  parents: OS,
+): CombineObservableRefined<OS> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  new CombineObservableClass(
+    parents,
+  ) as unknown as CombineObservableRefined<OS>;
+
+/**
+ * Alias for `combine()`.
+ * @see combine
+ */
+export const combineLatest = combine; // alias
+
+class CombineObservableClass<const A extends NonEmptyUnknownList>
+  extends SyncChildObservableClass<A, A>
+  implements CombineObservable<A>
+{
+  constructor(parents: Wrap<A>) {
+    const parentsValues = parents.map((p) => p.getSnapshot());
+
+    super({
+      parents,
+      initialValue: parentsValues.every(Optional.isSome)
+        ? Optional.some(
+            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+            Arr.map(parentsValues, (c) => c.value) as A,
+          )
+        : Optional.none,
+    });
+  }
+
+  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+    if (this.parents.every((o) => o.updaterSymbol !== updaterSymbol)) return; // all parents are skipped
+
+    const parentValues = this.parents.map((a) => a.getSnapshot());
+
+    if (parentValues.every(Optional.isSome)) {
+      const nextValue =
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        Arr.map(parentValues, (a) => a.value) as A;
+
+      this.setNext(nextValue, updaterSymbol);
+    }
+  }
+}
+
+{
+  {
+    const s1: Observable<1> = source<1>();
+
+    const s2: Observable<2> = source<2>();
+
+    const _d = combine([s1, s2]);
+
+    expectType<typeof _d, CombineObservable<readonly [1, 2]>>('=');
+
+    expectType<typeof _d, Observable<readonly [1, 2]>>('<=');
+  }
+
+  {
+    const s1: InitializedObservable<1> = source<1>().pipe(withInitialValue(1));
+
+    const s2: Observable<2> = source<2>();
+
+    const _d = combine([s1, s2]);
+
+    expectType<typeof _d, CombineObservable<readonly [1, 2]>>('=');
+
+    expectType<typeof _d, Observable<readonly [1, 2]>>('<=');
+  }
+
+  {
+    const s1: InitializedObservable<1> = source<1>().pipe(withInitialValue(1));
+
+    const s2: InitializedObservable<2> = source<2>().pipe(withInitialValue(2));
+
+    const _d = combine([s1, s2]);
+
+    // Returns InitializedObservable if all OS are InitializedObservable
+    expectType<typeof _d, InitializedObservable<readonly [1, 2]>>('<=');
+  }
+
+  const r1 = fromArray([1, 2, 3]);
+
+  const r2 = fromArray(['a', 'b', 'c']);
+
+  const _c = combine([r1, r2]);
+
+  const _ci = combine([
+    r1.pipe(withInitialValue(0)),
+    r2.pipe(withInitialValue(0)),
+  ]);
+
+  expectType<typeof _c, SyncChildObservable<readonly [number, string]>>('<=');
+
+  expectType<
+    typeof _ci,
+    InitializedSyncChildObservable<readonly [number, number | string]>
+  >('<=');
+}

package/src/core/combine/index.mts

@@ -0,0 +1,3 @@
+export * from './combine.mjs';
+export * from './merge.mjs';
+export * from './zip.mjs';

package/src/core/combine/merge.mts

@@ -0,0 +1,84 @@
+import { Optional, expectType } from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import { fromArray } from '../create/index.mjs';
+import {
+  type MergeObservable,
+  type MergeObservableRefined,
+  type NonEmptyUnknownList,
+  type Observable,
+  type SyncChildObservable,
+  type UpdaterSymbol,
+  type Wrap,
+} from '../types/index.mjs';
+
+/**
+ * Merges multiple observables into a single observable that emits all values from all sources.
+ * Emits whenever any source observable emits a value.
+ *
+ * @template OS - Tuple type of source observables
+ * @param parents - Array of observables to merge
+ * @returns A merged observable emitting values from any source
+ *
+ * @example
+ * ```ts
+ * const clicks$ = source<MouseEvent>();
+ *
+ * const keys$ = source<KeyboardEvent>();
+ *
+ * const events$ = merge([clicks$, keys$]);
+ *
+ * events$.subscribe((event_) => {
+ *   console.log(event_);
+ * });
+ * // Logs any mouse click or keyboard event
+ * ```
+ *
+ * @note To improve code readability, consider using `createState` instead of `merge`,
+ * subscribing to `parents` and calling `setState` within it.
+ */
+export const merge = <const OS extends NonEmptyArray<Observable<unknown>>>(
+  parents: OS,
+): MergeObservableRefined<OS> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  new MergeObservableClass(parents) as MergeObservableRefined<OS>;
+
+class MergeObservableClass<const P extends NonEmptyUnknownList>
+  extends SyncChildObservableClass<ArrayElement<P>, P>
+  implements MergeObservable<P>
+{
+  constructor(parents: Wrap<P>) {
+    super({
+      parents,
+      initialValue: Optional.none,
+    });
+  }
+
+  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+    const parentToUse = this.parents.find(
+      (o) =>
+        o.updaterSymbol === updaterSymbol && Optional.isSome(o.getSnapshot()),
+    );
+
+    if (parentToUse === undefined) return;
+
+    const nextValue =
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      Optional.unwrap(parentToUse.getSnapshot()) as ArrayElement<P>;
+
+    this.setNext(nextValue, updaterSymbol);
+  }
+}
+
+if (import.meta.vitest !== undefined) {
+  test('type test', () => {
+    expect(1).toBe(1); // dummy
+  });
+
+  const r1 = fromArray([1, 2, 3]);
+
+  const r2 = fromArray(['a', 'b', 'c']);
+
+  const _m = merge([r1, r2] as const);
+
+  expectType<typeof _m, SyncChildObservable<number | string>>('<=');
+}

package/src/core/combine/zip.mts

@@ -0,0 +1,149 @@
+import { Arr, Optional, createQueue, expectType } from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import { fromArray, source } from '../create/index.mjs';
+import { withInitialValue } from '../operators/index.mjs';
+import {
+  type InitializedObservable,
+  type InitializedSyncChildObservable,
+  type NonEmptyUnknownList,
+  type Observable,
+  type SyncChildObservable,
+  type TupleToQueueTuple,
+  type UpdaterSymbol,
+  type Wrap,
+  type ZipObservable,
+  type ZipObservableRefined,
+} from '../types/index.mjs';
+
+/**
+ * Combines multiple observables by pairing their emissions by index.
+ * Waits for all sources to emit their nth value before emitting the nth tuple.
+ * Completes when any source completes.
+ *
+ * @template OS - Tuple type of source observables
+ * @param parents - Array of observables to zip
+ * @returns A zipped observable emitting tuples of values
+ *
+ * @example
+ * ```ts
+ * const letters$ = fromArray(['a', 'b', 'c']);
+ *
+ * const numbers$ = fromArray([1, 2, 3]);
+ *
+ * const zipped$ = zip([letters$, numbers$]);
+ *
+ * zipped$.subscribe(([letter, num]) => {
+ *   console.log(letter, num);
+ * });
+ * // logs: a 1, b 2, c 3
+ * ```
+ */
+export const zip = <const OS extends NonEmptyArray<Observable<unknown>>>(
+  parents: OS,
+): ZipObservableRefined<OS> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  new ZipObservableClass(parents) as unknown as ZipObservableRefined<OS>;
+
+class ZipObservableClass<const A extends NonEmptyUnknownList>
+  extends SyncChildObservableClass<A, A>
+  implements ZipObservable<A>
+{
+  readonly #queues: TupleToQueueTuple<A>;
+
+  constructor(parents: Wrap<A>) {
+    const parentsValues = parents.map((p) => p.getSnapshot());
+
+    super({
+      parents,
+      initialValue: parentsValues.every(Optional.isSome)
+        ? Optional.some(
+            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+            Arr.map(parentsValues, (c) => c.value) as A,
+          )
+        : Optional.none,
+    });
+
+    this.#queues = Arr.map(parents, () =>
+      createQueue(),
+    ) satisfies TupleToQueueTuple<A>;
+  }
+
+  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+    const queues = this.#queues;
+
+    for (const [index, par] of this.parents.entries()) {
+      const sn = par.getSnapshot();
+
+      if (par.updaterSymbol === updaterSymbol && Optional.isSome(sn)) {
+        queues[index]?.enqueue(sn.value);
+      }
+    }
+
+    if (queues.every((list) => !list.isEmpty)) {
+      const nextValue =
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        Arr.map(queues, (q) => Optional.unwrap(q.dequeue())) as A;
+
+      this.setNext(nextValue, updaterSymbol);
+    }
+  }
+}
+
+if (import.meta.vitest !== undefined) {
+  test('type test', () => {
+    expect(1).toBe(1); // dummy
+  });
+
+  {
+    const s1: Observable<1> = source<1>();
+
+    const s2: Observable<2> = source<2>();
+
+    const _d = zip([s1, s2]);
+
+    expectType<typeof _d, ZipObservable<readonly [1, 2]>>('=');
+
+    expectType<typeof _d, Observable<readonly [1, 2]>>('<=');
+  }
+
+  {
+    const s1: InitializedObservable<1> = source<1>().pipe(withInitialValue(1));
+
+    const s2: Observable<2> = source<2>();
+
+    const _d = zip([s1, s2]);
+
+    expectType<typeof _d, ZipObservable<readonly [1, 2]>>('=');
+
+    expectType<typeof _d, Observable<readonly [1, 2]>>('<=');
+  }
+
+  {
+    const s1: InitializedObservable<1> = source<1>().pipe(withInitialValue(1));
+
+    const s2: InitializedObservable<2> = source<2>().pipe(withInitialValue(2));
+
+    const _d = zip([s1, s2]);
+
+    // Returns InitializedObservable if all OS are InitializedObservable
+    expectType<typeof _d, InitializedObservable<readonly [1, 2]>>('<=');
+  }
+
+  const r1 = fromArray([1, 2, 3]);
+
+  const r2 = fromArray(['a', 'b', 'c']);
+
+  const _z = zip([r1, r2] as const);
+
+  const _zi = zip([
+    r1.pipe(withInitialValue(0)),
+    r2.pipe(withInitialValue('0')),
+  ] as const);
+
+  expectType<typeof _z, SyncChildObservable<readonly [number, string]>>('<=');
+
+  expectType<
+    typeof _zi,
+    InitializedSyncChildObservable<readonly [number, string]>
+  >('<=');
+}

package/src/core/create/from-array.mts

@@ -0,0 +1,58 @@
+import { Optional } from 'ts-data-forge';
+import { RootObservableClass } from '../class/index.mjs';
+import { type FromArrayObservable } from '../types/index.mjs';
+
+/**
+ * Creates an observable that emits all values from an array sequentially, then completes.
+ *
+ * @template A - The type of array elements
+ * @param values - The array of values to emit
+ * @param startManually - If true, waits for manual start (default: false)
+ * @returns An observable that emits array values
+ *
+ * @example
+ * ```ts
+ * const nums$ = fromArray([1, 2, 3]);
+ *
+ * nums$.subscribe((x) => {
+ *   console.log(x);
+ * });
+ * // logs: 1, 2, 3
+ * ```
+ */
+export const fromArray = <A,>(
+  values: readonly A[],
+  startManually: boolean = false,
+): FromArrayObservable<A> =>
+  new FromArrayObservableClass<A>(values, startManually);
+
+class FromArrayObservableClass<A>
+  extends RootObservableClass<A>
+  implements FromArrayObservable<A>
+{
+  readonly #values: readonly A[];
+
+  constructor(values: readonly A[], startManually: boolean = false) {
+    super({ initialValue: Optional.none });
+
+    this.#values = values;
+
+    if (!startManually) {
+      setTimeout(() => {
+        this.emit();
+      }, 0);
+    }
+  }
+
+  emit(): this {
+    if (this.isCompleted) return this;
+
+    for (const v of this.#values) {
+      this.startUpdate(v);
+    }
+
+    this.complete();
+
+    return this;
+  }
+}

package/src/core/create/from-promise.mts

@@ -0,0 +1,58 @@
+import { Optional, Result } from 'ts-data-forge';
+import { RootObservableClass } from '../class/index.mjs';
+import { type FromPromiseObservable } from '../types/index.mjs';
+
+/**
+ * Creates an observable from a Promise.
+ * Emits Result.ok when the promise resolves, or Result.err when it rejects.
+ *
+ * @template A - The type of the resolved value
+ * @template E - The type of the error
+ * @param promise - The promise to convert to observable
+ * @returns An observable that emits the promise result
+ *
+ * @example
+ * ```ts
+ * const data$ = fromPromise(fetch('/api/data').then((r) => r.json()));
+ *
+ * data$.subscribe((result) => {
+ *   if (Result.isOk(result)) {
+ *     console.log('Data:', result.value);
+ *   } else {
+ *     console.error('Error:', result.value);
+ *   }
+ * });
+ * ```
+ */
+export const fromPromise = <A, E = unknown>(
+  promise: Readonly<Promise<A>>,
+): FromPromiseObservable<A, E> => new FromPromiseObservableClass(promise);
+
+class FromPromiseObservableClass<A, E = unknown>
+  extends RootObservableClass<Result<A, E>>
+  implements FromPromiseObservable<A, E>
+{
+  constructor(promise: Readonly<Promise<A>>) {
+    super({ initialValue: Optional.none });
+
+    promise
+      .then((value) => {
+        if (this.isCompleted) return;
+
+        this.startUpdate(Result.ok(value));
+      })
+      .catch((error: unknown) => {
+        if (this.isCompleted) return;
+
+        this.startUpdate(
+          Result.err(
+            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+            error as E,
+          ),
+        );
+      })
+      .finally(() => {
+        this.complete();
+      });
+  }
+}

package/src/core/create/from-subscribable.mts

@@ -0,0 +1,37 @@
+import { Optional, Result } from 'ts-data-forge';
+import { RootObservableClass } from '../class/index.mjs';
+import {
+  type FromSubscribableObservable,
+  type Subscribable,
+} from '../types/index.mjs';
+
+export const fromSubscribable = <A, E = unknown>(
+  subscribable: Subscribable<A>,
+): FromSubscribableObservable<A, E> =>
+  new FromSubscribableObservableClass(subscribable);
+
+class FromSubscribableObservableClass<A, E = unknown>
+  extends RootObservableClass<Result<A, E>>
+  implements FromSubscribableObservable<A, E>
+{
+  constructor(subscribable: Subscribable<A>) {
+    super({ initialValue: Optional.none });
+
+    subscribable.subscribe(
+      (nextValue) => {
+        this.startUpdate(Result.ok(nextValue));
+      },
+      (error?: unknown) => {
+        this.startUpdate(
+          Result.err(
+            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+            error as E,
+          ),
+        );
+      },
+      () => {
+        this.complete();
+      },
+    );
+  }
+}

package/src/core/create/index.mts

@@ -0,0 +1,7 @@
+export * from './from-array.mjs';
+export * from './from-promise.mjs';
+export * from './from-subscribable.mjs';
+export * from './interval.mjs';
+export * from './of.mjs';
+export * from './source.mjs';
+export * from './timer.mjs';