mvc-kit 2.8.0 → 2.9.0

package/dist/Pagination.cjs

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+class Pagination {
+  _page = 1;
+  _pageSize;
+  _listeners = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this._pageSize = options?.pageSize ?? 10;
+  }
+  // ── Readable state ──
+  /** Current page number (1-based). */
+  get page() {
+    return this._page;
+  }
+  /** Number of items per page. */
+  get pageSize() {
+    return this._pageSize;
+  }
+  // ── Derived (require total) ──
+  /** Total number of pages for the given item count. */
+  pageCount(total) {
+    return Math.max(1, Math.ceil(total / this._pageSize));
+  }
+  /** Whether there is a next page available. */
+  hasNext(total) {
+    return this._page < this.pageCount(total);
+  }
+  /** Whether there is a previous page available. */
+  hasPrev() {
+    return this._page > 1;
+  }
+  // ── Actions ──
+  /** Navigate to a specific page (clamped to >= 1). */
+  setPage(page) {
+    const clamped = Math.max(1, Math.floor(page));
+    if (clamped === this._page) return;
+    this._page = clamped;
+    this._notify();
+  }
+  /** Change the page size and reset to page 1. */
+  setPageSize(size) {
+    if (size < 1) return;
+    this._pageSize = size;
+    this._page = 1;
+    this._notify();
+  }
+  /** Advance to the next page. */
+  nextPage() {
+    this._page++;
+    this._notify();
+  }
+  /** Go back to the previous page. No-op if already on page 1. */
+  prevPage() {
+    if (this._page > 1) {
+      this._page--;
+      this._notify();
+    }
+  }
+  /** Reset to page 1. */
+  reset() {
+    if (this._page === 1) return;
+    this._page = 1;
+    this._notify();
+  }
+  // ── Pipeline ──
+  /** Slice an array to the current page window. Returns the page subset. */
+  apply(items) {
+    const start = (this._page - 1) * this._pageSize;
+    return items.slice(start, start + this._pageSize);
+  }
+  // ── Subscribable interface ──
+  /** Subscribe to pagination state changes. Returns an unsubscribe function. */
+  subscribe(cb) {
+    this._listeners.add(cb);
+    return () => {
+      this._listeners.delete(cb);
+    };
+  }
+  _notify() {
+    for (const cb of this._listeners) cb();
+  }
+}
+exports.Pagination = Pagination;
+//# sourceMappingURL=Pagination.cjs.map

