storion 0.8.3 → 0.10.0

package/dist/persist/persist.d.ts

@@ -1,4 +1,4 @@
-import { StoreMiddleware, StoreMiddlewareContext } from '../types';
+import { StoreMiddleware, StoreMiddlewareContext, StoreInstance } from '../types';
 
 /**
  * Mark stores or fields as not persisted.
@@ -27,8 +27,8 @@ import { StoreMiddleware, StoreMiddlewareContext } from '../types';
  *   state: { name: '', password: '', token: '' },
  *   setup: () => ({}),
  *   meta: [
- *     notPersisted('password'),
- *     notPersisted('token'),
+ *     notPersisted.for('password'),
+ *     notPersisted.for('token'),
  *   ],
  * });
  * ```
@@ -38,6 +38,33 @@ export declare const notPersisted: import('..').MetaType<any, [], true>;
  * Result from load function - can be sync or async
  */
 export type PersistLoadResult = Record<string, unknown> | null | undefined | Promise<Record<string, unknown> | null | undefined>;
+/**
+ * Context passed to the handler function.
+ * Extends StoreMiddlewareContext with the created store instance.
+ */
+export interface PersistContext extends StoreMiddlewareContext {
+    /** The store instance being persisted */
+    store: StoreInstance;
+}
+/**
+ * Handler returned by the handler function.
+ * Contains the load and save operations for a specific store.
+ */
+export interface PersistHandler {
+    /**
+     * Load persisted state for the store.
+     * Can return sync or async result.
+     *
+     * @returns The persisted state, null/undefined if not found, or a Promise
+     */
+    load?: () => PersistLoadResult;
+    /**
+     * Save state to persistent storage.
+     *
+     * @param state - The dehydrated state to save
+     */
+    save?: (state: Record<string, unknown>) => void;
+}
 /**
  * Options for persist middleware
  */
