@converse/skeletor 3.1.2 → 3.1.4

package/CHANGES.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 3.1.4 (2026-06-23)
+
+- Fix the `autoSync` hydration promise clobbering a consumer's own `initialized` promise.
+  The promise that resolves once hydration is complete is now exposed as `hydrated` (on both
+  `Model` and `Collection`) instead of `initialized`. The old name collided with the common
+  convention (used by Converse.js) of setting a `model.initialized` promise inside
+  `initialize()` to track a consumer's own async setup.
+
+  Skeletor no longer sets or reads `initialized`. Await `model.hydrated` / `collection.hydrated`
+  to know when hydration is complete. If you used the autoSync `initialized` promise added
+  in 3.1.0, rename those reads to `hydrated`.
+
+## 3.1.3 (2026-06-23)
+
+- Fix a regression (since 3.1.0) where a missing record on a `read` was treated as an error.
+  `model.fetch({ promise: true })` rejected with the bare string `'Record Not Found'` on a
+  first-run read of a non-existent record (and the `error` callback / `'error'` event fired),
+  where previously 3.0.x had resolved. A read miss is a normal empty state, so it now
+  resolves with `null` on both the callback (`success`) and promise forms.
+
+  **Behaviour change:** a read miss no longer fires the `error` callback or the `'error'` event,
+  it fires `success(null)` instead.
+
+- Storage-layer `sync` failures now surface a real `Error` (with a stack) through the `error`
+  callback / rejected promise instead of a bare string. The internal `Model#hydrate`
+  `'Record Not Found'` string-match workaround is removed accordingly.
+
 ## 3.1.2 (2026-06-22)
 
 - Fix the published package missing its `dist/` directory. `dist/` is gitignored and nothing built

package/README.md

@@ -159,7 +159,7 @@ class Settings extends Model {
 }
 
 const settings = new Settings({ id: 'main' });
-await settings.initialized; // resolves when prior data has been loaded
+await settings.hydrated; // resolves when prior data has been loaded
 
 settings.attrs.theme = 'dark'; // persisted automatically (debounced)
 settings.set('lang', 'en'); // also auto-saved
@@ -171,7 +171,8 @@ settings.set('transient', true, { noAutoSave: true });
 Pending writes are debounced (see `autoSyncDelay`, default 100ms) and flushed when the
 page is hidden (`visibilitychange`) or unloaded (`pagehide`).
 
-When `autoSync` is off, `initialized` is `undefined`, but `await model.initialized` is still safe (awaiting `undefined` is a no-op), so code can await it uniformly.
+When `autoSync` is off, `hydrated` is `undefined`, but `await model.hydrated` is still safe
+(awaiting `undefined` is a no-op), so code can await it uniformly.
 
 On a `Collection`, `autoSync` is **hydrate-only**: the collection loads its stored
 state on construction but does not auto-save on `add`/`remove`/`reset`. To persist

package/dist/skeletor.d.ts

@@ -26,7 +26,7 @@ export declare class Collection<T extends Model = Model> extends EventEmitterObj
     _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;
@@ -51,7 +51,7 @@ export declare class Collection<T extends Model = Model> extends EventEmitterObj
     set browserStorage(s: PersistentStorage);
     /**
      * 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
@@ -545,7 +545,7 @@ export declare class Model<T extends ModelAttributes = ModelAttributes> extends
     cid: string;
     collection?: Collection;
     id: string | number;
-    initialized?: Promise<void>;
+    hydrated?: Promise<void>;
     validationError: string | number | null;
     /**
      * Create a new model with the specified attributes. A client id (`cid`)

package/dist/skeletor.esm.js

@@ -8705,7 +8705,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
@@ -8762,10 +8762,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) {
@@ -8779,10 +8781,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'));
                 }
             }
         }
@@ -10894,18 +10907,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 {
@@ -11078,7 +11091,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))
@@ -11454,12 +11467,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");
     }
@@ -11524,11 +11531,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() {
@@ -11560,7 +11567,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
@@ -12234,8 +12241,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