decantr 0.9.0

package/src/data/entity.js

@@ -0,0 +1,281 @@
+import { createSignal, createMemo, batch } from '../state/index.js';
+
+/**
+ * @template T
+ * @template {string|number} ID
+ * @typedef {Object} EntityStore
+ * @property {(entities: T[]) => void} addMany
+ * @property {(entity: T) => void} upsert
+ * @property {(id: ID, partial: Partial<T>) => void} update
+ * @property {(id: ID) => void} remove
+ * @property {() => void} clear
+ * @property {(id: ID) => () => T|undefined} get
+ * @property {() => T[]} all
+ * @property {() => number} count
+ * @property {(predicate: (entity: T) => boolean) => () => T[]} filter
+ * @property {(comparator: (a: T, b: T) => number) => () => T[]} sorted
+ * @property {(opts: { page: () => number, size: () => number }) => () => T[]} paginated
+ */
+
+/**
+ * @template T
+ * @template {string|number} [ID=string]
+ * @typedef {Object} EntityStoreOptions
+ * @property {(entity: T) => ID} getId - Extract the unique identifier from an entity
+ */
+
+/**
+ * Create a normalized entity collection store with per-entity reactivity.
+ *
+ * Entities are stored in a `Map<ID, T>` for O(1) lookups. A collection-level
+ * version signal drives derived views (`all`, `count`, `filter`, `sorted`,
+ * `paginated`). Per-entity signals are lazily created on first `.get(id)` call
+ * so that fine-grained subscriptions only pay for what they use.
+ *
+ * @template T
+ * @template {string|number} [ID=string]
+ * @param {EntityStoreOptions<T, ID>} options
+ * @returns {EntityStore<T, ID>}
+ *
+ * @example
+ * ```js
+ * const users = createEntityStore({ getId: u => u.id });
+ * users.addMany([{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }]);
+ * const alice = users.get('1'); // memo — only re-runs when entity '1' changes
+ * console.log(alice().name);    // 'Alice'
+ * ```
+ */
+export function createEntityStore(options) {
+  const { getId } = options;
+
+  // ── Internal storage ──────────────────────────────────────────────────
+
+  /** @type {Map<ID, T>} */
+  const entities = new Map();
+
+  /**
+   * Collection-level version counter. Incremented on any structural change
+   * (add, remove, clear). Derived memos read this to know when to recompute.
+   */
+  const [version, setVersion] = createSignal(0);
+
+  /**
+   * Per-entity signal cache. Lazily populated by `.get(id)`.
+   * Each entry is a `[getter, setter]` tuple from `createSignal`.
+   * @type {Map<ID, [() => T|undefined, (v: T|undefined) => void]>}
+   */
+  const entitySignals = new Map();
+
+  // ── Helpers ───────────────────────────────────────────────────────────
+
+  /** Bump the collection version so all derived views recompute. */
+  function bump() {
+    setVersion(v => v + 1);
+  }
+
+  /**
+   * Notify the per-entity signal for `id`, if one exists.
+   * @param {ID} id
+   * @param {T|undefined} value
+   */
+  function notifyEntity(id, value) {
+    const sig = entitySignals.get(id);
+    if (sig) sig[1](value);
+  }
+
+  /**
+   * Internal: set a single entity in the map and notify.
+   * Returns true if this was a new insertion (structural change).
+   * @param {T} entity
+   * @returns {boolean}
+   */
+  function setEntity(entity) {
+    const id = getId(entity);
+    const existed = entities.has(id);
+    entities.set(id, entity);
+    notifyEntity(id, entity);
+    return !existed;
+  }
+
+  // ── Public API ────────────────────────────────────────────────────────
+
+  /**
+   * Batch-add multiple entities. Entities with duplicate IDs overwrite
+   * existing entries (upsert semantics).
+   * @param {T[]} items
+   */
+  function addMany(items) {
+    if (items.length === 0) return;
+    batch(() => {
+      for (let i = 0; i < items.length; i++) {
+        setEntity(items[i]);
+      }
+      bump();
+    });
+  }
+
+  /**
+   * Add or replace a single entity.
+   * @param {T} entity
+   */
+  function upsert(entity) {
+    batch(() => {
+      setEntity(entity);
+      bump();
+    });
+  }
+
+  /**
+   * Shallow-merge a partial update into an existing entity.
+   * No-op if the entity does not exist.
+   * @param {ID} id
+   * @param {Partial<T>} partial
+   */
+  function update(id, partial) {
+    const existing = entities.get(id);
+    if (existing === undefined) return;
+    /** @type {T} */
+    const merged = { ...existing, ...partial };
+    batch(() => {
+      entities.set(id, merged);
+      notifyEntity(id, merged);
+      bump();
+    });
+  }
+
+  /**
+   * Remove an entity by ID. No-op if the entity does not exist.
+   * @param {ID} id
+   */
+  function remove(id) {
+    if (!entities.has(id)) return;
+    batch(() => {
+      entities.delete(id);
+      notifyEntity(id, undefined);
+      bump();
+    });
+  }
+
+  /**
+   * Remove all entities.
+   */
+  function clear() {
+    if (entities.size === 0) return;
+    batch(() => {
+      // Notify all existing per-entity signals
+      for (const [id] of entitySignals) {
+        notifyEntity(id, undefined);
+      }
+      entities.clear();
+      bump();
+    });
+  }
+
+  /**
+   * Get a per-entity memo. Returns a reactive getter that only recomputes
+   * when THIS specific entity changes — not when the collection changes.
+   *
+   * Signals are lazily created and cached in a Map. Subsequent calls with
+   * the same `id` return the same memo.
+   *
+   * @param {ID} id
+   * @returns {() => T|undefined}
+   */
+  function get(id) {
+    let sig = entitySignals.get(id);
+    if (!sig) {
+      sig = createSignal(entities.get(id));
+      entitySignals.set(id, sig);
+    }
+    // Wrap in a memo so downstream effects only fire on value change
+    return createMemo(() => {
+      const s = entitySignals.get(id);
+      return s ? s[0]() : undefined;
+    });
+  }
+
+  /**
+   * Reactive getter: all entities as an array (snapshot order matches
+   * insertion order of the underlying Map).
+   * @type {() => T[]}
+   */
+  const all = createMemo(() => {
+    version(); // subscribe to structural changes
+    return Array.from(entities.values());
+  });
+
+  /**
+   * Reactive getter: entity count.
+   * @type {() => number}
+   */
+  const count = createMemo(() => {
+    version();
+    return entities.size;
+  });
+
+  /**
+   * Create a filtered derived view. The returned memo recomputes whenever
+   * the collection changes structurally.
+   *
+   * @param {(entity: T) => boolean} predicate
+   * @returns {() => T[]}
+   */
+  function filter(predicate) {
+    return createMemo(() => {
+      version();
+      /** @type {T[]} */
+      const result = [];
+      for (const entity of entities.values()) {
+        if (predicate(entity)) result.push(entity);
+      }
+      return result;
+    });
+  }
+
+  /**
+   * Create a sorted derived view. The returned memo recomputes whenever
+   * the collection changes structurally.
+   *
+   * @param {(a: T, b: T) => number} comparator
+   * @returns {() => T[]}
+   */
+  function sorted(comparator) {
+    return createMemo(() => {
+      version();
+      return Array.from(entities.values()).sort(comparator);
+    });
+  }
+
+  /**
+   * Create a paginated derived view. `page` is 1-indexed. Returns an
+   * empty array if the page is out of range.
+   * Accepts plain numbers or signal getters for page/size.
+   *
+   * @param {{ page: number|(() => number), size: number|(() => number) }} opts
+   * @returns {() => T[]}
+   */
+  function paginated(opts) {
+    return createMemo(() => {
+      version();
+      const p = typeof opts.page === 'function' ? opts.page() : opts.page;
+      const s = typeof opts.size === 'function' ? opts.size() : opts.size;
+      const items = Array.from(entities.values());
+      const start = (p - 1) * s;
+      return items.slice(start, start + s);
+    });
+  }
+
+  return {
+    addMany,
+    upsert,
+    update,
+    remove,
+    clear,
+    get,
+    all,
+    count,
+    filter,
+    sorted,
+    paginated
+  };
+}

