@converse/skeletor 0.0.8 → 1.0.0

package/src/drivers/sessionStorage.ts

@@ -0,0 +1,297 @@
+// Copyright 2014 Mozilla
+// Copyright 2015 Thodoris Greasidis
+// Copyright 2018-2025 JC Brand
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import executeCallback from 'localforage/src/utils/executeCallback';
+import getCallback from 'localforage/src/utils/getCallback';
+import normalizeKey from 'localforage/src/utils/normalizeKey';
+import serializer from 'localforage/src/utils/serializer';
+
+const serialize = serializer['serialize'];
+const deserialize = serializer['deserialize'];
+
+interface DbInfo {
+  keyPrefix: string;
+  serializer: {
+    serialize: typeof serialize;
+    deserialize: typeof deserialize;
+  };
+  [key: string]: any;
+}
+
+interface LocalForageOptions {
+  name: string;
+  storeName: string;
+  [key: string]: any;
+}
+
+interface IteratorCallback<T, U> {
+  (value: T, key: string, iterationNumber: number): U;
+}
+
+function isSessionStorageValid(): boolean {
+  try {
+    if (sessionStorage && 'setItem' in sessionStorage) {
+      return true;
+    }
+  } catch (e) {
+    console.log(e);
+  }
+  return false;
+}
+
+function _getKeyPrefix(options: LocalForageOptions, defaultConfig: LocalForageOptions): string {
+  let keyPrefix = options.name + '/';
+
+  if (options.storeName !== defaultConfig.storeName) {
+    keyPrefix += options.storeName + '/';
+  }
+  return keyPrefix;
+}
+
+const dbInfo: DbInfo = {
+  keyPrefix: '',
+  serializer: {
+    serialize: serialize,
+    deserialize: deserialize,
+  },
+};
+
+function _initStorage(this: any, options: LocalForageOptions): void {
+  dbInfo.keyPrefix = _getKeyPrefix(options, this._defaultConfig);
+  if (options) {
+    for (const i in options) {
+      dbInfo[i] = options[i];
+    }
+  }
+}
+
+// Remove all keys from the datastore, effectively destroying all data in
+// the app's key/value store!
+function clear(callback?: (err: any) => void): Promise<void> {
+  const promise = this.ready().then(function () {
+    const keyPrefix = dbInfo.keyPrefix;
+
+    for (let i = sessionStorage.length - 1; i >= 0; i--) {
+      const key = sessionStorage.key(i);
+      if (key && key.indexOf(keyPrefix) === 0) {
+        sessionStorage.removeItem(key);
+      }
+    }
+  });
+
+  executeCallback(promise, callback);
+  return promise;
+}
+
+function getItem<T>(key: string, callback?: (err: any, value: T | null) => void): Promise<T | null> {
+  key = normalizeKey(key);
+
+  const promise = this.ready().then(function (): T | null {
+    const result = sessionStorage.getItem(dbInfo.keyPrefix + key);
+    // If a result was found, parse it from the serialized
+    // string into a JS object. If result isn't truthy, the key
+    // is likely undefined and we'll pass it straight to the
+    // callback.
+    if (result) {
+      return dbInfo.serializer.deserialize(result) as T;
+    }
+    return null;
+  });
+
+  executeCallback(promise, callback);
+  return promise;
+}
+
+function iterate<T, U>(
+  iterator: IteratorCallback<T, U>,
+  callback?: (err: any, result: U | undefined) => void
+): Promise<U | undefined> {
+  const self = this;
+
+  const promise = self.ready().then(function (): U | undefined {
+    const keyPrefix = dbInfo.keyPrefix;
+    const keyPrefixLength = keyPrefix.length;
+    const length = sessionStorage.length;
+    let iterationNumber = 1;
+
+    for (let i = 0; i < length; i++) {
+      const key = sessionStorage.key(i);
+      if (!key || key.indexOf(keyPrefix) !== 0) {
+        continue;
+      }
+
+      // If a result was found, parse it from the serialized
+      // string into a JS object. If result isn't truthy, the
+      // key is likely undefined and we'll pass it straight
+      // to the iterator.
+      const item = sessionStorage.getItem(key);
+      const value = item ? dbInfo.serializer.deserialize(item) : item;
+
+      const result = iterator(value as T, key.substring(keyPrefixLength), iterationNumber++);
+      if (result !== void 0) {
+        return result;
+      }
+    }
+    return;
+  });
+
+  executeCallback(promise, callback);
+  return promise;
+}
+
+// Same as sessionStorage's key() method, except takes a callback.
+function key(n: number, callback?: (err: any, key: string | null) => void): Promise<string | null> {
+  const self = this;
+  const promise = self.ready().then(function (): string | null {
+    let result: string | null;
+    try {
+      result = sessionStorage.key(n);
+    } catch (error) {
+      result = null;
+    }
+
+    // Remove the prefix from the key, if a key is found.
+    if (result) {
+      result = result.substring(dbInfo.keyPrefix.length);
+    }
+
+    return result;
+  });
+
+  executeCallback(promise, callback);
+  return promise;
+}
+
+function keys(callback?: (err: any, keys: string[]) => void): Promise<string[]> {
+  const self = this;
+  const promise = self.ready().then(function (): string[] {
+    const length = sessionStorage.length;
+    const keys: string[] = [];
+
+    for (let i = 0; i < length; i++) {
+      const itemKey = sessionStorage.key(i);
+      if (itemKey && itemKey.indexOf(dbInfo.keyPrefix) === 0) {
+        keys.push(itemKey.substring(dbInfo.keyPrefix.length));
+      }
+    }
+    return keys;
+  });
+
+  executeCallback(promise, callback);
+  return promise;
+}
+
+// Supply the number of keys in the datastore to the callback function.
+function length(callback?: (err: any, numberOfKeys: number) => void): Promise<number> {
+  const self = this;
+  const promise = self.keys().then(function (keys: string[]) {
+    return keys.length;
+  });
+
+  executeCallback(promise, callback);
+  return promise;
+}
+
+function removeItem(key: string, callback?: (err: any) => void): Promise<void> {
+  key = normalizeKey(key);
+  const promise = this.ready().then(function () {
+    sessionStorage.removeItem(dbInfo.keyPrefix + key);
+  });
+  executeCallback(promise, callback);
+  return promise;
+}
+
+async function setItem<T>(key: string, value: T, callback?: (err: any, value: T) => void): Promise<T> {
+  key = normalizeKey(key);
+  await this.ready();
+
+  value = value ?? (null as unknown as T);
+  const originalValue = value;
+
+  return new Promise<T>((resolve, reject) => {
+    dbInfo.serializer.serialize(value, (serializedValue: string, error: any) => {
+      if (error) {
+        reject(error);
+        executeCallback(Promise.reject(error), callback);
+        return;
+      }
+
+      try {
+        sessionStorage.setItem(dbInfo.keyPrefix + key, serializedValue);
+        resolve(originalValue);
+        executeCallback(Promise.resolve(originalValue), callback);
+      } catch (e: any) {
+        if (e.name === 'QuotaExceededError' || e.name === 'NS_ERROR_DOM_QUOTA_REACHED') {
+          console.error('Your sessionStorage capacity is used up.');
+        }
+        reject(e);
+        executeCallback(Promise.reject(e), callback);
+      }
+    });
+  });
+}
+
+function dropInstance(options: any, callback?: (err: any) => void): Promise<void> {
+  callback = getCallback.apply(this, arguments as any);
+
+  options = (typeof options !== 'function' && options) || {};
+  if (!options.name) {
+    const currentConfig = this.config();
+    options.name = options.name || currentConfig.name;
+    options.storeName = options.storeName || currentConfig.storeName;
+  }
+
+  const self = this;
+  let promise: Promise<void>;
+  if (!options.name) {
+    promise = Promise.reject(new Error('Invalid arguments'));
+  } else {
+    promise = new Promise<string>(function (resolve) {
+      if (!options.storeName) {
+        resolve(`${options.name}/`);
+      } else {
+        resolve(_getKeyPrefix(options, self._defaultConfig));
+      }
+    }).then(function (keyPrefix: string) {
+      for (let i = sessionStorage.length - 1; i >= 0; i--) {
+        const key = sessionStorage.key(i);
+        if (key && key.indexOf(keyPrefix) === 0) {
+          sessionStorage.removeItem(key);
+        }
+      }
+    });
+  }
+
+  executeCallback(promise, callback);
+  return promise;
+}
+
+const sessionStorageWrapper = {
+  _driver: 'sessionStorageWrapper',
+  _initStorage: _initStorage,
+  _support: isSessionStorageValid(),
+  iterate,
+  getItem,
+  setItem,
+  removeItem,
+  clear,
+  length,
+  key,
+  keys,
+  dropInstance,
+};
+
+export default sessionStorageWrapper;

