synstate 0.1.2 → 1.0.1

package/src/core/combine/combine.mts

@@ -1,6 +1,7 @@
 import { Arr, Optional, expectType } from 'ts-data-forge';
+import { type NonEmptyArray } from 'ts-type-forge';
 import { SyncChildObservableClass } from '../class/index.mjs';
-import { fromArray, source } from '../create/index.mjs';
+import { source } from '../create/index.mjs';
 import { withInitialValue } from '../operators/index.mjs';
 import {
   type CombineObservable,
@@ -10,7 +11,7 @@ import {
   type NonEmptyUnknownList,
   type Observable,
   type SyncChildObservable,
-  type UpdaterSymbol,
+  type UpdateToken,
   type Wrap,
 } from '../types/index.mjs';
 
@@ -41,30 +42,30 @@ import {
  *
  * const user$ = combine([name$, age$]);
  *
- * const mut_history: (readonly [string, number])[] = [];
+ * const userHistory: (readonly [string, number])[] = [];
  *
  * user$.subscribe(([name_, age]) => {
- *   mut_history.push([name_, age]);
+ *   userHistory.push([name_, age]);
  * });
  *
  * name$.next('Alice'); // nothing logged (age$ hasn't emitted yet)
  *
- * assert.deepStrictEqual(mut_history, []);
+ * assert.deepStrictEqual(userHistory, []);
  *
  * age$.next(25); // logs: { name: 'Alice', age: 25 }
  *
- * assert.deepStrictEqual(mut_history, [['Alice', 25]]);
+ * assert.deepStrictEqual(userHistory, [['Alice', 25]]);
  *
  * name$.next('Bob'); // logs: { name: 'Bob', age: 25 }
  *
- * assert.deepStrictEqual(mut_history, [
+ * assert.deepStrictEqual(userHistory, [
  *   ['Alice', 25],
  *   ['Bob', 25],
  * ]);
  *
  * age$.next(30); // logs: { name: 'Bob', age: 30 }
  *
- * assert.deepStrictEqual(mut_history, [
+ * assert.deepStrictEqual(userHistory, [
  *   ['Alice', 25],
  *   ['Bob', 25],
  *   ['Bob', 30],
@@ -103,8 +104,8 @@ class CombineObservableClass<const A extends NonEmptyUnknownList>
     });
   }
 
-  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
-    if (this.parents.every((o) => o.updaterSymbol !== updaterSymbol)) return; // all parents are skipped
+  override tryUpdate(updateToken: UpdateToken): void {
+    if (this.parents.every((o) => o.updateToken !== updateToken)) return; // all parents are skipped
 
     const parentValues = this.parents.map((a) => a.getSnapshot());
 
@@ -113,7 +114,7 @@ class CombineObservableClass<const A extends NonEmptyUnknownList>
         // eslint-disable-next-line total-functions/no-unsafe-type-assertion
         Arr.map(parentValues, (a) => a.value) as A;
 
-      this.setNext(nextValue, updaterSymbol);
+      this.setNext(nextValue, updateToken);
     }
   }
 }
@@ -154,9 +155,9 @@ class CombineObservableClass<const A extends NonEmptyUnknownList>
     expectType<typeof _d, InitializedObservable<readonly [1, 2]>>('<=');
   }
 
-  const r1 = fromArray([1, 2, 3]);
+  const r1 = source(1);
 
-  const r2 = fromArray(['a', 'b', 'c']);
+  const r2 = source('a');
 
   const _c = combine([r1, r2]);
 

package/src/core/combine/merge.mts

@@ -1,13 +1,14 @@
 import { Optional, expectType } from 'ts-data-forge';
+import { type ArrayElement, type NonEmptyArray } from 'ts-type-forge';
 import { SyncChildObservableClass } from '../class/index.mjs';
-import { fromArray } from '../create/index.mjs';
+import { source } from '../create/index.mjs';
 import {
   type MergeObservable,
   type MergeObservableRefined,
   type NonEmptyUnknownList,
   type Observable,
   type SyncChildObservable,
-  type UpdaterSymbol,
+  type UpdateToken,
   type Wrap,
 } from '../types/index.mjs';
 
@@ -23,7 +24,7 @@ import {
  * ```ts
  * //  Timeline:
  * //
- * //  clicks$   c1          c2                    c3
+ * //  clicks$   c1              c2                c3
  * //  keys$               k1          k2                    k3
  * //  events$   c1        k1    c2    k2          c3        k3
  * //
@@ -38,25 +39,25 @@ import {
  *
  * const events$ = merge([clicks$, keys$]);
  *
- * const mut_history: string[] = [];
+ * const valueHistory: string[] = [];
  *
  * events$.subscribe((event_) => {
- *   mut_history.push(event_);
+ *   valueHistory.push(event_);
  * });
  *
  * clicks$.next('c1');
  *
- * assert.deepStrictEqual(mut_history, ['c1']);
+ * assert.deepStrictEqual(valueHistory, ['c1']);
  *
  * keys$.next('k1');
  *
- * assert.deepStrictEqual(mut_history, ['c1', 'k1']);
+ * assert.deepStrictEqual(valueHistory, ['c1', 'k1']);
  *
  * clicks$.next('c2');
  *
  * keys$.next('k2');
  *
- * assert.deepStrictEqual(mut_history, ['c1', 'k1', 'c2', 'k2']);
+ * assert.deepStrictEqual(valueHistory, ['c1', 'k1', 'c2', 'k2']);
  * ```
  *
  * @note To improve code readability, consider using `createState` instead of `merge`,
@@ -79,10 +80,9 @@ class MergeObservableClass<const P extends NonEmptyUnknownList>
     });
   }
 
