@converse/skeletor 4.0.0 → 4.0.2

package/package.json

@@ -39,25 +39,23 @@
   "contributors": [
     "JC Brand"
   ],
-  "version": "4.0.0",
+  "version": "4.0.2",
   "engines": {
     "node": ">=22.0.0"
   },
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/conversejs/skeletor.git"
+    "url": "git+https://github.com/conversejs/skeletor.git"
   },
   "scripts": {
-    "build": "npm run prebuild && npm run build:declarations && rollup -c",
-    "build:declarations": "npm run build:types && api-extractor run --local && api-extractor run --local -c api-extractor.node.json && rm -rf dist/defs",
-    "build:types": "tsc -p tsconfig.declarations.json",
+    "build": "npm run clean && rollup -c",
     "check": "npm run check:types && npm run test && npm run test:node && npm run lint",
     "check:types": "tsc --noEmit",
+    "check:dts": "tsc -p tsconfig.dts.json",
     "clean": "rm -rf dist",
     "dev": "karma start --single-run=false",
     "lint": "eslint src/*.ts test/*.ts",
-    "prebuild": "npm run clean && mkdir -p dist/defs",
     "prepack": "npm run build",
     "prettier": "prettier --write src/**/*.js test/**/*.js src/**/*.ts test/**/*.ts",
     "test": "karma start && karma start --mocha-only",
@@ -74,7 +72,6 @@
     "dist/skeletor.node.js",
     "dist/skeletor.node.mjs",
     "dist/skeletor.d.ts",
-    "dist/skeletor.d.ts.map",
     "dist/skeletor.node.d.ts",
     "src/**/*.ts"
   ],
