@converse/skeletor 3.0.0 → 3.1.0

package/src/drivers/nodeSQLiteStorage.ts

@@ -0,0 +1,162 @@
+import { DatabaseSync, type StatementSync } from 'node:sqlite';
+import fsMod from 'node:fs';
+import pathMod from 'node:path';
+import { normalizeKey, serializeSync, deserialize, sanitizePathSegment } from './helpers';
+import { StorageDriver } from './types';
+
+const DEFAULT_BASE_DIR = '.skeletor-storage';
+
+/**
+ * SQLite-backed implementation of StorageDriver.
+ * Uses a single table with key/value columns, storing values as JSON strings.
+ */
+export class NodeSQLiteStorage implements StorageDriver {
+  private db: DatabaseSync;
+  private stmt: {
+    insert: StatementSync;
+    select: StatementSync;
+    delete: StatementSync;
+    clear: StatementSync;
+    count: StatementSync;
+    keyByIndex: StatementSync;
+    keys: StatementSync;
+    getItems: StatementSync;
+  };
+
+  ready(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  debouncedSetItems?: {
+    (items: Record<string, any>): Promise<void>;
+    flush?: () => void;
+  };
+
+  constructor(name: string, storageDir?: string, inMemory?: boolean) {
+    if (inMemory) {
+      this.db = new DatabaseSync(':memory:');
+    } else {
+      const safeName = sanitizePathSegment(name);
+      const baseDir = storageDir || DEFAULT_BASE_DIR;
+      const dbFilePath = pathMod.join(baseDir, `${safeName}.db`);
+
+      // Ensure parent directory exists
+      const dir = pathMod.dirname(dbFilePath);
+      if (!fsMod.existsSync(dir)) {
+        fsMod.mkdirSync(dir, { recursive: true });
+      }
+
+      this.db = new DatabaseSync(dbFilePath);
+    }
+    // Use DELETE journal mode (default, no separate WAL files)
+    this.db.exec('PRAGMA journal_mode=DELETE');
+    // Enable busy timeout
+    this.db.exec('PRAGMA busy_timeout=5000');
+
+    // Create the kv table if it doesn't exist
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS kv (
+        key   TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      ) STRICT
+    `);
+
+    // Prepare all statements once
+    this.stmt = {
+      insert: this.db.prepare('INSERT OR REPLACE INTO kv (key, value) VALUES (?, ?)'),
+      select: this.db.prepare('SELECT value FROM kv WHERE key = ?'),
+      delete: this.db.prepare('DELETE FROM kv WHERE key = ?'),
+      clear: this.db.prepare('DELETE FROM kv'),
+      count: this.db.prepare('SELECT COUNT(*) as count FROM kv'),
+      keyByIndex: this.db.prepare('SELECT key FROM kv ORDER BY key LIMIT 1 OFFSET ?'),
+      keys: this.db.prepare('SELECT key FROM kv ORDER BY key'),
+      getItems: this.db.prepare('SELECT key, value FROM kv WHERE key IN (SELECT value FROM json_each(?))'),
+    };
+  }
+
+  setItem(key: string, value: any): Promise<any> {
+    key = normalizeKey(key);
+    const coerced = value ?? null;
+    this.stmt.insert.run(key, serializeSync(coerced));
+    return Promise.resolve(value);
+  }
+
+  getItem<T>(key: string): Promise<T | null> {
+    key = normalizeKey(key);
+    const row = this.stmt.select.get(key) as { value: string } | undefined;
+    if (!row) {
+      return Promise.resolve(null);
+    }
+    return Promise.resolve(deserialize<T>(row.value));
+  }
+
+  removeItem(key: string): Promise<void> {
+    key = normalizeKey(key);
+    this.stmt.delete.run(key);
+    return Promise.resolve();
+  }
+
+  clear(): Promise<void> {
+    this.stmt.clear.run();
+    return Promise.resolve();
+  }
+
+  length(): Promise<number> {
+    const row = this.stmt.count.get() as { count: number };
+    return Promise.resolve(row.count);
+  }
+
+  key(n: number): Promise<string | null> {
+    const row = this.stmt.keyByIndex.get(n) as { key: string } | undefined;
+    return Promise.resolve(row ? row.key : null);
+  }
+
+  keys(): Promise<string[]> {
+    const rows = this.stmt.keys.all() as Array<{ key: string }>;
+    return Promise.resolve(rows.map((r) => r.key));
+  }
+
+  setItems(items: Record<string, any>): Promise<void> {
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      for (const [key, value] of Object.entries(items)) {
+        const normalizedKey = normalizeKey(key);
+        const coerced = value ?? null;
+        this.stmt.insert.run(normalizedKey, serializeSync(coerced));
+      }
+      this.db.exec('COMMIT');
+    } catch (e) {
+      try {
+        this.db.exec('ROLLBACK');
+      } catch (rollbackError) {
+        // If ROLLBACK fails, attach it as cause to the original error
+        // This preserves the root cause while providing full context
+        if (e instanceof Error && rollbackError instanceof Error) {
+          (e as Error & { cause?: Error }).cause = rollbackError;
+        }
+      }
+      throw e;
+    }
+    return Promise.resolve();
+  }
+
+  getItems(keys: string[]): Promise<Record<string, any>> {
+    if (keys.length === 0) {
+      return Promise.resolve({});
+    }
+    const keysJson = JSON.stringify(keys);
+    const rows = this.stmt.getItems.all(keysJson) as Array<{ key: string; value: string }>;
+    const result: Record<string, any> = {};
+    for (const row of rows) {
+      result[row.key] = deserialize(row.value);
+    }
+    return Promise.resolve(result);
+  }
+
+  /**
+   * Close the database connection. Useful for cleanup in tests.
+   */
+  close(): void {
+    this.db.close();
+  }
+}

package/src/drivers/sessionStorage.ts

@@ -14,13 +14,7 @@
 // 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'];
+import { chainCallback, getCallback, normalizeKey, serialize, deserialize } from './helpers';
 
 interface DbInfo {
   keyPrefix: string;
@@ -92,7 +86,7 @@ function clear(callback?: (err: any) => void): Promise<void> {
     }
   });
 
-  executeCallback(promise, callback);
+  chainCallback(promise, callback);
   return promise;
 }
 
@@ -111,13 +105,13 @@ function getItem<T>(key: string, callback?: (err: any, value: T | null) => void)
     return null;
   });
 
-  executeCallback(promise, callback);
+  chainCallback(promise, callback);
   return promise;
 }
 
 function iterate<T, U>(
   iterator: IteratorCallback<T, U>,
-  callback?: (err: any, result: U | undefined) => void
+  callback?: (err: any, result: U | undefined) => void,
 ): Promise<U | undefined> {
   const self = this;
 
@@ -148,7 +142,7 @@ function iterate<T, U>(
     return;
   });
 
-  executeCallback(promise, callback);
+  chainCallback(promise, callback);
   return promise;
 }
 
@@ -171,7 +165,7 @@ function key(n: number, callback?: (err: any, key: string | null) => void): Prom
     return result;
   });
 
-  executeCallback(promise, callback);
+  chainCallback(promise, callback);
   return promise;
 }
 
@@ -190,7 +184,7 @@ function keys(callback?: (err: any, keys: string[]) => void): Promise<string[]>
     return keys;
   });
 
-  executeCallback(promise, callback);
+  chainCallback(promise, callback);
   return promise;
 }
 
@@ -201,7 +195,7 @@ function length(callback?: (err: any, numberOfKeys: number) => void): Promise<nu
     return keys.length;
   });
 
-  executeCallback(promise, callback);
+  chainCallback(promise, callback);
   return promise;
 }
 
@@ -210,7 +204,7 @@ function removeItem(key: string, callback?: (err: any) => void): Promise<void> {
   const promise = this.ready().then(function () {
     sessionStorage.removeItem(dbInfo.keyPrefix + key);
   });
-  executeCallback(promise, callback);
+  chainCallback(promise, callback);
   return promise;
 }
 
@@ -225,29 +219,29 @@ async function setItem<T>(key: string, value: T, callback?: (err: any, value: T)
     dbInfo.serializer.serialize(value, (serializedValue: string, error: any) => {
       if (error) {
         reject(error);
-        executeCallback(Promise.reject(error), callback);
+        chainCallback(Promise.reject(error), callback);
         return;
       }
 
       try {
         sessionStorage.setItem(dbInfo.keyPrefix + key, serializedValue);
         resolve(originalValue);
-        executeCallback(Promise.resolve(originalValue), callback);
+        chainCallback(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);
+        chainCallback(Promise.reject(e), callback);
       }
     });
   });
 }
 
-function dropInstance(options: any, callback?: (err: any) => void): Promise<void> {
-  callback = getCallback.apply(this, arguments as any);
+function dropInstance(this: any, ...args: any[]): Promise<void> {
+  const callback = getCallback(...args);
 
-  options = (typeof options !== 'function' && options) || {};
+  let options = (typeof args[0] !== 'function' && args[0]) || {};
   if (!options.name) {
     const currentConfig = this.config();
     options.name = options.name || currentConfig.name;
@@ -275,7 +269,7 @@ function dropInstance(options: any, callback?: (err: any) => void): Promise<void
     });
   }
 
-  executeCallback(promise, callback);
+  chainCallback(promise, callback);
   return promise;
 }
 

package/src/drivers/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Storage driver interface for key-value persistence.
+ * @public
+ */
+export 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 type StoreType = 'local' | 'session' | 'indexed' | 'in_memory' | 'node';

package/src/eventemitter.ts

@@ -160,6 +160,15 @@ export function EventEmitter<T extends ClassConstructor>(Base: T) {
       eventsApi(triggerApi, this._events, name, undefined, args);
       return this;
     }
+
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     * Compatible with `useSyncExternalStore` and other store-style APIs.
+     */
+    subscribe(event: string, callback: EventCallback, context?: EventContext): () => void {
+      this.on(event, callback, context);
+      return () => this.off(event, callback, context);
+    }
   };
 }
 

package/src/helpers.ts

@@ -7,6 +7,7 @@ import result from 'lodash-es/result';
 import { Model } from './model';
 import { Collection } from './collection';
 import { type SyncOptions, SyncOperation } from './types';
+import type PersistentStorage from './storage';
 
 /**
  * Custom error for indicating timeouts
@@ -33,7 +34,7 @@ export function guid(): string {
 //
 export function inherits<T extends new (...args: any[]) => any>(
   protoProps: Record<string, any> | null,
-  staticProps?: Record<string, any>
+  staticProps?: Record<string, any>,
 ): T {
   // eslint-disable-next-line @typescript-eslint/no-this-alias
   const parent = this;
@@ -90,19 +91,21 @@ export function getResolveablePromise(): ResolveablePromise {
   }) as ResolveablePromise;
 
   Object.assign(promise, wrapper);
+  // This `then` only mirrors settlement into the state flags. It must NOT
+  // rethrow on rejection: the derived promise is discarded, so rethrowing would
+  // surface as an unhandled rejection whenever the promise is rejected. The real
+  // consumer still awaits `promise` itself, which rejects normally.
   promise.then(
-    function (v) {
+    function () {
       promise.isResolved = true;
       promise.isPending = false;
       promise.isRejected = false;
-      return v;
     },
-    function (e) {
+    function () {
       promise.isResolved = false;
       promise.isPending = false;
       promise.isRejected = true;
-      throw e;
-    }
+    },
   );
   return promise;
 }
@@ -112,12 +115,19 @@ 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 {
+// Wrap an optional error callback with a fallback error event. When a
+// `promise` is supplied (the `{ promise: true }` fetch/save path), the error is
+// also forwarded to `promise.reject` so the returned promise settles on failure.
+export function wrapError(
+  model: Model<any> | Collection<any>,
+  options: any,
+  promise?: ResolveablePromise,
+): 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);
+    promise && promise.reject && promise.reject(resp);
   };
 }
 
@@ -130,9 +140,46 @@ const methodMap: Record<string, string> = {
   read: 'GET',
 };
 
+// Tracks the classes we've already warned about, so the `browserStorage`
+// deprecation notice is logged at most once per class rather than once per
+// instance (a collection can resolve storage once per contained model).
+const warnedBrowserStorage = new WeakSet<object>();
+
+/**
+ * Emit a one-time-per-class deprecation warning nudging downstream code from
+ * the `browserStorage` alias to the canonical `storage` accessor.
+ */
+export function warnBrowserStorageDeprecation(obj: Model<any> | Collection<any>): void {
+  const ctor = obj?.constructor;
+  if (!ctor || warnedBrowserStorage.has(ctor)) return;
+  warnedBrowserStorage.add(ctor);
+  const name = (ctor as { name?: string }).name;
+  console.warn(
+    `Skeletor: \`browserStorage\` is deprecated and will be removed in a future major version; ` +
+      `use \`storage\` instead${name ? ` (on \`${name}\`)` : ''}.`,
+  );
+}
+
+/**
+ * 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 function getStorage(obj: Model<any> | Collection<any> | null | undefined): PersistentStorage | undefined {
+  if (!obj) return undefined;
+  const storage = result(obj, 'storage') as PersistentStorage | undefined;
+  if (storage != null) return storage;
+  // Fall back to the deprecated alias; warn only when it actually supplies the
+  // store, so storage-less models/collections don't trip the notice.
+  const legacy = result(obj, 'browserStorage') as PersistentStorage | undefined;
+  if (legacy != null) warnBrowserStorageDeprecation(obj);
+  return legacy;
+}
+
 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;
+  const store = getStorage(model) || getStorage((model as Model).collection);
+  return store ? store.sync() : sync;
 }
 
 /**

package/src/index.node.ts

@@ -0,0 +1,8 @@
+/**
+ * Node.js entry point for @converse/skeletor.
+ * Re-exports everything from the browser entry and additionally
+ * exports the NodeSQLiteStorage LocalForage implementation.
+ */
+export * from './index';
+export { default } from './index';
+export { NodeSQLiteStorage } from './drivers/nodeSQLiteStorage';

package/src/index.ts

@@ -1,6 +1,6 @@
 /* global global */
 import { EventEmitter } from './eventemitter';
-import BrowserStorage from './storage';
+import PersistentStorage from './storage';
 import { Collection } from './collection';
 import { Model } from './model';
 import { sync } from './helpers';
@@ -54,12 +54,20 @@ skeletor.noConflict = noConflict;
 root.Skeletor = skeletor;
 export default skeletor;
 
-export { noConflict, Collection, EventEmitter, Model, BrowserStorage, sync };
+/**
+ * @deprecated Use `PersistentStorage` instead.
+ * @public
+ */
+const BrowserStorage = PersistentStorage;
+export { noConflict, Collection, EventEmitter, Model, PersistentStorage, BrowserStorage, sync };
+export { getStorage } from './helpers';
 
-export type { LocalForageWithExtensions } from './storage';
+export type { StorageDriver, StoreType } from './drivers/types';
 export type {
   ClassConstructor,
   CollectionOptions,
+  ComputedProperties,
+  ComputedProperty,
   Comparator,
   EventCallback,
   EventCallbackMap,