@converse/skeletor 3.1.5 → 4.0.0

package/package.json

@@ -9,18 +9,19 @@
   "browser": "dist/skeletor.js",
   "exports": {
     ".": {
-      "types": "./dist/skeletor.d.ts",
       "node": {
+        "types": "./dist/skeletor.node.d.ts",
         "require": "./dist/skeletor.node.js",
         "import": "./dist/skeletor.node.mjs"
       },
       "default": {
+        "types": "./dist/skeletor.d.ts",
         "import": "./dist/skeletor.esm.js",
         "require": "./dist/skeletor.js"
       }
     },
     "./node": {
-      "types": "./dist/skeletor.d.ts",
+      "types": "./dist/skeletor.node.d.ts",
       "require": "./dist/skeletor.node.js",
       "import": "./dist/skeletor.node.mjs"
     }
@@ -38,7 +39,7 @@
   "contributors": [
     "JC Brand"
   ],
-  "version": "3.1.5",
+  "version": "4.0.0",
   "engines": {
     "node": ">=22.0.0"
   },
@@ -49,7 +50,7 @@
   },
   "scripts": {
     "build": "npm run prebuild && npm run build:declarations && rollup -c",
-    "build:declarations": "npm run build:types && api-extractor run --local && rm -rf dist/defs",
+    "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",
     "check": "npm run check:types && npm run test && npm run test:node && npm run lint",
     "check:types": "tsc --noEmit",
@@ -74,6 +75,7 @@
     "dist/skeletor.node.mjs",
     "dist/skeletor.d.ts",
     "dist/skeletor.d.ts.map",
+    "dist/skeletor.node.d.ts",
     "src/**/*.ts"
   ],
   "dependencies": {

package/src/collection.ts

@@ -4,10 +4,18 @@ import groupBy from 'lodash-es/groupBy';
 import isFunction from 'lodash-es/isFunction';
 import isString from 'lodash-es/isString';
 import keyBy from 'lodash-es/keyBy';
+import matches from 'lodash-es/matches';
 import sortBy from 'lodash-es/sortBy';
 import { EventEmitterObject } from './eventemitter';
 import PersistentStorage from './storage';
-import { getResolveablePromise, getStorage, getSyncMethod, warnBrowserStorageDeprecation, wrapError } from './helpers';
+import {
+  bridgeSyncToPromise,
+  getResolveablePromise,
+  getStorage,
+  getSyncMethod,
+  warnBrowserStorageDeprecation,
+  wrapError,
+} from './helpers';
 import { ensureUnloadListener } from './autosync';
 import { Model } from './model';
 import {
@@ -26,6 +34,24 @@ import {
 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<T extends Model>(
+  pred: ((model: T) => any) | string | Partial<ModelAttributes>,
+): (model: T) => any {
+  if (isFunction(pred)) return pred as (model: T) => any;
+  if (isString(pred)) return (m: T) => m.get(pred);
+  const matcher = matches(pred);
+  return (m: T) => matcher(m.attributes);
+}
+
 /**
  * @public
  * If models tend to represent a single row of data, a Collection is
@@ -394,20 +420,14 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
   }
 
   filter(callback: ((model: T) => boolean) | string | Partial<ModelAttributes>, thisArg?: any): T[] {
-    return this.models.filter(
-      isFunction(callback)
-        ? (callback as (model: T) => boolean)
-        : (m) => m.matches(callback as Partial<ModelAttributes>),
-      thisArg,
-    );
+    return this.models.filter(toModelPredicate(callback), thisArg);
   }
 
   every(pred: ((attrs: ModelAttributes) => boolean) | Options): boolean {
     if (isFunction(pred)) {
-      return this.models.map((m) => m.attributes).every(pred as (attrs: ModelAttributes) => boolean);
-    } else {
-      return this.models.every((m) => m.matches(pred));
+      return this.models.every((m) => (pred as (attrs: ModelAttributes) => boolean)(m.attributes));
     }
+    return this.models.every(toModelPredicate(pred));
   }
 
   difference(values: T[]): T[] {
@@ -428,19 +448,13 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
 
   some(pred: ((attrs: ModelAttributes) => boolean) | Options): boolean {
     if (isFunction(pred)) {
-      return this.models.map((m) => m.attributes).some(pred as (attrs: ModelAttributes) => boolean);
-    } else {
-      return this.models.some((m) => m.matches(pred));
+      return this.models.some((m) => (pred as (attrs: ModelAttributes) => boolean)(m.attributes));
     }
+    return this.models.some(toModelPredicate(pred));
   }
 
-  sortBy(iteratee: string | ((model: T) => any)): T[] {
-    return sortBy(
-      this.models,
-      isFunction(iteratee)
-        ? iteratee
-        : (m: T) => (isString(iteratee) ? m.get(iteratee as string) : m.matches(iteratee as Partial<ModelAttributes>)),
-    );
+  sortBy(iteratee: string | ((model: T) => any) | Partial<ModelAttributes>): T[] {
+    return sortBy(this.models, toModelPredicate(iteratee));
   }
 
   isEmpty(): boolean {
@@ -468,11 +482,11 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
   }
 
   countBy(f: string | ((model: T) => string) | Partial<ModelAttributes>): Record<string, number> {
-    return countBy(this.models, isFunction(f) ? f : (m) => (isString(f) ? m.get(f) : m.matches(f)));
+    return countBy(this.models, toModelPredicate(f));
   }
 
-  groupBy(pred: string | ((model: T) => string | number)): Record<string, T[]> {
-    return groupBy(this.models, isFunction(pred) ? pred : (m) => (isString(pred) ? m.get(pred) : m.matches(pred)));
+  groupBy(pred: string | ((model: T) => string | number) | Partial<ModelAttributes>): Record<string, T[]> {
+    return groupBy(this.models, toModelPredicate(pred));
   }
 
   indexOf(model: T, fromIndex?: number): number {
@@ -480,12 +494,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
   }
 
   findLastIndex(pred: ((model: T) => boolean) | string | Partial<ModelAttributes>, fromIndex?: number): number {
-    return this.models.findLastIndex(
-      isFunction(pred)
-        ? (pred as (model: T) => boolean)
-        : (m) => (isString(pred) ? m.get(pred as string) : m.matches(pred as Partial<ModelAttributes>)),
-      fromIndex,
-    );
+    return this.models.findLastIndex(toModelPredicate(pred), fromIndex);
   }
 
   lastIndexOf(model: T, fromIndex?: number): number {
@@ -493,11 +502,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
   }
 
   findIndex(pred: ((model: T) => boolean) | string | Partial<ModelAttributes>): number {
-    return this.models.findIndex(
-      isFunction(pred)
-        ? (pred as (model: T) => boolean)
-        : (m) => (isString(pred) ? m.get(pred as string) : m.matches(pred as Partial<ModelAttributes>)),
-    );
+    return this.models.findIndex(toModelPredicate(pred));
   }
 
   last(): T | undefined {
@@ -514,12 +519,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
   }
 
   map<U>(cb: string | ((model: T) => U) | Partial<ModelAttributes>, thisArg?: any): U[] {
-    return this.models.map(
-      isFunction(cb)
-        ? (cb as (model: T) => U)
-        : (m) => (isString(cb) ? m.get(cb as string) : m.matches(cb as Partial<ModelAttributes>)),
-      thisArg,
-    );
+    return this.models.map(toModelPredicate(cb), thisArg);
   }
 
   reduce<U = T>(callback: (accumulator: U, model: T, index: number, array: T[]) => U, initialValue?: U): U | T {
@@ -579,10 +579,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
   }
 
   find(predicate: ((model: T) => boolean) | Partial<ModelAttributes> | string, fromIndex?: number): T | undefined {
-    const pred = isFunction(predicate)
-      ? (predicate as (model: T) => boolean)
-      : (m: T) => m.matches(predicate as Partial<ModelAttributes>);
-    return this.models.find(pred, fromIndex);
+    return this.models.find(toModelPredicate(predicate), fromIndex);
   }
 
   /**
@@ -627,47 +624,22 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     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: any) {
-      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: 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 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;
   }
 
   /**
@@ -681,8 +653,19 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     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: any;
+    const captureInvalid = (_c: unknown, err: any) => (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);
 
@@ -706,8 +689,15 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
       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 {
       return preparedModel;

package/src/drivers/nodeSQLiteStorage.ts

@@ -9,6 +9,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
  */
 export class NodeSQLiteStorage implements StorageDriver {
   private db: DatabaseSync;

package/src/helpers.ts

@@ -28,6 +28,15 @@ export function guid(): string {
 // 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.
+ */
+export function isThenable(value: any): value is PromiseLike<any> {
+  return value != null && typeof value.then === 'function';
+}
+
 // Helper function to correctly set up the prototype chain for subclasses.
 // Similar to `goog.inherits`, but uses a hash of prototype properties and
 // class properties to be extended.
@@ -131,6 +140,68 @@ export function wrapError(
   };
 }
 
+/**
+ * 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.
+ */
+export function bridgeSyncToPromise(options: any, promise: ResolveablePromise | undefined, run: () => any): any {
+  if (!promise) return run();
+
+  let settled = false;
+  const success = options.success;
+  const error = options.error;
+  options.success = (...args: any[]) => {
+    settled = true;
+    return success && success(...args);
+  };
+  options.error = (...args: any[]) => {
+    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: Record<string, string> = {
   create: 'POST',
@@ -183,21 +254,42 @@ export function getSyncMethod(model: Model | Collection<any>): typeof 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
  */
+export class HTTPError extends Error {
+  readonly status: number;
+  readonly response: Response;
+
+  constructor(response: Response, method: string, url: string) {
+    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
  */
 export function sync(method: SyncOperation, model: Model | Collection<any>, options: SyncOptions = {}): Promise<any> {
+  const type = methodMap[method];
   let data = options.data;
 
   // Ensure that we have the appropriate request data.
@@ -205,22 +297,40 @@ export function sync(method: SyncOperation, model: Model | Collection<any>, opti
     data = options.attrs || model.toJSON();
   }
 
-  const type = methodMap[method];
-  const params: RequestInit & { success?: any; error?: any } = {
-    method: type,
-    body: data ? JSON.stringify(data) : '',
-    headers: {
-      'Content-Type': 'application/json',
-    },
-    success: options.success,
-    error: options.error,
-  };
+  let url: string = options.url || result(model, 'url') || urlError();
+  const params: RequestInit = { 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 url = options.url || result(model, 'url') || urlError();
   const xhr = fetch(url, params);
-  if (options) {
-    options.xhr = xhr;
-  }
+  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;
+      },
+    );
 }

package/src/index.ts

@@ -3,7 +3,7 @@ import { EventEmitter } from './eventemitter';
 import PersistentStorage from './storage';
 import { Collection } from './collection';
 import { Model } from './model';
-import { sync } from './helpers';
+import { sync, HTTPError } from './helpers';
 
 /**
  * @public
@@ -13,6 +13,7 @@ interface SkeletorType {
   EventEmitter: typeof EventEmitter;
   Model: typeof Model;
   sync: typeof sync;
+  HTTPError: typeof HTTPError;
   VERSION?: string;
   noConflict?: () => SkeletorType;
 }
@@ -25,6 +26,7 @@ const skeletor: SkeletorType = {
   EventEmitter,
   Model,
   sync,
+  HTTPError,
 };
 
 // Establish the root object, `window` (`self`) in the browser, or `global` on the server.
@@ -59,10 +61,11 @@ export default skeletor;
  * @public
  */
 const BrowserStorage = PersistentStorage;
-export { noConflict, Collection, EventEmitter, Model, PersistentStorage, BrowserStorage, sync };
+export { noConflict, Collection, EventEmitter, Model, PersistentStorage, BrowserStorage, sync, HTTPError };
 export { getStorage } from './helpers';
 
 export type { StorageDriver, StoreType } from './drivers/types';
+export type { NodeStorageConstructor } from './storage';
 export type {
   ClassConstructor,
   CollectionOptions,