-  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+  override tryUpdate(updateToken: UpdateToken): void {
     const parentToUse = this.parents.find(
-      (o) =>
-        o.updaterSymbol === updaterSymbol && Optional.isSome(o.getSnapshot()),
+      (o) => o.updateToken === updateToken && Optional.isSome(o.getSnapshot()),
     );
 
     if (parentToUse === undefined) return;
@@ -91,7 +91,7 @@ class MergeObservableClass<const P extends NonEmptyUnknownList>
       // eslint-disable-next-line total-functions/no-unsafe-type-assertion
       Optional.unwrap(parentToUse.getSnapshot()) as ArrayElement<P>;
 
-    this.setNext(nextValue, updaterSymbol);
+    this.setNext(nextValue, updateToken);
   }
 }
 
@@ -100,9 +100,9 @@ if (import.meta.vitest !== undefined) {
     expect(1).toBe(1); // dummy
   });
 
-  const r1 = fromArray([1, 2, 3]);
+  const r1 = source(1);
 
-  const r2 = fromArray(['a', 'b', 'c']);
+  const r2 = source('a');
 
   const _m = merge([r1, r2] as const);
 

package/src/core/combine/zip.mts

@@ -1,6 +1,7 @@
 import { Arr, Optional, createQueue, expectType } from 'ts-data-forge';
+import { type NonEmptyArray } from 'ts-type-forge';
 import { SyncChildObservableClass } from '../class/index.mjs';
