@converse/skeletor 3.0.0 → 3.1.0

package/package.json

@@ -4,9 +4,25 @@
   "url": "https://github.com/conversejs/skeletor",
   "type": "module",
   "main": "dist/skeletor.js",
-  "module": "src/index.ts",
+  "module": "dist/skeletor.esm.js",
   "types": "dist/skeletor.d.ts",
   "browser": "dist/skeletor.js",
+  "exports": {
+    ".": {
+      "node": {
+        "require": "./dist/skeletor.node.js",
+        "import": "./dist/skeletor.node.mjs"
+      },
+      "default": {
+        "import": "./dist/skeletor.esm.js",
+        "require": "./dist/skeletor.js"
+      }
+    },
+    "./node": {
+      "require": "./dist/skeletor.node.js",
+      "import": "./dist/skeletor.node.mjs"
+    }
+  },
   "keywords": [
     "model",
     "view",
@@ -20,7 +36,10 @@
   "contributors": [
     "JC Brand"
   ],
-  "version": "3.0.0",
+  "version": "3.1.0",
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -32,17 +51,23 @@
     "build": "npm run prebuild && npm run build:declarations && rollup -c",
     "build:types": "tsc -p tsconfig.declarations.json",
     "build:declarations": "npm run build:types && api-extractor run --local && rm -rf dist/defs",
-    "check": "npm run check:types && npm run test && npm run lint",
+    "check": "npm run check:types && npm run test && npm run test:node && npm run lint",
     "check:types": "tsc --noEmit",
     "dev": "karma start --single-run=false",
     "lint": "eslint src/*.ts test/*.ts",
     "prettier": "prettier --write src/**/*.js test/**/*.js src/**/*.ts test/**/*.ts",
-    "test": "karma start && karma start --mocha-only"
+    "test": "karma start && karma start --mocha-only",
+    "test:node": "tsx node_modules/mocha/bin/mocha.js 'test/nodeStorage.test.ts'"
   },
   "files": [
     "LICENSE",
     "dist/skeletor.js",
+    "dist/skeletor.esm.js",
+    "dist/skeletor.js.map",
+    "dist/skeletor.esm.js.map",
     "dist/skeletor.min.js",
+    "dist/skeletor.node.js",
+    "dist/skeletor.node.mjs",
     "dist/skeletor.d.ts",
     "dist/skeletor.d.ts.map",
     "src/"
@@ -55,7 +80,8 @@
     "localforage-driver-memory": "^1.0.5",
     "localforage-setitems": "^1.4.0",
     "lodash-es": "^4.17.21",
-    "mergebounce": "0.1.3"
+    "mergebounce": "0.1.3",
+    "tslib": "^2.8.1"
   },
   "devDependencies": {
     "@babel/core": "^7.10.2",
@@ -92,6 +118,7 @@
     "rollup-plugin-summary": "^3.0.0",
     "sinon": "^9.0.2",
     "ts-loader": "^9.5.4",
+    "tsx": "^4.21.0",
     "typescript": "^5.8.3",
     "webpack": "^5.98.0",
     "webpack-cli": "^6.0.1",

package/src/autosync.ts

@@ -0,0 +1,156 @@
+/**
+ * Debounced auto-save scheduling and unload-flush for models/collections
+ * with autoSync enabled.
+ */
+import type PersistentStorage from './storage';
+import { IEventEmitter } from './types';
+
+const pending = new Map<IEventEmitter, { timerId: ReturnType<typeof setTimeout>; run: () => unknown }>();
+const inFlight = new Set<Promise<unknown>>();
+// Per-object view of `inFlight`, so a caller (notably `Model.destroy`) can
+// await the saves for a single object without blocking on unrelated writes.
+const inFlightByObj = new Map<IEventEmitter, Set<Promise<unknown>>>();
+let unloadListenerAttached = false;
+
+/**
+ * Execute a save `run` now and track the resulting promise as in-flight until
+ * it settles, both globally (`inFlight`) and per object (`inFlightByObj`), so
+ * `flushPending({ wait: true })` can await every save and `Model.destroy` can
+ * await just its own.
+ *
+ * @internal
+ * @param obj - The owning model/collection (or `null` when the save isn't tied to one).
+ *    A rejection is logged and re-surfaced on `obj`'s `error` event.
+ *    Called when a debounce timer fires or a flush forces it.
+ */
+function fireRun(obj: IEventEmitter | null, run: () => unknown): void {
+  const p = Promise.resolve(run()).catch((e) => {
+    console.error('Skeletor autoSync save error:', e);
+    // Surface failures that bypassed `options.error` on the model's `error` event,
+    // the same channel storage-layer failures already use. Storage saves route
+    // errors through `options.error` and then resolve, so they never reach this
+    // catch and won't double-emit.
+    obj?.trigger?.('error', obj, e);
+  });
+  inFlight.add(p);
+  let perObj: Set<Promise<unknown>> | undefined;
+  if (obj) {
+    perObj = inFlightByObj.get(obj);
+    if (!perObj) {
+      perObj = new Set();
+      inFlightByObj.set(obj, perObj);
+    }
+    perObj.add(p);
+  }
+  p.finally(() => {
+    inFlight.delete(p);
+    if (perObj) {
+      perObj.delete(p);
+      if (perObj.size === 0) inFlightByObj.delete(obj!);
+    }
+  });
+}
+
+/**
+ * Schedule a debounced auto-save for `obj`. Replaces any pending schedule
+ * for the same object.
+ * @internal
+ */
+export function scheduleAutoSave(obj: IEventEmitter, run: () => unknown, delay: number): void {
+  const existing = pending.get(obj);
+  if (existing) clearTimeout(existing.timerId);
+  const timerId = setTimeout(() => {
+    pending.delete(obj);
+    fireRun(obj, run);
+  }, delay);
+  pending.set(obj, { timerId, run });
+}
+
+/**
+ * Cancel any pending auto-save for `obj`.
+ *
+ * This only stops a *pending* (not-yet-fired) debounce timer. A save whose
+ * timer has already fired is in flight and beyond cancellation — sequence
+ * against it with {@link awaitInFlightSaves} instead.
+ * @internal
+ */
+export function cancelAutoSave(obj: IEventEmitter): void {
+  const existing = pending.get(obj);
+  if (existing) {
+    clearTimeout(existing.timerId);
+    pending.delete(obj);
+  }
+}
+
+/**
+ * Return a promise that settles once every in-flight auto-save for `obj` has
+ * completed, or `null` when none are in flight. `Model.destroy` uses this to
+ * sequence its delete after a save that has already fired, so a late write
+ * cannot land after the delete and resurrect the record.
+ * @internal
+ */
+export function awaitInFlightSaves(obj: IEventEmitter): Promise<void> | null {
+  const set = inFlightByObj.get(obj);
+  if (!set || set.size === 0) return null;
+  return Promise.all([...set]).then(() => undefined);
+}
+
+/**
+ * Immediately execute all pending auto-saves and flush storage-level
+ * debounced write buffers.
+ *
+ * Pass `wait: true` to also await all in-flight saves before resolving — use
+ * this in tests instead of arbitrary `setTimeout` sleeps.
+ *
+ * The default (`wait: false`) is synchronous and is what the unload handler
+ * uses, since the browser gives no way to await a write while the page is
+ * tearing down. It *initiates* every pending write synchronously (buffering
+ * into the storage-level batch and flushing it), giving the browser its best
+ * chance to persist them.
+ * @internal
+ */
+export function flushPending(opts?: { storage?: typeof PersistentStorage; wait?: false }): void;
+export function flushPending(opts: { storage?: typeof PersistentStorage; wait: true }): Promise<void>;
+export function flushPending({
+  storage,
+  wait = false,
+}: { storage?: typeof PersistentStorage; wait?: boolean } = {}): void | Promise<void> {
+  for (const [obj, { timerId, run }] of pending.entries()) {
+    clearTimeout(timerId);
+    fireRun(obj, run);
+  }
+  pending.clear();
+  if (storage) storage.flushAll();
+  if (wait) return Promise.all([...inFlight]).then(() => undefined);
+}
+
+/**
+ * Reset all module-level state. For use in test afterEach hooks only.
+ * @internal
+ */
+export function resetForTesting(): void {
+  for (const { timerId } of pending.values()) clearTimeout(timerId);
+  pending.clear();
+  inFlight.clear();
+  inFlightByObj.clear();
+  unloadListenerAttached = false;
+}
+
+/**
+ * Lazily attach pagehide/visibilitychange listeners in browser environments
+ * to flush pending writes when the page is hidden/unloading. This is a
+ * best-effort durability measure: the flush initiates writes synchronously but
+ * cannot guarantee an asynchronous backend finishes persisting them before the
+ * page goes away. Called at most once.
+ * @internal
+ */
+export function ensureUnloadListener(storage: typeof PersistentStorage): void {
+  if (unloadListenerAttached || typeof window === 'undefined') return;
+  unloadListenerAttached = true;
+
+  const flush = () => flushPending({ storage });
+  window.addEventListener('pagehide', flush);
+  window.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'hidden') flush();
+  });
+}

