memorio 4.9.10 → 4.9.30

package/README.md

@@ -135,14 +135,79 @@ observer('state.user.name', callback)
 `dispatch` is the event mechanism underneath it, if you need to hook in lower-level:
 
 ```ts
-memorio.dispatch.listen('state.user', event => console.debug(event.detail))
+const off = memorio.dispatch.listen('state.user', event => console.debug(event.detail))
 memorio.dispatch.set('state.user', { detail: { name: 'Sara' } })
+
+off()                                   // remove only this subscription
+memorio.dispatch.remove('state.user')   // remove all subscriptions on a name
 ```
 
+Multiple subscribers on the same path each keep firing — each `listen` returns
+its own unsubscribe. Prefer the returned `off()` over `remove()` for per-caller
+teardown, since `remove()` clears *every* listener registered under that name.
+
 `observer` paths are runtime strings — for compiler-checked access, see [typed state](#typed-state--schema-validation).
 
 React apps get a dedicated hook, `useObserver` — see [React integration](#react-integration).
 
+## Redux / state-manager integration
+
+Memorio ships its Redux integration as a **separate, optional entrypoint** (`memorio/redux`). It is
+*not* part of core and is **never imported by `import memorio from 'memorio'`** — so applications
+that don't use Redux pay nothing. Redux is neither a dependency of Memorio nor of the adapter: the
+adapter talks to any store that satisfies a tiny structural shape (`getState` / `subscribe` /
+`dispatch`), so `redux`, Redux Toolkit, Zustand, NgRx, etc. are all accepted without importing the
+`redux` types.
+
+> **Ownership rule:** *Redux owns application state. Memorio owns memory.* The adapter only writes
+> **selected** values (declared opt-in mappings) into Memorio memory, and only recalls them once,
+> at bootstrap. It never mirrors the whole Redux tree and never two-way syncs.
+
+```ts
+import memorio from 'memorio'
+import { createMemorioReduxBridge } from 'memorio/redux'
+
+type AppState = { user: { name: string; preferences?: { theme?: string } } }
+
+const memorioRedux = createMemorioReduxBridge<AppState>({
+  // Opt-in: only these paths become durable memory.
+  mappings: {
+    'user.preferences': {
+      selector: (s) => s.user.preferences,
+      type: 'preference',
+      scope: 'local',          // never 'hot' for Redux mappings
+      tags: ['app', 'user']
+    },
+    'user.name': (s) => s.user.name   // a bare selector is also accepted
+  },
+  // Performance: only consider the action types that can mutate mapped state.
+  whitelist: ['user/preferencesChanged', 'user/nameChanged'],
+  // Diagnostics
+  debug: true
+})
+
+const store = createStore(reducer, applyMiddleware(memorioRedux.middleware))
+
+// Bootstrap hydration (Memorio -> Redux, one-shot). The bridge arms a
+// re-entrancy guard so the restore dispatch does not echo back to Memorio.
+await memorioRedux.hydrate(store, {
+  onHydration: (values) => store.dispatch(restorePreferences(values))
+})
+```
+
+Directional flow, no loops:
+
+| Direction | Mechanism | Ownership |
+| --- | --- | --- |
+| Redux -> Memorio | middleware persists only `mappings` whose selector changed **and** whose action type isn't blacklisted (#30) | Memorio is the durable owner (#31) |
+| Memorio -> Redux | `hydrate()` recalls once at bootstrap; the app dispatches its own restore actions | Redux owns runtime state |
+
+- **No store mirroring:** only mapped selectors are persisted — never `store.getState()` wholesale.
+- **No synchronization loops:** hydration arms `setHydrating(true)` + seeds the change-detection cache, so the restore dispatch is seen as "no change" and is not re-persisted.
+- **Async is off the reducer path:** middleware defers `memorio.memory.remember` to a microtask and coerces a burst of actions into a single flush.
+- **Failure-isolated:** Memorio errors are swallowed by default (`failSoft: true`, default) and routed to `onError`; Redux dispatch always completes normally.
+- **Production-safe:** nothing in the adapter exposes Memorio's database on `globalThis` / DevTools.
+
 ## The layers
 
 ### `store` — persistent key/value

package/examples/basic.ts

@@ -81,7 +81,7 @@ console.debug('Username:', store.get('username'))
 console.debug('Preferences:', store.get('preferences'))
 
 // Get storage size
-console.debug('Storage size:', store.size(), 'bytes')
+console.debug('Storage size:', store.size(), 'kilobytes')
 
 // ============================================
 // SESSION - Temporary session storage

package/examples/session-advanced.ts

@@ -73,7 +73,7 @@ console.debug('Cart total:', total)
 // ============================================
 
 // Get session storage size
-console.debug('Session size:', session.size(), 'bytes')
+console.debug('Session size:', session.size(), 'kilobytes')
 
 // ============================================
 // CLEANUP

package/examples/store-advanced.ts

@@ -51,7 +51,7 @@ if (savedPrefs) {
 
 // Get storage size
 const currentSize = store.size()
-console.debug('Current storage size:', currentSize, 'bytes')
+console.debug('Current storage size:', currentSize, 'kilobytes')
 
 // ============================================
 // ALIAS METHODS

package/index.cjs

@@ -645,24 +645,29 @@ var init_store = __esm({
             }, "value")
           },
           /**
-           * Calculates total size of all memorio items (characters).
+           * Calculates total size of all memorio items in kilobytes.
+           * Counts each prefixed key and its JSON-serialized value, summing their
+           * byte lengths and converting to whole kilobytes (Math.ceil). Replaces
+           * the previous character-only total which did not express real usage.
+           * @returns Total size in kilobytes (0 when empty / no memorio items).
            */
           size: {
             value: /* @__PURE__ */ __name(() => {
-              let totalSize = 0;
+              let totalBytes = 0;
               if (_hasStorage) {
-                Object.keys(_localStorage).forEach((key) => {
-                  if (key.startsWith(_getPrefix())) {
+                for (let i = 0; i < _localStorage.length; i++) {
+                  const key = _localStorage.key(i);
+                  if (key && key.startsWith(_getPrefix())) {
                     const item = _localStorage.getItem(key);
-                    if (item) totalSize += item.length;
+                    if (item) totalBytes += key.length + item.length;
                   }
-                });
+                }
               } else {
-                _getFallbackStorage().forEach((value) => {
-                  totalSize += value.length;
+                _getFallbackStorage().forEach((value, key) => {
+                  totalBytes += key.length + value.length;
                 });
               }
-              return totalSize;
+              return totalBytes === 0 ? 0 : Math.ceil(totalBytes / 1024);
             }, "value")
           },
           /**
@@ -1733,30 +1738,51 @@ var dispatch = {
   }, "set"),
   ///
   /**
-   * Listens for the specified event names and executes the callback when the event is triggered.
+   * Subscribes a callback to an event name. Maintains a *list* of handlers per
+   * name, so multiple subscribers on the same path (e.g. several
+   * `useObserver` calls observing `state.report`) each keep firing and each
+   * get an independent unsubscribe. The previous single-slot-per-name
+   * behaviour silently dropped the second subscriber and let any unsubscribe
+   * cancel every other subscriber on that path.
    * @param name The name of the event to listen for.
    * @param cb The callback function to execute when the event is triggered.
+   * @returns An unsubscribe function for this subscriber, or void if no callback.
    */
   listen: /* @__PURE__ */ __name((name, cb = null, _flag) => {
-    if (globalThis.events?.[name]) return;
-    const exec = cb ? (e) => {
+    if (!cb) return;
+    const wrapped = /* @__PURE__ */ __name((e) => {
       const target = e;
-      return globalThis.queueMicrotask ? globalThis.queueMicrotask(() => cb(target)) : Promise.resolve().then(() => cb(target));
-    } : void 0;
-    if (exec) globalThis.addEventListener(name, exec);
-    if (exec) globalThis.events[name] = exec;
+      if (globalThis.queueMicrotask) {
+        globalThis.queueMicrotask(() => cb(target));
+      } else {
+        Promise.resolve().then(() => cb(target));
+      }
+    }, "wrapped");
+    globalThis.addEventListener(name, wrapped);
+    const list = globalThis.events[name] = globalThis.events[name] ?? [];
+    list.push(wrapped);
+    return () => {
+      globalThis.removeEventListener(name, wrapped);
+      const idx = list.indexOf(wrapped);
+      if (idx > -1) list.splice(idx, 1);
+      if (!list.length) delete globalThis.events[name];
+    };
   }, "listen"),
   ///
   /**
-   * Removes the event listener for the specified event names.
-   * @param name The name of the event to remove the listener for.
+   * Removes ALL handlers for the specified event name (imperative bulk
+   * removal). For per-subscriber teardown, use the unsubscribe function
+   * returned by `listen`.
+   * @param name The name of the event to remove the listeners for.
    */
   remove: /* @__PURE__ */ __name((name) => {
-    const listener = globalThis.events?.[name];
-    if (listener) {
-      globalThis.removeEventListener(name, listener);
-      delete globalThis.events[name];
+    const entry = globalThis.events?.[name];
+    if (Array.isArray(entry)) {
+      entry.forEach((h) => globalThis.removeEventListener(name, h));
+    } else if (typeof entry === "function") {
+      globalThis.removeEventListener(name, entry);
     }
+    delete globalThis.events[name];
   }, "remove")
 };
 
@@ -2285,27 +2311,28 @@ if (globalThis[SESSION_INSTANCE_KEY]) {
         }, "value")
       },
       /**
-       * Gets total size of all sessionStorage items.
-       * @returns Total size in characters.
+       * Calculates total size of all memorio session items in kilobytes.
+       * Counts each prefixed key and its JSON-serialized value, summing their
+       * byte lengths and converting to whole kilobytes (Math.ceil).
+       * @returns Total size in kilobytes (0 when empty / no memorio items).
        */
       size: {
         value: /* @__PURE__ */ __name(() => {
-          let totalSize = 0;
+          let totalBytes = 0;
           if (_hasStorage2) {
-            Object.keys(_sessionStorage).forEach(
-              (key) => {
-                if (key.startsWith(_getPrefix2())) {
-                  const item = _sessionStorage.getItem(key);
-                  if (item) totalSize += item.length;
-                }
+            for (let i = 0; i < _sessionStorage.length; i++) {
+              const key = _sessionStorage.key(i);
+              if (key && key.startsWith(_getPrefix2())) {
+                const item = _sessionStorage.getItem(key);
+                if (item) totalBytes += key.length + item.length;
               }
-            );
+            }
           } else {
-            _getFallbackStorage2().forEach((value) => {
-              totalSize += value.length;
+            _getFallbackStorage2().forEach((value, key) => {
+              totalBytes += key.length + value.length;
             });
           }
-          return totalSize;
+          return totalBytes === 0 ? 0 : Math.ceil(totalBytes / 1024);
         }, "value")
       },
       /**
@@ -2524,6 +2551,7 @@ var useObserver = /* @__PURE__ */ __name(((func, deps = []) => {
     };
   }
   const handlers = [];
+  const unsubs = [];
   const depList = Array.isArray(deps) && !deps.__path ? deps : [deps];
   try {
     depList.forEach((dep) => {
@@ -2537,8 +2565,11 @@ var useObserver = /* @__PURE__ */ __name(((func, deps = []) => {
       if (t) {
         t = t.replace(/^(\(\)\s*=>\s*)/, "").replace(/^globalThis\./, "").replace(/^state\./, "");
         const path = t.startsWith("store.") || t.startsWith("state.") ? t : "state." + t;
-        dispatch.listen(path, () => func());
-        handlers.push(path);
+        if (!handlers.includes(path)) {
+          handlers.push(path);
+          const off = dispatch.listen(path, () => func());
+          if (typeof off === "function") unsubs.push({ path, off });
+        }
       } else {
         exports.internal.clearTrackedPaths();
         exports.internal.tracking = true;
@@ -2550,8 +2581,9 @@ var useObserver = /* @__PURE__ */ __name(((func, deps = []) => {
         exports.internal.trackedPaths.forEach((path) => {
           if (!handlers.includes(path)) {
             message_default(`useObserver: [Auto-Discovery] -> "${path}"`);
-            dispatch.listen(path, () => func());
             handlers.push(path);
+            const off = dispatch.listen(path, () => func());
+            if (typeof off === "function") unsubs.push({ path, off });
           }
         });
       }
@@ -2562,11 +2594,9 @@ var useObserver = /* @__PURE__ */ __name(((func, deps = []) => {
       console.warn(`useObserver: No paths resolved for monitoring. Check your dependencies!`);
     }
     return () => {
-      handlers.forEach((path) => {
-        if (typeof dispatch.remove === "function") {
-          dispatch.remove(path);
-          message_default(`useObserver: Stopped monitoring "${path}"`);
-        }
+      unsubs.forEach(({ path, off }) => {
+        off();
+        message_default(`useObserver: Stopped monitoring "${path}"`);
       });
     };
   } catch (err) {
@@ -3273,7 +3303,7 @@ init_internal();
 
 // package.json
 var package_default = {
-  version: "4.9.10"};
+  version: "4.9.30"};
 
 // core/global.ts
 init_env();

package/index.js

@@ -642,24 +642,29 @@ var init_store = __esm({
             }, "value")
           },
           /**
-           * Calculates total size of all memorio items (characters).
+           * Calculates total size of all memorio items in kilobytes.
+           * Counts each prefixed key and its JSON-serialized value, summing their
+           * byte lengths and converting to whole kilobytes (Math.ceil). Replaces
+           * the previous character-only total which did not express real usage.
+           * @returns Total size in kilobytes (0 when empty / no memorio items).
            */
           size: {
             value: /* @__PURE__ */ __name(() => {
-              let totalSize = 0;
+              let totalBytes = 0;
               if (_hasStorage) {
-                Object.keys(_localStorage).forEach((key) => {
-                  if (key.startsWith(_getPrefix())) {
+                for (let i = 0; i < _localStorage.length; i++) {
+                  const key = _localStorage.key(i);
+                  if (key && key.startsWith(_getPrefix())) {
                     const item = _localStorage.getItem(key);
-                    if (item) totalSize += item.length;
+                    if (item) totalBytes += key.length + item.length;
                   }
-                });
+                }
               } else {
-                _getFallbackStorage().forEach((value) => {
-                  totalSize += value.length;
+                _getFallbackStorage().forEach((value, key) => {
+                  totalBytes += key.length + value.length;
                 });
               }
-              return totalSize;
+              return totalBytes === 0 ? 0 : Math.ceil(totalBytes / 1024);
             }, "value")
           },
           /**
@@ -1730,30 +1735,51 @@ var dispatch = {
   }, "set"),
   ///
   /**
-   * Listens for the specified event names and executes the callback when the event is triggered.
+   * Subscribes a callback to an event name. Maintains a *list* of handlers per
+   * name, so multiple subscribers on the same path (e.g. several
+   * `useObserver` calls observing `state.report`) each keep firing and each
+   * get an independent unsubscribe. The previous single-slot-per-name
+   * behaviour silently dropped the second subscriber and let any unsubscribe
+   * cancel every other subscriber on that path.
    * @param name The name of the event to listen for.
    * @param cb The callback function to execute when the event is triggered.
+   * @returns An unsubscribe function for this subscriber, or void if no callback.
    */
   listen: /* @__PURE__ */ __name((name, cb = null, _flag) => {
-    if (globalThis.events?.[name]) return;
-    const exec = cb ? (e) => {
+    if (!cb) return;
+    const wrapped = /* @__PURE__ */ __name((e) => {
       const target = e;
-      return globalThis.queueMicrotask ? globalThis.queueMicrotask(() => cb(target)) : Promise.resolve().then(() => cb(target));
-    } : void 0;
-    if (exec) globalThis.addEventListener(name, exec);
-    if (exec) globalThis.events[name] = exec;
+      if (globalThis.queueMicrotask) {
+        globalThis.queueMicrotask(() => cb(target));
+      } else {
+        Promise.resolve().then(() => cb(target));
+      }
+    }, "wrapped");
+    globalThis.addEventListener(name, wrapped);
+    const list = globalThis.events[name] = globalThis.events[name] ?? [];
+    list.push(wrapped);
+    return () => {
+      globalThis.removeEventListener(name, wrapped);
+      const idx = list.indexOf(wrapped);
+      if (idx > -1) list.splice(idx, 1);
+      if (!list.length) delete globalThis.events[name];
+    };
   }, "listen"),
   ///
   /**
-   * Removes the event listener for the specified event names.
-   * @param name The name of the event to remove the listener for.
+   * Removes ALL handlers for the specified event name (imperative bulk
+   * removal). For per-subscriber teardown, use the unsubscribe function
+   * returned by `listen`.
+   * @param name The name of the event to remove the listeners for.
    */
   remove: /* @__PURE__ */ __name((name) => {
-    const listener = globalThis.events?.[name];
-    if (listener) {
-      globalThis.removeEventListener(name, listener);
-      delete globalThis.events[name];
+    const entry = globalThis.events?.[name];
+    if (Array.isArray(entry)) {
+      entry.forEach((h) => globalThis.removeEventListener(name, h));
+    } else if (typeof entry === "function") {
+      globalThis.removeEventListener(name, entry);
     }
+    delete globalThis.events[name];
   }, "remove")
 };
 
@@ -2282,27 +2308,28 @@ if (globalThis[SESSION_INSTANCE_KEY]) {
         }, "value")
       },
       /**
-       * Gets total size of all sessionStorage items.
-       * @returns Total size in characters.
+       * Calculates total size of all memorio session items in kilobytes.
+       * Counts each prefixed key and its JSON-serialized value, summing their
+       * byte lengths and converting to whole kilobytes (Math.ceil).
+       * @returns Total size in kilobytes (0 when empty / no memorio items).
        */
       size: {
         value: /* @__PURE__ */ __name(() => {
-          let totalSize = 0;
+          let totalBytes = 0;
           if (_hasStorage2) {
-            Object.keys(_sessionStorage).forEach(
-              (key) => {
-                if (key.startsWith(_getPrefix2())) {
-                  const item = _sessionStorage.getItem(key);
-                  if (item) totalSize += item.length;
-                }
+            for (let i = 0; i < _sessionStorage.length; i++) {
+              const key = _sessionStorage.key(i);
+              if (key && key.startsWith(_getPrefix2())) {
+                const item = _sessionStorage.getItem(key);
+                if (item) totalBytes += key.length + item.length;
               }
-            );
+            }
           } else {
-            _getFallbackStorage2().forEach((value) => {
-              totalSize += value.length;
+            _getFallbackStorage2().forEach((value, key) => {
+              totalBytes += key.length + value.length;
             });
           }
-          return totalSize;
+          return totalBytes === 0 ? 0 : Math.ceil(totalBytes / 1024);
         }, "value")
       },
       /**
@@ -2521,6 +2548,7 @@ var useObserver = /* @__PURE__ */ __name(((func, deps = []) => {
     };
   }
   const handlers = [];
+  const unsubs = [];
   const depList = Array.isArray(deps) && !deps.__path ? deps : [deps];
   try {
     depList.forEach((dep) => {
@@ -2534,8 +2562,11 @@ var useObserver = /* @__PURE__ */ __name(((func, deps = []) => {
       if (t) {
         t = t.replace(/^(\(\)\s*=>\s*)/, "").replace(/^globalThis\./, "").replace(/^state\./, "");
         const path2 = t.startsWith("store.") || t.startsWith("state.") ? t : "state." + t;
-        dispatch.listen(path2, () => func());
-        handlers.push(path2);
+        if (!handlers.includes(path2)) {
+          handlers.push(path2);
+          const off = dispatch.listen(path2, () => func());
+          if (typeof off === "function") unsubs.push({ path: path2, off });
+        }
       } else {
         internal_default.clearTrackedPaths();
         internal_default.tracking = true;
@@ -2547,8 +2578,9 @@ var useObserver = /* @__PURE__ */ __name(((func, deps = []) => {
         internal_default.trackedPaths.forEach((path2) => {
           if (!handlers.includes(path2)) {
             message_default(`useObserver: [Auto-Discovery] -> "${path2}"`);
-            dispatch.listen(path2, () => func());
             handlers.push(path2);
+            const off = dispatch.listen(path2, () => func());
+            if (typeof off === "function") unsubs.push({ path: path2, off });
           }
         });
       }
@@ -2559,11 +2591,9 @@ var useObserver = /* @__PURE__ */ __name(((func, deps = []) => {
       console.warn(`useObserver: No paths resolved for monitoring. Check your dependencies!`);
     }
     return () => {
-      handlers.forEach((path2) => {
-        if (typeof dispatch.remove === "function") {
-          dispatch.remove(path2);
-          message_default(`useObserver: Stopped monitoring "${path2}"`);
-        }
+      unsubs.forEach(({ path: path2, off }) => {
+        off();
+        message_default(`useObserver: Stopped monitoring "${path2}"`);
       });
     };
   } catch (err) {
@@ -3270,7 +3300,7 @@ init_internal();
 
 // package.json
 var package_default = {
-  version: "4.9.10"};
+  version: "4.9.30"};
 
 // core/global.ts
 init_env();

package/llms.txt

@@ -100,7 +100,7 @@ store.removeAll()
 store.clearAll()  // alias
 
 // Check size
-console.debug(store.size(), 'chars stored')
+console.debug(store.size(), 'kilobytes')
 
 // Check if persistent (real localStorage vs memory fallback)
 console.debug(store.isPersistent)  // true → real localStorage
@@ -134,7 +134,7 @@ session.removeAll()
 session.clearAll()  // alias
 
 // Check size
-console.debug(session.size(), 'chars stored')
+console.debug(session.size(), 'kilobytes')
 
 // Check if persistent
 console.debug(session.isPersistent)
@@ -466,15 +466,23 @@ MIT © Dario Passariello (BigLogic Inc Canada)
 
 Internal event system used by state changes; also usable directly for custom events.
 
+Listeners are stored as a *list* per event name, so multiple subscribers on the
+same name each keep firing. `dispatch.listen` returns an unsubscribe function
+for that specific subscriber — call it to remove only that one listener without
+affecting others registered under the same name.
+
 ```javascript
 // Dispatch a custom event
 memorio.dispatch.set('custom:event', { detail: { data: 'value' } })
 
-// Listen for an event
-memorio.dispatch.listen('custom:event', (e) => {
+// Listen for an event (returns an unsubscribe function)
+const off = memorio.dispatch.listen('custom:event', (e) => {
   console.debug('Event triggered:', e.detail)
 })
 
-// Remove listener
+// Remove only this listener via the returned unsubscribe
+off()
+
+// Remove *all* listeners for a name (imperative bulk removal)
 memorio.dispatch.remove('custom:event')
 ```