use-everywhere 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -21,44 +21,57 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  BroadcastChannelTransport: () => import_core3.BroadcastChannelTransport,
-  CID_PARAM: () => import_core3.CID_PARAM,
+  BroadcastChannelTransport: () => import_core4.BroadcastChannelTransport,
+  CID_PARAM: () => import_core4.CID_PARAM,
   DEFAULT_NAME: () => import_core.DEFAULT_NAME,
-  HandshakeTimeoutError: () => import_core3.HandshakeTimeoutError,
-  NoopTransport: () => import_core3.NoopTransport,
-  StorageTransport: () => import_core3.StorageTransport,
-  WindowClosedError: () => import_core3.WindowClosedError,
-  connectToOpener: () => import_core3.connectToOpener,
-  createChannel: () => import_core3.createChannel,
-  createLeader: () => import_core3.createLeader,
-  createPresence: () => import_core3.createPresence,
-  createSharedStore: () => import_core3.createSharedStore,
-  defaultTransport: () => import_core3.defaultTransport,
+  HandshakeTimeoutError: () => import_core4.HandshakeTimeoutError,
+  NoopTransport: () => import_core4.NoopTransport,
+  StorageTransport: () => import_core4.StorageTransport,
+  WIRE_VERSION: () => import_core4.WIRE_VERSION,
+  WindowClosedError: () => import_core4.WindowClosedError,
+  connectToOpener: () => import_core4.connectToOpener,
+  createChannel: () => import_core4.createChannel,
+  createLeader: () => import_core4.createLeader,
+  createNamespace: () => createNamespace,
+  createPresence: () => import_core4.createPresence,
+  createSharedReducer: () => import_core4.createSharedReducer,
+  createSharedStore: () => import_core4.createSharedStore,
+  defaultTransport: () => import_core4.defaultTransport,
   defineChannel: () => defineChannel,
   defineStore: () => defineStore,
-  enableDebug: () => import_core3.enableDebug,
-  getBusNames: () => import_core3.getBusNames,
+  enableDebug: () => import_core4.enableDebug,
+  getBusNames: () => import_core4.getBusNames,
   getLeader: () => getLeader,
   getSharedStore: () => getSharedStore,
-  getTransportKind: () => import_core3.getTransportKind,
-  isBroadcastChannelAvailable: () => import_core3.isBroadcastChannelAvailable,
-  isStorageEventAvailable: () => import_core3.isStorageEventAvailable,
-  localStorageAdapter: () => import_core3.localStorageAdapter,
-  newer: () => import_core3.newer,
-  observeBus: () => import_core3.observeBus,
-  openWindow: () => import_core3.openWindow,
-  sessionStorageAdapter: () => import_core3.sessionStorageAdapter,
+  getTransportKind: () => import_core4.getTransportKind,
+  getWireSkew: () => import_core4.getWireSkew,
+  indexedDbAdapter: () => import_core4.indexedDbAdapter,
+  isBroadcastChannelAvailable: () => import_core4.isBroadcastChannelAvailable,
+  isStorageEventAvailable: () => import_core4.isStorageEventAvailable,
+  jsonSerializer: () => import_core4.jsonSerializer,
+  localStorageAdapter: () => import_core4.localStorageAdapter,
+  newer: () => import_core4.newer,
+  observeBus: () => import_core4.observeBus,
+  openWindow: () => import_core4.openWindow,
+  sessionStorageAdapter: () => import_core4.sessionStorageAdapter,
+  shallowEqual: () => shallowEqual,
+  useAnswer: () => useAnswer,
+  useAsk: () => useAsk,
   useChannel: () => useChannel,
   useClientId: () => useClientId,
+  useHydrated: () => useHydrated,
   useIsLeader: () => useIsLeader,
   useLeader: () => useLeader,
   useLeaderEffect: () => useLeaderEffect,
   useMessage: () => useMessage,
   useOpenedWindow: () => useOpenedWindow,
   usePeers: () => usePeers,
+  usePresenceMetadata: () => usePresenceMetadata,
   useSend: () => useSend,
+  useSharedReducer: () => useSharedReducer,
   useSharedState: () => useSharedState,
