dantian 0.0.2-beta.8 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+
+### [1.0.2](https://github.com/JuliusKoronciCH/dantian/compare/v1.0.1-beta.0...v1.0.2) (2026-02-08)
+
+### [1.0.1](https://github.com/JuliusKoronciCH/dantian/compare/v1.0.1-beta.0...v1.0.1) (2026-02-08)
+
+### 1.0.1-beta.1 (2026-02-08)
+
+### 1.0.1-beta.0 (2026-02-08)
+
+### 0.0.2-beta.19 (2026-02-08)
+
+### 0.0.2-beta.18 (2024-05-21)
+
+### Bug Fixes
+
+- useIsHydrated race condition fix on later call of the hook ([#19](https://github.com/JuliusKoronciCH/dantian/issues/19)) ([2c7c0ff](https://github.com/JuliusKoronciCH/dantian/commit/2c7c0ffbe1ecdab03b912508ca4410fc65e1f242))
+
+### 0.0.2-beta.17 (2024-05-07)
+
+### 0.0.2-beta.16 (2024-05-07)
+
+### 0.0.2-beta.15 (2024-04-25)
+
+### Bug Fixes
+
+- child property observable ([#16](https://github.com/JuliusKoronciCH/dantian/issues/16)) ([6d33779](https://github.com/JuliusKoronciCH/dantian/commit/6d33779d5dfe7d51cd7e2e75f0b3a20fe88bcf41))
+
+### 0.0.2-beta.14 (2024-04-25)
+
+### 0.0.2-beta.13 (2024-04-25)
+
+### 0.0.2-beta.12 (2024-04-18)
+
+### 0.0.2-beta.11 (2024-04-08)
+
+### 0.0.2-beta.10 (2024-04-07)
+
+### 0.0.2-beta.9 (2024-04-07)
+
+### 0.0.2-beta.8 (2024-04-04)
+
+### 0.0.2-beta.7 (2024-04-04)
+
+### 0.0.2-beta.6 (2024-04-04)
+
+### 0.0.2-beta.5 (2024-04-04)
+
+### 0.0.2-beta.4 (2024-04-04)
+
+### 0.0.2-beta.3 (2024-04-04)
+
+### 0.0.2-beta.2 (2024-04-04)

package/README.md

@@ -1,55 +1,322 @@
-**Dantian - React State Management Reimagined**
+# Dantian
 
-[![npm version](https://badge.fury.io/js/dantian.svg)](https://badge.fury.io/js/dantian)
+Event-based state management for React, powered by RxJS. Dantian exposes a small event store API and React hooks that subscribe to specific property paths, so only the parts of UI that care about a given event re-render.
 
-Dantian is an event-based state management library for React applications that delivers pinpoint performance and effortless integration with forms. Say goodbye to unnecessary rerenders and complex state comparisons – Dantian ensures that components only update when they subscribe to specific state changes.
+## Installation
 
-**The Problem**
+```bash
+npm install dantian
+```
 
-Traditional state management solutions in React often lead to performance issues, especially in applications with frequent updates or large forms. Unnecessary rerenders can slow down the user experience.
+## Compatibility
 
-**Our Solution**
+| Runtime | Supported versions |
+| ------- | ------------------ |
+| React   | 18, 19             |
+| RxJS    | 7, 8               |
+| Node    | 18, 20, 22         |
 
-Dantian's event-driven approach focuses on precision. State updates are triggered by events, and only components subscribed to those events rerender. This provides granular control and optimizes performance where it matters most.
+## Use Cases & FAQ
 
-**Features**
+### Quickstart: event store basics
 
-- **useState-like hooks:** Familiar interface for ease of use.
-- **Custom events:** Power and flexibility for complex scenarios.
-- **Asynchronous state updates:** Handle async patterns gracefully.
-- **Optimized form integration:** Tackle large forms without performance compromises.
+```ts
+// store.ts
+import { createEventStore } from 'dantian';
 
-**Installation**
+export const store = createEventStore({
+  count: 0,
+  user: { name: 'n/a' },
+});
 
-```bash
-npm install dantian
+export const {
+  useStoreValue,
+  publish,
+  useHydrateStore,
+  useIsHydrated,
+  reset,
+  feed,
+  destroy,
+  state$,
+  systemEvents$,
+} = store;
 ```
 
-**Basic usage**
-
-```TypeScript
-import { useEventState } from 'dantian';
+```tsx
+// Counter.tsx
+import { useStoreValue } from './store';
 
-function MyComponent() {
-  const [count, setCount] = useEventState('counter', 0);
-
-  const increment = () => setCount(count + 1);
+export function Counter() {
+  const [count, setCount] = useStoreValue('count');
 
   return (
-    <div>
-      <p>Count: {count}</p>
-      <button onClick={increment}>Increment</button>
-    </div>
+    <button type="button" onClick={() => setCount(count + 1)}>
+      Count: {count}
+    </button>
   );
 }
 ```
 
-**Getting Started**
+At a glance, `createEventStore` maintains a stream of events and derives state from them. Updates are published by property path (for example, `user.name`), and hooks subscribe to those paths.
+
+### How do I update nested fields?
+
+```tsx
+const [name, setName] = useStoreValue('user.name');
+setName('Ada');
+
+// Or outside React:
+publish('user.name', 'Ada');
+```
+
+### How do I hydrate from an async source?
+
+```ts
+const store = createEventStore(
+  { user: { name: 'n/a' } },
+  {
+    hydrator: async () => {
+      const response = await fetch('/api/profile');
+      return (await response.json()) as { user: { name: string } };
+    },
+  },
+);
+```
+
+### How do I persist state?
+
+```ts
+const store = createEventStore(
+  { count: 0 },
+  {
+    persist: async (state) => {
+      localStorage.setItem('dantianState', JSON.stringify(state));
+    },
+  },
+);
+```
+
+If hydration or persistence fails, you can observe the error via system events
+while console errors remain intact:
+
+```ts
+systemEvents$.subscribe((event) => {
+  if (event.type === '@@HYDRATE_ERROR' || event.type === '@@PERSIST_ERROR') {
+    console.error('store error', event.payload.error);
+  }
+});
+```
+
+### How do I avoid flicker from concurrent updates?
+
+If updates are coming from multiple sources, you can disable local caching per hook:
+
+```tsx
+const [value, setValue] = useStoreValue('profile.name', {
+  disableCache: true,
+});
+```
+
+You can also throttle update propagation with `throttle` (milliseconds):
+
+```tsx
+const [user] = useStoreValue('user', { throttle: 50 });
+```
+
+### How do I reset or feed state?
+
+```ts
+reset({ count: 0, user: { name: 'n/a' } });
+feed({ count: 5, user: { name: 'Julius' } });
+```
+
+### How do I subscribe outside React?
+
+```ts
+const subscription = state$.subscribe((state) => {
+  console.log('state changed', state);
+});
+
+subscription.unsubscribe();
+```
+
+### Dispose of a store
+
+If a store is no longer needed, dispose of it to complete internal subjects and
+prevent lingering subscriptions:
+
+```ts
+store.destroy();
+```
+
+After `destroy()`, calls to `publish`, `reset`, `feed`, and the callback from
+`useHydrateStore()` are no-ops.
+
+## Task Guides
+
+### Create a store
+
+```ts
+import { createEventStore } from 'dantian';
+
+const store = createEventStore({ count: 0 }, { debug: false });
+```
+
+### Read and update values in components
+
+```tsx
+const [count, setCount] = store.useStoreValue('count');
+setCount(count + 1);
+
+// Or publish directly
+store.publish('count', 42);
+```
+
+`useStoreValue` options:
+
+- `disableCache`: bypasses local caching to avoid flicker in edge cases.
+- `throttle`: throttles updates in milliseconds.
+- `throtle`: legacy alias for `throttle` (kept for backward compatibility).
+
+### Hydrate and persist
+
+```ts
+const store = createEventStore(
+  { count: 0 },
+  {
+    hydrator: async () => ({ count: 10 }),
+    persist: async (state) => {
+      localStorage.setItem('dantianState', JSON.stringify(state));
+    },
+  },
+);
+```
+
+In React, you can trigger hydration manually:
+
+```tsx
+const hydrate = store.useHydrateStore();
+const isHydrated = store.useIsHydrated();
+```
+
+### Reset and feed
+
+```ts
+store.reset({ count: 0 });
+store.feed({ count: 5 });
+```
+
+### Destroy
+
+```ts
+store.destroy();
+```
+
+### Observe with RxJS
+
+```ts
+const sub = store.getPropertyObservable('count').subscribe((value) => {
+  console.log('count changed', value);
+});
+
+sub.unsubscribe();
+```
+
+### Classic store basics
+
+If you need a minimal store with selectors and updates, use `buildClassicStore`:
+
+```ts
+import { buildClassicStore } from 'dantian';
+
+const classic = await buildClassicStore({ count: 0 });
+const [state, update] = classic.useStore();
+const count = classic.useSelector((s) => s.count);
+update((prev) => ({ ...prev, count: prev.count + 1 }));
+```
+
+With hydration and persistence:
+
+```ts
+const classic = await buildClassicStore({
+  beforeLoadState: { count: 0 },
+  hydrator: async () => ({ count: 2 }),
+  persist: async (state) => {
+    localStorage.setItem('classicState', JSON.stringify(state));
+  },
+});
+```
+
+## API Reference
+
+### `createEventStore<T extends object>(initialState, options?)`
+
+Options:
+
+- `debug?: boolean` — log events and state transitions.
+- `hydrator?: () => Promise<T>` — async hydration source.
+- `persist?: (state: T) => Promise<void>` — persistence callback.
+
+Returns:
+
+- `useStoreValue<K>(path, options?)`: React hook for reading/updating a property path.
+- `publish(path, payload)`: publish an event for a property path.
+- `getPropertyObservable(path, throttle?)`: RxJS observable for a property path.
+- `useHydrateStore()`: returns a function to emit `@@HYDRATED` with payload.
+- `useIsHydrated()`: returns a boolean hydration flag.
+- `reset(payload)`: emit `@@RESET` system event.
+- `feed(payload)`: emit `@@FEED` system event.
+- `state$`: `BehaviorSubject<T>` with current state.
+- `globalEventStore$`: `BehaviorSubject` of all events.
+- `systemEvents$`: observable of system events (event types starting with `@@`,
+  including `@@HYDRATE_ERROR` and `@@PERSIST_ERROR`).
+- `destroy()`: dispose the store, completing internal subjects and stopping
+  further publishes.
+
+`useStoreValue` options:
+
+- `disableCache?: boolean`
+- `throttle?: number`
+- `throtle?: number` (legacy alias)
+
+### `buildClassicStore<T>(defaultState)`
+
+`defaultState` can be either a plain initial state or an object with:
+
+- `beforeLoadState: T`
+- `hydrator: () => Promise<T>`
+- `persist?: (state: T) => Promise<void>`
+
+Returns:
+
+- `useStore()`: React hook for `[state, update]`.
+- `useSelector(selector)`: React hook for derived values.
+- `update(updater)`: update function.
+- `getValue()`: current value getter.
+- `subject$`: `BehaviorSubject<T>`.
+- `defaultState`: the provided default state.
+
+### `wuji`
+
+Alias of `createEventStore`.
+
+## Troubleshooting
+
+- Hydration errors: `systemEvents$` emits `@@HYDRATE_ERROR` and the console logs
+  `Failed to hydrate store`. Verify the hydrator resolves with the same shape
+  as the initial state and handle thrown errors.
+- Persist errors: `systemEvents$` emits `@@PERSIST_ERROR` and the console logs
+  `Failed to persist store`. Ensure your persist callback returns a promise and
+  handles storage quotas or serialization failures.
+- Disposed stores still referenced: call `destroy()` when a store is no longer
+  used, and avoid calling `publish/reset/feed` afterward.
+
+## 1.0 Migration Notes
 
-**Why Dantian?**
+- No breaking changes are required.
+- `destroy()` is now available to explicitly dispose of stores.
+- `systemEvents$` now includes `@@HYDRATE_ERROR` and `@@PERSIST_ERROR` events.
 
-Performance by design: Avoid unnecessary rerenders, especially in complex forms.
-Developer-friendly: Intuitive API and seamless form integration.
-**License**
+## License
 
 MIT