package/src/collection.ts

@@ -5,13 +5,15 @@ import isFunction from 'lodash-es/isFunction';
 import isString from 'lodash-es/isString';
 import keyBy from 'lodash-es/keyBy';
 import sortBy from 'lodash-es/sortBy';
-import {EventEmitterObject} from './eventemitter';
-import type Storage from './storage';
-import {getResolveablePromise, getSyncMethod, wrapError} from './helpers';
-import {Model} from './model';
+import { EventEmitterObject } from './eventemitter';
+import PersistentStorage from './storage';
+import { getResolveablePromise, getStorage, getSyncMethod, warnBrowserStorageDeprecation, wrapError } from './helpers';
+import { ensureUnloadListener } from './autosync';
+import { Model } from './model';
 import {
   CollectionOptions,
   Comparator,
+  EventCallback,
   FetchOrCreateOptions,
   ModelAttributes,
   ModelOptions,
@@ -21,8 +23,8 @@ import {
 } from './types';
 
 // Default options for `Collection#set`.
-const setOptions = {add: true, remove: true, merge: true};
-const addOptions = {add: true, remove: false};
+const setOptions = { add: true, remove: true, merge: true };
+const addOptions = { add: true, remove: false };
 
 /**
  * @public
@@ -35,9 +37,10 @@ const addOptions = {add: true, remove: false};
  */
 export class Collection<T extends Model = Model> extends EventEmitterObject {
   [key: symbol]: () => CollectionIterator<T>;
-  _browserStorage?: Storage;
+  _storage?: PersistentStorage;
   _comparator?: Comparator<T>;
   _url: string = '';
+  initialized?: Promise<void>;
   models: T[];
   protected _byId: Record<string, T>;
   protected _model?: new (attributes?: Partial<ModelAttributes>, options?: ModelOptions) => T;
@@ -55,9 +58,15 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     if (options.comparator !== undefined) this.comparator = options.comparator;
     this._reset();
     this.initialize.apply(this, arguments as any);
-    if (models) this.reset(models, Object.assign({silent: true}, options));
+    if (models) this.reset(models, Object.assign({ silent: true }, options));
 
     this[Symbol.iterator] = this.values;
+    // When autoSync is on, `initialized` is always a Promise so callers can
+    // uniformly `await collection.initialized`; it resolves immediately when
+    // there's no storage to hydrate from.
+    if (this.autoSync) {
+      this.initialized = getStorage(this) ? this.#hydrate() : Promise.resolve();
+    }
   }
 
   get comparator(): Comparator<T> {
@@ -68,12 +77,51 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     this._comparator = c;
   }
 
-  set browserStorage(storage: Storage) {
-    this._browserStorage = storage;
+  /**
+   * The canonical storage accessor. Set to a `PersistentStorage` instance
+   * to enable local persistence for this collection.
+   */
+  get storage(): PersistentStorage | undefined {
+    return this._storage;
+  }
+
+  set storage(s: PersistentStorage) {
+    this._storage = s;
+    PersistentStorage.register(s);
+  }
+
+  /**
+   * @deprecated Use `storage` instead.
+   */
+  get browserStorage(): PersistentStorage | undefined {
+    return this._storage;
+  }
+
+  set browserStorage(s: PersistentStorage) {
+    warnBrowserStorageDeprecation(this);
+    this.storage = s;
+  }
+
+  /**
+   * Override to return `true` to automatically load the collection from
+   * storage on construction. Await `initialized` to know when hydration
+   * is complete.
+   *
+   * Note: collection `autoSync` is hydrate-only. Unlike `Model`, it does
+   * **not** schedule auto-saves when the collection changes (`add`/`remove`/
+   * `reset`). Persisting members is each model's responsibility — enable
+   * `autoSync` on the contained model class and every model writes its own
+   * record. A collection-level write would be redundant with that.
+   */
+  get autoSync(): boolean {
+    return false;
   }
 
-  get browserStorage(): Storage | undefined {
-    return this._browserStorage;
+  async #hydrate(): Promise<void> {
+    ensureUnloadListener(PersistentStorage);
+    // findAll() returns [] for an empty store, so a first-run collection
+    // resolves rather than erroring the way a model fetch-by-id would.
+    await this.fetch({ fromStorage: true, promise: true });
   }
 
   /**
@@ -132,7 +180,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
    * combination of the two.
    */
   add(models: T[] | T | ModelAttributes | ModelAttributes[], options?: Options): T | T[] {
-    return this.set(models, Object.assign({merge: false}, options, addOptions));
+    return this.set(models, Object.assign({ merge: false }, options, addOptions));
   }
 
   /**
@@ -144,7 +192,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     const modelsArray = singular ? [models] : (models as T[]).slice();
     const removed = this._removeModels(modelsArray, options);
     if (!options.silent && removed.length) {
-      options.changes = {added: [], merged: [], removed: removed};
+      options.changes = { added: [], merged: [], removed: removed };
       this.trigger('update', this, options);
     }
     return singular ? removed[0] : removed;
@@ -247,7 +295,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     }
 
     // Silently sort the collection if appropriate.
-    if (sort) this.sort({silent: true});
+    if (sort) this.sort({ silent: true });
 
     // Unless silenced, it's time to fire all appropriate add/sort/update events.
     if (!options.silent) {
@@ -282,12 +330,12 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
                 console.error(e);
                 resolve();
               },
-            })
+            }),
           );
         });
-      })
+      }),
     );
-    await this.browserStorage?.clear();
+    await getStorage(this)?.clear();
     this.reset();
   }
 
@@ -304,7 +352,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     }
     options.previousModels = this.models;
     this._reset();
-    models = this.add(models, Object.assign({silent: true}, options));
+    models = this.add(models, Object.assign({ silent: true }, options));
     if (!options.silent) this.trigger('reset', this, options);
     return models as T | T[];
   }
@@ -313,7 +361,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
    * Add a model to the end of the collection.
    */
   push(model: T | ModelAttributes, options?: Options): T {
-    return this.add(model, Object.assign({at: this.length}, options)) as T;
+    return this.add(model, Object.assign({ at: this.length }, options)) as T;
   }
 
   /**
@@ -328,7 +376,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
    * Add a model to the beginning of the collection.
    */
   unshift(model: T | ModelAttributes, options?: Options): T {
-    return this.add(model, Object.assign({at: 0}, options)) as T;
+    return this.add(model, Object.assign({ at: 0 }, options)) as T;
   }
 
   /**
@@ -349,7 +397,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
       isFunction(callback)
         ? (callback as (model: T) => boolean)
         : (m) => m.matches(callback as Partial<ModelAttributes>),
-      thisArg
+      thisArg,
     );
   }
 
@@ -390,7 +438,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
       this.models,
       isFunction(iteratee)
         ? iteratee
-        : (m: T) => (isString(iteratee) ? m.get(iteratee as string) : m.matches(iteratee as Partial<ModelAttributes>))
+        : (m: T) => (isString(iteratee) ? m.get(iteratee as string) : m.matches(iteratee as Partial<ModelAttributes>)),
     );
   }
 
@@ -435,7 +483,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
       isFunction(pred)
         ? (pred as (model: T) => boolean)
         : (m) => (isString(pred) ? m.get(pred as string) : m.matches(pred as Partial<ModelAttributes>)),
-      fromIndex
+      fromIndex,
     );
   }
 
@@ -447,7 +495,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     return this.models.findIndex(
       isFunction(pred)
         ? (pred as (model: T) => boolean)
-        : (m) => (isString(pred) ? m.get(pred as string) : m.matches(pred as Partial<ModelAttributes>))
+        : (m) => (isString(pred) ? m.get(pred as string) : m.matches(pred as Partial<ModelAttributes>)),
     );
   }
 
@@ -469,7 +517,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
       isFunction(cb)
         ? (cb as (model: T) => U)
         : (m) => (isString(cb) ? m.get(cb as string) : m.matches(cb as Partial<ModelAttributes>)),
-      thisArg
+      thisArg,
     );
   }
 
@@ -572,20 +620,53 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
    * data will be passed through the `reset` method instead of `set`.
    */
   fetch(options?: Options): Promise<any> | any {
-    options = Object.assign({parse: true}, options);
+    options = Object.assign({ parse: true }, options);
     const success = options.success;
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const collection = this;
-    const promise = options.promise && getResolveablePromise();
+    const promise = options.promise ? getResolveablePromise() : undefined;
+
+    // Tracks whether sync invoked one of the callbacks. A sync may instead
+    // settle its returned promise; the `.then`/`.catch` below bridges that to
+    // the callbacks so the fetch promise never hangs. The flag is set
+    // synchronously inside each callback (before sync's promise resolves), so
+    // it's reliable by the time those handlers run.
+    let settled = false;
+
     options.success = function (resp: any) {
+      settled = true;
       const method = options.reset ? 'reset' : 'set';
-      collection[method](resp, options);
+      // fromStorage prevents individual model set() calls from triggering auto-save on reads
+      collection[method](resp, Object.assign({}, options, { fromStorage: true }));
       if (success) success.call(options.context, collection, resp, options);
       promise && promise.resolve();
       collection.trigger('sync', collection, resp, options);
     };
-    wrapError(this, options);
-    return promise ? promise : this.sync('read', this, options);
+    wrapError(this, options, promise);
+    if (promise) {
+      const onError = options.error;
+      options.error = (resp: any) => {
+        settled = true;
+        onError(resp);
+      };
+    }
+
+    const result = this.sync('read', this, options);
+    if (promise) {
+      Promise.resolve(result).then(
+        // A sync that resolves its promise without invoking options.success:
+        // treat the resolved value as the response, so the collection is still
+        // populated and the promise settles instead of hanging.
+        (value) => {
+          if (!settled) options.success(value);
+        },
+        // A sync that rejects instead of invoking options.error; settling
+        // twice is a harmless no-op.
+        (e) => promise.reject(e),
+      );
+      return promise;
+    }
+    return result;
   }
 
   /**
@@ -624,7 +705,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
       return_promise && promise.reject(e);
     };
 
-    preparedModel.save(null, Object.assign(options, {'promise': false}));
+    preparedModel.save(null, Object.assign(options, { 'promise': false }));
     if (return_promise) {
       return promise;
     } else {
@@ -632,6 +713,30 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     }
   }
 
+  /**
+   * Subscribe to collection changes (add, remove, reset, sort, update).
+   * Returns an unsubscribe function.
+   *
+   * `collection.subscribe(callback)` — fires once per operation on add/remove/reset/sort (via `update`, `reset`, `sort` events).
+   * `collection.subscribe(event, callback)` — subscribe to a specific event (base EventEmitter form).
+   *
+   * Compatible with React's `useSyncExternalStore` and other store-style APIs.
+   */
+  subscribe(event: string, callback: EventCallback, context?: unknown): () => void;
+  subscribe(callback: (collection: this) => void): () => void;
+  subscribe(
+    eventOrCallback: string | ((collection: this) => void),
+    callback?: EventCallback,
+    context?: unknown,
+  ): () => void {
+    if (typeof eventOrCallback === 'function') {
+      const cb = () => (eventOrCallback as (collection: this) => void)(this);
+      this.on('update reset sort', cb);
+      return () => this.off('update reset sort', cb);
+    }
+    return super.subscribe(eventOrCallback, callback, context);
+  }
+
   /**
    * **parse** converts a response into a list of models to be added to the
    * collection. The default implementation is just to pass it through.
@@ -816,7 +921,7 @@ export class CollectionIterator<T extends Model> {
         this._index++;
 
         if (!model) {
-          return {value: undefined, done: true};
+          return { value: undefined, done: true };
         }
 
         // Construct a value depending on what kind of values should be iterated.
@@ -832,7 +937,7 @@ export class CollectionIterator<T extends Model> {
             value = [id, model];
           }
         }
-        return {value, done: false};
+        return { value, done: false };
       }
 
       // Once exhausted, remove the reference to the collection so future
@@ -840,7 +945,7 @@ export class CollectionIterator<T extends Model> {
       this._collection = undefined;
     }
 
-    return {value: undefined, done: true};
+    return { value: undefined, done: true };
   }
 
   [Symbol.iterator](): IterableIterator<any> {

package/src/drivers/helpers.ts

@@ -0,0 +1,61 @@
+export function chainCallback<T>(promise: Promise<T>, callback: ((err: any, result?: T) => void) | undefined): void {
+  if (callback) {
+    promise.then(
+      (result) => callback(null, result),
+      (err) => callback(err),
+    );
+  }
+}
+
+export function getCallback(...args: any[]): ((...args: any[]) => void) | undefined {
+  if (args.length && typeof args[args.length - 1] === 'function') {
+    return args[args.length - 1];
+  }
+}
+
+export function normalizeKey(key: string | number): string {
+  if (typeof key !== 'string') {
+    console.warn(`${key} used as a key, but it is not a string.`);
+    key = String(key);
+  }
+  return key;
+}
+
+export function serializeSync(value: any): string {
+  return JSON.stringify(value, (_key, val) => {
+    if (val instanceof Date) {
+      return val.toISOString();
+    }
+    return val;
+  });
+}
+
+export function serialize(value: any, callback: (serializedValue: string, error: any) => void): void {
+  try {
+    callback(serializeSync(value), null);
+  } catch (e) {
+    callback('', e);
+  }
+}
+
+export function deserialize<T>(value: string): T {
+  return JSON.parse(value);
+}
+
+/**
+ * Sanitize a user-supplied string so it is safe to use as a single path segment.
+ * Removes path separators, null bytes, and resolves away any `.` / `..` components.
+ * Throws if the result is empty.
+ */
+export function sanitizePathSegment(segment: string): string {
+  if (typeof segment !== 'string' || segment.length === 0) {
+    throw new Error(`Storage name must be a non-empty string, got: ${JSON.stringify(segment)}`);
+  }
+  // eslint-disable-next-line no-control-regex
+  const cleaned = segment.replace(/\x00/g, '');
+  const sanitized = cleaned.replace(/[/\\]/g, '_');
+  if (sanitized.length === 0) {
+    throw new Error(`Storage name sanitized to an empty string: ${JSON.stringify(segment)}`);
+  }
+  return sanitized;
+}