synstate 0.1.2 → 1.0.1

package/src/core/predefined/operators/map-result-err.mts

@@ -1,7 +1,54 @@
-import { Result } from 'ts-data-forge';
+import { Result, type UnknownResult } from 'ts-data-forge';
+import { map } from '../../operators/index.mjs';
 import { type KeepInitialValueOperator } from '../../types/index.mjs';
-import { map } from './map.mjs';
 
+/**
+ * Transforms the error value (`Err`) of a `Result` type emitted by the source.
+ * If the value is `Err`, the mapping function is applied; if `Ok`, it remains unchanged.
+ *
+ * @template R - The Result type from the source
+ * @template E2 - The type of the mapped error value
+ * @param mapFn - A function to transform the Err value
+ * @returns An operator that maps the Err side of Result emissions
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  result$   Ok(1)    Err("bad")      Err("fail")
+ * //  mapped$   Ok(1)    Err("BAD")      Err("FAIL")
+ * //
+ * //  Explanation:
+ * //  - mapResultErr transforms the Err value of Result emissions
+ * //  - Ok values pass through unchanged
+ *
+ * const result$ = source<Result<number, string>>();
+ *
+ * const mapped$ = result$.pipe(mapResultErr((e) => e.toUpperCase()));
+ *
+ * const valueHistory: Result<number, string>[] = [];
+ *
+ * mapped$.subscribe((v) => {
+ *   valueHistory.push(v);
+ * });
+ *
+ * result$.next(Result.ok(1));
+ *
+ * assert.deepStrictEqual(valueHistory, [Result.ok(1)]);
+ *
+ * result$.next(Result.err('bad'));
+ *
+ * assert.deepStrictEqual(valueHistory, [Result.ok(1), Result.err('BAD')]);
+ *
+ * result$.next(Result.err('fail'));
+ *
+ * assert.deepStrictEqual(valueHistory, [
+ *   Result.ok(1),
+ *   Result.err('BAD'),
+ *   Result.err('FAIL'),
+ * ]);
+ * ```
+ */
 export const mapResultErr = <R extends UnknownResult, E2>(
   mapFn: (x: Result.UnwrapErr<R>) => E2,
 ): KeepInitialValueOperator<R, Result<Result.UnwrapOk<R>, E2>> =>

package/src/core/predefined/operators/map-result-ok.mts

@@ -1,7 +1,54 @@
-import { Result } from 'ts-data-forge';
+import { Result, type UnknownResult } from 'ts-data-forge';
+import { map } from '../../operators/index.mjs';
 import { type KeepInitialValueOperator } from '../../types/index.mjs';
-import { map } from './map.mjs';
 
+/**
+ * Transforms the success value (`Ok`) of a `Result` type emitted by the source.
+ * If the value is `Ok`, the mapping function is applied; if `Err`, it remains unchanged.
+ *
+ * @template R - The Result type from the source
+ * @template S2 - The type of the mapped success value
+ * @param mapFn - A function to transform the Ok value
+ * @returns An operator that maps the Ok side of Result emissions
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  result$   Ok(2)      Err("e")   Ok(5)
+ * //  doubled$  Ok(4)      Err("e")   Ok(10)
+ * //
+ * //  Explanation:
+ * //  - mapResultOk transforms the Ok value of Result emissions
+ * //  - Err values pass through unchanged
+ *
+ * const result$ = source<Result<number, string>>();
+ *
+ * const doubled$ = result$.pipe(mapResultOk((x) => x * 2));
+ *
+ * const valueHistory: Result<number, string>[] = [];
+ *
+ * doubled$.subscribe((v) => {
+ *   valueHistory.push(v);
+ * });
+ *
+ * result$.next(Result.ok(2));
+ *
+ * assert.deepStrictEqual(valueHistory, [Result.ok(4)]);
+ *
+ * result$.next(Result.err('e'));
+ *
+ * assert.deepStrictEqual(valueHistory, [Result.ok(4), Result.err('e')]);
+ *
+ * result$.next(Result.ok(5));
+ *
+ * assert.deepStrictEqual(valueHistory, [
+ *   Result.ok(4),
+ *   Result.err('e'),
+ *   Result.ok(10),
+ * ]);
+ * ```
+ */
 export const mapResultOk = <R extends UnknownResult, S2>(
   mapFn: (x: Result.UnwrapOk<R>) => S2,
 ): KeepInitialValueOperator<R, Result<S2, Result.UnwrapErr<R>>> =>

