@converse/skeletor 0.0.8 → 1.0.0

package/src/storage.ts

@@ -0,0 +1,293 @@
+/**
+ * IndexedDB, localStorage and sessionStorage adapter
+ */
+import * as memoryDriver from 'localforage-driver-memory';
+import cloneDeep from 'lodash-es/cloneDeep';
+import isString from 'lodash-es/isString';
+import localForage from 'localforage';
+import mergebounce from 'mergebounce';
+import sessionStorageWrapper from './drivers/sessionStorage';
+import { extendPrototype as extendPrototypeWithSetItems } from 'localforage-setitems';
+import { extendPrototype as extendPrototypeWithGetItems } from '@converse/localforage-getitems/dist/localforage-getitems.es6';
+import { guid } from './helpers';
+import type { Model } from './model';
+import type { Collection } from './collection';
+import type { SyncOptions, SyncOperation } from './types';
+
+const IN_MEMORY = memoryDriver._driver;
+localForage.defineDriver(memoryDriver);
+extendPrototypeWithSetItems(localForage);
+extendPrototypeWithGetItems(localForage);
+
+/**
+ * @public
+ */
+export interface LocalForageWithExtensions {
+  setItem(key: string, value: any): Promise<any>;
+  getItem(key: string): Promise<any>;
+  removeItem(key: string): Promise<void>;
+  clear(): Promise<void>;
+  length(): Promise<number>;
+  key(keyIndex: number): Promise<string>;
+  keys(): Promise<string[]>;
+  setItems?(items: Record<string, any>): Promise<void>;
+  getItems?(keys: string[]): Promise<Record<string, any>>;
+  debouncedSetItems?: {
+    (items: Record<string, any>): Promise<void>;
+    flush?: () => void;
+  };
+}
+
+/**
+ * @public
+ */
+class BrowserStorage {
+  storeInitialized: Promise<void>;
+  store: LocalForageWithExtensions;
+  name: string;
+
+  static sessionStorageInitialized: Promise<void>;
+  static localForage: typeof localForage;
+
+  constructor(
+    id: string,
+    type: 'local' | 'session' | 'indexed' | 'in_memory' | LocalForageWithExtensions,
+    batchedWrites = false
+  ) {
+    if (type === 'local' && !window.localStorage) {
+      throw new Error('Skeletor.storage: Environment does not support localStorage.');
+    } else if (type === 'session' && !window.sessionStorage) {
+      throw new Error('Skeletor.storage: Environment does not support sessionStorage.');
+    }
+    if (isString(type)) {
+      this.storeInitialized = this.initStore(type as 'local' | 'session' | 'indexed' | 'in_memory', batchedWrites);
+    } else {
+      this.store = type;
+      if (batchedWrites) {
+        this.store.debouncedSetItems = mergebounce((items: Record<string, any>) => this.store.setItems!(items), 50, {
+          'promise': true,
+        });
+      }
+      this.storeInitialized = Promise.resolve();
+    }
+    this.name = id;
+  }
+
+  /**
+   * @param type - The storage type: 'local', 'session', 'indexed', or 'in_memory'
+   * @param batchedWrites - Whether to enable batched writes
+   */
+  async initStore(type: 'local' | 'session' | 'indexed' | 'in_memory', batchedWrites: boolean): Promise<void> {
+    if (type === 'session') {
+      await localForage.setDriver(sessionStorageWrapper._driver);
+    } else if (type === 'local') {
+      await localForage.config({ 'driver': localForage.LOCALSTORAGE });
+    } else if (type === 'in_memory') {
+      await localForage.config({ 'driver': IN_MEMORY });
+    } else if (type !== 'indexed') {
+      throw new Error('Skeletor.storage: No storage type was specified');
+    }
+    this.store = localForage as LocalForageWithExtensions;
+    if (batchedWrites) {
+      this.store.debouncedSetItems = mergebounce((items: Record<string, any>) => this.store.setItems!(items), 50, {
+        'promise': true,
+      });
+    }
+  }
+
+  flush(): void {
+    if (this.store.debouncedSetItems && typeof this.store.debouncedSetItems.flush === 'function') {
+      this.store.debouncedSetItems.flush();
+    }
+  }
+
+  async clear(): Promise<void> {
+    await this.store.removeItem(this.name).catch((e) => console.error(e));
+    const re = new RegExp(`^${this.name}-`);
+    const keys = await this.store.keys();
+    const removed_keys = keys.filter((k) => re.test(k));
+    await Promise.all(removed_keys.map((k) => this.store.removeItem(k).catch((e) => console.error(e))));
+  }
+
+  sync() {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const that = this;
+
+    async function localSync(method: SyncOperation, model: Model, options: SyncOptions) {
+      let resp: any, errorMessage: string | undefined, promise: Promise<any>, new_attributes: any;
+
+      // We get the collection (and if necessary the model attribute.
+      // Waiting for storeInitialized will cause another iteration of
+      // the event loop, after which the collection reference will
+      // be removed from the model.
+      const collection = model.collection;
+      if (['patch', 'update'].includes(method)) {
+        new_attributes = cloneDeep(model.attributes);
+      }
+      await that.storeInitialized;
+      try {
+        const original_attributes = model.attributes;
+        switch (method) {
+          case 'read':
+            if (model.id !== undefined) {
+              resp = await that.find(model);
+            } else {
+              resp = await that.findAll();
+            }
+            break;
+          case 'create':
+            resp = await that.create(model, options);
+            break;
+          case 'patch':
+          case 'update':
+            if (options.wait) {
+              // When `wait` is set to true, Skeletor waits until
+              // confirmation of storage before setting the values on
+              // the model.
+              // However, the new attributes needs to be sent, so it
+              // sets them manually on the model and then removes
+              // them after calling `sync`.
+              // Because our `sync` method is asynchronous and we
+              // wait for `storeInitialized`, the attributes are
+              // already restored once we get here, so we need to do
+              // the attributes dance again.
+              model.attributes = new_attributes;
+            }
+            promise = that.update(model);
+            if (options.wait) {
+              model.attributes = original_attributes;
+            }
+            resp = await promise;
+            break;
+          case 'delete':
+            resp = await that.destroy(model, collection);
+            break;
+        }
+      } catch (error: any) {
+        const storageSize = await that.getStorageSize();
+        if (error.code === 22 && storageSize === 0) {
+          errorMessage = 'Private browsing is unsupported';
+        } else {
+          errorMessage = error.message;
+        }
+      }
+
+      if (resp) {
+        if (options && options.success) {
+          // When storing, we don't pass back the response (which is
+          // the set attributes returned from localforage because
+          // Skeletor sets them again on the model and due to the async
+          // nature of localforage it can cause stale attributes to be
+          // set on a model after it's been updated in the meantime.
+          const data = method === 'read' ? resp : null;
+          options.success(data, options);
+        }
+      } else {
+        errorMessage = errorMessage ? errorMessage : 'Record Not Found';
+        if (options && options.error) {
+          options.error(errorMessage);
+        }
+      }
+    }
+    localSync.__name__ = 'localSync';
+    return localSync;
+  }
+
+  removeCollectionReference(model: Model, collection: Collection | undefined): Promise<any> | undefined {
+    if (!collection) {
+      return;
+    }
+    const ids = collection.filter((m) => m.id !== model.id).map((m) => this.getItemName(m.id!));
+
+    return this.store.setItem(this.name, ids);
+  }
+
+  addCollectionReference(model: Model, collection: Collection | undefined): Promise<any> | undefined {
+    if (!collection) {
+      return;
+    }
+    const ids = collection.map((m) => this.getItemName(m.id!));
+    const new_id = this.getItemName(model.id!);
+    if (!ids.includes(new_id)) {
+      ids.push(new_id);
+    }
+    return this.store.setItem(this.name, ids);
+  }
+
+  getCollectionReferenceData(model: Model): Record<string, string[]> {
+    if (!model.collection) {
+      return {};
+    }
+    const ids = model.collection.map((m) => this.getItemName(m.id!));
+    const new_id = this.getItemName(model.id!);
+    if (!ids.includes(new_id)) {
+      ids.push(new_id);
+    }
+    const result: Record<string, string[]> = {};
+    result[this.name] = ids;
+    return result;
+  }
+
+  async save(model: Model): Promise<any> {
+    if (this.store.setItems) {
+      const items: Record<string, any> = {};
+      items[this.getItemName(model.id!)] = model.toJSON();
+      Object.assign(items, this.getCollectionReferenceData(model));
+      return this.store.debouncedSetItems ? this.store.debouncedSetItems(items) : this.store.setItems!(items);
+    } else {
+      const key = this.getItemName(model.id!);
+      const data = await this.store.setItem(key, model.toJSON());
+      await this.addCollectionReference(model, model.collection);
+      return data;
+    }
+  }
+
+  create(model: Model, options: SyncOptions): Promise<any> {
+    /* Add a model, giving it a (hopefully)-unique GUID, if it doesn't already
+     * have an id of it's own.
+     */
+    if (!model.id) {
+      model.id = guid();
+      model.set(model.idAttribute, model.id, options);
+    }
+    return this.save(model);
+  }
+
+  update(model: Model): Promise<any> {
+    return this.save(model);
+  }
+
+  find(model: Model): Promise<any> {
+    return this.store.getItem(this.getItemName(model.id!));
+  }
+
+  async findAll(): Promise<any[]> {
+    /* Return the array of all models currently in storage.
+     */
+    const keys = (await this.store.getItem(this.name)) as string[] | null;
+    if (keys?.length) {
+      const items = await this.store.getItems!(keys);
+      return Object.values(items);
+    }
+    return [];
+  }
+
+  async destroy(model: Model, collection: Collection | undefined): Promise<Model> {
+    await this.flush();
+    await this.store.removeItem(this.getItemName(model.id!));
+    await this.removeCollectionReference(model, collection);
+    return model;
+  }
+
+  async getStorageSize(): Promise<number> {
+    return await this.store.length();
+  }
+
+  getItemName(id: string | number): string {
+    return this.name + '-' + id;
+  }
+}
+
+BrowserStorage.sessionStorageInitialized = localForage.defineDriver(sessionStorageWrapper);
+BrowserStorage.localForage = localForage;
+export default BrowserStorage;

