@converse/skeletor 3.1.5 → 4.0.0

package/CHANGES.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 4.0.0 (2026-10-24)
+
+- Attribute-object queries on a collection (`findWhere`, `where`, and `find`, `filter`, `some`,
+  `every`, `map`, `sortBy`, `countBy`, `groupBy`, `findIndex` and `findLastIndex` when given an
+  object) now build their lodash matcher once per scan instead of once per model visited. Each
+  per-model build deep-cloned the attributes object and walked its keys, which made `findWhere`
+  roughly 8 to 13 times slower than `find` with a hand-written predicate on a few thousand models.
+  Matching semantics are unchanged: still lodash's partial, deep comparison, so nested lookups
+  such as `where({ FORM_TYPE: { type: 'hidden' } })` keep working. One alignment: `find` and
+  `filter` given a string now read that attribute through `Model.get`, like the other query
+  methods already did, instead of resolving it as a lodash property path over the raw attributes.
+
+- `Model.matches` no longer deep-clones its argument on every call (it uses lodash's `isMatch`)
+  and its signature now admits the predicate function it has always accepted at runtime. The
+  undocumented lodash string and `[key, value]` shorthand forms are no longer supported.
+
+- Fix `Model.save({ promise: true })` hanging forever, and leaking an unhandled rejection, when
+  its `sync` settles the returned promise instead of invoking the `success`/`error` callbacks
+  (a rejecting custom `sync`, or a throwing `'sync'`/`'error'` listener). `save` now bridges that
+  promise to the one it hands back, the way `fetch` already did. `Collection.create({ promise: true })`,
+  which delegates to `save`, is fixed the same way.
+
+- Fix `fetch({ promise: true })` on a Model or Collection settling early when a callback-style `sync`
+  returns a non-thenable (nothing, or an XHR) and invokes `success`/`error` later. The bridge from the
+  `sync` return value to the returned promise now only engages for a thenable, so such a `sync` settles
+  the promise through its callbacks. The same guard applies to `save({ promise: true })`.
+
+- The `{ promise: true }` paths of `fetch` and `save` now share one bridge from the `sync` outcome
+  to the returned promise, with two behaviour changes: a `sync` that rejects its promise without
+  calling the callbacks now also runs the `error` callback and fires the `'error'` event, and a
+  `'sync'`/`'error'` listener (or `success`/`error` callback) that throws now rejects the promise
+  instead of leaving it pending with an unhandled rejection. `Collection.fetch` fires `'sync'` before
+  resolving, as `Model.fetch`/`save` already did, so a throwing listener rejects there too.
+
+- Fix `save({ promise: true })` and `fetch({ promise: true, validate: true })` leaving the promise
+  pending when the attributes returned by `sync` fail validation. The promise now rejects with
+  `validationError`; the `'invalid'` event fires as before.
+
+- `save({ promise: true })` now returns a promise rejected with `validationError`, instead of `false`,
+  when the attributes passed to it fail validation; `create({ promise: true })` likewise returns a
+  rejected promise instead of `null`. The callback forms still return `false`/`null`.
+
+- The default HTTP `sync` now honours both the callback and the promise contracts. It never invoked
+  `success`/`error` (it passed them to `fetch()` as init options, which ignores them), sent an empty
+  body on GET (which the Fetch API rejects outright), and resolved with the raw `Response`, which the
+  promise bridge then merged into the model as attributes. It now sends `data` as query parameters on
+  GET and as a JSON body otherwise, passes a parsed 2xx JSON body (`null` when empty) to `success` and
+  resolves with it, and on a non-2xx response or a network failure calls `error` with, and rejects
+  with, the error: an `HTTPError` (new export, carrying `status` and `response`) for the former.
+
+## 3.1.6 (2026-08-06)
+
+- The `'node'` store type can now be told where to put its database files, via the new
+  `PersistentStorage.nodeStorageDir`. The driver has always taken a `storageDir` argument,
+  but nothing could reach it through the string store type, so `new PersistentStorage(id, 'node')`
+  was stuck with the driver's default. That default is relative, so it resolves against
+  `process.cwd()` and an app started from two directories keeps two separate sets of state.
+  Set an absolute path (`$XDG_STATE_HOME/<app>`, say) to pin it. The default is unchanged.
+
+- Ship a separate `dist/skeletor.node.d.ts` for the `@converse/skeletor/node` entry point.
+  Both entry points pointed their `types` at the browser rollup.
+
 ## 3.1.5 (2026-07-22)
 
 - Fix every write through the Node.js SQLite driver failing with `Record Not Found` while

package/dist/skeletor.d.ts

@@ -136,7 +136,7 @@ export declare class Collection<T extends Model = Model> extends EventEmitterObj
     min(): number;
     drop(n?: number): T[];
     some(pred: ((attrs: ModelAttributes) => boolean) | Options): boolean;
-    sortBy(iteratee: string | ((model: T) => any)): T[];
+    sortBy(iteratee: string | ((model: T) => any) | Partial<ModelAttributes>): T[];
     isEmpty(): boolean;
     keyBy(iteratee: string | ((model: T) => string)): Record<string, T>;
     each(callback: (model: T, index: number, array: T[]) => void, thisArg?: any): void;
@@ -144,7 +144,7 @@ export declare class Collection<T extends Model = Model> extends EventEmitterObj
     includes(item: T): boolean;
     size(): number;
     countBy(f: string | ((model: T) => string) | Partial<ModelAttributes>): Record<string, number>;
-    groupBy(pred: string | ((model: T) => string | number)): Record<string, T[]>;
+    groupBy(pred: string | ((model: T) => string | number) | Partial<ModelAttributes>): Record<string, T[]>;
     indexOf(model: T, fromIndex?: number): number;
     findLastIndex(pred: ((model: T) => boolean) | string | Partial<ModelAttributes>, fromIndex?: number): number;
     lastIndexOf(model: T, fromIndex?: number): number;
@@ -487,6 +487,17 @@ export declare type FetchOrCreateOptions = Options & {
  */
 export declare function getStorage(obj: Model<any> | Collection<any> | null | undefined): PersistentStorage | undefined;
 
+/**
+ * The error the default `sync` hands to `options.error`, and rejects with, for
+ * a response outside the 2xx range.
+ * @public
+ */
+export declare class HTTPError extends Error {
+    readonly status: number;
+    readonly response: Response;
+    constructor(response: Response, method: string, url: string);
+}
+
 /**
  * @public
  */
@@ -634,9 +645,17 @@ export declare class Model<T extends ModelAttributes = ModelAttributes> extends
      */
     has(attr: keyof T): boolean;
     /**
-     * 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;
+    matches(attrs: Partial<T> | ((attrs: T) => any)): boolean;
     /**
      * Set a hash of model attributes on the object, firing `"change"`. This is
      * the core primitive operation of a model, updating the data and notifying
@@ -762,8 +781,9 @@ export declare function noConflict(): any;
 /**
  * Constructor for a Node.js-only storage driver. Registered by the
  * `@converse/skeletor/node` entry point via {@link PersistentStorage.nodeStorage}.
+ * @public
  */
-declare type NodeStorageConstructor = new (name: string) => StorageDriver;
+export declare type NodeStorageConstructor = new (name: string, storageDir?: string, inMemory?: boolean) => StorageDriver;
 
 /**
  * @public
@@ -795,6 +815,18 @@ export declare class PersistentStorage {
     static sessionStorageInitialized: Promise<void>;
     static localForage: typeof localForage;
     static nodeStorage: NodeStorageConstructor | 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;
     /** Register a storage instance with a weak reference. @public */
     static register(instance: PersistentStorage): void;
     /**
@@ -843,6 +875,7 @@ export declare interface SkeletorType {
     EventEmitter: typeof EventEmitter;
     Model: typeof Model;
     sync: typeof sync;
+    HTTPError: typeof HTTPError;
     VERSION?: string;
     noConflict?: () => SkeletorType;
 }
@@ -880,18 +913,20 @@ export declare interface StorageDriver {
 export declare type StoreType = 'local' | 'session' | 'indexed' | 'in_memory' | 'node';
 
 /**
- * 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()`.
+ * 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.
  *
- * Some possible customizations could be:
+ * 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.
  *
- * - Use `setTimeout` to batch rapid-fire updates into a single request.
- * - Persist models via WebSockets instead of Ajax.
- * - Persist models to browser storage
- */
-/**
+ * `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 declare function sync(method: SyncOperation, model: Model | Collection<any>, options?: SyncOptions): Promise<any>;