@converse/skeletor 3.0.1 → 3.1.0

package/dist/skeletor.d.ts

@@ -1,38 +1,10 @@
 import localForage from 'localforage';
 
 /**
+ * @deprecated Use `PersistentStorage` instead.
  * @public
  */
-export declare 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?: boolean);
-    /**
-     * @param type - The storage type: 'local', 'session', 'indexed', or 'in_memory'
-     * @param batchedWrites - Whether to enable batched writes
-     */
-    initStore(type: 'local' | 'session' | 'indexed' | 'in_memory', batchedWrites: boolean): Promise<void>;
-    flush(): void;
-    clear(): Promise<void>;
-    sync(): {
-        (method: SyncOperation, model: Model, options: SyncOptions): Promise<void>;
-        __name__: string;
-    };
-    removeCollectionReference(model: Model, collection: Collection | undefined): Promise<any> | undefined;
-    addCollectionReference(model: Model, collection: Collection | undefined): Promise<any> | undefined;
-    getCollectionReferenceData(model: Model): Record<string, string[]>;
-    save(model: Model): Promise<any>;
-    create(model: Model, options: SyncOptions): Promise<any>;
-    update(model: Model): Promise<any>;
-    find(model: Model): Promise<any>;
-    findAll(): Promise<any[]>;
-    destroy(model: Model, collection: Collection | undefined): Promise<Model>;
-    getStorageSize(): Promise<number>;
-    getItemName(id: string | number): string;
-}
+export declare const BrowserStorage: typeof PersistentStorage;
 
 /**
  * @public
@@ -49,10 +21,12 @@ export declare type ClassConstructor<T = any> = new (...args: any[]) => T;
  * indexes of their models, both in order, and for lookup by `id`.
  */
 export declare class Collection<T extends Model = Model> extends EventEmitterObject {
+    #private;
     [key: symbol]: () => CollectionIterator<T>;
-    _browserStorage?: BrowserStorage;
+    _storage?: PersistentStorage;
     _comparator?: Comparator<T>;
     _url: string;
+    initialized?: Promise<void>;
     models: T[];
     protected _byId: Record<string, T>;
     protected _model?: new (attributes?: Partial<ModelAttributes>, options?: ModelOptions) => T;
@@ -64,8 +38,29 @@ export declare class Collection<T extends Model = Model> extends EventEmitterObj
     constructor(models?: T[] | ModelAttributes[] | T | ModelAttributes, options?: CollectionOptions<T>);
     get comparator(): Comparator<T>;
     set comparator(c: Comparator<T>);
-    set browserStorage(storage: BrowserStorage);
-    get browserStorage(): BrowserStorage | undefined;
+    /**
+     * The canonical storage accessor. Set to a `PersistentStorage` instance
+     * to enable local persistence for this collection.
+     */
+    get storage(): PersistentStorage | undefined;
+    set storage(s: PersistentStorage);
+    /**
+     * @deprecated Use `storage` instead.
+     */
+    get browserStorage(): PersistentStorage | undefined;
+    set browserStorage(s: PersistentStorage);
+    /**
+     * Override to return `true` to automatically load the collection from
+     * storage on construction. Await `initialized` to know when hydration
+     * is complete.
+     *
+     * Note: collection `autoSync` is hydrate-only. Unlike `Model`, it does
+     * **not** schedule auto-saves when the collection changes (`add`/`remove`/
+     * `reset`). Persisting members is each model's responsibility — enable
+     * `autoSync` on the contained model class and every model writes its own
+     * record. A collection-level write would be redundant with that.
+     */
+    get autoSync(): boolean;
     /**
      * The default model for a collection is just a **Model**.
      * This should be overridden in most cases.
@@ -207,6 +202,17 @@ export declare class Collection<T extends Model = Model> extends EventEmitterObj
      * wait for the server to agree.
      */
     create(model: T | ModelAttributes, options?: FetchOrCreateOptions): Promise<T> | T;
+    /**
+     * Subscribe to collection changes (add, remove, reset, sort, update).
+     * Returns an unsubscribe function.
+     *
+     * `collection.subscribe(callback)` — fires once per operation on add/remove/reset/sort (via `update`, `reset`, `sort` events).
+     * `collection.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: (collection: this) => void): () => void;
     /**
      * **parse** converts a response into a list of models to be added to the
      * collection. The default implementation is just to pass it through.
@@ -296,6 +302,19 @@ export declare type CollectionOptions<T extends Model = Model> = Options & {
  */
 export declare type Comparator<T extends Model = Model> = string | boolean | ((a: T, b: T) => number) | ((a?: T) => string);
 
+/**
+ * @public
+ */
+export declare type ComputedProperties<M> = Record<string, ComputedProperty<M>>;
+
+/**
+ * @public
+ */
+export declare type ComputedProperty<M> = {
+    deps: string[];
+    fn: (model: M) => any;
+};
+
 /**
  * @public
  */
@@ -362,6 +381,11 @@ export declare function EventEmitter<T extends ClassConstructor>(Base: T): {
          * receive the true name of the event as the first argument).
          */
         trigger(name: string, ...args: any[]): /*elided*/ any;
+        /**
+         * Subscribe to an event. Returns an unsubscribe function.
+         * Compatible with `useSyncExternalStore` and other store-style APIs.
+         */
+        subscribe(event: string, callback: EventCallback, context?: EventContext): () => void;
     };
 } & T;
 
@@ -416,6 +440,11 @@ export declare const EventEmitterObject: {
          * receive the true name of the event as the first argument).
          */
         trigger(name: string, ...args: any[]): /*elided*/ any;