package/src/types.ts

@@ -0,0 +1,189 @@
+import {Collection} from './collection';
+import {Model} from './model';
+
+/**
+ * @public
+ */
+export type SyncOperation = 'create' | 'update' | 'patch' | 'delete' | 'read';
+
+/**
+ * @public
+ */
+export type ObjectListenedTo = object & {_listenId?: string};
+
+/**
+ * @public
+ */
+export interface SyncOptions {
+  url?: string;
+  data?: any;
+  attrs?: any;
+  success?: (data?: any, options?: SyncOptions) => void;
+  error?: (error: any) => void;
+  xhr?: any;
+  wait?: boolean;
+}
+
+/**
+ * @public
+ */
+export type ClassConstructor<T = any> = new (...args: any[]) => T;
+
+/**
+ * @public
+ */
+export type EventContext = unknown;
+
+/**
+ * @public
+ */
+export type EventCallback = (...args: any[]) => void;
+
+/**
+ * @public
+ */
+export type EventCallbackMap = Record<string, EventCallback>;
+
+/**
+ * @public
+ */
+export type EventCallbacksMap = Record<string, EventCallback[]>;
+
+/**
+ * @public
+ */
+export type EventListenerMap = Record<string, ListeningType>;
+
+/**
+ * @public
+ */
+export interface EventHandlersMap {
+  all?: EventHandler[];
+  [name: string]: EventHandler[];
+}
+
+/**
+ * @public
+ */
+export type ListeningMap = Record<string, ListeningType>;
+
+/**
+ * @public
+ */
+export type ObjectWithId = Record<string, any> & {id: string | number};
+
+/**
+ * @public
+ */
+export interface IEventEmitter {
+  _events?: Record<string, any>;
+  _listeners?: ListeningMap;
+  _listeningTo?: ListeningMap;
+  _listenId?: string;
+
+  on(name: string | EventCallbackMap, callback?: EventCallback | EventContext, context?: EventContext): this;
+  off(
+    name?: string | EventCallbackMap | null,
+    callback?: EventCallback | EventContext | null,
+    context?: EventContext
+  ): this;
+  trigger(name: string, ...args: any[]): this;
+  stopListening(obj?: any, name?: string | EventCallbackMap, callback?: EventCallback): this;
+  once(name: string | EventCallbackMap, callback?: EventCallback | EventContext, context?: EventContext): this;
+  listenTo(obj: ObjectListenedTo, name: string | EventCallbackMap, callback?: EventCallback): this;
+  listenToOnce(obj: any, name: string | EventCallbackMap, callback?: EventCallback): this;
+}
+
+/**
+ * @public
+ */
+export interface EventHandler {
+  callback: EventCallback;
+  context: any;
+  ctx: any;
+  listening?: ListeningType | null;
+}
+
+/**
+ * @public
+ */
+export interface ListeningType {
+  _events?: EventCallbackMap;
+  cleanup(): void;
+  count: number;
+  id: string;
+  interop: boolean;
+  listener: IEventEmitter;
+  obj: any;
+
+  start(name: string | EventCallbackMap, callback: EventCallback, context: any, _listening: ListeningType): this;
+  stop(name: string | EventCallbackMap, callback: EventCallback): void;
+}
+
+/**
+ * @public
+ */
+export interface EventsApiOptions {
+  context?: any;
+  ctx?: any;
+  listening?: ListeningType;
+  listeners?: ListeningMap;
+}
+
+/**
+ * @public
+ */
+export interface OffApiOptions {
+  context?: any;
+  listeners?: {[key: string]: ListeningType};
+}
+
+/**
+ * @public
+ */
+export type Comparator<T extends Model = Model> = string | boolean | ((a: T, b: T) => number) | ((a?: T) => string);
+
+/**
+ * @public
+ */
+export type OfferFunction = (name: string, callback: EventCallback) => void;
+
+/**
+ * @public
+ */
+export type IterateeFunction = (
+  eventsOrMap: EventCallbackMap | EventHandlersMap,
+  name: string | null,
+  callback: EventCallback | EventHandler | null,
+  options: EventsApiOptions | OffApiOptions | OfferFunction | any[]
+) => EventCallbackMap | EventHandlersMap | void;
+
+/**
+ * @public
+ */
+export type ModelAttributes = Record<string | number, any> & {id?: string | number};
+
+/**
+ * @public
+ */
+export type Options = Record<string, any>;
+
+/**
+ * @public
+ */
+export type CollectionOptions<T extends Model = Model> = Options & {
+  model?: new (attributes?: Partial<ModelAttributes>, options?: ModelOptions) => T;
+  comparator?: Comparator<T>;
+  previousModels?: Model[];
+};
+
+/**
+ * @public
+ */
+export type ModelOptions = Options & {
+  collection?: Collection;
+  parse?: boolean;
+  unset?: boolean;
+  silent?: boolean;
+  validate?: boolean;
+};

