synstate 0.1.0 → 0.1.1

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>,

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/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>(

package/src/utils/create-state.mts

@@ -34,15 +34,25 @@ const reducer = <S,>(state: S, action: Action<S>): S => {
  * ```ts
  * const [state, setState, { updateState, resetState }] = createState(0);
  *
+ * const mut_history: number[] = [];
+ *
  * state.subscribe((value: number) => {
- *   console.log(value);
- * }); // logs: 0
+ *   mut_history.push(value);
+ * });
+ *
+ * assert.deepStrictEqual(mut_history, [0]);
  *
  * setState(10); // logs: 10
  *
+ * assert.deepStrictEqual(mut_history, [0, 10]);
+ *
  * updateState((prev: number) => prev + 1); // logs: 11
  *
+ * assert.deepStrictEqual(mut_history, [0, 10, 11]);
+ *
  * resetState(); // logs: 0
+ *
+ * assert.deepStrictEqual(mut_history, [0, 10, 11, 0]);
  * ```
  */
 export const createState = <S,>(
@@ -91,15 +101,25 @@ export const createState = <S,>(
  * ```ts
  * const [state, { setTrue, toggle }] = createBooleanState(false);
  *
+ * const mut_history: boolean[] = [];
+ *
  * state.subscribe((value: boolean) => {
- *   console.log(value);
- * }); // logs: false
+ *   mut_history.push(value);
+ * });
+ *
+ * assert.deepStrictEqual(mut_history, [false]);
  *
  * setTrue(); // logs: true
  *
+ * assert.deepStrictEqual(mut_history, [false, true]);
+ *
  * toggle(); // logs: false
  *
+ * assert.deepStrictEqual(mut_history, [false, true, false]);
+ *
  * toggle(); // logs: true
+ *
+ * assert.deepStrictEqual(mut_history, [false, true, false, true]);
  * ```
  */
 export const createBooleanState = (