@converse/skeletor 3.1.2 → 3.1.4

package/dist/skeletor.node.js

@@ -8030,7 +8030,7 @@ class PersistentStorage {
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         const that = this;
         async function localSync(method, model, options) {
-            let resp, errorMessage, promise, new_attributes;
+            let resp, caughtError, promise, new_attributes;
             // 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
@@ -8087,10 +8087,12 @@ class PersistentStorage {
             catch (error) {
                 const storageSize = await that.getStorageSize();
                 if (error.code === 22 && storageSize === 0) {
-                    errorMessage = 'Private browsing is unsupported';
+                    caughtError = new Error('Private browsing is unsupported');
                 }
                 else {
-                    errorMessage = error.message;
+                    // Preserve a real Error (stack/name); wrap anything else so the
+                    // error path always surfaces an Error, never a bare string.
+                    caughtError = error instanceof Error ? error : new Error(error?.message ?? String(error));
                 }
             }
             if (resp) {
@@ -8104,10 +8106,21 @@ class PersistentStorage {
                     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 {
-                errorMessage = errorMessage ? errorMessage : 'Record Not Found';
+                // 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(errorMessage);
+                    options.error(caughtError ?? new Error('Record Not Found'));
                 }
             }
         }
@@ -11046,18 +11059,18 @@ class Model extends EventEmitterObject {
         this.initialize.apply(this, arguments);
         // 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
+        // When autoSync is on, `hydrated` is always a Promise so callers can
+        // uniformly `await model.hydrated`. 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()) {
                 __classPrivateFieldSet(this, _Model_state, 'hydrating', "f");
-                this.initialized = __classPrivateFieldGet(this, _Model_instances, "m", _Model_hydrate).call(this);
+                this.hydrated = __classPrivateFieldGet(this, _Model_instances, "m", _Model_hydrate).call(this);
             }
             else {
                 __classPrivateFieldSet(this, _Model_state, 'ready', "f");
-                this.initialized = Promise.resolve();
+                this.hydrated = Promise.resolve();
             }
         }
         else {
@@ -11230,7 +11243,7 @@ class Model extends EventEmitterObject {
         // 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 && __classPrivateFieldGet(this, _Model_state, "f") === 'hydrating' && !options.fromStorage) {
-            throw new Error(`Skeletor: set() called on an autoSync model before initialized resolved. Await model.initialized first.`);
+            throw new Error(`Skeletor: set() called on an autoSync model before hydration resolved. Await model.hydrated first.`);
         }
         // Run validation.
         if (!this._validate(attrs, options))
@@ -11606,12 +11619,6 @@ _Model_computedCache = new WeakMap(), _Model_computedDefs = new WeakMap(), _Mode
     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 {
         __classPrivateFieldSet(this, _Model_state, 'ready', "f");
     }
@@ -11676,11 +11683,11 @@ class Collection extends EventEmitterObject {
         if (models)
             this.reset(models, Object.assign({ silent: true }, options));
         this[Symbol.iterator] = this.values;
-        // When autoSync is on, `initialized` is always a Promise so callers can
-        // uniformly `await collection.initialized`; it resolves immediately when
+        // When autoSync is on, `hydrated` is always a Promise so callers can
+        // uniformly `await collection.hydrated`; it resolves immediately when
         // there's no storage to hydrate from.
         if (this.autoSync) {
-            this.initialized = getStorage(this) ? __classPrivateFieldGet(this, _Collection_instances, "m", _Collection_hydrate).call(this) : Promise.resolve();
+            this.hydrated = getStorage(this) ? __classPrivateFieldGet(this, _Collection_instances, "m", _Collection_hydrate).call(this) : Promise.resolve();
         }
     }
     get comparator() {
@@ -11712,7 +11719,7 @@ class Collection extends EventEmitterObject {
     }
     /**
      * Override to return `true` to automatically load the collection from
-     * storage on construction. Await `initialized` to know when hydration
+     * storage on construction. Await `hydrated` to know when hydration
      * is complete.
      *
      * Note: collection `autoSync` is hydrate-only. Unlike `Model`, it does
@@ -12386,8 +12393,9 @@ class Collection extends EventEmitterObject {
 }
 _Collection_instances = new WeakSet(), _Collection_hydrate = async function _Collection_hydrate() {
     ensureUnloadListener(PersistentStorage);
-    // findAll() returns [] for an empty store, so a first-run collection
-    // resolves rather than erroring the way a model fetch-by-id would.
+    // An empty store is a normal first-run state: findAll() returns [] and a
+    // missing model record resolves to null, so hydration resolves rather
+    // than rejecting.
     await this.fetch({ fromStorage: true, promise: true });
 }, _a = Symbol.iterator;
 // This "enum" defines the three possible kinds of values which can be emitted

package/dist/skeletor.node.mjs

@@ -8026,7 +8026,7 @@ class PersistentStorage {
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         const that = this;
         async function localSync(method, model, options) {
-            let resp, errorMessage, promise, new_attributes;
+            let resp, caughtError, promise, new_attributes;
             // 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
@@ -8083,10 +8083,12 @@ class PersistentStorage {
             catch (error) {
                 const storageSize = await that.getStorageSize();
                 if (error.code === 22 && storageSize === 0) {
-                    errorMessage = 'Private browsing is unsupported';
+                    caughtError = new Error('Private browsing is unsupported');
                 }
                 else {
-                    errorMessage = error.message;
+                    // Preserve a real Error (stack/name); wrap anything else so the
+                    // error path always surfaces an Error, never a bare string.
+                    caughtError = error instanceof Error ? error : new Error(error?.message ?? String(error));
                 }
             }
             if (resp) {
@@ -8100,10 +8102,21 @@ class PersistentStorage {
                     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 {
-                errorMessage = errorMessage ? errorMessage : 'Record Not Found';
+                // 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(errorMessage);
+                    options.error(caughtError ?? new Error('Record Not Found'));
                 }
             }
         }
@@ -11042,18 +11055,18 @@ class Model extends EventEmitterObject {
         this.initialize.apply(this, arguments);
         // 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
+        // When autoSync is on, `hydrated` is always a Promise so callers can
+        // uniformly `await model.hydrated`. 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()) {
                 __classPrivateFieldSet(this, _Model_state, 'hydrating', "f");
-                this.initialized = __classPrivateFieldGet(this, _Model_instances, "m", _Model_hydrate).call(this);
+                this.hydrated = __classPrivateFieldGet(this, _Model_instances, "m", _Model_hydrate).call(this);
             }
             else {
                 __classPrivateFieldSet(this, _Model_state, 'ready', "f");
-                this.initialized = Promise.resolve();
+                this.hydrated = Promise.resolve();
             }
         }
         else {
@@ -11226,7 +11239,7 @@ class Model extends EventEmitterObject {
         // 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 && __classPrivateFieldGet(this, _Model_state, "f") === 'hydrating' && !options.fromStorage) {
-            throw new Error(`Skeletor: set() called on an autoSync model before initialized resolved. Await model.initialized first.`);
+            throw new Error(`Skeletor: set() called on an autoSync model before hydration resolved. Await model.hydrated first.`);
         }
         // Run validation.
         if (!this._validate(attrs, options))
@@ -11602,12 +11615,6 @@ _Model_computedCache = new WeakMap(), _Model_computedDefs = new WeakMap(), _Mode
     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 {
         __classPrivateFieldSet(this, _Model_state, 'ready', "f");
     }
@@ -11672,11 +11679,11 @@ class Collection extends EventEmitterObject {
         if (models)
             this.reset(models, Object.assign({ silent: true }, options));
         this[Symbol.iterator] = this.values;
-        // When autoSync is on, `initialized` is always a Promise so callers can
-        // uniformly `await collection.initialized`; it resolves immediately when
+        // When autoSync is on, `hydrated` is always a Promise so callers can
+        // uniformly `await collection.hydrated`; it resolves immediately when
         // there's no storage to hydrate from.
         if (this.autoSync) {
-            this.initialized = getStorage(this) ? __classPrivateFieldGet(this, _Collection_instances, "m", _Collection_hydrate).call(this) : Promise.resolve();
+            this.hydrated = getStorage(this) ? __classPrivateFieldGet(this, _Collection_instances, "m", _Collection_hydrate).call(this) : Promise.resolve();
         }
     }
     get comparator() {
@@ -11708,7 +11715,7 @@ class Collection extends EventEmitterObject {
     }
     /**
      * Override to return `true` to automatically load the collection from
-     * storage on construction. Await `initialized` to know when hydration
+     * storage on construction. Await `hydrated` to know when hydration
      * is complete.
      *
      * Note: collection `autoSync` is hydrate-only. Unlike `Model`, it does
@@ -12382,8 +12389,9 @@ class Collection extends EventEmitterObject {
 }
 _Collection_instances = new WeakSet(), _Collection_hydrate = async function _Collection_hydrate() {
     ensureUnloadListener(PersistentStorage);
-    // findAll() returns [] for an empty store, so a first-run collection
-    // resolves rather than erroring the way a model fetch-by-id would.
+    // An empty store is a normal first-run state: findAll() returns [] and a
+    // missing model record resolves to null, so hydration resolves rather
+    // than rejecting.
     await this.fetch({ fromStorage: true, promise: true });
 }, _a = Symbol.iterator;
 // This "enum" defines the three possible kinds of values which can be emitted

package/package.json

@@ -36,7 +36,7 @@
   "contributors": [
     "JC Brand"
   ],
-  "version": "3.1.2",
+  "version": "3.1.4",
   "engines": {
     "node": ">=22.0.0"
   },

package/src/collection.ts

@@ -40,7 +40,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
   _storage?: PersistentStorage;
   _comparator?: Comparator<T>;
   _url: string = '';
-  initialized?: Promise<void>;
+  hydrated?: Promise<void>;
   models: T[];
   protected _byId: Record<string, T>;
   protected _model?: new (attributes?: Partial<ModelAttributes>, options?: ModelOptions) => T;
@@ -61,11 +61,11 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
     if (models) this.reset(models, Object.assign({ silent: true }, options));
 
     this[Symbol.iterator] = this.values;
-    // When autoSync is on, `initialized` is always a Promise so callers can
-    // uniformly `await collection.initialized`; it resolves immediately when
+    // When autoSync is on, `hydrated` is always a Promise so callers can
+    // uniformly `await collection.hydrated`; it resolves immediately when
     // there's no storage to hydrate from.
     if (this.autoSync) {
-      this.initialized = getStorage(this) ? this.#hydrate() : Promise.resolve();
+      this.hydrated = getStorage(this) ? this.#hydrate() : Promise.resolve();
     }
   }
 
@@ -104,7 +104,7 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
 
   /**
    * Override to return `true` to automatically load the collection from
-   * storage on construction. Await `initialized` to know when hydration
+   * storage on construction. Await `hydrated` to know when hydration
    * is complete.
    *
    * Note: collection `autoSync` is hydrate-only. Unlike `Model`, it does
@@ -119,8 +119,9 @@ export class Collection<T extends Model = Model> extends EventEmitterObject {
 
   async #hydrate(): Promise<void> {
     ensureUnloadListener(PersistentStorage);
-    // findAll() returns [] for an empty store, so a first-run collection
-    // resolves rather than erroring the way a model fetch-by-id would.
+    // An empty store is a normal first-run state: findAll() returns [] and a
+    // missing model record resolves to null, so hydration resolves rather
+    // than rejecting.
     await this.fetch({ fromStorage: true, promise: true });
   }
 

package/src/model.ts

@@ -58,7 +58,7 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
   cid: string;
   collection?: Collection;
   id: string | number;
-  initialized?: Promise<void>;
+  hydrated?: Promise<void>;
   validationError: string | number | null = null;
 
   /**
@@ -102,17 +102,17 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     // 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
+    // When autoSync is on, `hydrated` is always a Promise so callers can
+    // uniformly `await model.hydrated`. 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();
+        this.hydrated = this.#hydrate();
       } else {
         this.#state = 'ready';
-        this.initialized = Promise.resolve();
+        this.hydrated = Promise.resolve();
       }
     } else {
       this.#state = 'ready';
@@ -164,10 +164,6 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     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';
     }
@@ -351,7 +347,7 @@ export class Model<T extends ModelAttributes = ModelAttributes> extends EventEmi
     // 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.`,
+        `Skeletor: set() called on an autoSync model before hydration resolved. Await model.hydrated first.`,
       );
     }
 

package/src/storage.ts

@@ -125,7 +125,7 @@ class PersistentStorage {
       if (!NodeSQLiteStorage) {
         throw new Error(
           "Skeletor.storage: the 'node' storage type is only available in Node.js builds. " +
-            "Import from '@converse/skeletor/node' instead of '@converse/skeletor'."
+            "Import from '@converse/skeletor/node' instead of '@converse/skeletor'.",
         );
       }
       this.store = new NodeSQLiteStorage(this.name);
@@ -166,7 +166,7 @@ class PersistentStorage {
     const that = this;
 
     async function localSync(method: SyncOperation, model: Model, options: SyncOptions) {
-      let resp: any, errorMessage: string | undefined, promise: Promise<any>, new_attributes: any;
+      let resp: any, caughtError: Error | undefined, promise: Promise<any>, new_attributes: any;
 
       // We get the collection (and if necessary the model attribute.
       // Waiting for storeInitialized will cause another iteration of
@@ -223,9 +223,11 @@ class PersistentStorage {
       } catch (error: any) {
         const storageSize = await that.getStorageSize();
         if (error.code === 22 && storageSize === 0) {
-          errorMessage = 'Private browsing is unsupported';
+          caughtError = new Error('Private browsing is unsupported');
         } else {
-          errorMessage = error.message;
+          // Preserve a real Error (stack/name); wrap anything else so the
+          // error path always surfaces an Error, never a bare string.
+          caughtError = error instanceof Error ? error : new Error(error?.message ?? String(error));
         }
       }
 
@@ -239,10 +241,20 @@ class PersistentStorage {
           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 {
-        errorMessage = errorMessage ? errorMessage : 'Record Not Found';
+        // 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(errorMessage);
+          options.error(caughtError ?? new Error('Record Not Found'));
         }
       }
     }