-import { fromArray, source } from '../create/index.mjs';
+import { source } from '../create/index.mjs';
 import { withInitialValue } from '../operators/index.mjs';
 import {
   type InitializedObservable,
@@ -9,7 +10,7 @@ import {
   type Observable,
   type SyncChildObservable,
   type TupleToQueueTuple,
-  type UpdaterSymbol,
+  type UpdateToken,
   type Wrap,
   type ZipObservable,
   type ZipObservableRefined,
@@ -28,38 +29,39 @@ import {
  * ```ts
  * //  Timeline:
  * //
- * //  letters$  'a'       'b'       'c'
+ * //  letters$  'A'       'B'       'C'
  * //  numbers$  1         2         3
- * //  zipped$   ['a',1]   ['b',2]   ['c',3]
+ * //  zipped$   ['A',1]   ['B',2]   ['C',3]
  * //
  * //  Explanation:
  * //  - zip pairs values by their index from multiple sources
  * //  - Waits for all sources to emit at the same index
  * //  - Completes when any source completes
  *
- * const letters$ = fromArray(['a', 'b', 'c']);
+ * const [letters$, setLetter] = createState<string>('A');
  *
- * const numbers$ = fromArray([1, 2, 3]);
+ * const [numbers$, setNumber] = createState<number>(1);
  *
  * const zipped$ = zip([letters$, numbers$]);
  *
- * const mut_history: (readonly [string, number])[] = [];
+ * const valueHistory: (readonly [string, number])[] = [];
  *
- * await new Promise<void>((resolve) => {
- *   zipped$.subscribe(
- *     ([letter, num]) => {
- *       mut_history.push([letter, num]);
- *     },
- *     () => {
- *       resolve();
- *     },
- *   );
+ * zipped$.subscribe(([letter, num]) => {
+ *   valueHistory.push([letter, num]);
  * });
  *
- * assert.deepStrictEqual(mut_history, [
- *   ['a', 1],
- *   ['b', 2],
- *   ['c', 3],
+ * for (const letter of ['B', 'C']) {
+ *   setLetter(letter);
+ * }
+ *
+ * for (const num of [2, 3]) {
+ *   setNumber(num);
+ * }
+ *
+ * assert.deepStrictEqual(valueHistory, [
+ *   ['A', 1],
+ *   ['B', 2],
+ *   ['C', 3],
  * ]);
  * ```
  */
@@ -93,13 +95,13 @@ class ZipObservableClass<const A extends NonEmptyUnknownList>
     ) satisfies TupleToQueueTuple<A>;
   }
 
-  override tryUpdate(updaterSymbol: UpdaterSymbol): void {
+  override tryUpdate(updateToken: UpdateToken): void {
     const queues = this.#queues;
 
     for (const [index, par] of this.parents.entries()) {
       const sn = par.getSnapshot();
 
-      if (par.updaterSymbol === updaterSymbol && Optional.isSome(sn)) {
+      if (par.updateToken === updateToken && Optional.isSome(sn)) {
         queues[index]?.enqueue(sn.value);
       }
     }
@@ -109,7 +111,7 @@ class ZipObservableClass<const A extends NonEmptyUnknownList>
         // eslint-disable-next-line total-functions/no-unsafe-type-assertion
         Arr.map(queues, (q) => Optional.unwrap(q.dequeue())) as A;
 
-      this.setNext(nextValue, updaterSymbol);
+      this.setNext(nextValue, updateToken);
     }
   }
 }
@@ -154,9 +156,9 @@ if (import.meta.vitest !== undefined) {
     expectType<typeof _d, InitializedObservable<readonly [1, 2]>>('<=');
   }
 
-  const r1 = fromArray([1, 2, 3]);
+  const r1 = source(1);
 
-  const r2 = fromArray(['a', 'b', 'c']);
+  const r2 = source('a');
 
   const _z = zip([r1, r2] as const);
 

package/src/core/create/{interval.mts → counter.mts}

@@ -1,12 +1,12 @@
 import { asSafeUint, Optional, SafeUint } from 'ts-data-forge';
 import { RootObservableClass } from '../class/index.mjs';
-import { type IntervalObservable } from '../types/index.mjs';
+import { type CounterObservable, type TimerId } 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 intervalMilliSeconds - The interval duration in milliseconds
  * @param startManually - If true, waits for manual start (default: false)
  * @returns An observable that emits sequential numbers
  *
@@ -18,16 +18,16 @@ import { type IntervalObservable } from '../types/index.mjs';
  * //  tick$     0     1     2     3     4     5     ...
  * //
  * //  Explanation:
- * //  - interval emits incrementing numbers at specified intervals
+ * //  - counter emits incrementing numbers at specified intervals
  * //  - Starts at 0 and continues indefinitely
  * //  - Useful for periodic tasks or animations
  *
- * const tick$ = interval(100);
+ * const tick$ = counter(100);
  *
- * const mut_history: number[] = [];
+ * const valueHistory: number[] = [];
  *
  * const subscription = tick$.subscribe((count) => {
- *   mut_history.push(count);
+ *   valueHistory.push(count);
  * });
  *
  * await new Promise((resolve) => {
@@ -36,35 +36,40 @@ import { type IntervalObservable } from '../types/index.mjs';
  *
  * subscription.unsubscribe();
  *
- * assert.isTrue(Arr.isArrayAtLeastLength(mut_history, 3));
+ * assert.isTrue(Arr.isArrayAtLeastLength(valueHistory, 3));
  *
- * assert.deepStrictEqual(mut_history[0], 0);
+ * assert.deepStrictEqual(valueHistory[0], 0);
  *
- * assert.deepStrictEqual(mut_history[1], 1);
+ * assert.deepStrictEqual(valueHistory[1], 1);
  *
- * assert.deepStrictEqual(mut_history[2], 2);
+ * assert.deepStrictEqual(valueHistory[2], 2);
  * ```
  */
-export const interval = (
-  milliSeconds: number,
-  startManually?: boolean,
-): IntervalObservable =>
-  new IntervalObservableClass(milliSeconds, startManually);
-
-class IntervalObservableClass
+export const counter = (
+  intervalMilliSeconds: number,
+  options?: Readonly<{
+    startManually?: boolean;
+  }>,
+): CounterObservable =>
+  new CounterObservableClass(
+    intervalMilliSeconds,
+    options?.startManually ?? false,
+  );
+
+class CounterObservableClass
   extends RootObservableClass<SafeUint>
-  implements IntervalObservable
+  implements CounterObservable
 {
-  readonly #milliSeconds: number;
+  readonly #intervalMilliSeconds: number;
   #mut_counter: SafeUint;
   #mut_timerId0: TimerId | undefined;
   #mut_timerId: TimerId | undefined;
   #mut_isStarted: boolean;
 
-  constructor(milliSeconds: number, startManually?: boolean) {
+  constructor(intervalMilliSeconds: number, startManually: boolean) {
     super({ initialValue: Optional.none });
 
-    this.#milliSeconds = milliSeconds;
+    this.#intervalMilliSeconds = intervalMilliSeconds;
 
     this.#mut_counter = asSafeUint(0);
 
@@ -74,27 +79,26 @@ class IntervalObservableClass
 
     this.#mut_isStarted = false;
 
-    if (startManually !== true) {
+    if (!startManually) {
       this.start();
     }
   }
 
-  start(): this {
+  start(): void {
     if (this.#mut_isStarted) {
       console.warn('cannot start twice');
 
-      return this;
+      return;
     }
 
     this.#mut_isStarted = true;
 
     if (this.isCompleted) {
-      console.warn('cannot restart stopped IntervalObservable');
+      console.warn('cannot restart stopped CounterObservable');
 
-      return this;
+      return;
     }
 
-    // emit zero
     this.#mut_timerId0 = setTimeout(() => {
       this.startUpdate(this.#mut_counter);
     }, 0);
@@ -103,9 +107,7 @@ class IntervalObservableClass
       this.#mut_counter = SafeUint.add(1, this.#mut_counter);
 
       this.startUpdate(this.#mut_counter);
-    }, this.#milliSeconds);
-
-    return this;
+    }, this.#intervalMilliSeconds);
   }
 
   #resetTimer(): void {

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

@@ -0,0 +1,83 @@
+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 factory that receives an `AbortSignal`.
+ * When the observable is completed (e.g., by `switchMap` switching to a new
+ * inner observable), the `AbortController` is automatically aborted, cancelling
+ * the in-flight request.
+ *
+ * Emits `Result.ok(value)` when the promise resolves, or `Result.err(error)`
+ * when it rejects. Rejections caused by abort (`AbortError`) are silently
+ * ignored and do not emit.
+ *
+ * @template A - The type of the resolved value
+ * @template E - The type of the error (excluding AbortError)
+ * @param factory - A function that receives an `AbortSignal` and returns a Promise
+ * @returns An observable that emits the promise result
+ *
+ * @example
+ * ```ts
+ * const results$ = query.pipe(
+ *   switchMap((q) =>
+ *     fromAbortablePromise((signal) =>
+ *       fetch(`/api/search?q=${q}`, { signal }).then((r) => r.json()),
+ *     ),
+ *   ),
+ * );
+ * ```
+ */
+export const fromAbortablePromise = <A, E = unknown>(
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  factory: (signal: AbortSignal) => Promise<A>,
+): FromPromiseObservable<A, E> =>
+  new FromAbortablePromiseObservableClass(factory);
+
+class FromAbortablePromiseObservableClass<A, E = unknown>
+  extends RootObservableClass<Result<A, E>>
+  implements FromPromiseObservable<A, E>
+{
+  readonly #abortController: AbortController;
+
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  constructor(factory: (signal: AbortSignal) => Promise<A>) {
+    super({ initialValue: Optional.none });
+
+    this.#abortController = new AbortController();
+
+    const promise = factory(this.#abortController.signal);
+
+    promise
+      .then((value) => {
+        if (this.isCompleted) return;
+
+        this.startUpdate(Result.ok(value));
+      })
+      .catch((error: unknown) => {
+        if (this.isCompleted) return;
+
+        // Silently ignore AbortError — it means the observable was
+        // intentionally completed (e.g., by switchMap).
+        if (error instanceof DOMException && error.name === 'AbortError') {
+          return;
+        }
+
+        this.startUpdate(
+          Result.err(
+            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+            error as E,
+          ),
+        );
+      })
+      .finally(() => {
+        this.complete();
+      });
+  }
+
+  override complete(): void {
+    this.#abortController.abort();
+
+    super.complete();
+  }
+}

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

@@ -16,7 +16,7 @@ import { type FromPromiseObservable } from '../types/index.mjs';
  * //  Timeline:
  * //
  * //  promise     [pending...]  -> resolved/rejected
- * //  data$                     Ok(value) or Err(error)
+ * //  data$                        Ok(value) or Err(error)
  * //
  * //  Explanation:
  * //  - fromPromise converts a Promise into an observable
@@ -24,17 +24,20 @@ import { type FromPromiseObservable } from '../types/index.mjs';
  * //  - Completes after emitting the result
  * //  - Useful for integrating async operations into reactive flows
  *
- * const fetchData = async (): Promise<{ value: number }> => ({ value: 42 });
+ * const fetchData = async (): Promise<Readonly<{ value: number }>> =>
+ *   ({
+ *     value: 42,
+ *   }) as const;
  *
  * const data$ = fromPromise(fetchData());
  *
- * const mut_history: { value: number }[] = [];
+ * const valueHistory: Readonly<{ value: number }>[] = [];
  *
  * await new Promise<void>((resolve) => {
  *   data$.subscribe(
  *     (result) => {
  *       if (Result.isOk(result)) {
- *         mut_history.push(result.value);
+ *         valueHistory.push(result.value);
  *       }
  *     },
  *     () => {
@@ -43,18 +46,18 @@ import { type FromPromiseObservable } from '../types/index.mjs';
  *   );
  * });
  *
- * assert.deepStrictEqual(mut_history, [{ value: 42 }]);
+ * assert.deepStrictEqual(valueHistory, [{ value: 42 }]);
  * ```
  */
 export const fromPromise = <A, E = unknown>(
-  promise: Readonly<Promise<A>>,
+  promise: 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>>) {
+  constructor(promise: Promise<A>) {
     super({ initialValue: Optional.none });
 
     promise

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

@@ -41,17 +41,17 @@ import {
  *
  *     return { unsubscribe: () => {} };
  *   },
- * };
+ * } as const;
  *
  * const observable$ = fromSubscribable<number>(customSubscribable);
  *
- * const mut_history: number[] = [];
+ * const valueHistory: number[] = [];
  *
  * await new Promise<void>((resolve) => {
  *   observable$.subscribe(
  *     (result) => {
  *       if (Result.isOk(result)) {
- *         mut_history.push(result.value);
+ *         valueHistory.push(result.value);
  *       }
  *     },
  *     () => {
@@ -60,7 +60,7 @@ import {
  *   );
  * });
  *
- * assert.deepStrictEqual(mut_history, [1, 2, 3]);
+ * assert.deepStrictEqual(valueHistory, [1, 2, 3]);
  * ```
  */
 export const fromSubscribable = <A, E = unknown>(

package/src/core/create/index.mts

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

package/src/core/create/just.mts

@@ -0,0 +1,43 @@
+import { Optional } from 'ts-data-forge';
+import { RootObservableClass } from '../class/index.mjs';
+import { type InitializedRootObservable } from '../types/index.mjs';
+
+/**
+ * Creates an Observable that holds a single static value and immediately
+ * completes. Useful inside `switchMap` to emit a fallback value when no
+ * asynchronous work is needed.
+ *
+ * @template A - The type of the value
+ * @param value - The value to emit
+ * @returns An initialized Observable that holds the value and is already completed
+ *
+ * @example
+ * ```ts
+ * const greeting$ = just('hello');
+ *
+ * const valueHistory: string[] = [];
+ *
+ * greeting$.subscribe(
+ *   (value) => {
+ *     valueHistory.push(value);
+ *   },
+ *   () => {
+ *     // onComplete — called immediately since just() completes right away
+ *   },
+ * );
+ *
+ * assert.deepStrictEqual(valueHistory, ['hello']);
+ *
+ * assert.strictEqual(greeting$.isCompleted, true);
+ * ```
+ */
+export const just = <const A,>(value: A): InitializedRootObservable<A> => {
+  const obs = new RootObservableClass<A>({
+    initialValue: Optional.some(value),
+  });
+
+  obs.complete();
+
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  return obs as InitializedRootObservable<A>;
+};