@signaltree/core 5.1.1 → 5.1.3

package/dist/enhancers/serialization/lib/serialization.js

@@ -0,0 +1,662 @@
+import { isSignal } from '@angular/core';
+import { TYPE_MARKERS } from '../constants.js';
+
+const DEFAULT_CONFIG = {
+  includeMetadata: true,
+  replacer: undefined,
+  reviver: undefined,
+  preserveTypes: true,
+  maxDepth: 50,
+  handleCircular: true
+};
+function unwrapObjectSafely(obj, visited = new WeakSet(), depth = 0, maxDepth = 50, preserveTypes = true) {
+  if (depth > maxDepth) return '[Max Depth Exceeded]';
+  if (obj === null || typeof obj !== 'object') {
+    if (!preserveTypes) return obj;
+    if (obj === undefined) return {
+      [TYPE_MARKERS.UNDEFINED]: true
+    };
+    if (typeof obj === 'number') {
+      if (Number.isNaN(obj)) return {
+        [TYPE_MARKERS.NAN]: true
+      };
+      if (obj === Infinity) return {
+        [TYPE_MARKERS.INFINITY]: true
+      };
+      if (obj === -Infinity) return {
+        [TYPE_MARKERS.NEG_INFINITY]: true
+      };
+      return obj;
+    }
+    if (typeof obj === 'bigint') return {
+      [TYPE_MARKERS.BIGINT]: String(obj)
+    };
+    if (typeof obj === 'symbol') return {
+      [TYPE_MARKERS.SYMBOL]: String(obj)
+    };
+    return obj;
+  }
+  if (typeof obj === 'function') {
+    try {
+      const result = obj();
+      return unwrapObjectSafely(result, visited, depth + 1, maxDepth, preserveTypes);
+    } catch {
+      return '[Function]';
+    }
+  }
+  if (visited.has(obj)) return '[Circular Reference]';
+  if (isSignal(obj)) return obj();
+  if (preserveTypes) {
+    if (obj instanceof Date) return {
+      [TYPE_MARKERS.DATE]: obj.toISOString()
+    };
+    if (obj instanceof RegExp) return {
+      [TYPE_MARKERS.REGEXP]: {
+        source: obj.source,
+        flags: obj.flags
+      }
+    };
+    if (obj instanceof Map) {
+      return {
+        [TYPE_MARKERS.MAP]: Array.from(obj.entries())
+      };
+    }
+    if (obj instanceof Set) {
+      return {
+        [TYPE_MARKERS.SET]: Array.from(obj.values())
+      };
+    }
+  } else {
+    if (obj instanceof Date || obj instanceof RegExp) return obj;
+  }
+  visited.add(obj);
+  try {
+    if (Array.isArray(obj)) {
+      const arr = obj.map(item => unwrapObjectSafely(item, visited, depth + 1, maxDepth, preserveTypes));
+      visited.delete(obj);
+      return arr;
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+      if ((k === 'set' || k === 'update') && typeof v === 'function' && !isSignal(v)) continue;
+      if (isSignal(v)) {
+        out[k] = unwrapObjectSafely(v(), visited, depth + 1, maxDepth, preserveTypes);
+      } else if (typeof v === 'function' && k !== 'set' && k !== 'update') {
+        try {
+          const callResult = v();
+          out[k] = unwrapObjectSafely(callResult, visited, depth + 1, maxDepth, preserveTypes);
+        } catch {
+          continue;
+        }
+      } else {
+        out[k] = unwrapObjectSafely(v, visited, depth + 1, maxDepth, preserveTypes);
+      }
+    }
+    visited.delete(obj);
+    return out;
+  } catch {
+    visited.delete(obj);
+    return '[Serialization Error]';
+  }
+}
+function detectCircularReferences(obj, path = '', seen = new WeakSet(), paths = new Map()) {
+  const circular = [];
+  if (obj === null || typeof obj !== 'object') {
+    return circular;
+  }
+  if (seen.has(obj)) {
+    const targetPath = paths.get(obj) || '';
+    circular.push({
+      path,
+      targetPath
+    });
+    return circular;
+  }
+  seen.add(obj);
+  paths.set(obj, path);
+  if (Array.isArray(obj)) {
+    const arrObj = obj;
+    for (let i = 0; i < arrObj.length; i++) {
+      const itemPath = path ? `${path}[${i}]` : `[${i}]`;
+      const childCircular = detectCircularReferences(arrObj[i], itemPath, seen, paths);
+      circular.push(...childCircular);
+    }
+  } else {
+    for (const [key, value] of Object.entries(obj)) {
+      const propPath = path ? `${path}.${key}` : key;
+      const childCircular = detectCircularReferences(value, propPath, seen, paths);
+      circular.push(...childCircular);
+    }
+  }
+  seen.delete(obj);
+  return circular;
+}
+function createReplacer(config) {
+  const seen = new WeakSet();
+  const circularPaths = new Map();
+  return function replacer(key, value) {
+    if (config.replacer) {
+      value = config.replacer.call(this, key, value);
+    }
+    if (isSignal(value)) {
+      return value();
+    }
+    if (value && typeof value === 'object') {
+      if (seen.has(value)) {
+        if (config.handleCircular) {
+          const targetPath = circularPaths.get(value) || '';
+          return {
+            [TYPE_MARKERS.CIRCULAR]: targetPath
+          };
+        }
+        return undefined;
+      }
+      seen.add(value);
+      const currentPath = key || '';
+      circularPaths.set(value, currentPath);
+    }
+    return value;
+  };
+}
+function resolveCircularReferences(obj, circularPaths) {
+  for (const {
+    path,
+    targetPath
+  } of circularPaths) {
+    const pathParts = path.split(/\.|\[|\]/).filter(Boolean);
+    const targetParts = targetPath.split(/\.|\[|\]/).filter(Boolean);
+    let current = obj;
+    for (let i = 0; i < pathParts.length - 1; i++) {
+      current = current[pathParts[i]];
+      if (!current) break;
+    }
+    let target = obj;
+    for (const part of targetParts) {
+      target = target[part];
+      if (!target) break;
+    }
+    if (current && target) {
+      current[pathParts[pathParts.length - 1]] = target;
+    }
+  }
+}
+function withSerialization(defaultConfig = {}) {
+  const enhancer = tree => {
+    const enhanced = tree;
+    enhanced.toJSON = () => {
+      return tree();
+    };
+    enhanced.fromJSON = (data, metadata) => {
+      const restoreSpecialTypes = value => {
+        if (!value || typeof value !== 'object') {
+          return value;
+        }
+        if (TYPE_MARKERS.UNDEFINED in value) {
+          return undefined;
+        }
+        if (TYPE_MARKERS.NAN in value) {
+          return NaN;
+        }
+        if (TYPE_MARKERS.INFINITY in value) {
+          return Infinity;
+        }
+        if (TYPE_MARKERS.NEG_INFINITY in value) {
+          return -Infinity;
+        }
+        if (TYPE_MARKERS.BIGINT in value) {
+          return BigInt(value[TYPE_MARKERS.BIGINT]);
+        }
+        if (TYPE_MARKERS.SYMBOL in value) {
+          return Symbol.for(value[TYPE_MARKERS.SYMBOL]);
+        }
+        if (TYPE_MARKERS.DATE in value) {
+          return new Date(value[TYPE_MARKERS.DATE]);
+        }
+        if (TYPE_MARKERS.REGEXP in value) {
+          const regexpData = value[TYPE_MARKERS.REGEXP];
+          return new RegExp(regexpData.source, regexpData.flags);
+        }
+        if (TYPE_MARKERS.MAP in value) {
+          return new Map(value[TYPE_MARKERS.MAP]);
+        }
+        if (TYPE_MARKERS.SET in value) {
+          return new Set(value[TYPE_MARKERS.SET]);
+        }
+        if (Array.isArray(value)) {
+          return value.map(restoreSpecialTypes);
+        }
+        const result = {};
+        for (const [k, v] of Object.entries(value)) {
+          result[k] = restoreSpecialTypes(v);
+        }
+        return result;
+      };
+      const restoredData = restoreSpecialTypes(data);
+      function resolveAliasSignal(path, key) {
+        let node = tree.$;
+        if (path && node) {
+          for (const part of path.split('.')) {
+            if (!part) continue;
+            const next = node[part];
+            if (!next || typeof next !== 'object' && typeof next !== 'function') {
+              node = undefined;
+              break;
+            }
+            node = next;
+          }
+        }
+        const candidate = node?.[key];
+        return isSignal(candidate) ? candidate : undefined;
+      }
+      function updateSignals(target, source, path = '') {
+        if (!target || !source) return;
+        for (const key in source) {
+          if (!Object.prototype.hasOwnProperty.call(source, key)) continue;
+          const sourceValue = source[key];
+          const direct = target[key];
+          const targetSignal = isSignal(direct) ? direct : typeof direct === 'function' && 'set' in direct && typeof direct.set === 'function' ? direct : resolveAliasSignal(path, key);
+          if (targetSignal) {
+            targetSignal.set(sourceValue);
+            continue;
+          }
+          if (sourceValue && typeof sourceValue === 'object' && !Array.isArray(sourceValue) && direct && (typeof direct === 'object' || typeof direct === 'function' && !('set' in direct)) && !isSignal(direct)) {
+            updateSignals(direct, sourceValue, path ? `${path}.${key}` : key);
+          }
+        }
+      }
+      const nodeMap = metadata?.nodeMap;
+      if (nodeMap && Object.keys(nodeMap).length > 0) {
+        if (nodeMap[''] === 'r') {
+          const rootAlias = tree.$;
+          if (rootAlias && typeof rootAlias.set === 'function') {
+            rootAlias.set(restoredData);
+          }
+        }
+        for (const [path, kind] of Object.entries(nodeMap)) {
+          if (path === '') continue;
+          if (kind !== 'b') continue;
+          const parts = path.split(/\.|\[|\]/).filter(Boolean);
+          let node = tree.$;
+          for (const p of parts) {
+            if (!node) break;
+            node = node[p] ?? undefined;
+          }
+          if (node && (isSignal(node) || typeof node === 'function' && 'set' in node && typeof node.set === 'function')) {
+            let current = restoredData;
+            for (const p of parts) {
+              if (current == null) {
+                current = undefined;
+                break;
+              }
+              if (typeof current === 'object') {
+                current = current[p];
+              } else {
+                current = undefined;
+                break;
+              }
+            }
+            try {
+              node.set(current);
+            } catch {}
+          }
+        }
+        updateSignals(tree.state, restoredData);
+        return;
+      }
+      updateSignals(tree.state, restoredData);
+    };
+    function encodeSpecials(v, preserveTypes) {
+      if (!preserveTypes) return v;
+      if (v === undefined) return {
+        [TYPE_MARKERS.UNDEFINED]: true
+      };
+      if (typeof v === 'number') {
+        if (Number.isNaN(v)) return {
+          [TYPE_MARKERS.NAN]: true
+        };
+        if (v === Infinity) return {
+          [TYPE_MARKERS.INFINITY]: true
+        };
+        if (v === -Infinity) return {
+          [TYPE_MARKERS.NEG_INFINITY]: true
+        };
+        return v;
+      }
+      if (typeof v === 'bigint') return {
+        [TYPE_MARKERS.BIGINT]: String(v)
+      };
+      if (typeof v === 'symbol') return {
+        [TYPE_MARKERS.SYMBOL]: String(v)
+      };
+      if (v instanceof Date) return {
+        [TYPE_MARKERS.DATE]: v.toISOString()
+      };
+      if (v instanceof RegExp) return {
+        [TYPE_MARKERS.REGEXP]: {
+          source: v.source,
+          flags: v.flags
+        }
+      };
+      if (v instanceof Map) return {
+        [TYPE_MARKERS.MAP]: Array.from(v.entries())
+      };
+      if (v instanceof Set) return {
+        [TYPE_MARKERS.SET]: Array.from(v.values())
+      };
+      if (Array.isArray(v)) return v.map(x => encodeSpecials(x, preserveTypes));
+      if (v && typeof v === 'object') {
+        const out = {};
+        for (const [k, val] of Object.entries(v)) out[k] = encodeSpecials(val, preserveTypes);
+        return out;
+      }
+      return v;
+    }
+    enhanced.serialize = config => {
+      const fullConfig = {
+        ...DEFAULT_CONFIG,
+        ...defaultConfig,
+        ...config
+      };
+      const raw = unwrapObjectSafely(tree.state, new WeakSet(), 0, fullConfig.maxDepth, fullConfig.preserveTypes);
+      const state = encodeSpecials(raw, fullConfig.preserveTypes);
+      const circularPaths = fullConfig.handleCircular ? detectCircularReferences(state) : [];
+      const data = {
+        data: state
+      };
+      const nodeMap = {};
+      try {
+        const rootAlias = tree.$;
+        if (rootAlias && typeof rootAlias.set === 'function') {
+          nodeMap[''] = 'r';
+        }
+        const visited = new WeakSet();
+        const isBranch = v => isSignal(v) || typeof v === 'function' && 'set' in v && typeof v.set === 'function';
+        const walkAlias = (obj, path = '') => {
+          if (!obj || typeof obj !== 'object' && typeof obj !== 'function') return;
+          const ref = obj;
+          if (visited.has(ref)) return;
+          visited.add(ref);
+          if (path && isBranch(obj)) {
+            nodeMap[path] = 'b';
+          }
+          for (const [k, v] of Object.entries(obj)) {
+            const childPath = path ? `${path}.${k}` : k;
+            walkAlias(v, childPath);
+          }
+        };
+        if (rootAlias) walkAlias(rootAlias);
+      } catch {}
+      if (fullConfig.includeMetadata) {
+        data.metadata = {
+          timestamp: Date.now(),
+          version: '1.0.0',
+          ...(circularPaths.length > 0 && {
+            circularRefs: circularPaths
+          }),
+          ...(Object.keys(nodeMap).length > 0 && {
+            nodeMap
+          })
+        };
+      }
+      const replacer = createReplacer(fullConfig);
+      const json = JSON.stringify(data, replacer, 2);
+      return json;
+    };
+    enhanced.deserialize = (json, config) => {
+      const fullConfig = {
+        ...DEFAULT_CONFIG,
+        ...defaultConfig,
+        ...config
+      };
+      try {
+        const parsed = JSON.parse(json);
+        const {
+          data,
+          metadata
+        } = parsed;
+        if (metadata?.circularRefs && fullConfig.handleCircular) {
+          resolveCircularReferences(data, metadata.circularRefs);
+        }
+        enhanced.fromJSON(data, metadata);
+        if (tree.__config?.debugMode) {
+          console.log('[SignalTree] State restored from serialized data', {
+            timestamp: metadata?.timestamp,
+            version: metadata?.version
+          });
+        }
+      } catch (error) {
+        console.error('[SignalTree] Failed to deserialize:', error);
+        throw new Error(`Failed to deserialize SignalTree state: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      }
+    };
+    enhanced.snapshot = () => {
+      const state = enhanced.toJSON();
+      const circularPaths = detectCircularReferences(state);
+      return {
+        data: JSON.parse(JSON.stringify(state)),
+        metadata: {
+          timestamp: Date.now(),
+          version: '1.0.0',
+          ...(circularPaths.length > 0 && {
+            circularRefs: circularPaths
+          })
+        }
+      };
+    };
+    enhanced.restore = snapshot => {
+      const {
+        data,
+        metadata
+      } = snapshot;
+      if (metadata?.circularRefs) {
+        resolveCircularReferences(data, metadata.circularRefs);
+      }
+      enhanced.fromJSON(data, metadata);
+    };
+    return enhanced;
+  };
+  enhancer.metadata = {
+    name: 'serialization'
+  };
+  return enhancer;
+}
+function enableSerialization() {
+  return withSerialization({
+    includeMetadata: true,
+    preserveTypes: true,
+    handleCircular: true
+  });
+}
+function withPersistence(config) {
+  const {
+    key,
+    storage = typeof window !== 'undefined' ? window.localStorage : undefined,
+    autoSave = true,
+    debounceMs = 1000,
+    autoLoad = true,
+    ...serializationConfig
+  } = config;
+  if (!storage) {
+    throw new Error('No storage adapter available. Provide a storage adapter in the config.');
+  }
+  const storageAdapter = storage;
+  function enhancer(tree) {
+    const serializable = withSerialization(serializationConfig)(tree);
+    const enhanced = serializable;
+    let lastCacheKey = null;
+    enhanced.save = async () => {
+      try {
+        const cacheKey = enhanced.serialize({
+          ...serializationConfig,
+          includeMetadata: false
+        });
+        if (config.skipCache || cacheKey !== lastCacheKey) {
+          const serialized = enhanced.serialize(serializationConfig);
+          await Promise.resolve(storageAdapter.setItem(key, serialized));
+          lastCacheKey = cacheKey;
+          if (tree.__config?.debugMode) {
+            console.log(`[SignalTree] State saved to storage key: ${key}`);
+          }
+        } else if (tree.__config?.debugMode) {
+          console.log(`[SignalTree] State unchanged, skipping storage write for key: ${key}`);
+        }
+      } catch (error) {
+        console.error('[SignalTree] Failed to save state:', error);
+        throw error;
+      }
+    };
+    enhanced.load = async () => {
+      try {
+        const data = await Promise.resolve(storageAdapter.getItem(key));
+        if (data) {
+          enhanced.deserialize(data, serializationConfig);
+          lastCacheKey = enhanced.serialize({
+            ...serializationConfig,
+            includeMetadata: false
+          });
+          if (tree.__config?.debugMode) {
+            console.log(`[SignalTree] State loaded from storage key: ${key}`);
+          }
+        }
+      } catch (error) {
+        console.error('[SignalTree] Failed to load state:', error);
+        throw error;
+      }
+    };
+    enhanced.clear = async () => {
+      try {
+        await Promise.resolve(storageAdapter.removeItem(key));
+        lastCacheKey = null;
+        if (tree.__config?.debugMode) {
+          console.log(`[SignalTree] State cleared from storage key: ${key}`);
+        }
+      } catch (error) {
+        console.error('[SignalTree] Failed to clear state:', error);
+        throw error;
+      }
+    };
+    if (autoLoad) {
+      setTimeout(() => {
+        enhanced.load().catch(error => {
+          console.warn('[SignalTree] Auto-load failed:', error);
+        });
+      }, 0);
+    }
+    if (autoSave) {
+      let saveTimeout;
+      let previousState = JSON.stringify(tree());
+      let pollingActive = true;
+      const triggerAutoSave = () => {
+        if (saveTimeout) {
+          clearTimeout(saveTimeout);
+        }
+        saveTimeout = setTimeout(() => {
+          enhanced.save().catch(error => {
+            console.error('[SignalTree] Auto-save failed:', error);
+          });
+        }, debounceMs);
+      };
+      try {
+        tree.subscribe(() => {
+          const currentState = JSON.stringify(tree());
+          if (currentState !== previousState) {
+            previousState = currentState;
+            triggerAutoSave();
+          }
+        });
+      } catch {
+        const checkForChanges = () => {
+          if (!pollingActive) return;
+          const currentState = JSON.stringify(tree());
+          if (currentState !== previousState) {
+            previousState = currentState;
+            triggerAutoSave();
+          }
+          setTimeout(checkForChanges, 100);
+        };
+        setTimeout(checkForChanges, 0);
+      }
+      enhanced.__flushAutoSave = () => {
+        pollingActive = false;
+        if (saveTimeout) {
+          clearTimeout(saveTimeout);
+          saveTimeout = undefined;
+          return enhanced.save();
+        }
+        return Promise.resolve();
+      };
+    }
+    return enhanced;
+  }
+  enhancer.metadata = {
+    name: 'persistence'
+  };
+  return enhancer;
+}
+function createStorageAdapter(getItem, setItem, removeItem) {
+  return {
+    getItem,
+    setItem,
+    removeItem
+  };
+}
+function createIndexedDBAdapter(dbName = 'SignalTreeDB', storeName = 'states') {
+  let db = null;
+  const openDB = async () => {
+    if (db) return db;
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(dbName, 1);
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => {
+        db = request.result;
+        resolve(db);
+      };
+      request.onupgradeneeded = event => {
+        const database = event.target.result;
+        if (!database.objectStoreNames.contains(storeName)) {
+          database.createObjectStore(storeName);
+        }
+      };
+    });
+  };
+  return {
+    async getItem(key) {
+      const database = await openDB();
+      return new Promise((resolve, reject) => {
+        const transaction = database.transaction([storeName], 'readonly');
+        const store = transaction.objectStore(storeName);
+        const request = store.get(key);
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve(request.result || null);
+      });
+    },
+    async setItem(key, value) {
+      const database = await openDB();
+      return new Promise((resolve, reject) => {
+        const transaction = database.transaction([storeName], 'readwrite');
+        const store = transaction.objectStore(storeName);
+        const request = store.put(value, key);
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve();
+      });
+    },
+    async removeItem(key) {
+      const database = await openDB();
+      return new Promise((resolve, reject) => {
+        const transaction = database.transaction([storeName], 'readwrite');
+        const store = transaction.objectStore(storeName);
+        const request = store.delete(key);
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve();
+      });
+    }
+  };
+}
+function applySerialization(tree) {
+  return withSerialization()(tree);
+}
+function applyPersistence(tree, cfg) {
+  return withPersistence(cfg)(tree);
+}
+
+export { applyPersistence, applySerialization, createIndexedDBAdapter, createStorageAdapter, enableSerialization, withPersistence, withSerialization };