+        /**
+         * Subscribe to an event. Returns an unsubscribe function.
+         * Compatible with `useSyncExternalStore` and other store-style APIs.
+         */
+        subscribe(event: string, callback: EventCallback, context?: EventContext): () => void;
     };
 } & ObjectConstructor;
 
@@ -442,11 +471,22 @@ export declare interface EventHandlersMap {
  */
 export declare type EventListenerMap = Record<string, ListeningType>;
 
+/**
+ * @public
+ */
 export declare type FetchOrCreateOptions = Options & {
     promise?: boolean;
     success?: (m: Model, resp: any, callbackOpts: Options) => void;
 };
 
+/**
+ * Return the PersistentStorage instance configured on `obj`, checking both
+ * the canonical `storage` accessor and the deprecated `browserStorage` alias
+ * so that subclasses that still override `get browserStorage()` continue to work.
+ * @public
+ */
+export declare function getStorage(obj: Model<any> | Collection<any> | null | undefined): PersistentStorage | undefined;
+
 /**
  * @public
  */
@@ -484,25 +524,6 @@ export declare interface ListeningType {
     stop(name: string | EventCallbackMap, callback: EventCallback): void;
 }
 
-/**
- * @public
- */
-export declare 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
  * **Models** are the basic data object in the framework --
@@ -511,25 +532,47 @@ export declare interface LocalForageWithExtensions {
  * performing computations and transformations on that data.
  */
 export declare class Model<T extends ModelAttributes = ModelAttributes> extends EventEmitterObject {
-    _browserStorage?: BrowserStorage;
+    #private;
+    _storage?: PersistentStorage;
     _changing: boolean;
     _pending: boolean | ModelOptions;
     _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;
     /**
      * 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);
-    set browserStorage(storage: BrowserStorage);
-    get browserStorage(): BrowserStorage | undefined;
+    /**
+     * The canonical storage accessor. Set to a `PersistentStorage` instance
+     * to enable local persistence for this model.
+     */
+    get storage(): PersistentStorage | undefined;
+    set storage(s: PersistentStorage);
+    /**
+     * @deprecated Use `storage` instead.
+     */
+    get browserStorage(): PersistentStorage | undefined;
+    set browserStorage(s: PersistentStorage);
+    /**
+     * 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;
+    /**
+     * Debounce delay (ms) for auto-save writes. Override to tune.
+     */
+    get autoSyncDelay(): number;
     /**
      * 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
@@ -556,6 +599,15 @@ export declare class Model<T extends ModelAttributes = ModelAttributes> extends
      * Return a hash of defaults for the model's attributes.
      */
     defaults(): 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 a copy of the model's `attributes` object.
      */
@@ -565,7 +617,7 @@ export declare class Model<T extends ModelAttributes = ModelAttributes> extends
      */
     sync(method: SyncOperation, model: Model<any>, options: Options): any;
     /**
-     * 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];
     keys(): string[];
@@ -663,6 +715,16 @@ export declare class Model<T extends ModelAttributes = ModelAttributes> extends
      * Check if the model is currently in a valid state.
      */
     isValid(options?: ModelOptions): boolean;
+    /**
+     * 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;
     /**
      * Run validation against the next complete set of model attributes,
      * returning `true` if all is well. Otherwise, fire an `"invalid"` event.
@@ -686,6 +748,10 @@ export declare 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;
 };
 
 /**
@@ -712,6 +778,50 @@ export declare type ObjectWithId = Record<string, any> & {
  */
 export declare type Options = Record<string, any>;
 
+/**
+ * @public
+ */
+export declare class PersistentStorage {
+    storeInitialized: Promise<void>;
+    storeReady: boolean;
+    store: StorageDriver;
+    name: string;
+    static sessionStorageInitialized: Promise<void>;
+    static localForage: typeof localForage;
+    /** Register a storage instance with a weak reference. @public */
+    static register(instance: PersistentStorage): void;
+    /**
+     * 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;
+    constructor(id: string, type: StoreType | StorageDriver, batchedWrites?: boolean);
+    /**
+     * @param type - The storage type: 'local', 'session', 'indexed', 'node', or 'in_memory'
+     * @param batchedWrites - Whether to enable batched writes
+     */
+    initStore(type: StoreType, batchedWrites: boolean): Promise<void>;
+    flush(): void;
+    clear(): Promise<void>;
+    sync(): {
+        (method: SyncOperation, model: Model, options: SyncOptions): Promise<void>;
+        __name__: string;
+    };
+    removeCollectionReference(model: Model, collection: Collection | undefined): Promise<any> | undefined;
+    addCollectionReference(model: Model, collection: Collection | undefined): Promise<any> | undefined;
+    getCollectionReferenceData(model: Model): Record<string, string[]>;
+    save(model: Model): Promise<any>;
+    create(model: Model, options: SyncOptions): Promise<any>;
+    update(model: Model): Promise<any>;
+    find(model: Model): Promise<any>;
+    findAll(): Promise<any[]>;
+    destroy(model: Model, collection: Collection | undefined): Promise<Model>;
+    getStorageSize(): Promise<number>;
+    getItemName(id: string | number): string;
+}
+
 /**
  * @public
  */
@@ -730,6 +840,32 @@ export declare interface SkeletorType {
     noConflict?: () => SkeletorType;
 }
 
+/**
+ * Storage driver interface for key-value persistence.
+ * @public
+ */
+export declare interface StorageDriver {
+    ready(): Promise<void>;
+    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 | null>;
+    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
+ */
+export declare type StoreType = 'local' | 'session' | 'indexed' | 'in_memory' | 'node';
+
 /**
  * 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
@@ -763,6 +899,7 @@ export declare interface SyncOptions {
     error?: (error: any) => void;
     xhr?: any;
     wait?: boolean;
+    collection?: Collection;
 }
 
 export { }