([]);\nconst filter = state<'all' | 'active' | 'completed'>('all');\nconst newTodo = state('');\n\n// 3. Add persistence\npersistLocalStorage(todos, 'todos');\npersistLocalStorage(filter, 'todos-filter');\n\n// 4. Create computed values\nexport const filteredTodos = derived(() => {\n switch (filter.value) {\n case 'active':\n return todos.value.filter(todo => !todo.completed);\n case 'completed':\n return todos.value.filter(todo => todo.completed);\n default:\n return todos.value;\n }\n});\n\n// 5. Define action functions\nconst addTodo = action(() => {\n if (newTodo.value.trim()) {\n todos.value = [\n ...todos.value,\n {\n id: Date.now(),\n text: newTodo.value.trim(),\n completed: false,\n },\n ];\n newTodo.value = '';\n }\n}, 'addTodo');\n\nconst toggleTodo = action((id: number) => {\n todos.value = todos.value.map(todo =>\n todo.id === id ? { ...todo, completed: !todo.completed } : todo,\n );\n}, 'toggleTodo');\n\n// 6. Export everything\nexport {\n todos,\n filter,\n newTodo,\n addTodo,\n toggleTodo,\n // ... other exports\n};\n```\n\n### Component Example\n\n```tsx\nfunction TodoApp() {\n const { todos, newTodo, addTodo, toggleTodo } = useUnderstate({\n todos,\n newTodo,\n addTodo,\n toggleTodo,\n });\n}\n\nreturn {/* Clean, simple component logic */}
;\n```\n\n### Why This Pattern Works\n\n**๐ฏ Clear Separation of Concerns**\n\n- **State**: Raw reactive values\n- **Computed**: Derived values that automatically update\n- **Actions**: Pure functions that modify state\n- **Persistence**: Declarative storage configuration\n\n**๐งช Excellent Testability**\n\n```tsx\n// Test actions independently\ndescribe('Todo Actions', () => {\n beforeEach(() => {\n todos.value = [];\n newTodo.value = '';\n });\n\n it('should add a todo', () => {\n newTodo.value = 'Test todo';\n addTodo();\n expect(todos.value).toHaveLength(1);\n expect(todos.value[0].text).toBe('Test todo');\n });\n});\n```\n\n**๐ Easy Component Integration**\n\n```tsx\nfunction TodoApp() {\n const { todos, newTodo, addTodo, toggleTodo } = useUnderstate({\n todos,\n newTodo,\n addTodo,\n toggleTodo,\n });\n\n return {/* Clean, simple component logic */}
;\n}\n```\n\n**๐ฆ Perfect Tree-Shaking**\n\n- Import only what you need\n- Unused actions are eliminated from the bundle\n- Computed values are only created when used\n\n**๐ ๏ธ Maintainable Architecture**\n\n- Easy to add new features\n- Clear data flow\n- Predictable state updates\n- Type-safe throughout\n\n### Pattern Benefits\n\n| Aspect | Benefit |\n| --------------- | ------------------------------------------- |\n| **Testing** | Actions can be tested without React |\n| **Reusability** | Logic works in any framework |\n| **Performance** | Only used code is bundled |\n| **Type Safety** | Full TypeScript support |\n| **Debugging** | Clear separation makes issues easy to trace |\n| **Scaling** | Pattern scales from simple to complex apps |\n\nThis pattern is used in both the [Calculator](examples/calculator/) and [Todo App](examples/todo-app/) examples, demonstrating its versatility across different application types.\n\n## Examples\n\n**๐ [Live Examples on Documentation Site](https://mjbeswick.github.io/react-understate/examples/todo)** - Interactive examples you can try in your browser\n\n**๐ [Source Code Examples](examples/)** - Complete working examples in the repository:\n\n- **Calculator** - Basic state management with derived values\n- **Todo App** - Full-featured todo app with persistence\n\n## API Reference\n\n> **๐ For complete API documentation with detailed examples, visit the [Documentation Site](https://mjbeswick.github.io/react-understate/api/state)**\n\n### Core Functions\n\n- `state(initialValue: T, name?: string): State` - Create a reactive state\n- `derived(fn: () => T, name?: string): Derived` - Create a derived value\n- `effect(fn: () => void | (() => void) | Promise, name?: string, options?: EffectOptions): () => void` - Create an effect\n- `batch(fn: () => void): void` - Batch multiple updates\n- `action(fn: (...args: T) => void, name?: string): (...args: T) => void` - Create an action function\n- `group(namespace: string): { state, derived, action, effect }` - Create a namespaced API for grouping related items\n\n### React Integration\n\n- `useUnderstate(state: State): [T]` - Subscribe to a single state\n- `useUnderstate(store: Store): T` - Subscribe to a store object\n\n### Persistence\n\n- `persistLocalStorage(state: State, key: string, options?: PersistOptions): () => void`\n- `persistSessionStorage(state: State, key: string, options?: PersistOptions): () => void`\n- `persistStates(states: T, keyPrefix: string, storage?: Storage): () => void`\n\n### Types\n\n```tsx\ntype EffectOptions = {\n once?: boolean; // Run effect only once, ignore subsequent dependency changes\n preventOverlap?: boolean; // Prevent overlapping executions of async effects\n preventLoops?: boolean; // Automatically prevent infinite loops (default: true)\n};\n\ntype PersistOptions = {\n loadInitial?: boolean; // Load initial value from storage (default: true)\n syncAcrossTabs?: boolean; // Sync changes across tabs (default: true)\n serialize?: (value: T) => string; // Custom serializer (default: JSON.stringify)\n deserialize?: (value: string) => T; // Custom deserializer (default: JSON.parse)\n onError?: (error: Error) => void; // Error handler\n};\n```\n\n## Breaking Changes\n\n### Version 1.8.0\n\n- **State Setters Now Accept Async Functions**: State setters can now accept async functions directly:\n\n ```tsx\n // โ
New in 1.8.0 - async setters\n count.value = async prev => {\n await new Promise(resolve => setTimeout(resolve, 100));\n return prev + 1;\n };\n ```\n\n- **Effect Options**: Effects now accept an options parameter for better control:\n ```tsx\n // โ
New in 1.8.0 - effect options\n effect(\n () => {\n // effect logic\n },\n 'effectName',\n { once: true, preventOverlap: true },\n );\n ```\n\n## Coming Soon\n\n- Enhanced Chrome DevTools integration for comprehensive debugging and state inspection.\n\n## License\n\nMIT ยฉ [mjbeswick](https://github.com/mjbeswick)\n\n---\n\n**Note**: This library is actively maintained and follows semantic versioning. For the latest updates and breaking changes, please check the [CHANGELOG.md](CHANGELOG.md).\n","readmeFilename":"README.md"}