package/dist/Pagination.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pagination.cjs","sources":["../src/Pagination.ts"],"sourcesContent":["/**\n * Page-based pagination state manager with array slicing pipeline.\n * Tracks current page and page size, provides navigation helpers.\n * Subscribable — auto-tracked when used as a ViewModel property.\n */\nexport class Pagination {\n  private _page: number = 1;\n  private _pageSize: number;\n  private _listeners = new Set<() => void>();\n\n  constructor(options?: { pageSize?: number }) {\n    this._pageSize = options?.pageSize ?? 10;\n  }\n\n  // ── Readable state ──\n\n  /** Current page number (1-based). */\n  get page(): number {\n    return this._page;\n  }\n\n  /** Number of items per page. */\n  get pageSize(): number {\n    return this._pageSize;\n  }\n\n  // ── Derived (require total) ──\n\n  /** Total number of pages for the given item count. */\n  pageCount(total: number): number {\n    return Math.max(1, Math.ceil(total / this._pageSize));\n  }\n\n  /** Whether there is a next page available. */\n  hasNext(total: number): boolean {\n    return this._page < this.pageCount(total);\n  }\n\n  /** Whether there is a previous page available. */\n  hasPrev(): boolean {\n    return this._page > 1;\n  }\n\n  // ── Actions ──\n\n  /** Navigate to a specific page (clamped to >= 1). */\n  setPage(page: number): void {\n    const clamped = Math.max(1, Math.floor(page));\n    if (clamped === this._page) return;\n    this._page = clamped;\n    this._notify();\n  }\n\n  /** Change the page size and reset to page 1. */\n  setPageSize(size: number): void {\n    if (size < 1) return;\n    this._pageSize = size;\n    this._page = 1;\n    this._notify();\n  }\n\n  /** Advance to the next page. */\n  nextPage(): void {\n    this._page++;\n    this._notify();\n  }\n\n  /** Go back to the previous page. No-op if already on page 1. */\n  prevPage(): void {\n    if (this._page > 1) {\n      this._page--;\n      this._notify();\n    }\n  }\n\n  /** Reset to page 1. */\n  reset(): void {\n    if (this._page === 1) return;\n    this._page = 1;\n    this._notify();\n  }\n\n  // ── Pipeline ──\n\n  /** Slice an array to the current page window. Returns the page subset. */\n  apply<T>(items: T[]): T[] {\n    const start = (this._page - 1) * this._pageSize;\n    return items.slice(start, start + this._pageSize);\n  }\n\n  // ── Subscribable interface ──\n\n  /** Subscribe to pagination state changes. Returns an unsubscribe function. */\n  subscribe(cb: () => void): () => void {\n    this._listeners.add(cb);\n    return () => { this._listeners.delete(cb); };\n  }\n\n  private _notify(): void {\n    for (const cb of this._listeners) cb();\n  }\n}\n"],"names":[],"mappings":";;AAKO,MAAM,WAAW;AAAA,EACd,QAAgB;AAAA,EAChB;AAAA,EACA,iCAAiB,IAAA;AAAA,EAEzB,YAAY,SAAiC;AAC3C,SAAK,YAAY,SAAS,YAAY;AAAA,EACxC;AAAA;AAAA;AAAA,EAKA,IAAI,OAAe;AACjB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,WAAmB;AACrB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA,EAKA,UAAU,OAAuB;AAC/B,WAAO,KAAK,IAAI,GAAG,KAAK,KAAK,QAAQ,KAAK,SAAS,CAAC;AAAA,EACtD;AAAA;AAAA,EAGA,QAAQ,OAAwB;AAC9B,WAAO,KAAK,QAAQ,KAAK,UAAU,KAAK;AAAA,EAC1C;AAAA;AAAA,EAGA,UAAmB;AACjB,WAAO,KAAK,QAAQ;AAAA,EACtB;AAAA;AAAA;AAAA,EAKA,QAAQ,MAAoB;AAC1B,UAAM,UAAU,KAAK,IAAI,GAAG,KAAK,MAAM,IAAI,CAAC;AAC5C,QAAI,YAAY,KAAK,MAAO;AAC5B,SAAK,QAAQ;AACb,SAAK,QAAA;AAAA,EACP;AAAA;AAAA,EAGA,YAAY,MAAoB;AAC9B,QAAI,OAAO,EAAG;AACd,SAAK,YAAY;AACjB,SAAK,QAAQ;AACb,SAAK,QAAA;AAAA,EACP;AAAA;AAAA,EAGA,WAAiB;AACf,SAAK;AACL,SAAK,QAAA;AAAA,EACP;AAAA;AAAA,EAGA,WAAiB;AACf,QAAI,KAAK,QAAQ,GAAG;AAClB,WAAK;AACL,WAAK,QAAA;AAAA,IACP;AAAA,EACF;AAAA;AAAA,EAGA,QAAc;AACZ,QAAI,KAAK,UAAU,EAAG;AACtB,SAAK,QAAQ;AACb,SAAK,QAAA;AAAA,EACP;AAAA;AAAA;AAAA,EAKA,MAAS,OAAiB;AACxB,UAAM,SAAS,KAAK,QAAQ,KAAK,KAAK;AACtC,WAAO,MAAM,MAAM,OAAO,QAAQ,KAAK,SAAS;AAAA,EAClD;AAAA;AAAA;AAAA,EAKA,UAAU,IAA4B;AACpC,SAAK,WAAW,IAAI,EAAE;AACtB,WAAO,MAAM;AAAE,WAAK,WAAW,OAAO,EAAE;AAAA,IAAG;AAAA,EAC7C;AAAA,EAEQ,UAAgB;AACtB,eAAW,MAAM,KAAK,WAAY,IAAA;AAAA,EACpC;AACF;;"}

package/dist/Pagination.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Page-based pagination state manager with array slicing pipeline.
+ * Tracks current page and page size, provides navigation helpers.
+ * Subscribable — auto-tracked when used as a ViewModel property.
+ */
+export declare class Pagination {
+    private _page;
+    private _pageSize;
+    private _listeners;
+    constructor(options?: {
+        pageSize?: number;
+    });
+    /** Current page number (1-based). */
+    get page(): number;
+    /** Number of items per page. */
+    get pageSize(): number;
+    /** Total number of pages for the given item count. */
+    pageCount(total: number): number;
+    /** Whether there is a next page available. */
+    hasNext(total: number): boolean;
+    /** Whether there is a previous page available. */
+    hasPrev(): boolean;
+    /** Navigate to a specific page (clamped to >= 1). */
+    setPage(page: number): void;
+    /** Change the page size and reset to page 1. */
+    setPageSize(size: number): void;
+    /** Advance to the next page. */
+    nextPage(): void;
+    /** Go back to the previous page. No-op if already on page 1. */
+    prevPage(): void;
+    /** Reset to page 1. */
+    reset(): void;
+    /** Slice an array to the current page window. Returns the page subset. */
+    apply<T>(items: T[]): T[];
+    /** Subscribe to pagination state changes. Returns an unsubscribe function. */
+    subscribe(cb: () => void): () => void;
+    private _notify;
+}
+//# sourceMappingURL=Pagination.d.ts.map

package/dist/Pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pagination.d.ts","sourceRoot":"","sources":["../src/Pagination.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAyB;gBAE/B,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;IAM3C,qCAAqC;IACrC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,gCAAgC;IAChC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAID,sDAAsD;IACtD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIhC,8CAA8C;IAC9C,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAI/B,kDAAkD;IAClD,OAAO,IAAI,OAAO;IAMlB,qDAAqD;IACrD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAO3B,gDAAgD;IAChD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAO/B,gCAAgC;IAChC,QAAQ,IAAI,IAAI;IAKhB,gEAAgE;IAChE,QAAQ,IAAI,IAAI;IAOhB,uBAAuB;IACvB,KAAK,IAAI,IAAI;IAQb,0EAA0E;IAC1E,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE;IAOzB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKrC,OAAO,CAAC,OAAO;CAGhB"}

package/dist/Pagination.js

@@ -0,0 +1,84 @@
+class Pagination {
+  _page = 1;
+  _pageSize;
+  _listeners = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this._pageSize = options?.pageSize ?? 10;
+  }
+  // ── Readable state ──
+  /** Current page number (1-based). */
+  get page() {
+    return this._page;
+  }
+  /** Number of items per page. */
+  get pageSize() {
+    return this._pageSize;
+  }
+  // ── Derived (require total) ──
+  /** Total number of pages for the given item count. */
+  pageCount(total) {
+    return Math.max(1, Math.ceil(total / this._pageSize));
+  }
+  /** Whether there is a next page available. */
+  hasNext(total) {
+    return this._page < this.pageCount(total);
+  }
+  /** Whether there is a previous page available. */
+  hasPrev() {
+    return this._page > 1;
+  }
+  // ── Actions ──
+  /** Navigate to a specific page (clamped to >= 1). */
+  setPage(page) {
+    const clamped = Math.max(1, Math.floor(page));
+    if (clamped === this._page) return;
+    this._page = clamped;
+    this._notify();
+  }
+  /** Change the page size and reset to page 1. */
+  setPageSize(size) {
+    if (size < 1) return;
+    this._pageSize = size;
+    this._page = 1;
+    this._notify();
+  }
+  /** Advance to the next page. */
+  nextPage() {
+    this._page++;
+    this._notify();
+  }
+  /** Go back to the previous page. No-op if already on page 1. */
+  prevPage() {
+    if (this._page > 1) {
+      this._page--;
+      this._notify();
+    }
+  }
+  /** Reset to page 1. */
+  reset() {
+    if (this._page === 1) return;
+    this._page = 1;
+    this._notify();
+  }
+  // ── Pipeline ──
+  /** Slice an array to the current page window. Returns the page subset. */
+  apply(items) {
+    const start = (this._page - 1) * this._pageSize;
+    return items.slice(start, start + this._pageSize);
+  }
+  // ── Subscribable interface ──
+  /** Subscribe to pagination state changes. Returns an unsubscribe function. */
+  subscribe(cb) {
+    this._listeners.add(cb);
+    return () => {
+      this._listeners.delete(cb);
+    };
+  }
+  _notify() {
+    for (const cb of this._listeners) cb();
+  }
+}
+export {
+  Pagination
+};
+//# sourceMappingURL=Pagination.js.map

