@use-everywhere/core 0.6.0 → 0.7.0

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(src_exports, {
   DEFAULT_NAME: () => DEFAULT_NAME,
   HandshakeTimeoutError: () => HandshakeTimeoutError,
   NoopTransport: () => NoopTransport,
+  StorageTransport: () => StorageTransport,
   WindowClosedError: () => WindowClosedError,
   connectToOpener: () => connectToOpener,
   createChannel: () => createChannel,
@@ -34,7 +35,9 @@ __export(src_exports, {
   defaultTransport: () => defaultTransport,
   enableDebug: () => enableDebug,
   getBusNames: () => getBusNames,
+  getTransportKind: () => getTransportKind,
   isBroadcastChannelAvailable: () => isBroadcastChannelAvailable,
+  isStorageEventAvailable: () => isStorageEventAvailable,
   localStorageAdapter: () => localStorageAdapter,
   newer: () => newer,
   observeBus: () => observeBus,
@@ -121,9 +124,31 @@ function newMsgId() {
   return randomHex(16);
 }
 
+// src/rendezvous.ts
+var PROTOCOL = 1;
+var TABLE = /* @__PURE__ */ Symbol.for(`use-everywhere.rendezvous.${PROTOCOL}`);
+var CENSUS = /* @__PURE__ */ Symbol.for("use-everywhere.rendezvous.census");
+function announce() {
+  const g = globalThis;
+  const census = g[CENSUS] ?? (g[CENSUS] = { protocols: [] });
+  if (census.protocols.includes(PROTOCOL)) return;
+  census.protocols.push(PROTOCOL);
+  if (census.protocols.length > 1) {
+    devWarn(
+      `[use-everywhere] two incompatible versions of this library are loaded on one page (rendezvous protocols ${census.protocols.join(", ")}). They will not share a client identity: expect one presence entry per version and no synchronous delivery between them. They still sync over the bus. Align the versions to fix it.`
+    );
+  }
+}
+function busTable() {
+  announce();
+  const g = globalThis;
+  return g[TABLE] ?? (g[TABLE] = /* @__PURE__ */ new Map());
+}
+
 // src/transport/broadcast-channel-transport.ts
 var BroadcastChannelTransport = class {
   constructor(name) {
+    this.kind = "broadcast-channel";
     this.listeners = /* @__PURE__ */ new Set();
     this.bc = new BroadcastChannel(name);
     this.bc.onmessage = (event) => {
@@ -145,6 +170,9 @@ var BroadcastChannelTransport = class {
 
 // src/transport/noop-transport.ts
 var NoopTransport = class {
+  constructor() {
+    this.kind = "none";
+  }
   post() {
   }
   subscribe() {
@@ -155,115 +183,217 @@ var NoopTransport = class {
   }
 };
 
+// src/transport/storage-transport.ts
+var StorageTransport = class {
+  constructor(name, storage = globalThis.localStorage) {
+    this.kind = "storage";
+    this.listeners = /* @__PURE__ */ new Set();
+    this.seq = 0;
+    if (!storage) {
+      throw new Error(
+        "[use-everywhere] StorageTransport needs localStorage; workers have none. Use BroadcastChannel there."
+      );
+    }
+    this.key = `use-everywhere:bus:${name}`;
+    this.storage = storage;
+    this.onStorage = (event) => {
+      if (event.key !== this.key || event.newValue === null) return;
+      let payload;
+      try {
+        payload = JSON.parse(event.newValue);
+      } catch {
+        return;
+      }
+      for (const listener of this.listeners) listener(payload.data);
+    };
+    addEventListener("storage", this.onStorage);
+  }
+  post(data) {
+    const envelope = JSON.stringify({ seq: this.seq++, data }, rejectUnrepresentable);
+    try {
+      this.storage.setItem(this.key, envelope);
+      this.storage.removeItem(this.key);
+    } catch {
+    }
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  close() {
+    this.listeners.clear();
+    removeEventListener("storage", this.onStorage);
+  }
+};
+function rejectUnrepresentable(_key, value) {
+  if (typeof value === "function" || typeof value === "symbol") {
+    throw new TypeError(`${typeof value} values cannot be shared`);
+  }
+  return value;
+}
+
 // src/transport/default-transport.ts
 function isBroadcastChannelAvailable() {
   return typeof BroadcastChannel !== "undefined";
 }
+function isStorageEventAvailable() {
+  if (typeof addEventListener !== "function") return false;
+  try {
+    const storage = globalThis.localStorage;
+    if (!storage) return false;
+    const probe = "use-everywhere:probe";
+    storage.setItem(probe, "1");
+    storage.removeItem(probe);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function defaultTransport(name) {
-  return isBroadcastChannelAvailable() ? new BroadcastChannelTransport(name) : new NoopTransport();
+  if (isBroadcastChannelAvailable()) return new BroadcastChannelTransport(name);
+  if (isStorageEventAvailable()) {
+    devWarn(
+      "[use-everywhere] no BroadcastChannel; using the storage-event fallback. Values serialise as JSON, not structured clone \u2014 keep them JSON-shaped."
+    );
+    return new StorageTransport(name);
+  }
+  devWarn(
+    "[use-everywhere] no BroadcastChannel and no usable localStorage: nothing is shared between tabs. Storage is probably blocked."
+  );
+  return new NoopTransport();
 }
 
 // src/bus.ts
 function isBusWire(data) {
-  return typeof data === "object" && data !== null && data.v === 1;
+  if (typeof data !== "object" || data === null) return false;
+  const wire = data;
+  return wire.v === 1 && typeof wire.scope === "string" && typeof wire.type === "string" && typeof wire.clientId === "string";
 }
 function defaultKind() {
   return typeof document === "undefined" ? "worker" : "tab";
 }
-var registry = /* @__PURE__ */ new Map();
-function createBus(name, options, onShutdown) {
+var SHARED_WITHIN_CLIENT = /* @__PURE__ */ new Set(["state", "event"]);
+function createBusCore(name, options, onShutdown) {
   const transport = (options.transport ?? defaultTransport)(name);
   const clientId = newClientId();
   const kind = options.kind ?? defaultKind();
-  const listeners = /* @__PURE__ */ new Set();
+  const handles = /* @__PURE__ */ new Set();
   let refs = 0;
   let closed = false;
-  const post = (wire) => {
+  const deliver = (wire, from) => {
+    for (const handle of handles) {
+      if (handle === from) continue;
+      for (const fn of handle.listeners) fn(wire);
+    }
+  };
+  const post = (wire, from) => {
     if (closed) return;
     emitBusEvent(name, "out", wire);
     transport.post(wire);
+    if (SHARED_WITHIN_CLIENT.has(wire.scope)) deliver(wire, from);
   };
   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 });
+      post({ v: 1, scope: "presence", type: "ping", clientId, kind }, null);
     }
-    for (const fn of listeners) fn(data);
+    deliver(data, null);
   });
-  post({ v: 1, scope: "presence", type: "hello", clientId, kind });
+  post({ v: 1, scope: "presence", type: "hello", clientId, kind }, null);
   const heartbeat = setInterval(
-    () => post({ v: 1, scope: "presence", type: "ping", clientId, kind }),
+    () => post({ v: 1, scope: "presence", type: "ping", clientId, kind }, null),
     options.heartbeatMs ?? 2e3
   );
-  const sayBye = () => post({ v: 1, scope: "presence", type: "bye", clientId, kind });
+  const sayBye = () => post({ v: 1, scope: "presence", type: "bye", clientId, kind }, null);
   const onPageShow = (event) => {
     if (!event.persisted) return;
-    post({ v: 1, scope: "presence", type: "hello", clientId, kind });
+    post({ v: 1, scope: "presence", type: "hello", clientId, kind }, null);
+  };
+  const onVisible = () => {
+    if (document.visibilityState === "visible") {
+      post({ v: 1, scope: "presence", type: "hello", clientId, kind }, null);
+    }
   };
   const hasWindow = typeof document !== "undefined" && typeof addEventListener === "function";
   if (hasWindow) {
     addEventListener("pagehide", sayBye);
     addEventListener("pageshow", onPageShow);
+    addEventListener("visibilitychange", onVisible);
   }
+  const shutdown = () => {
+    sayBye();
+    closed = true;
+    clearInterval(heartbeat);
+    if (hasWindow) {
+      removeEventListener("pagehide", sayBye);
+      removeEventListener("pageshow", onPageShow);
+      removeEventListener("visibilitychange", onVisible);
+    }
+    unsubscribe();
+    transport.close();
+    handles.clear();
+    onShutdown();
+  };
   return {
     name,
     clientId,
     kind,
+    transportKind: transport.kind ?? "custom",
     heartbeatMs: options.heartbeatMs ?? 2e3,
-    post,
-    subscribe(fn) {
-      listeners.add(fn);
-      return () => listeners.delete(fn);
-    },
-    acquire() {
+    connect() {
+      const handle = { listeners: /* @__PURE__ */ new Set() };
+      handles.add(handle);
       refs++;
-    },
-    release() {
-      if (closed) return;
-      refs--;
-      if (refs > 0) return;
-      sayBye();
-      closed = true;
-      clearInterval(heartbeat);
-      if (hasWindow) {
-        removeEventListener("pagehide", sayBye);
-        removeEventListener("pageshow", onPageShow);
-      }
-      unsubscribe();
-      transport.close();
-      listeners.clear();
-      onShutdown();
+      let released = false;
+      return {
+        name,
+        clientId,
+        kind,
+        transportKind: transport.kind ?? "custom",
+        post: (wire) => post(wire, handle),
+        subscribe(fn) {
+          handle.listeners.add(fn);
+          return () => handle.listeners.delete(fn);
+        },
+        release() {
+          if (released || closed) return;
+          released = true;
+          handles.delete(handle);
+          handle.listeners.clear();
+          refs--;
+          if (refs === 0) shutdown();
+        }
+      };
     }
   };
 }
 function getBusNames() {
-  return [...registry.keys()];
+  return [...busTable().keys()];
+}
+function getTransportKind(name) {
+  return busTable().get(name)?.transportKind ?? null;
 }
 function getBus(name, options = {}) {
-  if (options.transport) {
-    const bus2 = createBus(name, options, () => {
-    });
-    bus2.acquire();
-    return bus2;
-  }
-  let bus = registry.get(name);
-  if (!bus) {
-    bus = createBus(name, options, () => registry.delete(name));
-    registry.set(name, bus);
+  if (options.transport) return createBusCore(name, options, () => {
+  }).connect();
+  const table = busTable();
+  let core = table.get(name);
+  if (!core) {
+    core = createBusCore(name, options, () => table.delete(name));
+    table.set(name, core);
   } else {
-    if (options.heartbeatMs !== void 0 && options.heartbeatMs !== bus.heartbeatMs) {
+    if (options.heartbeatMs !== void 0 && options.heartbeatMs !== core.heartbeatMs) {
       devWarn(
         `[use-everywhere] bus "${name}": heartbeatMs ignored \u2014 the first creator fixes bus options`
       );
     }
-    if (options.kind !== void 0 && options.kind !== bus.kind) {
+    if (options.kind !== void 0 && options.kind !== core.kind) {
       devWarn(`[use-everywhere] bus "${name}": kind ignored \u2014 the first creator fixes bus options`);
     }
   }
-  bus.acquire();
-  return bus;
+  return core.connect();
 }
 
 // src/channel.ts
@@ -315,6 +445,9 @@ function createChannel(name, options = {}) {
 function newer(a, b) {
   return !b || a[0] > b[0] || a[0] === b[0] && a[1] > b[1];
 }
+function isVersion(value) {
+  return Array.isArray(value) && value.length === 2 && typeof value[0] === "number" && Number.isFinite(value[0]) && typeof value[1] === "string";
+}
 
 // src/dev-freeze.ts
 var inDev2 = false;
@@ -354,7 +487,7 @@ function createSharedStore(name, initial, options = {}) {
     const live = liveStores.get(name) ?? 0;
     if (live > 0) {
       devWarn(
-        `[use-everywhere] second shared store for "${name}" in this tab \u2014 stores on one page never hear each other and will diverge. Reuse one per name.`
+        `[use-everywhere] second shared store for "${name}" in this tab \u2014 they stay in sync, but you are paying twice for one store's state, subscriptions, and persistence writes. Reuse one per name.`
       );
     }
     liveStores.set(name, live + 1);
@@ -402,11 +535,14 @@ function createSharedStore(name, initial, options = {}) {
     }
     if (accept && !accept(meta)) return;
     if (wire.type === "patch") {
+      if (typeof wire.key !== "string" || !isVersion(wire.version)) return;
       applyRemote(wire.key, wire.value, wire.version, meta);
     } else {
+      const versions2 = wire.versions;
+      if (typeof versions2 !== "object" || versions2 === null) return;
       for (const k in wire.state) {
-        const version = wire.versions[k];
-        if (version) applyRemote(k, wire.state[k], version, meta);
+        const version = versions2[k];
+        if (isVersion(version)) applyRemote(k, wire.state[k], version, meta);
       }
     }
   });
@@ -560,6 +696,7 @@ function createSharedStore(name, initial, options = {}) {
 // src/presence.ts
 function createPresence(name, options = {}) {
   const pruneAfterMs = options.pruneAfterMs ?? 5e3;
+  const probeGraceMs = options.probeGraceMs ?? 1e3;
   const bus = getBus(name, options);
   const peers = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Set();
@@ -569,6 +706,7 @@ function createPresence(name, options = {}) {
     for (const fn of listeners) fn();
   }
   const unsubscribe = bus.subscribe((wire) => {
+    if (wire.clientId === bus.clientId) return;
     if (wire.scope === "presence" && wire.type === "bye") {
       if (peers.delete(wire.clientId)) notify();
       return;
@@ -577,19 +715,41 @@ function createPresence(name, options = {}) {
     peers.set(wire.clientId, { id: wire.clientId, kind: wire.kind, lastSeen: Date.now() });
     if (!existing) notify();
   });
+  bus.post({ v: 1, scope: "presence", type: "hello", clientId: bus.clientId, kind: bus.kind });
+  const probed = /* @__PURE__ */ new Map();
   const prune = setInterval(
     () => {
-      const cutoff = Date.now() - pruneAfterMs;
+      const now = Date.now();
+      const silentSince = now - pruneAfterMs;
       let changed = false;
+      let needProbe = false;
       for (const [id, peer] of peers) {
-        if (peer.lastSeen < cutoff) {
+        if (peer.lastSeen >= silentSince) {
+          probed.delete(id);
+          continue;
+        }
+        const askedAt = probed.get(id);
+        if (askedAt === void 0) {
+          probed.set(id, now);
+          needProbe = true;
+        } else if (now - askedAt >= probeGraceMs) {
           peers.delete(id);
+          probed.delete(id);
           changed = true;
         }
       }
+      if (needProbe) {
+        bus.post({
+          v: 1,
+          scope: "presence",
+          type: "hello",
+          clientId: bus.clientId,
+          kind: bus.kind
+        });
+      }
       if (changed) notify();
     },
-    Math.max(500, Math.floor(pruneAfterMs / 2))
+    Math.max(250, Math.floor(Math.min(pruneAfterMs, probeGraceMs) / 2))
   );
   let closed = false;
   return {
@@ -610,9 +770,149 @@ function createPresence(name, options = {}) {
   };
 }
 
-// src/leader.ts
+// src/leader-web-locks.ts
 var NO_LEADER = Object.freeze({ leaderId: null, isLeader: false });
+function createWebLocksLeader(name, options, locks) {
+  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 snapshot = NO_LEADER;
+  let closed = false;
+  const listeners = /* @__PURE__ */ new Set();
+  const waiters = /* @__PURE__ */ new Set();
+  let releaseHeld = null;
+  let pending = null;
+  function setLeader(id) {
+    if (id === leaderId) return;
+    leaderId = id;
+    snapshot = Object.freeze({ leaderId: id, isLeader: id === clientId });
+    for (const fn of listeners) fn();
+    if (id === clientId) {
+      for (const waiter of waiters) waiter.resolve();
+      waiters.clear();
+    }
+  }
+  const term = [1, clientId];
+  const announce2 = () => bus.post({ v: 1, scope: "leader", type: "heartbeat", term, clientId, kind: bus.kind });
+  const unsubscribe = bus.subscribe((wire) => {
+    if (wire.scope !== "leader") return;
+    if (wire.type === "hello") {
+      if (leaderId === clientId) announce2();
+      return;
+    }
+    if (wire.type === "resign") {
+      if (wire.clientId === leaderId) setLeader(null);
+      return;
+    }
+    setLeader(wire.clientId);
+  });
+  function joinQueue() {
+    if (closed || !eligible || releaseHeld || pending) return;
+    const controller = new AbortController();
+    pending = controller;
+    const held = new Promise((resolve) => {
+      releaseHeld = resolve;
+    });
+    void locks.request(name, { signal: controller.signal }, async () => {
+      pending = null;
+      if (closed || !eligible) return;
+      setLeader(clientId);
+      announce2();
+      await held;
+    }).catch(() => {
+    });
+  }
+  function letGo() {
+    const release = releaseHeld;
+    releaseHeld = null;
+    release?.();
+  }
+  function resign() {
+    if (leaderId !== clientId) return;
+    letGo();
+    setLeader(null);
+    bus.post({ v: 1, scope: "leader", type: "resign", term, clientId, kind: bus.kind });
+    joinQueue();
+  }
+  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 });
+  joinQueue();
+  return {
+    clientId,
+    strategy: "web-locks",
+    getSnapshot: () => snapshot,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    waitForLeadership() {
+      if (leaderId === clientId) return Promise.resolve();
+      if (closed) return Promise.reject(new Error("leader is closed"));
+      return new Promise((resolve, reject) => {
+        waiters.add({ resolve, reject });
+      });
+    },
+    resign,
+    setEligible(next) {
+      if (next === eligible) return;
+      eligible = next;
+      if (next) {
+        joinQueue();
+        return;
+      }
+      if (leaderId === clientId) resignWithoutRequeue();
+      pending?.abort();
+      pending = null;
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      if (leaderId === clientId) resignWithoutRequeue();
+      pending?.abort();
+      pending = null;
+      if (hasWindow) removeEventListener("pagehide", onPageHide);
+      for (const waiter of waiters) waiter.reject(new Error("leader is closed"));
+      waiters.clear();
+      unsubscribe();
+      listeners.clear();
+      bus.release();
+    }
+  };
+  function resignWithoutRequeue() {
+    letGo();
+    setLeader(null);
+    bus.post({ v: 1, scope: "leader", type: "resign", term, clientId, kind: bus.kind });
+  }
+}
+
+// src/leader.ts
+var NO_LEADER2 = Object.freeze({ leaderId: null, isLeader: false });
+function availableLocks(options) {
+  if (options.locks) return options.locks;
+  const locks = globalThis.navigator?.locks;
+  return typeof locks?.request === "function" ? locks : void 0;
+}
 function createLeader(name, options = {}) {
+  const strategy = options.strategy ?? "auto";
+  if (strategy !== "heartbeat") {
+    const locks = availableLocks(options);
+    if (locks) return createWebLocksLeader(name, options, locks);
+    if (strategy === "web-locks") {
+      throw new Error(
+        'strategy: "web-locks" was requested but navigator.locks is unavailable. Web Locks needs a secure context (https, or localhost) \u2014 use "auto" to fall back to the heartbeat election.'
+      );
+    }
+  }
+  return createHeartbeatLeader(name, options);
+}
+function createHeartbeatLeader(name, options) {
   const heartbeatMs = options.heartbeatMs ?? 1e3;
   const leaseMs = options.leaseMs ?? 3e3;
   const busOptions = {
@@ -624,16 +924,21 @@ function createLeader(name, options = {}) {
   let eligible = options.eligible ?? true;
   let leaderId = null;
   let term = [0, clientId];
-  let snapshot = NO_LEADER;
+  let snapshot = NO_LEADER2;
   let beat;
   let lease;
   let closed = false;
   const listeners = /* @__PURE__ */ new Set();
+  const waiters = /* @__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();
+    if (id === clientId) {
+      for (const waiter of waiters) waiter.resolve();
+      waiters.clear();
+    }
   }
   function armLease(delay) {
     clearTimeout(lease);
@@ -671,6 +976,7 @@ function createLeader(name, options = {}) {
       armLease(0);
       return;
     }
+    if (!isVersion(wire.term)) return;
     if (newer(wire.term, term)) {
       term = wire.term;
       stepDown(wire.clientId);
@@ -706,11 +1012,19 @@ function createLeader(name, options = {}) {
   armLease(heartbeatMs);
   return {
     clientId,
+    strategy: "heartbeat",
     getSnapshot: () => snapshot,
     subscribe(fn) {
       listeners.add(fn);
       return () => listeners.delete(fn);
     },
+    waitForLeadership() {
+      if (leaderId === clientId) return Promise.resolve();
+      if (closed) return Promise.reject(new Error("leader is closed"));
+      return new Promise((resolve, reject) => {
+        waiters.add({ resolve, reject });
+      });
+    },
     resign,
     setEligible(next) {
       if (next === eligible) return;
@@ -725,6 +1039,8 @@ function createLeader(name, options = {}) {
       if (closed) return;
       closed = true;
       resign();
+      for (const waiter of waiters) waiter.reject(new Error("leader is closed"));
+      waiters.clear();
       clearInterval(beat);
       clearTimeout(lease);
       if (hasWindow) {
@@ -1035,6 +1351,7 @@ function connectToOpener(options) {
   DEFAULT_NAME,
   HandshakeTimeoutError,
   NoopTransport,
+  StorageTransport,
   WindowClosedError,
   connectToOpener,
   createChannel,
@@ -1044,7 +1361,9 @@ function connectToOpener(options) {
   defaultTransport,
   enableDebug,
   getBusNames,
+  getTransportKind,
   isBroadcastChannelAvailable,
+  isStorageEventAvailable,
   localStorageAdapter,
   newer,
   observeBus,