synstate 0.1.0 → 0.1.2

package/README.md

@@ -1,25 +1,34 @@
-# SyncFlow
+# SynState
 
-[![npm version](https://img.shields.io/npm/v/ts-data-forge.svg)](https://www.npmjs.com/package/ts-data-forge)
-[![npm downloads](https://img.shields.io/npm/dm/ts-data-forge.svg)](https://www.npmjs.com/package/ts-data-forge)
-[![License](https://img.shields.io/npm/l/ts-data-forge.svg)](./LICENSE)
-[![codecov](https://codecov.io/gh/noshiro-pf/ts-data-forge/branch/main/graph/badge.svg?token=69TA40HACZ)](https://codecov.io/gh/noshiro-pf/ts-data-forge)
+<p align="center">
+  <img src="./assets/synstate-icon.png" alt="SynState Logo" width="400" />
+</p>
 
-**SyncFlow** is a lightweight, type-safe state management library for TypeScript/JavaScript. Perfect for building reactive global state and event-driven systems in React, Vue, and other frameworks.
+<p align="center">
+
+[![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)
+
+</p>
+
+**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.
 
 ## 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
+- 🔄 **Reactive Updates**: Automatic propagation of state changes to all subscribers
 - 🎨 **Type-Safe**: Full TypeScript support with precise type inference
-- 🚀 **Lightweight**: Minimal bundle size, zero external runtime dependencies
-- ⚡ **Framework Agnostic**: Works with React, Vue, Svelte, or vanilla JavaScript
-- 🔧 **Flexible**: Simple state management with optional advanced features
+- 🚀 **Lightweight**: Minimal bundle size with only one external runtime dependency ([ts-data-forge](https://www.npmjs.com/package/ts-data-forge))
+- ⚡ **High Performance**: Optimized for fast state updates and minimal re-renders
+- 🌐 **Framework Agnostic**: Works with React, Vue, Svelte, or vanilla JavaScript
+- 🔧 **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`, `debounceTime`) and combinators (`merge`, `combine`)
 
 ## Documentation
 
-- API reference: <https://noshiro-pf.github.io/synstate/>
+- API reference: TBD <!-- <https://noshiro-pf.github.io/synstate/> -->
 
 ## Installation
 
@@ -42,39 +51,33 @@ pnpm add synstate
 ### Simple State Management
 
 ```tsx
-import { createState } from 'synstate';
-
 // Create a reactive state
-const [state, setState, { updateState }] = createState(0);
+const [state, setState, { updateState, resetState, getSnapshot }] =
+    createState(0);
+
+const mut_history: number[] = [];
 
 // Subscribe to changes (in React components, Vue watchers, etc.)
-state.subscribe((count: number) => {
-    console.log('Count:', count);
+state.subscribe((count) => {
+    mut_history.push(count);
 });
 
+assert.deepStrictEqual(mut_history, [0]);
+
 // Update state
 setState(1);
 
-updateState((prev: number) => prev + 1);
-```
+assert.deepStrictEqual(mut_history, [0, 1]);
 
-### Event Emitter
+updateState((prev) => prev + 2);
 
-```tsx
-import { createValueEmitter } from 'synstate';
+assert.deepStrictEqual(mut_history, [0, 1, 3]);
 
-type User = Readonly<{ id: number; name: string }>;
+assert.isTrue(getSnapshot() === 3);
 
-// Create event emitter
-const [userLoggedIn$, emitUserLoggedIn] = createValueEmitter<User>();
+resetState();
 
-// Subscribe to events
-userLoggedIn$.subscribe((user) => {
-    console.log('User logged in:', user.name);
-});
-
-// Emit events
-emitUserLoggedIn({ id: 1, name: 'Alice' });
+assert.isTrue(getSnapshot() === 0);
 ```
 
 ### With React
@@ -121,14 +124,97 @@ const UserProfile = (): React.JSX.Element => {
 };
 ```
 
+If you're using React v18 or later:
+
+```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>
+    );
+};
+```
+
+You can write the equivalent code more concisely using synstate-react-hooks:
+
+```bash
+npm add synstate-react-hooks
+```
+
+```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>
+    );
+};
+```
+
+See also the [synstate-react-hooks README](../synstate-react-hooks/README.md).
+
 ## Core Concepts
 
 ### State Management
 
-SyncFlow provides simple, intuitive APIs for managing application state:
+SynState provides simple, intuitive APIs for managing application state:
 
-- **`createState`**: Create mutable state with getter/setter
-- **`createReducer`**: Redux-style state management
+- **`createState`**: Create state with getter/setter
+- **`createReducer`**: Create state by reducer and initial value
 - **`createBooleanState`**: Specialized state for boolean values
 
 ### Event System
@@ -142,25 +228,50 @@ Built-in event emitter for event-driven patterns:
 
 For advanced use cases, you can use observables to build complex reactive data flows. However, most applications will only need `createState`, `createReducer`, and `createValueEmitter`.
 
+## API Reference
+
+For complex scenarios, SynState provides observable-based APIs:
+
+### Creation Functions
+
+- `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
+
+### Operators
+
+- `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
+
+### Combination
+
+- `combine(observables)`: Combine latest values from multiple sources
+- `merge(observables)`: Merge multiple streams
+- `zip(observables)`: Pair values by index
+
+## Examples
+
+### 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 }] =
+export const [useCounterState, , { updateState, resetState, getSnapshot }] =
     createState(0);
 
 // 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>
@@ -191,85 +302,17 @@ const ResetButton = (): React.JSX.Element => (
 );
 ```
 
-## API Reference
-
-### State Management (Recommended)
-
-#### createState
-
-Create reactive state with getter and setter:
-
-```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' });
-```
-
-#### createBooleanState
-
-Specialized state for boolean values:
+### 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 }
@@ -277,10 +320,9 @@ type Action = Readonly<
     | { type: 'remove'; id: number }
 >;
 
-const [todoState, dispatch, getSnapshot] = createReducer<
-    readonly Todo[],
-    Action
->((todos, action) => {
+const initialTodos: readonly Todo[] = [];
+
+const reducer = (todos: readonly Todo[], action: Action): readonly Todo[] => {
     switch (action.type) {
         case 'add':
             return [
@@ -291,128 +333,109 @@ 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>
     );
 };
 ```
 
-#### createReducer
-
-Create state with reducer pattern (like Redux):
+### Boolean State (Dark Mode)
 
 ```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>;
 };
 ```
 
-### Event System
-
-#### createValueEmitter
-
-Create type-safe event emitter with payload:
+### Cross-Component Communication
 
 ```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>
@@ -424,7 +447,7 @@ const ItemInput = (): React.JSX.Element => {
             />
             <button
                 onClick={() => {
-                    emitItemAdded(input);
+                    addItem(input);
 
                     setInput('');
                 }}
@@ -437,15 +460,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>
@@ -454,33 +469,36 @@ const ItemList = (): React.JSX.Element => {
                     <li key={i}>{item}</li>
                 ))}
             </ul>
-            <button onClick={emitClearAll}>{'Clear All'}</button>
+            <button onClick={resetItemsState}>{'Clear All'}</button>
         </div>
     );
 };
 ```
 
-#### createEventEmitter
+// Events
 
-Create event emitter without payload:
+### Advanced: Search with Debounce
 
 ```tsx
-import * as React from 'react';
+import type * as React from 'react';
 import {
     createState,
     debounceTime,
     filter,
     fromPromise,
-    type Observable,
+    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(filter((query) => query.length > 2))
@@ -495,24 +513,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>
@@ -523,7 +530,7 @@ const SearchBox = (): React.JSX.Element => {
                 }}
             />
             <ul>
-                {results.map((item) => (
+                {searchResults.map((item) => (
                     <li key={item.id}>{item.name}</li>
                 ))}
             </ul>
@@ -532,315 +539,60 @@ const SearchBox = (): React.JSX.Element => {
 };
 ```
 
-### Advanced Features (Optional)
-
-For complex scenarios, SyncFlow provides observable-based APIs:
-
-#### Creation Functions
-
-- `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
-
-#### Operators
-
-- `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
-
-#### Combination
-
-- `combine(observables)`: Combine latest values from multiple sources
-- `merge(observables)`: Merge multiple streams
-- `zip(observables)`: Pair values by index
-
-## Examples
-
-### Global Counter State (React)
-
-```tsx
-import { createState } from 'synstate';
-import { useState, useEffect } from 'react';
-
-// Create global state
-export const counterState = createState(0);
-
-// Component 1
-function Counter() {
-    const [count, setCount] = useState(counterState.getSnapshot());
-
-    useEffect(() => {
-        const sub = counterState.state.subscribe(setCount);
-        return () => sub.unsubscribe();
-    }, []);
-
-    return (
-        <div>
-            <p>Count: {count}</p>
-            <button onClick={() => counterState.updateState((n) => n + 1)}>
-                Increment
-            </button>
-        </div>
-    );
-}
-
-// Component 2 (synced automatically)
-function ResetButton() {
-    return <button onClick={() => counterState.resetState()}>Reset</button>;
-}
-```
-
-### Event-Driven Architecture (React)
-
-```tsx
-import { createValueEmitter } from 'synstate';
-import { useEffect } from 'react';
-
-// Global events
-export const [userLoggedIn$, emitUserLoggedIn] = createValueEmitter<{
-    id: number;
-    name: string;
-}>();
-
-export const [userLoggedOut$, emitUserLoggedOut] = createEventEmitter();
-
-// Component that emits events
-function LoginButton() {
-    const handleLogin = async () => {
-        const user = await loginUser();
-        emitUserLoggedIn(user);
-    };
-
-    return <button onClick={handleLogin}>Login</button>;
-}
-
-// Component that listens to events
-function Notification() {
-    const [message, setMessage] = useState('');
-
-    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;
-}
-```
-
-### Todo List with Reducer (React)
+### Advanced: Event Emitter with Throttle
 
 ```tsx
-import { createReducer } from 'synstate';
-import { useState, useEffect } from 'react';
-
-type Todo = { id: number; text: string; done: boolean };
-type Action =
-    | { type: 'add'; text: string }
-    | { type: 'toggle'; id: number }
-    | { type: 'remove'; id: number };
-
-const todoState = createReducer<Todo[], Action>((todos, action) => {
-    switch (action.type) {
-        case 'add':
-            return [
-                ...todos,
-                {
-                    id: Date.now(),
-                    text: action.text,
-                    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);
-    }
-}, []);
-
-function TodoList() {
-    const [todos, setTodos] = useState(todoState.getSnapshot());
-
-    useEffect(() => {
-        const sub = todoState.state.subscribe(setTodos);
-        return () => sub.unsubscribe();
-    }, []);
+import { createEventEmitter, throttleTime } from 'synstate';
 
-    return (
-        <div>
-            {todos.map((todo) => (
-                <div key={todo.id}>
-                    <input
-                        type="checkbox"
-                        checked={todo.done}
-                        onChange={() =>
-                            todoState.dispatch({
-                                type: 'toggle',
-                                id: todo.id,
-                            })
-                        }
-                    />
-                    <span>{todo.text}</span>
-                </div>
-            ))}
-            <button
-                onClick={() =>
-                    todoState.dispatch({
-                        type: 'add',
-                        text: 'New Todo',
-                    })
-                }
-            >
-                Add Todo
-            </button>
-        </div>
-    );
-}
-```
-
-### Boolean State (Dark Mode)
-
-```tsx
-import { createBooleanState } from 'synstate';
-import { useState, useEffect } from 'react';
-
-export const darkModeState = createBooleanState(false);
-
-function ThemeToggle() {
-    const [isDark, setIsDark] = useState(darkModeState.getSnapshot());
-
-    useEffect(() => {
-        const sub = darkModeState.state.subscribe(setIsDark);
-        return () => sub.unsubscribe();
-    }, []);
-
-    useEffect(() => {
-        document.body.className = isDark ? 'dark' : 'light';
-    }, [isDark]);
-
-    return (
-        <button onClick={() => darkModeState.toggle()}>
-            {isDark ? '🌙' : '☀️'}
-        </button>
-    );
-}
-```
-
-### Cross-Component Communication
-
-```tsx
-import { createValueEmitter, createState } from 'synstate';
-import { useState, useEffect } from 'react';
-```
-
-// Events
-
-### Advanced: Search with Debounce
-
-```tsx
-import * as React from 'react';
-import {
-    createState,
-    debounceTime,
-    filter,
-    fromPromise,
-    type Observable,
-    switchMap,
-} from 'synstate';
-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>
-> = searchState
-    .pipe(debounceTime(300))
-    .pipe(filter((query) => query.length > 2))
-    .pipe(
-        switchMap((query) =>
-            fromPromise(
-                fetch(`/api/search?q=${query}`).then(
-                    (r) =>
-                        r.json() as Promise<
-                            readonly Readonly<{ id: string; name: string }>[]
-                        >,
-                ),
-            ),
-        ),
-    );
+// Create event emitter
+const [refreshClicked, onRefreshClick] = createEventEmitter();
 
-const SearchBox = (): React.JSX.Element => {
-    const [results, setResults] = React.useState<
-        readonly Readonly<{ id: string; name: string }>[]
-    >([]);
+// Subscribe to events
+refreshClicked.subscribe(() => {
+    console.log('Refresh Clicked');
+});
 
-    React.useEffect(() => {
-        const sub = searchResults$.subscribe((result) => {
-            if (Result.isOk(result)) {
-                setResults(result.value);
-            }
-        });
+// Throttle refresh clicks to prevent rapid successive executions
+const throttledRefresh = refreshClicked.pipe(throttleTime(2000));
 
-        return () => {
-            sub.unsubscribe();
-        };
-    }, []);
+throttledRefresh.subscribe(() => {
+    console.log('Executing refresh...');
+    // Actual refresh logic here
+    // This will be called at most once every 2 seconds
+});
 
-    return (
-        <div>
-            <input
-                placeholder={'Search...'}
-                onChange={(e) => {
-                    setSearchState(e.target.value);
-                }}
-            />
-            <ul>
-                {results.map((item) => (
-                    <li key={item.id}>{item.name}</li>
-                ))}
-            </ul>
-        </div>
-    );
-};
+const DataTable = (): React.JSX.Element => (
+    <div>
+        <button onClick={onRefreshClick}>{'Refresh'}</button>
+        <p>
+            {'Data: '}
+            {/* Display data here */}
+        </p>
+    </div>
+);
 ```
 
-## Why SyncFlow?
+## Why SynState?
 
 ### Simple State Management, Not Complex Reactive Programming
 
-Unlike RxJS, which can make code harder to read with many operators and complex streams, SyncFlow focuses on **simple, readable state management and event handling**. Most applications only need `createState`, `createReducer`, and `createValueEmitter` - clean, straightforward APIs that developers understand immediately.
+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.
+
+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 simple operators/combinators like `combine` and `map` — clean, straightforward APIs that developers understand immediately.
 
 **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.
 
 ### Key Differences from RxJS
 
-- **Focus on State & Events**: Designed for state management and event-driven architecture
-- **Simpler API**: Most use cases covered by `createState`, `createReducer`, and `createValueEmitter`
+- **Focus on State Management**: Designed specifically for state management, not just asynchronous event processing
+- **InitializedObservable**: Provides `InitializedObservable` which always holds an initial value, making it ideal for representing state
+- **Simpler API**: Most use cases are covered by `createState`, `createReducer`, and `createEventEmitter`
 - **Better Readability**: No need for complex operator chains in everyday code
-- **Optional Complexity**: Advanced features available when needed
+- **Optional Complexity**: Advanced features available to manipulate Observables when needed
 
 ### Use Cases
 
-**Use SyncFlow when you need:**
+**Use SynState when you need:**
 
 - ✅ Global state management across components
 - ✅ Event-driven communication between components
@@ -850,24 +602,12 @@ Unlike RxJS, which can make code harder to read with many operators and complex
 
 **Consider other solutions when:**
 
-- ❌ You need complex stream processing (use RxJS)
+- ❌ You need state in a React component (use React hooks `useState`, `useReducer`)
 - ❌ Your app is simple enough for React Context alone
 
 ## Type Safety
 
-SyncFlow maintains full type information:
-
-```tsx
-const userState = createState({ name: 'Alice', age: 25 });
-// state type: Observable<{ name: string; age: number }>
-
-const snapshot = userState.getSnapshot();
-// snapshot type: { name: string; age: number }
-
-const [onClick$, emitClick] = createValueEmitter<MouseEvent>();
-// onClick$ type: Observable<MouseEvent>
-// emitClick type: (event: MouseEvent) => void
-```
+SynState maintains full type information.
 
 ## License