@converse/skeletor 0.0.8 → 1.0.0

package/src/index.ts

@@ -0,0 +1,84 @@
+/* global global */
+import { EventEmitter } from './eventemitter';
+import Storage from './storage';
+import { Collection } from './collection';
+import { Model } from './model';
+import { sync } from './helpers';
+
+/**
+ * @public
+ */
+interface SkeletorType {
+  Collection: typeof Collection;
+  EventEmitter: typeof EventEmitter;
+  Model: typeof Model;
+  sync: typeof sync;
+  VERSION?: string;
+  noConflict?: () => SkeletorType;
+}
+
+/**
+ * @public
+ */
+const skeletor: SkeletorType = {
+  Collection,
+  EventEmitter,
+  Model,
+  sync,
+};
+
+// Establish the root object, `window` (`self`) in the browser, or `global` on the server.
+// We use `self` instead of `window` for `WebWorker` support.
+const root =
+  (typeof self == 'object' && self.self === self && self) ||
+  (typeof global == 'object' && global.global === global && global);
+
+// Current version of the library. Keep in sync with `package.json`.
+skeletor.VERSION = '0.0.1';
+
+// Save the previous value of the `Skeletor` variable, so that it can be
+// restored later on, if `noConflict` is used.
+const previousSkeletor = root.Skeletor;
+
+// Runs Skeletor.js in *noConflict* mode, returning the `Skeletor` variable
+// to its previous owner. Returns a reference to this Skeletor object.
+/**
+ * @public
+ */
+function noConflict() {
+  root.Skeletor = previousSkeletor;
+  return this;
+}
+skeletor.noConflict = noConflict;
+
+root.Skeletor = skeletor;
+export default skeletor;
+
+export { noConflict, Collection, EventEmitter, Model, Storage, sync };
+
+export type { LocalForageWithExtensions } from './storage';
+export type {
+  ClassConstructor,
+  CollectionOptions,
+  Comparator,
+  EventCallback,
+  EventCallbackMap,
+  EventContext,
+  EventHandlersMap,
+  EventListenerMap,
+  ModelAttributes,
+  ModelOptions,
+  ObjectListenedTo,
+  ObjectWithId,
+  Options,
+  SyncOperation,
+  SyncOptions,
+  EventHandler,
+  ListeningType,
+  IEventEmitter,
+  ListeningMap,
+} from './types';
+
+export type { CollectionIterator } from './collection';
+export type { SkeletorType };
+export type { EventEmitterObject } from './eventemitter';

package/src/listening.ts

@@ -0,0 +1,86 @@
+import { eventsApi, onApi, offApi } from './utils/events';
+import type {
+  EventCallback,
+  IEventEmitter,
+  EventCallbackMap,
+  EventsApiOptions,
+  ListeningType,
+} from './types';
+
+/**
+ * A listening class that tracks and cleans up memory bindings
+ * when all callbacks have been offed.
+ */
+class Listening implements ListeningType {
+  id: string;
+  listener: IEventEmitter;
+  obj: any;
+  interop: boolean;
+  count: number;
+  _events?: EventCallbackMap;
+
+  constructor(listener: IEventEmitter, obj: any) {
+    this.id = listener._listenId!;
+    this.listener = listener;
+    this.obj = obj;
+    this.interop = true;
+    this.count = 0;
+    this._events = undefined;
+  }
+
+  start(name: string | EventCallbackMap, callback: EventCallback, context: any, _listening: ListeningType): this {
+    const options: EventsApiOptions = {
+      context: this.obj,
+      ctx: context,
+      listening: _listening,
+    };
+
+    this._events = eventsApi(onApi, this._events || {}, name, callback, options) as EventCallbackMap;
+
+    if (_listening) {
+      const listeners = this.obj._listeners || (this.obj._listeners = {});
+      listeners[this.id] = this;
+
+      // Allow the listening to use a counter, instead of tracking
+      // callbacks for library interop
+      this.interop = false;
+    }
+
+    return this;
+  }
+
+  /**
+   * Stop's listening to a callback (or several).
+   * Uses an optimized counter if the listenee uses Backbone.Events.
+   * Otherwise, falls back to manual tracking to support events
+   * library interop.
+   */
+  stop(name: string | EventCallbackMap, callback: EventCallback): void {
+    let cleanup: boolean;
+    if (this.interop) {
+      this._events = eventsApi(offApi, this._events, name, callback, {
+        context: undefined,
+        listeners: undefined,
+      }) as EventCallbackMap;
+      cleanup = !this._events;
+    } else {
+      this.count--;
+      cleanup = this.count === 0;
+    }
+    if (cleanup) this.cleanup();
+  }
+
+  /**
+   * Cleans up memory bindings between the listener and the listenee.
+   */
+  cleanup(): void {
+    if (this.listener._listeningTo) {
+      delete this.listener._listeningTo[this.obj._listenId!];
+    }
+    if (!this.interop && this.obj._listeners) {
+      delete this.obj._listeners[this.id];
+    }
+  }
+}
+
+export default Listening;

package/src/model.ts