@@ -46,41 +73,56 @@ export interface PersistOptions {
      * Filter which stores should be persisted.
      * If not provided, all stores are persisted.
      *
-     * @param context - The middleware context
+     * @param context - The persist context with store instance
      * @returns true to persist, false to skip
      */
-    filter?: (context: StoreMiddlewareContext) => boolean;
+    filter?: (context: PersistContext) => boolean;
     /**
      * Filter which fields should be persisted.
      * If not provided, all fields are persisted.
      *
-     * @param context - The middleware context
+     * @param context - The persist context with store instance
      * @returns the fields to persist
      */
-    fields?: (context: StoreMiddlewareContext) => string[];
+    fields?: (context: PersistContext) => string[];
     /**
-     * Load persisted state for a store.
-     * Can return sync or async result.
+     * Handler factory that creates load/save operations for each store.
+     * Receives context with store instance, returns handler with load/save.
+     * Can be sync or async (e.g., for IndexedDB initialization).
      *
-     * @param context - The middleware context
-     * @returns The persisted state, null/undefined if not found, or a Promise
-     */
-    load?: (context: StoreMiddlewareContext) => PersistLoadResult;
-    /**
-     * Save state to persistent storage.
+     * @param context - The persist context with store instance
+     * @returns Handler with load/save operations, or Promise of handler
      *
-     * @param context - The middleware context
-     * @param state - The dehydrated state to save
+     * @example Sync handler (localStorage)
+     * ```ts
+     * handler: (ctx) => {
+     *   const key = `app:${ctx.displayName}`;
+     *   return {
+     *     load: () => JSON.parse(localStorage.getItem(key) || 'null'),
+     *     save: (state) => localStorage.setItem(key, JSON.stringify(state)),
+     *   };
+     * }
+     * ```
+     *
+     * @example Async handler (IndexedDB)
+     * ```ts
+     * handler: async (ctx) => {
+     *   const db = await openDB('app-db');
+     *   return {
+     *     load: () => db.get('stores', ctx.displayName),
+     *     save: (state) => db.put('stores', state, ctx.displayName),
+     *   };
+     * }
+     * ```
      */
-    save?: (context: StoreMiddlewareContext, state: Record<string, unknown>) => void;
+    handler: (context: PersistContext) => PersistHandler | PromiseLike<PersistHandler>;
     /**
-     * Called when an error occurs during load or save.
+     * Called when an error occurs during init, load, or save.
      *
-     * @param context - The middleware context
      * @param error - The error that occurred
-     * @param operation - Whether the error occurred during 'load' or 'save'
+     * @param operation - Whether the error occurred during 'init', 'load', or 'save'
      */
-    onError?: (context: StoreMiddlewareContext, error: unknown, operation: "load" | "save") => void;
+    onError?: (error: unknown, operation: "init" | "load" | "save") => void;
     /**
      * Force hydration to overwrite dirty (modified) state properties.
      *
@@ -96,62 +138,77 @@ export interface PersistOptions {
 /**
  * Creates a persist middleware that automatically saves and restores store state.
  *
- * @example
+ * @example localStorage (sync handler)
  * ```ts
- * import { container } from "storion";
- * import { persistMiddleware } from "storion/persist";
+ * import { container, forStores } from "storion";
+ * import { persist } from "storion/persist";
  *
  * const app = container({
- *   middleware: [persistMiddleware({
- *     load: (ctx) => {
- *       const key = `storion:${ctx.spec.displayName}`;
- *       const data = localStorage.getItem(key);
- *       return data ? JSON.parse(data) : null;
- *     },
- *     save: (ctx, state) => {
- *       const key = `storion:${ctx.spec.displayName}`;
- *       localStorage.setItem(key, JSON.stringify(state));
- *     },
- *     onError: (ctx, error, op) => {
- *       console.error(`Persist ${op} error for ${ctx.spec.displayName}:`, error);
- *     },
- *   })],
+ *   middleware: forStores([
+ *     persist({
+ *       handler: (ctx) => {
+ *         const key = `app:${ctx.displayName}`;
+ *         return {
+ *           load: () => JSON.parse(localStorage.getItem(key) || 'null'),
+ *           save: (state) => localStorage.setItem(key, JSON.stringify(state)),
+ *         };
+ *       },
+ *       onError: (error, op) => console.error(`Persist ${op} failed:`, error),
+ *     }),
+ *   ]),
  * });
  * ```
  *
- * @example Async load (e.g., IndexedDB)
+ * @example IndexedDB (async handler)
  * ```ts
- * persistMiddleware({
- *   load: async (ctx) => {
- *     const db = await openDB();
- *     return db.get('stores', ctx.spec.displayName);
- *   },
- *   save: (ctx, state) => {
- *     openDB().then(db => db.put('stores', state, ctx.spec.displayName));
+ * persist({
+ *   handler: async (ctx) => {
+ *     const db = await openDB('app-db', 1, {
+ *       upgrade(db) { db.createObjectStore('stores'); },
+ *     });
+ *     return {
+ *       load: () => db.get('stores', ctx.displayName),
+ *       save: (state) => db.put('stores', state, ctx.displayName),
+ *     };
  *   },
  * });
  * ```
  *
- * @example Using meta in callbacks
+ * @example With shared debounce
  * ```ts
- * import { meta } from "storion";
+ * persist({
+ *   handler: (ctx) => {
+ *     const key = `app:${ctx.displayName}`;
+ *     const debouncedSave = debounce(
+ *       (s) => localStorage.setItem(key, JSON.stringify(s)),
+ *       300
+ *     );
+ *     return {
+ *       load: () => JSON.parse(localStorage.getItem(key) || 'null'),
+ *       save: debouncedSave,
+ *     };
+ *   },
+ * });
+ * ```
  *
- * const persistKey = meta<string>();
+ * @example Multi-storage with meta
+ * ```ts
+ * const inSession = meta();
+ * const inLocal = meta();
  *
- * persistMiddleware({
- *   load: (ctx) => {
- *     // Use custom key from meta, fallback to displayName
- *     const customKey = ctx.meta(persistKey).store;
- *     const key = customKey ?? ctx.spec.displayName;
- *     return JSON.parse(localStorage.getItem(key) || 'null');
- *   },
- *   save: (ctx, state) => {
- *     const customKey = ctx.meta(persistKey).store;
- *     const key = customKey ?? ctx.spec.displayName;
- *     localStorage.setItem(key, JSON.stringify(state));
+ * // Session storage middleware
+ * persist({
+ *   filter: ({ meta }) => meta.any(inSession),
+ *   fields: ({ meta }) => meta.fields(inSession),
+ *   handler: (ctx) => {
+ *     const key = `session:${ctx.displayName}`;
+ *     return {
+ *       load: () => JSON.parse(sessionStorage.getItem(key) || 'null'),
+ *       save: (state) => sessionStorage.setItem(key, JSON.stringify(state)),
+ *     };
  *   },
  * });
  * ```
  */
-export declare function persistMiddleware(options: PersistOptions): StoreMiddleware;
+export declare function persist(options: PersistOptions): StoreMiddleware;
 //# sourceMappingURL=persist.d.ts.map

package/dist/persist/persist.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persist.d.ts","sourceRoot":"","sources":["../../src/persist/persist.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAIxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,YAAY,sCAAS,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvB,IAAI,GACJ,SAAS,GACT,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC;IAEtD;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,MAAM,EAAE,CAAC;IAEvD;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,iBAAiB,CAAC;IAE9D;;;;;OAKG;IACH,IAAI,CAAC,EAAE,CACL,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,IAAI,CAAC;IAEV;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CACR,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAAG,MAAM,KACvB,IAAI,CAAC;IAEV;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,eAAe,CAyH1E"}
+{"version":3,"file":"persist.d.ts","sourceRoot":"","sources":["../../src/persist/persist.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EACtB,aAAa,EACd,MAAM,UAAU,CAAC;AAIlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,YAAY,sCAAS,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvB,IAAI,GACJ,SAAS,GACT,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,sBAAsB;IAC5D,yCAAyC;IACzC,KAAK,EAAE,aAAa,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,iBAAiB,CAAC;IAE/B;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC;IAE9C;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,MAAM,EAAE,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,OAAO,EAAE,CACP,OAAO,EAAE,cAAc,KACpB,cAAc,GAAG,WAAW,CAAC,cAAc,CAAC,CAAC;IAElD;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,KAAK,IAAI,CAAC;IAExE;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,eAAe,CAmJhE"}

package/dist/pool.d.ts

@@ -0,0 +1,77 @@
+import { AutoDisposeOptions, Equality } from './types';
+
+/**
+ * A lazy-instantiation Map with factory function.
+ * Items are created on-demand via `get()`.
+ */
+export interface Pool<TKey, TValue> {
+    (key: TKey): TValue;
+    /** Call callback if key exists (does NOT create item). Chainable. */
+    tap(key: TKey, callback: (item: TValue) => void): this;
+    /** Check if key exists (does NOT create item). */
+    has(key: TKey): boolean;
+    /** Get item by key, creating it via factory if it doesn't exist. */
+    get(key: TKey): TValue;
+    /** Explicitly set an item. Chainable. */
+    set(key: TKey, value: TValue): this;
+    /** Number of items in the pool. */
+    size(): number;
+    /** Remove all items. Calls dispose if autoDispose enabled. Chainable. */
+    clear(): this;
+    /** Remove item by key. Calls dispose if autoDispose enabled. Chainable. */
+    delete(key: TKey): this;
+    /** Iterate over keys. */
+    keys(): IterableIterator<TKey>;
+    /** Iterate over values. */
+    values(): IterableIterator<TValue>;
+    /** Iterate over [key, value] pairs. */
+    entries(): IterableIterator<[TKey, TValue]>;
+}
+export interface PoolOptions<TKey, TValue> {
+    initial?: readonly [TKey, TValue][];
+    /**
+     * Custom equality function for keys (O(n) lookup).
+     * For better performance, use `keyOf` instead.
+     */
+    equality?: Equality<TKey>;
+    /**
+     * Hash function to normalize keys (O(1) lookup).
+     * Converts complex keys to a hashable string/number.
+     *
+     * @example
+     * ```ts
+     * // Object keys hashed by id
+     * pool(createUser, { keyOf: (user) => user.id })
+     *
+     * // Array keys hashed by JSON
+     * pool(createItem, { keyOf: JSON.stringify })
+     * ```
+     */
+    keyOf?: (key: TKey) => string | number;
+    /**
+     * Automatically call dispose method of the item when it is removed from the pool.
+     */
+    autoDispose?: AutoDisposeOptions | boolean;
+}
+/**
+ * Lazy-instantiation Map wrapper.
+ *
+ * Creates items on first access via `get()`. Useful for managing
+ * pools where items should be created on-demand.
+ *
+ * @example
+ * ```ts
+ * // Create a pool of emitters, one per property key
+ * const emitters = pool((key: string) => emitter<void>());
+ *
+ * // First access creates the emitter
+ * const countEmitter = emitters.get("count"); // creates new emitter
+ * const countEmitter2 = emitters.get("count"); // returns same emitter
+ * ```
+ *
+ * @param createItem - Factory function to create new items
+ * @param optionsOrInitial - Optional options or initial entries
+ * @returns A Map-like object with lazy instantiation on `get()`
+ */
+export declare function pool<TValue, TKey = unknown>(createItem: (key: TKey) => TValue, optionsOrInitial?: PoolOptions<TKey, TValue> | readonly [TKey, TValue][]): Pool<TKey, TValue>;
+//# sourceMappingURL=pool.d.ts.map

package/dist/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,IAAI,CAAC,IAAI,EAAE,MAAM;IAChC,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;IACpB,qEAAqE;IACrE,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IACvD,kDAAkD;IAClD,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC;IACxB,oEAAoE;IACpE,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;IACvB,yCAAyC;IACzC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,mCAAmC;IACnC,IAAI,IAAI,MAAM,CAAC;IACf,yEAAyE;IACzE,KAAK,IAAI,IAAI,CAAC;IACd,2EAA2E;IAC3E,MAAM,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,yBAAyB;IACzB,IAAI,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC/B,2BAA2B;IAC3B,MAAM,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACnC,uCAAuC;IACvC,OAAO,IAAI,gBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,WAAW,CAAC,IAAI,EAAE,MAAM;IACvC,OAAO,CAAC,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,GAAG,MAAM,CAAC;IAEvC;;OAEG;IACH,WAAW,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,EACzC,UAAU,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,EACjC,gBAAgB,CAAC,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,GACvE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CA6LpB"}

package/dist/react/index.d.ts

@@ -5,8 +5,8 @@
  */
 export { StoreProvider, useContainer } from './context';
 export { useStore } from './useStore';
-export { type LocalStoreResult } from './useLocalStore';
-export { withStore, createWithStore, type WithStoreHook, type WithStoreRender, type WithStoreRenderWithRef, type WithStoreOptions, type BoundWithStore, type GenericWithStoreHook, type UseContextHook, } from './withStore';
+export { withStore, type WithStoreHook, type WithStoreRender, type WithStoreRenderWithRef, type WithStoreOptions, type BoundWithStore, type GenericWithStoreHook, type UseContextHook, } from './withStore';
 export { create, type CreateSelector, type UseCreatedStore, type CreateResult, type CreatedStoreContext, type WithCreatedStore, } from './create';
+export { stable, type PropEqualityConfig } from './stable';
 export * from '../index';
 //# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGxD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,SAAS,EACT,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,MAAM,EACN,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,UAAU,CAAC;AAGlB,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGxD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EACL,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,MAAM,EACN,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,MAAM,EAAE,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAG3D,cAAc,UAAU,CAAC"}