package/dist/Pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pagination.js","sources":["../src/Pagination.ts"],"sourcesContent":["/**\n * Page-based pagination state manager with array slicing pipeline.\n * Tracks current page and page size, provides navigation helpers.\n * Subscribable — auto-tracked when used as a ViewModel property.\n */\nexport class Pagination {\n  private _page: number = 1;\n  private _pageSize: number;\n  private _listeners = new Set<() => void>();\n\n  constructor(options?: { pageSize?: number }) {\n    this._pageSize = options?.pageSize ?? 10;\n  }\n\n  // ── Readable state ──\n\n  /** Current page number (1-based). */\n  get page(): number {\n    return this._page;\n  }\n\n  /** Number of items per page. */\n  get pageSize(): number {\n    return this._pageSize;\n  }\n\n  // ── Derived (require total) ──\n\n  /** Total number of pages for the given item count. */\n  pageCount(total: number): number {\n    return Math.max(1, Math.ceil(total / this._pageSize));\n  }\n\n  /** Whether there is a next page available. */\n  hasNext(total: number): boolean {\n    return this._page < this.pageCount(total);\n  }\n\n  /** Whether there is a previous page available. */\n  hasPrev(): boolean {\n    return this._page > 1;\n  }\n\n  // ── Actions ──\n\n  /** Navigate to a specific page (clamped to >= 1). */\n  setPage(page: number): void {\n    const clamped = Math.max(1, Math.floor(page));\n    if (clamped === this._page) return;\n    this._page = clamped;\n    this._notify();\n  }\n\n  /** Change the page size and reset to page 1. */\n  setPageSize(size: number): void {\n    if (size < 1) return;\n    this._pageSize = size;\n    this._page = 1;\n    this._notify();\n  }\n\n  /** Advance to the next page. */\n  nextPage(): void {\n    this._page++;\n    this._notify();\n  }\n\n  /** Go back to the previous page. No-op if already on page 1. */\n  prevPage(): void {\n    if (this._page > 1) {\n      this._page--;\n      this._notify();\n    }\n  }\n\n  /** Reset to page 1. */\n  reset(): void {\n    if (this._page === 1) return;\n    this._page = 1;\n    this._notify();\n  }\n\n  // ── Pipeline ──\n\n  /** Slice an array to the current page window. Returns the page subset. */\n  apply<T>(items: T[]): T[] {\n    const start = (this._page - 1) * this._pageSize;\n    return items.slice(start, start + this._pageSize);\n  }\n\n  // ── Subscribable interface ──\n\n  /** Subscribe to pagination state changes. Returns an unsubscribe function. */\n  subscribe(cb: () => void): () => void {\n    this._listeners.add(cb);\n    return () => { this._listeners.delete(cb); };\n  }\n\n  private _notify(): void {\n    for (const cb of this._listeners) cb();\n  }\n}\n"],"names":[],"mappings":"AAKO,MAAM,WAAW;AAAA,EACd,QAAgB;AAAA,EAChB;AAAA,EACA,iCAAiB,IAAA;AAAA,EAEzB,YAAY,SAAiC;AAC3C,SAAK,YAAY,SAAS,YAAY;AAAA,EACxC;AAAA;AAAA;AAAA,EAKA,IAAI,OAAe;AACjB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,WAAmB;AACrB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA,EAKA,UAAU,OAAuB;AAC/B,WAAO,KAAK,IAAI,GAAG,KAAK,KAAK,QAAQ,KAAK,SAAS,CAAC;AAAA,EACtD;AAAA;AAAA,EAGA,QAAQ,OAAwB;AAC9B,WAAO,KAAK,QAAQ,KAAK,UAAU,KAAK;AAAA,EAC1C;AAAA;AAAA,EAGA,UAAmB;AACjB,WAAO,KAAK,QAAQ;AAAA,EACtB;AAAA;AAAA;AAAA,EAKA,QAAQ,MAAoB;AAC1B,UAAM,UAAU,KAAK,IAAI,GAAG,KAAK,MAAM,IAAI,CAAC;AAC5C,QAAI,YAAY,KAAK,MAAO;AAC5B,SAAK,QAAQ;AACb,SAAK,QAAA;AAAA,EACP;AAAA;AAAA,EAGA,YAAY,MAAoB;AAC9B,QAAI,OAAO,EAAG;AACd,SAAK,YAAY;AACjB,SAAK,QAAQ;AACb,SAAK,QAAA;AAAA,EACP;AAAA;AAAA,EAGA,WAAiB;AACf,SAAK;AACL,SAAK,QAAA;AAAA,EACP;AAAA;AAAA,EAGA,WAAiB;AACf,QAAI,KAAK,QAAQ,GAAG;AAClB,WAAK;AACL,WAAK,QAAA;AAAA,IACP;AAAA,EACF;AAAA;AAAA,EAGA,QAAc;AACZ,QAAI,KAAK,UAAU,EAAG;AACtB,SAAK,QAAQ;AACb,SAAK,QAAA;AAAA,EACP;AAAA;AAAA;AAAA,EAKA,MAAS,OAAiB;AACxB,UAAM,SAAS,KAAK,QAAQ,KAAK,KAAK;AACtC,WAAO,MAAM,MAAM,OAAO,QAAQ,KAAK,SAAS;AAAA,EAClD;AAAA;AAAA;AAAA,EAKA,UAAU,IAA4B;AACpC,SAAK,WAAW,IAAI,EAAE;AACtB,WAAO,MAAM;AAAE,WAAK,WAAW,OAAO,EAAE;AAAA,IAAG;AAAA,EAC7C;AAAA,EAEQ,UAAgB;AACtB,eAAW,MAAM,KAAK,WAAY,IAAA;AAAA,EACpC;AACF;"}

package/dist/PersistentCollection.cjs

@@ -18,6 +18,9 @@ class PersistentCollection extends Collection.Collection {
   // ── Internal state ──
   _hydrated = false;
   _hydrating = false;
+  // Suppresses the self-subscriber during reset/clear overrides,
+  // which queue deltas manually instead of relying on diff.
+  _suppressSubscriber = false;
   _persistenceReady = false;
   _preHydrationWarned = false;
   _pendingWrites = /* @__PURE__ */ new Map();
@@ -28,7 +31,7 @@ class PersistentCollection extends Collection.Collection {
   constructor(initialItems = []) {
     super(initialItems);
     const unsub = this.subscribe((current, prev) => {
-      if (this._hydrating) return;
+      if (this._hydrating || this._suppressSubscriber) return;
       this._ensurePersistenceReady();
       this._diffAndQueue(current, prev);
       this._scheduleSave();
@@ -134,11 +137,11 @@ class PersistentCollection extends Collection.Collection {
     for (const item of items) {
       this._pendingWrites.set(item.id, item);
     }
-    this._hydrating = true;
+    this._suppressSubscriber = true;
     try {
       super.reset(items);
     } finally {
-      this._hydrating = false;
+      this._suppressSubscriber = false;
     }
     this._scheduleSave();
   }
@@ -146,11 +149,11 @@ class PersistentCollection extends Collection.Collection {
     this._pendingClear = true;
     this._pendingWrites.clear();
     this._pendingRemoves.clear();
-    this._hydrating = true;
+    this._suppressSubscriber = true;
     try {
       super.clear();
     } finally {
-      this._hydrating = false;
+      this._suppressSubscriber = false;
     }
     this._scheduleSave();
   }

package/dist/PersistentCollection.cjs.map

@@ -1 +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 _diffMap = new Map<T['id'], T>();\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 = this._diffMap;\n    prevMap.clear();\n    for (const item of prev) {\n      prevMap.set(item.id, item);\n    }\n\n    // Added or updated: in current but different reference in prev\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      prevMap.delete(item.id); // consume matched items\n    }\n\n    // Remaining in prevMap = removed (in prev but not in current)\n    for (const [id] of prevMap) {\n      this._pendingRemoves.add(id);\n      this._pendingWrites.delete(id);\n    }\n\n    prevMap.clear();\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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"}
+{"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  /** Retrieve a single item by id from storage. @protected */\n  protected abstract persistGet(id: T['id']): T | null | Promise<T | null>;\n  /** Retrieve all items from storage. @protected */\n  protected abstract persistGetAll(): T[] | Promise<T[]>;\n  /** Upsert semantics — insert or replace the given items in storage. @protected */\n  protected abstract persistSet(items: T[]): void | Promise<void>;\n  /** Remove items by their ids from storage. @protected */\n  protected abstract persistRemove(ids: T['id'][]): void | Promise<void>;\n  /** Remove all items from storage. @protected */\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  // Suppresses the self-subscriber during reset/clear overrides,\n  // which queue deltas manually instead of relying on diff.\n  private _suppressSubscriber = 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 _diffMap = new Map<T['id'], T>();\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 || this._suppressSubscriber) 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    // Suppress the self-subscriber — deltas are queued manually above\n    this._suppressSubscriber = true;\n    try {\n      super.reset(items);\n    } finally {\n      this._suppressSubscriber = false;\n    }\n    this._scheduleSave();\n  }\n\n  clear(): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    // Suppress the self-subscriber — deltas are queued manually above\n    this._suppressSubscriber = true;\n    try {\n      super.clear();\n    } finally {\n      this._suppressSubscriber = 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 = this._diffMap;\n    prevMap.clear();\n    for (const item of prev) {\n      prevMap.set(item.id, item);\n    }\n\n    // Added or updated: in current but different reference in prev\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      prevMap.delete(item.id); // consume matched items\n    }\n\n    // Remaining in prevMap = removed (in prev but not in current)\n    for (const [id] of prevMap) {\n      this._pendingRemoves.add(id);\n      this._pendingWrites.delete(id);\n    }\n\n    prevMap.clear();\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.d.ts

@@ -11,11 +11,15 @@ export declare abstract class PersistentCollection<T extends {
     static WRITE_DELAY: number;
     /** Unique key identifying this collection in storage. */
     protected abstract readonly storageKey: string;
+    /** Retrieve a single item by id from storage. @protected */
     protected abstract persistGet(id: T['id']): T | null | Promise<T | null>;
+    /** Retrieve all items from storage. @protected */
     protected abstract persistGetAll(): T[] | Promise<T[]>;
-    /** Upsert semantics — insert or replace the given items. */
+    /** Upsert semantics — insert or replace the given items in storage. @protected */
     protected abstract persistSet(items: T[]): void | Promise<void>;
+    /** Remove items by their ids from storage. @protected */
     protected abstract persistRemove(ids: T['id'][]): void | Promise<void>;
+    /** Remove all items from storage. @protected */
     protected abstract persistClear(): void | Promise<void>;
     /** Serialize items to a string. Used by string-based adapters (WebStorage, NativeCollection). */
     protected serialize(items: T[]): string;
@@ -25,6 +29,7 @@ export declare abstract class PersistentCollection<T extends {
     protected onPersistError?(error: unknown): void;
     private _hydrated;
     private _hydrating;
+    private _suppressSubscriber;
     private _persistenceReady;
     private _preHydrationWarned;
     private _pendingWrites;

package/dist/PersistentCollection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PersistentCollection.d.ts","sourceRoot":"","sources":["../src/PersistentCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO1C;;;;GAIG;AACH,8BAAsB,oBAAoB,CACxC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CACjC,SAAQ,UAAU,CAAC,CAAC,CAAC;IACrB,8DAA8D;IAC9D,MAAM,CAAC,WAAW,SAAO;IAEzB,yDAAyD;IACzD,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAI/C,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IACxE,SAAS,CAAC,QAAQ,CAAC,aAAa,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IACtD,4DAA4D;IAC5D,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/D,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IACtE,SAAS,CAAC,QAAQ,CAAC,YAAY,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,iGAAiG;IACjG,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,MAAM;IAIvC,yEAAyE;IACzE,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,EAAE;IAMvC,iFAAiF;IACjF,SAAS,CAAC,cAAc,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAI/C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,WAAW,CAA8C;gBAErD,YAAY,GAAE,CAAC,EAAO;IAelC;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAmB/B,4CAA4C;IAC5C,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAqB7B;;;OAGG;IACH,SAAS,CAAC,YAAY,IAAI,IAAI;IAsB9B;;OAEG;IACH,YAAY,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BpC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAgBvB,KAAK,IAAI,IAAI;IAeb,IAAI,KAAK,IAAI,CAAC,EAAE,CASf;IAED,IAAI,KAAK,IAAI,CAAC,EAAE,CAEf;IAID,OAAO,IAAI,IAAI;IA0Bf,OAAO,CAAC,aAAa;IA0BrB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,MAAM;IAuCd,OAAO,CAAC,mBAAmB;CAS5B"}
+{"version":3,"file":"PersistentCollection.d.ts","sourceRoot":"","sources":["../src/PersistentCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO1C;;;;GAIG;AACH,8BAAsB,oBAAoB,CACxC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CACjC,SAAQ,UAAU,CAAC,CAAC,CAAC;IACrB,8DAA8D;IAC9D,MAAM,CAAC,WAAW,SAAO;IAEzB,yDAAyD;IACzD,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAI/C,4DAA4D;IAC5D,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IACxE,kDAAkD;IAClD,SAAS,CAAC,QAAQ,CAAC,aAAa,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IACtD,kFAAkF;IAClF,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/D,yDAAyD;IACzD,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IACtE,gDAAgD;IAChD,SAAS,CAAC,QAAQ,CAAC,YAAY,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,iGAAiG;IACjG,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,MAAM;IAIvC,yEAAyE;IACzE,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,EAAE;IAMvC,iFAAiF;IACjF,SAAS,CAAC,cAAc,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAI/C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAG3B,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,WAAW,CAA8C;gBAErD,YAAY,GAAE,CAAC,EAAO;IAelC;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAmB/B,4CAA4C;IAC5C,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAqB7B;;;OAGG;IACH,SAAS,CAAC,YAAY,IAAI,IAAI;IAsB9B;;OAEG;IACH,YAAY,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BpC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAiBvB,KAAK,IAAI,IAAI;IAgBb,IAAI,KAAK,IAAI,CAAC,EAAE,CASf;IAED,IAAI,KAAK,IAAI,CAAC,EAAE,CAEf;IAID,OAAO,IAAI,IAAI;IA0Bf,OAAO,CAAC,aAAa;IA0BrB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,MAAM;IAuCd,OAAO,CAAC,mBAAmB;CAS5B"}

package/dist/PersistentCollection.js

@@ -16,6 +16,9 @@ class PersistentCollection extends Collection {
   // ── Internal state ──
   _hydrated = false;
   _hydrating = false;
+  // Suppresses the self-subscriber during reset/clear overrides,
+  // which queue deltas manually instead of relying on diff.
+  _suppressSubscriber = false;
   _persistenceReady = false;
   _preHydrationWarned = false;
   _pendingWrites = /* @__PURE__ */ new Map();
@@ -26,7 +29,7 @@ class PersistentCollection extends Collection {
   constructor(initialItems = []) {
     super(initialItems);
     const unsub = this.subscribe((current, prev) => {
-      if (this._hydrating) return;
+      if (this._hydrating || this._suppressSubscriber) return;
       this._ensurePersistenceReady();
       this._diffAndQueue(current, prev);
       this._scheduleSave();
@@ -132,11 +135,11 @@ class PersistentCollection extends Collection {
     for (const item of items) {
       this._pendingWrites.set(item.id, item);
     }
-    this._hydrating = true;
+    this._suppressSubscriber = true;
     try {
       super.reset(items);
     } finally {
-      this._hydrating = false;
+      this._suppressSubscriber = false;
     }
     this._scheduleSave();
   }
@@ -144,11 +147,11 @@ class PersistentCollection extends Collection {
     this._pendingClear = true;
     this._pendingWrites.clear();
     this._pendingRemoves.clear();
-    this._hydrating = true;
+    this._suppressSubscriber = true;
     try {
       super.clear();
     } finally {
-      this._hydrating = false;
+      this._suppressSubscriber = false;
     }
     this._scheduleSave();
   }

package/dist/PersistentCollection.js.map

@@ -1 +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 _diffMap = new Map<T['id'], T>();\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 = this._diffMap;\n    prevMap.clear();\n    for (const item of prev) {\n      prevMap.set(item.id, item);\n    }\n\n    // Added or updated: in current but different reference in prev\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      prevMap.delete(item.id); // consume matched items\n    }\n\n    // Remaining in prevMap = removed (in prev but not in current)\n    for (const [id] of prevMap) {\n      this._pendingRemoves.add(id);\n      this._pendingWrites.delete(id);\n    }\n\n    prevMap.clear();\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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"}
+{"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  /** Retrieve a single item by id from storage. @protected */\n  protected abstract persistGet(id: T['id']): T | null | Promise<T | null>;\n  /** Retrieve all items from storage. @protected */\n  protected abstract persistGetAll(): T[] | Promise<T[]>;\n  /** Upsert semantics — insert or replace the given items in storage. @protected */\n  protected abstract persistSet(items: T[]): void | Promise<void>;\n  /** Remove items by their ids from storage. @protected */\n  protected abstract persistRemove(ids: T['id'][]): void | Promise<void>;\n  /** Remove all items from storage. @protected */\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  // Suppresses the self-subscriber during reset/clear overrides,\n  // which queue deltas manually instead of relying on diff.\n  private _suppressSubscriber = 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 _diffMap = new Map<T['id'], T>();\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 || this._suppressSubscriber) 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    // Suppress the self-subscriber — deltas are queued manually above\n    this._suppressSubscriber = true;\n    try {\n      super.reset(items);\n    } finally {\n      this._suppressSubscriber = false;\n    }\n    this._scheduleSave();\n  }\n\n  clear(): void {\n    this._pendingClear = true;\n    this._pendingWrites.clear();\n    this._pendingRemoves.clear();\n    // Suppress the self-subscriber — deltas are queued manually above\n    this._suppressSubscriber = true;\n    try {\n      super.clear();\n    } finally {\n      this._suppressSubscriber = 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 = this._diffMap;\n    prevMap.clear();\n    for (const item of prev) {\n      prevMap.set(item.id, item);\n    }\n\n    // Added or updated: in current but different reference in prev\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      prevMap.delete(item.id); // consume matched items\n    }\n\n    // Remaining in prevMap = removed (in prev but not in current)\n    for (const [id] of prevMap) {\n      this._pendingRemoves.add(id);\n      this._pendingWrites.delete(id);\n    }\n\n    prevMap.clear();\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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"}

package/dist/Resource.cjs

@@ -65,12 +65,15 @@ class Resource extends Collection.Collection {
     return this.onInit?.();
   }
   // ── Collection delegation ─────────────────────────────────────
+  /** Current items array. Delegates to external Collection when injected. */
   get state() {
     return this._external ? this._external.state : super.state;
   }
+  /** The raw array of items. Delegates to external Collection when injected. */
   get items() {
     return this._external ? this._external.items : super.items;
   }
+  /** Number of items. Delegates to external Collection when injected. */
   get length() {
     return this._external ? this._external.length : super.length;
   }

package/dist/Resource.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"Resource.cjs","sources":["../src/Resource.ts"],"sourcesContent":["import { Collection } from './Collection';\nimport { walkPrototypeChain } from './walkPrototypeChain';\nimport { wrapAsyncMethods } from './wrapAsyncMethods';\nimport type { InternalTaskState } from './wrapAsyncMethods';\nimport type { Listener, TaskState } from './types';\n\nconst __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;\n\n// ── Async tracking types ────────────────────────────────────────\n\nconst DEFAULT_TASK_STATE: TaskState = Object.freeze({ loading: false, error: null, errorCode: null });\n\nexport type ResourceAsyncMethodKeys<T> = {\n  [K in Exclude<keyof T, keyof Resource<any>>]: T[K] extends (...args: any[]) => Promise<any> ? K : never;\n}[Exclude<keyof T, keyof Resource<any>>];\n\ntype ResourceAsyncMap<T> = {\n  readonly [K in ResourceAsyncMethodKeys<T>]: TaskState;\n};\n\nconst RESERVED_ASYNC_KEYS = ['async', 'subscribeAsync'] as const;\nconst LIFECYCLE_HOOKS = new Set(['onInit', 'onDispose']);\n\n// ── Resource ────────────────────────────────────────────────────\n\n/**\n * Collection + async tracking toolkit. Extends Collection with lifecycle\n * (init/dispose) and automatic async method tracking. Optionally delegates\n * to an external Collection for shared data scenarios.\n */\nexport class Resource<T extends { id: string | number }> extends Collection<T> {\n  private _external: Collection<T> | null = null;\n  private _initialized = false;\n\n  // ── Async tracking fields ──\n  private _asyncStates = new Map<string, InternalTaskState>();\n  private _asyncSnapshots = new Map<string, TaskState>();\n  private _asyncListeners = new Set<() => void>();\n  private _asyncProxy: ResourceAsyncMap<this> | null = null;\n  private _activeOps: Map<string, number> | null = null;\n\n  /** DEV-only timeout (ms) for detecting ghost async operations after dispose. */\n  static GHOST_TIMEOUT = 3000;\n\n  constructor(collectionOrItems?: Collection<T> | T[]) {\n    const isExternal = collectionOrItems != null && !Array.isArray(collectionOrItems);\n    super(isExternal ? [] : (collectionOrItems as T[]) ?? []);\n\n    if (isExternal) {\n      this._external = collectionOrItems as Collection<T>;\n\n      if (__DEV__) {\n        const Ctor = this.constructor as typeof Resource;\n        if (Ctor.MAX_SIZE > 0 || Ctor.TTL > 0) {\n          console.warn(\n            `[mvc-kit] Resource \"${Ctor.name}\" has MAX_SIZE or TTL set but uses an ` +\n            `injected Collection. Configure these on the Collection instead.`\n          );\n        }\n      }\n    }\n\n    this._guardReservedKeys();\n  }\n\n  // ── Lifecycle ─────────────────────────────────────────────────\n\n  /** Whether init() has been called. */\n  get initialized(): boolean {\n    return this._initialized;\n  }\n\n  /** Initializes the instance. Called automatically by React hooks after mount. */\n  init(): void | Promise<void> {\n    if (this._initialized || this.disposed) return;\n    this._initialized = true;\n\n    if (__DEV__) {\n      this._activeOps = new Map();\n    }\n\n    wrapAsyncMethods({\n      instance: this,\n      stopPrototype: Resource.prototype,\n      reservedKeys: RESERVED_ASYNC_KEYS,\n      lifecycleHooks: LIFECYCLE_HOOKS,\n      isDisposed: () => this.disposed,\n      isInitialized: () => this._initialized,\n      asyncStates: this._asyncStates,\n      asyncSnapshots: this._asyncSnapshots,\n      asyncListeners: this._asyncListeners,\n      notifyAsync: () => this._notifyAsync(),\n      addCleanup: (fn) => this.addCleanup(fn),\n      ghostTimeout: (this.constructor as typeof Resource).GHOST_TIMEOUT,\n      className: 'Resource',\n      activeOps: this._activeOps,\n    });\n\n    return this.onInit?.();\n  }\n\n  /** Lifecycle hook called at the end of init(). Override to load initial data. @protected */\n  protected onInit?(): void | Promise<void>;\n\n  // ── Collection delegation ─────────────────────────────────────\n\n  get state(): T[] {\n    return this._external ? this._external.state : super.state;\n  }\n\n  get items(): T[] {\n    return this._external ? this._external.items : super.items;\n  }\n\n  get length(): number {\n    return this._external ? this._external.length : super.length;\n  }\n\n  add(...items: T[]): void {\n    this._external ? this._external.add(...items) : super.add(...items);\n  }\n\n  upsert(...items: T[]): void {\n    this._external ? this._external.upsert(...items) : super.upsert(...items);\n  }\n\n  update(id: T['id'], changes: Partial<T>): void {\n    this._external ? this._external.update(id, changes) : super.update(id, changes);\n  }\n\n  remove(...ids: T['id'][]): void {\n    this._external ? this._external.remove(...ids) : super.remove(...ids);\n  }\n\n  reset(items: T[]): void {\n    this._external ? this._external.reset(items) : super.reset(items);\n  }\n\n  clear(): void {\n    this._external ? this._external.clear() : super.clear();\n  }\n\n  optimistic(callback: () => void): () => void {\n    return this._external ? this._external.optimistic(callback) : super.optimistic(callback);\n  }\n\n  get(id: T['id']): T | undefined {\n    return this._external ? this._external.get(id) : super.get(id);\n  }\n\n  has(id: T['id']): boolean {\n    return this._external ? this._external.has(id) : super.has(id);\n  }\n\n  find(predicate: (item: T) => boolean): T | undefined {\n    return this._external ? this._external.find(predicate) : super.find(predicate);\n  }\n\n  filter(predicate: (item: T) => boolean): T[] {\n    return this._external ? this._external.filter(predicate) : super.filter(predicate);\n  }\n\n  sorted(compareFn: (a: T, b: T) => number): T[] {\n    return this._external ? this._external.sorted(compareFn) : super.sorted(compareFn);\n  }\n\n  map<U>(fn: (item: T) => U): U[] {\n    return this._external ? this._external.map(fn) : super.map(fn);\n  }\n\n  subscribe(listener: Listener<T[]>): () => void {\n    if (this.disposed) return () => {};\n    return this._external ? this._external.subscribe(listener) : super.subscribe(listener);\n  }\n\n  // ── Async tracking API ────────────────────────────────────────\n\n  /** Proxy providing `TaskState` (loading, error, errorCode) per async method. */\n  get async(): ResourceAsyncMap<this> {\n    if (!this._asyncProxy) {\n      const self = this;\n      this._asyncProxy = new Proxy({} as ResourceAsyncMap<this>, {\n        get(_, prop: string) {\n          return self._asyncSnapshots.get(prop) ?? DEFAULT_TASK_STATE;\n        },\n        has(_, prop: string) {\n          return self._asyncSnapshots.has(prop);\n        },\n        ownKeys() {\n          return Array.from(self._asyncSnapshots.keys());\n        },\n        getOwnPropertyDescriptor(_, prop: string) {\n          if (self._asyncSnapshots.has(prop)) {\n            return { configurable: true, enumerable: true, value: self._asyncSnapshots.get(prop) };\n          }\n          return undefined;\n        },\n      });\n    }\n    return this._asyncProxy;\n  }\n\n  /** Subscribes to async state changes. Used by `useInstance` for React integration. */\n  subscribeAsync(listener: () => void): () => void {\n    if (this.disposed) return () => {};\n    this._asyncListeners.add(listener);\n    return () => { this._asyncListeners.delete(listener); };\n  }\n\n  // ── Private: async tracking internals ─────────────────────────\n\n  private _notifyAsync(): void {\n    for (const listener of this._asyncListeners) {\n      listener();\n    }\n  }\n\n  private _guardReservedKeys(): void {\n    walkPrototypeChain(this, Resource.prototype, (key) => {\n      if (RESERVED_ASYNC_KEYS.includes(key as any)) {\n        throw new Error(\n          `[mvc-kit] \"${key}\" is a reserved property on Resource and cannot be overridden.`\n        );\n      }\n    });\n  }\n\n}\n"],"names":["Collection","wrapAsyncMethods","walkPrototypeChain"],"mappings":";;;;;AAMA,MAAM,UAAU,OAAO,oBAAoB,eAAe;AAI1D,MAAM,qBAAgC,OAAO,OAAO,EAAE,SAAS,OAAO,OAAO,MAAM,WAAW,MAAM;AAUpG,MAAM,sBAAsB,CAAC,SAAS,gBAAgB;AACtD,MAAM,kBAAkB,oBAAI,IAAI,CAAC,UAAU,WAAW,CAAC;AAShD,MAAM,iBAAoDA,WAAAA,WAAc;AAAA,EACrE,YAAkC;AAAA,EAClC,eAAe;AAAA;AAAA,EAGf,mCAAmB,IAAA;AAAA,EACnB,sCAAsB,IAAA;AAAA,EACtB,sCAAsB,IAAA;AAAA,EACtB,cAA6C;AAAA,EAC7C,aAAyC;AAAA;AAAA,EAGjD,OAAO,gBAAgB;AAAA,EAEvB,YAAY,mBAAyC;AACnD,UAAM,aAAa,qBAAqB,QAAQ,CAAC,MAAM,QAAQ,iBAAiB;AAChF,UAAM,aAAa,KAAM,qBAA6B,CAAA,CAAE;AAExD,QAAI,YAAY;AACd,WAAK,YAAY;AAEjB,UAAI,SAAS;AACX,cAAM,OAAO,KAAK;AAClB,YAAI,KAAK,WAAW,KAAK,KAAK,MAAM,GAAG;AACrC,kBAAQ;AAAA,YACN,uBAAuB,KAAK,IAAI;AAAA,UAAA;AAAA,QAGpC;AAAA,MACF;AAAA,IACF;AAEA,SAAK,mBAAA;AAAA,EACP;AAAA;AAAA;AAAA,EAKA,IAAI,cAAuB;AACzB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,OAA6B;AAC3B,QAAI,KAAK,gBAAgB,KAAK,SAAU;AACxC,SAAK,eAAe;AAEpB,QAAI,SAAS;AACX,WAAK,iCAAiB,IAAA;AAAA,IACxB;AAEAC,sCAAiB;AAAA,MACf,UAAU;AAAA,MACV,eAAe,SAAS;AAAA,MACxB,cAAc;AAAA,MACd,gBAAgB;AAAA,MAChB,YAAY,MAAM,KAAK;AAAA,MACvB,eAAe,MAAM,KAAK;AAAA,MAC1B,aAAa,KAAK;AAAA,MAClB,gBAAgB,KAAK;AAAA,MACrB,gBAAgB,KAAK;AAAA,MACrB,aAAa,MAAM,KAAK,aAAA;AAAA,MACxB,YAAY,CAAC,OAAO,KAAK,WAAW,EAAE;AAAA,MACtC,cAAe,KAAK,YAAgC;AAAA,MACpD,WAAW;AAAA,MACX,WAAW,KAAK;AAAA,IAAA,CACjB;AAED,WAAO,KAAK,SAAA;AAAA,EACd;AAAA;AAAA,EAOA,IAAI,QAAa;AACf,WAAO,KAAK,YAAY,KAAK,UAAU,QAAQ,MAAM;AAAA,EACvD;AAAA,EAEA,IAAI,QAAa;AACf,WAAO,KAAK,YAAY,KAAK,UAAU,QAAQ,MAAM;AAAA,EACvD;AAAA,EAEA,IAAI,SAAiB;AACnB,WAAO,KAAK,YAAY,KAAK,UAAU,SAAS,MAAM;AAAA,EACxD;AAAA,EAEA,OAAO,OAAkB;AACvB,SAAK,YAAY,KAAK,UAAU,IAAI,GAAG,KAAK,IAAI,MAAM,IAAI,GAAG,KAAK;AAAA,EACpE;AAAA,EAEA,UAAU,OAAkB;AAC1B,SAAK,YAAY,KAAK,UAAU,OAAO,GAAG,KAAK,IAAI,MAAM,OAAO,GAAG,KAAK;AAAA,EAC1E;AAAA,EAEA,OAAO,IAAa,SAA2B;AAC7C,SAAK,YAAY,KAAK,UAAU,OAAO,IAAI,OAAO,IAAI,MAAM,OAAO,IAAI,OAAO;AAAA,EAChF;AAAA,EAEA,UAAU,KAAsB;AAC9B,SAAK,YAAY,KAAK,UAAU,OAAO,GAAG,GAAG,IAAI,MAAM,OAAO,GAAG,GAAG;AAAA,EACtE;AAAA,EAEA,MAAM,OAAkB;AACtB,SAAK,YAAY,KAAK,UAAU,MAAM,KAAK,IAAI,MAAM,MAAM,KAAK;AAAA,EAClE;AAAA,EAEA,QAAc;AACZ,SAAK,YAAY,KAAK,UAAU,MAAA,IAAU,MAAM,MAAA;AAAA,EAClD;AAAA,EAEA,WAAW,UAAkC;AAC3C,WAAO,KAAK,YAAY,KAAK,UAAU,WAAW,QAAQ,IAAI,MAAM,WAAW,QAAQ;AAAA,EACzF;AAAA,EAEA,IAAI,IAA4B;AAC9B,WAAO,KAAK,YAAY,KAAK,UAAU,IAAI,EAAE,IAAI,MAAM,IAAI,EAAE;AAAA,EAC/D;AAAA,EAEA,IAAI,IAAsB;AACxB,WAAO,KAAK,YAAY,KAAK,UAAU,IAAI,EAAE,IAAI,MAAM,IAAI,EAAE;AAAA,EAC/D;AAAA,EAEA,KAAK,WAAgD;AACnD,WAAO,KAAK,YAAY,KAAK,UAAU,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;AAAA,EAC/E;AAAA,EAEA,OAAO,WAAsC;AAC3C,WAAO,KAAK,YAAY,KAAK,UAAU,OAAO,SAAS,IAAI,MAAM,OAAO,SAAS;AAAA,EACnF;AAAA,EAEA,OAAO,WAAwC;AAC7C,WAAO,KAAK,YAAY,KAAK,UAAU,OAAO,SAAS,IAAI,MAAM,OAAO,SAAS;AAAA,EACnF;AAAA,EAEA,IAAO,IAAyB;AAC9B,WAAO,KAAK,YAAY,KAAK,UAAU,IAAI,EAAE,IAAI,MAAM,IAAI,EAAE;AAAA,EAC/D;AAAA,EAEA,UAAU,UAAqC;AAC7C,QAAI,KAAK,SAAU,QAAO,MAAM;AAAA,IAAC;AACjC,WAAO,KAAK,YAAY,KAAK,UAAU,UAAU,QAAQ,IAAI,MAAM,UAAU,QAAQ;AAAA,EACvF;AAAA;AAAA;AAAA,EAKA,IAAI,QAAgC;AAClC,QAAI,CAAC,KAAK,aAAa;AACrB,YAAM,OAAO;AACb,WAAK,cAAc,IAAI,MAAM,IAA8B;AAAA,QACzD,IAAI,GAAG,MAAc;AACnB,iBAAO,KAAK,gBAAgB,IAAI,IAAI,KAAK;AAAA,QAC3C;AAAA,QACA,IAAI,GAAG,MAAc;AACnB,iBAAO,KAAK,gBAAgB,IAAI,IAAI;AAAA,QACtC;AAAA,QACA,UAAU;AACR,iBAAO,MAAM,KAAK,KAAK,gBAAgB,MAAM;AAAA,QAC/C;AAAA,QACA,yBAAyB,GAAG,MAAc;AACxC,cAAI,KAAK,gBAAgB,IAAI,IAAI,GAAG;AAClC,mBAAO,EAAE,cAAc,MAAM,YAAY,MAAM,OAAO,KAAK,gBAAgB,IAAI,IAAI,EAAA;AAAA,UACrF;AACA,iBAAO;AAAA,QACT;AAAA,MAAA,CACD;AAAA,IACH;AACA,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,eAAe,UAAkC;AAC/C,QAAI,KAAK,SAAU,QAAO,MAAM;AAAA,IAAC;AACjC,SAAK,gBAAgB,IAAI,QAAQ;AACjC,WAAO,MAAM;AAAE,WAAK,gBAAgB,OAAO,QAAQ;AAAA,IAAG;AAAA,EACxD;AAAA;AAAA,EAIQ,eAAqB;AAC3B,eAAW,YAAY,KAAK,iBAAiB;AAC3C,eAAA;AAAA,IACF;AAAA,EACF;AAAA,EAEQ,qBAA2B;AACjCC,uBAAAA,mBAAmB,MAAM,SAAS,WAAW,CAAC,QAAQ;AACpD,UAAI,oBAAoB,SAAS,GAAU,GAAG;AAC5C,cAAM,IAAI;AAAA,UACR,cAAc,GAAG;AAAA,QAAA;AAAA,MAErB;AAAA,IACF,CAAC;AAAA,EACH;AAEF;;"}
+{"version":3,"file":"Resource.cjs","sources":["../src/Resource.ts"],"sourcesContent":["import { Collection } from './Collection';\nimport { walkPrototypeChain } from './walkPrototypeChain';\nimport { wrapAsyncMethods } from './wrapAsyncMethods';\nimport type { InternalTaskState } from './wrapAsyncMethods';\nimport type { Listener, TaskState } from './types';\n\nconst __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;\n\n// ── Async tracking types ────────────────────────────────────────\n\nconst DEFAULT_TASK_STATE: TaskState = Object.freeze({ loading: false, error: null, errorCode: null });\n\nexport type ResourceAsyncMethodKeys<T> = {\n  [K in Exclude<keyof T, keyof Resource<any>>]: T[K] extends (...args: any[]) => Promise<any> ? K : never;\n}[Exclude<keyof T, keyof Resource<any>>];\n\ntype ResourceAsyncMap<T> = {\n  readonly [K in ResourceAsyncMethodKeys<T>]: TaskState;\n};\n\nconst RESERVED_ASYNC_KEYS = ['async', 'subscribeAsync'] as const;\nconst LIFECYCLE_HOOKS = new Set(['onInit', 'onDispose']);\n\n// ── Resource ────────────────────────────────────────────────────\n\n/**\n * Collection + async tracking toolkit. Extends Collection with lifecycle\n * (init/dispose) and automatic async method tracking. Optionally delegates\n * to an external Collection for shared data scenarios.\n */\nexport class Resource<T extends { id: string | number }> extends Collection<T> {\n  private _external: Collection<T> | null = null;\n  private _initialized = false;\n\n  // ── Async tracking fields ──\n  private _asyncStates = new Map<string, InternalTaskState>();\n  private _asyncSnapshots = new Map<string, TaskState>();\n  private _asyncListeners = new Set<() => void>();\n  private _asyncProxy: ResourceAsyncMap<this> | null = null;\n  private _activeOps: Map<string, number> | null = null;\n\n  /** DEV-only timeout (ms) for detecting ghost async operations after dispose. */\n  static GHOST_TIMEOUT = 3000;\n\n  constructor(collectionOrItems?: Collection<T> | T[]) {\n    const isExternal = collectionOrItems != null && !Array.isArray(collectionOrItems);\n    super(isExternal ? [] : (collectionOrItems as T[]) ?? []);\n\n    if (isExternal) {\n      this._external = collectionOrItems as Collection<T>;\n\n      if (__DEV__) {\n        const Ctor = this.constructor as typeof Resource;\n        if (Ctor.MAX_SIZE > 0 || Ctor.TTL > 0) {\n          console.warn(\n            `[mvc-kit] Resource \"${Ctor.name}\" has MAX_SIZE or TTL set but uses an ` +\n            `injected Collection. Configure these on the Collection instead.`\n          );\n        }\n      }\n    }\n\n    this._guardReservedKeys();\n  }\n\n  // ── Lifecycle ─────────────────────────────────────────────────\n\n  /** Whether init() has been called. */\n  get initialized(): boolean {\n    return this._initialized;\n  }\n\n  /** Initializes the instance. Called automatically by React hooks after mount. */\n  init(): void | Promise<void> {\n    if (this._initialized || this.disposed) return;\n    this._initialized = true;\n\n    if (__DEV__) {\n      this._activeOps = new Map();\n    }\n\n    wrapAsyncMethods({\n      instance: this,\n      stopPrototype: Resource.prototype,\n      reservedKeys: RESERVED_ASYNC_KEYS,\n      lifecycleHooks: LIFECYCLE_HOOKS,\n      isDisposed: () => this.disposed,\n      isInitialized: () => this._initialized,\n      asyncStates: this._asyncStates,\n      asyncSnapshots: this._asyncSnapshots,\n      asyncListeners: this._asyncListeners,\n      notifyAsync: () => this._notifyAsync(),\n      addCleanup: (fn) => this.addCleanup(fn),\n      ghostTimeout: (this.constructor as typeof Resource).GHOST_TIMEOUT,\n      className: 'Resource',\n      activeOps: this._activeOps,\n    });\n\n    return this.onInit?.();\n  }\n\n  /** Lifecycle hook called at the end of init(). Override to load initial data. @protected */\n  protected onInit?(): void | Promise<void>;\n\n  // ── Collection delegation ─────────────────────────────────────\n\n  /** Current items array. Delegates to external Collection when injected. */\n  get state(): T[] {\n    return this._external ? this._external.state : super.state;\n  }\n\n  /** The raw array of items. Delegates to external Collection when injected. */\n  get items(): T[] {\n    return this._external ? this._external.items : super.items;\n  }\n\n  /** Number of items. Delegates to external Collection when injected. */\n  get length(): number {\n    return this._external ? this._external.length : super.length;\n  }\n\n  add(...items: T[]): void {\n    this._external ? this._external.add(...items) : super.add(...items);\n  }\n\n  upsert(...items: T[]): void {\n    this._external ? this._external.upsert(...items) : super.upsert(...items);\n  }\n\n  update(id: T['id'], changes: Partial<T>): void {\n    this._external ? this._external.update(id, changes) : super.update(id, changes);\n  }\n\n  remove(...ids: T['id'][]): void {\n    this._external ? this._external.remove(...ids) : super.remove(...ids);\n  }\n\n  reset(items: T[]): void {\n    this._external ? this._external.reset(items) : super.reset(items);\n  }\n\n  clear(): void {\n    this._external ? this._external.clear() : super.clear();\n  }\n\n  optimistic(callback: () => void): () => void {\n    return this._external ? this._external.optimistic(callback) : super.optimistic(callback);\n  }\n\n  get(id: T['id']): T | undefined {\n    return this._external ? this._external.get(id) : super.get(id);\n  }\n\n  has(id: T['id']): boolean {\n    return this._external ? this._external.has(id) : super.has(id);\n  }\n\n  find(predicate: (item: T) => boolean): T | undefined {\n    return this._external ? this._external.find(predicate) : super.find(predicate);\n  }\n\n  filter(predicate: (item: T) => boolean): T[] {\n    return this._external ? this._external.filter(predicate) : super.filter(predicate);\n  }\n\n  sorted(compareFn: (a: T, b: T) => number): T[] {\n    return this._external ? this._external.sorted(compareFn) : super.sorted(compareFn);\n  }\n\n  map<U>(fn: (item: T) => U): U[] {\n    return this._external ? this._external.map(fn) : super.map(fn);\n  }\n\n  subscribe(listener: Listener<T[]>): () => void {\n    if (this.disposed) return () => {};\n    return this._external ? this._external.subscribe(listener) : super.subscribe(listener);\n  }\n\n  // ── Async tracking API ────────────────────────────────────────\n\n  /** Proxy providing `TaskState` (loading, error, errorCode) per async method. */\n  get async(): ResourceAsyncMap<this> {\n    if (!this._asyncProxy) {\n      const self = this;\n      this._asyncProxy = new Proxy({} as ResourceAsyncMap<this>, {\n        get(_, prop: string) {\n          return self._asyncSnapshots.get(prop) ?? DEFAULT_TASK_STATE;\n        },\n        has(_, prop: string) {\n          return self._asyncSnapshots.has(prop);\n        },\n        ownKeys() {\n          return Array.from(self._asyncSnapshots.keys());\n        },\n        getOwnPropertyDescriptor(_, prop: string) {\n          if (self._asyncSnapshots.has(prop)) {\n            return { configurable: true, enumerable: true, value: self._asyncSnapshots.get(prop) };\n          }\n          return undefined;\n        },\n      });\n    }\n    return this._asyncProxy;\n  }\n\n  /** Subscribes to async state changes. Used by `useInstance` for React integration. */\n  subscribeAsync(listener: () => void): () => void {\n    if (this.disposed) return () => {};\n    this._asyncListeners.add(listener);\n    return () => { this._asyncListeners.delete(listener); };\n  }\n\n  // ── Private: async tracking internals ─────────────────────────\n\n  private _notifyAsync(): void {\n    for (const listener of this._asyncListeners) {\n      listener();\n    }\n  }\n\n  private _guardReservedKeys(): void {\n    walkPrototypeChain(this, Resource.prototype, (key) => {\n      if (RESERVED_ASYNC_KEYS.includes(key as any)) {\n        throw new Error(\n          `[mvc-kit] \"${key}\" is a reserved property on Resource and cannot be overridden.`\n        );\n      }\n    });\n  }\n\n}\n"],"names":["Collection","wrapAsyncMethods","walkPrototypeChain"],"mappings":"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"}

package/dist/Resource.d.ts

@@ -30,8 +30,11 @@ export declare class Resource<T extends {
     init(): void | Promise<void>;
     /** Lifecycle hook called at the end of init(). Override to load initial data. @protected */
     protected onInit?(): void | Promise<void>;
+    /** Current items array. Delegates to external Collection when injected. */
     get state(): T[];
+    /** The raw array of items. Delegates to external Collection when injected. */
     get items(): T[];
+    /** Number of items. Delegates to external Collection when injected. */
     get length(): number;
     add(...items: T[]): void;
     upsert(...items: T[]): void;