synstate 0.1.1 → 1.0.0

package/README.md

@@ -9,26 +9,30 @@
 [![npm version](https://img.shields.io/npm/v/synstate.svg)](https://www.npmjs.com/package/synstate)
 [![npm downloads](https://img.shields.io/npm/dm/synstate.svg)](https://www.npmjs.com/package/synstate)
 [![License](https://img.shields.io/npm/l/synstate.svg)](./LICENSE)
-[![codecov](https://codecov.io/gh/noshiro-pf/synstate/graph/badge.svg?token=xrJgTVxMpr)](https://codecov.io/gh/noshiro-pf/synstate)
+[![codecov](https://codecov.io/gh/noshiro-pf/synstate/graph/badge.svg)](https://codecov.io/gh/noshiro-pf/synstate)
 
 </p>
 
-**SynState** is a lightweight, high-performance, type-safe state management library for TypeScript/JavaScript. Perfect for building reactive global state and event-driven systems in React, Vue, and other frameworks.
+**SynState** is a lightweight, high-performance, type-safe state management library for TypeScript/JavaScript applications. Perfect for building reactive global state and event-driven systems in React, Vue, and other frameworks.
+
+"SynState" is named after "Synchronized + State." It represents a sound synchronized state through a **glitch-free**[^1] Observable implementation.
+
+[^1]: See ["How SynState solved the glitch?"](./documents/how-synstate-solved-the-glitch.md).
 
 ## Features
 
-- 🎯 **Simple State Management**: Easy-to-use `createState` and `createReducer` for global state
-- 📡 **Event System**: Built-in `createValueEmitter`, `createEventEmitter` for event-driven architecture
-- 🔄 **Reactive Updates**: Automatic propagation of state changes to subscribers
-- 🎨 **Type-Safe**: Full TypeScript support with precise type inference
-- 🚀 **Lightweight**: Minimal bundle size with only one external runtime dependency ([ts-data-forge](https://www.npmjs.com/package/ts-data-forge))
+- 🎯 **Simple State Management**: Easy-to-use `createState` and `createReducer` similar to React useState/useReducer for global state
 - ⚡ **High Performance**: Optimized for fast state updates and minimal re-renders
+- 🎨 **Type-Safe**: Full TypeScript support with precise type inference
+- 🚀 **Lightweight**: <!-- bundle-size:synstate -->~4.5 kB min+gzip<!-- /bundle-size:synstate --> with only one external runtime dependency ([ts-data-forge](https://www.npmjs.com/package/ts-data-forge))
 - 🌐 **Framework Agnostic**: Works with React, Vue, Svelte, or vanilla JavaScript
-- 🔧 **Flexible**: Simple state management with optional advanced Observable-based features (operators like `map`, `filter`, `debounceTime`, `throttleTime`, and combinators like `merge`, `combine`)
+- 🔄 **Reactive Updates**: Automatic propagation of state changes to all subscribers
+- 📡 **Event System**: Built-in `createValueEmitter`, `createEventEmitter` for event-driven architecture
+- 🔧 **Observable-based**: Built on Observable pattern similar to RxJS, but with a completely independent implementation from scratch — not a wrapper. Offers optional advanced features like operators (`map`, `filter`, `scan`, `debounce`) and combinators (`merge`, `combine`)
 
 ## Documentation
 
-- API reference: TBD <!-- <https://noshiro-pf.github.io/synstate/> -->
+- <https://noshiro-pf.github.io/synstate/>
 
 ## Installation
 
@@ -52,28 +56,103 @@ pnpm add synstate
 
 ```tsx
 // Create a reactive state
-const [state, setState, { updateState }] = createState(0);
+const [state, setState] = createState(0);
+// type of state: InitializedObservable<number>
+// type of setState: (v: number) => number
 
-const mut_history: number[] = [];
+const stateHistory: number[] = [];
 
-// Subscribe to changes (in React components, Vue watchers, etc.)
-state.subscribe((count: number) => {
-    mut_history.push(count);
+// Subscribe to changes
+state.subscribe((count) => {
+    stateHistory.push(count);
 });
 
-assert.deepStrictEqual(mut_history, [0]);
+assert.deepStrictEqual(stateHistory, [0]);
 
 // Update state
 setState(1);
 
-assert.deepStrictEqual(mut_history, [0, 1]);
+assert.deepStrictEqual(stateHistory, [0, 1]);
+```
 
-updateState((prev: number) => prev + 1);
+### With React
 
-assert.deepStrictEqual(mut_history, [0, 1, 2]);
+```bash
+npm add synstate-react-hooks
 ```
 
-### With React
+```tsx
+import type * as React from 'react';
+import { createState } from 'synstate-react-hooks';
+
+const [useUserState, setUserState] = createState({
+    name: '',
+    email: '',
+});
+
+const UserProfile = (): React.JSX.Element => {
+    const user = useUserState();
+
+    return (
+        <div>
+            <p>{`Name: ${user.name}`}</p>
+            <button
+                onClick={() => {
+                    setUserState({
+                        name: 'Alice',
+                        email: 'alice@example.com',
+                    });
+                }}
+            >
+                {'Set User'}
+            </button>
+        </div>
+    );
+};
+```
+
+This is equivalent to the following code without synstate-react-hook:
+
+```tsx
+import * as React from 'react';
+import { createState } from 'synstate';
+
+const [userState, setUserState] = createState({
+    name: '',
+    email: '',
+});
+
+const UserProfile = (): React.JSX.Element => {
+    const user = React.useSyncExternalStore(
+        (onStoreChange: () => void) => {
+            const { unsubscribe } = userState.subscribe(onStoreChange);
+
+            return unsubscribe;
+        },
+        () => userState.getSnapshot().value,
+    );
+
+    return (
+        <div>
+            <p>{`Name: ${user.name}`}</p>
+            <button
+                onClick={() => {
+                    setUserState({
+                        name: 'Alice',
+                        email: 'alice@example.com',
+                    });
+                }}
+            >
+                {'Set User'}
+            </button>
+        </div>
+    );
+};
+```
+
+See also the [synstate-react-hooks README](../synstate-react-hooks/README.md).
+
+If you're using React v17 or earlier:
 
 ```tsx
 import * as React from 'react';
@@ -98,10 +177,7 @@ const UserProfile = (): React.JSX.Element => {
 
     return (
         <div>
-            <p>
-                {'Name: '}
-                {user.name}
-            </p>
+            <p>{`Name: ${user.name}`}</p>
             <button
                 onClick={() => {
                     setUserState({
@@ -117,207 +193,135 @@ const UserProfile = (): React.JSX.Element => {
 };
 ```
 
-## Core Concepts
-
-### State Management
+## Why SynState?
 
-SynState provides simple, intuitive APIs for managing application state:
+### Simple to Start, Powerful When You Need It
 
-- **`createState`**: Create mutable state with getter/setter
-- **`createReducer`**: Redux-style state management
-- **`createBooleanState`**: Specialized state for boolean values
+SynState is a state management library for web frontends. For most use cases, `createState`, `createReducer`, and simple combinators like `combine` and `map` are all you need — clean, minimal APIs that feel as intuitive as React's `useState` / `useReducer`, but for global state.
 
-### Event System
+When your requirements grow more complex, SynState scales with you. Built on its own Observable implementation, it provides operators like `debounce`, `throttle`, `switchMap`, and `mergeMap` for sophisticated asynchronous state management — without requiring an additional library like RxJS. You can describe everything from a simple counter to a debounced search pipeline with auto-cancellation in a single, unified API.
 
-Built-in event emitter for event-driven patterns:
+### Why Observable-Based?
 
-- **`createValueEmitter`**: Create type-safe event emitters
-- **`createEventEmitter`**: Create event emitters without payload
+A state management library that scales from simple global state to complex asynchronous workflows needs **reactive value propagation** at its core — when one piece of state changes, all derived values must update automatically and consistently. The Observable pattern is a natural fit for this: it models state as streams of values that can be composed, transformed, and combined declaratively.
 
-### Observable (Optional Advanced Feature)
+RxJS is the most well-known Observable library, and it excels at modeling asynchronous event processing. However, RxJS has a fundamental issue known as **glitch**[^1] — a phenomenon where derived values can temporarily enter inconsistent intermediate states during synchronous propagation. For a state management library, where consistency of derived state is critical, this is unacceptable. SynState was built from scratch with a glitch-free Observable implementation to solve this problem.
 
-For advanced use cases, you can use observables to build complex reactive data flows. However, most applications will only need `createState`, `createReducer`, and `createValueEmitter`.
+For a detailed explanation, see ["How SynState solved the glitch?"](./documents/how-synstate-solved-the-glitch.md).
 
-## API Reference
+### Key Differences from RxJS
 
-<!-- ### State Management (Recommended)
+- **Glitch free**: While RxJS Observables suffer from a troublesome phenomenon called glitch [^1], SynState Observables are glitch-free.
+- **InitializedObservable**: Provides `InitializedObservable` which always holds an initial value, making it ideal for representing state
+- **Focus on State Management**: Designed specifically for state management, not just asynchronous event processing. SynState provides utility functions `createState`, `createReducer`, and `createBooleanState`. However, this doesn't mean it's inadequate for asynchronous event processing — it can handle asynchronous operations as elegantly as RxJS.
 
-#### createState
+### Use Cases
 
-Create reactive state with getter and setter.
+**Use SynState when you need:**
 
-#### createBooleanState
+- ✅ A small piece of global state shared across components (e.g., dark mode toggle, user session)
+- ✅ Complex asynchronous state management with operators like `debounce`, `throttle`, `switchMap`
+- ✅ Redux-like state with reducers (`createReducer`)
+- ✅ A project where the scale of state management is uncertain — SynState's unified API covers everything from a single shared counter to a full debounced search pipeline, so you never have to switch libraries as requirements grow
+- ✅ Type-safe event emitters (`createEventEmitter`)
 
-Specialized state for boolean values.
+**Consider other solutions when:**
 
-#### createReducer
+- You only need a React component (local) state (use React hooks `useState`, `useReducer`)
 
-Create state with reducer pattern (like Redux).
+## Examples
 
-### Event System
+### Simple State with Additional APIs
 
-#### createValueEmitter
+```tsx
+// Create a reactive state
+const [
+    state,
+    setState,
+    { updateState, resetState, getSnapshot, initialState },
+] = createState(0);
+// type of state: InitializedObservable<number>
+// type of setState: (v: number) => number
+// type of updateState: (updater: (prev: number) => number) => number
+// type of resetState: () => void
+// type of getSnapshot: () => number
+// type of initialState: number
+
+const stateHistory: number[] = [];
+
+// Subscribe to changes
+state.subscribe((count) => {
+    stateHistory.push(count);
+});
 
-Create type-safe event emitter with payload.
+assert.deepStrictEqual(stateHistory, [0]);
 
-#### createEventEmitter
+assert.strictEqual(getSnapshot(), 0);
 
-Create event emitter without payload.
--->
+// Update state
+setState(1);
 
-### Advanced Features (Optional)
+assert.strictEqual(getSnapshot(), 1);
 
-For complex scenarios, SynState provides observable-based APIs:
+assert.deepStrictEqual(stateHistory, [0, 1]);
 
-#### Creation Functions
+updateState((prev) => prev + 2);
 
-- `source<T>()`: Create a new observable source
-- `of(value)`: Create observable from a single value
-- `fromArray(array)`: Create observable from array
-- `fromPromise(promise)`: Create observable from promise
-- `interval(ms)`: Emit values at intervals
-- `timer(delay)`: Emit after delay
+assert.strictEqual(getSnapshot(), 3);
 
-#### Operators
+assert.deepStrictEqual(stateHistory, [0, 1, 3]);
 
-- `filter(predicate)`: Filter values
-- `map(fn)`: Transform values
-- `scan(reducer, seed)`: Accumulate values
-- `debounceTime(ms)`: Debounce emissions
-- `throttleTime(ms)`: Throttle emissions
-- `skipIfNoChange()`: Skip duplicate values
-- `takeUntil(notifier)`: Complete on notifier emission
+resetState();
 
-#### Combination
+assert.strictEqual(getSnapshot(), 0);
 
-- `combine(observables)`: Combine latest values from multiple sources
-- `merge(observables)`: Merge multiple streams
-- `zip(observables)`: Pair values by index
+assert.strictEqual(initialState, 0);
 
-## Examples
+assert.deepStrictEqual(stateHistory, [0, 1, 3, 0]);
+```
 
 ### Global Counter State (React)
 
 ```tsx
-import * as React from 'react';
-import { createState } from 'synstate';
+import type * as React from 'react';
+import { createState } from 'synstate-react-hooks';
 
 // Create global state
-export const [counterState, , { updateState, resetState, getSnapshot }] =
-    createState(0);
+export const [useCounterState, , { updateState, resetState }] = createState(0);
+
+const increment = (): void => {
+    updateState((n) => n + 1);
+};
 
 // Component 1
 const Counter = (): React.JSX.Element => {
-    const [count, setCount] = React.useState(getSnapshot());
-
-    React.useEffect(() => {
-        const sub = counterState.subscribe(setCount);
-
-        return () => {
-            sub.unsubscribe();
-        };
-    }, []);
+    const count = useCounterState();
 
     return (
         <div>
-            <p>
-                {'Count: '}
-                {count}
-            </p>
-            <button
-                onClick={() => {
-                    updateState((n: number) => n + 1);
-                }}
-            >
-                {'Increment'}
-            </button>
+            <p>{`Count: ${count}`}</p>
+            <button onClick={increment}>{'Increment'}</button>
         </div>
     );
 };
 
-// Component 2 (synced automatically)
+// Component 2
 const ResetButton = (): React.JSX.Element => (
-    <button
-        onClick={() => {
-            resetState();
-        }}
-    >
-        {'Reset'}
-    </button>
+    <button onClick={resetState}>{'Reset'}</button>
 );
 ```
 
-### Event-Driven Architecture (React)
-
-```tsx
-import * as React from 'react';
-import { createEventEmitter, createValueEmitter } from 'synstate';
-
-// Global events
-export const [userLoggedIn$, emitUserLoggedIn] = createValueEmitter<
-    Readonly<{
-        id: number;
-        name: string;
-    }>
->();
-
-export const [userLoggedOut$, emitUserLoggedOut] = createEventEmitter();
-
-// Component that emits events
-const LoginButton = (): React.JSX.Element => {
-    const handleLogin = React.useCallback(() => {
-        (async () => {
-            const user = await loginUser();
-
-            emitUserLoggedIn(user);
-        })().catch(() => {});
-    }, []);
-
-    return <button onClick={handleLogin}>{'Login'}</button>;
-};
-
-// Component that listens to events
-const NotificationPage = (): React.JSX.Element => {
-    const [message, setMessage] = React.useState('');
-
-    React.useEffect(() => {
-        const sub1 = userLoggedIn$.subscribe((user) => {
-            setMessage(`Welcome, ${user.name}!`);
-        });
-
-        const sub2 = userLoggedOut$.subscribe(() => {
-            setMessage('Logged out');
-        });
-
-        return () => {
-            sub1.unsubscribe();
-
-            sub2.unsubscribe();
-        };
-    }, []);
-
-    return message !== '' ? (
-        <div className={'notification'}>{message}</div>
-    ) : (
-        <>{null}</>
-    );
-};
-
-const loginUser = async (): Promise<
-    Readonly<{
-        id: number;
-        name: string;
-    }>
-> => ({ id: 1, name: 'Alice' });
-```
-
 ### Todo List with Reducer (React)
 
 ```tsx
 import * as React from 'react';
-import { createReducer } from 'synstate';
+import { createReducer } from 'synstate-react-hooks';
 
-type Todo = Readonly<{ id: number; text: string; done: boolean }>;
+type Todo = Readonly<{
+    id: number;
+    text: string;
+    done: boolean;
+}>;
 
 type Action = Readonly<
     | { type: 'add'; text: string }
@@ -325,10 +329,9 @@ type Action = Readonly<
     | { type: 'remove'; id: number }
 >;
 
-const [todoState, dispatch, getSnapshot] = createReducer<
-    readonly Todo[],
-    Action
->((todos, action) => {
+const initialTodos: readonly Todo[] = [] as const;
+
+const reducer = (todos: readonly Todo[], action: Action): readonly Todo[] => {
     switch (action.type) {
         case 'add':
             return [
@@ -339,53 +342,66 @@ const [todoState, dispatch, getSnapshot] = createReducer<
                     done: false,
                 },
             ];
+
         case 'toggle':
             return todos.map((t) =>
                 t.id === action.id ? { ...t, done: !t.done } : t,
             );
+
         case 'remove':
             return todos.filter((t) => t.id !== action.id);
     }
-}, []);
+};
 
-const TodoList = (): React.JSX.Element => {
-    const [todos, setTodos] = React.useState(getSnapshot());
+const [useTodoState, dispatch] = createReducer<readonly Todo[], Action>(
+    reducer,
+    initialTodos,
+);
 
-    React.useEffect(() => {
-        const sub = todoState.subscribe(setTodos);
+const addTodo = (): void => {
+    dispatch({
+        type: 'add',
+        text: 'New Todo',
+    });
+};
 
-        return () => {
-            sub.unsubscribe();
-        };
-    }, []);
+const TodoList = (): React.JSX.Element => {
+    const todos = useTodoState();
+
+    const todosWithHandler = React.useMemo(
+        () =>
+            todos.map((todo) => ({
+                ...todo,
+                onToggle: () => {
+                    dispatch({
+                        type: 'toggle',
+                        id: todo.id,
+                    });
+                },
+                onRemove: () => {
+                    dispatch({
+                        type: 'remove',
+                        id: todo.id,
+                    });
+                },
+            })),
+        [todos],
+    );
 
     return (
         <div>
-            {todos.map((todo) => (
+            {todosWithHandler.map((todo) => (
                 <div key={todo.id}>
                     <input
                         checked={todo.done}
                         type={'checkbox'}
-                        onChange={() => {
-                            dispatch({
-                                type: 'toggle',
-                                id: todo.id,
-                            });
-                        }}
+                        onChange={todo.onToggle}
                     />
                     <span>{todo.text}</span>
+                    <button onClick={todo.onRemove}>{'Remove'}</button>
                 </div>
             ))}
-            <button
-                onClick={() => {
-                    dispatch({
-                        type: 'add',
-                        text: 'New Todo',
-                    });
-                }}
-            >
-                {'Add Todo'}
-            </button>
+            <button onClick={addTodo}>{'Add Todo'}</button>
         </div>
     );
 };
@@ -395,35 +411,19 @@ const TodoList = (): React.JSX.Element => {
 
 ```tsx
 import * as React from 'react';
-import { createBooleanState } from 'synstate';
+import { createBooleanState } from 'synstate-react-hooks';
 
-export const [darkModeState, { toggle, getSnapshot }] =
+export const [useDarkModeState, { toggle: toggleDarkMode }] =
     createBooleanState(false);
 
 const ThemeToggle = (): React.JSX.Element => {
-    const [isDark, setIsDark] = React.useState(getSnapshot());
-
-    React.useEffect(() => {
-        const sub = darkModeState.subscribe(setIsDark);
-
-        return () => {
-            sub.unsubscribe();
-        };
-    }, []);
+    const isDark = useDarkModeState();
 
     React.useEffect(() => {
         document.body.className = isDark ? 'dark' : 'light';
     }, [isDark]);
 
-    return (
-        <button
-            onClick={() => {
-                toggle();
-            }}
-        >
-            {isDark ? '🌙' : '☀️'}
-        </button>
-    );
+    return <button onClick={toggleDarkMode}>{isDark ? '🌙' : '☀️'}</button>;
 };
 ```
 
@@ -431,30 +431,20 @@ const ThemeToggle = (): React.JSX.Element => {
 
 ```tsx
 import * as React from 'react';
-import { createEventEmitter, createState, createValueEmitter } from 'synstate';
-
-// Events
-const [onItemAdded$, emitItemAdded] = createValueEmitter<string>();
-
-const [onClearAll$, emitClearAll] = createEventEmitter();
+import { createState } from 'synstate-react-hooks';
 
 // State
-const [itemsState, setItemsState, { updateState, getSnapshot }] = createState<
-    readonly string[]
->([]);
+const [useItemsState, _, { updateState, resetState: resetItemsState }] =
+    createState<readonly string[]>([]);
 
 // Setup event handlers
-onItemAdded$.subscribe((item) => {
+const addItem = (item: string): void => {
     updateState((items: readonly string[]) => [...items, item]);
-});
-
-onClearAll$.subscribe(() => {
-    setItemsState([]);
-});
+};
 
 // Component 1: Add items
 const ItemInput = (): React.JSX.Element => {
-    const [input, setInput] = React.useState('');
+    const [input, setInput] = React.useState<string>('');
 
     return (
         <div>
@@ -466,7 +456,7 @@ const ItemInput = (): React.JSX.Element => {
             />
             <button
                 onClick={() => {
-                    emitItemAdded(input);
+                    addItem(input);
 
                     setInput('');
                 }}
@@ -479,15 +469,7 @@ const ItemInput = (): React.JSX.Element => {
 
 // Component 2: Display items
 const ItemList = (): React.JSX.Element => {
-    const [items, setItems] = React.useState(getSnapshot());
-
-    React.useEffect(() => {
-        const sub = itemsState.subscribe(setItems);
-
-        return () => {
-            sub.unsubscribe();
-        };
-    }, []);
+    const items = useItemsState();
 
     return (
         <div>
@@ -496,40 +478,41 @@ const ItemList = (): React.JSX.Element => {
                     <li key={i}>{item}</li>
                 ))}
             </ul>
-            <button onClick={emitClearAll}>{'Clear All'}</button>
+            <button onClick={resetItemsState}>{'Clear All'}</button>
         </div>
     );
 };
 ```
 
-// Events
-
 ### Advanced: Search with Debounce
 
 ```tsx
-import * as React from 'react';
+import type * as React from 'react';
 import {
     createState,
-    debounceTime,
+    debounce,
     filter,
-    fromPromise,
-    type Observable,
+    fromAbortablePromise,
+    type InitializedObservable,
+    map,
     switchMap,
+    withInitialValue,
 } from 'synstate';
+import { useObservableValue } from 'synstate-react-hooks';
 import { Result } from 'ts-data-forge';
 
 const [searchState, setSearchState] = createState('');
 
-// Advanced reactive pipeline (optional feature)
-const searchResults$: Observable<
-    Result<readonly Readonly<{ id: string; name: string }>[], unknown>
+// Advanced reactive pipeline with debounce and filtering
+const searchResults$: InitializedObservable<
+    readonly Readonly<{ id: string; name: string }>[]
 > = searchState
-    .pipe(debounceTime(300))
+    .pipe(debounce(300))
     .pipe(filter((query) => query.length > 2))
     .pipe(
         switchMap((query) =>
-            fromPromise(
-                fetch(`/api/search?q=${query}`).then(
+            fromAbortablePromise((signal) =>
+                fetch(`/api/search?q=${query}`, { signal }).then(
                     (r) =>
                         r.json() as Promise<
                             readonly Readonly<{ id: string; name: string }>[]
@@ -537,24 +520,13 @@ const searchResults$: Observable<
                 ),
             ),
         ),
-    );
+    )
+    .pipe(filter((res) => Result.isOk(res)))
+    .pipe(map((res) => Result.unwrapOk(res)))
+    .pipe(withInitialValue([]));
 
 const SearchBox = (): React.JSX.Element => {
-    const [results, setResults] = React.useState<
-        readonly Readonly<{ id: string; name: string }>[]
-    >([]);
-
-    React.useEffect(() => {
-        const sub = searchResults$.subscribe((result) => {
-            if (Result.isOk(result)) {
-                setResults(result.value);
-            }
-        });
-
-        return () => {
-            sub.unsubscribe();
-        };
-    }, []);
+    const searchResults = useObservableValue(searchResults$);
 
     return (
         <div>
@@ -565,7 +537,7 @@ const SearchBox = (): React.JSX.Element => {
                 }}
             />
             <ul>
-                {results.map((item) => (
+                {searchResults.map((item) => (
                     <li key={item.id}>{item.name}</li>
                 ))}
             </ul>
@@ -577,10 +549,12 @@ const SearchBox = (): React.JSX.Element => {
 ### Advanced: Event Emitter with Throttle
 
 ```tsx
-import { createEventEmitter, throttleTime } from 'synstate';
+import { createEventEmitter, throttle } from 'synstate';
 
 // Create event emitter
 const [refreshClicked, onRefreshClick] = createEventEmitter();
+// refreshClicked: Observable<void>
+// onRefreshClick: () => void
 
 // Subscribe to events
 refreshClicked.subscribe(() => {
@@ -588,7 +562,7 @@ refreshClicked.subscribe(() => {
 });
 
 // Throttle refresh clicks to prevent rapid successive executions
-const throttledRefresh = refreshClicked.pipe(throttleTime(2000));
+const throttledRefresh = refreshClicked.pipe(throttle(2000));
 
 throttledRefresh.subscribe(() => {
     console.log('Executing refresh...');
@@ -607,37 +581,82 @@ const DataTable = (): React.JSX.Element => (
 );
 ```
 
-## Why SynState?
+## API Reference
 
-### Simple State Management, Not Complex Reactive Programming
+### State Management
 
-SynState is a state management library for web frontends, similar to Redux, Jotai, Zustand, and MobX. It provides APIs for creating and managing global state across your application.
+SynState provides simple, intuitive APIs for managing application state:
 
-Under the hood, SynState is built on Observable patterns similar to those provided by RxJS. However, unlike RxJS, which can make code harder to read with many operators and complex streams, SynState focuses on **simple, readable state management and event handling**. Most applications only need `createState`, `createReducer`, and `createValueEmitter` - clean, straightforward APIs that developers understand immediately.
+- **`createState`**: Create state with InitializedObservable and setter
+- **`createReducer`**: Create state by reducer and initial value
+- **`createBooleanState`**: Specialized state for boolean values
 
-**Advanced reactive features are optional** and only used when you actually need them (like debouncing search input). The library doesn't force you into a reactive programming mindset.
+### Event System
 
-### Key Differences from RxJS
+Built-in event emitter for event-driven patterns:
 
-- **Focus on State & Events**: Designed for state management and event-driven architecture
-- **Simpler API**: Most use cases covered by `createState`, `createReducer`, and `createValueEmitter`
-- **Better Readability**: No need for complex operator chains in everyday code
-- **Optional Complexity**: Advanced features available when needed
+- **`createValueEmitter`**: Create type-safe event emitters
+- **`createEventEmitter`**: Create event emitters without payload
 
-### Use Cases
+### Observable APIs
 
-**Use SynState when you need:**
+For complex scenarios, SynState provides observable-based APIs:
 
-- ✅ Global state management across components
-- ✅ Event-driven communication between components
-- ✅ Type-safe event emitters
-- ✅ Redux-like state with reducers
-- ✅ Simple reactive patterns (debounce, throttle, etc.)
+#### Creation Functions
 
-**Consider other solutions when:**
+- `source<T>()`: Create a new observable source (Almost equivalent to RxJS `subject`)
+- `fromPromise(promise)`: Create observable from promise
+- `fromSubscribable()`: Create observable from any subscribable object
+- `counter(ms)`: Emit values at intervals (Almost equivalent to RxJS `interval`)
+- `timer(delay)`: Emit after delay
+
+#### Operators
+
+- `map` variants
+    - `map(fn)`: Transform values
+    - `mapTo(value)`: Map all values to a constant
+    - `getKey(key)`: Extract property value from objects (alias: `pluck`)
+    - `attachIndex()`: Attach index to each value (alias: `withIndex`)
+    - Result/Optional
+        - `mapOptional(fn)`: Map over Optional values
+        - `mapResultOk(fn)`: Map over Result ok values
+        - `mapResultErr(fn)`: Map over Result error values
+        - `unwrapOptional()`: Unwrap Optional values to undefined
+        - `unwrapResultOk()`: Unwrap Result ok values to undefined
+        - `unwrapResultErr()`: Unwrap Result error values to undefined
+    - `mergeMap(fn)`: Map to observables and merge all (runs in parallel) (alias: `flatMap`)
+    - `switchMap(fn)`: Map to observables and switch to latest (cancels previous)
+- Filtering
+    - `filter(predicate)`: Filter values
+    - `skipIfNoChange()`: Skip duplicate values (alias: `distinctUntilChanged`)
+    - `skip(n)`: Skip first n emissions
+    - `take(n)`: Take first n emissions then complete
+    - `skipWhile(predicate)`: Skip values while predicate is true
+    - `takeWhile(predicate)`: Emit values while predicate is true, then complete
+    - `skipUntil(notifier)`: Skip values until notifier emits
+    - `takeUntil(notifier)`: Complete on notifier emission
+- Time series processing
+    - `audit(ms)`: Emit the last value after specified time window (Almost equivalent to RxJS `auditTime`)
+    - `debounce(ms)`: Debounce emissions (Almost equivalent to RxJS `debounceTime`)
+    - `throttle(ms)`: Throttle emissions (Almost equivalent to RxJS `throttleTime`)
+- Others
+    - `pairwise()`: Emit previous and current values as pairs
+    - `scan(reducer, seed)`: Accumulate values
+    - `withBuffered(observable)`: Buffer values from observable and emit with parent (alias: `withBufferedFrom`)
+    - `withCurrentValueFrom(observable)`: Sample current value from another observable (alias: `withLatestFrom`)
+    - `withInitialValue(value)`: Provide an initial value for uninitialized observable
+
+#### Combination
+
+- `combine(observables)`: Combine latest values from multiple sources (alias: `combineLatest`)
+- `merge(observables)`: Merge multiple streams
+- `zip(observables)`: Pair values by index
+
+#### Utilities
 
-- ❌ You need complex stream processing (use RxJS)
-- ❌ Your app is simple enough for React Context alone
+- `isChildObservable(obs)`: Check if observable is a child observable
+- `isManagerObservable(obs)`: Check if observable is a manager observable
+- `isRootObservable(obs)`: Check if observable is a root observable
 
 ## Type Safety