@converse/skeletor 3.0.1 → 3.1.0

package/src/model.ts

@@ -1,4 +1,12 @@
-import { getResolveablePromise, getSyncMethod, urlError, wrapError } from './helpers';
+import {
+  getResolveablePromise,
+  getStorage,
+  getSyncMethod,
+  urlError,
+  warnBrowserStorageDeprecation,
+  wrapError,
+} from './helpers';
+import { scheduleAutoSave, cancelAutoSave, awaitInFlightSaves, ensureUnloadListener } from './autosync';
 import clone from 'lodash-es/clone';
 import defaults from 'lodash-es/defaults';
 import defer from 'lodash-es/defer';
@@ -12,11 +20,20 @@ import pick from 'lodash-es/pick';
 import result from 'lodash-es/result';
 import uniqueId from 'lodash-es/uniqueId';
 import { EventEmitterObject } from './eventemitter';
+import PersistentStorage from './storage';
 
 // Import types
 import type { Collection } from './collection';
-import type Storage from './storage';
-import { ModelAttributes, ObjectWithId, SyncOperation, ModelOptions, Options } from './types';
+import {
+  ComputedProperties,
+  ComputedProperty,
+  EventCallback,
+  ModelAttributes,
+  ObjectWithId,
+  SyncOperation,
+  ModelOptions,
+  Options,
+} from './types';
 
 /**
  * @public
@@ -26,17 +43,22 @@ import { ModelAttributes, ObjectWithId, SyncOperation, ModelOptions, Options } f
  * performing computations and transformations on that data.
  */
 export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmitterObject {
-  _browserStorage?: Storage;
+  #computedCache?: Record<string, any>;
+  #computedDefs?: Record<string, ComputedProperty<this>>;
+  #state: 'constructing' | 'hydrating' | 'ready' = 'constructing';
+  _storage?: PersistentStorage;
   _changing = false;
   _pending: boolean | ModelOptions = false;
   _previousAttributes?: T;
   _url: string = '';
   _urlRoot: string;
+  attrs: T;
   attributes: T;
   changed: Partial<T> = {};
   cid: string;
   collection?: Collection;
   id: string | number;
+  initialized?: Promise<void>;
   validationError: string | number | null = null;
 
   /**
@@ -60,18 +82,99 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
 
     this.set(attrs, options);
 
+    this.#initComputed();
+
+    this.attrs = new Proxy(this.attributes as T, {
+      get: (_target, key) => {
+        if (typeof key !== 'symbol' && this.#computedCache && (key as string) in this.#computedCache) {
+          return this.#computedCache[key as string];
+        }
+        return (this.attributes as any)[key];
+      },
+      set: (_target, key, value) => {
+        this.set(key as string, value);
+        return true;
+      },
+    });
+
     this.initialize.apply(this, arguments as any);
 
     // Reset changed after initial set
     this.changed = {};
+
+    // When autoSync is on, `initialized` is always a Promise so callers can
+    // uniformly `await model.initialized`. It only hydrates from storage when
+    // there's something to load (storage configured and the model isn't new);
+    // otherwise it's already ready and resolves immediately.
+    if (this.autoSync) {
+      if (getStorage(this) && !this.isNew()) {
+        this.#state = 'hydrating';
+        this.initialized = this.#hydrate();
+      } else {
+        this.#state = 'ready';
+        this.initialized = Promise.resolve();
+      }
+    } else {
+      this.#state = 'ready';
+    }
   }
 
-  set browserStorage(storage: Storage) {
-    this._browserStorage = storage;
+  /**
+   * The canonical storage accessor. Set to a `PersistentStorage` instance
+   * to enable local persistence for this model.
+   */
+  get storage(): PersistentStorage | undefined {
+    return this._storage;
   }
 
-  get browserStorage(): Storage | undefined {
-    return this._browserStorage;
+  set storage(s: PersistentStorage) {
+    this._storage = s;
+    PersistentStorage.register(s);
+  }
+
+  /**
+   * @deprecated Use `storage` instead.
+   */
+  get browserStorage(): PersistentStorage | undefined {
+    return this._storage;
+  }
+
+  set browserStorage(s: PersistentStorage) {
+    warnBrowserStorageDeprecation(this);
+    this.storage = s;
+  }
+
+  /**
+   * Override to enable automatic persistence. When true, any `set()` call
+   * that changes attributes will schedule a debounced save to `storage`, and
+   * the model will auto-hydrate from storage on construction.
+   */
+  get autoSync(): boolean {
+    return false;
+  }
+
+  /**
+   * Debounce delay (ms) for auto-save writes. Override to tune.
+   */
+  get autoSyncDelay(): number {
+    return 100;
+  }
+
+  async #hydrate(): Promise<void> {
+    ensureUnloadListener(PersistentStorage);
+    try {
+      await this.fetch({ fromStorage: true, promise: true });
+    } catch (e) {
+      // 'Record Not Found' is a normal first-run state (nothing stored yet);
+      // keep the initial attributes and resolve. Re-throw anything else.
+      if (e !== 'Record Not Found') throw e;
+    } finally {
+      this.#state = 'ready';
+    }
+  }
+
+  #doAutoSave(): unknown {
+    return this.save(null, { noAutoSave: true });
   }
 
   /**
@@ -114,6 +217,39 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     return {} as Partial<T>;
   }
 
+  /**
+   * Declare computed properties. Override in subclasses to define properties
+   * that derive their value from other attributes. Each entry specifies the
+   * attribute keys it depends on (`deps`) and a function (`fn`) that receives
+   * the model and returns the computed value. The value is cached and
+   * recalculated automatically when any dep changes, firing a `change:key`
+   * event.
+   */
+  get computed(): ComputedProperties<this> {
+    return {};
+  }
+
+  #updateComputed(key: string, def: ComputedProperty<this>, silent: boolean, options: ModelOptions): void {
+    const newVal = def.fn(this);
+    if (!isEqual(this.#computedCache[key], newVal)) {
+      this.#computedCache[key] = newVal;
+      if (!silent) {
+        (this.changed as any)[key] = newVal;
+        this.trigger('change:' + key, this, newVal, options);
+      }
+    }
+  }
+
+  #initComputed(): void {
+    const defs = result(this, 'computed') as ComputedProperties<this>;
+    if (!defs || isEmpty(defs)) return;
+    this.#computedDefs = defs;
+    this.#computedCache = {};
+    for (const [key, def] of Object.entries(defs)) {
+      this.#computedCache[key] = def.fn(this);
+    }
+  }
+
   /**
    * Return a copy of the model's `attributes` object.
    */
