storion 0.8.3 → 0.10.0

package/CHANGELOG.md

@@ -8,31 +8,122 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+
+- `SelectorContext.scoped()` for component-local stores that auto-dispose on unmount
+  ```tsx
+  const { value, setValue } = useStore(({ scoped }) => {
+    const [state, actions, instance] = scoped(formStore);
+    return { value: state.value, setValue: actions.setValue };
+  });
+  ```
+- `async.mixin()` for component-local async state (mutations, form submissions)
+
+  ```tsx
+  // Define mutation - no store needed
+  const submitForm = async.mixin(async (ctx, data: FormData) => {
+    const res = await fetch("/api/submit", {
+      method: "POST",
+      body: JSON.stringify(data),
+      signal: ctx.signal,
+    });
+    return res.json();
+  });
+
+  // Use as mixin - state is component-local, auto-disposed
+  const { status, submit } = useStore(({ mixin }) => {
+    const [state, actions] = mixin(submitForm);
+    return { status: state.status, submit: actions.dispatch };
+  });
+  ```
+
+- `AsyncContext.get()` allows async handlers to access other stores' state
+
+  ```tsx
+  // Access other stores for cross-store mutations
+  const checkout = async.mixin(async (ctx, paymentMethod: string) => {
+    const [user] = ctx.get(userStore);
+    const [cart] = ctx.get(cartStore);
+    return fetch("/api/checkout", {
+      body: JSON.stringify({ userId: user.id, items: cart.items }),
+    });
+  });
+  ```
+
 - `MetaEntry.fields` now supports arrays for applying meta to multiple fields at once
   ```ts
-  meta: [notPersisted.for(["password", "token"])]
+  meta: [notPersisted.for(["password", "token"])];
   ```
 - `MetaQuery.fields(type, predicate?)` method to get field names with a specific meta type
   ```ts
-  const sessionFields = ctx.meta.fields(sessionStore);  // ['token', 'userId']
-  const highPriority = ctx.meta.fields(priority, v => v > 5);
-  ```
-- `persistMiddleware` `fields` option for multi-storage patterns
-  ```ts
-  // Split fields between session and local storage
-  persistMiddleware({
-    filter: ({ meta }) => meta.any(sessionStore),
-    fields: ({ meta }) => meta.fields(sessionStore),
-    save: (ctx, state) => sessionStorage.setItem(ctx.displayName, JSON.stringify(state)),
-  })
+  const sessionFields = ctx.meta.fields(sessionStore); // ['token', 'userId']
+  const highPriority = ctx.meta.fields(priority, (v) => v > 5);
   ```
 - `applyFor` now supports object form to map patterns to different middleware
   ```ts
   applyFor({
-    "userStore": loggingMiddleware,
+    userStore: loggingMiddleware,
     "auth*": [authMiddleware, securityMiddleware],
     "*Cache": cacheMiddleware,
-  })
+  });
+  ```
+
+### Removed
+
+- **BREAKING**: `useLocalStore` hook removed - use `scoped()` in `useStore` selector instead
+
+  ```tsx
+  // Before
+  const [state, actions] = useLocalStore(formStore);
+
+  // After
+  const { state, actions } = useStore(({ scoped }) => {
+    const [s, a] = scoped(formStore);
+    return { state: s, actions: a };
+  });
+  ```
+
+- **BREAKING**: `SelectorContext.create()` removed - creates uncontrolled instances without disposal tracking. Use `get()` for cached services or `scoped()` for component-local stores instead.
+
+### Changed
+
+- **BREAKING**: `persist` API refactored for better encapsulation (renamed from `persistMiddleware`)
+
+  - New `handler` option replaces `load`/`save` callbacks
+  - `persistMiddleware` is now deprecated, use `persist` instead
+  - Handler receives `PersistContext` (extends `StoreMiddlewareContext` with `store` instance)
+  - Handler returns `{ load, save }` object (can be sync or async)
+  - `onError` signature changed to `(error, operation)` where operation is `"init" | "load" | "save"`
+  - Enables encapsulated async initialization (e.g., IndexedDB)
+
+  ```ts
+  // Before (old API)
+  persistMiddleware({
+    load: (ctx) => localStorage.getItem(ctx.displayName),
+    save: (ctx, state) =>
+      localStorage.setItem(ctx.displayName, JSON.stringify(state)),
+  });
+
+  // After (new API)
+  persist({
+    handler: (ctx) => {
+      const key = `app:${ctx.displayName}`;
+      return {
+        load: () => JSON.parse(localStorage.getItem(key) || "null"),
+        save: (state) => localStorage.setItem(key, JSON.stringify(state)),
+      };
+    },
+  });
+
+  // Async handler (IndexedDB)
+  persist({
+    handler: async (ctx) => {
+      const db = await openDB("app-db");
+      return {
+        load: () => db.get("stores", ctx.displayName),
+        save: (state) => db.put("stores", state, ctx.displayName),
+      };
+    },
+  });
   ```
 
 ---
