@converse/skeletor 3.1.5 → 4.0.0

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';
@@ -317,10 +318,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);
   }
 
   /**
@@ -511,48 +521,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 +562,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 +588,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 +611,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;
   }
 
   /**

package/src/storage.ts

@@ -36,8 +36,13 @@ const registered = new WeakSet<PersistentStorage>();
 /**
  * Constructor for a Node.js-only storage driver. Registered by the
  * `@converse/skeletor/node` entry point via {@link PersistentStorage.nodeStorage}.
+ * @public
  */
-type NodeStorageConstructor = new (name: string) => StorageDriver;
+export type NodeStorageConstructor = new (
+  name: string,
+  storageDir?: string,
+  inMemory?: boolean,
+) => StorageDriver;
 
 /**
  * @public
@@ -60,6 +65,19 @@ class PersistentStorage {
   // bundle; the `@converse/skeletor/node` entry sets it.
   static nodeStorage: NodeStorageConstructor | null = null;
 
+  /**
+   * Directory the `'node'` store type writes its database files to. The driver's
+   * own default is relative, so it resolves against `process.cwd()` and a process
+   * started from two directories ends up with two separate sets of state. Set an
+   * absolute path (`$XDG_STATE_HOME/<app>`, say) to pin it. Left `null`, the
+   * driver's default applies.
+   *
+   * Only the `'node'` string store type reads this; passing a driver instance to
+   * the constructor means you've already chosen a directory yourself.
+   * @public
+   */
+  static nodeStorageDir: string | null = null;
+
   /** Register a storage instance with a weak reference. @public */
   static register(instance: PersistentStorage): void {
     if (registered.has(instance)) return;
@@ -128,7 +146,7 @@ class PersistentStorage {
             "Import from '@converse/skeletor/node' instead of '@converse/skeletor'.",
         );
       }
-      this.store = new NodeSQLiteStorage(this.name);
+      this.store = new NodeSQLiteStorage(this.name, PersistentStorage.nodeStorageDir ?? undefined);
       if (batchedWrites) {
         this.store.debouncedSetItems = mergebounce((items: Record<string, any>) => this.store.setItems!(items), 50, {
           'promise': true,
@@ -155,9 +173,11 @@ class PersistentStorage {
   async clear(): Promise<void> {
     await this.storeInitialized;
     await this.store.removeItem(this.name).catch((e) => console.error(e));
+
     const re = new RegExp(`^${this.name}-`);
     const keys = await this.store.keys();
     const removed_keys = keys.filter((k) => re.test(k));
+
     await Promise.all(removed_keys.map((k) => this.store.removeItem(k).catch((e) => console.error(e))));
   }