memorio 4.9.8 → 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
@@ -285,6 +350,18 @@ memorio.registerSchema('user', {
 state.user = { name: 'Sara' }   // rejected — missing required "email"
 ```
 
+Array item validation is supported per-element with the `items` schema field:
+
+```ts
+memorio.registerSchema('tags', {
+  type: 'array',
+  items: { type: 'string' },
+})
+
+state.tags = ['a', 'b']   // accepted
+state.tags = [1, 2, 3]    // rejected — items must be strings
+```
+
 ## Local-first sync
 
 The local application owns its data; the cloud is optional transport.
@@ -302,7 +379,9 @@ memorio.memory.configure({
 })
 ```
 
-Conflict resolution defaults to *higher confidence wins, then more recent `lastConfirmedAt`* — override it when you need a different rule:
+When `replay()` pulls remote operations, entries are ordered causally by HLC timestamp. For
+*concurrent* writes to the same key (an HLC tie) the **remote entry wins by default**; provide a
+`resolveConflict` to override:
 
 ```ts
 memorio.memory.configure({
@@ -313,7 +392,9 @@ memorio.memory.configure({
 })
 ```
 
-This resolver only settles *client-side* divergence between what memorio has seen locally — the provider is still responsible for the final server-side policy.
+When no resolver is supplied, Memorio logs a warn (dev only) and applies the remote entry on a
+tie. The resolver only settles *client-side* divergence between what memorio has seen locally —
+the provider is still responsible for the final server-side policy.
 
 ## Cross-platform support
 

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")
 };
 
@@ -1820,6 +1846,14 @@ var _validateValue = /* @__PURE__ */ __name((value, schema2, path) => {
       }
     }
   }