package/src/core/predefined/operators/map-to.mts

@@ -1,5 +1,45 @@
+import { map } from '../../operators/index.mjs';
 import { type KeepInitialValueOperator } from '../../types/index.mjs';
-import { map } from './map.mjs';
 
+/**
+ * Maps all emitted values to a constant value, ignoring the source values.
+ * Equivalent to `map(() => value)`.
+ *
+ * @template A - The type of values from the source
+ * @template B - The type of the constant value
+ * @param value - The constant value to emit
+ * @returns An operator that always emits the given constant
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  click$    MouseEvent   MouseEvent   MouseEvent
+ * //  count$    1            1            1
+ * //
+ * //  Explanation:
+ * //  - mapTo maps all emitted values to a constant value
+ * //  - Ignores the source values entirely
+ * //  - Useful for converting events to signals
+ *
+ * const click$ = source<string>();
+ *
+ * const one$ = click$.pipe(mapTo(1));
+ *
+ * const valueHistory: number[] = [];
+ *
+ * one$.subscribe((value) => {
+ *   valueHistory.push(value);
+ * });
+ *
+ * click$.next('click1');
+ *
+ * click$.next('click2');
+ *
+ * click$.next('click3');
+ *
+ * assert.deepStrictEqual(valueHistory, [1, 1, 1]);
+ * ```
+ */
 export const mapTo = <A, B>(value: B): KeepInitialValueOperator<A, B> =>
   map(() => value);

package/src/core/predefined/operators/pluck.mts

@@ -1,6 +1,45 @@
+import { map } from '../../operators/index.mjs';
 import { type KeepInitialValueOperator } from '../../types/index.mjs';
-import { map } from './map.mjs';
 
+/**
+ * Extracts a property value from each emitted object by key.
+ * Equivalent to `map(value => value[key])`.
+ *
+ * @template A - The type of the emitted object
+ * @template K - The key to extract
+ * @param key - The property key to pluck
+ * @returns An operator that emits the property value
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  user$   { name: "Alice", age: 25 }   { name: "Bob", age: 30 }
+ * //  name$   "Alice"                       "Bob"
+ * //
+ * //  Explanation:
+ * //  - getKey extracts a property value from each emitted object
+ * //  - Equivalent to map(value => value[key])
+ *
+ * const user$ = source<Readonly<{ name: string; age: number }>>();
+ *
+ * const name$ = user$.pipe(getKey('name'));
+ *
+ * const valueHistory: string[] = [];
+ *
+ * name$.subscribe((n) => {
+ *   valueHistory.push(n);
+ * });
+ *
+ * user$.next({ name: 'Alice', age: 25 });
+ *
+ * assert.deepStrictEqual(valueHistory, ['Alice']);
+ *
+ * user$.next({ name: 'Bob', age: 30 });
+ *
+ * assert.deepStrictEqual(valueHistory, ['Alice', 'Bob']);
+ * ```
+ */
 export const pluck = <A, K extends keyof A>(
   key: K,
 ): KeepInitialValueOperator<A, A[K]> => map((a) => a[key]);

package/src/core/predefined/operators/skip.mts

@@ -1,7 +1,55 @@
 import { PositiveSafeInt } from 'ts-data-forge';
+import { type PositiveSafeIntWithSmallInt } from 'ts-type-forge';
 import { skipWhile } from '../../operators/index.mjs';
 import { type DropInitialValueOperator } from '../../types/index.mjs';
 