@@ -129,9 +265,12 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
   }
 
   /**
-   * Get the value of an attribute.
+   * Get the value of an attribute, or a computed property.
    */
   get<K extends keyof T>(attr: K): T[K] {
+    if (this.#computedCache && (attr as string) in this.#computedCache) {
+      return this.#computedCache[attr as string];
+    }
     return this.attributes[attr];
   }
 
@@ -208,6 +347,14 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
 
     options = options || {};
 
+    // Guard must come after arg normalization: when called as set(obj, opts),
+    // fromStorage lives in `val` (second arg), not `options` (third arg).
+    if (this.autoSync && this.#state === 'hydrating' && !options.fromStorage) {
+      throw new Error(
+        `Skeletor: set() called on an autoSync model before initialized resolved. Await model.initialized first.`,
+      );
+    }
+
     // Run validation.
     if (!this._validate(attrs, options)) return null;
 
@@ -250,6 +397,15 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
       }
     }
 
+    // Recalculate computed properties whose deps changed.
+    if (changes.length && this.#computedDefs) {
+      for (const [key, def] of Object.entries(this.#computedDefs)) {
+        if (def.deps.some((dep) => changes.includes(dep))) {
+          this.#updateComputed(key, def, silent, options);
+        }
+      }
+    }
+
     if (changing) return this;
 
     if (!silent) {
@@ -263,6 +419,21 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     }
     this._pending = false;
     this._changing = false;
+
+    // Auto-save: schedule a debounced write when autoSync is on and there
+    // were actual changes that originated from application code (not a
+    // storage read or an explicit noAutoSave call).
+    if (
+      this.#state === 'ready' &&
+      this.autoSync &&
+      getStorage(this) &&
+      changes.length &&
+      !options.fromStorage &&
+      !options.noAutoSave
+    ) {
+      scheduleAutoSave(this, () => this.#doAutoSave(), this.autoSyncDelay);
+    }
+
     return this;
   }
 
@@ -342,16 +513,50 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     options = Object.assign({ parse: true }, options);
 
     const success = options.success;
+    const promise = options.promise ? getResolveablePromise() : undefined;
+
+    // Tracks whether sync invoked one of the callbacks. A sync may instead
+    // settle its returned promise; the `.then`/`.catch` below bridges that to
+    // the callbacks so the fetch promise never hangs. The flag is set
+    // synchronously inside each callback (before sync's promise resolves), so
+    // it's reliable by the time those handlers run.
+    let settled = false;
 
     options.success = (resp: any) => {
+      settled = true;
       const serverAttrs = options.parse ? this.parse(resp, options) : resp;
-      if (!this.set(serverAttrs, options)) return false;
+      // fromStorage prevents the set() from triggering auto-save on reads
+      if (!this.set(serverAttrs, Object.assign({}, options, { fromStorage: true }))) return false;
       if (success) success.call(options.context, this, resp, options);
       this.trigger('sync', this, resp, options);
+      promise && promise.resolve(resp);
     };
 
-    wrapError(this, options);
-    return this.sync('read', this, options);
+    wrapError(this, options, promise);
+    if (promise) {
+      const onError = options.error;
+      options.error = (resp: any) => {
+        settled = true;
+        onError(resp);
+      };
+    }
+
+    const result = this.sync('read', this, options);
+    if (promise) {
+      Promise.resolve(result).then(
+        // A sync that resolves its promise without invoking options.success:
+        // treat the resolved value as the response, so the model is still
+        // merged and the promise settles instead of hanging.
+        (value) => {
+          if (!settled) options.success(value);
+        },
+        // A sync that rejects instead of invoking options.error; settling
+        // twice is a harmless no-op.
+        (e) => promise.reject(e),
+      );
+      return promise;
+    }
+    return result;
   }
 
   /**
@@ -431,6 +636,7 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
    * If `wait: true` is passed, waits for the server to respond before removal.
    */
   destroy(options?: ModelOptions): any {
+    cancelAutoSave(this);
     options = options ? clone(options) : {};
     const success = options.success;
     const wait = options.wait;
@@ -446,12 +652,24 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
       if (!this.isNew()) this.trigger('sync', this, resp, options);
     };
 
