mvc-kit 2.5.3 → 2.5.4

package/dist/PersistentCollection.cjs

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const Collection = require("./Collection.cjs");
+const __DEV__ = typeof __MVC_KIT_DEV__ !== "undefined" && __MVC_KIT_DEV__;
+const _registeredKeys = __DEV__ ? /* @__PURE__ */ new Map() : null;
+class PersistentCollection extends Collection.Collection {
+  /** Debounce delay in ms for storage writes. 0 = immediate. */
+  static WRITE_DELAY = 100;
+  // ── Serialization hooks ──
+  /** Serialize items to a string. Used by string-based adapters (WebStorage, NativeCollection). */
+  serialize(items) {
+    return JSON.stringify(items);
+  }
+  /** Deserialize a string back to items. Used by string-based adapters. */
+  deserialize(raw) {
+    return JSON.parse(raw);
+  }
+  // ── Internal state ──
+  _hydrated = false;
+  _hydrating = false;
+  _persistenceReady = false;
+  _preHydrationWarned = false;
+  _pendingWrites = /* @__PURE__ */ new Map();
+  _pendingRemoves = /* @__PURE__ */ new Set();
+  _pendingClear = false;
+  _flushTimer = null;
+  constructor(initialItems = []) {
+    super(initialItems);
+    const unsub = this.subscribe((current, prev) => {
+      if (this._hydrating) return;
+      this._ensurePersistenceReady();
+      this._diffAndQueue(current, prev);
+      this._scheduleSave();
+    });
+    this.addCleanup(unsub);
+  }
+  /**
+   * DEV check for duplicate storageKey. Called lazily since storageKey is an abstract
+   * field that isn't available during the parent constructor chain.
+   */
+  _ensurePersistenceReady() {
+    if (this._persistenceReady) return;
+    this._persistenceReady = true;
+    if (__DEV__ && _registeredKeys) {
+      const className = this.constructor.name;
+      const existing = _registeredKeys.get(this.storageKey);
+      if (existing && existing !== className) {
+        console.warn(
+          `[mvc-kit] Duplicate storageKey "${this.storageKey}" used by "${className}" and "${existing}". Each PersistentCollection should have a unique storageKey.`
+        );
+      }
+      _registeredKeys.set(this.storageKey, className);
+    }
+  }
+  // ── Public API ──
+  /** Whether storage data has been loaded. */
+  get hydrated() {
+    return this._hydrated;
+  }
+  /**
+   * Load data from storage into the collection. Idempotent — subsequent calls return current items.
+   * Returns the items after hydration.
+   */
+  async hydrate() {
+    if (this._hydrated) return this.items;
+    this._ensurePersistenceReady();
+    this._hydrating = true;
+    try {
+      const stored = await this.persistGetAll();
+      if (stored.length > 0) {
+        super.reset(stored);
+      }
+      this._hydrated = true;
+      return this.items;
+    } catch (err) {
+      this._handlePersistError(err);
+      this._hydrated = true;
+      return this.items;
+    } finally {
+      this._hydrating = false;
+    }
+  }
+  /**
+   * Synchronous hydration for sync adapters (e.g., WebStorage).
+   * Call from the **leaf class** constructor (after field initializers have run).
+   */
+  _hydrateSync() {
+    if (this._hydrated) return;
+    this._ensurePersistenceReady();
+    this._hydrating = true;
+    try {
+      const stored = this.persistGetAll();
+      if (stored instanceof Promise) {
+        throw new Error("[mvc-kit] _hydrateSync called with async persistGetAll");
+      }
+      if (stored.length > 0) {
+        super.reset(stored);
+      }
+      this._hydrated = true;
+    } catch (err) {
+      this._handlePersistError(err);
+      this._hydrated = true;
+    } finally {
+      this._hydrating = false;
+    }
+  }
+  /**
+   * Clear all data from storage AND from the in-memory collection.
+   */
+  clearStorage() {
+    this._ensurePersistenceReady();
+    this._pendingWrites.clear();
+    this._pendingRemoves.clear();
+    this._pendingClear = false;
+    this._cancelSave();
+    if (this.length > 0) {
+      super.clear();
+    }
+    try {
+      const result = this.persistClear();
+      if (result instanceof Promise) {
+        return result.catch((err) => this._handlePersistError(err));
+      }
+    } catch (err) {
+      this._handlePersistError(err);
+    }
+  }
+  // ── Overrides for clear/reset tracking ──
+  reset(items) {
+    this._pendingClear = true;
+    this._pendingWrites.clear();
+    this._pendingRemoves.clear();
+    for (const item of items) {
+      this._pendingWrites.set(item.id, item);
+    }
+    this._hydrating = true;
+    try {
+      super.reset(items);
+    } finally {
+      this._hydrating = false;
+    }
+    this._scheduleSave();
+  }
+  clear() {
+    this._pendingClear = true;
+    this._pendingWrites.clear();
+    this._pendingRemoves.clear();
+    this._hydrating = true;
+    try {
+      super.clear();
+    } finally {
+      this._hydrating = false;
+    }
+    this._scheduleSave();
+  }
+  // ── Override items getter for DEV pre-hydration warning ──
+  get items() {
+    if (__DEV__ && !this._hydrated && !this._hydrating && !this._preHydrationWarned) {
+      this._preHydrationWarned = true;
+      console.warn(
+        `[mvc-kit] Accessing items on "${this.constructor.name}" before hydrate() has been called. Data may be incomplete. Call hydrate() first.`
+      );
+    }
+    return super.items;
+  }
+  get state() {
+    return this.items;
+  }
+  // ── Dispose ──
+  dispose() {
+    if (this.disposed) return;
+    this._cancelSave();
+    if (this._hasPending()) {
+      try {
+        const result = this._flush();
+        if (result instanceof Promise) {
+          result.catch((err) => this._handlePersistError(err));
+        }
+      } catch (err) {
+        this._handlePersistError(err);
+      }
+    }
+    if (__DEV__ && _registeredKeys && this._persistenceReady) {
+      _registeredKeys.delete(this.storageKey);
+    }
+    super.dispose();
+  }
+  // ── Private: delta tracking ──
+  _diffAndQueue(current, prev) {
+    const prevMap = /* @__PURE__ */ new Map();
+    for (const item of prev) {
+      prevMap.set(item.id, item);
+    }
+    const currentMap = /* @__PURE__ */ new Map();
+    for (const item of current) {
+      currentMap.set(item.id, item);
+    }
+    for (const item of current) {
+      const prevItem = prevMap.get(item.id);
+      if (!prevItem || prevItem !== item) {
+        this._pendingWrites.set(item.id, item);
+        this._pendingRemoves.delete(item.id);
+      }
+    }
+    for (const item of prev) {
+      if (!currentMap.has(item.id)) {
+        this._pendingRemoves.add(item.id);
+        this._pendingWrites.delete(item.id);
+      }
+    }
+  }
+  _hasPending() {
+    return this._pendingClear || this._pendingWrites.size > 0 || this._pendingRemoves.size > 0;
+  }
+  // ── Private: debounce + flush ──
+  _scheduleSave() {
+    this._cancelSave();
+    const delay = this.constructor.WRITE_DELAY;
+    if (delay <= 0) {
+      this._doFlush();
+      return;
+    }
+    this._flushTimer = setTimeout(() => this._doFlush(), delay);
+  }
+  _cancelSave() {
+    if (this._flushTimer !== null) {
+      clearTimeout(this._flushTimer);
+      this._flushTimer = null;
+    }
+  }
+  _doFlush() {
+    if (!this._hasPending()) return;
+    try {
+      const result = this._flush();
+      if (result instanceof Promise) {
+        result.catch((err) => this._handlePersistError(err));
+      }
+    } catch (err) {
+      this._handlePersistError(err);
+    }
+  }
+  _flush() {
+    const doClear = this._pendingClear;
+    const writes = this._pendingWrites.size > 0 ? [...this._pendingWrites.values()] : null;
+    const removes = this._pendingRemoves.size > 0 ? [...this._pendingRemoves] : null;
+    this._pendingClear = false;
+    this._pendingWrites.clear();
+    this._pendingRemoves.clear();
+    if (doClear) {
+      const clearResult = this.persistClear();
+      if (clearResult instanceof Promise) {
+        return clearResult.then(() => {
+          if (writes) return this.persistSet(writes);
+        });
+      }
+      if (writes) {
+        return this.persistSet(writes);
+      }
+      return;
+    }
+    if (removes) {
+      const removeResult = this.persistRemove(removes);
+      if (removeResult instanceof Promise) {
+        return removeResult.then(() => {
+          if (writes) return this.persistSet(writes);
+        });
+      }
+    }
+    if (writes) {
+      return this.persistSet(writes);
+    }
+  }
+  // ── Private: error handling ──
+  _handlePersistError(err) {
+    if (this.onPersistError) {
+      this.onPersistError(err);
+      return;
+    }
+    if (__DEV__) {
+      console.warn("[mvc-kit] Storage error:", err);
+    }
+  }
+}
+exports.PersistentCollection = PersistentCollection;
+//# sourceMappingURL=PersistentCollection.cjs.map