@@ -40,8 +131,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.8.0] - 2024-12-21
 
 ### Added
+
 - **Persist Module** (`storion/persist`)
-  - `persistMiddleware(options)` for automatic state persistence
+  - `persist(options)` for automatic state persistence
   - `notPersisted` meta for excluding stores or fields from persistence
   - Supports sync and async `load`/`save` handlers
   - `force` option to override dirty state during hydration
@@ -58,6 +150,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `store.hydrate(state, { force })` - force option to override dirty properties
 
 ### Changed
+
 - `StoreMiddlewareContext` now includes `meta` property for querying store metadata
 - `FactoryMiddlewareContext` now includes `meta` property for querying factory metadata
 
@@ -66,6 +159,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.7.0] - 2024-12-15
 
 ### Added
+
 - **DevTools Module** (`storion/devtools`)
   - `devtoolsMiddleware()` for state inspection
   - `__revertState` and `__takeSnapshot` injected actions
@@ -79,6 +173,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `create()` shorthand for single-store apps returning `[instance, useHook, withStore]`
 
 ### Changed
+
 - Improved TypeScript inference for store actions
 
 ---
@@ -86,6 +181,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.6.0] - 2024-12-01
 
 ### Added
+
 - **Async Module** (`storion/async`)
   - `async.fresh<T>()` - throws during loading (Suspense-compatible)
   - `async.stale<T>(initialData)` - returns stale data during loading
@@ -95,6 +191,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `trigger(action, deps, ...args)` for declarative data fetching in components
 
 ### Changed
+
 - Effects now require synchronous functions (use `ctx.safe()` for async)
 
 ---
@@ -102,6 +199,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.5.0] - 2024-11-15
 
 ### Added
+
 - **Focus (Lens-like Access)**
   - `focus(path)` for nested state access
   - Returns `[getter, setter]` tuple
@@ -119,6 +217,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.4.0] - 2024-11-01
 
 ### Added
+
 - **Middleware System**
   - `container({ middleware: [...] })` for middleware injection
   - Middleware receives `MiddlewareContext` with `type`, `next`, `resolver`
@@ -127,6 +226,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `createValidationMiddleware()` built-in middleware
 
 ### Changed
+
 - Container now uses middleware chain pattern
 
 ---
@@ -134,6 +234,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.3.0] - 2024-10-15
 
 ### Added
+
 - **Store Lifecycle**
   - `lifetime: "keepAlive"` (default) - persists until container disposal
   - `lifetime: "autoDispose"` - disposes when no subscribers
@@ -145,6 +246,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `store.reset()` to restore initial state
 
 ### Changed
+
 - Stores now track dirty state automatically
 
 ---
@@ -152,6 +254,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.2.0] - 2024-10-01
 
 ### Added
+
 - **Dependency Injection**
   - `container()` for managing store instances
   - `get(factory)` for resolving dependencies
@@ -161,6 +264,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `useContainer()` hook
 
 ### Changed
+
 - Stores are now lazily instantiated via container
 
 ---
@@ -168,6 +272,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.1.0] - 2024-09-15
 
 ### Added
+
 - **Core Store**
   - `store(options)` factory function
   - `state` - reactive state object
@@ -195,22 +300,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Migrating to 0.8.0
 
 #### Meta System Changes
+
 If you were using internal meta APIs, update to the new public API:
 
 ```ts
 // Before (internal)
-spec.meta // was MetaEntry[]
+spec.meta; // was MetaEntry[]
 
 // After (0.8.0)
-ctx.meta(persistMeta).store    // query store-level
-ctx.meta(persistMeta).fields   // query field-level
-ctx.meta.all(type)             // get all values
-ctx.meta.any(type1, type2)     // check existence
+ctx.meta(persistMeta).store; // query store-level
+ctx.meta(persistMeta).fields; // query field-level
+ctx.meta.all(type); // get all values
+ctx.meta.any(type1, type2); // check existence
 ```
 
 ### Migrating to 0.6.0
 
 #### Async Effects
+
 Effects must now be synchronous:
 
 ```ts
@@ -239,4 +346,3 @@ effect((ctx) => {
 [0.3.0]: https://github.com/linq2js/storion/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/linq2js/storion/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/linq2js/storion/releases/tag/v0.1.0
-