+    // A debounced auto-save may already have fired and be in flight.
+    // cancelAutoSave() above only stops a *pending* timer, so sequence the
+    // delete after any in-flight save; otherwise the late write could land
+    // after the delete and resurrect the record. Capture the collection now,
+    // the optimistic in-memory removal below nulls `model.collection` before
+    // the deferred sync runs, but the storage layer still needs it to drop
+    // this id from the collection's persisted index.
+    const inFlightSave = awaitInFlightSaves(this);
+    if (inFlightSave && this.collection) options.collection = this.collection;
+
     let xhr: any = false;
     if (this.isNew()) {
       defer(options.success);
     } else {
       wrapError(this, options);
-      xhr = this.sync('delete', this, options);
+      xhr = inFlightSave
+        ? inFlightSave.then(() => this.sync('delete', this, options))
+        : this.sync('delete', this, options);
     }
     if (!wait) destroy();
     return xhr;
@@ -505,6 +723,29 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     return this._validate({}, Object.assign({}, options, { validate: true }));
   }
 
+  /**
+   * Subscribe to model changes. Returns an unsubscribe function.
+   *
+   * `model.subscribe(callback)` — fires on any attribute change, receives `(model, changed)`.
+   * `model.subscribe(event, callback)` — subscribe to a specific event (base EventEmitter form).
+   *
+   * Compatible with React's `useSyncExternalStore` and other store-style APIs.
+   */
+  subscribe(event: string, callback: EventCallback, context?: unknown): () => void;
+  subscribe(callback: (model: this, changed: Partial<T>) => void): () => void;
+  subscribe(
+    eventOrCallback: string | ((model: this, changed: Partial<T>) => void),
+    callback?: EventCallback,
+    context?: unknown,
+  ): () => void {
+    if (typeof eventOrCallback === 'function') {
+      const cb = (model: this) => (eventOrCallback as (model: this, changed: Partial<T>) => void)(model, this.changed);
+      this.on('change', cb);
+      return () => this.off('change', cb);
+    }
+    return super.subscribe(eventOrCallback, callback, context);
+  }
+
   /**
    * Run validation against the next complete set of model attributes,
    * returning `true` if all is well. Otherwise, fire an `"invalid"` event.

package/src/storage.ts

@@ -13,54 +13,76 @@ import { guid } from './helpers';
 import type { Model } from './model';
 import type { Collection } from './collection';
 import type { SyncOptions, SyncOperation } from './types';
+import { StorageDriver, StoreType } from './drivers/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;
-  };
-}
+// Every storage instance is registered with a WeakRef so that flushAll() can
+// reach pending writes without keeping instances alive. There's no leak and no
+// lifecycle hook to maintain: an instance is collected once its owning model or
+// collection is gone, at which point nothing is writing through it anyway.
+// Models with a pending debounced save stay reachable via the autosync `pending`
+// map until the timer fires, so flushAll() always reaches in-flight writes.
+const weakInstances = new Set<WeakRef<PersistentStorage>>();
+
+// Tracks which instances already have a WeakRef in `weakInstances`, so repeated
+// `storage =` assignments (or a store shared across models) don't register the
+// same instance twice and make flushAll() flush it more than once.
+const registered = new WeakSet<PersistentStorage>();
 
 /**
  * @public
  */
