@converse/skeletor 0.0.9 → 1.0.0

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

@@ -2,33 +2,71 @@
  * IndexedDB, localStorage and sessionStorage adapter
  */
 import * as memoryDriver from 'localforage-driver-memory';
-import cloneDeep from 'lodash-es/cloneDeep.js';
-import isString from 'lodash-es/isString.js';
+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.js';
+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.js';
+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);
 
-class Storage {
-  constructor(id, type, batchedWrites = false) {
+/**
+ * @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, batchedWrites);
+      this.storeInitialized = this.initStore(type as 'local' | 'session' | 'indexed' | 'in_memory', batchedWrites);
     } else {
       this.store = type;
       if (batchedWrites) {
-        this.store.debouncedSetItems = mergebounce((items) => this.store.setItems(items), 50, { 'promise': true });
+        this.store.debouncedSetItems = mergebounce((items: Record<string, any>) => this.store.setItems!(items), 50, {
+          'promise': true,
+        });
       }
       this.storeInitialized = Promise.resolve();
     }
@@ -36,10 +74,10 @@ class Storage {
   }
 
   /**
-   * @param {'local'|'session'|'indexed'|'in_memory'} type
-   * @param {boolean} batchedWrites
+   * @param type - The storage type: 'local', 'session', 'indexed', or 'in_memory'
+   * @param batchedWrites - Whether to enable batched writes
    */
-  async initStore(type, batchedWrites) {
+  async initStore(type: 'local' | 'session' | 'indexed' | 'in_memory', batchedWrites: boolean): Promise<void> {
     if (type === 'session') {
       await localForage.setDriver(sessionStorageWrapper._driver);
     } else if (type === 'local') {
@@ -49,17 +87,21 @@ class Storage {
     } else if (type !== 'indexed') {
       throw new Error('Skeletor.storage: No storage type was specified');
     }
-    this.store = localForage;
+    this.store = localForage as LocalForageWithExtensions;
     if (batchedWrites) {
-      this.store.debouncedSetItems = mergebounce((items) => this.store.setItems(items), 50, { 'promise': true });
+      this.store.debouncedSetItems = mergebounce((items: Record<string, any>) => this.store.setItems!(items), 50, {
+        'promise': true,
+      });
     }
   }
 
-  flush() {
-    return this.store.debouncedSetItems?.flush();
+  flush(): void {
+    if (this.store.debouncedSetItems && typeof this.store.debouncedSetItems.flush === 'function') {
+      this.store.debouncedSetItems.flush();
+    }
   }
 
-  async clear() {
+  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();
@@ -71,8 +113,8 @@ class Storage {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const that = this;
 
-    async function localSync(method, model, options) {
-      let resp, errorMessage, promise, new_attributes;
+    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
@@ -121,8 +163,9 @@ class Storage {
             resp = await that.destroy(model, collection);
             break;
         }
-      } catch (error) {
-        if (error.code === 22 && that.getStorageSize() === 0) {
+      } catch (error: any) {
+        const storageSize = await that.getStorageSize();
+        if (error.code === 22 && storageSize === 0) {
           errorMessage = 'Private browsing is unsupported';
         } else {
           errorMessage = error.message;
@@ -150,56 +193,56 @@ class Storage {
     return localSync;
   }
 
-  removeCollectionReference(model, collection) {
+  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));
+    const ids = collection.filter((m) => m.id !== model.id).map((m) => this.getItemName(m.id!));
 
     return this.store.setItem(this.name, ids);
   }
 
-  addCollectionReference(model, collection) {
+  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);
+    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) {
+  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);
+    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 = {};
+    const result: Record<string, string[]> = {};
     result[this.name] = ids;
     return result;
   }
 
-  async save(model) {
+  async save(model: Model): Promise<any> {
     if (this.store.setItems) {
-      const items = {};
-      items[this.getItemName(model.id)] = model.toJSON();
+      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);
+      return this.store.debouncedSetItems ? this.store.debouncedSetItems(items) : this.store.setItems!(items);
     } else {
-      const key = this.getItemName(model.id);
+      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, options) {
+  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.
      */
@@ -210,41 +253,41 @@ class Storage {
     return this.save(model);
   }
 
-  update(model) {
+  update(model: Model): Promise<any> {
     return this.save(model);
   }
 
-  find(model) {
-    return this.store.getItem(this.getItemName(model.id));
+  find(model: Model): Promise<any> {
+    return this.store.getItem(this.getItemName(model.id!));
   }
 
-  async findAll() {
+  async findAll(): Promise<any[]> {
     /* Return the array of all models currently in storage.
      */
-    const keys = await this.store.getItem(this.name);
+    const keys = (await this.store.getItem(this.name)) as string[] | null;
     if (keys?.length) {
-      const items = await this.store.getItems(keys);
+      const items = await this.store.getItems!(keys);
       return Object.values(items);
     }
     return [];
   }
 
-  async destroy(model, collection) {
+  async destroy(model: Model, collection: Collection | undefined): Promise<Model> {
     await this.flush();
-    await this.store.removeItem(this.getItemName(model.id));
+    await this.store.removeItem(this.getItemName(model.id!));
     await this.removeCollectionReference(model, collection);
     return model;
   }
 
-  getStorageSize() {
-    return this.store.length;
+  async getStorageSize(): Promise<number> {
+    return await this.store.length();
   }
 
-  getItemName(id) {
+  getItemName(id: string | number): string {
     return this.name + '-' + id;
   }
 }
 
-Storage.sessionStorageInitialized = localForage.defineDriver(sessionStorageWrapper);
-Storage.localForage = localForage;
-export default Storage;
+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.js → events.ts}

@@ -1,5 +1,15 @@
-import once from 'lodash-es/once.js';
-import keys from 'lodash-es/keys.js';
+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+/;
@@ -9,34 +19,55 @@ const eventSplitter = /\s+/;
  * space-separated events `"change blur", callback` and jQuery-style event
  * maps `{event: callback}`).
  */
-export function eventsApi(iteratee, events, name, callback, opts) {
-  let i = 0,
-    names;
+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 = keys(name); i < names.length; i++) {
+    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 && eventSplitter.test(name)) {
+  } 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++) {
-      events = iteratee(events, names[i], callback, opts);
+      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, callback, opts);
+    events = iteratee(events, name as string | null, callback as EventCallback | EventHandler, opts) as
+      | EventHandlersMap
+      | EventCallbackMap;
   }
   return events;
 }
 
-// The reducing API that adds a callback to the `events` object.
-export function onApi(events, name, callback, options) {
+/**
+ * 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,
-      ctx = options.ctx,
-      listening = options.listening;
+    const context = options.context;
+    const ctx = options.ctx;
+    const listening = options.listening;
     if (listening) listening.count++;
 
     handlers.push({ callback, context, ctx: context || ctx, listening });
@@ -47,12 +78,13 @@ export function onApi(events, name, callback, options) {
 /**
  * An try-catch guarded #on function, to prevent poisoning the global
  * `_listening` variable.
- * @param {any} obj
- * @param {string} name
- * @param {Function} callback
- * @param {any} context
  */
-export function tryCatchOn(obj, name, callback, context) {
+export function tryCatchOn(
+  obj: any,
+  name: string | EventCallbackMap,
+  callback: EventCallback | EventContext,
+  context: EventContext
+): any {
   try {
     obj.on(name, callback, context);
   } catch (e) {
@@ -63,52 +95,59 @@ export function tryCatchOn(obj, name, callback, context) {
 /**
  * The reducing API that removes a callback from the `events` object.
  */
-export function offApi(events, name, callback, options) {
+export function offApi(
+  events: EventHandlersMap,
+  name: string | null,
+  callback: EventCallback | null,
+  options: OffApiOptions
+): EventHandlersMap | void {
   if (!events) return;
 
-  const context = options.context,
-    listeners = options.listeners;
-  let i = 0,
-    names;
+  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) {
-    for (names = keys(listeners); i < names.length; i++) {
-      listeners[names[i]].cleanup();
+    if (listeners) {
+      for (names = Object.keys(listeners); i < names.length; i++) {
+        listeners[names[i]].cleanup();
+      }
     }
     return;
   }
 
-  names = name ? [name] : keys(events);
+  names = name ? [name] : Object.keys(events);
   for (; i < names.length; i++) {
-    name = names[i];
-    const handlers = events[name];
+    const currentName = names[i];
+    const handlers = events[currentName];
 
     // Bail out if there are no events stored.
     if (!handlers) {
-      break;
+      continue;
     }
 
     // Find any remaining events.
-    const remaining = [];
+    const remaining: EventHandler[] = [];
     for (let j = 0; j < handlers.length; j++) {
       const handler = handlers[j];
       if (
-        (callback && callback !== handler.callback && callback !== handler.callback._callback) ||
+        (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(name, callback);
+        if (listening) listening.stop(currentName, callback!);
       }
     }
 
     // Replace events if there are any remaining.  Otherwise, clean up.
     if (remaining.length) {
-      events[name] = remaining;
+      events[currentName] = remaining;
     } else {
-      delete events[name];
+      delete events[currentName];
     }
   }
 
@@ -119,19 +158,30 @@ export function offApi(events, name, callback, options) {
  * Reduces the event callbacks into a map of `{event: onceWrapper}`.
  * `offer` unbinds the `onceWrapper` after it has been called.
  */
-export function onceMap(map, name, callback, offer) {
+export function onceMap(
+  map: EventCallbackMap,
+  name: string,
+  callback: EventCallback | null,
+  offer: OfferFunction
+): { [name: string]: EventCallback } {
   if (callback) {
-    const _once = (map[name] = once(function () {
+    const _once = once(function (this: any, ...args: any[]) {
       offer(name, _once);
-      callback.apply(this, arguments);
-    }));
+      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, name, callback, args) {
+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;
@@ -147,13 +197,13 @@ export function triggerApi(objEvents, name, callback, args) {
  * triggering events. Tries to keep the usual cases speedy (most internal
  * Backbone events have 3 arguments).
  */
-function triggerEvents(events, args) {
-  let ev,
-    i = -1;
-  const l = events.length,
-    a1 = args[0],
-    a2 = args[1],
-    a3 = args[2];
+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);