synstate 0.1.0 → 0.1.2

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

@@ -17,23 +17,42 @@ import {
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  num$          1         2         stop      3 (ignored)
+ * //  stopNotifier                      X
+ * //  limited$      1         2         |------- (completed)
+ * //
+ * //  Explanation:
+ * //  - takeUntil completes the observable when the notifier emits
+ * //  - After stop() is called, no further values are emitted
+ * //  - Useful for cleanup and cancellation patterns
+ *
  * const num$ = source<number>();
  *
  * const [stopNotifier, stop_] = createEventEmitter();
  *
  * const limited$ = num$.pipe(takeUntil(stopNotifier));
  *
+ * const mut_history: number[] = [];
+ *
  * limited$.subscribe((x) => {
- *   console.log(x);
+ *   mut_history.push(x);
  * });
  *
  * num$.next(1); // logs: 1
  *
+ * assert.deepStrictEqual(mut_history, [1]);
+ *
  * num$.next(2); // logs: 2
  *
+ * assert.deepStrictEqual(mut_history, [1, 2]);
+ *
  * stop_();
  *
  * num$.next(3); // nothing logged (completed)
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2]);
  * ```
  */
 export const takeUntil = <A,>(

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

@@ -16,6 +16,53 @@ import {
 } from '../types/index.mjs';
 import { withInitialValue } from './with-initial-value.mjs';
 
+/**
+ * Emits values from the source observable while the predicate returns true.
+ * Completes immediately when the predicate returns false.
+ *
+ * @template A - The type of values from the source
+ * @param predicate - Function to test each value
+ * @returns An operator that takes values while the predicate is true
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  num$      1     2     3     4     5     6 (ignored)
+ * //  taken$    1     2     3     4     | (completes)
+ * //
+ * //  Explanation:
+ * //  - takeWhile emits values while the predicate returns true
+ * //  - Completes immediately when the predicate returns false
+ * //  - No further values are emitted after completion
+ *
+ * const num$ = source<number>();
+ *
+ * const taken$ = num$.pipe(takeWhile((x) => x < 5));
+ *
+ * const mut_history: number[] = [];
+ *
+ * taken$.subscribe((x) => {
+ *   mut_history.push(x);
+ * });
+ *
+ * num$.next(1); // logs: 1
+ *
+ * assert.deepStrictEqual(mut_history, [1]);
+ *
+ * num$.next(2); // logs: 2
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2]);
+ *
+ * num$.next(5); // nothing logged (completes)
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2]);
+ *
+ * num$.next(6); // nothing logged (already completed)
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2]);
+ * ```
+ */
 export const takeWhile =
   <A,>(
     predicate: (value: A, index: SafeUint | -1) => boolean,
@@ -23,12 +70,6 @@ export const takeWhile =
   (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>
@@ -86,7 +127,7 @@ if (import.meta.vitest !== undefined) {
   {
     const s: Observable<number> = source<number>();
 
-    const _d1 = s.pipe(take(3));
+    const _d1 = s.pipe(takeWhile((_, index) => index + 1 <= 3));
 
     expectType<typeof _d1, Observable<number>>('=');
   }
@@ -96,7 +137,7 @@ if (import.meta.vitest !== undefined) {
 
     const m: InitializedObservable<number> = s.pipe(withInitialValue(0));
 
-    const _d = m.pipe(take(3));
+    const _d = m.pipe(takeWhile((_, index) => index + 1 <= 3));
 
     expectType<typeof _d, Observable<number>>('=');
   }

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

@@ -17,14 +17,53 @@ import {
  *
  * @example
  * ```ts
- * const scroll$ = source<Event>();
+ * //  Timeline (1000ms throttle):
+ * //
+ * //  Time(ms)  0    100   200   300   ...   1000  1100  1200  ...   2000  2100
+ * //  scroll$   e1   e2    e3    e4          e5    e6    e7          e8    e9
+ * //  throttled$ e1                          e5                      e8
+ * //             |-------1000ms------>       |------1000ms------>    |------1000ms------>
+ * //
+ * //  Explanation:
+ * //  - throttleTime emits the first value immediately, then ignores subsequent values
+ * //    for the specified duration (1000ms)
+ * //  - At 0ms: e1 is emitted immediately
+ * //  - At 100-300ms: e2, e3, e4 are ignored (within 1000ms window)
+ * //  - At 1000ms: e5 is emitted (1000ms has passed since e1)
+ * //  - At 1100-1200ms: e6, e7 are ignored
+ * //  - At 2000ms: e8 is emitted (1000ms has passed since e5)
  *
- * const throttled$ = scroll$.pipe(throttleTime(1000));
+ * const scroll$ = source<number>();
  *
- * throttled$.subscribe((event_) => {
- *   console.log(event_);
+ * const throttled$ = scroll$.pipe(throttleTime(200));
+ *
+ * const mut_history: number[] = [];
+ *
+ * throttled$.subscribe((value) => {
+ *   mut_history.push(value);
  * });
- * // Emits at most once per second
+ *
+ * scroll$.next(1);
+ *
+ * assert.deepStrictEqual(mut_history, [1]);
+ *
+ * await new Promise((resolve) => {
+ *   setTimeout(resolve, 50);
+ * });
+ *
+ * scroll$.next(2);
+ *
+ * scroll$.next(3);
+ *
+ * assert.deepStrictEqual(mut_history, [1]);
+ *
+ * await new Promise((resolve) => {
+ *   setTimeout(resolve, 200);
+ * });
+ *
+ * scroll$.next(4);
+ *
+ * assert.deepStrictEqual(mut_history, [1, 4]);
  * ```
  */
 export const throttleTime = <A,>(

package/src/core/operators/with-buffered-from.mts

@@ -8,6 +8,59 @@ import {
 } from '../types/index.mjs';
 import { maxDepth } from '../utils/index.mjs';
 
+/**
+ * Buffers values from the source observable and emits them along with the parent value
+ * when the parent emits. The buffer is cleared after each emission.
+ *
+ * @template A - The type of values from the parent observable
+ * @template B - The type of values from the source observable
+ * @param observable - The observable whose values will be buffered
+ * @returns An operator that emits tuples of [parentValue, bufferedValues]
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  data$       d1    d2    d3    d4    d5    d6    d7    d8
+ * //  trigger$                T1                T2                T3
+ * //  result$                 [T1,[d1,d2,d3]]   [T2,[d4,d5,d6]]   [T3,[d7,d8]]
+ * //
+ * //  Explanation:
+ * //  - withBufferedFrom collects values from the source observable
+ * //  - When the trigger emits, it emits a tuple of [triggerValue, bufferedValues]
+ * //  - Buffer is cleared after each emission
+ * //  - Useful for batching data collection triggered by events
+ *
+ * const data$ = source<string>();
+ *
+ * const trigger$ = source<number>();
+ *
+ * const result$ = trigger$.pipe(withBufferedFrom(data$));
+ *
+ * const mut_history: (readonly [number, readonly string[]])[] = [];
+ *
+ * result$.subscribe(([triggerValue, bufferedData]) => {
+ *   mut_history.push([triggerValue, bufferedData]);
+ * });
+ *
+ * data$.next('a');
+ *
+ * data$.next('b');
+ *
+ * trigger$.next(1);
+ *
+ * assert.deepStrictEqual(mut_history, [[1, ['a', 'b']]]);
+ *
+ * data$.next('c');
+ *
+ * trigger$.next(2);
+ *
+ * assert.deepStrictEqual(mut_history, [
+ *   [1, ['a', 'b']],
+ *   [2, ['c']],
+ * ]);
+ * ```
+ */
 export const withBufferedFrom = <A, B>(
   observable: Observable<B>,
 ): KeepInitialValueOperator<A, readonly [A, readonly B[]]> =>
@@ -18,7 +71,11 @@ export const withBufferedFrom = <A, B>(
       observable,
     )) as KeepInitialValueOperator<A, readonly [A, readonly B[]]>;
 
-export const withBuffered = withBufferedFrom; // alias
+/**
+ * Alias for `withBufferedFrom`.
+ * @see withBufferedFrom
+ */
+export const withBuffered = withBufferedFrom;
 
 class WithBufferedFromObservableClass<A, B>
   extends SyncChildObservableClass<readonly [A, readonly B[]], readonly [A]>

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

@@ -8,6 +8,61 @@ import {
 } from '../types/index.mjs';
 import { maxDepth } from '../utils/index.mjs';
 
+/**
+ * Samples the current value from another observable each time the source emits.
+ * Emits a tuple of [sourceValue, sampledValue].
+ *
+ * @template A - The type of values from the source observable
+ * @template B - The type of values from the sampled observable
+ * @param observable - The observable to sample from
+ * @returns An operator that emits tuples of source and sampled values
+ *
+ * @example
+ * ```ts
+ * //  Timeline:
+ * //
+ * //  name$     "Alice"           "Bob"               "Charlie"
+ * //  age$                25              30      35              40
+ * //  result$             ["Alice",25]  ["Bob",30]  ["Bob",35]  ["Charlie",40]
+ * //
+ * //  Explanation:
+ * //  - withCurrentValueFrom samples the current value from another observable
+ * //  - Emits a tuple [sourceValue, sampledValue] each time the source emits
+ * //  - Does not emit until both observables have emitted at least once
+ * //  - Similar to combine, but only emits when the source (not the sampled) emits
+ *
+ * const name$ = source<string>();
+ *
+ * const age$ = source<number>();
+ *
+ * const result$ = name$.pipe(withCurrentValueFrom(age$));
+ *
+ * const mut_history: (readonly [string, number])[] = [];
+ *
+ * result$.subscribe(([name_, currentAge]) => {
+ *   mut_history.push([name_, currentAge]);
+ * });
+ *
+ * name$.next('Alice'); // nothing logged (age$ hasn't emitted)
+ *
+ * assert.deepStrictEqual(mut_history, []);
+ *
+ * age$.next(25);
+ *
+ * name$.next('Bob'); // logs: Bob is 25 years old
+ *
+ * assert.deepStrictEqual(mut_history, [['Bob', 25]]);
+ *
+ * age$.next(30);
+ *
+ * name$.next('Charlie'); // logs: Charlie is 30 years old
+ *
+ * assert.deepStrictEqual(mut_history, [
+ *   ['Bob', 25],
+ *   ['Charlie', 30],
+ * ]);
+ * ```
+ */
 export const withCurrentValueFrom =
   <A, B>(
     observable: Observable<B>,
@@ -15,7 +70,11 @@ export const withCurrentValueFrom =
   (parentObservable) =>
     new WithCurrentValueFromObservableClass(parentObservable, observable);
 
-export const withLatestFrom = withCurrentValueFrom; // alias
+/**
+ * Alias for `withCurrentValueFrom`.
+ * @see withCurrentValueFrom
+ */
+export const withLatestFrom = withCurrentValueFrom;
 
 class WithCurrentValueFromObservableClass<A, B>
   extends SyncChildObservableClass<readonly [A, B], readonly [A]>

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

@@ -21,15 +21,37 @@ import {
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  num$             1    2    3
+ * //  withInitial$ 0   1    2    3
+ * //               ^
+ * //               initial value
+ * //
+ * //  Explanation:
+ * //  - withInitialValue provides an initial value before the source emits
+ * //  - Converts an uninitialized observable to an initialized one
+ * //  - Useful when you need a default value immediately
+ *
  * const num$ = source<number>();
  *
  * const initialized$ = num$.pipe(withInitialValue(0));
  *
+ * const mut_history: number[] = [];
+ *
  * initialized$.subscribe((x) => {
- *   console.log(x);
- * }); // immediately logs: 0
+ *   mut_history.push(x);
+ * });
+ *
+ * assert.deepStrictEqual(mut_history, [0]);
  *
  * num$.next(1); // logs: 1
+ *
+ * assert.deepStrictEqual(mut_history, [0, 1]);
+ *
+ * num$.next(2); // logs: 2
+ *
+ * assert.deepStrictEqual(mut_history, [0, 1, 2]);
  * ```
  */
 export const withInitialValue =

package/src/core/predefined/index.mts

@@ -0,0 +1 @@
+export * from './operators/index.mjs';

package/src/core/predefined/operators/attach-index.mts

@@ -0,0 +1,13 @@
+import { mapWithIndex } from '../../operators/index.mjs';
+import { type KeepInitialValueOperator } from '../../types/index.mjs';
+
+export const withIndex = <A,>(): KeepInitialValueOperator<
+  A,
+  readonly [SafeUint | -1, A]
+> => mapWithIndex((a, i) => [i, a] as const);
+
+/**
+ * Alias for `withIndex`.
+ * @see withIndex
+ */
+export const attachIndex = withIndex;

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

@@ -0,0 +1,12 @@
+export * from './attach-index.mjs';
+export * from './map-optional.mjs';
+export * from './map-result-err.mjs';
+export * from './map-result-ok.mjs';
+export * from './map-to.mjs';
+export * from './map.mjs';
+export * from './pluck.mjs';
+export * from './skip.mjs';
+export * from './take.mjs';
+export * from './unwrap-optional.mjs';
+export * from './unwrap-result-err.mjs';
+export * from './unwrap-result-ok.mjs';

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

@@ -0,0 +1,8 @@
+import { Optional } from 'ts-data-forge';
+import { type KeepInitialValueOperator } from '../../types/index.mjs';
+import { map } from './map.mjs';
+
+export const mapOptional = <O extends UnknownOptional, B>(
+  mapFn: (x: Optional.Unwrap<O>) => B,
+): KeepInitialValueOperator<O, Optional<B>> =>
+  map((a) => Optional.map(a, mapFn));

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

@@ -0,0 +1,8 @@
+import { Result } from 'ts-data-forge';
+import { type KeepInitialValueOperator } from '../../types/index.mjs';
+import { map } from './map.mjs';
+
+export const mapResultErr = <R extends UnknownResult, E2>(
+  mapFn: (x: Result.UnwrapErr<R>) => E2,
+): KeepInitialValueOperator<R, Result<Result.UnwrapOk<R>, E2>> =>
+  map((a) => Result.mapErr(a, mapFn));

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

@@ -0,0 +1,8 @@
+import { Result } from 'ts-data-forge';
+import { type KeepInitialValueOperator } from '../../types/index.mjs';
+import { map } from './map.mjs';
+
+export const mapResultOk = <R extends UnknownResult, S2>(
+  mapFn: (x: Result.UnwrapOk<R>) => S2,
+): KeepInitialValueOperator<R, Result<S2, Result.UnwrapErr<R>>> =>
+  map((a) => Result.map(a, mapFn));

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

@@ -0,0 +1,5 @@
+import { type KeepInitialValueOperator } from '../../types/index.mjs';
+import { map } from './map.mjs';
+
+export const mapTo = <A, B>(value: B): KeepInitialValueOperator<A, B> =>
+  map(() => value);

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

@@ -0,0 +1,5 @@
+import { mapWithIndex } from '../../operators/index.mjs';
+import { type KeepInitialValueOperator } from '../../types/index.mjs';
+
+export const map = <A, B>(mapFn: (x: A) => B): KeepInitialValueOperator<A, B> =>
+  mapWithIndex(mapFn);

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

@@ -0,0 +1,12 @@
+import { type KeepInitialValueOperator } from '../../types/index.mjs';
+import { map } from './map.mjs';
+
+export const pluck = <A, K extends keyof A>(
+  key: K,
+): KeepInitialValueOperator<A, A[K]> => map((a) => a[key]);
+
+/**
+ * Alias for `pluck`.
+ * @see pluck
+ */
+export const getKey = pluck;

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

@@ -0,0 +1,10 @@
+import { PositiveSafeInt } from 'ts-data-forge';
+import { skipWhile } from '../../operators/index.mjs';
+import { type DropInitialValueOperator } from '../../types/index.mjs';
+
+export const skip = <A,>(
+  n: PositiveSafeIntWithSmallInt,
+): DropInitialValueOperator<A, A> =>
+  !PositiveSafeInt.is(n) ? idFn : skipWhile((_, index) => index + 1 <= n);
+
+const idFn = <T,>(value: T): T => value;

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

@@ -0,0 +1,6 @@
+import { takeWhile } from '../../operators/index.mjs';
+import { type DropInitialValueOperator } from '../../types/index.mjs';
+
+export const take = <A,>(
+  n: PositiveSafeIntWithSmallInt,
+): DropInitialValueOperator<A, A> => takeWhile((_, index) => index + 1 <= n);

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

@@ -0,0 +1,9 @@
+import { Optional } from 'ts-data-forge';
+import { type KeepInitialValueOperator } from '../../types/index.mjs';
+import { map } from './map.mjs';
+
+export const unwrapOptional = <
+  O extends UnknownOptional,
+>(): KeepInitialValueOperator<O, Optional.Unwrap<O> | undefined> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  map(Optional.unwrap as Fn<O, Optional.Unwrap<O> | undefined>);

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

@@ -0,0 +1,8 @@
+import { Result } from 'ts-data-forge';
+import { type KeepInitialValueOperator } from '../../types/index.mjs';
+import { map } from './map.mjs';
+
+export const unwrapResultErr = <
+  R extends UnknownResult,
+>(): KeepInitialValueOperator<R, Result.UnwrapErr<R> | undefined> =>
+  map(Result.unwrapErr as Fn<R, Result.UnwrapErr<R> | undefined>);

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

@@ -0,0 +1,9 @@
+import { Result } from 'ts-data-forge';
+import { type KeepInitialValueOperator } from '../../types/index.mjs';
+import { map } from './map.mjs';
+
+export const unwrapResultOk = <
+  R extends UnknownResult,
+>(): KeepInitialValueOperator<R, Result.UnwrapOk<R> | undefined> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  map(Result.unwrapOk as Fn<R, Result.UnwrapOk<R> | undefined>);

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

@@ -65,7 +65,7 @@ export type ScanOperatorObservable<A, B> = InitializedSyncChildObservable<
 
 // SyncChildObservable
 
-namespace SyncFlowInternals {
+namespace SynStateInternals {
   type Cast<A> = A extends NonEmptyUnknownList ? A : never;
 
   type EveryInitialized<OS extends NonEmptyArray<Observable<unknown>>> =
@@ -164,25 +164,25 @@ namespace SyncFlowInternals {
 }
 
 export type CombineObservable<A extends NonEmptyUnknownList> =
-  SyncFlowInternals.CombineObservableImpl<A>;
+  SynStateInternals.CombineObservableImpl<A>;
 
 export type CombineObservableRefined<
   OS extends NonEmptyArray<Observable<unknown>>,
-> = SyncFlowInternals.CombineObservableRefinedImpl<OS>;
+> = SynStateInternals.CombineObservableRefinedImpl<OS>;
 
 export type ZipObservable<A extends NonEmptyUnknownList> =
-  SyncFlowInternals.ZipObservableImpl<A>;
+  SynStateInternals.ZipObservableImpl<A>;
 
 export type ZipObservableRefined<
   OS extends NonEmptyArray<Observable<unknown>>,
-> = SyncFlowInternals.ZipObservableRefinedImpl<OS>;
+> = SynStateInternals.ZipObservableRefinedImpl<OS>;
 
 export type MergeObservable<A extends NonEmptyUnknownList> =
-  SyncFlowInternals.MergeObservableImpl<A>;
+  SynStateInternals.MergeObservableImpl<A>;
 
 export type MergeObservableRefined<
   OS extends NonEmptyArray<Observable<unknown>>,
-> = SyncFlowInternals.MergeObservableRefinedImpl<OS>;
+> = SynStateInternals.MergeObservableRefinedImpl<OS>;
 
 export type MapWithIndexOperatorObservable<A, B> = SyncChildObservable<
   B,

package/src/utils/create-event-emitter.mts

@@ -10,11 +10,21 @@ import { source, type Observable } from '../core/index.mjs';
  * ```ts
  * const [click$, emitClick] = createEventEmitter();
  *
+ * const mut_clickCount = { value: 0 };
+ *
  * click$.subscribe(() => {
- *   console.log('Clicked!');
+ *   mut_clickCount.value += 1;
  * });
  *
  * emitClick(); // logs: Clicked!
+ *
+ * assert.deepStrictEqual(mut_clickCount.value, 1);
+ *
+ * emitClick();
+ *
+ * emitClick();
+ *
+ * assert.deepStrictEqual(mut_clickCount.value, 3);
  * ```
  */
 export const createEventEmitter = (): readonly [
@@ -41,11 +51,19 @@ export const createEventEmitter = (): readonly [
  * ```ts
  * const [message$, emitMessage] = createValueEmitter<string>();
  *
+ * const mut_history: string[] = [];
+ *
  * message$.subscribe((msg) => {
- *   console.log(msg);
+ *   mut_history.push(msg);
  * });
  *
  * emitMessage('Hello'); // logs: Hello
+ *
+ * assert.deepStrictEqual(mut_history, ['Hello']);
+ *
+ * emitMessage('World');
+ *
+ * assert.deepStrictEqual(mut_history, ['Hello', 'World']);
  * ```
  */
 export const createValueEmitter = <A,>(): readonly [

package/src/utils/create-reducer.mts

@@ -24,11 +24,23 @@ import { source, type InitializedObservable } from '../core/index.mjs';
  *   0,
  * );
  *
+ * const mut_history: number[] = [];
+ *
  * state.subscribe((value: number) => {
- *   console.log(value);
+ *   mut_history.push(value);
  * });
  *
+ * assert.deepStrictEqual(mut_history, [0]);
+ *
  * dispatch({ type: 'increment' }); // logs: 1
+ *
+ * assert.deepStrictEqual(mut_history, [0, 1]);
+ *
+ * dispatch({ type: 'increment' });
+ *
+ * dispatch({ type: 'decrement' });
+ *
+ * assert.deepStrictEqual(mut_history, [0, 1, 2, 1]);
  * ```
  */
 export const createReducer = <S, A>(