package/dist/PersistentCollection.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersistentCollection.cjs","sources":["../src/PersistentCollection.ts"],"sourcesContent":["import { Collection } from './Collection';\n\nconst __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;\n\n// Track storageKey uniqueness in DEV\nconst _registeredKeys: Map<string, string> | null = __DEV__ ? new Map() : null;\n\n/**\n * Abstract base for Collections that persist to external storage.\n * Tracks deltas per mutation and flushes via debounced writes.\n * Subclasses implement the storage-specific `persist*` methods.\n */\nexport abstract class PersistentCollection<\n  T extends { id: string | number },\n> extends Collection<T> {\n  /** Debounce delay in ms for storage writes. 0 = immediate. */\n  static WRITE_DELAY = 100;\n\n  /** Unique key identifying this collection in storage. */\n  protected abstract readonly storageKey: string;\n\n  // ── Abstract persistence methods ──\n\n  protected abstract persistGet(id: T['id']): T | null | Promise<T | null>;\n  protected abstract persistGetAll(): T[] | Promise<T[]>;\n  /** Upsert semantics — insert or replace the given items. */\n  protected abstract persistSet(items: T[]): void | Promise<void>;\n  protected abstract persistRemove(ids: T['id'][]): void | Promise<void>;\n  protected abstract persistClear(): void | Promise<void>;\n\n  // ── Serialization hooks ──\n\n  /** Serialize items to a string. Used by string-based adapters (WebStorage, NativeCollection). */\n  protected serialize(items: T[]): string {\n    return JSON.stringify(items);\n  }\n\n  /** Deserialize a string back to items. Used by string-based adapters. */\n  protected deserialize(raw: string): T[] {\n    return JSON.parse(raw);\n  }\n\n  // ── Error hook ──\n\n  /** Called when a storage operation fails. Override for custom error handling. */\n  protected onPersistError?(error: unknown): void;\n\n  // ── Internal state ──\n\n  private _hydrated = false;\n  private _hydrating = false;\n  private _persistenceReady = false;\n  private _preHydrationWarned = false;\n  private _pendingWrites = new Map<T['id'], T>();\n  private _pendingRemoves = new Set<T['id']>();\n  private _pendingClear = false;\n  private _flushTimer: ReturnType<typeof setTimeout> | null = null;\n\n  constructor(initialItems: T[] = []) {\n    super(initialItems);\n\n    // Self-subscribe to detect mutations via diff.\n    // storageKey may not be available yet (class field initializers run after super()),\n    // but that's fine — the subscriber only fires on mutations, not during construction.\n    const unsub = this.subscribe((current, prev) => {\n      if (this._hydrating) return;\n      this._ensurePersistenceReady();\n      this._diffAndQueue(current, prev);\n      this._scheduleSave();\n    });\n    this.addCleanup(unsub);\n  }\n\n  /**\n   * DEV check for duplicate storageKey. Called lazily since storageKey is an abstract\n   * field that isn't available during the parent constructor chain.\n   */\n  private _ensurePersistenceReady(): void {\n    if (this._persistenceReady) return;\n    this._persistenceReady = true;\n\n    if (__DEV__ && _registeredKeys) {\n      const className = this.constructor.name;\n      const existing = _registeredKeys.get(this.storageKey);\n      if (existing && existing !== className) {\n        console.warn(\n          `[mvc-kit] Duplicate storageKey \"${this.storageKey}\" used by \"${className}\" ` +\n            `and \"${existing}\". Each PersistentCollection should have a unique storageKey.`,\n        );\n      }\n      _registeredKeys.set(this.storageKey, className);\n    }\n  }\n\n  // ── Public API ──\n\n  /** Whether storage data has been loaded. */\n  get hydrated(): boolean {\n    return this._hydrated;\n  }\n\n  /**\n   * Load data from storage into the collection. Idempotent — subsequent calls return current items.\n   * Returns the items after hydration.\n   */\n  async hydrate(): Promise<T[]> {\n    if (this._hydrated) return this.items;\n    this._ensurePersistenceReady();\n\n    this._hydrating = true;\n    try {\n      const stored = await this.persistGetAll();\n      if (stored.length > 0) {\n        super.reset(stored);\n      }\n      this._hydrated = true;\n      return this.items;\n    } catch (err) {\n      this._handlePersistError(err);\n      this._hydrated = true;\n      return this.items;\n    } finally {\n      this._hydrating = false;\n    }\n  }\n\n  /**\n   * Synchronous hydration for sync adapters (e.g., WebStorage).\n   * Call from the **leaf class** constructor (after field initializers have run).\n   */\n  protected _hydrateSync(): void {\n    if (this._hydrated) return;\n    this._ensurePersistenceReady();\n\n    this._hydrating = true;\n    try {\n      const stored = this.persistGetAll();\n      if (stored instanceof Promise) {\n        throw new Error('[mvc-kit] _hydrateSync called with async persistGetAll');\n      }\n      if (stored.length > 0) {\n        super.reset(stored);\n      }\n      this._hydrated = true;\n    } catch (err) {\n      this._handlePersistError(err);\n      this._hydrated = true;\n    } finally {\n      this._hydrating = false;\n    }\n  }\n\n  /**\n   * Clear all data from storage AND from the in-memory collection.\n   */\n  clearStorage(): void | Promise<void> {\n    this._ensurePersistenceReady();\n\n    // Clear pending queues — we're wiping everything\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    this._pendingClear = false;\n    this._cancelSave();\n\n    // Clear in-memory\n    if (this.length > 0) {\n      super.clear();\n    }\n\n    try {\n      const result = this.persistClear();\n      if (result instanceof Promise) {\n        return result.catch((err) => this._handlePersistError(err));\n      }\n    } catch (err) {\n      this._handlePersistError(err);\n    }\n  }\n\n  // ── Overrides for clear/reset tracking ──\n\n  reset(items: T[]): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    for (const item of items) {\n      this._pendingWrites.set(item.id, item);\n    }\n    this._hydrating = true; // Re-use flag to skip subscriber\n    try {\n      super.reset(items);\n    } finally {\n      this._hydrating = false;\n    }\n    this._scheduleSave();\n  }\n\n  clear(): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    this._hydrating = true;\n    try {\n      super.clear();\n    } finally {\n      this._hydrating = false;\n    }\n    this._scheduleSave();\n  }\n\n  // ── Override items getter for DEV pre-hydration warning ──\n\n  get items(): T[] {\n    if (__DEV__ && !this._hydrated && !this._hydrating && !this._preHydrationWarned) {\n      this._preHydrationWarned = true;\n      console.warn(\n        `[mvc-kit] Accessing items on \"${this.constructor.name}\" before hydrate() has been called. ` +\n          `Data may be incomplete. Call hydrate() first.`,\n      );\n    }\n    return super.items;\n  }\n\n  get state(): T[] {\n    return this.items;\n  }\n\n  // ── Dispose ──\n\n  dispose(): void {\n    if (this.disposed) return;\n\n    // Flush any pending saves before disposing\n    this._cancelSave();\n    if (this._hasPending()) {\n      try {\n        const result = this._flush();\n        if (result instanceof Promise) {\n          result.catch((err) => this._handlePersistError(err));\n        }\n      } catch (err) {\n        this._handlePersistError(err);\n      }\n    }\n\n    // DEV: unregister storageKey\n    if (__DEV__ && _registeredKeys && this._persistenceReady) {\n      _registeredKeys.delete(this.storageKey);\n    }\n\n    super.dispose();\n  }\n\n  // ── Private: delta tracking ──\n\n  private _diffAndQueue(current: readonly T[], prev: readonly T[]): void {\n    const prevMap = new Map<T['id'], T>();\n    for (const item of prev) {\n      prevMap.set(item.id, item);\n    }\n\n    const currentMap = new Map<T['id'], T>();\n    for (const item of current) {\n      currentMap.set(item.id, item);\n    }\n\n    // Added or updated: in current but not in prev, or different reference\n    for (const item of current) {\n      const prevItem = prevMap.get(item.id);\n      if (!prevItem || prevItem !== item) {\n        this._pendingWrites.set(item.id, item);\n        this._pendingRemoves.delete(item.id);\n      }\n    }\n\n    // Removed: in prev but not in current\n    for (const item of prev) {\n      if (!currentMap.has(item.id)) {\n        this._pendingRemoves.add(item.id);\n        this._pendingWrites.delete(item.id);\n      }\n    }\n  }\n\n  private _hasPending(): boolean {\n    return this._pendingClear || this._pendingWrites.size > 0 || this._pendingRemoves.size > 0;\n  }\n\n  // ── Private: debounce + flush ──\n\n  private _scheduleSave(): void {\n    this._cancelSave();\n    const delay = (this.constructor as typeof PersistentCollection).WRITE_DELAY;\n    if (delay <= 0) {\n      this._doFlush();\n      return;\n    }\n    this._flushTimer = setTimeout(() => this._doFlush(), delay);\n  }\n\n  private _cancelSave(): void {\n    if (this._flushTimer !== null) {\n      clearTimeout(this._flushTimer);\n      this._flushTimer = null;\n    }\n  }\n\n  private _doFlush(): void {\n    if (!this._hasPending()) return;\n    try {\n      const result = this._flush();\n      if (result instanceof Promise) {\n        result.catch((err) => this._handlePersistError(err));\n      }\n    } catch (err) {\n      this._handlePersistError(err);\n    }\n  }\n\n  private _flush(): void | Promise<void> {\n    const doClear = this._pendingClear;\n    const writes = this._pendingWrites.size > 0 ? [...this._pendingWrites.values()] : null;\n    const removes = this._pendingRemoves.size > 0 ? [...this._pendingRemoves] : null;\n\n    // Clear queues\n    this._pendingClear = false;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n\n    if (doClear) {\n      const clearResult = this.persistClear();\n      if (clearResult instanceof Promise) {\n        return clearResult.then(() => {\n          if (writes) return this.persistSet(writes);\n        });\n      }\n      if (writes) {\n        return this.persistSet(writes);\n      }\n      return;\n    }\n\n    // Non-clear: removes then writes\n    if (removes) {\n      const removeResult = this.persistRemove(removes);\n      if (removeResult instanceof Promise) {\n        return removeResult.then(() => {\n          if (writes) return this.persistSet(writes);\n        });\n      }\n    }\n    if (writes) {\n      return this.persistSet(writes);\n    }\n  }\n\n  // ── Private: error handling ──\n\n  private _handlePersistError(err: unknown): void {\n    if (this.onPersistError) {\n      this.onPersistError(err);\n      return;\n    }\n    if (__DEV__) {\n      console.warn('[mvc-kit] Storage error:', err);\n    }\n  }\n}\n"],"names":["Collection"],"mappings":"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"}

