@converse/skeletor 0.0.9 → 2.0.0

package/src/{model.js → model.ts}

@@ -1,81 +1,76 @@
-import { getResolveablePromise, getSyncMethod, urlError, wrapError } from './helpers.js';
-import clone from 'lodash-es/clone.js';
-import defaults from 'lodash-es/defaults.js';
-import defer from 'lodash-es/defer.js';
-import has from 'lodash-es/has.js';
-import invert from 'lodash-es/invert.js';
-import isEmpty from 'lodash-es/isEmpty.js';
-import isEqual from 'lodash-es/isEqual.js';
-import iteratee from 'lodash-es/iteratee.js';
-import omit from 'lodash-es/omit.js';
-import pick from 'lodash-es/pick.js';
-import result from 'lodash-es/result.js';
-import uniqueId from 'lodash-es/uniqueId.js';
-import EventEmitter from './eventemitter.js';
-
-/**
- * @typedef {import('./collection.js').Collection} Collection
- * @typedef {Record.<string, any>} Attributes
- *
- * @typedef {Record.<string, any>} Options
- * @property {boolean} [validate]
- *
- * @typedef {Record.<string, any>} ModelOptions
- * @property {Collection} [collection]
- * @property {boolean} [parse]
- * @property {boolean} [unset]
- * @property {boolean} [silent]
- */
+import { getResolveablePromise, getSyncMethod, urlError, wrapError } from './helpers';
+import clone from 'lodash-es/clone';
+import defaults from 'lodash-es/defaults';
+import defer from 'lodash-es/defer';
+import has from 'lodash-es/has';
+import invert from 'lodash-es/invert';
+import isEmpty from 'lodash-es/isEmpty';
+import isEqual from 'lodash-es/isEqual';
+import iteratee from 'lodash-es/iteratee';
+import omit from 'lodash-es/omit';
+import pick from 'lodash-es/pick';
+import result from 'lodash-es/result';
+import uniqueId from 'lodash-es/uniqueId';
+import { EventEmitterObject } from './eventemitter';
+
+// Import types
+import type { Collection } from './collection';
+import type Storage from './storage';
+import { ModelAttributes, ObjectWithId, SyncOperation, ModelOptions, Options } from './types';
 
 /**
+ * @public
  * **Models** are the basic data object in the framework --
  * frequently representing a row in a table in a database on your server.
  * A discrete chunk of data and a bunch of useful, related methods for
  * performing computations and transformations on that data.
  */
