@use-everywhere/core 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,3 +1,37 @@
+// src/defaults.ts
+var DEFAULT_NAME = "use-everywhere";
+
+// src/debug.ts
+var observers = /* @__PURE__ */ new Map();
+function emitBusEvent(name, direction, wire) {
+  const set = observers.get(name);
+  if (!set) return;
+  const event = { name, direction, wire };
+  for (const fn of set) fn(event);
+}
+function observeBus(name, fn) {
+  let set = observers.get(name);
+  if (!set) {
+    set = /* @__PURE__ */ new Set();
+    observers.set(name, set);
+  }
+  set.add(fn);
+  return () => {
+    const current = observers.get(name);
+    if (!current) return;
+    current.delete(fn);
+    if (current.size === 0) observers.delete(name);
+  };
+}
+function enableDebug(options = {}) {
+  const name = options.name ?? DEFAULT_NAME;
+  const log = options.log ?? ((...args) => console.log(...args));
+  return observeBus(name, ({ direction, wire }) => {
+    const arrow = direction === "out" ? "\u2192" : "\u2190";
+    log(`[use-everywhere:${name}] ${arrow} ${wire.scope}/${wire.type}`, wire);
+  });
+}
+
 // src/ids.ts
 function newClientId() {
   return Math.random().toString(36).slice(2, 8);
@@ -64,11 +98,14 @@ function createBus(name, options, onShutdown) {
   let refs = 0;
   let closed = false;
   const post = (wire) => {
-    if (!closed) transport.post(wire);
+    if (closed) return;
+    emitBusEvent(name, "out", wire);
+    transport.post(wire);
   };
   const unsubscribe = transport.subscribe((data) => {
     if (!isBusWire(data)) return;
     if (data.clientId === clientId) return;
+    emitBusEvent(name, "in", data);
     if (data.scope === "presence" && data.type === "hello") {
       post({ v: 1, scope: "presence", type: "ping", clientId, kind });
     }
@@ -108,6 +145,9 @@ function createBus(name, options, onShutdown) {
     }
   };
 }
+function getBusNames() {
+  return [...registry.keys()];
+}
 function getBus(name, options = {}) {
   if (options.transport) {
     const bus2 = createBus(name, options, () => {
@@ -171,6 +211,24 @@ function newer(a, b) {
   return !b || a[0] > b[0] || a[0] === b[0] && a[1] > b[1];
 }
 
+// src/dev-freeze.ts
+var inDev = false;
+try {
+  inDev = process.env.NODE_ENV !== "production";
+} catch {
+}
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return;
+  Object.freeze(value);
+  for (const key of Object.keys(value)) {
+    deepFreeze(value[key]);
+  }
+}
+function freezeShared(value) {
+  if (inDev) deepFreeze(value);
+  return value;
+}
+
 // src/shared-store.ts
 function createSharedStore(name, initial, options = {}) {
   const bus = getBus(name, options);
@@ -178,12 +236,17 @@ function createSharedStore(name, initial, options = {}) {
   const accept = options.accept;
   const state = { ...initial };
   const versions = {};
-  for (const k in state) versions[k] = [0, clientId];
+  for (const k in state) {
+    versions[k] = [0, clientId];
+    freezeShared(state[k]);
+  }
   let snapshot = Object.freeze({ ...state });
+  let versionsSnapshot = Object.freeze({ ...versions });
   const listeners = /* @__PURE__ */ new Set();
   const keyListeners = /* @__PURE__ */ new Map();
   function notify(key, value, meta) {
     snapshot = Object.freeze({ ...state });
+    versionsSnapshot = Object.freeze({ ...versions });
     for (const fn of listeners) fn(key, value, meta);
     const set = keyListeners.get(key);
     if (set) for (const fn of set) fn();
@@ -191,7 +254,7 @@ function createSharedStore(name, initial, options = {}) {
   function applyRemote(key, value, version, meta) {
     if (!newer(version, versions[key])) return;
     versions[key] = version;
-    state[key] = value;
+    state[key] = freezeShared(value);
     notify(key, value, meta);
   }
   const unsubscribe = bus.subscribe((wire) => {
@@ -222,7 +285,7 @@ function createSharedStore(name, initial, options = {}) {
   function setKey(key, value) {
     const version = [(versions[key]?.[0] ?? 0) + 1, clientId];
     versions[key] = version;
-    state[key] = value;
+    state[key] = freezeShared(value);
     bus.post({
       v: 1,
       scope: "state",
@@ -242,11 +305,65 @@ function createSharedStore(name, initial, options = {}) {
       return true;
     }
   });
+  const persist = options.persist;
+  let flushPersist;
+  if (persist) {
+    const { adapter, keys, debounceMs = 100 } = persist;
+    const shouldPersist = (key) => !keys || keys.includes(key);
+    const hydrate = (saved2) => {
+      if (!saved2) return;
+      for (const key in saved2.state) {
+        const version = saved2.versions[key];
+        if (!version || !shouldPersist(key)) continue;
+        applyRemote(key, saved2.state[key], version, { clientId, kind: bus.kind, self: true });
+        bus.post({
+          v: 1,
+          scope: "state",
+          type: "patch",
+          key,
+          value: saved2.state[key],
+          version,
+          clientId,
+          kind: bus.kind
+        });
+      }
+    };
+    const collect = () => {
+      const out = { v: 1, state: {}, versions: {} };
+      for (const key in versions) {
+        const version = versions[key];
+        if (!version || version[0] === 0 || !shouldPersist(key)) continue;
+        out.state[key] = state[key];
+        out.versions[key] = version;
+      }
+      return out;
+    };
+    let timer;
+    flushPersist = () => {
+      clearTimeout(timer);
+      timer = void 0;
+      void adapter.write(collect());
+    };
+    const saved = adapter.read();
+    if (saved instanceof Promise) {
+      void saved.then(hydrate);
+    } else {
+      hydrate(saved);
+    }
+    listeners.add(() => {
+      if (timer !== void 0) return;
+      timer = setTimeout(flushPersist, debounceMs);
+    });
+    if (typeof document !== "undefined" && typeof addEventListener === "function") {
+      addEventListener("pagehide", flushPersist);
+    }
+  }
   bus.post({ v: 1, scope: "state", type: "hello", clientId, kind: bus.kind });
   return {
     clientId,
     state: proxy,
     getSnapshot: () => snapshot,
+    getVersions: () => versionsSnapshot,
     set(key, value) {
       const next = typeof value === "function" ? value(state[key]) : value;
       setKey(key, next);
@@ -269,8 +386,15 @@ function createSharedStore(name, initial, options = {}) {
       versions[key] = [0, clientId];
       state[key] = initialValue;
       snapshot = Object.freeze({ ...state });
+      versionsSnapshot = Object.freeze({ ...versions });
     },
     close() {
+      if (flushPersist) {
+        flushPersist();
+        if (typeof document !== "undefined" && typeof removeEventListener === "function") {
+          removeEventListener("pagehide", flushPersist);
+        }
+      }
       unsubscribe();
       listeners.clear();
       keyListeners.clear();
@@ -329,6 +453,167 @@ function createPresence(name, options = {}) {
   };
 }
 
+// src/leader.ts
+var NO_LEADER = Object.freeze({ leaderId: null, isLeader: false });
+function createLeader(name, options = {}) {
+  const heartbeatMs = options.heartbeatMs ?? 1e3;
+  const leaseMs = options.leaseMs ?? 3e3;
+  const busOptions = {
+    ...options.transport ? { transport: options.transport } : {},
+    ...options.kind ? { kind: options.kind } : {}
+  };
+  const bus = getBus(name, busOptions);
+  const clientId = bus.clientId;
+  let eligible = options.eligible ?? true;
+  let leaderId = null;
+  let term = [0, clientId];
+  let snapshot = NO_LEADER;
+  let beat;
+  let lease;
+  let closed = false;
+  const listeners = /* @__PURE__ */ new Set();
+  function setLeader(id) {
+    if (id === leaderId) return;
+    leaderId = id;
+    snapshot = Object.freeze({ leaderId: id, isLeader: id === clientId });
+    for (const fn of listeners) fn();
+  }
+  function armLease(delay) {
+    clearTimeout(lease);
+    lease = setTimeout(onLeaseExpired, delay);
+  }
+  function onLeaseExpired() {
+    if (closed) return;
+    setLeader(null);
+    if (eligible) claim();
+  }
+  function heartbeat() {
+    bus.post({ v: 1, scope: "leader", type: "heartbeat", term, clientId, kind: bus.kind });
+  }
+  function claim() {
+    term = [term[0] + 1, clientId];
+    setLeader(clientId);
+    bus.post({ v: 1, scope: "leader", type: "claim", term, clientId, kind: bus.kind });
+    clearInterval(beat);
+    beat = setInterval(heartbeat, heartbeatMs);
+  }
+  function stepDown(next) {
+    clearInterval(beat);
+    beat = void 0;
+    setLeader(next);
+  }
+  const unsubscribe = bus.subscribe((wire) => {
+    if (wire.scope !== "leader") return;
+    if (wire.type === "hello") {
+      if (leaderId === clientId) heartbeat();
+      return;
+    }
+    if (wire.type === "resign") {
+      if (wire.clientId !== leaderId) return;
+      setLeader(null);
+      armLease(0);
+      return;
+    }
+    if (newer(wire.term, term)) {
+      term = wire.term;
+      stepDown(wire.clientId);
+      armLease(leaseMs);
+      return;
+    }
+    if (leaderId === clientId) {
+      heartbeat();
+      return;
+    }
+    if (wire.clientId === leaderId) armLease(leaseMs);
+  });
+  function resign() {
+    if (leaderId !== clientId) return;
+    const resigning = term;
+    stepDown(null);
+    bus.post({ v: 1, scope: "leader", type: "resign", term: resigning, clientId, kind: bus.kind });
+    armLease(leaseMs);
+  }
+  const hasWindow = typeof document !== "undefined" && typeof addEventListener === "function";
+  const onPageHide = () => resign();
+  if (hasWindow) addEventListener("pagehide", onPageHide);
+  bus.post({ v: 1, scope: "leader", type: "hello", clientId, kind: bus.kind });
+  armLease(heartbeatMs);
+  return {
+    clientId,
+    getSnapshot: () => snapshot,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    resign,
+    setEligible(next) {
+      if (next === eligible) return;
+      eligible = next;
+      if (!next) {
+        if (leaderId === clientId) resign();
+        return;
+      }
+      if (leaderId === null) armLease(0);
+    },
+    close() {
+      closed = true;
+      resign();
+      clearInterval(beat);
+      clearTimeout(lease);
+      if (hasWindow) removeEventListener("pagehide", onPageHide);
+      unsubscribe();
+      listeners.clear();
+      bus.release();
+    }
+  };
+}
+
+// src/persist-web-storage.ts
+function isPersisted(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return candidate.v === 1 && typeof candidate.state === "object" && typeof candidate.versions === "object";
+}
+function webStorageAdapter(storage, key) {
+  const resolve = () => {
+    try {
+      return typeof storage === "function" ? storage() : storage;
+    } catch {
+      return void 0;
+    }
+  };
+  return {
+    read() {
+      try {
+        const raw = resolve()?.getItem(key);
+        if (!raw) return void 0;
+        const parsed = JSON.parse(raw);
+        return isPersisted(parsed) ? parsed : void 0;
+      } catch {
+        return void 0;
+      }
+    },
+    write(snapshot) {
+      try {
+        resolve()?.setItem(key, JSON.stringify(snapshot));
+      } catch {
+      }
+    },
+    remove() {
+      try {
+        resolve()?.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+function localStorageAdapter(key) {
+  return webStorageAdapter(() => globalThis.localStorage, key);
+}
+function sessionStorageAdapter(key) {
+  return webStorageAdapter(() => globalThis.sessionStorage, key);
+}
+
 // src/errors/handshake-timeout-error.ts
 var HandshakeTimeoutError = class extends Error {
   constructor(message = "handshake with the other window timed out") {
@@ -615,6 +900,7 @@ var MemoryHub = class {
 export {
   BroadcastChannelTransport,
   CID_PARAM,
+  DEFAULT_NAME,
   HandshakeTimeoutError,
   MemoryHub,
   MemoryTransport,
@@ -622,10 +908,17 @@ export {
   WindowClosedError,
   connectToOpener,
   createChannel,
+  createLeader,
   createPresence,
   createSharedStore,
   defaultTransport,
+  enableDebug,
+  getBusNames,
   isBroadcastChannelAvailable,
+  localStorageAdapter,
   newer,
-  openWindow
+  observeBus,
+  openWindow,
+  sessionStorageAdapter,
+  webStorageAdapter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-everywhere/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Cross-tab shared state, events, presence, and cross-origin window channels",
   "license": "MIT",
   "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
@@ -25,12 +25,19 @@
   },
   "type": "module",
   "sideEffects": false,
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [
@@ -41,13 +48,19 @@
       "name": "everything (import *)",
       "path": "dist/index.js",
       "import": "*",
-      "limit": "3.5 kB"
+      "limit": "4.5 kB"
+    },
+    {
+      "name": "createLeader",
+      "path": "dist/index.js",
+      "import": "{ createLeader }",
+      "limit": "1.3 kB"
     },
     {
       "name": "createSharedStore",
       "path": "dist/index.js",
       "import": "{ createSharedStore }",
-      "limit": "1.3 kB"
+      "limit": "1.6 kB"
     },
     {
       "name": "createChannel",
@@ -78,15 +91,27 @@
       "path": "dist/index.js",
       "import": "{ MemoryHub }",
       "limit": "300 B"
+    },
+    {
+      "name": "observeBus + enableDebug",
+      "path": "dist/index.js",
+      "import": "{ observeBus, enableDebug }",
+      "limit": "500 B"
+    },
+    {
+      "name": "localStorageAdapter",
+      "path": "dist/index.js",
+      "import": "{ localStorageAdapter }",
+      "limit": "500 B"
     }
   ],
   "devDependencies": {
-    "@size-limit/preset-small-lib": "^12.1.0",
+    "@size-limit/preset-small-lib": "^13.0.1",
     "@vitest/coverage-v8": "^4.1.10",
-    "happy-dom": "^20.10.6",
-    "size-limit": "^12.1.0",
-    "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
+    "happy-dom": "^20.11.1",
+    "size-limit": "^13.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   },
   "scripts": {