@jqhtml/core 2.3.59 → 2.3.64

package/dist/local-storage.js

@@ -1,699 +0,0 @@
-/**
- * Jqhtml_Local_Storage - Scoped local storage for JQHTML component caching
- *
- * Provides safe, scoped access to localStorage with automatic handling of
- * unavailable storage, quota exceeded errors, and scope invalidation.
- *
- * Key Features:
- * - **Manual scoping**: Cache key must be set via set_cache_key() before use
- * - **Graceful degradation**: Returns null when storage unavailable or cache key not set
- * - **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,
- * user ID, or combination of relevant scope factors). This scope is stored in
- * `_jqhtml_cache_key`. If the cache key changes between page loads, all JQHTML
- * storage is cleared to prevent stale data from different sessions/users.
- *
- * Key Format:
- * Keys are stored as: `jqhtml::developer_key::cache_key`
- * Example: `jqhtml::User_Profile_data::user_123`
- *
- * The `jqhtml::` prefix identifies JQHTML keys, allowing safe clearing of only our keys
- * without affecting other JavaScript libraries. This enables transparent coexistence
- * with third-party libraries that also use browser storage.
- *
- * Quota Exceeded Handling:
- * When storage quota is exceeded during a set operation, only JQHTML keys (prefixed with
- * `jqhtml::`) are cleared, preserving other libraries' data. The operation is then retried
- * 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 - 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');
- *   // cached.contact instanceof Contact_Model === true
- *
- * IMPORTANT - Volatile Storage:
- * Storage can be cleared at any time due to:
- * - User clearing browser data
- * - Private browsing mode restrictions
- * - Quota exceeded errors
- * - Cache key changes
- * - Browser storage unavailable
- *
- * Therefore, NEVER store critical data. Only use for:
- * - Cached component HTML (performance optimization)
- * - Transient UI state (convenience, not required)
- *
- * @internal This class is not exposed in the public API
- */
-// ============================================================================
-// Class Registry for Serialization
-// ============================================================================
-// Registry mapping class names to constructors
-const class_registry = Object.create(null);
-// Markers for serialized class instances (unique to avoid collisions with user data)
-// Replaced at build time by rollup (see rollup.config.js).
-const CORE_VERSION = '__VERSION__';
-const CLASS_MARKER = '__jqhtml_class__';
-const PROPS_MARKER = '__jqhtml_props__';
-/**
- * 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 function register_cache_class(klass) {
-    if (typeof klass !== 'function' || !klass.name) {
-        throw new Error('[JQHTML Cache] register_cache_class requires a named class constructor');
-    }
-    class_registry[klass.name] = klass;
-}
-/**
- * Check if a class is registered for caching
- */
-export function is_cache_class_registered(class_name) {
-    return class_name in class_registry;
-}
-// ============================================================================
-// Serialization (Object → String)
-// ============================================================================
-/**
- * Serialize a value to JSON string, handling ES6 class instances recursively.
- * Returns null if serialization fails for any reason.
- *
- * @param value - The value to serialize
- * @param verbose - Whether to log warnings
- * @returns Serialized JSON string, or null if serialization failed
- */
-function serialize_value(value, verbose) {
-    try {
-        const seen = new WeakSet();
-        const processed = process_for_serialization(value, verbose, seen);
-        if (processed === undefined) {
-            // Serialization failed - undefined signals failure
-            return null;
-        }
-        return JSON.stringify(processed);
-    }
-    catch (e) {
-        if (verbose) {
-            console.warn('[JQHTML Cache] Serialization failed:', e);
-        }
-        return null;
-    }
-}
-/**
- * Recursively process a value for serialization.
- * Returns undefined if serialization should fail (unserializable value encountered).
- *
- * @param value - The value to process
- * @param verbose - Whether to log warnings
- * @param seen - WeakSet to detect circular references
- * @returns Processed value ready for JSON.stringify, or undefined if failed
- */
-function process_for_serialization(value, verbose, seen) {
-    // Handle null and undefined
-    if (value === null) {
-        return null;
-    }
-    if (value === undefined) {
-        return undefined; // JSON.stringify will omit this property
-    }
-    // Handle primitives
-    if (typeof value !== 'object') {
-        // string, number, boolean are fine
-        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-            return value;
-        }
-        // bigint, symbol, function cannot be serialized
-        if (verbose) {
-            console.warn(`[JQHTML Cache] Cannot serialize ${typeof value} - value will be omitted`);
-        }
-        // Return undefined to omit this value (not fail entire serialization)
-        return undefined;
-    }
-    // Handle circular references.
-    // `seen` tracks only the current ancestor path (the DFS stack): an object is
-    // added on the way down and removed on the way back up (see finally below).
-    // This flags a genuine cycle (a back-edge to an ancestor) while allowing a
-    // shared reference in a DAG to be serialized independently on each visit.
-    // JSON round-trip semantics do not preserve identity anyway, so emitting a
-    // copy per reference is correct; silently omitting the property is not.
-    if (seen.has(value)) {
-        if (verbose) {
-            console.warn('[JQHTML Cache] Circular reference detected - cannot serialize');
-        }
-        return undefined; // Fail entire serialization
-    }
-    seen.add(value);
-    try {
-        // Handle arrays
-        if (Array.isArray(value)) {
-            const result = [];
-            for (let i = 0; i < value.length; i++) {
-                const item = value[i];
-                const processed = process_for_serialization(item, verbose, seen);
-                // For arrays, we keep undefined as null to preserve indices
-                result.push(processed === undefined ? null : processed);
-            }
-            return result;
-        }
-        // Handle Date objects specially
-        if (value instanceof Date) {
-            return {
-                [CLASS_MARKER]: 'Date',
-                [PROPS_MARKER]: value.toISOString()
-            };
-        }
-        // Handle Map objects
-        if (value instanceof Map) {
-            const entries = [];
-            for (const [k, v] of value) {
-                const processedKey = process_for_serialization(k, verbose, seen);
-                const processedValue = process_for_serialization(v, verbose, seen);
-                entries.push([processedKey, processedValue]);
-            }
-            return {
-                [CLASS_MARKER]: 'Map',
-                [PROPS_MARKER]: entries
-            };
-        }
-        // Handle Set objects
-        if (value instanceof Set) {
-            const items = [];
-            for (const item of value) {
-                items.push(process_for_serialization(item, verbose, seen));
-            }
-            return {
-                [CLASS_MARKER]: 'Set',
-                [PROPS_MARKER]: items
-            };
-        }
-        // Get the constructor
-        const ctor = value.constructor;
-        // Handle registered class instances
-        if (ctor && ctor.name && class_registry[ctor.name]) {
-            const props = {};
-            // Extract own enumerable properties (bypass any toJSON method)
-            for (const key of Object.keys(value)) {
-                const propValue = value[key];
-                const processed = process_for_serialization(propValue, verbose, seen);
-                // Only include if not undefined (failed serialization)
-                if (processed !== undefined || propValue === undefined) {
-                    props[key] = processed;
-                }
-            }
-            return {
-                [CLASS_MARKER]: ctor.name,
-                [PROPS_MARKER]: props
-            };
-        }
-        // Handle plain objects (constructor is Object or no constructor)
-        if (ctor === Object || ctor === undefined || ctor === null) {
-            const result = {};
-            for (const key of Object.keys(value)) {
-                const propValue = value[key];
-                const processed = process_for_serialization(propValue, verbose, seen);
-                // Only include if not undefined (unless original was undefined)
-                if (processed !== undefined || propValue === undefined) {
-                    result[key] = processed;
-                }
-            }
-            return result;
-        }
-        // Unregistered class instance - convert to plain object for hot/cold parity
-        // This ensures developers catch missing class registrations during development
-        // (methods will be lost, only properties preserved)
-        if (verbose) {
-            console.warn(`[JQHTML Cache] Converting unregistered class "${ctor.name}" to plain object. ` +
-                `Methods will be lost. Call jqhtml.register_cache_class(${ctor.name}) to preserve the class.`);
-        }
-        // Convert to plain object - properties are preserved, prototype methods are lost
-        const result = {};
-        for (const key of Object.keys(value)) {
-            const propValue = value[key];
-            const processed = process_for_serialization(propValue, verbose, seen);
-            // Only include if not undefined (unless original was undefined)
-            if (processed !== undefined || propValue === undefined) {
-                result[key] = processed;
-            }
-        }
-        return result;
-    }
-    finally {
-        // Pop this object off the ancestor path now that its subtree is done.
-        seen.delete(value);
-    }
-}
-// ============================================================================
-// Deserialization (String → Object)
-// ============================================================================
-/**
- * Deserialize a JSON string, restoring ES6 class instances.
- * Returns null if deserialization fails.
- *
- * @param str - The JSON string to deserialize
- * @param verbose - Whether to log warnings
- * @returns Deserialized value with class instances restored, or null if failed
- */
-function deserialize_value(str, verbose) {
-    try {
-        const parsed = JSON.parse(str);
-        return process_for_deserialization(parsed, verbose);
-    }
-    catch (e) {
-        if (verbose) {
-            console.warn('[JQHTML Cache] Deserialization failed:', e);
-        }
-        return null;
-    }
-}
-/**
- * Recursively process a parsed value, restoring class instances.
- *
- * @param value - The parsed value to process
- * @param verbose - Whether to log warnings
- * @returns Processed value with class instances restored
- */
-function process_for_deserialization(value, verbose) {
-    // Handle primitives and null
-    if (value === null || value === undefined || typeof value !== 'object') {
-        return value;
-    }
-    // Handle arrays
-    if (Array.isArray(value)) {
-        return value.map(item => process_for_deserialization(item, verbose));
-    }
-    // Check for class marker
-    if (value[CLASS_MARKER] !== undefined && value[PROPS_MARKER] !== undefined) {
-        const class_name = value[CLASS_MARKER];
-        const props = value[PROPS_MARKER];
-        // Handle built-in types
-        if (class_name === 'Date') {
-            return new Date(props);
-        }
-        if (class_name === 'Map') {
-            const map = new Map();
-            for (const [k, v] of props) {
-                map.set(process_for_deserialization(k, verbose), process_for_deserialization(v, verbose));
-            }
-            return map;
-        }
-        if (class_name === 'Set') {
-            const set = new Set();
-            for (const item of props) {
-                set.add(process_for_deserialization(item, verbose));
-            }
-            return set;
-        }
-        // Look up registered class
-        const klass = class_registry[class_name];
-        if (!klass) {
-            if (verbose) {
-                console.warn(`[JQHTML Cache] Cannot restore class "${class_name}" - not registered. ` +
-                    `Data will be returned as plain object. ` +
-                    `Call jqhtml.register_cache_class(${class_name}) to restore class instances.`);
-            }
-            // Return as plain object rather than failing completely
-            return process_for_deserialization(props, verbose);
-        }
-        // Create instance without calling constructor and assign properties
-        try {
-            const instance = Object.create(klass.prototype);
-            const processed_props = process_for_deserialization(props, verbose);
-            Object.assign(instance, processed_props);
-            return instance;
-        }
-        catch (e) {
-            if (verbose) {
-                console.warn(`[JQHTML Cache] Failed to restore class "${class_name}":`, e);
-            }
-            // Return null to signal cache should be treated as miss
-            return null;
-        }
-    }
-    // Plain object - process recursively
-    const result = {};
-    for (const key of Object.keys(value)) {
-        result[key] = process_for_deserialization(value[key], verbose);
-    }
-    return result;
-}
-export class Jqhtml_Local_Storage {
-    /**
-     * 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, cache_mode = 'data') {
-        this._cache_key = cache_key;
-        // Key SHAPE is a function of the library (see cache-key-serializer.ts), so an
-        // upgrade that changes it must invalidate everything persisted under the old shape.
-        // Version the SCOPE MARKER rather than the key itself: _validate_scope() already
-        // clears every jqhtml key when this value changes, and leaving the per-entry key
-        // format alone keeps stored keys readable and avoids repeating the version in each.
-        this._scope_marker = `${CORE_VERSION}::${cache_key}`;
-        this._cache_mode = cache_mode;
-        this._init();
-    }
-    /**
-     * Check if cache key has been set
-     * @returns {boolean} True if cache key is configured
-     */
-    static has_cache_key() {
-        return this._cache_key !== null;
-    }
-    /**
-     * Get the current cache mode
-     * @returns {CacheMode} Current cache mode ('data' or 'html')
-     */
-    static get_cache_mode() {
-        return this._cache_mode;
-    }
-    /**
-     * Initialize storage system and validate scope
-     * Called automatically after cache key is set
-     * @private
-     */
-    static _init() {
-        // Check storage availability
-        if (this._storage_available === null) {
-            this._storage_available = this._is_storage_available();
-        }
-        if (!this._storage_available || !this._cache_key) {
-            return;
-        }
-        // Validate scope
-        this._validate_scope();
-        this._initialized = true;
-    }
-    /**
-     * Check if localStorage is available
-     * @returns {boolean}
-     * @private
-     */
-    static _is_storage_available() {
-        try {
-            const storage = window.localStorage;
-            const test = '__jqhtml_storage_test__';
-            storage.setItem(test, test);
-            storage.removeItem(test);
-            return true;
-        }
-        catch (e) {
-            return false;
-        }
-    }
-    /**
-     * Check if verbose mode is enabled
-     * @private
-     */
-    static _is_verbose() {
-        return window.jqhtml?.debug?.verbose === true;
-    }
-    /**
-     * Validate storage scope and clear JQHTML keys if cache key changed
-     * Only clears keys prefixed with 'jqhtml::' to preserve other libraries' data
-     * @private
-     */
-    static _validate_scope() {
-        if (!this._storage_available) {
-            return;
-        }
-        try {
-            const stored_key = localStorage.getItem('_jqhtml_cache_key');
-            // If the scope marker (core version + developer key) changed, clear only JQHTML keys
-            if (stored_key !== null && stored_key !== this._scope_marker) {
-                console.log('[JQHTML Local Storage] Cache scope changed, clearing JQHTML keys:', {
-                    old_key: stored_key,
-                    new_key: this._scope_marker,
-                });
-                this._clear_jqhtml_keys();
-                localStorage.setItem('_jqhtml_cache_key', this._scope_marker);
-            }
-            else if (stored_key === null) {
-                // First time JQHTML is using this storage - just set the key, don't clear
-                console.log('[JQHTML Local Storage] Initializing cache scope (first use):', {
-                    new_key: this._scope_marker,
-                });
-                localStorage.setItem('_jqhtml_cache_key', this._scope_marker);
-            }
-        }
-        catch (e) {
-            console.error('[JQHTML Local Storage] Failed to validate scope:', e);
-        }
-    }
-    /**
-     * Clear only JQHTML keys from storage (keys starting with 'jqhtml::')
-     * Preserves keys from other libraries
-     * @private
-     */
-    static _clear_jqhtml_keys() {
-        if (!this._storage_available) {
-            return;
-        }
-        const keys_to_remove = [];
-        // Collect all JQHTML keys
-        for (let i = 0; i < localStorage.length; i++) {
-            const key = localStorage.key(i);
-            if (key && key.startsWith('jqhtml::')) {
-                keys_to_remove.push(key);
-            }
-        }
-        // Remove collected keys
-        keys_to_remove.forEach(key => {
-            try {
-                localStorage.removeItem(key);
-            }
-            catch (e) {
-                console.error('[JQHTML Local Storage] Failed to remove key:', key, e);
-            }
-        });
-        console.log(`[JQHTML Local Storage] Cleared ${keys_to_remove.length} JQHTML keys`);
-    }
-    /**
-     * Build scoped key with JQHTML namespace prefix
-     * @param {string} key - Developer-provided key
-     * @returns {string}
-     * @private
-     */
-    static _build_key(key) {
-        return `jqhtml::${key}::${this._cache_key}`;
-    }
-    /**
-     * Check if storage is ready for use
-     * @returns {boolean}
-     * @private
-     */
-    static _is_ready() {
-        return this._storage_available === true && this._cache_key !== null && this._initialized;
-    }
-    /**
-     * 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 (primitives, objects, arrays, or registered class instances)
-     */
-    static set(key, value) {
-        if (!this._is_ready()) {
-            return;
-        }
-        const verbose = this._is_verbose();
-        const scoped_key = this._build_key(key);
-        // Serialize with class-aware processing
-        const serialized = serialize_value(value, verbose);
-        if (serialized === null) {
-            // Serialization failed - remove any existing cache entry
-            if (verbose) {
-                console.warn(`[JQHTML Cache] Failed to serialize value for key "${key}". ` +
-                    `Removing existing cache entry if present.`);
-            }
-            try {
-                localStorage.removeItem(scoped_key);
-            }
-            catch (e) {
-                // Ignore removal errors
-            }
-            return;
-        }
-        // Check size before attempting to store (1MB limit)
-        const size_bytes = new Blob([serialized]).size;
-        const size_mb = size_bytes / (1024 * 1024);
-        if (size_mb > 1) {
-            if (verbose) {
-                console.warn(`[JQHTML Cache] Skipping set - value too large (${size_mb.toFixed(2)}MB > 1MB limit)`, { key, size_bytes, size_mb });
-            }
-            // Remove existing cache entry since we can't update it
-            try {
-                localStorage.removeItem(scoped_key);
-            }
-            catch (e) {
-                // Ignore removal errors
-            }
-            return;
-        }
-        this._set_item(key, serialized);
-    }
-    /**
-     * 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} Deserialized value with class instances restored, or null if not found/failed
-     */
-    static get(key) {
-        if (!this._is_ready()) {
-            return null;
-        }
-        const verbose = this._is_verbose();
-        const scoped_key = this._build_key(key);
-        try {
-            const serialized = localStorage.getItem(scoped_key);
-            if (serialized === null) {
-                return null;
-            }
-            const result = deserialize_value(serialized, verbose);
-            if (result === null) {
-                // Deserialization failed - treat as cache miss
-                if (verbose) {
-                    console.warn(`[JQHTML Cache] Failed to deserialize value for key "${key}". ` +
-                        `Treating as cache miss.`);
-                }
-                return null;
-            }
-            return result;
-        }
-        catch (e) {
-            if (verbose) {
-                console.warn('[JQHTML Cache] Failed to get item:', e);
-            }
-            return null;
-        }
-    }
-    /**
-     * Remove item from localStorage
-     * @param {string} key - Storage key
-     */
-    static remove(key) {
-        if (!this._is_ready()) {
-            return;
-        }
-        this._remove_item(key);
-    }
-    /**
-     * 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) {
-        const verbose = this._is_verbose();
-        // Serialize to JSON string
-        const serialized = serialize_value(value, verbose);
-        if (serialized === null) {
-            // Serialization failed completely - return original
-            // (This happens with circular references or other fatal issues)
-            if (verbose) {
-                console.warn('[JQHTML Cache] normalize_for_cache: Serialization failed, returning original value');
-            }
-            return value;
-        }
-        // Deserialize back to object
-        const deserialized = deserialize_value(serialized, verbose);
-        if (deserialized === null) {
-            // Deserialization failed - return original
-            if (verbose) {
-                console.warn('[JQHTML Cache] normalize_for_cache: Deserialization failed, returning original value');
-            }
-            return value;
-        }
-        return deserialized;
-    }
-    /**
-     * Internal set implementation with scope validation and quota handling
-     * @param {string} key
-     * @param {string} serialized - Pre-serialized JSON string
-     * @private
-     */
-    static _set_item(key, serialized) {
-        // Validate scope before every write
-        this._validate_scope();
-        const scoped_key = this._build_key(key);
-        try {
-            localStorage.setItem(scoped_key, serialized);
-        }
-        catch (e) {
-            // Check if quota exceeded
-            if (e.name === 'QuotaExceededError' || e.code === 22) {
-                console.warn('[JQHTML Local Storage] Quota exceeded, clearing JQHTML keys and retrying');
-                // Clear only JQHTML keys and retry once
-                this._clear_jqhtml_keys();
-                localStorage.setItem('_jqhtml_cache_key', this._cache_key);
-                try {
-                    localStorage.setItem(scoped_key, serialized);
-                }
-                catch (retry_error) {
-                    console.error('[JQHTML Local Storage] Failed to set item after clearing JQHTML keys:', retry_error);
-                }
-            }
-            else {
-                console.error('[JQHTML Local Storage] Failed to set item:', e);
-            }
-        }
-    }
-    /**
-     * Internal remove implementation
-     * @param {string} key
-     * @private
-     */
-    static _remove_item(key) {
-        const scoped_key = this._build_key(key);
-        try {
-            localStorage.removeItem(scoped_key);
-        }
-        catch (e) {
-            console.error('[JQHTML Local Storage] Failed to remove item:', e);
-        }
-    }
-}
-Jqhtml_Local_Storage._cache_key = null;
-/** Versioned scope identity - compared in _validate_scope() to clear on a core upgrade. */
-Jqhtml_Local_Storage._scope_marker = null;
-Jqhtml_Local_Storage._cache_mode = 'data';
-Jqhtml_Local_Storage._storage_available = null;
-Jqhtml_Local_Storage._initialized = false;
-//# sourceMappingURL=local-storage.js.map