use-everywhere 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -0,0 +1,287 @@
+'use client';
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  DEFAULT_NAME: () => import_core.DEFAULT_NAME,
+  defineChannel: () => defineChannel,
+  defineStore: () => defineStore,
+  getLeader: () => getLeader,
+  getSharedStore: () => getSharedStore,
+  useChannel: () => useChannel,
+  useClientId: () => useClientId,
+  useIsLeader: () => useIsLeader,
+  useLeader: () => useLeader,
+  useLeaderEffect: () => useLeaderEffect,
+  useMessage: () => useMessage,
+  useOpenedWindow: () => useOpenedWindow,
+  usePeers: () => usePeers,
+  useSend: () => useSend,
+  useSharedState: () => useSharedState
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/use-shared-state.ts
+var import_react = require("react");
+
+// src/registry.ts
+var import_core = require("@use-everywhere/core");
+var stores = /* @__PURE__ */ new Map();
+var presences = /* @__PURE__ */ new Map();
+var channels = /* @__PURE__ */ new Map();
+var leaders = /* @__PURE__ */ new Map();
+var storeConfig = /* @__PURE__ */ new Map();
+var scopeOptions = {
+  everywhere: {},
+  tabs: { accept: (meta) => meta.kind !== "worker" },
+  tab: { transport: () => new import_core.NoopTransport() }
+};
+function getSharedStore(name = import_core.DEFAULT_NAME, scope = "everywhere") {
+  return getStore(name, scope);
+}
+function configureStore(name, scope, options) {
+  const key = `${scope} ${name}`;
+  if (stores.has(key)) {
+    throw new Error(
+      `defineStore('${name}') ran after that store was already created. Move it to module scope \u2014 configuring a live store would silently hand you one without persistence.`
+    );
+  }
+  storeConfig.set(key, options);
+}
+function getStore(name, scope = "everywhere") {
+  const key = `${scope} ${name}`;
+  let store = stores.get(key);
+  if (!store) {
+    store = (0, import_core.createSharedStore)(name, {}, { ...scopeOptions[scope], ...storeConfig.get(key) });
+    stores.set(key, store);
+  }
+  return store;
+}
+function getPresence(name) {
+  let presence = presences.get(name);
+  if (!presence) {
+    presence = (0, import_core.createPresence)(name);
+    presences.set(name, presence);
+  }
+  return presence;
+}
+function getLeader(name, options) {
+  let leader = leaders.get(name);
+  if (!leader) {
+    leader = (0, import_core.createLeader)(name, options);
+    leaders.set(name, leader);
+  }
+  return leader;
+}
+function getChannel(name) {
+  let channel = channels.get(name);
+  if (!channel) {
+    channel = (0, import_core.createChannel)(name);
+    channels.set(name, channel);
+  }
+  return channel;
+}
+
+// src/use-shared-state.ts
+function useSharedState(key, initial, options) {
+  const store = getStore(options?.store ?? import_core.DEFAULT_NAME, options?.scope ?? "everywhere");
+  store.registerKey(key, initial);
+  const value = (0, import_react.useSyncExternalStore)(
+    (0, import_react.useCallback)((onChange) => store.subscribeKey(key, onChange), [store, key]),
+    () => store.getSnapshot()[key],
+    () => initial
+  );
+  const setValue = (0, import_react.useCallback)(
+    (next) => store.set(key, next),
+    [store, key]
+  );
+  return [value, setValue];
+}
+
+// src/use-message.ts
+var import_react2 = require("react");
+function useChannel(name) {
+  return getChannel(name);
+}
+function useMessage(channel, type, handler) {
+  const handlerRef = (0, import_react2.useRef)(handler);
+  (0, import_react2.useEffect)(() => {
+    handlerRef.current = handler;
+  });
+  (0, import_react2.useEffect)(
+    () => channel.on(type, (payload, meta) => handlerRef.current(payload, meta)),
+    [channel, type]
+  );
+}
+function useSend(channel) {
+  return channel.post;
+}
+
+// src/define-channel.ts
+function defineChannel(name) {
+  const useBoundSend = () => useSend(useChannel(name));
+  const useBoundMessage = (type, handler) => useMessage(useChannel(name), type, handler);
+  return {
+    get: () => getChannel(name),
+    useSend: useBoundSend,
+    useMessage: useBoundMessage
+  };
+}
+
+// src/define-store.ts
+function defineStore(name, options = {}) {
+  const scope = options.scope ?? "everywhere";
+  if (options.persist) {
+    configureStore(name, scope, {
+      persist: {
+        adapter: options.persist,
+        ...options.persistKeys ? { keys: options.persistKeys } : {},
+        ...options.persistDebounceMs === void 0 ? {} : { debounceMs: options.persistDebounceMs }
+      }
+    });
+  }
+  return {
+    get: () => getStore(name, scope),
+    useSharedState: (key, initial) => useSharedState(key, initial, { store: name, scope })
+  };
+}
+
+// src/use-peers.ts
+var import_react3 = require("react");
+var NO_PEERS = 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]),
+    () => presence.getPeers(),
+    () => NO_PEERS
+  );
+}
+function useClientId(options) {
+  return getPresence(options?.name ?? import_core.DEFAULT_NAME).clientId;
+}
+
+// src/use-leader.ts
+var import_react4 = require("react");
+var NO_LEADER = 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)(() => {
+    if (eligible === void 0) return;
+    leader.setEligible(eligible);
+  }, [leader, eligible]);
+  return (0, import_react4.useSyncExternalStore)(
+    (0, import_react4.useCallback)((onChange) => leader.subscribe(onChange), [leader]),
+    () => leader.getSnapshot(),
+    () => NO_LEADER
+  );
+}
+function useIsLeader(options) {
+  return useLeader(options).isLeader;
+}
+function useLeaderEffect(effect, options) {
+  const { isLeader } = useLeader(options);
+  const effectRef = (0, import_react4.useRef)(effect);
+  (0, import_react4.useEffect)(() => {
+    effectRef.current = effect;
+  });
+  (0, import_react4.useEffect)(() => {
+    if (!isLeader) return;
+    return effectRef.current();
+  }, [isLeader]);
+}
+
+// src/use-opened-window.ts
+var import_react5 = require("react");
+var import_core2 = require("@use-everywhere/core");
+function useOpenedWindow(factory) {
+  const [status, setStatus] = (0, import_react5.useState)("idle");
+  const [result, setResult] = (0, import_react5.useState)(void 0);
+  const [error, setError] = (0, import_react5.useState)(void 0);
+  const current = (0, import_react5.useRef)(null);
+  const factoryRef = (0, import_react5.useRef)(factory);
+  factoryRef.current = factory;
+  const open = (0, import_react5.useCallback)(() => {
+    current.current?.close();
+    let opened;
+    try {
+      opened = factoryRef.current();
+    } catch (err) {
+      setStatus("error");
+      setError(err);
+      return;
+    }
+    current.current = opened;
+    setStatus("opening");
+    setResult(void 0);
+    setError(void 0);
+    const fresh = () => current.current === opened;
+    opened.ready.then(
+      () => {
+        if (fresh()) setStatus((s) => s === "opening" ? "connected" : s);
+      },
+      () => {
+      }
+      // surfaced through result below
+    );
+    opened.result.then(
+      (value) => {
+        if (!fresh()) return;
+        setResult(value);
+        setStatus("done");
+      },
+      (err) => {
+        if (!fresh()) return;
+        setError(err);
+        setStatus(err instanceof import_core2.WindowClosedError ? "closed-early" : "error");
+      }
+    );
+  }, []);
+  const post = (0, import_react5.useCallback)((type, payload) => {
+    current.current?.post(type, payload);
+  }, []);
+  const close = (0, import_react5.useCallback)(() => current.current?.close(), []);
+  return { open, status, result, error, post, close };
+}
+
+// src/index.ts
+__reExport(src_exports, require("@use-everywhere/core"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_NAME,
+  defineChannel,
+  defineStore,
+  getLeader,
+  getSharedStore,
+  useChannel,
+  useClientId,
+  useIsLeader,
+  useLeader,
+  useLeaderEffect,
+  useMessage,
+  useOpenedWindow,
+  usePeers,
+  useSend,
+  useSharedState,
+  ...require("@use-everywhere/core")
+});