package/dist/PersistentCollection.js

@@ -0,0 +1,285 @@
+import { Collection } from "./Collection.js";
+const __DEV__ = typeof __MVC_KIT_DEV__ !== "undefined" && __MVC_KIT_DEV__;
+const _registeredKeys = __DEV__ ? /* @__PURE__ */ new Map() : null;
+class PersistentCollection extends Collection {
+  /** Debounce delay in ms for storage writes. 0 = immediate. */
+  static WRITE_DELAY = 100;
+  // ── Serialization hooks ──
+  /** Serialize items to a string. Used by string-based adapters (WebStorage, NativeCollection). */
+  serialize(items) {
+    return JSON.stringify(items);
+  }
+  /** Deserialize a string back to items. Used by string-based adapters. */
+  deserialize(raw) {
+    return JSON.parse(raw);
+  }
+  // ── Internal state ──
+  _hydrated = false;
+  _hydrating = false;
+  _persistenceReady = false;
+  _preHydrationWarned = false;
+  _pendingWrites = /* @__PURE__ */ new Map();
+  _pendingRemoves = /* @__PURE__ */ new Set();
+  _pendingClear = false;
+  _flushTimer = null;
+  constructor(initialItems = []) {
+    super(initialItems);
+    const unsub = this.subscribe((current, prev) => {
+      if (this._hydrating) return;
+      this._ensurePersistenceReady();
+      this._diffAndQueue(current, prev);
+      this._scheduleSave();
+    });
+    this.addCleanup(unsub);
+  }
+  /**
+   * DEV check for duplicate storageKey. Called lazily since storageKey is an abstract
+   * field that isn't available during the parent constructor chain.
+   */
+  _ensurePersistenceReady() {
+    if (this._persistenceReady) return;
+    this._persistenceReady = true;
+    if (__DEV__ && _registeredKeys) {
+      const className = this.constructor.name;
+      const existing = _registeredKeys.get(this.storageKey);
+      if (existing && existing !== className) {
+        console.warn(
+          `[mvc-kit] Duplicate storageKey "${this.storageKey}" used by "${className}" and "${existing}". Each PersistentCollection should have a unique storageKey.`
+        );
+      }
+      _registeredKeys.set(this.storageKey, className);
+    }
+  }
+  // ── Public API ──
+  /** Whether storage data has been loaded. */
+  get hydrated() {
+    return this._hydrated;
+  }
+  /**
+   * Load data from storage into the collection. Idempotent — subsequent calls return current items.
+   * Returns the items after hydration.
+   */
+  async hydrate() {
+    if (this._hydrated) return this.items;
+    this._ensurePersistenceReady();
+    this._hydrating = true;
+    try {
+      const stored = await this.persistGetAll();
+      if (stored.length > 0) {
+        super.reset(stored);
+      }
+      this._hydrated = true;
+      return this.items;
+    } catch (err) {
+      this._handlePersistError(err);
+      this._hydrated = true;
+      return this.items;
+    } finally {
+      this._hydrating = false;
+    }
+  }
+  /**
+   * Synchronous hydration for sync adapters (e.g., WebStorage).
+   * Call from the **leaf class** constructor (after field initializers have run).
+   */
+  _hydrateSync() {
+    if (this._hydrated) return;
+    this._ensurePersistenceReady();
+    this._hydrating = true;
+    try {
+      const stored = this.persistGetAll();
+      if (stored instanceof Promise) {
+        throw new Error("[mvc-kit] _hydrateSync called with async persistGetAll");
+      }
+      if (stored.length > 0) {
+        super.reset(stored);
+      }
+      this._hydrated = true;
+    } catch (err) {
+      this._handlePersistError(err);
+      this._hydrated = true;
+    } finally {
+      this._hydrating = false;
+    }
+  }
+  /**
+   * Clear all data from storage AND from the in-memory collection.
+   */
+  clearStorage() {
+    this._ensurePersistenceReady();
+    this._pendingWrites.clear();
+    this._pendingRemoves.clear();
+    this._pendingClear = false;
+    this._cancelSave();
+    if (this.length > 0) {
+      super.clear();
+    }
+    try {
+      const result = this.persistClear();
+      if (result instanceof Promise) {
+        return result.catch((err) => this._handlePersistError(err));
+      }
+    } catch (err) {
+      this._handlePersistError(err);
+    }
+  }
+  // ── Overrides for clear/reset tracking ──
+  reset(items) {
+    this._pendingClear = true;
+    this._pendingWrites.clear();
+    this._pendingRemoves.clear();
+    for (const item of items) {
+      this._pendingWrites.set(item.id, item);
+    }
+    this._hydrating = true;
+    try {
+      super.reset(items);
+    } finally {
+      this._hydrating = false;
+    }
+    this._scheduleSave();
+  }
+  clear() {
+    this._pendingClear = true;
+    this._pendingWrites.clear();
+    this._pendingRemoves.clear();
+    this._hydrating = true;
+    try {
+      super.clear();
+    } finally {
+      this._hydrating = false;
+    }
+    this._scheduleSave();
+  }
+  // ── Override items getter for DEV pre-hydration warning ──
+  get items() {
+    if (__DEV__ && !this._hydrated && !this._hydrating && !this._preHydrationWarned) {
+      this._preHydrationWarned = true;
+      console.warn(
+        `[mvc-kit] Accessing items on "${this.constructor.name}" before hydrate() has been called. Data may be incomplete. Call hydrate() first.`
+      );
+    }
+    return super.items;
+  }
+  get state() {
+    return this.items;
+  }
+  // ── Dispose ──
+  dispose() {
+    if (this.disposed) return;
+    this._cancelSave();
+    if (this._hasPending()) {
+      try {
+        const result = this._flush();
+        if (result instanceof Promise) {
+          result.catch((err) => this._handlePersistError(err));
+        }
+      } catch (err) {
+        this._handlePersistError(err);
+      }
+    }
+    if (__DEV__ && _registeredKeys && this._persistenceReady) {
+      _registeredKeys.delete(this.storageKey);
+    }
+    super.dispose();
+  }
+  // ── Private: delta tracking ──
+  _diffAndQueue(current, prev) {
+    const prevMap = /* @__PURE__ */ new Map();
+    for (const item of prev) {
+      prevMap.set(item.id, item);
+    }
+    const currentMap = /* @__PURE__ */ new Map();
+    for (const item of current) {
+      currentMap.set(item.id, item);
+    }
+    for (const item of current) {
+      const prevItem = prevMap.get(item.id);
+      if (!prevItem || prevItem !== item) {
+        this._pendingWrites.set(item.id, item);
+        this._pendingRemoves.delete(item.id);
+      }
+    }
+    for (const item of prev) {
+      if (!currentMap.has(item.id)) {
+        this._pendingRemoves.add(item.id);
+        this._pendingWrites.delete(item.id);
+      }
+    }
+  }
+  _hasPending() {
+    return this._pendingClear || this._pendingWrites.size > 0 || this._pendingRemoves.size > 0;
+  }
+  // ── Private: debounce + flush ──
+  _scheduleSave() {
+    this._cancelSave();
+    const delay = this.constructor.WRITE_DELAY;
+    if (delay <= 0) {
+      this._doFlush();
+      return;
+    }
+    this._flushTimer = setTimeout(() => this._doFlush(), delay);
+  }
+  _cancelSave() {
+    if (this._flushTimer !== null) {
+      clearTimeout(this._flushTimer);
+      this._flushTimer = null;
+    }
+  }
+  _doFlush() {
+    if (!this._hasPending()) return;
+    try {
+      const result = this._flush();
+      if (result instanceof Promise) {
+        result.catch((err) => this._handlePersistError(err));
+      }
+    } catch (err) {
+      this._handlePersistError(err);
+    }
+  }
+  _flush() {
+    const doClear = this._pendingClear;
+    const writes = this._pendingWrites.size > 0 ? [...this._pendingWrites.values()] : null;
+    const removes = this._pendingRemoves.size > 0 ? [...this._pendingRemoves] : null;
+    this._pendingClear = false;
+    this._pendingWrites.clear();
+    this._pendingRemoves.clear();
+    if (doClear) {
+      const clearResult = this.persistClear();
+      if (clearResult instanceof Promise) {
+        return clearResult.then(() => {
+          if (writes) return this.persistSet(writes);
+        });
+      }
+      if (writes) {
+        return this.persistSet(writes);
+      }
+      return;
+    }
+    if (removes) {
+      const removeResult = this.persistRemove(removes);
+      if (removeResult instanceof Promise) {
+        return removeResult.then(() => {
+          if (writes) return this.persistSet(writes);
+        });
+      }
+    }
+    if (writes) {
+      return this.persistSet(writes);
+    }
+  }
+  // ── Private: error handling ──
+  _handlePersistError(err) {
+    if (this.onPersistError) {
+      this.onPersistError(err);
+      return;
+    }
+    if (__DEV__) {
+      console.warn("[mvc-kit] Storage error:", err);
+    }
+  }
+}
+export {
+  PersistentCollection
+};
+//# sourceMappingURL=PersistentCollection.js.map