+/**
+ * Skips the first `n` emissions from the source observable.
+ * After `n` values are skipped, all subsequent values pass through.
+ *
+ * @template A - The type of values from the source
+ * @param n - The number of values to skip
+ * @returns An operator that skips the first n emissions
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  num$      1     2     3     4     5
+ * //  skipped$              3     4     5
+ * //            |skip 2|
+ * //
+ * //  Explanation:
+ * //  - skip ignores the first n emissions from the source
+ * //  - After n values are skipped, all subsequent values pass through
+ *
+ * const num$ = source<number>();
+ *
+ * const skipped$ = num$.pipe(skip(2));
+ *
+ * const valueHistory: number[] = [];
+ *
+ * skipped$.subscribe((x) => {
+ *   valueHistory.push(x);
+ * });
+ *
+ * num$.next(1); // skipped
+ *
+ * num$.next(2); // skipped
+ *
+ * assert.deepStrictEqual(valueHistory, []);
+ *
+ * num$.next(3); // logs: 3
+ *
+ * assert.deepStrictEqual(valueHistory, [3]);
+ *
+ * num$.next(4); // logs: 4
+ *
+ * num$.next(5); // logs: 5
+ *
+ * assert.deepStrictEqual(valueHistory, [3, 4, 5]);
+ * ```
+ */
 export const skip = <A,>(
   n: PositiveSafeIntWithSmallInt,
 ): DropInitialValueOperator<A, A> =>

package/src/core/predefined/operators/take.mts

@@ -1,6 +1,48 @@
+import { type PositiveSafeIntWithSmallInt } from 'ts-type-forge';
 import { takeWhile } from '../../operators/index.mjs';
 import { type DropInitialValueOperator } from '../../types/index.mjs';
 
+/**
+ * Takes only the first `n` emissions from the source observable, then completes.
+ *
+ * @template A - The type of values from the source
+ * @param n - The number of values to take
+ * @returns An operator that takes the first n emissions
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  num$    1     2     3     4 (ignored)
+ * //  taken$  1     2     3     | (completes)
+ * //
+ * //  Explanation:
+ * //  - take emits only the first n values, then completes
+ * //  - Subsequent emissions from the source are ignored
+ *
+ * const num$ = source<number>();
+ *
+ * const taken$ = num$.pipe(take(3));
+ *
+ * const valueHistory: number[] = [];
+ *
+ * taken$.subscribe((x) => {
+ *   valueHistory.push(x);
+ * });
+ *
+ * num$.next(1);
+ *
+ * num$.next(2);
+ *
+ * num$.next(3);
+ *
+ * assert.deepStrictEqual(valueHistory, [1, 2, 3]);
+ *
+ * num$.next(4); // ignored (already completed)
+ *
+ * assert.deepStrictEqual(valueHistory, [1, 2, 3]);
+ * ```
+ */
 export const take = <A,>(
   n: PositiveSafeIntWithSmallInt,
 ): DropInitialValueOperator<A, A> => takeWhile((_, index) => index + 1 <= n);

package/src/core/predefined/operators/unwrap-optional.mts

@@ -1,7 +1,48 @@
-import { Optional } from 'ts-data-forge';
+import { Optional, type UnknownOptional } from 'ts-data-forge';
+import { type Fn } from 'ts-type-forge';
+import { map } from '../../operators/index.mjs';
 import { type KeepInitialValueOperator } from '../../types/index.mjs';
-import { map } from './map.mjs';
 