package/src/data/index.js

@@ -0,0 +1,13 @@
+/**
+ * Decantr Data Layer
+ * Server state, entity management, persistence, realtime, URL state, and worker integration.
+ *
+ * @module decantr/data
+ */
+
+export { createQuery, createInfiniteQuery, createMutation, queryClient } from './query.js';
+export { createEntityStore } from './entity.js';
+export { createURLSignal, createURLStore, parsers } from './url.js';
+export { createWebSocket, createEventSource } from './realtime.js';
+export { createPersisted, createIndexedDB, createCrossTab, createOfflineQueue } from './persist.js';
+export { createWorkerSignal, createWorkerQuery } from './worker.js';

package/src/data/persist.js

@@ -0,0 +1,225 @@
+import { createSignal, createEffect, batch } from '../state/index.js';
+
+/**
+ * Signal backed by localStorage or sessionStorage with cross-tab sync.
+ * @template T
+ * @param {string} key — storage key
+ * @param {T} init — fallback value when storage is empty
+ * @param {{ storage?: 'local' | 'session', serialize?: (v: T) => string, deserialize?: (s: string) => T }} [options]
+ * @returns {[() => T, (v: T | ((prev: T) => T)) => void]}
+ */
+export function createPersisted(key, init, options = {}) {
+  const storageType = options.storage || 'local';
+  const serialize = options.serialize || JSON.stringify;
+  const deserialize = options.deserialize || JSON.parse;
+
+  /** @returns {Storage | null} */
+  function getStore() {
+    if (typeof globalThis === 'undefined') return null;
+    try { return storageType === 'session' ? globalThis.sessionStorage : globalThis.localStorage; }
+    catch (_) { return null; }
+  }
+
+  // Read initial value from storage
+  let initial = init;
+  const store = getStore();
+  if (store) {
+    try {
+      const raw = store.getItem(key);
+      if (raw !== null) initial = deserialize(raw);
+    } catch (_) { /* corrupt data — use init */ }
+  }
+
+  const [get, set] = createSignal(initial);
+
+  // Persist on every change
+  createEffect(() => {
+    const value = get();
+    const s = getStore();
+    if (s) {
+      try { s.setItem(key, serialize(value)); }
+      catch (_) { /* storage full */ }
+    }
+  });
+
+  // Cross-tab sync via storage event (localStorage only)
+  if (storageType === 'local' && typeof globalThis !== 'undefined' && typeof globalThis.addEventListener === 'function') {
+    globalThis.addEventListener('storage', /** @param {StorageEvent} e */ (e) => {
+      if (e.key !== key || e.storageArea !== getStore()) return;
+      if (e.newValue === null) {
+        set(init);
+      } else {
+        try { set(deserialize(e.newValue)); }
+        catch (_) { /* corrupt cross-tab data */ }
+      }
+    });
+  }
+
+  return [get, /** @param {T | ((prev: T) => T)} next */ (next) => set(next)];
+}
+
+/**
+ * Reactive IndexedDB binding with lazy connection.
+ * @param {string} dbName
+ * @param {string} storeName
+ * @returns {{ get: <T>(key: IDBValidKey) => Promise<T>, set: (key: IDBValidKey, value: any) => Promise<void>, delete: (key: IDBValidKey) => Promise<void>, getAll: <T>() => Promise<T[]>, clear: () => Promise<void> }}
+ */
+export function createIndexedDB(dbName, storeName) {
+  /** @type {IDBDatabase | null} */
+  let db = null;
+  /** @type {Promise<IDBDatabase> | null} */
+  let opening = null;
+
+  function open() {
+    if (db) return Promise.resolve(db);
+    if (opening) return opening;
+    if (typeof indexedDB === 'undefined') return Promise.reject(new Error('IndexedDB is not available'));
+    opening = new Promise((resolve, reject) => {
+      const req = indexedDB.open(dbName, 1);
+      req.onupgradeneeded = () => {
+        if (!req.result.objectStoreNames.contains(storeName)) req.result.createObjectStore(storeName);
+      };
+      req.onsuccess = () => { db = req.result; opening = null; resolve(db); };
+      req.onerror = () => { opening = null; reject(req.error); };
+    });
+    return opening;
+  }
+
+  /** @param {IDBTransactionMode} mode @param {(s: IDBObjectStore) => IDBRequest} fn */
+  function tx(mode, fn) {
+    return open().then((d) => new Promise((resolve, reject) => {
+      const t = d.transaction(storeName, mode);
+      const req = fn(t.objectStore(storeName));
+      if (req) {
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+      } else {
+        t.oncomplete = () => resolve(undefined);
+        t.onerror = () => reject(t.error);
+      }
+    }));
+  }
+
+  return {
+    /** @template T @param {IDBValidKey} key @returns {Promise<T>} */
+    get(key) { return tx('readonly', (s) => s.get(key)); },
+    /** @param {IDBValidKey} key @param {any} value @returns {Promise<void>} */
+    set(key, value) { return tx('readwrite', (s) => s.put(value, key)); },
+    /** @param {IDBValidKey} key @returns {Promise<void>} */
+    delete(key) { return tx('readwrite', (s) => s.delete(key)); },
+    /** @template T @returns {Promise<T[]>} */
+    getAll() { return tx('readonly', (s) => s.getAll()); },
+    /** @returns {Promise<void>} */
+    clear() { return tx('readwrite', (s) => s.clear()); }
+  };
+}
+
+/**
+ * BroadcastChannel sync for a signal. Updates propagate across tabs.
+ * @template T
+ * @param {string} channel — channel name
+ * @param {[() => T, (v: T) => void]} signal — [getter, setter] tuple
+ * @returns {() => void} cleanup function
+ */
+export function createCrossTab(channel, signal) {
+  if (typeof BroadcastChannel === 'undefined') return () => {};
+
+  const [get, set] = signal;
+  const bc = new BroadcastChannel(channel);
+  const tabId = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : '__tab_' + Math.random().toString(36).slice(2) + Date.now().toString(36);
+  let skipEffect = false;
+
+  // Broadcast local changes to other tabs
+  createEffect(() => {
+    const value = get();
+    if (skipEffect) return;
+    try { bc.postMessage({ tabId, value }); }
+    catch (_) { /* channel closed or clone failed */ }
+  });
+
+  // Receive changes from other tabs
+  bc.onmessage = (e) => {
+    if (e.data && e.data.tabId !== tabId) {
+      skipEffect = true;
+      set(e.data.value);
+      skipEffect = false;
+    }
+  };
+
+  return () => { bc.close(); };
+}
+
+/**
+ * Queue operations while offline and flush on reconnect.
+ * @template T
+ * @param {{ process: (item: T) => Promise<any>, persist?: boolean, key?: string, retryDelay?: number }} options
+ * @returns {{ add: (item: T) => void, pending: () => T[], isOnline: () => boolean, flush: () => Promise<void> }}
+ */
+export function createOfflineQueue(options) {
+  const { process, persist = false, key = '__decantr_offline_queue', retryDelay = 1000 } = options;
+
+  // Restore persisted queue
+  let initial = [];
+  if (persist && typeof localStorage !== 'undefined') {
+    try {
+      const raw = localStorage.getItem(key);
+      if (raw) initial = JSON.parse(raw);
+    } catch (_) { /* corrupt — start fresh */ }
+  }
+
+  const [pending, setPending] = createSignal(initial);
+  const [isOnline, setIsOnline] = createSignal(
+    typeof navigator !== 'undefined' ? navigator.onLine : true
+  );
+  let flushing = false;
+
+  // Persist queue whenever it changes
+  if (persist) {
+    createEffect(() => {
+      const items = pending();
+      if (typeof localStorage !== 'undefined') {
+        try { localStorage.setItem(key, JSON.stringify(items)); }
+        catch (_) { /* storage full */ }
+      }
+    });
+  }
+
+  // Listen for online/offline events
+  if (typeof globalThis !== 'undefined' && typeof globalThis.addEventListener === 'function') {
+    globalThis.addEventListener('online', () => { setIsOnline(true); flush(); });
+    globalThis.addEventListener('offline', () => { setIsOnline(false); });
+  }
+
+  /** Process items sequentially (FIFO). Failed items stay in queue for retry. */
+  async function flush() {
+    if (flushing) return;
+    flushing = true;
+    try {
+      while (pending().length > 0 && isOnline()) {
+        const item = pending()[0];
+        try {
+          await process(item);
+          setPending((prev) => prev.slice(1));
+        } catch (_) {
+          await new Promise((r) => setTimeout(r, retryDelay));
+          if (!isOnline()) break;
+        }
+      }
+    } finally {
+      flushing = false;
+    }
+  }
+
+  return {
+    /** @param {T} item — add to queue; triggers flush if online */
+    add(item) {
+      setPending((prev) => [...prev, item]);
+      if (isOnline()) flush();
+    },
+    pending,
+    isOnline,
+    flush
+  };
+}