@adukiorg/anza 0.2.0

package/src/core/state/persist.js

@@ -0,0 +1,284 @@
+/**
+ * src/core/state/persist.js
+ *
+ * Transaction-aware IndexedDB persistence engine.
+ * Wraps low-level IDBRequest events with a clean Promise-based facade,
+ * manages chronologically ordered schema upgrades inside versionchange transactions,
+ * and exposes storage manager quota/persistence handlers.
+ *
+ * Source: doc 08 — State Management §5, §12, §13, §15
+ */
+
+class WriteQueue {
+  #queue = Promise.resolve();
+
+  enqueue(task) {
+    this.#queue = this.#queue.then(async () => {
+      let retries = 3;
+      let delay = 50;
+      while (retries > 0) {
+        try {
+          return await task();
+        } catch (err) {
+          retries--;
+          if (retries === 0) throw err;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          delay *= 2;
+        }
+      }
+    });
+    return this.#queue;
+  }
+}
+
+export class PlatformStorage {
+  #db = null;
+  #migrations = [];
+  #version = 1;
+  #dbName = 'platform-db';
+  #writeQueue = new WriteQueue();
+
+  /**
+   * Configures custom database name (primarily for test isolation).
+   */
+  setDatabaseName(name) {
+    this.#dbName = name;
+  }
+
+  /**
+   * Registers custom schema migration handlers.
+   * Migrations are index-mapped to the sequential schema upgrades (oldVersion -> N).
+   */
+  registerMigrations(migrations) {
+    this.#migrations = migrations;
+    this.#version = migrations.length + 1;
+  }
+
+  /**
+   * Connects to IndexedDB, evaluating upgrades sequentially inside transactions.
+   */
+  async open() {
+    if (this.#db) return this.#db;
+
+    return new Promise((resolve, reject) => {
+      const request = this.#migrations.length > 0
+        ? indexedDB.open(this.#dbName, this.#version)
+        : indexedDB.open(this.#dbName);
+
+      request.onupgradeneeded = (event) => {
+        const db = event.target.result;
+        const tx = event.target.transaction;
+        const oldVersion = event.oldVersion;
+
+        for (let i = oldVersion; i < this.#migrations.length; i++) {
+          try {
+            this.#migrations[i](db, tx);
+          } catch (err) {
+            console.error(`Storage schema migration failed for version v${i + 1}:`, err);
+            tx.abort();
+            return reject(err);
+          }
+        }
+      };
+
+      request.onsuccess = (event) => {
+        this.#db = event.target.result;
+        resolve(this.#db);
+      };
+
+      request.onerror = (event) => {
+        reject(event.target.error);
+      };
+    });
+  }
+
+  /**
+   * Retrieves a record from a specific store by its key.
+   */
+  async get(storeName, key) {
+    const db = await this.open();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readonly');
+      const store = tx.objectStore(storeName);
+      const request = store.get(key);
+
+      request.onsuccess = async () => {
+        const res = request.result;
+        if (res && typeof res === 'object' && 'value' in res && 'lastAccessed' in res) {
+          try {
+            await this.#updateAccess(storeName, key, res);
+          } catch (err) {
+            console.error('Failed to update access timestamp:', err);
+          }
+          resolve(res.value);
+        } else {
+          resolve(res || null);
+        }
+      };
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async #updateAccess(storeName, key, envelope) {
+    const db = await this.open();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readwrite');
+      const store = tx.objectStore(storeName);
+      envelope.lastAccessed = Date.now();
+      const req = store.put(envelope, key);
+      req.onsuccess = () => resolve();
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * Adds or updates a record inside a specific store.
+   */
+  async set(storeName, key, value, options = {}) {
+    return this.#writeQueue.enqueue(async () => {
+      const db = await this.open();
+      await this.#checkAndEvict(storeName);
+
+      const envelope = {
+        value,
+        lastAccessed: Date.now(),
+        expires: options.ttl ? Date.now() + options.ttl : null
+      };
+
+      return new Promise((resolve, reject) => {
+        const tx = db.transaction(storeName, 'readwrite');
+        const store = tx.objectStore(storeName);
+        
+        // key is optional if store has inline keyPath
+        const request = key ? store.put(envelope, key) : store.put(envelope);
+
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+      });
+    });
+  }
+
+  async #checkAndEvict(storeName) {
+    const estimate = await this.estimate();
+    if (!estimate.quota || !estimate.usage) return;
+
+    const ratio = estimate.usage / estimate.quota;
+    if (ratio > 0.8) {
+      if (typeof window !== 'undefined') {
+        window.dispatchEvent(new CustomEvent('quota', {
+          detail: { usage: estimate.usage, quota: estimate.quota }
+        }));
+      }
+
+      const db = await this.open();
+      if (!db.objectStoreNames.contains(storeName)) return;
+
+      const records = await new Promise((resolve) => {
+        const tx = db.transaction(storeName, 'readonly');
+        const store = tx.objectStore(storeName);
+        const list = [];
+        store.openCursor().onsuccess = (event) => {
+          const cursor = event.target.result;
+          if (cursor) {
+            list.push({ key: cursor.key, envelope: cursor.value });
+            cursor.continue();
+          } else {
+            resolve(list);
+          }
+        };
+      });
+
+      const now = Date.now();
+      const expired = records.filter(
+        (r) => r.envelope && typeof r.envelope === 'object' && r.envelope.expires && r.envelope.expires < now
+      );
+
+      if (expired.length > 0) {
+        await Promise.all(expired.map((r) => this.delete(storeName, r.key)));
+        const newEst = await this.estimate();
+        if ((newEst.usage / newEst.quota) <= 0.8) return;
+      }
+
+      const activeWrapped = records
+        .filter((r) => r.envelope && typeof r.envelope === 'object' && 'lastAccessed' in r.envelope)
+        .sort((a, b) => a.envelope.lastAccessed - b.envelope.lastAccessed);
+
+      for (const record of activeWrapped) {
+        await this.delete(storeName, record.key);
+        const newEst = await this.estimate();
+        if ((newEst.usage / newEst.quota) <= 0.8) break;
+      }
+    }
+  }
+
+  /**
+   * Deletes a record from a specific store.
+   */
+  async delete(storeName, key) {
+    const db = await this.open();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readwrite');
+      const store = tx.objectStore(storeName);
+      const request = store.delete(key);
+
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  /**
+   * Resolves a filtered list of records from a specific store.
+   */
+  async query(storeName, queryFn) {
+    const db = await this.open();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readonly');
+      const store = tx.objectStore(storeName);
+      const request = store.getAll();
+
+      request.onsuccess = () => {
+        const results = request.result || [];
+        const unwrapped = results.map((res) => {
+          if (res && typeof res === 'object' && 'value' in res && 'lastAccessed' in res) {
+            return res.value;
+          }
+          return res;
+        });
+        resolve(queryFn ? unwrapped.filter(queryFn) : unwrapped);
+      };
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  /**
+   * Fetches browser disk space allocation parameters for this origin.
+   */
+  async estimate() {
+    if (typeof navigator !== 'undefined' && navigator.storage && navigator.storage.estimate) {
+      return navigator.storage.estimate();
+    }
+    return { quota: 0, usage: 0 };
+  }
+
+  /**
+   * Requests origin storage to be marked as persistent (exempt from browser eviction).
+   */
+  async persist() {
+    if (typeof navigator !== 'undefined' && navigator.storage && navigator.storage.persist) {
+      return navigator.storage.persist();
+    }
+    return false;
+  }
+
+  /**
+   * Checks whether the origin has persistent storage enabled.
+   */
+  async isPersisted() {
+    if (typeof navigator !== 'undefined' && navigator.storage && navigator.storage.persisted) {
+      return navigator.storage.persisted();
+    }
+    return false;
+  }
+}
+
+export const storage = new PlatformStorage();

package/src/core/state/store.js

@@ -0,0 +1,308 @@
+/**
+ * src/core/state/store.js
+ *
+ * Proxy-based reactive state store.
+ * Tracks reactive read accesses (get) dynamically when an active subscriber
+ * context is present, and schedules microtask-batched triggers on writes.
+ * Supports manual batching (batch), serialization snapshots, and hydration.
+ *
+ * Source: doc 08 — State Management §4, §7, §8, §9
+ */
+
+import { derived } from './derived.js';
+import { sync } from './sync.js';
+
+let activeSubscriber = null;
+
+/**
+ * Sets the global active subscriber registry (used by reactive derived nodes).
+ */
+export function setActiveSubscriber(subscriber) {
+  activeSubscriber = subscriber;
+}
+
+/**
+ * Returns the current active subscriber registry.
+ */
+export function getActiveSubscriber() {
+  return activeSubscriber;
+}
+
+function fastClone(obj) {
+  if (obj === null || typeof obj !== 'object') return obj;
+  if (obj instanceof Date) return new Date(obj.getTime());
+  if (obj instanceof RegExp) return new RegExp(obj);
+  if (Array.isArray(obj)) {
+    return obj.map(fastClone);
+  }
+  if (Object.getPrototypeOf(obj) === Object.prototype) {
+    const copy = {};
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        copy[key] = fastClone(obj[key]);
+      }
+    }
+    return copy;
+  }
+  if (typeof structuredClone === 'function') {
+    return structuredClone(obj);
+  }
+  return JSON.parse(JSON.stringify(obj));
+}
+
+export class ReactiveStore {
+  #target;
+  #state;
+  #listeners = new Map(); // key -> Set<callback>
+  #batching = false;
+  #pendingNotifications = new Set();
+  #onMutationCallback = null;
+  #options;
+  #proxies;
+  #previousValues = new Map(); // Track previous values for subscribe callbacks
+
+  constructor(initial = {}, options = {}) {
+    const self = this;
+    this.#target = initial;
+    this.#options = options;
+    this.#proxies = new WeakMap();
+
+    this.#state = new Proxy(initial, {
+      get(target, key) {
+        self.#track(key);
+        const val = Reflect.get(target, key);
+        if (self.#options.deep && val !== null && typeof val === 'object' && !(val instanceof Date) && !(val instanceof RegExp)) {
+          return self.#createProxy(val, key);
+        }
+        return val;
+      },
+      set(target, key, value) {
+        const oldVal = Reflect.get(target, key);
+        if (Object.is(oldVal, value)) return true;
+        Reflect.set(target, key, value);
+        self.#trigger(key);
+        return true;
+      },
+      deleteProperty(target, key) {
+        if (Reflect.has(target, key)) {
+          Reflect.deleteProperty(target, key);
+          self.#trigger(key);
+        }
+        return true;
+      }
+    });
+  }
+
+  #createProxy(target, topLevelKey) {
+    if (target === null || typeof target !== 'object') return target;
+    if (target instanceof Date || target instanceof RegExp) return target;
+    
+    if (this.#proxies.has(target)) {
+      return this.#proxies.get(target);
+    }
+
+    const self = this;
+    const proxy = new Proxy(target, {
+      get(t, key) {
+        if (key === '__raw__') return t;
+        self.#track(topLevelKey);
+        const val = Reflect.get(t, key);
+        if (val !== null && typeof val === 'object' && !(val instanceof Date) && !(val instanceof RegExp)) {
+          return self.#createProxy(val, topLevelKey);
+        }
+        return val;
+      },
+      set(t, key, val) {
+        const oldVal = Reflect.get(t, key);
+        if (Object.is(oldVal, val)) return true;
+        Reflect.set(t, key, val);
+        self.#trigger(topLevelKey);
+        if (self.#onMutationCallback) {
+          self.#onMutationCallback(topLevelKey, self.#state[topLevelKey], 'local');
+        }
+        return true;
+      },
+      deleteProperty(t, key) {
+        if (Reflect.has(t, key)) {
+          Reflect.deleteProperty(t, key);
+          self.#trigger(topLevelKey);
+          if (self.#onMutationCallback) {
+            self.#onMutationCallback(topLevelKey, self.#state[topLevelKey], 'local');
+          }
+        }
+        return true;
+      }
+    });
+
+    this.#proxies.set(target, proxy);
+    return proxy;
+  }
+
+  /**
+   * Retrieves a property value from the reactive state.
+   */
+  get(key) {
+    return this.#state[key];
+  }
+
+  /**
+   * Modifies a property value in the reactive state.
+   */
+  set(key, value, source = 'local') {
+    this.#previousValues.set(key, this.#state[key]);
+    this.#state[key] = value;
+    if (this.#onMutationCallback) {
+      this.#onMutationCallback(key, value, source);
+    }
+  }
+
+  /**
+   * Registers a callback to monitor all state mutations (used by BroadcastChannel sync).
+   */
+  onMutation(callback) {
+    this.#onMutationCallback = callback;
+  }
+
+  #track(key) {
+    if (activeSubscriber) {
+      activeSubscriber.add({ store: this, key });
+    }
+  }
+
+  #trigger(key) {
+    this.#pendingNotifications.add(key);
+    if (!this.#batching) {
+      this.#scheduleQueue();
+    }
+  }
+
+  #scheduleQueue() {
+    queueMicrotask(() => {
+      if (this.#pendingNotifications.size === 0) return;
+      const keys = [...this.#pendingNotifications];
+      this.#pendingNotifications.clear();
+
+      // Map each callback to one representative changed key so subscribers are
+      // notified once per flush while still receiving the current value + key.
+      const callbackKey = new Map();
+      for (const key of keys) {
+        const set = this.#listeners.get(key);
+        if (set) {
+          for (const cb of set) {
+            if (!callbackKey.has(cb)) callbackKey.set(cb, key);
+          }
+        }
+      }
+
+      for (const [cb, key] of callbackKey) {
+        try {
+          const current = this.get(key);
+          const previous = this.#previousValues.get(key);
+          cb(current, key, previous);
+          this.#previousValues.set(key, current);
+        } catch (err) {
+          console.error('Error executing store change subscription:', err);
+        }
+      }
+    });
+  }
+
+  /**
+   * Subscribes to changes on a specific state key.
+   */
+  subscribe(key, callback, signal) {
+    if (signal?.aborted) return () => {};
+
+    if (!this.#listeners.has(key)) {
+      this.#listeners.set(key, new Set());
+    }
+    this.#listeners.get(key).add(callback);
+
+    const dispose = () => {
+      const set = this.#listeners.get(key);
+      if (set) {
+        set.delete(callback);
+        if (set.size === 0) {
+          this.#listeners.delete(key);
+        }
+      }
+    };
+
+    if (signal) {
+      signal.addEventListener('abort', dispose);
+    }
+
+    return dispose;
+  }
+
+  /**
+   * Batches multiple mutations atomically in a single microtask notification.
+   */
+  batch(fn) {
+    this.#batching = true;
+    try {
+       fn();
+    } finally {
+       this.#batching = false;
+       this.#scheduleQueue();
+    }
+  }
+
+  /**
+   * Serializes a deep-cloned copy of the current store state.
+   */
+  snapshot() {
+    if (this.#options?.clone) {
+      return this.#options.clone(this.#target);
+    }
+    return fastClone(this.#target);
+  }
+
+  /**
+   * Re-hydrates the store state from a snapshot without firing redundant triggers.
+   */
+  hydrate(snapshot) {
+    this.batch(() => {
+      for (const [key, value] of Object.entries(snapshot)) {
+        this.#state[key] = value;
+      }
+    });
+  }
+
+  /**
+   * Cleans and resets the store with new initial values.
+   */
+  reset(initial = {}) {
+    this.batch(() => {
+      for (const key of Object.keys(this.#state)) {
+        delete this.#state[key];
+      }
+      for (const [key, value] of Object.entries(initial)) {
+        this.#state[key] = value;
+      }
+    });
+  }
+
+  /**
+   * Replicates designated store keys across active browser tabs.
+   */
+  broadcast(channelName, keys = []) {
+    return sync(this, keys, channelName);
+  }
+
+  /**
+   * Syncs designated store keys across active browser tabs (alias for broadcast).
+   */
+  sync(keys = [], channelName) {
+    return this.broadcast(channelName, keys);
+  }
+
+  /**
+   * Creates a reactive derived node linked to this store.
+   */
+  derived(keys, compute) {
+    const fn = typeof keys === 'function' ? keys : compute;
+    return derived(fn);
+  }
+}
+

package/src/core/state/sync.js

@@ -0,0 +1,46 @@
+/**
+ * src/core/state/sync.js
+ *
+ * Cross-tab state synchronization.
+ * Leverages native BroadcastChannel to replicate designated state keys
+ * between active browser tabs while avoiding update cycles.
+ *
+ * Source: doc 08 — State Management §11
+ */
+
+/**
+ * Synchronizes reactive store mutations across multiple active browser tabs.
+ */
+export function sync(store, keys = [], channelName = 'platform-state-sync') {
+  if (typeof window === 'undefined' || typeof BroadcastChannel === 'undefined') {
+    return () => {};
+  }
+
+  const channel = new BroadcastChannel(channelName);
+
+  // Replicate state mutations to other tabs
+  store.onMutation((key, value, source) => {
+    if (source === 'local') {
+      // Sync only whitelisted keys (or all keys if whitelist is empty)
+      if (keys.length === 0 || keys.includes(key)) {
+        channel.postMessage({ key, value });
+      }
+    }
+  });
+
+  // Receive replication messages from other tabs
+  channel.onmessage = (event) => {
+    if (!event.data) return;
+    const { key, value } = event.data;
+
+    if (keys.length === 0 || keys.includes(key)) {
+      // Apply values with a 'broadcast' source tag to prevent circular replication echo
+      store.set(key, value, 'broadcast');
+    }
+  };
+
+  // Return a cleanup disposer function
+  return () => {
+    channel.close();
+  };
+}