@converse/skeletor 3.1.4 → 3.1.6

package/package.json

@@ -10,15 +10,18 @@
   "exports": {
     ".": {
       "node": {
+        "types": "./dist/skeletor.node.d.ts",
         "require": "./dist/skeletor.node.js",
         "import": "./dist/skeletor.node.mjs"
       },
       "default": {
+        "types": "./dist/skeletor.d.ts",
         "import": "./dist/skeletor.esm.js",
         "require": "./dist/skeletor.js"
       }
     },
     "./node": {
+      "types": "./dist/skeletor.node.d.ts",
       "require": "./dist/skeletor.node.js",
       "import": "./dist/skeletor.node.mjs"
     }
@@ -36,7 +39,7 @@
   "contributors": [
     "JC Brand"
   ],
-  "version": "3.1.4",
+  "version": "3.1.6",
   "engines": {
     "node": ">=22.0.0"
   },
@@ -47,7 +50,7 @@
   },
   "scripts": {
     "build": "npm run prebuild && npm run build:declarations && rollup -c",
-    "build:declarations": "npm run build:types && api-extractor run --local && rm -rf dist/defs",
+    "build:declarations": "npm run build:types && api-extractor run --local && api-extractor run --local -c api-extractor.node.json && rm -rf dist/defs",
     "build:types": "tsc -p tsconfig.declarations.json",
     "check": "npm run check:types && npm run test && npm run test:node && npm run lint",
     "check:types": "tsc --noEmit",
@@ -72,6 +75,7 @@
     "dist/skeletor.node.mjs",
     "dist/skeletor.d.ts",
     "dist/skeletor.d.ts.map",
+    "dist/skeletor.node.d.ts",
     "src/**/*.ts"
   ],
   "dependencies": {

package/src/declarations.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@converse/localforage-getitems` ships its types as an ambient script that
+ * declares the *unscoped* module name (`localforage-getitems`), left over from
+ * the package it was forked from. TypeScript therefore resolves the scoped
+ * specifier to a `typings/index.d.ts` that isn't a module (TS2306), so declare
+ * the shape we use here instead.
+ */
+declare module '@converse/localforage-getitems' {
+  export function extendPrototype<T>(localforage: T): T;
+  export const extendPrototypeResult: boolean;
+}

package/src/drivers/nodeSQLiteStorage.ts

@@ -9,6 +9,7 @@ const DEFAULT_BASE_DIR = '.skeletor-storage';
 /**
  * SQLite-backed implementation of StorageDriver.
  * Uses a single table with key/value columns, storing values as JSON strings.
+ * @public
  */
 export class NodeSQLiteStorage implements StorageDriver {
   private db: DatabaseSync;
@@ -27,11 +28,6 @@ export class NodeSQLiteStorage implements StorageDriver {
     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:');
@@ -116,7 +112,7 @@ export class NodeSQLiteStorage implements StorageDriver {
     return Promise.resolve(rows.map((r) => r.key));
   }
 
-  setItems(items: Record<string, any>): Promise<void> {
+  setItems(items: Record<string, any>): Promise<Record<string, any>> {
     this.db.exec('BEGIN IMMEDIATE');
     try {
       for (const [key, value] of Object.entries(items)) {
@@ -137,7 +133,7 @@ export class NodeSQLiteStorage implements StorageDriver {
       }
       throw e;
     }
-    return Promise.resolve();
+    return Promise.resolve(items);
   }
 
   getItems(keys: string[]): Promise<Record<string, any>> {

package/src/drivers/types.ts

@@ -11,10 +11,16 @@ export interface StorageDriver {
   length(): Promise<number>;
   key(keyIndex: number): Promise<string | null>;
   keys(): Promise<string[]>;
-  setItems?(items: Record<string, any>): Promise<void>;
+  /**
+   * Write several items in one go. A successful write is signalled by the
+   * promise settling, not by what it resolves with: drivers may resolve with
+   * the written items (localForage does) or with nothing, and callers must
+   * treat both as success.
+   */
+  setItems?(items: Record<string, any>): Promise<Record<string, any> | void>;
   getItems?(keys: string[]): Promise<Record<string, any>>;
   debouncedSetItems?: {
-    (items: Record<string, any>): Promise<void>;
+    (items: Record<string, any>): Promise<Record<string, any> | void>;
     flush?: () => void;
   };
 }

package/src/index.ts

@@ -63,6 +63,7 @@ export { noConflict, Collection, EventEmitter, Model, PersistentStorage, Browser
 export { getStorage } from './helpers';
 
 export type { StorageDriver, StoreType } from './drivers/types';
+export type { NodeStorageConstructor } from './storage';
 export type {
   ClassConstructor,
   CollectionOptions,

package/src/storage.ts

@@ -8,7 +8,7 @@ import localForage from 'localforage';
 import mergebounce from 'mergebounce';
 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 { extendPrototype as extendPrototypeWithGetItems } from '@converse/localforage-getitems';
 import { guid } from './helpers';
 import type { Model } from './model';
 import type { Collection } from './collection';
@@ -36,8 +36,13 @@ const registered = new WeakSet<PersistentStorage>();
 /**
  * Constructor for a Node.js-only storage driver. Registered by the
  * `@converse/skeletor/node` entry point via {@link PersistentStorage.nodeStorage}.
+ * @public
  */
-type NodeStorageConstructor = new (name: string) => StorageDriver;
+export type NodeStorageConstructor = new (
+  name: string,
+  storageDir?: string,
+  inMemory?: boolean,
+) => StorageDriver;
 
 /**
  * @public
@@ -60,6 +65,19 @@ class PersistentStorage {
   // bundle; the `@converse/skeletor/node` entry sets it.
   static nodeStorage: NodeStorageConstructor | null = null;
 
+  /**
+   * Directory the `'node'` store type writes its database files to. The driver's
+   * own default is relative, so it resolves against `process.cwd()` and a process
+   * started from two directories ends up with two separate sets of state. Set an
+   * absolute path (`$XDG_STATE_HOME/<app>`, say) to pin it. Left `null`, the
+   * driver's default applies.
+   *
+   * Only the `'node'` string store type reads this; passing a driver instance to
+   * the constructor means you've already chosen a directory yourself.
+   * @public
+   */
+  static nodeStorageDir: string | null = null;
+
   /** Register a storage instance with a weak reference. @public */
   static register(instance: PersistentStorage): void {
     if (registered.has(instance)) return;
@@ -128,7 +146,7 @@ class PersistentStorage {
             "Import from '@converse/skeletor/node' instead of '@converse/skeletor'.",
         );
       }
-      this.store = new NodeSQLiteStorage(this.name);
+      this.store = new NodeSQLiteStorage(this.name, PersistentStorage.nodeStorageDir ?? undefined);
       if (batchedWrites) {
         this.store.debouncedSetItems = mergebounce((items: Record<string, any>) => this.store.setItems!(items), 50, {
           'promise': true,
@@ -155,9 +173,11 @@ class PersistentStorage {
   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();
     const removed_keys = keys.filter((k) => re.test(k));
+
     await Promise.all(removed_keys.map((k) => this.store.removeItem(k).catch((e) => console.error(e))));
   }
 
@@ -231,31 +251,16 @@ class PersistentStorage {
         }
       }
 
-      if (resp) {
-        if (options && options.success) {
-          // When storing, we don't pass back the response (which is
-          // the set attributes returned from localforage because
-          // Skeletor sets them again on the model and due to the async
-          // nature of localforage it can cause stale attributes to be
-          // set on a model after it's been updated in the meantime.
-          const data = method === 'read' ? resp : null;
-          options.success(data, options);
-        }
-      } else if (method === 'read' && !caughtError) {
-        // A read that finds no record is a normal empty result (first run /
-        // empty storage), not an error. Resolve with `null` so the callback
-        // and promise forms of fetch() agree and a first-run read never
-        // rejects.
-        if (options && options.success) {
-          options.success(null, options);
-        }
-      } else {
-        // A genuine failure (storage threw, or a write produced no result):
-        // surface a real Error so consumers get a stack and `instanceof Error`
-        // holds.
-        if (options && options.error) {
-          options.error(caughtError ?? new Error('Record Not Found'));
-        }
+      if (caughtError) {
+        options?.error?.(caughtError);
+      } else if (options?.success) {
+        // When storing, we don't pass back the response (which is the set
+        // attributes returned from localforage) because Skeletor sets them
+        // again on the model and due to the async nature of localforage it can
+        // cause stale attributes to be set on a model after it's been updated
+        // in the meantime.
+        const data = method === 'read' ? (resp ?? null) : null;
+        options.success(data, options);
       }
     }
     localSync.__name__ = 'localSync';