@@ -0,0 +1,520 @@
+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.
+ */
+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.
+   */
+  constructor(attributes?: Partial<T>, options?: ModelOptions) {
+    super();
+    let attrs: Partial<T> = attributes || ({} as Partial<T>);
+    options = options || {};
+
+    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) || ({} 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 as any);
+
+    // Reset changed after initial set
+    this.changed = {};
+  }
+
+  set browserStorage(storage: Storage) {
+    this._browserStorage = storage;
+  }
+
+  get browserStorage(): Storage | undefined {
+    return this._browserStorage;
+  }
+
+  /**
+   * The default name for the JSON `id` attribute is `"id"`. MongoDB and
+   * CouchDB users may want to set this to `"_id"` (by overriding this getter
+   * in a subclass).
+   */
+  get idAttribute(): string {
+    return 'id';
+  }
+
+  /**
+   * 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.
+   */
+  get cidPrefix(): string {
+    return 'c';
+  }
+
+  /**
+   * 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.
+   */
+  preinitialize(...args: any[]): void {}
+
+  /**
+   * Initialize is an empty function by default. Override it with your own
+   * initialization logic.
+   */
+  initialize(attrs?: Partial<T>, options?: ModelOptions): void {}
+
+  validate(attrs: Partial<T> | ObjectWithId, options?: ModelOptions): string | number | null | void {
+    return null;
+  }
+
+  /**
+   * Return a hash of defaults for the model's attributes.
+   */
+  defaults(): Partial<T> {
+    return {} as Partial<T>;
+  }
+
+  /**
+   * Return a copy of the model's `attributes` object.
+   */
+  toJSON(): T {
+    return clone(this.attributes);
+  }
+
+  /**
+   * Override this if you need custom syncing semantics for *this* particular model.
+   */
+  sync(method: SyncOperation, model: Model<any>, options: Options): any {
+    return getSyncMethod(model)(method, model, options);
+  }
+
+  /**
+   * Get the value of an attribute.
+   */
+  get<K extends keyof T>(attr: K): T[K] {
+    return this.attributes[attr];
+  }
+
+  keys(): string[] {
+    return Object.keys(this.attributes);
+  }
+
+  values(): T[keyof T][] {
+    return Object.values(this.attributes);
+  }
+
+  pairs(): [keyof T, T[keyof T]][] {
+    return this.entries();
+  }
+
+  entries(): [keyof T, T[keyof T]][] {
+    return Object.entries(this.attributes) as [keyof T, T[keyof T]][];
+  }
+
+  invert(): Record<string, keyof T> {
+    return invert(this.attributes);
+  }
+
+  pick<K extends keyof T>(...args: K[]): Pick<T, K> {
+    if (args.length === 1 && Array.isArray(args[0])) {
+      args = args[0] as K[];
+    }
+    return pick(this.attributes, args) as Pick<T, K>;
+  }
+
+  omit<K extends keyof T>(...args: K[]): Omit<T, K> {
+    if (args.length === 1 && Array.isArray(args[0])) {
+      args = args[0] as K[];
+    }
+    return omit(this.attributes, args) as Omit<T, K>;
+  }
+
+  isEmpty(): boolean {
+    return isEmpty(this.attributes);
+  }
+
+  /**
+   * Returns `true` if the attribute contains a value that is not null
+   * or undefined.
+   */
+  has(attr: keyof T): boolean {
+    return this.get(attr) != null;
+  }
+
+  /**
+   * Special-cased proxy to lodash's `matches` method.
+   */
+  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.
+   */
+  set(key: string | Partial<T> | ObjectWithId, val?: any, options?: ModelOptions): boolean | this {
+    if (key == null) return this;
+
+    // Handle both `"key", value` and `{key: value}` -style arguments.
+    let attrs: Partial<T> | ObjectWithId;
+    if (typeof key === 'object') {
+      attrs = key;
+      options = val;
+    } else {
+      attrs = {} as Partial<T>;
+      attrs[key as keyof T] = val;
+    }
+
+    options = options || {};
+
+    // Run validation.
+    if (!this._validate(attrs, options)) return false;
+
+    // Extract attributes and options.
+    const unset = options.unset;
+    const silent = options.silent;
+    const changes = [];
+    const changing = this._changing;
+    this._changing = true;
+
+    if (!changing) {
+      this._previousAttributes = clone(this.attributes);
+      this.changed = {};
+    }
+
+    const current = this.attributes;
+    const changed = this.changed;
+    const prev = this._previousAttributes;
+
+    // For each `set` attribute, update or delete the current value.
+    for (const attr in attrs) {
+      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 as keyof T];
+      }
+      unset ? delete current[attr as keyof T] : (current[attr as keyof T] = val);
+    }
+
+    // Update the `id`.
+    if (this.idAttribute in attrs) this.id = this.get(this.idAttribute);
+
+    // Trigger all relevant attribute changes.
+    if (!silent) {
+      if (changes.length) this._pending = options;
+      for (let i = 0; i < changes.length; i++) {
+        this.trigger('change:' + changes[i], this, current[changes[i]], options);
+      }
+    }
+
+    if (changing) return true;
+
+    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 = this._pending as ModelOptions;
+        this._pending = false;
+        this.trigger('change', this, options);
+      }
+    }
+    this._pending = false;
+    this._changing = false;
+    return this;
+  }
+
+  /**
+   * Remove an attribute from the model, firing `"change"`. `unset` is a noop
+   * if the attribute doesn't exist.
+   */
+  unset(attr: keyof T, options?: ModelOptions): boolean | this {
+    return this.set(attr as string, undefined, Object.assign({}, options, { unset: true }));
+  }
+
+  /**
+   * Clear all attributes on the model, firing `"change"`.
+   */
+  clear(options?: ModelOptions): boolean | 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.
+   */
+  hasChanged(attr?: keyof T): boolean {
+    if (attr == null) return !isEmpty(this.changed);
+    return has(this.changed, attr as string);
+  }
+
+  /**
+   * Return an object containing all the attributes that have changed, or
+   * false if there are no changed attributes. Useful for determining what
+   * parts of a view need to be updated and/or what attributes need to be
+   * 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.
+   */
+  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: Partial<T> = {};
+    let hasChanged = false;
+    for (const attr in diff) {
+      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;
+  }
+
+  /**
+   * Get the previous value of an attribute, recorded at the time the last
+   * `"change"` event was fired.
+   */
+  previous<K extends keyof T>(attr: K): T[K] | null {
+    if (attr == null || !this._previousAttributes) return null;
+    return this._previousAttributes[attr];
+  }
+
+  /**
+   * Get all of the attributes of the model at the time of the previous
+   * `"change"` event.
+   */
+  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.
+   */
+  fetch(options: Options = {}): any {
+    options = Object.assign({ parse: true }, options);
+
+    const success = options.success;
+
+    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);
+      this.trigger('sync', this, resp, options);
+    };
+
+    wrapError(this, options);
+    return this.sync('read', this, options);
+  }
+
+  /**
+   * 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.
+   */
+  save(key?: string | null | Partial<T>, val?: any, options?: ModelOptions): any {
+    // Handle both `"key", value` and `{key: value}` -style arguments.
+    let attrs: Partial<T> | undefined;
+    if (key == null || typeof key === 'object') {
+      attrs = key as Partial<T>;
+      options = val as ModelOptions;
+    } else {
+      attrs = {} as Partial<T>;
+      attrs[key as keyof T] = val;
+    }
+
+    options = Object.assign({ validate: true, parse: true }, options);
+    const wait = options.wait;
+    const return_promise = options.promise;
+    const promise = return_promise && getResolveablePromise();
+
+    // 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)) return false;
+    } else if (!this._validate(attrs || {}, options)) {
+      return false;
+    }
+
+    // After a successful server-side save, the client is (optionally)
+    // updated with the server-side state.
+    const success = options.success;
+    const error = options.error;
+    const attributes = this.attributes;
+
+    options.success = (resp: any) => {
+      // Ensure attributes are restored during synchronous saves.
+      this.attributes = attributes;
+      let serverAttrs = options.parse ? this.parse(resp, options) : resp;
+      if (wait) serverAttrs = Object.assign({}, attrs, serverAttrs);
+      if (serverAttrs && !this.set(serverAttrs, options)) return false;
+      if (success) success.call(options.context, this, resp, options);
+      this.trigger('sync', this, resp, options);
+      return_promise && promise.resolve();
+    };
+
+    options.error = (model: this, e: any, options: Options) => {
+      error && error.call(options.context, model, e, options);
+      return_promise && promise.reject(e);
+    };
+
+    wrapError(this, options);
+
+    // Set temporary attributes if `{wait: true}` to properly find new ids.
+    if (attrs && wait) this.attributes = Object.assign({}, attributes, attrs);
+
+    const method = this.isNew() ? 'create' : options.patch ? 'patch' : 'update';
+    if (method === 'patch' && !options.attrs) options.attrs = attrs;
+    const xhr = this.sync(method, this, options);
+
+    // Restore attributes.
+    this.attributes = attributes;
+
+    if (return_promise) {
+      return promise;
+    } else {
+      return xhr;
+    }
+  }
+
+  /**
+   * 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.
+   */
+  destroy(options?: ModelOptions): any {
+    options = options ? clone(options) : {};
+    const success = options.success;
+    const wait = options.wait;
+
+    const destroy = () => {
+      this.stopListening();
+      this.trigger('destroy', this, this.collection, options);
+    };
+
+    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: any = false;
+    if (this.isNew()) {
+      defer(options.success);
+    } else {
+      wrapError(this, options);
+      xhr = this.sync('delete', this, options);
+    }
+    if (!wait) destroy();
+    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.
+   */
+  get url(): string {
+    if (this._url) return this._url;
+
+    const base = result(this, 'urlRoot') || result(this.collection, 'url') || urlError();
+    if (this.isNew()) return base as string;
+    const id = this.get(this.idAttribute);
+    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.
+   */
+  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(): boolean {
+    return !this.has(this.idAttribute);
+  }
+
+  /**
+   * Check if the model is currently in a valid state.
+   */
+  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.
+   */
+  _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;
+    this.trigger('invalid', this, error, Object.assign(options, { validationError: error }));
+    return false;
+  }
+}