@converse/skeletor 3.1.6 → 4.0.1

package/src/model.ts

@@ -1,4 +1,5 @@
 import {
+  bridgeSyncToPromise,
   getResolveablePromise,
   getStorage,
   getSyncMethod,
@@ -14,7 +15,7 @@ import has from 'lodash-es/has';
 import invert from 'lodash-es/invert';
 import isEmpty from 'lodash-es/isEmpty';
 import isEqual from 'lodash-es/isEqual';
-import iteratee from 'lodash-es/iteratee';
+import isMatch from 'lodash-es/isMatch';
 import omit from 'lodash-es/omit';
 import pick from 'lodash-es/pick';
 import result from 'lodash-es/result';
@@ -35,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 --
@@ -43,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;
@@ -67,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 || {};
 
@@ -82,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];
       },
@@ -108,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';
     }
   }
 
@@ -160,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
@@ -225,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.
    */
@@ -264,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];
   }
@@ -317,10 +350,19 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
   }
 
   /**
-   * Special-cased proxy to lodash's `matches` method.
+   * Returns `true` if the model's attributes satisfy `attrs`.
+   *
+   * An attributes object is compared with lodash's `isMatch`: a partial, deep
+   * comparison, so `{ form: { type: 'hidden' } }` matches a `form` attribute
+   * that has `type: 'hidden'` alongside other keys. A function is called with
+   * the attributes and its result coerced to a boolean.
+   *
+   * To scan a collection, prefer `Collection#find`, `filter` or `where`. They
+   * build their matcher once per scan instead of once per model.
    */
-  matches(attrs: Partial<T>): boolean {
-    return !!iteratee(attrs)(this.attributes);
+  matches(attrs: Partial<T> | ((attrs: T) => any)): boolean {
+    if (typeof attrs === 'function') return !!attrs(this.attributes);
+    return isMatch(this.attributes, attrs);
   }
 
   /**
@@ -342,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.`,
       );
@@ -394,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);
         }
       }
     }
@@ -420,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;
@@ -511,48 +554,26 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     const success = options.success;
     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 = (resp: any) => {
-      settled = true;
       const serverAttrs = options.parse ? this.parse(resp, options) : resp;
       // fromStorage prevents the set() from triggering auto-save on reads
-      if (!this.set(serverAttrs, Object.assign({}, options, { fromStorage: true }))) return false;
+      if (!this.set(serverAttrs, Object.assign({}, options, { fromStorage: true }))) {
+        // The fetched attributes failed validation (`'invalid'` has fired).
+        // Settle the promise with the error rather than leave it pending.
+        promise && promise.reject(this.validationError);
+        return false;
+      }
       if (success) success.call(options.context, this, resp, options);
       this.trigger('sync', this, resp, options);
       promise && promise.resolve(resp);
     };
 
     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 model is still
-        // merged 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;
+    // With `promise`, the sync's outcome is bridged to it however the sync
+    // reports it: through the callbacks, or through the promise it returns.
+    const result = bridgeSyncToPromise(options, promise, () => this.sync('read', this, options));
+    return promise ?? result;
   }
 
   /**
@@ -574,15 +595,19 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     options = Object.assign({ validate: true, parse: true }, options);
     const wait = options.wait;
     const return_promise = options.promise;
-    const promise = return_promise && getResolveablePromise();
+    const promise = return_promise ? getResolveablePromise() : undefined;
 
     // If we're not waiting and attributes exist, save acts as
     // `set(attr).save(null, opts)` with validation. Otherwise, check if
     // the model will be valid when the attributes, if any, are set.
-    if (attrs && !wait) {
-      if (!this.set(attrs, options)) return false;
-    } else if (!this._validate(attrs || {}, options)) {
-      return false;
+    const valid = attrs && !wait ? !!this.set(attrs, options) : this._validate(attrs || {}, options);
+    if (!valid) {
+      // Nothing is synced (`'invalid'` has fired). With `promise`, hand back a
+      // rejected promise rather than `false`, so the promise contract holds
+      // for every outcome.
+      if (!promise) return false;
+      promise.reject(this.validationError);
+      return promise;
     }
 
     // After a successful server-side save, the client is (optionally)
@@ -596,7 +621,12 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
       this.attributes = attributes;
       let serverAttrs = options.parse ? this.parse(resp, options) : resp;
       if (wait) serverAttrs = Object.assign({}, attrs, serverAttrs);
-      if (serverAttrs && !this.set(serverAttrs, options)) return false;
+      if (serverAttrs && !this.set(serverAttrs, options)) {
+        // The server attributes failed validation (`'invalid'` has fired).
+        // Settle the promise with the error rather than leave it pending.
+        return_promise && promise.reject(this.validationError);
+        return false;
+      }
       if (success) success.call(options.context, this, resp, options);
       this.trigger('sync', this, resp, options);
       return_promise && promise.resolve();
@@ -614,16 +644,14 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
 
     const method = this.isNew() ? 'create' : options.patch ? 'patch' : 'update';
     if (method === 'patch' && !options.attrs) options.attrs = attrs;
-    const xhr = this.sync(method, this, options);
+    // With `promise`, the sync's outcome is bridged to it however the sync
+    // reports it: through the callbacks, or through the promise it returns.
+    const xhr = bridgeSyncToPromise(options, promise, () => this.sync(method, this, options));
 
     // Restore attributes.
     this.attributes = attributes;
 
-    if (return_promise) {
-      return promise;
-    } else {
-      return xhr;
-    }
+    return promise ?? xhr;
   }
 
   /**