+/**
+ * Unwraps `Optional` values, converting `Some(value)` to `value` and `None` to `undefined`.
+ *
+ * @template O - The Optional type from the source
+ * @returns An operator that unwraps Optional emissions
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  opt$        Some(42)    None        Some(7)
+ * //  unwrapped$  42          undefined   7
+ * //
+ * //  Explanation:
+ * //  - unwrapOptional converts Some(value) to value, and None to undefined
+ * //  - Useful for extracting raw values from Optional streams
+ *
+ * const opt$ = source<Optional<number>>();
+ *
+ * const unwrapped$ = opt$.pipe(unwrapOptional());
+ *
+ * const valueHistory: (number | undefined)[] = [];
+ *
+ * unwrapped$.subscribe((v) => {
+ *   valueHistory.push(v);
+ * });
+ *
+ * opt$.next(Optional.some(42));
+ *
+ * assert.deepStrictEqual(valueHistory, [42]);
+ *
+ * opt$.next(Optional.none);
+ *
+ * assert.deepStrictEqual(valueHistory, [42, undefined]);
+ *
+ * opt$.next(Optional.some(7));
+ *
+ * assert.deepStrictEqual(valueHistory, [42, undefined, 7]);
+ * ```
+ */
 export const unwrapOptional = <
   O extends UnknownOptional,
 >(): KeepInitialValueOperator<O, Optional.Unwrap<O> | undefined> =>

package/src/core/predefined/operators/unwrap-result-err.mts

@@ -1,7 +1,48 @@
-import { Result } from 'ts-data-forge';
+import { Result, type UnknownResult } from 'ts-data-forge';
+import { type Fn } from 'ts-type-forge';
+import { map } from '../../operators/index.mjs';
 import { type KeepInitialValueOperator } from '../../types/index.mjs';
-import { map } from './map.mjs';
 
+/**
+ * Unwraps the error value from a `Result`, converting `Err(error)` to `error` and `Ok` to `undefined`.
+ *
+ * @template R - The Result type from the source
+ * @returns An operator that unwraps the Err side of Result emissions
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  result$     Ok(1)      Err("fail")   Ok(2)
+ * //  unwrapped$  undefined  "fail"        undefined
+ * //
+ * //  Explanation:
+ * //  - unwrapResultErr converts Err(error) to error, and Ok to undefined
+ * //  - Useful for extracting error values from Result streams
+ *
+ * const result$ = source<Result<number, string>>();
+ *
+ * const unwrapped$ = result$.pipe(unwrapResultErr());
+ *
+ * const valueHistory: (string | undefined)[] = [];
+ *
+ * unwrapped$.subscribe((v) => {
+ *   valueHistory.push(v);
+ * });
+ *
+ * result$.next(Result.ok(1));
+ *
+ * assert.deepStrictEqual(valueHistory, [undefined]);
+ *
+ * result$.next(Result.err('fail'));
+ *
+ * assert.deepStrictEqual(valueHistory, [undefined, 'fail']);
+ *
+ * result$.next(Result.ok(2));
+ *
+ * assert.deepStrictEqual(valueHistory, [undefined, 'fail', undefined]);
+ * ```
+ */
 export const unwrapResultErr = <
   R extends UnknownResult,
 >(): KeepInitialValueOperator<R, Result.UnwrapErr<R> | undefined> =>

package/src/core/predefined/operators/unwrap-result-ok.mts

@@ -1,7 +1,48 @@
-import { Result } from 'ts-data-forge';
+import { Result, type UnknownResult } from 'ts-data-forge';
+import { type Fn } from 'ts-type-forge';
+import { map } from '../../operators/index.mjs';
 import { type KeepInitialValueOperator } from '../../types/index.mjs';
-import { map } from './map.mjs';
 
+/**
+ * Unwraps the success value from a `Result`, converting `Ok(value)` to `value` and `Err` to `undefined`.
+ *
+ * @template R - The Result type from the source
+ * @returns An operator that unwraps the Ok side of Result emissions
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  result$     Ok(42)    Err("e")    Ok(7)
+ * //  unwrapped$  42        undefined   7
+ * //
+ * //  Explanation:
+ * //  - unwrapResultOk converts Ok(value) to value, and Err to undefined
+ * //  - Useful for extracting success values from Result streams
+ *
+ * const result$ = source<Result<number, string>>();
+ *
+ * const unwrapped$ = result$.pipe(unwrapResultOk());
+ *
+ * const valueHistory: (number | undefined)[] = [];
+ *
+ * unwrapped$.subscribe((v) => {
+ *   valueHistory.push(v);
+ * });
+ *
+ * result$.next(Result.ok(42));
+ *
+ * assert.deepStrictEqual(valueHistory, [42]);
+ *
+ * result$.next(Result.err('e'));
+ *
+ * assert.deepStrictEqual(valueHistory, [42, undefined]);
+ *
+ * result$.next(Result.ok(7));
+ *
+ * assert.deepStrictEqual(valueHistory, [42, undefined, 7]);
+ * ```
+ */
 export const unwrapResultOk = <
   R extends UnknownResult,
 >(): KeepInitialValueOperator<R, Result.UnwrapOk<R> | undefined> =>