@@ -90,25 +87,17 @@
     "tslib": "^2.8.1"
   },
   "devDependencies": {
-    "@babel/core": "^7.10.2",
-    "@babel/plugin-external-helpers": "^7.10.1",
-    "@babel/plugin-proposal-nullish-coalescing-operator": "^7.18.6",
-    "@babel/plugin-proposal-optional-chaining": "^7.13.12",
-    "@babel/preset-env": "^7.9.5",
-    "@microsoft/api-extractor": "^7.53.2",
-    "@rollup/plugin-babel": "^6.0.4",
     "@rollup/plugin-commonjs": "^28.0.3",
     "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-terser": "^1.0.0",
     "@rollup/plugin-typescript": "^12.1.4",
     "@types/chai": "^5.2.3",
     "@types/mocha": "^10.0.10",
+    "@types/node": "^26.6.5",
     "@types/qunit": "^2.19.13",
     "@types/sinon": "^17.0.4",
     "@typescript-eslint/eslint-plugin": "^8.29.0",
     "@typescript-eslint/parser": "^8.29.0",
-    "babel-eslint": "^10.1.0",
-    "babel-loader": "^9.2.1",
     "chai": "^4.2.0",
     "eslint": "^8.57.0",
     "karma": "^6.3.16",
@@ -117,15 +106,16 @@
     "karma-mocha": "^2.0.1",
     "karma-qunit": "^4.1.1",
     "karma-webpack": "^5.0.1",
-    "mocha": "^10.2.0",
+    "mocha": "^12.0.0",
     "prettier": "^3.0.0",
     "qunit": "^2.10.0",
     "rollup": "^4.39.0",
+    "rollup-plugin-dts": "^6.5.1",
     "rollup-plugin-summary": "^3.0.0",
     "sinon": "^9.0.2",
     "ts-loader": "^9.5.4",
     "tsx": "^4.21.0",
-    "typescript": "^5.8.3",
+    "typescript": "^6.0.3",
     "webpack": "^5.98.0",
     "webpack-cli": "^6.0.1",
     "window-or-global": "^1.0.1"

package/src/collection.ts

@@ -52,6 +52,36 @@ function toModelPredicate<T extends Model>(
   return (m: T) => matcher(m.attributes);
 }
 
+/**
+ * Load the collection's members from storage. A module-level function rather
+ * than a `#private` method so the published declarations carry no private
+ * members, which TypeScript 6 rejects in anonymously extended classes (TS4094).
+ */
+async function hydrate(collection: Collection<any>): Promise<void> {
+  ensureUnloadListener(PersistentStorage);
+  // An empty store is a normal first-run state: findAll() returns [] and a
+  // missing model record resolves to null, so hydration resolves rather
+  // than rejecting.
+  await collection.fetch({ fromStorage: true, promise: true });
+}
+
+/**
+ * `model` and `comparator` are declared on an interface merged with the class
+ * rather than on the class itself, so that subclasses may override them either
+ * as instance properties (`model = Contact`) or as accessors (`get model()`).
+ * TypeScript rejects the one form overriding the other (TS2610, TS2611) only
+ * when the base member is declared on a class.
+ */
+export interface Collection<T extends Model = Model> {
+  /**
+   * The model class to instantiate when raw attributes are added. Defaults to
+   * `Model` when unset. Typed loosely so that model classes whose constructors
+   * take required or narrower attributes and options fit.
+   */
+  model: new (attributes?: any, options?: any) => T;
+  comparator: Comparator<T>;
+}
+
 /**
  * @public
  * If models tend to represent a single row of data, a Collection is
@@ -61,15 +91,14 @@ function toModelPredicate<T extends Model>(
  * belonging to this particular author, and so on. Collections maintain
  * indexes of their models, both in order, and for lookup by `id`.
  */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging -- see the interface above
 export class Collection<T extends Model = Model> extends EventEmitterObject {
   [key: symbol]: () => CollectionIterator<T>;
   _storage?: PersistentStorage;
-  _comparator?: Comparator<T>;
   _url: string = '';
   hydrated?: Promise<void>;
   models: T[];
   protected _byId: Record<string, T>;
-  protected _model?: new (attributes?: Partial<ModelAttributes>, options?: ModelOptions) => T;
 
   /**
    * Create a new **Collection**, perhaps to contain a specific type of `model`.
@@ -80,7 +109,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     super();
     options = options || {};
     this.preinitialize.apply(this, arguments as any);
-    if (options.model) this._model = options.model;
+    if (options.model) this.model = options.model;
     if (options.comparator !== undefined) this.comparator = options.comparator;
     this._reset();
     this.initialize.apply(this, arguments as any);
@@ -91,18 +120,10 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     // uniformly `await collection.hydrated`; it resolves immediately when
     // there's no storage to hydrate from.
     if (this.autoSync) {
-      this.hydrated = getStorage(this) ? this.#hydrate() : Promise.resolve();
+      this.hydrated = getStorage(this) ? hydrate(this) : Promise.resolve();
     }
   }
 
-  get comparator(): Comparator<T> {
-    return this._comparator;
-  }
-
-  set comparator(c: Comparator<T>) {
-    this._comparator = c;
-  }
-
   /**
    * The canonical storage accessor. Set to a `PersistentStorage` instance
    * to enable local persistence for this collection.
@@ -143,26 +164,6 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     return false;
   }
 
-  async #hydrate(): Promise<void> {
-    ensureUnloadListener(PersistentStorage);
-    // An empty store is a normal first-run state: findAll() returns [] and a
-    // missing model record resolves to null, so hydration resolves rather
-    // than rejecting.
-    await this.fetch({ fromStorage: true, promise: true });
-  }
-
-  /**
-   * The default model for a collection is just a **Model**.
-   * This should be overridden in most cases.
-   */
-  get model(): new (attributes?: Partial<ModelAttributes>, options?: ModelOptions) => T | Model {
-    return this._model ?? Model;
-  }
-
-  set model(model: new (attributes?: Partial<ModelAttributes>, options?: ModelOptions) => T) {
-    this._model = model;
-  }
-
   get length(): number {
     return this.models.length;
   }
@@ -740,7 +741,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
    * Define how to uniquely identify models in the collection.
    */
   modelId(attrs: ModelAttributes): string | number | undefined {
-    return attrs[this.model.prototype?.idAttribute || 'id'];
+    return attrs[(this.model ?? Model).prototype?.idAttribute || 'id'];
   }
 
   /** Get an iterator of all models in this collection. */
@@ -774,7 +775,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
   }
 
   createModel(attrs: ModelAttributes, options?: Options): T {
-    const Klass = this.model;
+    const Klass = this.model ?? Model;
     return new Klass(attrs, options) as T;
   }
 

package/src/model.ts

@@ -36,6 +36,72 @@ import {
   Options,
 } from './types';
 
+/**
+ * Per-instance state that is private to this module.
+ *
+ * It lives in a WeakMap rather than in ES `#private` fields so that the
+ * published declarations carry no private members. TypeScript 6 refuses to
+ * emit an anonymous class type whose base has private members (TS4094), and
+ * that is exactly what the usual mixin pattern (`class extends Base`) over
+ * `Model` produces in consumers such as Converse.
+ */
+type ModelInternals = {
+  state: 'constructing' | 'hydrating' | 'ready';
+  computedCache?: Record<string, any>;
+  computedDefs?: ComputedProperties<any>;
+};
+
+const INTERNALS = new WeakMap<Model<any>, ModelInternals>();
+
+function internals(model: Model<any>): ModelInternals {
+  let priv = INTERNALS.get(model);
+  if (!priv) {
+    priv = { state: 'constructing' };
+    INTERNALS.set(model, priv);
+  }
+  return priv;
+}
+
+/** Load the model from storage, marking it ready whether or not the read succeeds. */
+async function hydrate(model: Model<any>, priv: ModelInternals): Promise<void> {
+  ensureUnloadListener(PersistentStorage);
+  try {
+    await model.fetch({ fromStorage: true, promise: true });
+  } finally {
+    priv.state = 'ready';
+  }
+}
+
+/** Evaluate the model's declared computed properties once, seeding the cache. */
+function initComputed(model: Model<any>, priv: ModelInternals): void {
+  const defs = result(model, 'computed') as ComputedProperties<any>;
+  if (!defs || isEmpty(defs)) return;
+  priv.computedDefs = defs;
+  priv.computedCache = {};
+  for (const [key, def] of Object.entries(defs)) {
+    priv.computedCache[key] = def.fn(model);
+  }
+}
+
+/** Recompute one computed property, firing `change:key` when its value changed. */
+function updateComputed(
+  model: Model<any>,
+  priv: ModelInternals,
+  key: string,
+  def: ComputedProperty<any>,
+  silent: boolean,
+  options: ModelOptions,
+): void {
+  const newVal = def.fn(model);
+  if (!isEqual(priv.computedCache[key], newVal)) {
+    priv.computedCache[key] = newVal;
+    if (!silent) {
+      (model.changed as any)[key] = newVal;
+      model.trigger('change:' + key, model, newVal, options);
+    }
+  }
+}
+
 /**
  * @public
  * **Models** are the basic data object in the framework --
@@ -44,9 +110,6 @@ import {
  * performing computations and transformations on that data.
  */
 export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmitterObject {
-  #computedCache?: Record<string, any>;
-  #computedDefs?: Record<string, ComputedProperty<this>>;
-  #state: 'constructing' | 'hydrating' | 'ready' = 'constructing';
   _storage?: PersistentStorage;
   _changing = false;
   _pending: boolean | ModelOptions = false;
@@ -68,6 +131,7 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
    */
   constructor(attributes?: Partial<T>, options?: ModelOptions) {
     super();
+    const priv = internals(this);
     let attrs: Partial<T> = attributes || ({} as Partial<T>);
     options = options || {};
 
@@ -83,12 +147,13 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
 
     this.set(attrs, options);
 
-    this.#initComputed();
+    initComputed(this, priv);
 
     this.attrs = new Proxy(this.attributes as T, {
       get: (_target, key) => {
-        if (typeof key !== 'symbol' && this.#computedCache && (key as string) in this.#computedCache) {
-          return this.#computedCache[key as string];
+        const cache = priv.computedCache;
+        if (typeof key !== 'symbol' && cache && (key as string) in cache) {
+          return cache[key as string];
         }
         return (this.attributes as any)[key];
       },
@@ -109,14 +174,14 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     // otherwise it's already ready and resolves immediately.
     if (this.autoSync) {
       if (getStorage(this) && !this.isNew()) {
-        this.#state = 'hydrating';
-        this.hydrated = this.#hydrate();
+        priv.state = 'hydrating';
+        this.hydrated = hydrate(this, priv);
       } else {
-        this.#state = 'ready';
+        priv.state = 'ready';
         this.hydrated = Promise.resolve();
       }
     } else {
-      this.#state = 'ready';
+      priv.state = 'ready';
     }
   }
 
@@ -161,19 +226,6 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     return 100;
   }
 
-  async #hydrate(): Promise<void> {
-    ensureUnloadListener(PersistentStorage);
-    try {
-      await this.fetch({ fromStorage: true, promise: true });
-    } finally {
-      this.#state = 'ready';
-    }
-  }
-
-  #doAutoSave(): unknown {
-    return this.save(null, { noAutoSave: true });
-  }
-
   /**
    * The default name for the JSON `id` attribute is `"id"`. MongoDB and
    * CouchDB users may want to set this to `"_id"` (by overriding this getter
@@ -226,27 +278,6 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     return {};
   }
 
-  #updateComputed(key: string, def: ComputedProperty<this>, silent: boolean, options: ModelOptions): void {
-    const newVal = def.fn(this);
-    if (!isEqual(this.#computedCache[key], newVal)) {
-      this.#computedCache[key] = newVal;
-      if (!silent) {
-        (this.changed as any)[key] = newVal;
-        this.trigger('change:' + key, this, newVal, options);
-      }
-    }
-  }
-
-  #initComputed(): void {
-    const defs = result(this, 'computed') as ComputedProperties<this>;
-    if (!defs || isEmpty(defs)) return;
-    this.#computedDefs = defs;
-    this.#computedCache = {};
-    for (const [key, def] of Object.entries(defs)) {
-      this.#computedCache[key] = def.fn(this);
-    }
-  }
-
   /**
    * Return a copy of the model's `attributes` object.
    */
@@ -265,8 +296,9 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
    * Get the value of an attribute, or a computed property.
    */
   get<K extends keyof T>(attr: K): T[K] {
-    if (this.#computedCache && (attr as string) in this.#computedCache) {
-      return this.#computedCache[attr as string];
+    const cache = internals(this).computedCache;
+    if (cache && (attr as string) in cache) {
+      return cache[attr as string];
     }
     return this.attributes[attr];
   }
@@ -352,10 +384,11 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     }
 
     options = options || {};
+    const priv = internals(this);
 
     // Guard must come after arg normalization: when called as set(obj, opts),
     // fromStorage lives in `val` (second arg), not `options` (third arg).
-    if (this.autoSync && this.#state === 'hydrating' && !options.fromStorage) {
+    if (this.autoSync && priv.state === 'hydrating' && !options.fromStorage) {
       throw new Error(
         `Skeletor: set() called on an autoSync model before hydration resolved. Await model.hydrated first.`,
       );
@@ -404,10 +437,10 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     }
 
     // Recalculate computed properties whose deps changed.
-    if (changes.length && this.#computedDefs) {
-      for (const [key, def] of Object.entries(this.#computedDefs)) {
+    if (changes.length && priv.computedDefs) {
+      for (const [key, def] of Object.entries(priv.computedDefs)) {
         if (def.deps.some((dep) => changes.includes(dep))) {
-          this.#updateComputed(key, def, silent, options);
+          updateComputed(this, priv, key, def, silent, options);
         }
       }
     }
@@ -430,14 +463,14 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     // were actual changes that originated from application code (not a
     // storage read or an explicit noAutoSave call).
     if (
-      this.#state === 'ready' &&
+      priv.state === 'ready' &&
       this.autoSync &&
       getStorage(this) &&
       changes.length &&
       !options.fromStorage &&
       !options.noAutoSave
     ) {
-      scheduleAutoSave(this, () => this.#doAutoSave(), this.autoSyncDelay);
+      scheduleAutoSave(this, () => this.save(null, { noAutoSave: true }), this.autoSyncDelay);
     }
 
     return this;

package/src/types.ts

@@ -62,10 +62,7 @@ export type EventListenerMap = Record<string, ListeningType>;
 /**
  * @public
  */
-export interface EventHandlersMap {
-  all?: EventHandler[];
-  [name: string]: EventHandler[];
-}
+export type EventHandlersMap = Record<string, EventHandler[]>;
 
 /**
  * @public
@@ -168,7 +165,9 @@ export type IterateeFunction = (
  */
 export type ComputedProperty<M> = {
   deps: string[];
-  fn: (model: M) => any;
+  // Method syntax, so that TypeScript checks `fn` bivariantly and
+  // `ComputedProperties<Subclass>` stays assignable to `ComputedProperties<Model>`.
+  fn(model: M): any;
 };
 
 /**
@@ -198,7 +197,7 @@ export type FetchOrCreateOptions = Options & {
  * @public
  */
 export type CollectionOptions<T extends Model = Model> = Options & {
-  model?: new (attributes?: Partial<ModelAttributes>, options?: ModelOptions) => T;
+  model?: new (attributes?: any, options?: any) => T;
   comparator?: Comparator<T>;
   previousModels?: Model[];
 };