package/src/eventemitter.ts

@@ -0,0 +1,172 @@
+/**
+ * @copyright 2010-2019 Jeremy Ashkenas and DocumentCloud
+ * @copyright 2023 JC Brand
+ */
+import isEmpty from 'lodash-es/isEmpty';
+import keys from 'lodash-es/keys';
+import uniqueId from 'lodash-es/uniqueId';
+import Listening from './listening';
+import { eventsApi, onApi, offApi, onceMap, tryCatchOn, triggerApi } from './utils/events';
+import {
+  ClassConstructor,
+  EventCallback,
+  EventCallbackMap,
+  EventContext,
+  EventHandlersMap,
+  EventListenerMap,
+  ObjectListenedTo,
+} from './types';
+
+// A private global variable to share between listeners and listenees.
+let _listening: Listening | undefined;
+
+/**
+ * @public
+ */
+export function EventEmitter<T extends ClassConstructor>(Base: T) {
+  return class EventEmitter extends Base implements EventEmitter {
+    _events?: EventHandlersMap;
+    _listeners?: EventListenerMap;
+    _listeningTo?: EventListenerMap;
+    _listenId?: string;
+
+    /**
+     * Bind an event to a `callback` function. Passing `"all"` will bind
+     * the callback to all events fired.
+     */
+    on(name: string | EventCallbackMap, callback?: EventCallback | EventContext, context?: EventContext): this {
+      this._events = eventsApi(onApi, this._events || {}, name, callback, {
+        context: context,
+        ctx: this,
+        listening: _listening,
+      }) as EventHandlersMap;
+
+      if (_listening) {
+        const listeners = this._listeners || (this._listeners = {});
+        listeners[_listening.id] = _listening;
+        // Allow the listening to use a counter, instead of tracking
+        // callbacks for library interop
+        _listening.interop = false;
+      }
+
+      return this;
+    }
+
+    /**
+     * Inversion-of-control versions of `on`. Tell *this* object to listen to
+     * an event in another object... keeping track of what it's listening to
+     * for easier unbinding later.
+     */
+    listenTo(obj: ObjectListenedTo, name: string | EventCallbackMap, callback?: EventCallback): this {
+      if (!obj) return this;
+
+      const id = obj._listenId || (obj._listenId = uniqueId('l'));
+      const listeningTo = this._listeningTo || (this._listeningTo = {});
+      let listening = (_listening = listeningTo[id]);
+
+      // This object is not listening to any other events on `obj` yet.
+      // Setup the necessary references to track the listening callbacks.
+      if (!listening) {
+        this._listenId || (this._listenId = uniqueId('l'));
+        listening = _listening = listeningTo[id] = new Listening(this, obj);
+      }
+
+      // Bind callbacks on obj.
+      const error = tryCatchOn(obj, name, callback, this);
+      _listening = undefined;
+
+      if (error) throw error;
+      // If the target obj is not Backbone.Events, track events manually.
+      if (listening.interop) listening.start(name, callback, this, _listening);
+
+      return this;
+    }
+
+    /**
+     * Remove one or many callbacks. If `context` is null, removes all
+     * callbacks with that function. If `callback` is null, removes all
+     * callbacks for the event. If `name` is null, removes all bound
+     * callbacks for all events.
+     */
+    off(
+      name?: string | EventCallbackMap | null,
+      callback?: EventCallback | EventContext | null,
+      context?: EventContext
+    ): this {
+      if (!this._events) return this;
+      this._events = eventsApi(offApi, this._events, name, callback, {
+        context: context,
+        listeners: this._listeners,
+      }) as EventHandlersMap;
+
+      return this;
+    }
+
+    /**
+     * Tell this object to stop listening to either specific events ... or
+     * to every object it's currently listening to.
+     */
+    stopListening(obj?: any, name?: string | EventCallbackMap, callback?: EventCallback): this {
+      const listeningTo = this._listeningTo;
+      if (!listeningTo) return this;
+
+      const ids = obj ? [obj._listenId] : keys(listeningTo);
+      for (let i = 0; i < ids.length; i++) {
+        const listening = listeningTo[ids[i]];
+
+        // If listening doesn't exist, this object is not currently
+        // listening to obj. Break out early.
+        if (!listening) break;
+
+        listening.obj.off(name, callback, this);
+        if (listening.interop) listening.stop(name, callback);
+      }
+      if (isEmpty(listeningTo)) this._listeningTo = undefined;
+
+      return this;
+    }
+
+    /**
+     * Bind an event to only be triggered a single time. After the first time
+     * the callback is invoked, its listener will be removed. If multiple events
+     * are passed in using the space-separated syntax, the handler will fire
+     * once for each event, not once for a combination of all events.
+     */
+    once(name: string | EventCallbackMap, callback?: EventCallback | EventContext, context?: EventContext): this {
+      // Map the event into a `{event: once}` object.
+      const events = eventsApi(onceMap, {}, name, callback, this.off.bind(this));
+      if (typeof name === 'string' && (context === null || context === undefined)) callback = undefined;
+      return this.on(events as EventCallbackMap, callback, context);
+    }
+
+    /**
+     * Inversion-of-control versions of `once`.
+     */
+    listenToOnce(obj: any, name: string | EventCallbackMap, callback?: EventCallback): this {
+      // Map the event into a `{event: once}` object.
+      const events = eventsApi(onceMap, {}, name, callback, this.stopListening.bind(this, obj));
+      return this.listenTo(obj, events as string | EventCallbackMap);
+    }
+
+    /**
+     * Trigger one or many events, firing all bound callbacks. Callbacks are
+     * passed the same arguments as `trigger` is, apart from the event name
+     * (unless you're listening on `"all"`, which will cause your callback to
+     * receive the true name of the event as the first argument).
+     */
+    trigger(name: string, ...args: any[]): this {
+      if (!this._events) return this;
+
+      eventsApi(triggerApi, this._events, name, undefined, args);
+      return this;
+    }
+  };
+}
+
+/**
+ * @public
+ */
+const EventEmitterObject = EventEmitter(Object);
+export { EventEmitterObject };
+
+export default EventEmitter;

