synstate 0.1.0 → 0.1.2

package/dist/utils/create-reducer.mjs

@@ -27,11 +27,23 @@ import { source } from '../core/create/source.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]);
  * ```
  */
 const createReducer = (reducer, initialState) => {

package/dist/utils/create-reducer.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"create-reducer.mjs","sources":["../../src/utils/create-reducer.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BG;MACU,aAAa,GAAG,CAC3B,OAAsB,EACtB,YAAe,KAKb;AACF,IAAA,MAAM,KAAK,GAAG,MAAM,CAAI,YAAY,CAAC;AAErC,IAAA,MAAM,QAAQ,GAAG,CAAC,MAAS,KAAO;AAChC,QAAA,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC;AAE5D,QAAA,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;AAErB,QAAA,OAAO,SAAS;AAClB,IAAA,CAAC;IAED,MAAM,WAAW,GAAG,MAAS,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK;AAEtD,IAAA,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAU;AAChD;;;;"}
+{"version":3,"file":"create-reducer.mjs","sources":["../../src/utils/create-reducer.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CG;MACU,aAAa,GAAG,CAC3B,OAAsB,EACtB,YAAe,KAKb;AACF,IAAA,MAAM,KAAK,GAAG,MAAM,CAAI,YAAY,CAAC;AAErC,IAAA,MAAM,QAAQ,GAAG,CAAC,MAAS,KAAO;AAChC,QAAA,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC;AAE5D,QAAA,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;AAErB,QAAA,OAAO,SAAS;AAClB,IAAA,CAAC;IAED,MAAM,WAAW,GAAG,MAAS,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK;AAEtD,IAAA,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAU;AAChD;;;;"}

package/dist/utils/create-state.d.mts

@@ -11,15 +11,25 @@ import { type InitializedObservable } from '../core/index.mjs';
  * ```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 declare const createState: <S>(initialState: S) => readonly [state: InitializedObservable<S>, setState: (v: S) => S, Readonly<{
@@ -38,15 +48,25 @@ export declare const createState: <S>(initialState: S) => readonly [state: Initi
  * ```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 declare const createBooleanState: (initialState: boolean) => readonly [state: InitializedObservable<boolean>, Readonly<{

package/dist/utils/create-state.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"create-state.d.mts","sourceRoot":"","sources":["../../src/utils/create-state.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAwB/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAC3B,cAAc,CAAC,KACd,SAAS,CACV,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,EAC/B,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EACrB,QAAQ,CAAC;IACP,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7C,UAAU,EAAE,MAAM,CAAC,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,CAAC;CACtB,CAAC,CAwBH,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,kBAAkB,GAC7B,cAAc,OAAO,KACpB,SAAS,CACV,KAAK,EAAE,qBAAqB,CAAC,OAAO,CAAC,EACrC,QAAQ,CAAC;IACP,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;IACrC,MAAM,EAAE,MAAM,OAAO,CAAC;IACtB,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,KAAK,OAAO,CAAC;IAC/D,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,WAAW,EAAE,MAAM,OAAO,CAAC;CAC5B,CAAC,CAqBH,CAAC"}
+{"version":3,"file":"create-state.d.mts","sourceRoot":"","sources":["../../src/utils/create-state.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAwB/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAC3B,cAAc,CAAC,KACd,SAAS,CACV,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,EAC/B,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EACrB,QAAQ,CAAC;IACP,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7C,UAAU,EAAE,MAAM,CAAC,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,CAAC;CACtB,CAAC,CAwBH,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,kBAAkB,GAC7B,cAAc,OAAO,KACpB,SAAS,CACV,KAAK,EAAE,qBAAqB,CAAC,OAAO,CAAC,EACrC,QAAQ,CAAC;IACP,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;IACrC,MAAM,EAAE,MAAM,OAAO,CAAC;IACtB,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,KAAK,OAAO,CAAC;IAC/D,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,WAAW,EAAE,MAAM,OAAO,CAAC;CAC5B,CAAC,CAqBH,CAAC"}

package/dist/utils/create-state.mjs

@@ -20,15 +20,25 @@ const reducer = (state, action) => {
  * ```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]);
  * ```
  */
 const createState = (initialState) => {
@@ -57,15 +67,25 @@ const createState = (initialState) => {
  * ```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]);
  * ```
  */
 const createBooleanState = (initialState) => {

package/dist/utils/create-state.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"create-state.mjs","sources":["../../src/utils/create-state.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAcA,MAAM,OAAO,GAAG,CAAK,KAAQ,EAAE,MAAiB,KAAO;AACrD,IAAA,QAAQ,MAAM,CAAC,IAAI;AACjB,QAAA,KAAK,KAAK;YACR,OAAO,MAAM,CAAC,SAAS;AAEzB,QAAA,KAAK,QAAQ;AACX,YAAA,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;;AAEnC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;AAsBG;AACI,MAAM,WAAW,GAAG,CACzB,YAAe,KASb;AACF,IAAA,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,GAAG,aAAa,CAClD,OAAO,EACP,YAAY,CACb;AAED,IAAA,MAAM,WAAW,GAAG,CAAC,QAAwB,KAC3C,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAExC,IAAA,MAAM,QAAQ,GAAG,CAAC,SAAY,KAAQ,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAE1E,IAAA,MAAM,UAAU,GAAG,MACjB,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;IAEpD,OAAO;QACL,KAAK;QACL,QAAQ;AACR,QAAA;YACE,WAAW;YACX,UAAU;YACV,WAAW;AACZ,SAAA;KACO;AACZ;AAEA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACI,MAAM,kBAAkB,GAAG,CAChC,YAAqB,KAYnB;AACF,IAAA,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,GAC/D,WAAW,CAAC,YAAY,CAAC;IAE3B,OAAO;QACL,KAAK;AACL,QAAA;YACE,OAAO,EAAE,MAAK;gBACZ,QAAQ,CAAC,IAAI,CAAC;YAChB,CAAC;YACD,QAAQ,EAAE,MAAK;gBACb,QAAQ,CAAC,KAAK,CAAC;YACjB,CAAC;AACD,YAAA,MAAM,EAAE,MAAM,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;YACpC,QAAQ;YACR,WAAW;YACX,UAAU;YACV,WAAW;AACZ,SAAA;KACO;AACZ;;;;"}
+{"version":3,"file":"create-state.mjs","sources":["../../src/utils/create-state.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAcA,MAAM,OAAO,GAAG,CAAK,KAAQ,EAAE,MAAiB,KAAO;AACrD,IAAA,QAAQ,MAAM,CAAC,IAAI;AACjB,QAAA,KAAK,KAAK;YACR,OAAO,MAAM,CAAC,SAAS;AAEzB,QAAA,KAAK,QAAQ;AACX,YAAA,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;;AAEnC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCG;AACI,MAAM,WAAW,GAAG,CACzB,YAAe,KASb;AACF,IAAA,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,GAAG,aAAa,CAClD,OAAO,EACP,YAAY,CACb;AAED,IAAA,MAAM,WAAW,GAAG,CAAC,QAAwB,KAC3C,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAExC,IAAA,MAAM,QAAQ,GAAG,CAAC,SAAY,KAAQ,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAE1E,IAAA,MAAM,UAAU,GAAG,MACjB,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;IAEpD,OAAO;QACL,KAAK;QACL,QAAQ;AACR,QAAA;YACE,WAAW;YACX,UAAU;YACV,WAAW;AACZ,SAAA;KACO;AACZ;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BG;AACI,MAAM,kBAAkB,GAAG,CAChC,YAAqB,KAYnB;AACF,IAAA,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,GAC/D,WAAW,CAAC,YAAY,CAAC;IAE3B,OAAO;QACL,KAAK;AACL,QAAA;YACE,OAAO,EAAE,MAAK;gBACZ,QAAQ,CAAC,IAAI,CAAC;YAChB,CAAC;YACD,QAAQ,EAAE,MAAK;gBACb,QAAQ,CAAC,KAAK,CAAC;YACjB,CAAC;AACD,YAAA,MAAM,EAAE,MAAM,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;YACpC,QAAQ;YACR,WAAW;YACX,UAAU;YACV,WAAW;AACZ,SAAA;KACO;AACZ;;;;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "synstate",
-  "version": "0.1.0",
-  "description": "Reactive Programming Library for TypeScript/JavaScript",
+  "version": "0.1.2",
+  "description": "Type-safe State Management Library for TypeScript/JavaScript",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/noshiro-pf/synstate.git"
@@ -23,9 +23,19 @@
   "files": [
     "src",
     "dist",
+    "assets",
     "README.md",
     "LICENSE"
   ],
+  "dependencies": {
+    "ts-data-forge": "^6.5.0"
+  },
+  "devDependencies": {
+    "@types/argparse": "^2.0.17",
+    "@types/react": "^19.2.14",
+    "argparse": "^2.0.1",
+    "react": "^19.2.4"
+  },
   "scripts": {
     "build": "tsx ./scripts/cmd/build.mts",
     "build:min": "tsx ./scripts/cmd/build.mts --skip-check",
@@ -58,14 +68,5 @@
     "z:vitest": "vitest --config ./configs/vitest.config.mts",
     "z:vitest:node": "pnpm run z:vitest --project='Node.js'",
     "z:vitest:stream": "vitest --config ./configs/vitest.config.stream.ts"
-  },
-  "dependencies": {
-    "ts-data-forge": "^6.5.0"
-  },
-  "devDependencies": {
-    "@types/argparse": "^2.0.17",
-    "@types/react": "^19.2.14",
-    "argparse": "^2.0.1",
-    "react": "^19.2.4"
   }
-}
+}

package/src/core/combine/combine.mts

@@ -24,21 +24,51 @@ import {
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  name$     "Alice"                 "Bob"
+ * //  age$                25                        30
+ * //  user$               ["Alice",25]  ["Bob",25]  ["Bob",30]
+ * //
+ * //  Explanation:
+ * //  - combine waits for all sources to emit at least once
+ * //  - Then emits the latest value from all sources whenever any source emits
+ * //  - Always emits an array with the latest values from each source
+ *
  * const name$ = source<string>();
  *
  * const age$ = source<number>();
  *
  * const user$ = combine([name$, age$]);
  *
+ * const mut_history: (readonly [string, number])[] = [];
+ *
  * user$.subscribe(([name_, age]) => {
- *   console.log({ name: name_, age });
+ *   mut_history.push([name_, age]);
  * });
  *
- * name$.next('Alice');
+ * name$.next('Alice'); // nothing logged (age$ hasn't emitted yet)
+ *
+ * assert.deepStrictEqual(mut_history, []);
  *
  * age$.next(25); // logs: { name: 'Alice', age: 25 }
  *
+ * assert.deepStrictEqual(mut_history, [['Alice', 25]]);
+ *
  * name$.next('Bob'); // logs: { name: 'Bob', age: 25 }
+ *
+ * assert.deepStrictEqual(mut_history, [
+ *   ['Alice', 25],
+ *   ['Bob', 25],
+ * ]);
+ *
+ * age$.next(30); // logs: { name: 'Bob', age: 30 }
+ *
+ * assert.deepStrictEqual(mut_history, [
+ *   ['Alice', 25],
+ *   ['Bob', 25],
+ *   ['Bob', 30],
+ * ]);
  * ```
  */
 export const combine = <const OS extends NonEmptyArray<Observable<unknown>>>(
@@ -50,10 +80,10 @@ export const combine = <const OS extends NonEmptyArray<Observable<unknown>>>(
   ) as unknown as CombineObservableRefined<OS>;
 
 /**
- * Alias for `combine()`.
+ * Alias for `combine`.
  * @see combine
  */
-export const combineLatest = combine; // alias
+export const combineLatest = combine;
 
 class CombineObservableClass<const A extends NonEmptyUnknownList>
   extends SyncChildObservableClass<A, A>

package/src/core/combine/merge.mts

@@ -21,16 +21,42 @@ import {
  *
  * @example
  * ```ts
- * const clicks$ = source<MouseEvent>();
+ * //  Timeline:
+ * //
+ * //  clicks$   c1          c2                    c3
+ * //  keys$               k1          k2                    k3
+ * //  events$   c1        k1    c2    k2          c3        k3
+ * //
+ * //  Explanation:
+ * //  - merge combines multiple observables into one
+ * //  - Emits values from any source as they arrive
+ * //  - Order is preserved based on emission time
  *
- * const keys$ = source<KeyboardEvent>();
+ * const clicks$ = source<string>();
+ *
+ * const keys$ = source<string>();
  *
  * const events$ = merge([clicks$, keys$]);
  *
+ * const mut_history: string[] = [];
+ *
  * events$.subscribe((event_) => {
- *   console.log(event_);
+ *   mut_history.push(event_);
  * });
- * // Logs any mouse click or keyboard event
+ *
+ * clicks$.next('c1');
+ *
+ * assert.deepStrictEqual(mut_history, ['c1']);
+ *
+ * keys$.next('k1');
+ *
+ * assert.deepStrictEqual(mut_history, ['c1', 'k1']);
+ *
+ * clicks$.next('c2');
+ *
+ * keys$.next('k2');
+ *
+ * assert.deepStrictEqual(mut_history, ['c1', 'k1', 'c2', 'k2']);
  * ```
  *
  * @note To improve code readability, consider using `createState` instead of `merge`,

package/src/core/combine/zip.mts

@@ -26,16 +26,41 @@ import {
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  letters$  'a'       'b'       'c'
+ * //  numbers$  1         2         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 numbers$ = fromArray([1, 2, 3]);
  *
  * const zipped$ = zip([letters$, numbers$]);
  *
- * zipped$.subscribe(([letter, num]) => {
- *   console.log(letter, num);
+ * const mut_history: (readonly [string, number])[] = [];
+ *
+ * await new Promise<void>((resolve) => {
+ *   zipped$.subscribe(
+ *     ([letter, num]) => {
+ *       mut_history.push([letter, num]);
+ *     },
+ *     () => {
+ *       resolve();
+ *     },
+ *   );
  * });
- * // logs: a 1, b 2, c 3
+ *
+ * assert.deepStrictEqual(mut_history, [
+ *   ['a', 1],
+ *   ['b', 2],
+ *   ['c', 3],
+ * ]);
  * ```
  */
 export const zip = <const OS extends NonEmptyArray<Observable<unknown>>>(

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

@@ -12,12 +12,30 @@ import { type FromArrayObservable } from '../types/index.mjs';
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  nums$     1     2     3     | (completes)
+ * //
+ * //  Explanation:
+ * //  - fromArray creates an observable from an array
+ * //  - Emits all values synchronously, then completes
+ *
  * const nums$ = fromArray([1, 2, 3]);
  *
- * nums$.subscribe((x) => {
- *   console.log(x);
+ * const mut_history: number[] = [];
+ *
+ * await new Promise<void>((resolve) => {
+ *   nums$.subscribe(
+ *     (x) => {
+ *       mut_history.push(x);
+ *     },
+ *     () => {
+ *       resolve();
+ *     },
+ *   );
  * });
- * // logs: 1, 2, 3
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2, 3]);
  * ```
  */
 export const fromArray = <A,>(

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

@@ -13,15 +13,37 @@ import { type FromPromiseObservable } from '../types/index.mjs';
  *
  * @example
  * ```ts
- * const data$ = fromPromise(fetch('/api/data').then((r) => r.json()));
+ * //  Timeline:
+ * //
+ * //  promise     [pending...]  -> resolved/rejected
+ * //  data$                     Ok(value) or Err(error)
+ * //
+ * //  Explanation:
+ * //  - fromPromise converts a Promise into an observable
+ * //  - Emits a Result type: Ok(value) on success, Err(error) on failure
+ * //  - Completes after emitting the result
+ * //  - Useful for integrating async operations into reactive flows
  *
- * data$.subscribe((result) => {
- *   if (Result.isOk(result)) {
- *     console.log('Data:', result.value);
- *   } else {
- *     console.error('Error:', result.value);
- *   }
+ * const fetchData = async (): Promise<{ value: number }> => ({ value: 42 });
+ *
+ * const data$ = fromPromise(fetchData());
+ *
+ * const mut_history: { value: number }[] = [];
+ *
+ * await new Promise<void>((resolve) => {
+ *   data$.subscribe(
+ *     (result) => {
+ *       if (Result.isOk(result)) {
+ *         mut_history.push(result.value);
+ *       }
+ *     },
+ *     () => {
+ *       resolve();
+ *     },
+ *   );
  * });
+ *
+ * assert.deepStrictEqual(mut_history, [{ value: 42 }]);
  * ```
  */
 export const fromPromise = <A, E = unknown>(

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

@@ -5,6 +5,64 @@ import {
   type Subscribable,
 } from '../types/index.mjs';
 
+/**
+ * Converts any subscribable object into a SynState Observable.
+ * Works with objects that have a subscribe(onNext, onError, onComplete) method.
+ *
+ * @template A - The type of values from the subscribable
+ * @template E - The type of errors from the subscribable
+ * @param subscribable - An object with a subscribe method
+ * @returns An observable that wraps values in Result type
+ *
+ * @example
+ * ```ts
+ * //  Explanation:
+ * //  - fromSubscribable converts any subscribable object into a SynState Observable
+ * //  - Works with objects that have a subscribe(onNext, onError, onComplete) method
+ * //  - Wraps values in Result type for error handling
+ * //  - Useful for integrating with other reactive libraries or custom subscribables
+ *
+ * // Example: Converting a custom subscribable
+ * const customSubscribable = {
+ *   subscribe: (
+ *     onNext: (value: number) => void,
+ *     _onError?: (error: unknown) => void,
+ *     onComplete?: () => void,
+ *   ) => {
+ *     setTimeout(() => {
+ *       onNext(1);
+ *
+ *       onNext(2);
+ *
+ *       onNext(3);
+ *
+ *       onComplete?.();
+ *     }, 0);
+ *
+ *     return { unsubscribe: () => {} };
+ *   },
+ * };
+ *
+ * const observable$ = fromSubscribable<number>(customSubscribable);
+ *
+ * const mut_history: number[] = [];
+ *
+ * await new Promise<void>((resolve) => {
+ *   observable$.subscribe(
+ *     (result) => {
+ *       if (Result.isOk(result)) {
+ *         mut_history.push(result.value);
+ *       }
+ *     },
+ *     () => {
+ *       resolve();
+ *     },
+ *   );
+ * });
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2, 3]);
+ * ```
+ */
 export const fromSubscribable = <A, E = unknown>(
   subscribable: Subscribable<A>,
 ): FromSubscribableObservable<A, E> =>

package/src/core/create/interval.mts

@@ -12,12 +12,37 @@ import { type IntervalObservable } from '../types/index.mjs';
  *
  * @example
  * ```ts
- * const tick$ = interval(1000);
+ * //  Timeline:
+ * //
+ * //  Time(s)   0     1     2     3     4     5
+ * //  tick$     0     1     2     3     4     5     ...
+ * //
+ * //  Explanation:
+ * //  - interval emits incrementing numbers at specified intervals
+ * //  - Starts at 0 and continues indefinitely
+ * //  - Useful for periodic tasks or animations
  *
- * tick$.subscribe((count) => {
- *   console.log(count);
+ * const tick$ = interval(100);
+ *
+ * const mut_history: number[] = [];
+ *
+ * const subscription = tick$.subscribe((count) => {
+ *   mut_history.push(count);
  * });
- * // logs: 0, 1, 2, 3, ... every second
+ *
+ * await new Promise((resolve) => {
+ *   setTimeout(resolve, 350);
+ * });
+ *
+ * subscription.unsubscribe();
+ *
+ * assert.isTrue(Arr.isArrayAtLeastLength(mut_history, 3));
+ *
+ * assert.deepStrictEqual(mut_history[0], 0);
+ *
+ * assert.deepStrictEqual(mut_history[1], 1);
+ *
+ * assert.deepStrictEqual(mut_history[2], 2);
  * ```
  */
 export const interval = (

package/src/core/create/of.mts

@@ -12,11 +12,30 @@ import { type OfObservable } from '../types/index.mjs';
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  num$    42  | (completes immediately)
+ * //
+ * //  Explanation:
+ * //  - of creates an observable that emits a single value, then completes
+ * //  - Useful for converting a static value into an observable
+ *
  * const num$ = of(42);
  *
- * num$.subscribe((x) => {
- *   console.log(x);
- * }); // logs: 42
+ * const mut_history: number[] = [];
+ *
+ * await new Promise<void>((resolve) => {
+ *   num$.subscribe(
+ *     (x) => {
+ *       mut_history.push(x);
+ *     },
+ *     () => {
+ *       resolve();
+ *     },
+ *   );
+ * });
+ *
+ * assert.deepStrictEqual(mut_history, [42]);
  * ```
  */
 export const of = <A,>(

package/src/core/create/source.mts

@@ -14,15 +14,34 @@ import {
  *
  * @example
  * ```ts
+ * //  Timeline:
+ * //
+ * //  count$    1     2     3     ...
+ * //
+ * //  Explanation:
+ * //  - source creates a new observable that you can manually emit values to
+ * //  - Use .next() to emit values
+ * //  - Foundation for building custom observables
+ *
  * const count$ = source<number>();
  *
+ * const mut_history: number[] = [];
+ *
  * count$.subscribe((value) => {
- *   console.log(value);
+ *   mut_history.push(value);
  * });
  *
  * count$.next(1); // logs: 1
  *
+ * assert.deepStrictEqual(mut_history, [1]);
+ *
  * count$.next(2); // logs: 2
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2]);
+ *
+ * count$.next(3); // logs: 3
+ *
+ * assert.deepStrictEqual(mut_history, [1, 2, 3]);
  * ```
  */
 export function source<A>(initialValue: A): InitializedSourceObservable<A>;
@@ -34,10 +53,10 @@ export function source<A>(...args: readonly A[]): SourceObservable<A> {
 }
 
 /**
- * Alias for `source()`. Creates a new Observable source.
+ * Alias for `source`. Creates a new Observable source.
  * @see source
  */
-export const subject = source; // alias
+export const subject = source;
 
 class SourceObservableClass<A>
   extends RootObservableClass<A>

package/src/core/create/timer.mts

@@ -11,12 +11,31 @@ import { type TimerObservable } from '../types/index.mjs';
  *
  * @example
  * ```ts
- * const delayed$ = timer(1000);
+ * //  Timeline:
+ * //
+ * //  Time(ms)  0     ...   1000
+ * //  delayed$                X (emits and completes)
+ * //
+ * //  Explanation:
+ * //  - timer emits once after the specified delay, then completes
+ * //  - Useful for delayed actions or timeouts
  *
- * delayed$.subscribe(() => {
- *   console.log('1 second passed');
+ * const delayed$ = timer(100);
+ *
+ * const mut_history: number[] = [];
+ *
+ * await new Promise<void>((resolve) => {
+ *   delayed$.subscribe(
+ *     () => {
+ *       mut_history.push(1);
+ *     },
+ *     () => {
+ *       resolve();
+ *     },
+ *   );
  * });
- * // After 1 second, logs: 1 second passed
+ *
+ * assert.deepStrictEqual(mut_history, [1]);
  * ```
  */
 export const timer = (

package/src/core/index.mts

@@ -2,5 +2,6 @@ export * from './class/index.mjs';
 export * from './combine/index.mjs';
 export * from './create/index.mjs';
 export * from './operators/index.mjs';
+export * from './predefined/index.mjs';
 export * from './types/index.mjs';
 export * from './utils/index.mjs';