+  if (schema2.type === "array" && Array.isArray(value) && schema2.items) {
+    for (let i = 0; i < value.length; i++) {
+      const itemResult = _validateValue(value[i], schema2.items, `${path}[${i}]`);
+      if (!itemResult.valid) {
+        errors.push(...itemResult.errors || []);
+      }
+    }
+  }
   return errors.length === 0 ? { valid: true } : { valid: false, errors };
 }, "_validateValue");
 var validate = /* @__PURE__ */ __name((path, value) => {
@@ -1880,7 +1914,8 @@ var buildProxy = /* @__PURE__ */ __name((obj, callback, tree = []) => {
   const event = /* @__PURE__ */ __name((name) => {
     try {
       dispatch.set(name, { detail: { name } });
-    } catch (_) {
+    } catch (err) {
+      if (exports.DEV) console.warn("[memorio state] event dispatch failed:", err);
     }
     return;
   }, "event");
@@ -1899,7 +1934,7 @@ var buildProxy = /* @__PURE__ */ __name((obj, callback, tree = []) => {
         }
         if (prop === "list") {
           message_default('Some state could be hidden when you use "state.list". Use "state" to see the complete list ');
-          return JSON.parse(JSON.stringify(target));
+          return deepRaw(target, /* @__PURE__ */ new WeakSet());
         }
         if (typeof prop === "string") {
           const path = tree.length > 0 ? "state." + tree.concat(prop).join(".") : "state." + prop;
@@ -2035,7 +2070,8 @@ var buildProxy = /* @__PURE__ */ __name((obj, callback, tree = []) => {
                     message_default(`State '${key}' is now unlocked.`);
                   }, "value")
                 });
-              } catch (_) {
+              } catch (err) {
+                if (exports.DEV) console.warn("[memorio state] lock/unlock defineProperty failed:", err);
               }
             }
           }
@@ -2275,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")
       },
       /**
@@ -2514,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) => {
@@ -2527,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;
@@ -2540,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 });
           }
         });
       }
@@ -2552,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) {
@@ -3263,7 +3303,7 @@ init_internal();
 
 // package.json
 var package_default = {
-  version: "4.9.8"};
+  version: "4.9.30"};
 
 // core/global.ts
 init_env();
@@ -3282,20 +3322,20 @@ __name(typed, "typed");
 // functions/history/index.ts
 init_cjs_shims();
 init_internal();
+init_env();
 init_message();
 function _clone(value) {
   if (value === null || typeof value !== "object") return value;
-  const ctor = value.constructor?.name;
-  if (ctor !== "Object" && ctor !== "Array") return value;
   try {
-    return JSON.parse(JSON.stringify(value));
-  } catch {
+    return deepRaw(value, /* @__PURE__ */ new WeakSet());
+  } catch (err) {
+    if (exports.DEV) console.warn("[memorio history] deep clone failed:", err);
     return value;
   }
 }
 __name(_clone, "_clone");
 var snapshot = /* @__PURE__ */ __name(() => {
-  return _clone(deepRaw(exports.state));
+  return deepRaw(exports.state, /* @__PURE__ */ new WeakSet());
 }, "snapshot");
 var diff = /* @__PURE__ */ __name((snap) => {
   const changes = [];
@@ -3445,9 +3485,11 @@ var clearRedo = /* @__PURE__ */ __name(() => {
 init_cjs_shims();
 init_store();
 init_idb();
+init_env();
 
 // functions/memory/journal.ts
 init_cjs_shims();
+init_env();
 init_store();
 var g2 = globalThis;
 function namespace() {
@@ -3468,7 +3510,8 @@ function parseEntry(raw) {
   try {
     if (typeof raw === "string") return JSON.parse(raw);
     return raw;
-  } catch {
+  } catch (err) {
+    if (exports.DEV) console.warn("[memorio memory] failed to parse journal entry:", err);
     return null;
   }
 }
@@ -3552,10 +3595,12 @@ var journal = {
    * local operations, then optionally pulls newer remote operations and applies
    * them. No-op (empty ack) when no provider is configured.
    *
-   * When pulling remote entries, HLC timestamps are used to order operations
-   * causally. Concurrent writes to the same key are resolved via the provider's
-   * `resolveConflict` method (if provided), falling back to HLC timestamp
-   * comparison.
+    * When pulling remote entries, HLC timestamps are used to order operations
+    * causally. Concurrent writes to the same key (HLC tie) are resolved via the
+    * provider's `resolveConflict` method (if provided), otherwise the REMOTE
+    * entry wins by default (logged at warn level in dev). Provide a resolver on
+    * the sync provider to override this behaviour and prevent silent local data
+    * loss.
    */
   async replay() {
     const ack = { synced: [], resolved: [] };
@@ -3591,7 +3636,11 @@ var journal = {
             if (ha && hb) {
               const cmp = hlc.compare(ha, hb);
               if (cmp === 0) {
-                const resolution = typeof provider.resolveConflict === "function" ? await provider.resolveConflict(localEntry, e) : "remote";
+                const hasResolver = typeof provider.resolveConflict === "function";
+                const resolution = hasResolver ? await provider.resolveConflict(localEntry, e) : "remote";
+                if (!hasResolver && exports.DEV) {
+                  console.warn(`[memorio memory] replay() conflict for "${e.id}": no resolveConflict handler provided, defaulting to remote-wins`);
+                }
                 ack.resolved?.push({ id: e.id, resolution });
                 if (resolution === "local") continue;
               } else if (cmp > 0) {
@@ -3602,7 +3651,8 @@ var journal = {
           await this.append(e, e.operation || "confirm");
           await this.markSynced([e.id]);
         }
-      } catch (_) {
+      } catch (err) {
+        if (exports.DEV) console.warn("[memorio memory] sync pull failed:", err);
       }
     }
     return ack;
@@ -3641,7 +3691,8 @@ async function recordJournal(entry, operation) {
   if (entry.scope === "hot") return;
   try {
     await journal_default.append(entry, operation);
-  } catch (_) {
+  } catch (err) {
+    if (exports.DEV) console.warn("[memorio memory] journal append failed:", err);
   }
 }
 __name(recordJournal, "recordJournal");
@@ -3804,7 +3855,8 @@ async function loadFromScope(id, scope, isSuperseded = false) {
     const entry = JSON.parse(raw);
     entry.id = entry.id || id;
     return entry;
-  } catch {
+  } catch (err) {
+    if (exports.DEV) console.warn("[memorio memory] failed to parse memory entry:", err);
     return null;
   }
 }
@@ -3850,7 +3902,8 @@ async function getAllIndexes() {
     const raw = exports.store.get(MEMORY_INDEX_KEY);
     if (!raw) return {};
     return JSON.parse(raw);
-  } catch {
+  } catch (err) {
+    if (exports.DEV) console.warn("[memorio memory] failed to parse memory index:", err);
     return {};
   }
 }
@@ -4121,6 +4174,7 @@ var memory = {
 
 // functions/inspect/index.ts
 init_cjs_shims();
+init_env();
 var stateKeys = /* @__PURE__ */ __name(() => {
   const raw = deepRaw(exports.state);
   return Object.keys(raw).filter(
@@ -4187,11 +4241,10 @@ function _getValue(path) {
 __name(_getValue, "_getValue");
 function _clone2(value) {
   if (value === null || typeof value !== "object") return value;
-  const ctor = value.constructor?.name;
-  if (ctor !== "Object" && ctor !== "Array") return value;
   try {
-    return JSON.parse(JSON.stringify(value));
-  } catch {
+    return deepRaw(value, /* @__PURE__ */ new WeakSet());
+  } catch (err) {
+    if (exports.DEV) console.warn("[memorio inspect] deep clone failed:", err);
     return value;
   }
 }
@@ -4218,15 +4271,18 @@ if (!("memorio" in globalThis)) {
       enumerable: false
     }
   );
-  Object.defineProperty(
-    globalThis,
-    "events",
-    {
-      value: {},
-      writable: true,
-      enumerable: false
-    }
-  );
+  if (!("events" in globalThis)) {
+    Object.defineProperty(
+      globalThis,
+      "events",
+      {
+        value: {},
+        writable: true,
+        enumerable: false,
+        configurable: true
+      }
+    );
+  }
   if (typeof globalThis.addEventListener === "function") {
     dispatch.listen("memorio:memory:cleanup", async () => memory.forgetExpired?.());
   }