package/src/helpers.ts

@@ -0,0 +1,179 @@
+// (c) 2010-2019 Jeremy Ashkenas and DocumentCloud
+// (c) 2018-2025 JC Brand
+import create from 'lodash-es/create';
+import extend from 'lodash-es/extend';
+import has from 'lodash-es/has';
+import result from 'lodash-es/result';
+import { Model } from './model';
+import { Collection } from './collection';
+import { type SyncOptions, SyncOperation } from './types';
+
+/**
+ * Custom error for indicating timeouts
+ * @namespace _converse
+ */
+export class NotImplementedError extends Error {}
+
+function S4(): string {
+  // Generate four random hex digits.
+  return (((1 + Math.random()) * 0x10000) | 0).toString(16).substring(1);
+}
+
+export function guid(): string {
+  // Generate a pseudo-GUID by concatenating random hexadecimal.
+  return S4() + S4() + '-' + S4() + '-' + S4() + '-' + S4() + '-' + S4() + S4() + S4();
+}
+
+// Helpers
+// -------
+
+// Helper function to correctly set up the prototype chain for subclasses.
+// Similar to `goog.inherits`, but uses a hash of prototype properties and
+// class properties to be extended.
+//
+export function inherits<T extends new (...args: any[]) => any>(
+  protoProps: Record<string, any> | null,
+  staticProps?: Record<string, any>
+): T {
+  // eslint-disable-next-line @typescript-eslint/no-this-alias
+  const parent = this;
+  let child: T;
+
+  // The constructor function for the new subclass is either defined by you
+  // (the "constructor" property in your `extend` definition), or defaulted
+  // by us to simply call the parent constructor.
+  if (protoProps && has(protoProps, 'constructor')) {
+    child = protoProps.constructor;
+  } else {
+    child = function (this: any, ...args: any[]) {
+      return parent.apply(this, args);
+    } as unknown as T;
+  }
+
+  // Add static properties to the constructor function, if supplied.
+  extend(child, parent, staticProps);
+
+  // Set the prototype chain to inherit from `parent`, without calling
+  // `parent`'s constructor function and add the prototype properties.
+  child.prototype = create(parent.prototype, protoProps);
+  child.prototype.constructor = child;
+
+  // Set a convenience property in case the parent's prototype is needed
+  // later.
+  (child as any).__super__ = parent.prototype;
+
+  return child;
+}
+
+interface PromiseWrapper {
+  isResolved: boolean;
+  isPending: boolean;
+  isRejected: boolean;
+  resolve: ((value?: any) => void) | null;
+  reject: ((reason?: any) => void) | null;
+}
+
+type ResolveablePromise = Promise<any> & PromiseWrapper;
+
+export function getResolveablePromise(): ResolveablePromise {
+  const wrapper: PromiseWrapper = {
+    isResolved: false,
+    isPending: true,
+    isRejected: false,
+    resolve: null,
+    reject: null,
+  };
+
+  const promise = new Promise((resolve, reject) => {
+    wrapper.resolve = resolve;
+    wrapper.reject = reject;
+  }) as ResolveablePromise;
+
+  Object.assign(promise, wrapper);
+  promise.then(
+    function (v) {
+      promise.isResolved = true;
+      promise.isPending = false;
+      promise.isRejected = false;
+      return v;
+    },
+    function (e) {
+      promise.isResolved = false;
+      promise.isPending = false;
+      promise.isRejected = true;
+      throw e;
+    }
+  );
+  return promise;
+}
+
+// Throw an error when a URL is needed, and none is supplied.
+export function urlError(): never {
+  throw new Error('A "url" property or function must be specified');
+}
+
+// Wrap an optional error callback with a fallback error event.
+export function wrapError(model: Model<any> | Collection<any>, options: any): void {
+  const error = options.error;
+  options.error = function (resp: any) {
+    if (error) error.call(options.context, model, resp, options);
+    model.trigger('error', model, resp, options);
+  };
+}
+
+// Map from CRUD to HTTP for our default `sync` implementation.
+const methodMap: Record<string, string> = {
+  create: 'POST',
+  update: 'PUT',
+  patch: 'PATCH',
+  delete: 'DELETE',
+  read: 'GET',
+};
+
+export function getSyncMethod(model: Model | Collection<any>): typeof sync & { __name__?: string } {
+  const store = result(model, 'browserStorage') || result((model as Model).collection, 'browserStorage');
+  return store ? (store as any).sync() : sync;
+}
+
+/**
+ * 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()`.
+ *
+ * Some possible customizations could be:
+ *
+ * - Use `setTimeout` to batch rapid-fire updates into a single request.
+ * - Persist models via WebSockets instead of Ajax.
+ * - Persist models to browser storage
+ */
+/**
+ * @public
+ */
+export function sync(method: SyncOperation, model: Model | Collection<any>, options: SyncOptions = {}): Promise<any> {
+  let data = options.data;
+
+  // Ensure that we have the appropriate request data.
+  if (data == null && model && (method === 'create' || method === 'update' || method === 'patch')) {
+    data = options.attrs || model.toJSON();
+  }
+
+  const type = methodMap[method];
+  const params: RequestInit & { success?: any; error?: any } = {
+    method: type,
+    body: data ? JSON.stringify(data) : '',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    success: options.success,
+    error: options.error,
+  };
+
+  const url = options.url || result(model, 'url') || urlError();
+  const xhr = fetch(url, params);
+  if (options) {
+    options.xhr = xhr;
+  }
+  model.trigger('request', model, xhr, { ...params, xhr });
+  return xhr;
+}