package/dist/PersistentCollection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersistentCollection.js","sources":["../src/PersistentCollection.ts"],"sourcesContent":["import { Collection } from './Collection';\n\nconst __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;\n\n// Track storageKey uniqueness in DEV\nconst _registeredKeys: Map<string, string> | null = __DEV__ ? new Map() : null;\n\n/**\n * Abstract base for Collections that persist to external storage.\n * Tracks deltas per mutation and flushes via debounced writes.\n * Subclasses implement the storage-specific `persist*` methods.\n */\nexport abstract class PersistentCollection<\n  T extends { id: string | number },\n> extends Collection<T> {\n  /** Debounce delay in ms for storage writes. 0 = immediate. */\n  static WRITE_DELAY = 100;\n\n  /** Unique key identifying this collection in storage. */\n  protected abstract readonly storageKey: string;\n\n  // ── Abstract persistence methods ──\n\n  protected abstract persistGet(id: T['id']): T | null | Promise<T | null>;\n  protected abstract persistGetAll(): T[] | Promise<T[]>;\n  /** Upsert semantics — insert or replace the given items. */\n  protected abstract persistSet(items: T[]): void | Promise<void>;\n  protected abstract persistRemove(ids: T['id'][]): void | Promise<void>;\n  protected abstract persistClear(): void | Promise<void>;\n\n  // ── Serialization hooks ──\n\n  /** Serialize items to a string. Used by string-based adapters (WebStorage, NativeCollection). */\n  protected serialize(items: T[]): string {\n    return JSON.stringify(items);\n  }\n\n  /** Deserialize a string back to items. Used by string-based adapters. */\n  protected deserialize(raw: string): T[] {\n    return JSON.parse(raw);\n  }\n\n  // ── Error hook ──\n\n  /** Called when a storage operation fails. Override for custom error handling. */\n  protected onPersistError?(error: unknown): void;\n\n  // ── Internal state ──\n\n  private _hydrated = false;\n  private _hydrating = false;\n  private _persistenceReady = false;\n  private _preHydrationWarned = false;\n  private _pendingWrites = new Map<T['id'], T>();\n  private _pendingRemoves = new Set<T['id']>();\n  private _pendingClear = false;\n  private _flushTimer: ReturnType<typeof setTimeout> | null = null;\n\n  constructor(initialItems: T[] = []) {\n    super(initialItems);\n\n    // Self-subscribe to detect mutations via diff.\n    // storageKey may not be available yet (class field initializers run after super()),\n    // but that's fine — the subscriber only fires on mutations, not during construction.\n    const unsub = this.subscribe((current, prev) => {\n      if (this._hydrating) return;\n      this._ensurePersistenceReady();\n      this._diffAndQueue(current, prev);\n      this._scheduleSave();\n    });\n    this.addCleanup(unsub);\n  }\n\n  /**\n   * DEV check for duplicate storageKey. Called lazily since storageKey is an abstract\n   * field that isn't available during the parent constructor chain.\n   */\n  private _ensurePersistenceReady(): void {\n    if (this._persistenceReady) return;\n    this._persistenceReady = true;\n\n    if (__DEV__ && _registeredKeys) {\n      const className = this.constructor.name;\n      const existing = _registeredKeys.get(this.storageKey);\n      if (existing && existing !== className) {\n        console.warn(\n          `[mvc-kit] Duplicate storageKey \"${this.storageKey}\" used by \"${className}\" ` +\n            `and \"${existing}\". Each PersistentCollection should have a unique storageKey.`,\n        );\n      }\n      _registeredKeys.set(this.storageKey, className);\n    }\n  }\n\n  // ── Public API ──\n\n  /** Whether storage data has been loaded. */\n  get hydrated(): boolean {\n    return this._hydrated;\n  }\n\n  /**\n   * Load data from storage into the collection. Idempotent — subsequent calls return current items.\n   * Returns the items after hydration.\n   */\n  async hydrate(): Promise<T[]> {\n    if (this._hydrated) return this.items;\n    this._ensurePersistenceReady();\n\n    this._hydrating = true;\n    try {\n      const stored = await this.persistGetAll();\n      if (stored.length > 0) {\n        super.reset(stored);\n      }\n      this._hydrated = true;\n      return this.items;\n    } catch (err) {\n      this._handlePersistError(err);\n      this._hydrated = true;\n      return this.items;\n    } finally {\n      this._hydrating = false;\n    }\n  }\n\n  /**\n   * Synchronous hydration for sync adapters (e.g., WebStorage).\n   * Call from the **leaf class** constructor (after field initializers have run).\n   */\n  protected _hydrateSync(): void {\n    if (this._hydrated) return;\n    this._ensurePersistenceReady();\n\n    this._hydrating = true;\n    try {\n      const stored = this.persistGetAll();\n      if (stored instanceof Promise) {\n        throw new Error('[mvc-kit] _hydrateSync called with async persistGetAll');\n      }\n      if (stored.length > 0) {\n        super.reset(stored);\n      }\n      this._hydrated = true;\n    } catch (err) {\n      this._handlePersistError(err);\n      this._hydrated = true;\n    } finally {\n      this._hydrating = false;\n    }\n  }\n\n  /**\n   * Clear all data from storage AND from the in-memory collection.\n   */\n  clearStorage(): void | Promise<void> {\n    this._ensurePersistenceReady();\n\n    // Clear pending queues — we're wiping everything\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    this._pendingClear = false;\n    this._cancelSave();\n\n    // Clear in-memory\n    if (this.length > 0) {\n      super.clear();\n    }\n\n    try {\n      const result = this.persistClear();\n      if (result instanceof Promise) {\n        return result.catch((err) => this._handlePersistError(err));\n      }\n    } catch (err) {\n      this._handlePersistError(err);\n    }\n  }\n\n  // ── Overrides for clear/reset tracking ──\n\n  reset(items: T[]): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    for (const item of items) {\n      this._pendingWrites.set(item.id, item);\n    }\n    this._hydrating = true; // Re-use flag to skip subscriber\n    try {\n      super.reset(items);\n    } finally {\n      this._hydrating = false;\n    }\n    this._scheduleSave();\n  }\n\n  clear(): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    this._hydrating = true;\n    try {\n      super.clear();\n    } finally {\n      this._hydrating = false;\n    }\n    this._scheduleSave();\n  }\n\n  // ── Override items getter for DEV pre-hydration warning ──\n\n  get items(): T[] {\n    if (__DEV__ && !this._hydrated && !this._hydrating && !this._preHydrationWarned) {\n      this._preHydrationWarned = true;\n      console.warn(\n        `[mvc-kit] Accessing items on \"${this.constructor.name}\" before hydrate() has been called. ` +\n          `Data may be incomplete. Call hydrate() first.`,\n      );\n    }\n    return super.items;\n  }\n\n  get state(): T[] {\n    return this.items;\n  }\n\n  // ── Dispose ──\n\n  dispose(): void {\n    if (this.disposed) return;\n\n    // Flush any pending saves before disposing\n    this._cancelSave();\n    if (this._hasPending()) {\n      try {\n        const result = this._flush();\n        if (result instanceof Promise) {\n          result.catch((err) => this._handlePersistError(err));\n        }\n      } catch (err) {\n        this._handlePersistError(err);\n      }\n    }\n\n    // DEV: unregister storageKey\n    if (__DEV__ && _registeredKeys && this._persistenceReady) {\n      _registeredKeys.delete(this.storageKey);\n    }\n\n    super.dispose();\n  }\n\n  // ── Private: delta tracking ──\n\n  private _diffAndQueue(current: readonly T[], prev: readonly T[]): void {\n    const prevMap = new Map<T['id'], T>();\n    for (const item of prev) {\n      prevMap.set(item.id, item);\n    }\n\n    const currentMap = new Map<T['id'], T>();\n    for (const item of current) {\n      currentMap.set(item.id, item);\n    }\n\n    // Added or updated: in current but not in prev, or different reference\n    for (const item of current) {\n      const prevItem = prevMap.get(item.id);\n      if (!prevItem || prevItem !== item) {\n        this._pendingWrites.set(item.id, item);\n        this._pendingRemoves.delete(item.id);\n      }\n    }\n\n    // Removed: in prev but not in current\n    for (const item of prev) {\n      if (!currentMap.has(item.id)) {\n        this._pendingRemoves.add(item.id);\n        this._pendingWrites.delete(item.id);\n      }\n    }\n  }\n\n  private _hasPending(): boolean {\n    return this._pendingClear || this._pendingWrites.size > 0 || this._pendingRemoves.size > 0;\n  }\n\n  // ── Private: debounce + flush ──\n\n  private _scheduleSave(): void {\n    this._cancelSave();\n    const delay = (this.constructor as typeof PersistentCollection).WRITE_DELAY;\n    if (delay <= 0) {\n      this._doFlush();\n      return;\n    }\n    this._flushTimer = setTimeout(() => this._doFlush(), delay);\n  }\n\n  private _cancelSave(): void {\n    if (this._flushTimer !== null) {\n      clearTimeout(this._flushTimer);\n      this._flushTimer = null;\n    }\n  }\n\n  private _doFlush(): void {\n    if (!this._hasPending()) return;\n    try {\n      const result = this._flush();\n      if (result instanceof Promise) {\n        result.catch((err) => this._handlePersistError(err));\n      }\n    } catch (err) {\n      this._handlePersistError(err);\n    }\n  }\n\n  private _flush(): void | Promise<void> {\n    const doClear = this._pendingClear;\n    const writes = this._pendingWrites.size > 0 ? [...this._pendingWrites.values()] : null;\n    const removes = this._pendingRemoves.size > 0 ? [...this._pendingRemoves] : null;\n\n    // Clear queues\n    this._pendingClear = false;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n\n    if (doClear) {\n      const clearResult = this.persistClear();\n      if (clearResult instanceof Promise) {\n        return clearResult.then(() => {\n          if (writes) return this.persistSet(writes);\n        });\n      }\n      if (writes) {\n        return this.persistSet(writes);\n      }\n      return;\n    }\n\n    // Non-clear: removes then writes\n    if (removes) {\n      const removeResult = this.persistRemove(removes);\n      if (removeResult instanceof Promise) {\n        return removeResult.then(() => {\n          if (writes) return this.persistSet(writes);\n        });\n      }\n    }\n    if (writes) {\n      return this.persistSet(writes);\n    }\n  }\n\n  // ── Private: error handling ──\n\n  private _handlePersistError(err: unknown): void {\n    if (this.onPersistError) {\n      this.onPersistError(err);\n      return;\n    }\n    if (__DEV__) {\n      console.warn('[mvc-kit] Storage error:', err);\n    }\n  }\n}\n"],"names":[],"mappings":"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"}