@converse/skeletor 3.1.5 → 4.0.0

package/dist/skeletor.node.mjs

@@ -7792,6 +7792,16 @@ function guid() {
     // Generate a pseudo-GUID by concatenating random hexadecimal.
     return S4() + S4() + '-' + S4() + '-' + S4() + '-' + S4() + '-' + S4() + S4() + S4();
 }
+// Helpers
+// -------
+/**
+ * Whether `value` is a thenable (a promise, or a promise-like object such as
+ * a jqXHR). Decides whether a `sync` return value can be bridged to the
+ * promise that `fetch`/`save` hand back.
+ */
+function isThenable(value) {
+    return value != null && typeof value.then === 'function';
+}
 function getResolveablePromise() {
     const wrapper = {
         isResolved: false,
@@ -7836,6 +7846,65 @@ function wrapError(model, options, promise) {
         promise && promise.reject && promise.reject(resp);
     };
 }
+/**
+ * Run a `sync` and make sure `promise` settles from its outcome, however the
+ * sync reports it.
+ *
+ * A `sync` may invoke `options.success`/`options.error` (the callback
+ * contract), or settle the promise it returns without calling them: a
+ * promise-only custom sync, or an async sync whose promise rejects because a
+ * `'sync'`/`'error'` listener threw after the callbacks ran. `options.success`
+ * and `options.error` must already be wired to resolve/reject `promise`. This
+ * wraps them to record that they ran, calls `run()`, and bridges a thenable
+ * result to them so the promise never hangs:
+ *
+ * - fulfilment with the callbacks unrun is delivered to `options.success`, so
+ *   the response is still merged into the model or collection;
+ * - rejection with the callbacks unrun is delivered to `options.error`, so the
+ *   caller's `error` callback and the `'error'` event still fire;
+ * - rejection after the callbacks ran rejects `promise` directly: a no-op if
+ *   they already settled it, and the only way to settle it if a listener threw
+ *   before they could;
+ * - a throw from either delivery (a throwing `success`/`error` callback or
+ *   listener) rejects `promise` instead of surfacing as an unhandled rejection.
+ *
+ * A non-thenable result (a callback-only sync that returns nothing, or an
+ * XHR) is left alone: such a sync settles `promise` through its callbacks, and
+ * bridging it would fire `success` on the next microtask, before the sync is
+ * done. Without a `promise`, `run()` is called as is.
+ */
+function bridgeSyncToPromise(options, promise, run) {
+    if (!promise)
+        return run();
+    let settled = false;
+    const success = options.success;
+    const error = options.error;
+    options.success = (...args) => {
+        settled = true;
+        return success && success(...args);
+    };
+    options.error = (...args) => {
+        settled = true;
+        return error && error(...args);
+    };
+    const result = run();
+    if (isThenable(result)) {
+        Promise.resolve(result)
+            .then((value) => {
+            if (!settled)
+                options.success(value);
+        }, (e) => {
+            if (settled) {
+                promise.reject(e);
+            }
+            else {
+                options.error(e);
+            }
+        })
+            .catch((e) => promise.reject(e));
+    }
+    return result;
+}
 // Map from CRUD to HTTP for our default `sync` implementation.
 const methodMap = {
     create: 'POST',
@@ -7885,43 +7954,77 @@ function getSyncMethod(model) {
     return store ? store.sync() : sync;
 }
 /**
- * Override this function to change the manner in which Backbone persists
- * models to the server. You will be passed the type of request, and the
- * model in question. By default makes a `fetch()` API call
- * to the model's `url()`.
- *
- * Some possible customizations could be:
- *
- * - Use `setTimeout` to batch rapid-fire updates into a single request.
- * - Persist models via WebSockets instead of Ajax.
- * - Persist models to browser storage
+ * The error the default `sync` hands to `options.error`, and rejects with, for
+ * a response outside the 2xx range.
+ * @public
  */
+class HTTPError extends Error {
+    constructor(response, method, url) {
+        const statusText = response.statusText ? ` ${response.statusText}` : '';
+        super(`${method} ${url} failed with HTTP ${response.status}${statusText}`);
+        this.name = 'HTTPError';
+        this.status = response.status;
+        this.response = response;
+    }
+}
 /**
+ * The default `sync`: a JSON request over `fetch()` to the model's `url()`.
+ * Override it (or `Model.sync`/`Collection.sync`) to change how models are
+ * persisted, for instance to batch rapid-fire updates with `setTimeout`, to
+ * talk over WebSockets, or to write to browser storage.
+ *
+ * It honours both contracts a `sync` may use. On a 2xx response the JSON body
+ * (`null` when the body is empty) is passed to `options.success` and the
+ * returned promise resolves with it. On a non-2xx response, a network failure
+ * or an unparsable body, `options.error` receives the error (an `HTTPError`
+ * for the first) and the promise rejects with it.
+ *
+ * `options.data` is sent as query parameters on GET, which may not carry a
+ * body, and as a JSON body otherwise. For create, update and patch the body
+ * defaults to `options.attrs` or the model's `toJSON()`.
  * @public
  */
 function sync(method, model, options = {}) {
+    const type = methodMap[method];
     let data = options.data;
     // Ensure that we have the appropriate request data.
     if (data == null && model && (method === 'create' || method === 'update' || method === 'patch')) {
         data = options.attrs || model.toJSON();
     }
-    const type = methodMap[method];
-    const params = {
-        method: type,
-        body: data ? JSON.stringify(data) : '',
-        headers: {
-            'Content-Type': 'application/json',
-        },
-        success: options.success,
-        error: options.error,
-    };
-    const url = options.url || result(model, 'url') || urlError();
-    const xhr = fetch(url, params);
-    if (options) {
-        options.xhr = xhr;
+    let url = options.url || result(model, 'url') || urlError();
+    const params = { method: type };
+    if (data != null) {
+        if (type === 'GET') {
+            url += (url.includes('?') ? '&' : '?') + new URLSearchParams(data).toString();
+        }
+        else {
+            params.body = JSON.stringify(data);
+            params.headers = { 'Content-Type': 'application/json' };
+        }
     }
+    const xhr = fetch(url, params);
+    options.xhr = xhr;
     model.trigger('request', model, xhr, { ...params, xhr });
-    return xhr;
+    return Promise.resolve(xhr)
+        .then(async (response) => {
+        if (!response.ok)
+            throw new HTTPError(response, type, url);
+        const text = await response.text();
+        return text ? JSON.parse(text) : null;
+    })
+        .then(
+    // The callbacks run before the returned promise settles, so a caller that
+    // bridges this promise (`Model.fetch`/`save`) sees the outcome as already
+    // reported. A throw from `success` (a `'sync'` listener, say) is not
+    // routed to `error`: it rejects the promise, which is what the bridge
+    // expects once the callbacks have run.
+    (resp) => {
+        options.success?.(resp, options);
+        return resp;
+    }, (e) => {
+        options.error?.(e);
+        throw e;
+    });
 }
 
 /**
@@ -8020,7 +8123,7 @@ class PersistentStorage {
                 throw new Error("Skeletor.storage: the 'node' storage type is only available in Node.js builds. " +
                     "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) => this.store.setItems(items), 50, {
                     'promise': true,
@@ -8224,6 +8327,18 @@ class PersistentStorage {
 // node-only driver (and its `node:sqlite` import) never enters the browser
 // bundle; the `@converse/skeletor/node` entry sets it.
 PersistentStorage.nodeStorage = 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
+ */
+PersistentStorage.nodeStorageDir = null;
 PersistentStorage.sessionStorageInitialized = localForage.defineDriver(sessionStorageWrapper);
 PersistentStorage.localForage = localForage;
 
@@ -8231,6 +8346,7 @@ const DEFAULT_BASE_DIR = '.skeletor-storage';
 /**
  * SQLite-backed implementation of StorageDriver.
  * Uses a single table with key/value columns, storing values as JSON strings.
+ * @public
  */
 class NodeSQLiteStorage {
     ready() {
@@ -10102,6 +10218,48 @@ var keyBy = createAggregator(function(result, value, key) {
   baseAssignValue(result, key, value);
 });
 
+/** Used to compose bitmasks for cloning. */
+var CLONE_DEEP_FLAG$1 = 1;
+
+/**
+ * Creates a function that performs a partial deep comparison between a given
+ * object and `source`, returning `true` if the given object has equivalent
+ * property values, else `false`.
+ *
+ * **Note:** The created function is equivalent to `_.isMatch` with `source`
+ * partially applied.
+ *
+ * Partial comparisons will match empty array and empty object `source`
+ * values against any array or object value, respectively. See `_.isEqual`
+ * for a list of supported value comparisons.
+ *
+ * **Note:** Multiple values can be checked by combining several matchers
+ * using `_.overSome`
+ *
+ * @static
+ * @memberOf _
+ * @since 3.0.0
+ * @category Util
+ * @param {Object} source The object of property values to match.
+ * @returns {Function} Returns the new spec function.
+ * @example
+ *
+ * var objects = [
+ *   { 'a': 1, 'b': 2, 'c': 3 },
+ *   { 'a': 4, 'b': 5, 'c': 6 }
+ * ];
+ *
+ * _.filter(objects, _.matches({ 'a': 4, 'c': 6 }));
+ * // => [{ 'a': 4, 'b': 5, 'c': 6 }]
+ *
+ * // Checking for several possible values
+ * _.filter(objects, _.overSome([_.matches({ 'a': 1 }), _.matches({ 'a': 4 })]));
+ * // => [{ 'a': 1, 'b': 2, 'c': 3 }, { 'a': 4, 'b': 5, 'c': 6 }]
+ */
+function matches(source) {
+  return baseMatches(baseClone(source, CLONE_DEEP_FLAG$1));
+}
+
 /** Built-in value references. */
 var spreadableSymbol = Symbol$1 ? Symbol$1.isConcatSpreadable : undefined;
 
@@ -10665,53 +10823,36 @@ function isEqual(value, other) {
   return baseIsEqual(value, other);
 }
 
-/** Used to compose bitmasks for cloning. */
-var CLONE_DEEP_FLAG$1 = 1;
-
 /**
- * Creates a function that invokes `func` with the arguments of the created
- * function. If `func` is a property name, the created function returns the
- * property value for a given element. If `func` is an array or object, the
- * created function returns `true` for elements that contain the equivalent
- * source properties, otherwise it returns `false`.
+ * Performs a partial deep comparison between `object` and `source` to
+ * determine if `object` contains equivalent property values.
+ *
+ * **Note:** This method is equivalent to `_.matches` when `source` is
+ * partially applied.
+ *
+ * Partial comparisons will match empty array and empty object `source`
+ * values against any array or object value, respectively. See `_.isEqual`
+ * for a list of supported value comparisons.
  *
  * @static
- * @since 4.0.0
  * @memberOf _
- * @category Util
- * @param {*} [func=_.identity] The value to convert to a callback.
- * @returns {Function} Returns the callback.
+ * @since 3.0.0
+ * @category Lang
+ * @param {Object} object The object to inspect.
+ * @param {Object} source The object of property values to match.
+ * @returns {boolean} Returns `true` if `object` is a match, else `false`.
  * @example
  *
- * var users = [
- *   { 'user': 'barney', 'age': 36, 'active': true },
- *   { 'user': 'fred',   'age': 40, 'active': false }
- * ];
- *
- * // The `_.matches` iteratee shorthand.
- * _.filter(users, _.iteratee({ 'user': 'barney', 'active': true }));
- * // => [{ 'user': 'barney', 'age': 36, 'active': true }]
- *
- * // The `_.matchesProperty` iteratee shorthand.
- * _.filter(users, _.iteratee(['user', 'fred']));
- * // => [{ 'user': 'fred', 'age': 40 }]
+ * var object = { 'a': 1, 'b': 2 };
  *
- * // The `_.property` iteratee shorthand.
- * _.map(users, _.iteratee('user'));
- * // => ['barney', 'fred']
- *
- * // Create custom iteratee shorthands.
- * _.iteratee = _.wrap(_.iteratee, function(iteratee, func) {
- *   return !_.isRegExp(func) ? iteratee(func) : function(string) {
- *     return func.test(string);
- *   };
- * });
+ * _.isMatch(object, { 'b': 2 });
+ * // => true
  *
- * _.filter(['abc', 'def'], /ef/);
- * // => ['def']
+ * _.isMatch(object, { 'b': 1 });
+ * // => false
  */
-function iteratee(func) {
-  return baseIteratee(typeof func == 'function' ? func : baseClone(func, CLONE_DEEP_FLAG$1));
+function isMatch(object, source) {
+  return object === source || baseIsMatch(object, source, getMatchData(source));
 }
 
 /**
@@ -11225,10 +11366,20 @@ class Model extends EventEmitterObject {
         return this.get(attr) != null;
     }
     /**
-     * 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) {
-        return !!iteratee(attrs)(this.attributes);
+        if (typeof attrs === 'function')
+            return !!attrs(this.attributes);
+        return isMatch(this.attributes, attrs);
     }
     /**
      * Set a hash of model attributes on the object, firing `"change"`. This is
@@ -11401,47 +11552,25 @@ class Model extends EventEmitterObject {
         options = Object.assign({ parse: true }, options);
         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) => {
-            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 })))
+            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) => {
-                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;
     }
     /**
      * Set a hash of model attributes, and sync the model to the server.
@@ -11462,16 +11591,19 @@ class Model extends EventEmitterObject {
         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))
+        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;
-        }
-        else if (!this._validate(attrs || {}, options)) {
-            return false;
+            promise.reject(this.validationError);
+            return promise;
         }
         // After a successful server-side save, the client is (optionally)
         // updated with the server-side state.
@@ -11484,8 +11616,12 @@ class Model extends EventEmitterObject {
             let serverAttrs = options.parse ? this.parse(resp, options) : resp;
             if (wait)
                 serverAttrs = Object.assign({}, attrs, serverAttrs);
-            if (serverAttrs && !this.set(serverAttrs, options))
+            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);
@@ -11502,15 +11638,12 @@ class Model extends EventEmitterObject {
         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;
     }
     /**
      * Destroy this model on the server if it was already persisted.
@@ -11657,6 +11790,23 @@ var _Collection_instances, _Collection_hydrate, _a;
 // Default options for `Collection#set`.
 const setOptions = { add: true, remove: true, merge: true };
 const addOptions = { add: true, remove: false };
+/**
+ * Normalizes the predicate forms accepted by the query methods into one
+ * `(model) => value` function. A function is used as-is, a string reads that
+ * attribute, and an attributes object becomes a lodash `matches` matcher.
+ *
+ * The matcher is built here, once per scan. Calling `Model#matches` per model
+ * instead rebuilds the match data for every model visited, which made
+ * `findWhere` an order of magnitude slower than a hand-written predicate.
+ */
+function toModelPredicate(pred) {
+    if (isFunction(pred))
+        return pred;
+    if (isString(pred))
+        return (m) => m.get(pred);
+    const matcher = matches(pred);
+    return (m) => matcher(m.attributes);
+}
 /**
  * @public
  * If models tend to represent a single row of data, a Collection is
@@ -11985,17 +12135,13 @@ class Collection extends EventEmitterObject {
         return this.models.slice(start, end);
     }
     filter(callback, thisArg) {
-        return this.models.filter(isFunction(callback)
-            ? callback
-            : (m) => m.matches(callback), thisArg);
+        return this.models.filter(toModelPredicate(callback), thisArg);
     }
     every(pred) {
         if (isFunction(pred)) {
-            return this.models.map((m) => m.attributes).every(pred);
-        }
-        else {
-            return this.models.every((m) => m.matches(pred));
+            return this.models.every((m) => pred(m.attributes));
         }
+        return this.models.every(toModelPredicate(pred));
     }
     difference(values) {
         return this.models.filter((m) => !values.includes(m));
@@ -12011,16 +12157,12 @@ class Collection extends EventEmitterObject {
     }
     some(pred) {
         if (isFunction(pred)) {
-            return this.models.map((m) => m.attributes).some(pred);
-        }
-        else {
-            return this.models.some((m) => m.matches(pred));
+            return this.models.some((m) => pred(m.attributes));
         }
+        return this.models.some(toModelPredicate(pred));
     }
     sortBy(iteratee) {
-        return sortBy(this.models, isFunction(iteratee)
-            ? iteratee
-            : (m) => (isString(iteratee) ? m.get(iteratee) : m.matches(iteratee)));
+        return sortBy(this.models, toModelPredicate(iteratee));
     }
     isEmpty() {
         return !this.models.length;
@@ -12041,26 +12183,22 @@ class Collection extends EventEmitterObject {
         return this.models.length;
     }
     countBy(f) {
-        return countBy(this.models, isFunction(f) ? f : (m) => (isString(f) ? m.get(f) : m.matches(f)));
+        return countBy(this.models, toModelPredicate(f));
     }
     groupBy(pred) {
-        return groupBy(this.models, isFunction(pred) ? pred : (m) => (isString(pred) ? m.get(pred) : m.matches(pred)));
+        return groupBy(this.models, toModelPredicate(pred));
     }
     indexOf(model, fromIndex) {
         return this.models.indexOf(model, fromIndex);
     }
     findLastIndex(pred, fromIndex) {
-        return this.models.findLastIndex(isFunction(pred)
-            ? pred
-            : (m) => (isString(pred) ? m.get(pred) : m.matches(pred)), fromIndex);
+        return this.models.findLastIndex(toModelPredicate(pred), fromIndex);
     }
     lastIndexOf(model, fromIndex) {
         return this.models.lastIndexOf(model, fromIndex);
     }
     findIndex(pred) {
-        return this.models.findIndex(isFunction(pred)
-            ? pred
-            : (m) => (isString(pred) ? m.get(pred) : m.matches(pred)));
+        return this.models.findIndex(toModelPredicate(pred));
     }
     last() {
         const length = this.models == null ? 0 : this.models.length;
@@ -12073,9 +12211,7 @@ class Collection extends EventEmitterObject {
         return this.head();
     }
     map(cb, thisArg) {
-        return this.models.map(isFunction(cb)
-            ? cb
-            : (m) => (isString(cb) ? m.get(cb) : m.matches(cb)), thisArg);
+        return this.models.map(toModelPredicate(cb), thisArg);
     }
     reduce(callback, initialValue) {
         return this.models.reduce(callback, initialValue || this.models[0]);
@@ -12126,10 +12262,7 @@ class Collection extends EventEmitterObject {
         return this.where(attrs, true);
     }
     find(predicate, fromIndex) {
-        const pred = isFunction(predicate)
-            ? predicate
-            : (m) => m.matches(predicate);
-        return this.models.find(pred, fromIndex);
+        return this.models.find(toModelPredicate(predicate), fromIndex);
     }
     /**
      * Force the collection to re-sort itself. You don't need to call this under
@@ -12172,46 +12305,22 @@ class Collection extends EventEmitterObject {
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         const collection = this;
         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) {
-            settled = true;
             const method = options.reset ? 'reset' : 'set';
             // 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();
+            // Fire 'sync' before resolving, as `Model.fetch`/`save` do, so a throwing
+            // listener rejects the promise instead of being lost.
             collection.trigger('sync', collection, resp, options);
+            promise && promise.resolve();
         };
         wrapError(this, options, promise);
-        if (promise) {
-            const onError = options.error;
-            options.error = (resp) => {
-                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;
+        // 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;
     }
     /**
      * Create a new instance of a model in this collection. Add the model to the
@@ -12223,9 +12332,22 @@ class Collection extends EventEmitterObject {
         const wait = options.wait;
         const return_promise = options.promise;
         const promise = return_promise && getResolveablePromise();
+        // `_prepareModel` reports attributes that fail validation by firing
+        // `'invalid'` and returning null. With `promise`, capture that error so a
+        // rejected promise is handed back rather than `null`.
+        let validationError;
+        const captureInvalid = (_c, err) => (validationError = err);
+        if (return_promise)
+            this.on('invalid', captureInvalid);
         const preparedModel = this._prepareModel(model, options);
-        if (!preparedModel)
-            return null;
+        if (return_promise)
+            this.off('invalid', captureInvalid);
+        if (!preparedModel) {
+            if (!return_promise)
+                return null;
+            promise.reject(validationError);
+            return promise;
+        }
         if (!wait)
             this.add(preparedModel, options);
         // eslint-disable-next-line @typescript-eslint/no-this-alias
@@ -12247,8 +12369,15 @@ class Collection extends EventEmitterObject {
             error && error.call(options.context, model, e, options);
             return_promise && promise.reject(e);
         };
-        preparedModel.save(null, Object.assign(options, { 'promise': false }));
+        // `options.promise` is passed through, so `save` installs its own bridge
+        // from the sync's returned promise to its callbacks: a sync that resolves
+        // without calling them still reaches the wired `options.success` above,
+        // which resolves our promise with the model. Only a rejection that bypassed
+        // the callbacks (a rejecting sync, or a throwing `'sync'`/`'error'`
+        // listener) still needs bridging to ours.
+        const result = preparedModel.save(null, options);
         if (return_promise) {
+            Promise.resolve(result).catch((e) => promise.reject(e));
             return promise;
         }
         else {
@@ -12474,6 +12603,7 @@ const skeletor = {
     EventEmitter,
     Model,
     sync,
+    HTTPError,
 };
 // Establish the root object, `window` (`self`) in the browser, or `global` on the server.
 // We use `self` instead of `window` for `WebWorker` support.
@@ -12511,5 +12641,5 @@ const BrowserStorage = PersistentStorage;
 // their bundles entirely.
 PersistentStorage.nodeStorage = NodeSQLiteStorage;
 
-export { BrowserStorage, Collection, EventEmitter, Model, NodeSQLiteStorage, PersistentStorage, skeletor as default, getStorage, noConflict, sync };
+export { BrowserStorage, Collection, EventEmitter, HTTPError, Model, NodeSQLiteStorage, PersistentStorage, skeletor as default, getStorage, noConflict, sync };
 //# sourceMappingURL=skeletor.node.mjs.map