-class BrowserStorage {
+class PersistentStorage {
   storeInitialized: Promise<void>;
-  store: LocalForageWithExtensions;
+  // Set once `storeInitialized` resolves. Lets `sync()` skip awaiting it on the
+  // hot path so a save buffers/issues its write *synchronously*, which is what
+  // makes the synchronous unload flush (`flushPending` -> `flushAll`) able to
+  // push a pending write out before the page is torn down.
+  storeReady = false;
+  store: StorageDriver;
   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) {
+  /** Register a storage instance with a weak reference. @public */
+  static register(instance: PersistentStorage): void {
+    if (registered.has(instance)) return;
+    registered.add(instance);
+    weakInstances.add(new WeakRef(instance));
+  }
+
+  /**
+   * Flush the debounced write buffer of every registered PersistentStorage
+   * instance. Called automatically on pagehide/visibilitychange when autoSync
+   * is in use; can also be called manually.
+   * @public
+   */
+  static flushAll(): void {
+    for (const ref of weakInstances) {
+      const instance = ref.deref();
+      if (!instance) {
+        weakInstances.delete(ref);
+      } else {
+        instance.flush();
+      }
+    }
+  }
+
+  constructor(id: string, type: StoreType | StorageDriver, batchedWrites = false) {
+    this.name = id;
+
+    if (type === 'local' && typeof window !== 'undefined' && !window.localStorage) {
       throw new Error('Skeletor.storage: Environment does not support localStorage.');
-    } else if (type === 'session' && !window.sessionStorage) {
+    } else if (type === 'session' && typeof window !== 'undefined' && !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);
+      this.storeInitialized = this.initStore(type as StoreType, batchedWrites);
     } else {
       this.store = type;
       if (batchedWrites) {
@@ -70,24 +92,36 @@ class BrowserStorage {
       }
       this.storeInitialized = Promise.resolve();
     }
-    this.name = id;
+    // Flip the synchronous-readiness flag once init settles. Callers that await
+    // `storeInitialized` directly still see any rejection; this branch only
+    // exists to set the flag and must not raise an unhandled rejection.
+    this.storeInitialized.then(() => (this.storeReady = true)).catch(() => {});
   }
 
   /**
-   * @param type - The storage type: 'local', 'session', 'indexed', or 'in_memory'
+   * @param type - The storage type: 'local', 'session', 'indexed', 'node', or 'in_memory'
    * @param batchedWrites - Whether to enable batched writes
    */
-  async initStore(type: 'local' | 'session' | 'indexed' | 'in_memory', batchedWrites: boolean): Promise<void> {
+  async initStore(type: StoreType, 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 === 'node') {
+      const { NodeSQLiteStorage } = await import('./drivers/nodeSQLiteStorage');
+      this.store = new NodeSQLiteStorage(this.name);
+      if (batchedWrites) {
+        this.store.debouncedSetItems = mergebounce((items: Record<string, any>) => this.store.setItems!(items), 50, {
+          'promise': true,
+        });
+      }
+      return;
     } else if (type !== 'indexed') {
       throw new Error('Skeletor.storage: No storage type was specified');
     }
-    this.store = localForage as LocalForageWithExtensions;
+    this.store = localForage as StorageDriver;
     if (batchedWrites) {
       this.store.debouncedSetItems = mergebounce((items: Record<string, any>) => this.store.setItems!(items), 50, {
         'promise': true,
@@ -102,6 +136,7 @@ class BrowserStorage {
   }
 
   async clear(): Promise<void> {
+    await this.storeInitialized;
     await this.store.removeItem(this.name).catch((e) => console.error(e));
     const re = new RegExp(`^${this.name}-`);
     const keys = await this.store.keys();
@@ -119,12 +154,17 @@ class BrowserStorage {
       // 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;
+      // be removed from the model. `options.collection` lets a deferred
+      // delete (sequenced behind an in-flight auto-save by Model.destroy)
+      // supply the collection captured before its optimistic removal.
+      const collection = options.collection ?? model.collection;
       if (['patch', 'update'].includes(method)) {
         new_attributes = cloneDeep(model.attributes);
       }
-      await that.storeInitialized;
+
+      // Skip `await` if not necessary to allow for sync flushing
+      if (!that.storeReady) await that.storeInitialized;
+
       try {
         const original_attributes = model.attributes;
         switch (method) {
@@ -288,6 +328,6 @@ class BrowserStorage {
   }
 }
 
-BrowserStorage.sessionStorageInitialized = localForage.defineDriver(sessionStorageWrapper);
-BrowserStorage.localForage = localForage;
-export default BrowserStorage;
+PersistentStorage.sessionStorageInitialized = localForage.defineDriver(sessionStorageWrapper);
+PersistentStorage.localForage = localForage;
+export default PersistentStorage;

package/src/types.ts

@@ -1,5 +1,5 @@
-import {Collection} from './collection';
-import {Model} from './model';
+import { Collection } from './collection';
+import { Model } from './model';
 
 /**
  * @public
@@ -9,7 +9,7 @@ export type SyncOperation = 'create' | 'update' | 'patch' | 'delete' | 'read';
 /**
  * @public
  */
-export type ObjectListenedTo = object & {_listenId?: string};
+export type ObjectListenedTo = object & { _listenId?: string };
 
 /**
  * @public
@@ -22,6 +22,11 @@ export interface SyncOptions {
   error?: (error: any) => void;
   xhr?: any;
   wait?: boolean;
+  // Lets `Model.destroy` pass the collection captured before its optimistic
+  // (synchronous) in-memory removal nulled `model.collection`, so the storage
+  // layer can still drop the id from the collection's persisted index even
+  // when the delete is deferred behind an in-flight auto-save.
+  collection?: Collection;
 }
 
 /**
@@ -70,7 +75,7 @@ export type ListeningMap = Record<string, ListeningType>;
 /**
  * @public
  */
-export type ObjectWithId = Record<string, any> & {id: string | number};
+export type ObjectWithId = Record<string, any> & { id: string | number };
 
 /**
  * @public
@@ -85,7 +90,7 @@ export interface IEventEmitter {
   off(
     name?: string | EventCallbackMap | null,
     callback?: EventCallback | EventContext | null,
-    context?: EventContext
+    context?: EventContext,
   ): this;
   trigger(name: string, ...args: any[]): this;
   stopListening(obj?: any, name?: string | EventCallbackMap, callback?: EventCallback): this;
@@ -135,7 +140,7 @@ export interface EventsApiOptions {
  */
 export interface OffApiOptions {
   context?: any;
-  listeners?: {[key: string]: ListeningType};
+  listeners?: { [key: string]: ListeningType };
 }
 
 /**
@@ -155,21 +160,37 @@ export type IterateeFunction = (
   eventsOrMap: EventCallbackMap | EventHandlersMap,
   name: string | null,
   callback: EventCallback | EventHandler | null,
-  options: EventsApiOptions | OffApiOptions | OfferFunction | any[]
+  options: EventsApiOptions | OffApiOptions | OfferFunction | any[],
 ) => EventCallbackMap | EventHandlersMap | void;
 
 /**
  * @public
  */
-export type ModelAttributes = Record<string | number, any> & {id?: string | number};
+export type ComputedProperty<M> = {
+  deps: string[];
+  fn: (model: M) => any;
+};
+
+/**
+ * @public
+ */
+export type ComputedProperties<M> = Record<string, ComputedProperty<M>>;
+
+/**
+ * @public
+ */
+export type ModelAttributes = Record<string | number, any> & { id?: string | number };
 
 /**
  * @public
  */
 export type Options = Record<string, any>;
 
+/**
+ * @public
+ */
 export type FetchOrCreateOptions = Options & {
-  promise?: boolean,
+  promise?: boolean;
   success?: (m: Model, resp: any, callbackOpts: Options) => void;
 };
 
@@ -191,4 +212,8 @@ export type ModelOptions = Options & {
   unset?: boolean;
   silent?: boolean;
   validate?: boolean;
+  /** Suppress the auto-save triggered by set() on autoSync models. */
+  noAutoSave?: boolean;
+  /** Mark a set() call as originating from a storage read; suppresses auto-save. */
+  fromStorage?: boolean;
 };