@jqhtml/core 2.3.68 → 2.3.71

package/dist/load-coordinator.d.ts

@@ -17,6 +17,15 @@
  * 3. Leader completes → distribute data to all followers
  * 4. Clear coordination entry (no caching)
  *
+ * The hand-off is a copy, and it is made by the cache serializer
+ * (Jqhtml_Local_Storage.serialize()/deserialize()), never by JSON.stringify.
+ * A follower never runs on_load() and never revalidates, so whatever it is
+ * handed is final: the copy has to rebuild Date, Map, Set and every
+ * register_cache_class() instance exactly as the leader's this.data holds them.
+ * JSON.stringify would consult toJSON() and hand out a wire form that
+ * normalize_for_cache() cannot recognise - the follower would then render
+ * against plain objects while the leader renders against instances.
+ *
  * @internal This class is not exposed in the public API
  */
 import type { Jqhtml_Component } from './component.js';

package/dist/load-coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-coordinator.d.ts","sourceRoot":"","sources":["../src/load-coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAcvD,MAAM,WAAW,mBAAmB;IAChC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACjC;;;;;;;;;;;OAWG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACzC;AAED,qBAAa,gBAAgB;IACzB,OAAO,CAAC,MAAM,CAAC,SAAS,CAA6C;IAErE;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,uBAAuB,CAC1B,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,GAAG,EACT,OAAO,GAAE,oBAAyB,GACnC,mBAAmB;IAkGtB;;;;;;;OAOG;IACH,MAAM,CAAC,sBAAsB,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAmBhF;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAClB,SAAS,EAAE,gBAAgB,EAC3B,GAAG,EAAE,MAAM,GACZ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI;IA6B5C;;;OAGG;IACH,MAAM,CAAC,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAUlE;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAkCrC;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAsC5F;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IA8B3D;;OAEG;IACH,MAAM,CAAC,kBAAkB,IAAI,GAAG;IAahC;;OAEG;IACH,MAAM,CAAC,SAAS,IAAI,IAAI;CAG3B"}
+{"version":3,"file":"load-coordinator.d.ts","sourceRoot":"","sources":["../src/load-coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAkBvD,MAAM,WAAW,mBAAmB;IAChC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACjC;;;;;;;;;;;OAWG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACzC;AAED,qBAAa,gBAAgB;IACzB,OAAO,CAAC,MAAM,CAAC,SAAS,CAA6C;IAErE;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,uBAAuB,CAC1B,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,GAAG,EACT,OAAO,GAAE,oBAAyB,GACnC,mBAAmB;IAkGtB;;;;;;;OAOG;IACH,MAAM,CAAC,sBAAsB,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAmBhF;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAClB,SAAS,EAAE,gBAAgB,EAC3B,GAAG,EAAE,MAAM,GACZ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI;IA6B5C;;;OAGG;IACH,MAAM,CAAC,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAUlE;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAiCrC;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAuC5F;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IA8B3D;;OAEG;IACH,MAAM,CAAC,kBAAkB,IAAI,GAAG;IAahC;;OAEG;IACH,MAAM,CAAC,SAAS,IAAI,IAAI;CAG3B"}

package/dist/local-storage.d.ts

@@ -16,7 +16,19 @@
  * ES6 class instances can be serialized and deserialized if registered via
  * register_cache_class(). Classes are wrapped as {__jqhtml_class__: "Name", __jqhtml_props__: {...}}
  * and restored to proper instances on retrieval. Nested class instances in objects
- * and arrays are handled recursively.
+ * and arrays are handled recursively. A class whose wire form is not its own
+ * properties (one that defines toJSON(), or keeps state in private fields)
+ * registers a {to_plain, from_plain} pair and is rebuilt through it. Date, Map and
+ * Set are pre-registered the same way - there is no second mechanism.
+ *
+ * ONE SERIALIZER. Every copy of on_load() data the framework makes goes through
+ * this file: the localStorage cache (set()/get()), the normalization of every
+ * on_load() result into this.data (normalize_for_cache()), and the copy a
+ * deduplicated follower takes of its leader's data (serialize()/deserialize(),
+ * used by load-coordinator.ts). Anything that survives one of those survives all
+ * of them, and anything dropped is dropped identically on all of them. A plain
+ * JSON.stringify anywhere on those paths would consult toJSON() and hand out a
+ * wire form nothing knows how to restore.
  *
  * Scoping Strategy:
  * Storage is scoped by a user-provided cache key (typically a session identifier,
@@ -92,14 +104,40 @@
  *       silently. Neither ever throws.
  * ---------------------------------------------------------------------------
  */
+/**
+ * How a registered class travels through the serializer.
+ *
+ * With no options, an instance's own enumerable properties go out and come back
+ * through Object.create(prototype) + Object.assign - right for a class whose
+ * state IS its own properties.
+ *
+ * A class whose wire form is something else names how to rebuild itself:
+ *
+ *   to_plain(instance)  -> the plain value to store. Default when from_plain is
+ *                          given: instance.toJSON() if the class defines one,
+ *                          otherwise its own enumerable properties. The result is
+ *                          walked by the serializer like any other value, so
+ *                          instances nested inside it are handled too.
+ *   from_plain(plain)   -> a live instance. Required whenever to_plain is given,
+ *                          because the serializer cannot guess how to undo a
+ *                          custom wire form.
+ */
+export interface Cache_Class_Options<T = any> {
+    to_plain?: (instance: T) => any;
+    from_plain?: (plain: any) => T;
+}
 /**
  * Register a class for cache serialization/deserialization.
  * Must be called before attempting to cache instances of this class.
  *
  * @param klass - The class constructor to register
- * @throws Error if klass is not a named function/class
+ * @param options - How to convert instances to and from their plain form; see
+ *                  Cache_Class_Options. Omit for a class whose state is its own
+ *                  enumerable properties.
+ * @throws Error if klass is not a named function/class, or if to_plain is given
+ *         without the from_plain that undoes it
  */
-export declare function register_cache_class(klass: new (...args: any[]) => any): void;
+export declare function register_cache_class(klass: new (...args: any[]) => any, options?: Cache_Class_Options): void;
 /**
  * Check if a class is registered for caching
  */
@@ -108,7 +146,7 @@ export declare function is_cache_class_registered(class_name: string): boolean;
  * What kind of value the serializer had to drop or degrade. Reported to a
  * collector; each kind maps to one piece of advice in strip_advice().
  */
-export type Strip_Kind = 'function' | 'promise' | 'dom-node' | 'jquery' | 'component' | 'symbol' | 'bigint' | 'circular' | 'unregistered-class';
+export type Strip_Kind = 'function' | 'promise' | 'dom-node' | 'jquery' | 'component' | 'symbol' | 'bigint' | 'circular' | 'unregistered-class' | 'to-plain-threw';
 /** Called once per dropped/degraded value with its path and what it was. */
 export type Strip_Collector = (path: string, kind: Strip_Kind, detail?: string) => void;
 /**
@@ -214,6 +252,25 @@ export declare class Jqhtml_Local_Storage {
      * @param {string} key - Storage key
      */
     static remove(key: string): void;
+    /**
+     * Serialize a value to its class-aware TEXT form - the same text set() stores.
+     *
+     * This is the copy-by-value primitive the rest of the framework uses whenever
+     * data has to cross from one component to another (load-coordinator.ts hands a
+     * leader's data to its followers through it). Plain JSON.stringify is not a
+     * substitute: it consults toJSON() and produces a wire form that deserialize()
+     * cannot recognise, so a registered class would come back as a plain object.
+     *
+     * @returns The text, or null when the value as a whole cannot be expressed.
+     */
+    static serialize(value: any): string | null;
+    /**
+     * Rebuild a value from text produced by serialize(), restoring Date, Map, Set
+     * and every register_cache_class() class. Returns null when the text is not
+     * restorable (a registered from_plain threw at the root) - the same signal
+     * get() gives for a corrupt entry.
+     */
+    static deserialize(text: string): any;
     /**
      * Perform a serialize/deserialize round-trip on a value.
      *

package/dist/local-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-storage.d.ts","sourceRoot":"","sources":["../src/local-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AAkBH;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GAAG,IAAI,CAK7E;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAErE;AAMD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAChB,UAAU,GACV,SAAS,GACT,UAAU,GACV,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,oBAAoB,CAAC;AAE3B,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AA+axF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAuB;IAChD,2FAA2F;IAC3F,OAAO,CAAC,MAAM,CAAC,aAAa,CAAuB;IACnD,OAAO,CAAC,MAAM,CAAC,WAAW,CAAqB;IAC/C,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAwB;IACzD,OAAO,CAAC,MAAM,CAAC,YAAY,CAAkB;IAE7C;;;;;OAKG;IACH,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,GAAE,SAAkB,GAAG,IAAI;IAa7E;;;OAGG;IACH,MAAM,CAAC,aAAa,IAAI,OAAO;IAI/B;;;OAGG;IACH,MAAM,CAAC,cAAc,IAAI,SAAS;IAIlC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,KAAK;IAepB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAYpC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAI1B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IA4B9B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IA2BjC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU;IAIzB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IAIxB;;;;;;;;OAQG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAkDzC;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAoCnC;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQhC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,GAAG,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,GAAG;IA4BpE;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IA+BxB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;CAS9B"}
+{"version":3,"file":"local-storage.d.ts","sourceRoot":"","sources":["../src/local-storage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jqhtml/core",
-  "version": "2.3.68",
+  "version": "2.3.71",
   "description": "Core runtime library for JQHTML",
   "type": "module",
   "main": "./dist/index.js",