@coherent.js/state 1.1.0 → 2.0.0-rc.0

package/dist/state-persistence.js

@@ -1,90 +1,40 @@
 // src/state-persistence.js
-var LocalStorageAdapter = class {
-  constructor() {
-    this.available = typeof localStorage !== "undefined";
+var WebStorageAdapter = class {
+  constructor(storageName) {
+    this.storageName = storageName;
+    this.available = typeof globalThis[storageName] !== "undefined" && globalThis[storageName] !== null;
+  }
+  get storage() {
+    return globalThis[this.storageName];
   }
   async get(key) {
     if (!this.available) return null;
-    try {
-      return localStorage.getItem(key);
-    } catch (error) {
-      console.error("LocalStorage get error:", error);
-      return null;
-    }
+    return this.storage.getItem(key);
   }
   async set(key, value) {
     if (!this.available) return false;
-    try {
-      localStorage.setItem(key, value);
-      return true;
-    } catch (error) {
-      console.error("LocalStorage set error:", error);
-      return false;
-    }
+    this.storage.setItem(key, value);
+    return true;
   }
   async remove(key) {
     if (!this.available) return false;
-    try {
-      localStorage.removeItem(key);
-      return true;
-    } catch (error) {
-      console.error("LocalStorage remove error:", error);
-      return false;
-    }
+    this.storage.removeItem(key);
+    return true;
   }
   async clear() {
     if (!this.available) return false;
-    try {
-      localStorage.clear();
-      return true;
-    } catch (error) {
-      console.error("LocalStorage clear error:", error);
-      return false;
-    }
+    this.storage.clear();
+    return true;
   }
 };
-var SessionStorageAdapter = class {
+var LocalStorageAdapter = class extends WebStorageAdapter {
   constructor() {
-    this.available = typeof sessionStorage !== "undefined";
-  }
-  async get(key) {
-    if (!this.available) return null;
-    try {
-      return sessionStorage.getItem(key);
-    } catch (error) {
-      console.error("SessionStorage get error:", error);
-      return null;
-    }
-  }
-  async set(key, value) {
-    if (!this.available) return false;
-    try {
-      sessionStorage.setItem(key, value);
-      return true;
-    } catch (error) {
-      console.error("SessionStorage set error:", error);
-      return false;
-    }
-  }
-  async remove(key) {
-    if (!this.available) return false;
-    try {
-      sessionStorage.removeItem(key);
-      return true;
-    } catch (error) {
-      console.error("SessionStorage remove error:", error);
-      return false;
-    }
+    super("localStorage");
   }
-  async clear() {
-    if (!this.available) return false;
-    try {
-      sessionStorage.clear();
-      return true;
-    } catch (error) {
-      console.error("SessionStorage clear error:", error);
-      return false;
-    }
+};
+var SessionStorageAdapter = class extends WebStorageAdapter {
+  constructor() {
+    super("sessionStorage");
   }
 };
 var IndexedDBAdapter = class {
@@ -93,19 +43,21 @@ var IndexedDBAdapter = class {
     this.storeName = storeName;
     this.available = typeof indexedDB !== "undefined";
     this.db = null;
+    this.opening = null;
   }
-  async init() {
-    if (!this.available) return false;
-    if (this.db) return true;
+  /**
+   * Open the database, creating the store in an upgrade. Without `version`,
+   * opens the current version (creating version 1 for a new database).
+   */
+  open(version) {
     return new Promise((resolve, reject) => {
-      const request = indexedDB.open(this.dbName, 1);
+      const request = version === void 0 ? indexedDB.open(this.dbName) : indexedDB.open(this.dbName, version);
       request.onerror = () => {
         console.error("IndexedDB open error:", request.error);
         reject(request.error);
       };
       request.onsuccess = () => {
-        this.db = request.result;
-        resolve(true);
+        resolve(request.result);
       };
       request.onupgradeneeded = (event) => {
         const db = event.target.result;
@@ -115,6 +67,27 @@ var IndexedDBAdapter = class {
       };
     });
   }
+  async init() {
+    if (!this.available) return false;
+    if (this.db) return true;
+    this.opening ??= (async () => {
+      let db = await this.open();
+      if (!db.objectStoreNames.contains(this.storeName)) {
+        const version = db.version + 1;
+        db.close();
+        db = await this.open(version);
+      }
+      db.onversionchange = () => {
+        db.close();
+        if (this.db === db) this.db = null;
+      };
+      this.db = db;
+      return true;
+    })().finally(() => {
+      this.opening = null;
+    });
+    return this.opening;
+  }
   async get(key) {
     if (!this.available) return null;
     await this.init();
@@ -200,47 +173,85 @@ var MemoryAdapter = class {
     return true;
   }
 };
-var SimpleEncryption = class {
-  constructor(key) {
-    this.key = key || "default-key";
+var ServerAdapter = class {
+  constructor() {
+    this.available = false;
+  }
+  async get() {
+    return null;
+  }
+  async set() {
+    return false;
+  }
+  async remove() {
+    return false;
+  }
+  async clear() {
+    return false;
   }
-  encrypt(text) {
-    let result = "";
-    for (let i = 0; i < text.length; i++) {
-      result += String.fromCharCode(
-        text.charCodeAt(i) ^ this.key.charCodeAt(i % this.key.length)
+};
+function toBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 32768) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  }
+  return btoa(binary);
+}
+function fromBase64(encoded) {
+  const binary = atob(encoded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+var XorObfuscation = class {
+  constructor(key) {
+    if (typeof key !== "string" || key.length === 0) {
+      throw new TypeError(
+        "createPersistentState: `encrypt: true` requires a non-empty `encryptionKey`. It is XOR obfuscation, not encryption; there is no default key."
       );
     }
-    return btoa(result);
-  }
-  decrypt(encrypted) {
-    const text = atob(encrypted);
-    let result = "";
-    for (let i = 0; i < text.length; i++) {
-      result += String.fromCharCode(
-        text.charCodeAt(i) ^ this.key.charCodeAt(i % this.key.length)
-      );
+    this.keyBytes = new globalThis.TextEncoder().encode(key);
+  }
+  xor(bytes) {
+    for (let i = 0; i < bytes.length; i++) {
+      bytes[i] ^= this.keyBytes[i % this.keyBytes.length];
     }
-    return result;
+    return bytes;
+  }
+  encode(text) {
+    return toBase64(this.xor(new globalThis.TextEncoder().encode(text)));
+  }
+  decode(encoded) {
+    return new globalThis.TextDecoder().decode(this.xor(fromBase64(encoded)));
   }
 };
-function createStorageAdapter(type) {
+function createStorageAdapter(type, options = {}) {
   switch (type) {
     case "localStorage":
       return new LocalStorageAdapter();
     case "sessionStorage":
       return new SessionStorageAdapter();
     case "indexedDB":
-      return new IndexedDBAdapter();
+      return new IndexedDBAdapter(options.dbName ?? void 0, options.storeName ?? void 0);
     case "memory":
       return new MemoryAdapter();
     default:
       return new LocalStorageAdapter();
   }
 }
+function createInstanceId() {
+  const cryptoApi = globalThis.crypto;
+  if (cryptoApi && typeof cryptoApi.randomUUID === "function") {
+    return cryptoApi.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
 function createPersistentState(initialState = {}, options = {}) {
   const opts = {
     storage: "localStorage",
+    adapter: null,
     key: "coherent-state",
     debounce: true,
     debounceDelay: 300,
@@ -260,11 +271,30 @@ function createPersistentState(initialState = {}, options = {}) {
     crossTab: false,
     ...options
   };
-  const adapter = createStorageAdapter(opts.storage);
-  const encryption = opts.encrypt ? new SimpleEncryption(opts.encryptionKey) : null;
+  const onServer = typeof window === "undefined";
+  const obfuscation = opts.encrypt ? new XorObfuscation(opts.encryptionKey) : null;
+  let adapter;
+  if (opts.adapter) {
+    adapter = opts.adapter;
+  } else if (onServer && opts.storage !== "memory") {
+    adapter = new ServerAdapter();
+  } else {
+    adapter = createStorageAdapter(opts.storage, opts);
+  }
+  const instanceId = createInstanceId();
   let state = { ...initialState };
   let saveTimeout = null;
+  let destroyed = false;
   const listeners = /* @__PURE__ */ new Set();
+  let initialRestorePending = false;
+  const touchedKeys = /* @__PURE__ */ new Set();
+  function reportError(error) {
+    if (opts.onError) {
+      opts.onError(error);
+    } else {
+      console.error("State persistence error:", error);
+    }
+  }
   function filterKeys(obj) {
     if (!obj || typeof obj !== "object") return obj;
     if (opts.include && Array.isArray(opts.include)) {
@@ -285,11 +315,31 @@ function createPersistentState(initialState = {}, options = {}) {
     }
     return obj;
   }
-  async function save(immediate = false) {
-    if (opts.debounce && !immediate) {
-      clearTimeout(saveTimeout);
-      saveTimeout = setTimeout(() => save(true), opts.debounceDelay);
-      return;
+  let channel = null;
+  if (opts.crossTab && !onServer && typeof BroadcastChannel !== "undefined") {
+    channel = new BroadcastChannel(`coherent-state-sync:${opts.key}`);
+    channel.onmessage = (event) => {
+      const message = event.data;
+      if (destroyed || !message || message.type !== "state-update" || message.source === instanceId) {
+        return;
+      }
+      const oldState = { ...state };
+      state = { ...state, ...message.state };
+      notifyListeners(oldState, state);
+    };
+    channel.unref?.();
+  }
+  function broadcast(filteredState) {
+    if (!channel) return;
+    try {
+      channel.postMessage({ type: "state-update", source: instanceId, state: filteredState });
+    } catch (error) {
+      reportError(error);
+    }
+  }
+  async function write() {
+    if (adapter.available === false) {
+      return false;
     }
     try {
       const filteredState = filterKeys(state);
@@ -301,31 +351,45 @@ function createPersistentState(initialState = {}, options = {}) {
         ttl: opts.ttl
       };
       let dataString = JSON.stringify(data);
-      if (encryption) {
-        dataString = encryption.encrypt(dataString);
+      if (obfuscation) {
+        dataString = obfuscation.encode(dataString);
+      }
+      const stored = await adapter.set(opts.key, dataString);
+      if (stored === false) {
+        throw new Error(`State "${opts.key}" could not be written to storage`);
       }
-      await adapter.set(opts.key, dataString);
       if (opts.onSave) {
         opts.onSave(filteredState);
       }
-      if (opts.crossTab && typeof BroadcastChannel !== "undefined") {
-        const channel = new BroadcastChannel("coherent-state-sync");
-        channel.postMessage({ type: "state-update", state: filteredState });
-        channel.close();
-      }
+      broadcast(filteredState);
+      return true;
     } catch (error) {
-      console.error("State save error:", error);
-      if (opts.onError) {
-        opts.onError(error);
-      }
+      reportError(error);
+      return false;
     }
   }
+  function save(immediate = false) {
+    if (destroyed) {
+      return Promise.resolve(false);
+    }
+    if (opts.debounce && !immediate) {
+      clearTimeout(saveTimeout);
+      saveTimeout = setTimeout(() => {
+        saveTimeout = null;
+        write();
+      }, opts.debounceDelay);
+      return void 0;
+    }
+    clearTimeout(saveTimeout);
+    saveTimeout = null;
+    return write();
+  }
   async function load() {
     try {
       let dataString = await adapter.get(opts.key);
       if (!dataString) return null;
-      if (encryption) {
-        dataString = encryption.decrypt(dataString);
+      if (obfuscation) {
+        dataString = obfuscation.decode(dataString);
       }
       const data = JSON.parse(dataString);
       if (data.ttl && data.timestamp) {
@@ -348,10 +412,7 @@ function createPersistentState(initialState = {}, options = {}) {
       }
       return loadedState;
     } catch (error) {
-      console.error("State load error:", error);
-      if (opts.onError) {
-        opts.onError(error);
-      }
+      reportError(error);
       return null;
     }
   }
@@ -368,6 +429,20 @@ function createPersistentState(initialState = {}, options = {}) {
       }
     });
   }
+  function applyLoaded(loaded, skipTouched) {
+    if (!loaded || typeof loaded !== "object") {
+      return false;
+    }
+    const updates = Object.fromEntries(
+      Object.entries(loaded).filter(([key]) => !skipTouched || !touchedKeys.has(key))
+    );
+    if (Object.keys(updates).length > 0) {
+      const oldState = { ...state };
+      state = { ...state, ...updates };
+      notifyListeners(oldState, state);
+    }
+    return true;
+  }
   function getState(key) {
     return key ? state[key] : { ...state };
   }
@@ -376,6 +451,9 @@ function createPersistentState(initialState = {}, options = {}) {
     if (typeof updates === "function") {
       updates = updates(oldState);
     }
+    if (initialRestorePending && updates && typeof updates === "object") {
+      for (const key of Object.keys(updates)) touchedKeys.add(key);
+    }
     state = { ...state, ...updates };
     notifyListeners(oldState, state);
     if (persist2) {
@@ -384,6 +462,10 @@ function createPersistentState(initialState = {}, options = {}) {
   }
   function resetState(persist2 = true) {
     const oldState = { ...state };
+    if (initialRestorePending) {
+      for (const key of Object.keys(oldState)) touchedKeys.add(key);
+      for (const key of Object.keys(initialState)) touchedKeys.add(key);
+    }
     state = { ...initialState };
     notifyListeners(oldState, state);
     if (persist2) {
@@ -391,33 +473,44 @@ function createPersistentState(initialState = {}, options = {}) {
     }
   }
   async function clearStorage() {
-    await adapter.remove(opts.key);
+    try {
+      await adapter.remove(opts.key);
+    } catch (error) {
+      reportError(error);
+    }
   }
   async function persist() {
-    await save(true);
+    return save(true);
   }
   async function restore() {
-    const loaded = await load();
-    if (loaded) {
-      const oldState = { ...state };
-      state = { ...state, ...loaded };
-      notifyListeners(oldState, state);
-      return true;
+    return applyLoaded(await load(), false);
+  }
+  async function destroy() {
+    if (destroyed) return;
+    const pending = saveTimeout !== null;
+    clearTimeout(saveTimeout);
+    saveTimeout = null;
+    if (pending) {
+      await write();
     }
-    return false;
-  }
-  if (opts.crossTab && typeof BroadcastChannel !== "undefined") {
-    const channel = new BroadcastChannel("coherent-state-sync");
-    channel.onmessage = (event) => {
-      if (event.data.type === "state-update") {
-        const oldState = { ...state };
-        state = { ...state, ...event.data.state };
-        notifyListeners(oldState, state);
-      }
-    };
-  }
-  if (opts.storage !== "memory") {
-    restore();
+    destroyed = true;
+    channel?.close();
+    channel = null;
+    listeners.clear();
+  }
+  let ready;
+  if (opts.storage !== "memory" || opts.adapter) {
+    initialRestorePending = true;
+    ready = load().then((loaded) => {
+      initialRestorePending = false;
+      if (destroyed) return false;
+      const restored = applyLoaded(loaded, true);
+      if (restored && touchedKeys.size > 0) save();
+      touchedKeys.clear();
+      return restored;
+    });
+  } else {
+    ready = Promise.resolve(false);
   }
   return {
     getState,
@@ -429,6 +522,9 @@ function createPersistentState(initialState = {}, options = {}) {
     clearStorage,
     load,
     save: () => save(true),
+    destroy,
+    /** Settles once the automatic restore on creation is done */
+    ready,
     get adapter() {
       return adapter;
     }