@jqhtml/core 2.3.10 → 2.3.13

package/dist/local-storage.d.ts

@@ -10,6 +10,13 @@
  * - **Quota management**: Auto-clears storage when full and retries operation
  * - **Scope validation**: Clears storage when cache key changes
  * - **Developer-friendly keys**: Scoped suffix allows easy inspection in dev tools
+ * - **Class-aware serialization**: ES6 class instances serialize and restore properly
+ *
+ * Class-Aware Serialization:
+ * 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.
  *
  * Scoping Strategy:
  * Storage is scoped by a user-provided cache key (typically a session identifier,
@@ -31,13 +38,20 @@
  * once. This ensures the application continues functioning even when storage is full.
  *
  * Usage:
+ *   // Register classes that need to be cached (call once at startup)
+ *   jqhtml.register_cache_class(Contact_Model);
+ *   jqhtml.register_cache_class(User_Profile);
+ *
  *   // Must set cache key first (typically done once on page load)
  *   Jqhtml_Local_Storage.set_cache_key('user_123');
  *
- *   // Then use storage normally
- *   Jqhtml_Local_Storage.set('cached_component', {html: '...', timestamp: Date.now()});
+ *   // Then use storage normally - ES6 classes serialize automatically
+ *   Jqhtml_Local_Storage.set('cached_component', {
+ *     contact: new Contact_Model(),
+ *     timestamp: Date.now()
+ *   });
  *   const cached = Jqhtml_Local_Storage.get('cached_component');
- *   Jqhtml_Local_Storage.remove('cached_component');
+ *   // cached.contact instanceof Contact_Model === true
  *
  * IMPORTANT - Volatile Storage:
  * Storage can be cleared at any time due to:
@@ -53,21 +67,53 @@
  *
  * @internal This class is not exposed in the public API
  */
+/**
+ * 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
+ */
+export declare function register_cache_class(klass: new (...args: any[]) => any): void;
+/**
+ * Check if a class is registered for caching
+ */
+export declare function is_cache_class_registered(class_name: string): boolean;
+/**
+ * Cache mode determines how component data is cached and restored.
+ *
+ * - 'data': (Recommended) Caches this.data with class-aware serialization.
+ *   Requires ES6 classes to be registered via register_cache_class().
+ *   On cache hit, this.data is hydrated before first render.
+ *
+ * - 'html': Caches rendered DOM HTML after children are ready.
+ *   Does not require class registration. On cache hit, HTML is injected
+ *   directly. Note: this.data is NOT populated during on_render() with
+ *   cached HTML - use on_ready() for any DOM manipulation that depends on data.
+ */
+export type CacheMode = 'data' | 'html';
 export declare class Jqhtml_Local_Storage {
     private static _cache_key;
+    private static _cache_mode;
     private static _storage_available;
     private static _initialized;
     /**
      * Set the cache key and initialize storage
      * Must be called before any get/set operations
      * @param {string} cache_key - Unique identifier for this cache scope
+     * @param {CacheMode} cache_mode - Cache strategy: 'data' (default, recommended) or 'html'
      */
-    static set_cache_key(cache_key: string): void;
+    static set_cache_key(cache_key: string, cache_mode?: CacheMode): void;
     /**
      * Check if cache key has been set
      * @returns {boolean} True if cache key is configured
      */
     static has_cache_key(): boolean;
+    /**
+     * Get the current cache mode
+     * @returns {CacheMode} Current cache mode ('data' or 'html')
+     */
+    static get_cache_mode(): CacheMode;
     /**
      * Initialize storage system and validate scope
      * Called automatically after cache key is set
@@ -80,6 +126,11 @@ export declare class Jqhtml_Local_Storage {
      * @private
      */
     private static _is_storage_available;
+    /**
+     * Check if verbose mode is enabled
+     * @private
+     */
+    private static _is_verbose;
     /**
      * Validate storage scope and clear JQHTML keys if cache key changed
      * Only clears keys prefixed with 'jqhtml::' to preserve other libraries' data
@@ -106,15 +157,22 @@ export declare class Jqhtml_Local_Storage {
      */
     private static _is_ready;
     /**
-     * Set item in localStorage
+     * Set item in localStorage with class-aware serialization.
+     *
+     * If serialization fails (e.g., unregistered class instances, circular refs),
+     * the existing cache entry is removed and nothing is stored.
+     *
      * @param {string} key - Storage key
-     * @param {*} value - Value to store (will be JSON serialized)
+     * @param {*} value - Value to store (primitives, objects, arrays, or registered class instances)
      */
     static set(key: string, value: any): void;
     /**
-     * Get item from localStorage
+     * Get item from localStorage with class-aware deserialization.
+     *
+     * If deserialization fails, returns null (as if no cache exists).
+     *
      * @param {string} key - Storage key
-     * @returns {*|null} Parsed value or null if not found/unavailable
+     * @returns {*|null} Deserialized value with class instances restored, or null if not found/failed
      */
     static get(key: string): any | null;
     /**
@@ -122,21 +180,27 @@ export declare class Jqhtml_Local_Storage {
      * @param {string} key - Storage key
      */
     static remove(key: string): void;
+    /**
+     * Perform a serialize/deserialize round-trip on a value.
+     *
+     * This ensures "hot" data (fresh from on_load) behaves identically to "cold" data
+     * (restored from cache). Unregistered class instances will be converted to plain
+     * objects, exactly as they would be if restored from cache.
+     *
+     * Use this to normalize data after on_load() so developers catch missing class
+     * registrations immediately rather than only after a page reload.
+     *
+     * @param {any} value - The value to normalize
+     * @returns {any} The value after serialize/deserialize round-trip, or original if serialization fails
+     */
+    static normalize_for_cache(value: any): any;
     /**
      * Internal set implementation with scope validation and quota handling
      * @param {string} key
-     * @param {*} value - Original value (not used, kept for clarity)
      * @param {string} serialized - Pre-serialized JSON string
      * @private
      */
     private static _set_item;
-    /**
-     * Internal get implementation
-     * @param {string} key
-     * @returns {*|null}
-     * @private
-     */
-    private static _get_item;
     /**
      * Internal remove implementation
      * @param {string} key

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAuB;IAChD,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAwB;IACzD,OAAO,CAAC,MAAM,CAAC,YAAY,CAAkB;IAE7C;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAK7C;;;OAGG;IACH,MAAM,CAAC,aAAa,IAAI,OAAO;IAI/B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,KAAK;IAepB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAYpC;;;;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;;;;OAIG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAqBzC;;;;OAIG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAQnC;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQhC;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IA4BxB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IAexB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;CAS9B"}
+{"version":3,"file":"local-storage.d.ts","sourceRoot":"","sources":["../src/local-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAaH;;;;;;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;AAySD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAuB;IAChD,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;IAM7E;;;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;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG;IAiC3C;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IA4BxB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;CAS9B"}

package/package.json

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