package/src/core/types/id.mts

@@ -1,5 +1,7 @@
+import { type Brand } from 'ts-type-forge';
+
 export type ObservableId = Brand<symbol, 'observable-id'>;
 
 export type SubscriberId = Brand<symbol, 'subscriber-id'>;
 
-export type UpdaterSymbol = Brand<symbol, 'updater-symbol'>;
+export type UpdateToken = Brand<symbol, 'update-token'>;

package/src/core/types/index.mts

@@ -2,4 +2,5 @@ export * from './id.mjs';
 export * from './observable-family.mjs';
 export * from './observable-kind.mjs';
 export * from './observable.mjs';
+export * from './timer.mjs';
 export * from './types.mjs';

package/src/core/types/observable-family.mts

@@ -1,4 +1,9 @@
 import { expectType, type Result } from 'ts-data-forge';
+import {
+  type ArrayElement,
+  type NonEmptyArray,
+  type SafeUint,
+} from 'ts-type-forge';
 import {
   type AsyncChildObservable,
   type InitializedObservable,
@@ -23,16 +28,6 @@ export type SourceObservable<A> = Readonly<{
 }> &
   RootObservable<A>;
 
-export type OfObservable<A> = Readonly<{
-  emit: () => OfObservable<A>;
-}> &
-  RootObservable<A>;
-
-export type FromArrayObservable<A> = Readonly<{
-  emit: () => FromArrayObservable<A>;
-}> &
-  RootObservable<A>;
-
 export type FromPromiseObservable<A, E = unknown> = RootObservable<
   Result<A, E>
 >;
@@ -41,13 +36,13 @@ export type FromSubscribableObservable<A, E = unknown> = RootObservable<
   Result<A, E>
 >;
 
-export type IntervalObservable = Readonly<{
-  start: () => IntervalObservable;
+export type CounterObservable = Readonly<{
+  start: () => void;
 }> &
   RootObservable<SafeUint>;
 
 export type TimerObservable = Readonly<{
-  start: () => TimerObservable;
+  start: () => void;
 }> &
   RootObservable<0>;
 
@@ -77,7 +72,7 @@ namespace SynStateInternals {
     ? true
     : false;
 
-  /** Evaluates True | false as true instead of boolean */
+  /** Evaluates true | false as true instead of boolean */
   type LogicalValue<B extends boolean> = readonly [B] extends readonly [true]
     ? true
     : readonly [B] extends readonly [false]
@@ -184,10 +179,7 @@ export type MergeObservableRefined<
   OS extends NonEmptyArray<Observable<unknown>>,
 > = SynStateInternals.MergeObservableRefinedImpl<OS>;
 
-export type MapWithIndexOperatorObservable<A, B> = SyncChildObservable<
-  B,
-  readonly [A]
->;
+export type MapOperatorObservable<A, B> = SyncChildObservable<B, readonly [A]>;
 
 export type PairwiseOperatorObservable<A> = SyncChildObservable<
   readonly [A, A],
@@ -231,19 +223,16 @@ export type SkipIfNoChangeOperatorObservable<A> = SyncChildObservable<
   readonly [A]
 >;
 
-export type ThrottleTimeOperatorObservable<A> = SyncChildObservable<
+export type ThrottleOperatorObservable<A> = SyncChildObservable<
   A,
   readonly [A]
 >;
 
 // AsyncChildObservable
 
-export type AuditTimeOperatorObservable<A> = AsyncChildObservable<
-  A,
-  readonly [A]
->;
+export type AuditOperatorObservable<A> = AsyncChildObservable<A, readonly [A]>;
 
-export type DebounceTimeOperatorObservable<A> = AsyncChildObservable<
+export type DebounceOperatorObservable<A> = AsyncChildObservable<
   A,
   readonly [A]
 >;

package/src/core/types/observable-kind.mts

@@ -1,3 +1,5 @@
+import { type StrictExclude } from 'ts-type-forge';
+
 export type ObservableKind = 'root' | 'sync child' | 'async child';
 
 export type ManagerObservableKind = StrictExclude<ObservableKind, 'sync child'>;

package/src/core/types/observable.mts

@@ -1,5 +1,6 @@
-import { expectType, type Optional } from 'ts-data-forge';
-import { type ObservableId, type UpdaterSymbol } from './id.mjs';
+import { expectType, type Optional, type Some } from 'ts-data-forge';
+import { type StrictOmit } from 'ts-type-forge';
+import { type ObservableId, type UpdateToken } from './id.mjs';
 import { type ObservableKind } from './observable-kind.mjs';
 import { type NonEmptyUnknownList, type Subscription } from './types.mjs';
 
@@ -28,12 +29,12 @@ type CreateObservableType<A, Kind extends ObservableKind> = Readonly<{
   // state
   getSnapshot: () => Optional<A>;
   isCompleted: boolean;
-  updaterSymbol: UpdaterSymbol;
+  updateToken: UpdateToken;
   hasSubscriber: boolean;
   hasChild: boolean;
   hasActiveChild: () => boolean;
 
-  tryUpdate: (updaterSymbol: UpdaterSymbol) => void;
+  tryUpdate: (updateToken: UpdateToken) => void;
   tryComplete: () => void;
   complete: () => void;
   subscribe: (onNext: (v: A) => void, onComplete?: () => void) => Subscription;

package/src/core/types/timer.mts

@@ -0,0 +1,2 @@
+// Timer types for Node.js/Browser compatibility
+export type TimerId = ReturnType<typeof setTimeout>;

package/src/core/utils/id-maker.mts

@@ -1,7 +1,7 @@
 import {
   type ObservableId,
   type SubscriberId,
-  type UpdaterSymbol,
+  type UpdateToken,
 } from '../types/index.mjs';
 
 function* idMaker<T extends symbol>(): Generator<T, T, T> {
@@ -19,7 +19,7 @@ const observableIdMaker = idMaker<ObservableId>();
 
 const subscriberIdMaker = idMaker<SubscriberId>();
 
-const updaterSymbolMaker = idMaker<UpdaterSymbol>();
+const updateTokenMaker = idMaker<UpdateToken>();
 
 export const issueObservableId = (): ObservableId =>
   observableIdMaker.next().value;
@@ -27,5 +27,5 @@ export const issueObservableId = (): ObservableId =>
 export const issueSubscriberId = (): SubscriberId =>
   subscriberIdMaker.next().value;
 
-export const issueUpdaterSymbol = (): UpdaterSymbol =>
-  updaterSymbolMaker.next().value;
+export const issueUpdateToken = (): UpdateToken =>
+  updateTokenMaker.next().value;

package/src/core/utils/utils.mts

@@ -1,4 +1,5 @@
 import { Arr, asSafeInt, asUint32, SafeInt } from 'ts-data-forge';
+import { type NegativeInt32, type Uint32 } from 'ts-type-forge';
 
 export const halfInt = (x: SafeInt): SafeInt =>
   x % 2 === 0

package/src/utils/collect-to-array.mts

@@ -0,0 +1,17 @@
+import { type Observable } from '../core/index.mjs';
+
+export const collectToArray = <A,>(
+  observable: Observable<A>,
+): Promise<readonly A[]> =>
+  new Promise<readonly A[]>((resolve) => {
+    const mut_buffer: A[] = [];
+
+    observable.subscribe(
+      (value) => {
+        mut_buffer.push(value);
+      },
+      () => {
+        resolve(mut_buffer);
+      },
+    );
+  });