package/dist/index.d.cts

@@ -0,0 +1,152 @@
+import { SharedStore, LeaderOptions, Leader, MessageMap, Channel, MessageMeta, PersistAdapter, Peer, LeaderSnapshot, OpenedWindow } from '@use-everywhere/core';
+export * from '@use-everywhere/core';
+export { DEFAULT_NAME } from '@use-everywhere/core';
+
+/**
+ * How far a shared value travels:
+ * - 'everywhere' — every tab, window, and worker on this origin (default)
+ * - 'tabs'       — tabs and windows only; writes coming from workers are ignored
+ * - 'tab'        — this tab only (state is still shared between components)
+ */
+type ShareScope = 'everywhere' | 'tabs' | 'tab';
+interface UseSharedStateOptions {
+    /** Store name; keys live in a namespace per store. Default 'use-everywhere'. */
+    store?: string;
+    /** How much to share. Default 'everywhere'. */
+    scope?: ShareScope;
+}
+
+/**
+ * Like useState, but the value exists in every tab, window, and worker on
+ * this origin. Late-joining tabs hydrate to the current value; concurrent
+ * writes converge last-writer-wins. Pass options.scope to delimit how much
+ * is shared ('everywhere' | 'tabs' | 'tab').
+ */
+declare function useSharedState<T>(key: string, initial: T, options?: UseSharedStateOptions): [T, (next: T | ((prev: T) => T)) => void];
+
+/** Registry stores hold arbitrary keys — shape is decided by the hooks using them. */
+type AnyStore = SharedStore<Record<string, unknown>>;
+
+/** Imperative access to the store behind useSharedState (patch logs, non-React code). */
+declare function getSharedStore(name?: string, scope?: ShareScope): AnyStore;
+/**
+ * One Leader per name per tab. Eligibility is deliberately *not* part of the
+ * key: two Leaders on one name would share a bus and a clientId, and since a
+ * post never loops back locally, neither would ever see the other's claims.
+ * Timing options are first-wins, like every other engine here.
+ */
+declare function getLeader(name: string, options?: LeaderOptions): Leader;
+
+/** Get the page-wide typed channel for `name` (one instance per name). */
+declare function useChannel<M extends MessageMap>(name: string): Channel<M>;
+/**
+ * Subscribe to one message type. The handler is kept fresh without
+ * resubscribing, so it may close over render state.
+ */
+declare function useMessage<M extends MessageMap, K extends keyof M & string>(channel: Channel<M>, type: K, handler: (payload: M[K], meta: MessageMeta) => void): void;
+/** The channel's post function (stable identity per channel). */
+declare function useSend<M extends MessageMap>(channel: Channel<M>): Channel<M>['post'];
+
+/** A channel bound to a name and message map: typed hooks with no per-call generics. */
+interface ChannelHooks<M extends MessageMap> {
+    /** The underlying channel instance (the same one the hooks use) — for non-React code. */
+    get: () => Channel<M>;
+    /** The channel's post function (stable identity). */
+    useSend: () => Channel<M>['post'];
+    /**
+     * Subscribe to one message type. Same contract as the standalone
+     * `useMessage`: the handler is kept fresh without resubscribing.
+     */
+    useMessage: <K extends keyof M & string>(type: K, handler: (payload: M[K], meta: MessageMeta) => void) => void;
+}
+
+/**
+ * Bind a channel name and message map once, at module level, and get fully
+ * typed hooks back. Sugar over useChannel/useMessage/useSend — the same
+ * page-wide channel singleton is shared, so mixing bound and standalone
+ * hooks for one name is safe.
+ */
+declare function defineChannel<M extends MessageMap>(name: string): ChannelHooks<M>;
+
+interface DefineStoreOptions {
+    /** Restore this store from disk on first use, and write it back as it changes. */
+    persist?: PersistAdapter;
+    /** Persist only these keys. Default: every key that has been written. */
+    persistKeys?: string[];
+    /** Coalesce disk writes for this long. Default 100. */
+    persistDebounceMs?: number;
+    /** How far this store is shared. Default 'everywhere'. */
+    scope?: ShareScope;
+}
+/** A store bound to a name and a shape: typed hooks with no per-call generics. */
+interface StoreHooks<S extends Record<string, unknown>> {
+    /** The underlying store instance (the same one the hooks use) — for non-React code. */
+    get: () => AnyStore;
+    useSharedState: <K extends keyof S & string>(key: K, initial: S[K]) => [S[K], (next: S[K] | ((prev: S[K]) => S[K])) => void];
+}
+
+/**
+ * Bind a store name — and optionally persistence — once, at module level.
+ *
+ * Like defineChannel, this does not construct anything: it registers the
+ * options the registry will use when the store is first needed, so importing
+ * the module has no side effect. The store stays a singleton per name, so
+ * `defineStore('settings', { persist })` and a bare
+ * `useSharedState('theme', 'dark', { store: 'settings' })` elsewhere resolve to
+ * the same store, and both get persistence.
+ *
+ * Must run before that store exists. Module evaluation always precedes render,
+ * so intended usage is automatic; if it does run late it throws rather than
+ * quietly handing back a store with no persistence.
+ */
+declare function defineStore<S extends Record<string, unknown> = Record<string, unknown>>(name: string, options?: DefineStoreOptions): StoreHooks<S>;
+
+/** The other tabs/windows/workers currently alive on this origin. */
+declare function usePeers(options?: {
+    name?: string;
+}): readonly Peer[];
+/** This client's own id on the presence bus (matches patch origin ids). */
+declare function useClientId(options?: {
+    name?: string;
+}): string;
+
+interface UseLeaderOptions extends LeaderOptions {
+    /** Which bus to elect on. Defaults to the shared default name. */
+    name?: string;
+}
+
+/**
+ * Who currently holds the seat on this bus, and whether it is us. Exactly one
+ * tab leads; opening another does not steal it, and closing the leader hands it
+ * over at once.
+ */
+declare function useLeader(options?: UseLeaderOptions): LeaderSnapshot;
+/** Is this tab the leader? */
+declare function useIsLeader(options?: UseLeaderOptions): boolean;
+/**
+ * Run an effect only in the tab that holds the seat, and tear it down when the
+ * seat moves. The one place to put "exactly one tab owns the socket".
+ */
+declare function useLeaderEffect(effect: () => void | (() => void), options?: UseLeaderOptions): void;
+
+type OpenedWindowStatus = 'idle' | 'opening' | 'connected' | 'done' | 'closed-early' | 'error';
+interface UseOpenedWindow<Out extends MessageMap, In extends MessageMap, R> {
+    /** Call from a click handler (popup blockers require a user gesture). */
+    open: () => void;
+    status: OpenedWindowStatus;
+    /** The child's finish() value, once status is 'done'. */
+    result: R | undefined;
+    error: unknown;
+    /** Post to the child; no-op while nothing is open. */
+    post: OpenedWindow<Out, In, R>['post'];
+    close: () => void;
+}
+
+/**
+ * Drive an openWindow() flow from a component: the factory is called on
+ * open(), and the child window's lifecycle is folded into render state.
+ * Reopening replaces the previous window; a stale window's outcome is ignored.
+ */
+declare function useOpenedWindow<Out extends MessageMap, In extends MessageMap, R = unknown>(factory: () => OpenedWindow<Out, In, R>): UseOpenedWindow<Out, In, R>;
+
+export { type AnyStore, type ChannelHooks, type DefineStoreOptions, type OpenedWindowStatus, type ShareScope, type StoreHooks, type UseLeaderOptions, type UseOpenedWindow, type UseSharedStateOptions, defineChannel, defineStore, getLeader, getSharedStore, useChannel, useClientId, useIsLeader, useLeader, useLeaderEffect, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { SharedStore, MessageMap, Channel, MessageMeta, Peer, OpenedWindow } from '@use-everywhere/core';
+import { SharedStore, LeaderOptions, Leader, MessageMap, Channel, MessageMeta, PersistAdapter, Peer, LeaderSnapshot, OpenedWindow } from '@use-everywhere/core';
 export * from '@use-everywhere/core';
+export { DEFAULT_NAME } from '@use-everywhere/core';
 
 /**
  * How far a shared value travels:
@@ -26,14 +27,15 @@ declare function useSharedState<T>(key: string, initial: T, options?: UseSharedS
 /** Registry stores hold arbitrary keys — shape is decided by the hooks using them. */
 type AnyStore = SharedStore<Record<string, unknown>>;
 
-/**
- * A BroadcastChannel is already global to the origin — identity is the name
- * string, not the React tree — so hooks share module-level singletons per
- * name instead of requiring a Provider. Instances live for the page lifetime.
- */
-declare const DEFAULT_NAME = "use-everywhere";
 /** Imperative access to the store behind useSharedState (patch logs, non-React code). */
 declare function getSharedStore(name?: string, scope?: ShareScope): AnyStore;
+/**
+ * One Leader per name per tab. Eligibility is deliberately *not* part of the
+ * key: two Leaders on one name would share a bus and a clientId, and since a
+ * post never loops back locally, neither would ever see the other's claims.
+ * Timing options are first-wins, like every other engine here.
+ */
+declare function getLeader(name: string, options?: LeaderOptions): Leader;
 
 /** Get the page-wide typed channel for `name` (one instance per name). */
 declare function useChannel<M extends MessageMap>(name: string): Channel<M>;
@@ -66,6 +68,39 @@ interface ChannelHooks<M extends MessageMap> {
  */
 declare function defineChannel<M extends MessageMap>(name: string): ChannelHooks<M>;
 
+interface DefineStoreOptions {
+    /** Restore this store from disk on first use, and write it back as it changes. */
+    persist?: PersistAdapter;
+    /** Persist only these keys. Default: every key that has been written. */
+    persistKeys?: string[];
+    /** Coalesce disk writes for this long. Default 100. */
+    persistDebounceMs?: number;
+    /** How far this store is shared. Default 'everywhere'. */
+    scope?: ShareScope;
+}
+/** A store bound to a name and a shape: typed hooks with no per-call generics. */
+interface StoreHooks<S extends Record<string, unknown>> {
+    /** The underlying store instance (the same one the hooks use) — for non-React code. */
+    get: () => AnyStore;
+    useSharedState: <K extends keyof S & string>(key: K, initial: S[K]) => [S[K], (next: S[K] | ((prev: S[K]) => S[K])) => void];
+}
+
+/**
+ * Bind a store name — and optionally persistence — once, at module level.
+ *
+ * Like defineChannel, this does not construct anything: it registers the
+ * options the registry will use when the store is first needed, so importing
+ * the module has no side effect. The store stays a singleton per name, so
+ * `defineStore('settings', { persist })` and a bare
+ * `useSharedState('theme', 'dark', { store: 'settings' })` elsewhere resolve to
+ * the same store, and both get persistence.
+ *
+ * Must run before that store exists. Module evaluation always precedes render,
+ * so intended usage is automatic; if it does run late it throws rather than
+ * quietly handing back a store with no persistence.
+ */
+declare function defineStore<S extends Record<string, unknown> = Record<string, unknown>>(name: string, options?: DefineStoreOptions): StoreHooks<S>;
+
 /** The other tabs/windows/workers currently alive on this origin. */
 declare function usePeers(options?: {
     name?: string;
@@ -75,6 +110,25 @@ declare function useClientId(options?: {
     name?: string;
 }): string;
 
+interface UseLeaderOptions extends LeaderOptions {
+    /** Which bus to elect on. Defaults to the shared default name. */
+    name?: string;
+}
+
+/**
+ * Who currently holds the seat on this bus, and whether it is us. Exactly one
+ * tab leads; opening another does not steal it, and closing the leader hands it
+ * over at once.
+ */
+declare function useLeader(options?: UseLeaderOptions): LeaderSnapshot;
+/** Is this tab the leader? */
+declare function useIsLeader(options?: UseLeaderOptions): boolean;
+/**
+ * Run an effect only in the tab that holds the seat, and tear it down when the
+ * seat moves. The one place to put "exactly one tab owns the socket".
+ */
+declare function useLeaderEffect(effect: () => void | (() => void), options?: UseLeaderOptions): void;
+
 type OpenedWindowStatus = 'idle' | 'opening' | 'connected' | 'done' | 'closed-early' | 'error';
 interface UseOpenedWindow<Out extends MessageMap, In extends MessageMap, R> {
     /** Call from a click handler (popup blockers require a user gesture). */
@@ -95,4 +149,4 @@ interface UseOpenedWindow<Out extends MessageMap, In extends MessageMap, R> {
  */
 declare function useOpenedWindow<Out extends MessageMap, In extends MessageMap, R = unknown>(factory: () => OpenedWindow<Out, In, R>): UseOpenedWindow<Out, In, R>;
 
-export { type AnyStore, type ChannelHooks, DEFAULT_NAME, type OpenedWindowStatus, type ShareScope, type UseOpenedWindow, type UseSharedStateOptions, defineChannel, getSharedStore, useChannel, useClientId, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };
+export { type AnyStore, type ChannelHooks, type DefineStoreOptions, type OpenedWindowStatus, type ShareScope, type StoreHooks, type UseLeaderOptions, type UseOpenedWindow, type UseSharedStateOptions, defineChannel, defineStore, getLeader, getSharedStore, useChannel, useClientId, useIsLeader, useLeader, useLeaderEffect, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };