@converse/skeletor 3.1.6 → 4.0.0

package/dist/skeletor.node.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
@@ -881,6 +900,7 @@ export declare interface SkeletorType {
     EventEmitter: typeof EventEmitter;
     Model: typeof Model;
     sync: typeof sync;
+    HTTPError: typeof HTTPError;
     VERSION?: string;
     noConflict?: () => SkeletorType;
 }
@@ -918,18 +938,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>;