package/src/utils/events.ts

@@ -0,0 +1,224 @@
+import once from 'lodash-es/once';
+import type {
+  EventCallback,
+  EventHandler,
+  EventCallbackMap,
+  EventsApiOptions,
+  IterateeFunction,
+  OffApiOptions,
+  OfferFunction,
+  EventHandlersMap,
+  EventContext,
+} from '../types';
+
+// Regular expression used to split event strings.
+const eventSplitter = /\s+/;
+
+/**
+ * Iterates over the standard `event, callback` (as well as the fancy multiple
+ * space-separated events `"change blur", callback` and jQuery-style event
+ * maps `{event: callback}`).
+ */
+export function eventsApi(
+  iteratee: IterateeFunction,
+  events: EventHandlersMap | EventCallbackMap,
+  name: string | EventCallbackMap | null,
+  callback: EventCallback | EventHandler | EventContext | null,
+  opts: EventsApiOptions | OffApiOptions | any[]
+): EventHandlersMap | EventCallbackMap {
+  let i = 0;
+  let names: string[];
+
+  if (name && typeof name === 'object') {
+    // Handle event maps.
+    if (callback !== undefined && 'context' in opts && opts.context === undefined) {
+      opts.context = callback;
+    }
+    for (names = Object.keys(name); i < names.length; i++) {
+      events = eventsApi(iteratee, events, names[i], name[names[i]], opts);
+    }
+  } else if (name && typeof name === 'string' && eventSplitter.test(name)) {
+    // Handle space-separated event names by delegating them individually.
+    for (names = name.split(eventSplitter); i < names.length; i++) {
+      const result = iteratee(events, names[i], callback as EventCallback | EventHandler, opts);
+      if (result !== undefined) {
+        events = result as EventHandlersMap;
+      }
+    }
+  } else {
+    // Finally, standard events.
+    events = iteratee(events, name as string | null, callback as EventCallback | EventHandler, opts) as
+      | EventHandlersMap
+      | EventCallbackMap;
+  }
+  return events;
+}
+
+/**
+ * A reducer that adds a callback to the `events` object.
+ */
+export function onApi(
+  events: EventHandlersMap,
+  name: string,
+  callback: EventCallback | null,
+  options: EventsApiOptions
+): EventHandlersMap {
+  if (callback) {
+    const handlers = events[name] || (events[name] = []);
+    const context = options.context;
+    const ctx = options.ctx;
+    const listening = options.listening;
+    if (listening) listening.count++;
+
+    handlers.push({ callback, context, ctx: context || ctx, listening });
+  }
+  return events;
+}
+
+/**
+ * An try-catch guarded #on function, to prevent poisoning the global
+ * `_listening` variable.
+ */
+export function tryCatchOn(
+  obj: any,
+  name: string | EventCallbackMap,
+  callback: EventCallback | EventContext,
+  context: EventContext
+): any {
+  try {
+    obj.on(name, callback, context);
+  } catch (e) {
+    return e;
+  }
+}
+
+/**
+ * The reducing API that removes a callback from the `events` object.
+ */
+export function offApi(
+  events: EventHandlersMap,
+  name: string | null,
+  callback: EventCallback | null,
+  options: OffApiOptions
+): EventHandlersMap | void {
+  if (!events) return;
+
+  const context = options.context;
+  const listeners = options.listeners;
+  let i = 0;
+  let names: string[];
+
+  // Delete all event listeners and "drop" events.
+  if (!name && !context && !callback) {
+    if (listeners) {
+      for (names = Object.keys(listeners); i < names.length; i++) {
+        listeners[names[i]].cleanup();
+      }
+    }
+    return;
+  }
+
+  names = name ? [name] : Object.keys(events);
+  for (; i < names.length; i++) {
+    const currentName = names[i];
+    const handlers = events[currentName];
+
+    // Bail out if there are no events stored.
+    if (!handlers) {
+      continue;
+    }
+
+    // Find any remaining events.
+    const remaining: EventHandler[] = [];
+    for (let j = 0; j < handlers.length; j++) {
+      const handler = handlers[j];
+      if (
+        (callback && callback !== handler.callback && callback !== (handler.callback as any)._callback) ||
+        (context && context !== handler.context)
+      ) {
+        remaining.push(handler);
+      } else {
+        const listening = handler.listening;
+        if (listening) listening.stop(currentName, callback!);
+      }
+    }
+
+    // Replace events if there are any remaining.  Otherwise, clean up.
+    if (remaining.length) {
+      events[currentName] = remaining;
+    } else {
+      delete events[currentName];
+    }
+  }
+
+  return events;
+}
+
+/**
+ * Reduces the event callbacks into a map of `{event: onceWrapper}`.
+ * `offer` unbinds the `onceWrapper` after it has been called.
+ */
+export function onceMap(
+  map: EventCallbackMap,
+  name: string,
+  callback: EventCallback | null,
+  offer: OfferFunction
+): { [name: string]: EventCallback } {
+  if (callback) {
+    const _once = once(function (this: any, ...args: any[]) {
+      offer(name, _once);
+      callback.apply(this, args);
+    }) as EventCallback & { _callback?: EventCallback };
+    map[name] = _once;
+    _once._callback = callback;
+  }
+  return map;
+}
+
+/** Handles triggering the appropriate event callbacks. */
+export function triggerApi(
+  objEvents: EventHandlersMap | null,
+  name: string,
+  _callback: EventCallback | null,
+  args: any[]
+): EventHandlersMap | null {
+  if (objEvents) {
+    const events = objEvents[name];
+    let allEvents = objEvents.all;
+    if (events && allEvents) allEvents = allEvents.slice();
+    if (events) triggerEvents(events, args);
+    if (allEvents) triggerEvents(allEvents, [name].concat(args));
+  }
+  return objEvents;
+}
+
+/**
+ * A difficult-to-believe, but optimized internal dispatch function for
+ * triggering events. Tries to keep the usual cases speedy (most internal
+ * Backbone events have 3 arguments).
+ */
+function triggerEvents(events: EventHandler[], args: any[]): void {
+  let ev: EventHandler;
+  let i = -1;
+  const l = events.length;
+  const a1 = args[0];
+  const a2 = args[1];
+  const a3 = args[2];
+  switch (args.length) {
+    case 0:
+      while (++i < l) (ev = events[i]).callback.call(ev.ctx);
+      return;
+    case 1:
+      while (++i < l) (ev = events[i]).callback.call(ev.ctx, a1);
+      return;
+    case 2:
+      while (++i < l) (ev = events[i]).callback.call(ev.ctx, a1, a2);
+      return;
+    case 3:
+      while (++i < l) (ev = events[i]).callback.call(ev.ctx, a1, a2, a3);
+      return;
+    default:
+      while (++i < l) (ev = events[i]).callback.apply(ev.ctx, args);
+      return;
+  }
+}