@converse/skeletor 3.1.5 → 4.0.0

package/dist/skeletor.js

@@ -8477,6 +8477,16 @@
       // 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,
@@ -8521,6 +8531,65 @@
           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',
@@ -8570,43 +8639,77 @@
       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;
+      });
   }
 
   /**
@@ -8705,7 +8808,7 @@
                   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,
@@ -8909,6 +9012,18 @@
   // 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;
 
@@ -9960,6 +10075,48 @@
     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;
 
@@ -10523,53 +10680,36 @@
     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));
   }
 
   /**
@@ -11083,10 +11223,20 @@
           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
@@ -11259,47 +11409,25 @@
           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.
@@ -11320,16 +11448,19 @@
           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.
@@ -11342,8 +11473,12 @@
               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);
@@ -11360,15 +11495,12 @@
           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.
@@ -11515,6 +11647,23 @@
   // 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
@@ -11843,17 +11992,13 @@
           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));
@@ -11869,16 +12014,12 @@
       }
       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;
@@ -11899,26 +12040,22 @@
           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;
@@ -11931,9 +12068,7 @@
           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]);
@@ -11984,10 +12119,7 @@
           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
@@ -12030,46 +12162,22 @@
           // 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
@@ -12081,9 +12189,22 @@
           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
@@ -12105,8 +12226,15 @@
               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 {
@@ -12332,6 +12460,7 @@
       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.
@@ -12362,6 +12491,7 @@
   exports.BrowserStorage = BrowserStorage;
   exports.Collection = Collection;
   exports.EventEmitter = EventEmitter;
+  exports.HTTPError = HTTPError;
   exports.Model = Model;
   exports.PersistentStorage = PersistentStorage;
   exports.default = skeletor;