-  webStorageAdapter: () => import_core3.webStorageAdapter
+  useSharedStore: () => useSharedStore,
+  webStorageAdapter: () => import_core4.webStorageAdapter
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -72,10 +85,17 @@ try {
 } catch {
 }
 var warned = /* @__PURE__ */ new Set();
-function devWarn(message) {
-  if (!inDev || warned.has(message)) return;
-  warned.add(message);
-  console.warn(message);
+var DOCS = "https://rxova.org/packages/use-everywhere/errors";
+function diagnostic(code, message) {
+  return `[use-everywhere] ${code}: ${message}
+  \u2192 ${DOCS}/#${code.toLowerCase()}`;
+}
+function devWarn(code, message) {
+  if (!inDev) return;
+  const line = diagnostic(code, message);
+  if (warned.has(line)) return;
+  warned.add(line);
+  console.warn(line);
 }
 var seenInitials = /* @__PURE__ */ new Map();
 function warnOnInitialMismatch(storeName, key, initial) {
@@ -89,7 +109,8 @@ function warnOnInitialMismatch(storeName, key, initial) {
   const comparable = (v) => v === null || typeof v !== "object";
   if (comparable(first) && comparable(initial) && !Object.is(first, initial)) {
     devWarn(
-      `[use-everywhere] useSharedState('${key}') was called with different initial values (${String(first)} and ${String(initial)}). The first registration wins, so the second is ignored. Define the default once \u2014 defineStore, or a shared constant.`
+      "UE2001",
+      `useSharedState('${key}') was called with different initial values (${String(first)} and ${String(initial)}). The first registration wins, so the second is ignored. Define the default once \u2014 defineStore, or a shared constant.`
     );
   }
 }
@@ -107,6 +128,12 @@ var unsubscribe = () => noop;
 var INERT = Object.freeze({
   clientId: SERVER_CLIENT_ID,
   // store
+  //
+  // Resolved, unlike the leader's `waitForLeadership` below. A server render
+  // has nothing to restore and is documented to render defaults, so `await
+  // store.hydrated` must proceed — a never-settling promise would hang the
+  // render rather than describe it honestly.
+  hydrated: Promise.resolve(),
   state: EMPTY,
   getVersions: () => EMPTY,
   set: noop,
@@ -115,6 +142,8 @@ var INERT = Object.freeze({
   // store + leader share getSnapshot; presence has getPeers
   getSnapshot: () => EMPTY,
   getPeers: () => NO_PEERS,
+  // presence
+  setMetadata: noop,
   // leader
   resign: noop,
   setEligible: noop,
@@ -133,6 +162,12 @@ var createServerLeader = () => ({
   getSnapshot: () => NO_LEADER,
   waitForLeadership: NEVER
 });
+var createServerReducer = (initial) => ({
+  ...INERT,
+  getSnapshot: () => initial,
+  dispatch: noop,
+  pendingCount: () => 0
+});
 var createServerChannel = (name) => ({ ...INERT, name, post: noop, on: unsubscribe });
 
 // src/registry.ts
@@ -153,15 +188,18 @@ function getSharedStore(name = import_core.DEFAULT_NAME, scope = "everywhere") {
 function configSignature(options) {
   const persist = options?.persist;
   if (!persist) return "none";
-  return `persist:${persist.keys?.join(",") ?? "*"}:${persist.debounceMs ?? "default"}`;
+  return `persist:${persist.keys?.join(",") ?? "*"}:${persist.debounceMs ?? "default"}:v${persist.version ?? 0}`;
 }
 function configureStore(name, scope, options) {
   const key = `${scope} ${name}`;
   if (stores.has(key)) {
     if (configSignature(storeConfig.get(key)) === configSignature(options)) return;
-    devWarn(
-      `[use-everywhere] defineStore('${name}') ran after that store was already created, with different options. The live store keeps the configuration it was built with. Move defineStore to module scope, before any component reads the store.`
-    );
+    if (process.env.NODE_ENV !== "production") {
+      devWarn(
+        "UE2002",
+        `defineStore('${name}') ran after that store was already created, with different options. The live store keeps the configuration it was built with. Move defineStore to module scope, before any component reads the store.`
+      );
+    }
     return;
   }
   storeConfig.set(key, options);
@@ -175,11 +213,12 @@ function getStore(name, scope = "everywhere") {
   }
   return store;
 }
-function getPresence(name) {
-  let presence = presences.get(name);
+function getPresence(name, includeSelf = false) {
+  const key = includeSelf ? `self ${name}` : name;
+  let presence = presences.get(key);
   if (!presence) {
-    presence = isServer() ? createServerPresence() : (0, import_core.createPresence)(name);
-    presences.set(name, presence);
+    presence = isServer() ? createServerPresence() : (0, import_core.createPresence)(name, { includeSelf });
+    presences.set(key, presence);
   }
   return presence;
 }
@@ -200,16 +239,45 @@ function warnOnLeaderOptionConflict(name, options) {
   for (const key of ["heartbeatMs", "leaseMs"]) {
     const requested = options[key];
     if (requested !== void 0 && requested !== first?.[key]) {
+      if (process.env.NODE_ENV !== "production") {
+        devWarn(
+          "UE2003",
+          `leader "${name}": ${key} ignored \u2014 the first useLeader/getLeader call fixes the election timings for this tab.`
+        );
+      }
+    }
+  }
+}
+var channelConfig = /* @__PURE__ */ new Map();
+function configureChannel(name, options) {
+  if (channels.has(name)) {
+    const before = Object.keys(channelConfig.get(name)?.schema ?? {}).sort();
+    const after = Object.keys(options.schema ?? {}).sort();
+    if (before.join() === after.join()) return;
+    if (process.env.NODE_ENV !== "production") {
       devWarn(
-        `[use-everywhere] leader "${name}": ${key} ignored \u2014 the first useLeader/getLeader call fixes the election timings for this tab.`
+        "UE2004",
+        `defineChannel('${name}') ran after that channel was already created, with different options. The live channel keeps the configuration it was built with. Move defineChannel to module scope, before any component sends or receives on it.`
       );
     }
+    return;
+  }
+  channelConfig.set(name, options);
+}
+var reducers = /* @__PURE__ */ new Map();
+function getReducer(name, key, reducer, initial) {
+  const id = `${name} ${key}`;
+  let existing = reducers.get(id);
+  if (!existing) {
+    existing = isServer() ? createServerReducer(initial) : (0, import_core.createSharedReducer)(name, reducer, initial, { key, leader: getLeader(name) });
+    reducers.set(id, existing);
   }
+  return existing;
 }
 function getChannel(name) {
   let channel = channels.get(name);
   if (!channel) {
-    channel = isServer() ? createServerChannel(name) : (0, import_core.createChannel)(name);
+    channel = isServer() ? createServerChannel(name) : (0, import_core.createChannel)(name, channelConfig.get(name));
     channels.set(name, channel);
   }
   return channel;
@@ -220,7 +288,9 @@ function useSharedState(key, initial, options) {
   const storeName = options?.store ?? import_core.DEFAULT_NAME;
   const store = getStore(storeName, options?.scope ?? "everywhere");
   store.registerKey(key, initial);
-  warnOnInitialMismatch(storeName, key, initial);
+  if (process.env.NODE_ENV !== "production") {
+    warnOnInitialMismatch(storeName, key, initial);
+  }
   const value = (0, import_react.useSyncExternalStore)(
     (0, import_react.useCallback)((onChange) => store.subscribeKey(key, onChange), [store, key]),
     () => store.getSnapshot()[key],
@@ -233,27 +303,98 @@ function useSharedState(key, initial, options) {
   return [value, setValue];
 }
 
-// src/use-message.ts
+// src/use-shared-reducer.ts
 var import_react2 = require("react");
+function useSharedReducer(reducer, initial, options) {
+  const engine = getReducer(
+    options?.name ?? import_core.DEFAULT_NAME,
+    options?.key ?? "default",
+    reducer,
+    initial
+  );
+  const value = (0, import_react2.useSyncExternalStore)(
+    (0, import_react2.useCallback)((onChange) => engine.subscribe(onChange), [engine]),
+    () => engine.getSnapshot(),
+    () => initial
+  );
+  const dispatch = (0, import_react2.useCallback)((action) => engine.dispatch(action), [engine]);
+  return [value, dispatch];
+}
+
+// src/use-shared-selector.ts
+var import_react3 = require("react");
+function useSharedStore(selector, options) {
+  const store = getStore(options?.store ?? import_core.DEFAULT_NAME, options?.scope ?? "everywhere");
+  const equal = options?.equal ?? Object.is;
+  const selectorRef = (0, import_react3.useRef)(selector);
+  selectorRef.current = selector;
+  const equalRef = (0, import_react3.useRef)(equal);
+  equalRef.current = equal;
+  const cache = (0, import_react3.useRef)(null);
+  const getSelection = (0, import_react3.useCallback)(() => {
+    const source = store.getSnapshot();
+    const select = selectorRef.current;
+    const previous = cache.current;
+    if (previous && previous.source === source && previous.select === select) return previous.value;
+    const next = select(source);
+    const value = previous && equalRef.current(previous.value, next) ? previous.value : next;
+    cache.current = { source, select, value };
+    return value;
+  }, [store]);
+  return (0, import_react3.useSyncExternalStore)(
+    (0, import_react3.useCallback)((onChange) => store.subscribe(onChange), [store]),
+    getSelection,
+    getSelection
+  );
+}
+function shallowEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
+  const left = a;
+  const right = b;
+  const keys = Object.keys(left);
+  if (keys.length !== Object.keys(right).length) return false;
+  return keys.every((key) => Object.is(left[key], right[key]));
+}
+
+// src/use-message.ts
+var import_react4 = require("react");
 function useChannel(name) {
   return getChannel(name);
 }
-function useMessage(channel, type, handler) {
-  const handlerRef = (0, import_react2.useRef)(handler);
-  (0, import_react2.useEffect)(() => {
+function useMessage(channel, type, handler, options) {
+  const handlerRef = (0, import_react4.useRef)(handler);
+  (0, import_react4.useEffect)(() => {
     handlerRef.current = handler;
   });
-  (0, import_react2.useEffect)(
-    () => channel.on(type, (payload, meta) => handlerRef.current(payload, meta)),
-    [channel, type]
-  );
+  const enabled = options?.enabled ?? true;
+  const once = options?.once ?? false;
+  (0, import_react4.useEffect)(() => {
+    if (!enabled) return;
+    return channel.on(type, (payload, meta) => handlerRef.current(payload, meta), { once });
+  }, [channel, type, enabled, once]);
+}
+function useAnswer(channel, type, responder, options) {
+  const responderRef = (0, import_react4.useRef)(responder);
+  (0, import_react4.useEffect)(() => {
+    responderRef.current = responder;
+  });
+  const enabled = options?.enabled ?? true;
+  (0, import_react4.useEffect)(() => {
+    if (!enabled) return;
+    return channel.answer(type, (payload, meta) => responderRef.current(payload, meta));
+  }, [channel, type, enabled]);
 }
 function useSend(channel) {
   return channel.post;
 }
+function useAsk(channel) {
+  return channel.ask;
+}
 
 // src/define-channel.ts
-function defineChannel(name) {
+function defineChannel(name, options) {
+  if (options) configureChannel(name, options);
   const useBoundSend = () => useSend(useChannel(name));
   const useBoundMessage = (type, handler) => useMessage(useChannel(name), type, handler);
   return {
@@ -271,7 +412,10 @@ function defineStore(name, options = {}) {
       persist: {
         adapter: options.persist,
         ...options.persistKeys ? { keys: options.persistKeys } : {},
-        ...options.persistDebounceMs === void 0 ? {} : { debounceMs: options.persistDebounceMs }
+        ...options.persistDebounceMs === void 0 ? {} : { debounceMs: options.persistDebounceMs },
+        ...options.persistVersion === void 0 ? {} : { version: options.persistVersion },
+        ...options.migrate ? { migrate: options.migrate } : {},
+        ...options.onRestoreError ? { onRestoreError: options.onRestoreError } : {}
       }
     });
   }
@@ -282,41 +426,64 @@ function defineStore(name, options = {}) {
 }
 
 // src/use-peers.ts
-var import_react3 = require("react");
+var import_react5 = require("react");
 var NO_PEERS2 = Object.freeze([]);
 function usePeers(options) {
-  const presence = getPresence(options?.name ?? import_core.DEFAULT_NAME);
-  return (0, import_react3.useSyncExternalStore)(
-    (0, import_react3.useCallback)((onChange) => presence.subscribe(onChange), [presence]),
+  const presence = getPresence(options?.name ?? import_core.DEFAULT_NAME, options?.includeSelf ?? false);
+  return (0, import_react5.useSyncExternalStore)(
+    (0, import_react5.useCallback)((onChange) => presence.subscribe(onChange), [presence]),
     () => presence.getPeers(),
     () => NO_PEERS2
   );
 }
 function useClientId(options) {
   const presence = getPresence(options?.name ?? import_core.DEFAULT_NAME);
-  return (0, import_react3.useSyncExternalStore)(
+  return (0, import_react5.useSyncExternalStore)(
     // The id never changes for the life of a presence engine, so there is
     // nothing to subscribe to — but uSES still needs the post-hydration read,
     // which it performs when it attaches this subscription.
-    (0, import_react3.useCallback)(() => () => {
+    (0, import_react5.useCallback)(() => () => {
     }, [presence]),
     () => presence.clientId,
     () => SERVER_CLIENT_ID
   );
 }
+function usePresenceMetadata(metadata, options) {
+  const presence = getPresence(options?.name ?? import_core.DEFAULT_NAME, options?.includeSelf ?? false);
+  (0, import_react5.useEffect)(() => {
+    presence.setMetadata(metadata);
+  }, [presence, metadata]);
+}
+
+// src/use-hydrated.ts
+var import_react6 = require("react");
+function useHydrated(options) {
+  const store = getStore(options?.store ?? import_core.DEFAULT_NAME, options?.scope ?? "everywhere");
+  const [ready, setReady] = (0, import_react6.useState)(false);
+  (0, import_react6.useEffect)(() => {
+    let cancelled = false;
+    void store.hydrated.then(() => {
+      if (!cancelled) setReady(true);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [store]);
+  return ready;
+}
 
 // src/use-leader.ts
-var import_react4 = require("react");
+var import_react7 = require("react");
 var NO_LEADER2 = Object.freeze({ leaderId: null, isLeader: false });
 function useLeader(options) {
   const leader = getLeader(options?.name ?? import_core.DEFAULT_NAME, options);
   const eligible = options?.eligible;
-  (0, import_react4.useEffect)(() => {
+  (0, import_react7.useEffect)(() => {
     if (eligible === void 0) return;
     leader.setEligible(eligible);
   }, [leader, eligible]);
-  return (0, import_react4.useSyncExternalStore)(
-    (0, import_react4.useCallback)((onChange) => leader.subscribe(onChange), [leader]),
+  return (0, import_react7.useSyncExternalStore)(
+    (0, import_react7.useCallback)((onChange) => leader.subscribe(onChange), [leader]),
     () => leader.getSnapshot(),
     () => NO_LEADER2
   );
@@ -326,32 +493,54 @@ function useIsLeader(options) {
 }
 function useLeaderEffect(effect, options) {
   const { isLeader } = useLeader(options);
-  const effectRef = (0, import_react4.useRef)(effect);
-  (0, import_react4.useEffect)(() => {
+  const effectRef = (0, import_react7.useRef)(effect);
+  (0, import_react7.useEffect)(() => {
     effectRef.current = effect;
   });
-  (0, import_react4.useEffect)(() => {
+  (0, import_react7.useEffect)(() => {
     if (!isLeader) return;
     return effectRef.current();
   }, [isLeader]);
 }
 
-// src/use-opened-window.ts
-var import_react5 = require("react");
+// src/namespace.ts
 var import_core2 = require("@use-everywhere/core");
+function createNamespace(namespace) {
+  const core = (0, import_core2.createNamespace)(namespace);
+  const { busName } = core;
+  return {
+    ...core,
+    defineStore: (name, options) => defineStore(busName(name), options),
+    defineChannel: (name, options) => defineChannel(busName(name), options),
+    getSharedStore: (name, scope) => getSharedStore(busName(name), scope),
+    useSharedState: (key, initial, options) => useSharedState(key, initial, { ...options, store: busName(options?.store) }),
+    useSharedStore: (selector, options) => useSharedStore(selector, { ...options, store: busName(options?.store) }),
+    usePeers: (options) => usePeers({ ...options, name: busName(options?.name) }),
+    usePresenceMetadata: (metadata, options) => usePresenceMetadata(metadata, { ...options, name: busName(options?.name) }),
+    useHydrated: (options) => useHydrated({ ...options, store: busName(options?.store) }),
+    useClientId: (options) => useClientId({ name: busName(options?.name) }),
+    useLeader: (options) => useLeader({ ...options, name: busName(options?.name) }),
+    useIsLeader: (options) => useIsLeader({ ...options, name: busName(options?.name) }),
+    useLeaderEffect: (effect, options) => useLeaderEffect(effect, { ...options, name: busName(options?.name) })
+  };
+}
+
+// src/use-opened-window.ts
+var import_react8 = require("react");
+var import_core3 = require("@use-everywhere/core");
 var IDLE = Object.freeze({
   status: "idle",
   result: void 0,
   error: void 0
 });
 function useOpenedWindow(factory) {
-  const [state, setState] = (0, import_react5.useState)(IDLE);
-  const current = (0, import_react5.useRef)(null);
-  const factoryRef = (0, import_react5.useRef)(factory);
-  (0, import_react5.useEffect)(() => {
+  const [state, setState] = (0, import_react8.useState)(IDLE);
+  const current = (0, import_react8.useRef)(null);
+  const factoryRef = (0, import_react8.useRef)(factory);
+  (0, import_react8.useEffect)(() => {
     factoryRef.current = factory;
   });
-  const open = (0, import_react5.useCallback)(() => {
+  const open = (0, import_react8.useCallback)(() => {
     current.current?.close();
     let opened;
     try {
@@ -381,20 +570,20 @@ function useOpenedWindow(factory) {
       (err) => {
         if (!fresh()) return;
         setState(
-          err instanceof import_core2.WindowClosedError ? { status: "closed-early", result: void 0, error: err } : { status: "error", result: void 0, error: err }
+          err instanceof import_core3.WindowClosedError ? { status: "closed-early", result: void 0, error: err } : { status: "error", result: void 0, error: err }
         );
       }
     );
   }, []);
-  const post = (0, import_react5.useCallback)((type, payload) => {
+  const post = (0, import_react8.useCallback)((type, payload) => {
     current.current?.post(type, payload);
   }, []);
-  const close = (0, import_react5.useCallback)(() => current.current?.close(), []);
+  const close = (0, import_react8.useCallback)(() => current.current?.close(), []);
   return { ...state, open, post, close };
 }
 
 // src/index.ts
-var import_core3 = require("@use-everywhere/core");
+var import_core4 = require("@use-everywhere/core");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BroadcastChannelTransport,
@@ -403,11 +592,14 @@ var import_core3 = require("@use-everywhere/core");
   HandshakeTimeoutError,
   NoopTransport,
   StorageTransport,
+  WIRE_VERSION,
   WindowClosedError,
   connectToOpener,
   createChannel,
   createLeader,
+  createNamespace,
   createPresence,
+  createSharedReducer,
   createSharedStore,
   defaultTransport,
   defineChannel,
@@ -417,22 +609,32 @@ var import_core3 = require("@use-everywhere/core");
   getLeader,
   getSharedStore,
   getTransportKind,
+  getWireSkew,
+  indexedDbAdapter,
   isBroadcastChannelAvailable,
   isStorageEventAvailable,
+  jsonSerializer,
   localStorageAdapter,
   newer,
   observeBus,
   openWindow,
   sessionStorageAdapter,
+  shallowEqual,
+  useAnswer,
+  useAsk,
   useChannel,
   useClientId,
+  useHydrated,
   useIsLeader,
   useLeader,
   useLeaderEffect,
   useMessage,
   useOpenedWindow,
   usePeers,
+  usePresenceMetadata,
   useSend,
+  useSharedReducer,
   useSharedState,
+  useSharedStore,
   webStorageAdapter
 });