-class Model extends EventEmitter(Object) {
+export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmitterObject {
+  _browserStorage?: Storage;
+  _changing = false;
+  _pending: boolean | ModelOptions = false;
+  _previousAttributes?: T;
+  _url: string = '';
+  _urlRoot: string;
+  attributes: T;
+  changed: Partial<T> = {};
+  cid: string;
+  collection?: Collection;
+  id: string | number;
+  validationError: string | number | null = null;
+
   /**
    * Create a new model with the specified attributes. A client id (`cid`)
    * is automatically generated and assigned for you.
-   * @param {Attributes} [attributes]
-   * @param {ModelOptions} [options]
    */
-  constructor(attributes, options) {
+  constructor(attributes?: Partial<T>, options?: ModelOptions) {
     super();
-    let attrs = attributes || {};
-    options || (options = {});
-    this.preinitialize.apply(this, arguments);
-    this.cid = uniqueId(this.cidPrefix);
-    this.attributes = {};
+    let attrs: Partial<T> = attributes || ({} as Partial<T>);
+    options = options || {};
 
-    // The value returned during the last failed validation.
-    this.validationError = null;
+    this.preinitialize.apply(this, arguments as any);
+    this.cid = uniqueId(this.cidPrefix);
+    this.attributes = {} as T;
 
     if (options.collection) this.collection = options.collection;
-    if (options.parse) attrs = this.parse(attrs, options) || {};
+    if (options.parse) attrs = this.parse(attrs, options) || ({} as Partial<T>);
 
     const default_attrs = result(this, 'defaults');
     attrs = defaults(Object.assign({}, default_attrs, attrs), default_attrs);
 
     this.set(attrs, options);
 
-    this.initialize.apply(this, arguments);
+    this.initialize.apply(this, arguments as any);
 
-    // A hash of attributes whose current and previous value differ.
+    // Reset changed after initial set
     this.changed = {};
   }
 
-  /**
-   * @param {Storage} storage
-   */
-  set browserStorage(storage) {
+  set browserStorage(storage: Storage) {
     this._browserStorage = storage;
   }
 
-  /**
-   * @returns {Storage} storage
-   */
-  get browserStorage() {
+  get browserStorage(): Storage | undefined {
     return this._browserStorage;
   }
 
@@ -84,8 +79,7 @@ class Model extends EventEmitter(Object) {
    * CouchDB users may want to set this to `"_id"` (by overriding this getter
    * in a subclass).
    */
-  // eslint-disable-next-line class-methods-use-this
-  get idAttribute() {
+  get idAttribute(): string {
     return 'id';
   }
 
@@ -93,8 +87,7 @@ class Model extends EventEmitter(Object) {
    * The prefix is used to create the client id which is used to identify models locally.
    * You may want to override this if you're experiencing name clashes with model ids.
    */
-  // eslint-disable-next-line class-methods-use-this
-  get cidPrefix() {
+  get cidPrefix(): string {
     return 'c';
   }
 
@@ -102,131 +95,121 @@ class Model extends EventEmitter(Object) {
    * preinitialize is an empty function by default. You can override it with a function
    * or object.  preinitialize will run before any instantiation logic is run in the Model.
    */
-  // eslint-disable-next-line class-methods-use-this
-  preinitialize() {}
+  preinitialize(...args: any[]): void {}
 
   /**
    * Initialize is an empty function by default. Override it with your own
    * initialization logic.
-   * @param {Attributes} [attrs]
-   * @param {ModelOptions} [options]
    */
-  initialize(attrs, options) {}
+  initialize(attrs?: Partial<T>, options?: ModelOptions): void {}
+
+  validate(attrs: Partial<T> | ObjectWithId, options?: ModelOptions): string | number | null | void {
+    return null;
+  }
 
   /**
-   * @param {object} attrs
-   * @param {object} [options]
-   * @returns {string} The validation error message
+   * Return a hash of defaults for the model's attributes.
    */
-  validate(attrs, options) {
-    return '';
+  defaults(): Partial<T> {
+    return {} as Partial<T>;
   }
 
   /**
    * Return a copy of the model's `attributes` object.
    */
-  toJSON() {
+  toJSON(): T {
     return clone(this.attributes);
   }
 
   /**
    * Override this if you need custom syncing semantics for *this* particular model.
-   * @param {'create'|'update'|'patch'|'delete'|'read'} method
-   * @param {Model} model
-   * @param {Options} options
    */
-  // eslint-disable-next-line class-methods-use-this
-  sync(method, model, options) {
+  sync(method: SyncOperation, model: Model<any>, options: Options): any {
     return getSyncMethod(model)(method, model, options);
   }
 
   /**
    * Get the value of an attribute.
-   * @param {string} attr
    */
-  get(attr) {
+  get<K extends keyof T>(attr: K): T[K] {
     return this.attributes[attr];
   }
 
-  keys() {
+  keys(): string[] {
     return Object.keys(this.attributes);
   }
 
-  values() {
+  values(): T[keyof T][] {
     return Object.values(this.attributes);
   }
 
-  pairs() {
+  pairs(): [keyof T, T[keyof T]][] {
     return this.entries();
   }
 
-  entries() {
-    return Object.entries(this.attributes);
+  entries(): [keyof T, T[keyof T]][] {
+    return Object.entries(this.attributes) as [keyof T, T[keyof T]][];
   }
 
-  invert() {
+  invert(): Record<string, keyof T> {
     return invert(this.attributes);
   }
 
-  pick(...args) {
+  pick<K extends keyof T>(...args: K[]): Pick<T, K> {
     if (args.length === 1 && Array.isArray(args[0])) {
-      args = args[0];
+      args = args[0] as K[];
     }
-    return pick(this.attributes, args);
+    return pick(this.attributes, args) as Pick<T, K>;
   }
 
-  omit(...args) {
+  omit<K extends keyof T>(...args: K[]): Omit<T, K> {
     if (args.length === 1 && Array.isArray(args[0])) {
-      args = args[0];
+      args = args[0] as K[];
     }
-    return omit(this.attributes, args);
+    return omit(this.attributes, args) as Omit<T, K>;
   }
 
-  isEmpty() {
+  isEmpty(): boolean {
     return isEmpty(this.attributes);
   }
 
   /**
    * Returns `true` if the attribute contains a value that is not null
    * or undefined.
-   * @param {string} attr
    */
-  has(attr) {
+  has(attr: keyof T): boolean {
     return this.get(attr) != null;
   }
 
   /**
    * Special-cased proxy to lodash's `matches` method.
-   * @param {Attributes} attrs
    */
-  matches(attrs) {
-    return !!iteratee(attrs, this)(this.attributes);
+  matches(attrs: Partial<T>): boolean {
+    return !!iteratee(attrs)(this.attributes);
   }
 
   /**
    * 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
    * anyone who needs to know about the change in state. The heart of the beast.
-   * @param {string|Object} key
-   * @param {string|Object} [val]
-   * @param {Options} [options]
    */
-  set(key, val, options) {
+  set(key: string | Partial<T> | ObjectWithId, val?: any, options?: ModelOptions): this {
     if (key == null) return this;
 
     // Handle both `"key", value` and `{key: value}` -style arguments.
-    let attrs;
+    let attrs: Partial<T> | ObjectWithId;
     if (typeof key === 'object') {
       attrs = key;
       options = val;
     } else {
-      (attrs = {})[key] = val;
+      attrs = {} as Partial<T>;
+      attrs[key as keyof T] = val;
     }
 
-    options || (options = {});
+    options = options || {};
 
     // Run validation.
-    if (!this._validate(attrs, options)) return false;
+    if (!this._validate(attrs, options)) return null;
 
     // Extract attributes and options.
     const unset = options.unset;
@@ -246,14 +229,14 @@ class Model extends EventEmitter(Object) {
 
     // For each `set` attribute, update or delete the current value.
     for (const attr in attrs) {
-      val = attrs[attr];
-      if (!isEqual(current[attr], val)) changes.push(attr);
-      if (!isEqual(prev[attr], val)) {
-        changed[attr] = val;
+      val = attrs[attr as keyof (T | ObjectWithId)];
+      if (!isEqual(current[attr as keyof T], val)) changes.push(attr);
+      if (!isEqual(prev[attr as keyof T], val)) {
+        changed[attr as keyof T] = val;
       } else {
-        delete changed[attr];
+        delete changed[attr as keyof T];
       }
-      unset ? delete current[attr] : (current[attr] = val);
+      unset ? delete current[attr as keyof T] : (current[attr as keyof T] = val);
     }
 
     // Update the `id`.
@@ -267,12 +250,13 @@ class Model extends EventEmitter(Object) {
       }
     }
 
-    // You might be wondering why there's a `while` loop here. Changes can
-    // be recursively nested within `"change"` events.
     if (changing) return this;
+
     if (!silent) {
+      // You might be wondering why there's a `while` loop here. Changes can
+      // be recursively nested within `"change"` events.
       while (this._pending) {
-        options = /** @type {Options} */ (this._pending);
+        options = this._pending as ModelOptions;
         this._pending = false;
         this.trigger('change', this, options);
       }
@@ -285,31 +269,27 @@ class Model extends EventEmitter(Object) {
   /**
    * Remove an attribute from the model, firing `"change"`. `unset` is a noop
    * if the attribute doesn't exist.
-   * @param {string} attr
-   * @param {Options} [options]
    */
-  unset(attr, options) {
-    return this.set(attr, undefined, Object.assign({}, options, { unset: true }));
+  unset(attr: keyof T, options?: ModelOptions): this {
+    return this.set(attr as string, undefined, Object.assign({}, options, { unset: true }));
   }
 
   /**
    * Clear all attributes on the model, firing `"change"`.
-   * @param {Options} options
    */
-  clear(options) {
-    const attrs = {};
-    for (const key in this.attributes) attrs[key] = undefined;
+  clear(options?: ModelOptions): this {
+    const attrs: Partial<T> = {};
+    for (const key in this.attributes) attrs[key as keyof T] = undefined;
     return this.set(attrs, Object.assign({}, options, { unset: true }));
   }
 
   /**
    * Determine if the model has changed since the last `"change"` event.
    * If you specify an attribute name, determine if that attribute has changed.
-   * @param {string} [attr]
    */
-  hasChanged(attr) {
+  hasChanged(attr?: keyof T): boolean {
     if (attr == null) return !isEmpty(this.changed);
-    return has(this.changed, attr);
+    return has(this.changed, attr as string);
   }
 
   /**
@@ -319,20 +299,19 @@ class Model extends EventEmitter(Object) {
    * persisted to the server. Unset attributes will be set to undefined.
    * You can also pass an attributes object to diff against the model,
    * determining if there *would be* a change.
-   * @param {Object} diff
    */
-  changedAttributes(diff) {
+  changedAttributes(diff?: Partial<T>): Partial<T> | false {
     if (!diff) {
       return this.hasChanged() ? clone(this.changed) : false;
     }
 
     const old = this._changing ? this._previousAttributes : this.attributes;
-    const changed = {};
-    let hasChanged;
+    const changed: Partial<T> = {};
+    let hasChanged = false;
     for (const attr in diff) {
-      const val = diff[attr];
-      if (isEqual(old[attr], val)) continue;
-      changed[attr] = val;
+      const val = diff[attr as keyof T];
+      if (isEqual(old[attr as keyof T], val)) continue;
+      changed[attr as keyof T] = val;
       hasChanged = true;
     }
     return hasChanged ? changed : false;
@@ -341,9 +320,8 @@ class Model extends EventEmitter(Object) {
   /**
    * Get the previous value of an attribute, recorded at the time the last
    * `"change"` event was fired.
-   * @param {string} [attr]
    */
-  previous(attr) {
+  previous<K extends keyof T>(attr: K): T[K] | null {
     if (attr == null || !this._previousAttributes) return null;
     return this._previousAttributes[attr];
   }
@@ -352,21 +330,20 @@ class Model extends EventEmitter(Object) {
    * Get all of the attributes of the model at the time of the previous
    * `"change"` event.
    */
-  previousAttributes() {
-    return clone(this._previousAttributes);
+  previousAttributes(): T | undefined {
+    return this._previousAttributes ? clone(this._previousAttributes) : undefined;
   }
 
   /**
    * Fetch the model from the server, merging the response with the model's
    * local attributes. Any changed attributes will trigger a "change" event.
-   * @param {Options} [options={}]
    */
-  fetch(options={}) {
+  fetch(options: Options = {}): any {
     options = Object.assign({ parse: true }, options);
 
     const success = options.success;
 
-    options.success = (resp) => {
+    options.success = (resp: any) => {
       const serverAttrs = options.parse ? this.parse(resp, options) : resp;
       if (!this.set(serverAttrs, options)) return false;
       if (success) success.call(options.context, this, resp, options);
@@ -381,18 +358,16 @@ class Model extends EventEmitter(Object) {
    * Set a hash of model attributes, and sync the model to the server.
    * If the server returns an attributes hash that differs, the model's
    * state will be `set` again.
-   * @param {string|Attributes} [key]
-   * @param {boolean|number|string|Options} [val]
-   * @param {Options} [options]
    */
-  save(key, val, options) {
+  save(key?: string | null | Partial<T>, val?: any, options?: ModelOptions): any {
     // Handle both `"key", value` and `{key: value}` -style arguments.
-    let attrs;
+    let attrs: Partial<T> | undefined;
     if (key == null || typeof key === 'object') {
-      attrs = key;
-      options = /** @type {Options} */ (val);
+      attrs = key as Partial<T>;
+      options = val as ModelOptions;
     } else {
-      (attrs = {})[key] = val;
+      attrs = {} as Partial<T>;
+      attrs[key as keyof T] = val;
     }
 
     options = Object.assign({ validate: true, parse: true }, options);
@@ -405,7 +380,7 @@ class Model extends EventEmitter(Object) {
     // the model will be valid when the attributes, if any, are set.
     if (attrs && !wait) {
       if (!this.set(attrs, options)) return false;
-    } else if (!this._validate(/** @type {Object} */ (attrs), options)) {
+    } else if (!this._validate(attrs || {}, options)) {
       return false;
     }
 
@@ -415,7 +390,7 @@ class Model extends EventEmitter(Object) {
     const error = options.error;
     const attributes = this.attributes;
 
-    options.success = (resp) => {
+    options.success = (resp: any) => {
       // Ensure attributes are restored during synchronous saves.
       this.attributes = attributes;
       let serverAttrs = options.parse ? this.parse(resp, options) : resp;
@@ -426,7 +401,7 @@ class Model extends EventEmitter(Object) {
       return_promise && promise.resolve();
     };
 
-    options.error = (model, e, options) => {
+    options.error = (model: this, e: any, options: Options) => {
       error && error.call(options.context, model, e, options);
       return_promise && promise.reject(e);
     };
@@ -454,9 +429,8 @@ class Model extends EventEmitter(Object) {
    * Destroy this model on the server if it was already persisted.
    * Optimistically removes the model from its collection, if it has one.
    * If `wait: true` is passed, waits for the server to respond before removal.
-   * @param {Options} [options]
    */
-  destroy(options) {
+  destroy(options?: ModelOptions): any {
     options = options ? clone(options) : {};
     const success = options.success;
     const wait = options.wait;
@@ -466,13 +440,13 @@ class Model extends EventEmitter(Object) {
       this.trigger('destroy', this, this.collection, options);
     };
 
-    options.success = (resp) => {
+    options.success = (resp: any) => {
       if (wait) destroy();
       if (success) success.call(options.context, this, resp, options);
       if (!this.isNew()) this.trigger('sync', this, resp, options);
     };
 
-    let xhr = false;
+    let xhr: any = false;
     if (this.isNew()) {
       defer(options.success);
     } else {
@@ -483,51 +457,60 @@ class Model extends EventEmitter(Object) {
     return xhr;
   }
 
+  get urlRoot(): string {
+    return this._urlRoot;
+  }
+
+  set urlRoot(root: string) {
+    this._urlRoot = root;
+  }
+
   /**
    * Default URL for the model's representation on the server -- if you're
    * using Backbone's restful methods, override this to change the endpoint
    * that will be called.
    */
-  url() {
+  get url(): string {
+    if (this._url) return this._url;
+
     const base = result(this, 'urlRoot') || result(this.collection, 'url') || urlError();
-    if (this.isNew()) return base;
+    if (this.isNew()) return base as string;
     const id = this.get(this.idAttribute);
-    return base.replace(/[^\/]$/, '$&/') + encodeURIComponent(id);
+    return (base as string).replace(/[^\/]$/, '$&/') + encodeURIComponent(String(id));
+  }
+
+  set url(url: string) {
+    this._url = url;
   }
 
   /**
    * **parse** converts a response into the hash of attributes to be `set` on
    * the model. The default implementation is just to pass the response along.
-   * @param {Options} resp
-   * @param {Options} [options]
    */
-  parse(resp, options) {
+  parse(resp: any, options?: ModelOptions): Partial<T> | null | void {
     return resp;
   }
 
   /**
    * A model is new if it has never been saved to the server, and lacks an id.
    */
-  isNew() {
+  isNew(): boolean {
     return !this.has(this.idAttribute);
   }
 
   /**
    * Check if the model is currently in a valid state.
-   * @param {Options} [options]
    */
-  isValid(options) {
+  isValid(options?: ModelOptions): boolean {
     return this._validate({}, Object.assign({}, options, { validate: true }));
   }
 
   /**
    * Run validation against the next complete set of model attributes,
    * returning `true` if all is well. Otherwise, fire an `"invalid"` event.
-   * @param {Attributes} attrs
-   * @param {Options} [options]
    */
-  _validate(attrs, options) {
-    if (!options.validate || !this.validate) return true;
+  _validate(attrs: Partial<T> | ObjectWithId, options?: ModelOptions): boolean {
+    if (!options?.validate || !this.validate) return true;
     attrs = Object.assign({}, this.attributes, attrs);
     const error = (this.validationError = this.validate(attrs, options) || null);
     if (!error) return true;
@@ -535,5 +518,3 @@ class Model extends EventEmitter(Object) {
     return false;
   }
 }
-
-export { Model };