use-everywhere 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,7 @@
 # use-everywhere
 
-React hooks for state and messages that exist in every tab, window, and worker.
+React hooks for state and messages that exist in every tab, window, and
+worker — plus a secure channel to windows on other origins.
 
 ```bash
 npm i use-everywhere
@@ -8,72 +9,148 @@ npm i use-everywhere
 
 Two transports behind one library:
 
-- **BroadcastChannel** (same-origin): shared state with last-writer-wins version
-  clocks and a late-joiner handshake, typed pub/sub events, and peer presence.
+- **BroadcastChannel** (same-origin): shared state with last-writer-wins
+  version clocks and a late-joiner handshake, typed pub/sub events, and peer
+  presence.
 - **window.opener / postMessage** (cross-origin): a secure 1:1 channel to a
   window you opened — e.g. a payment page on another domain that must report
-  back to the checkout that opened it. Every message is validated by origin,
-  envelope brand, a per-connection nonce, and the source window.
+  back to the checkout that opened it.
 
-## Usage
+## Shared state: `useSharedState`
+
+`useState`, but the value exists in every tab on your origin. Late-joining
+tabs hydrate to the current value; concurrent writes converge to one winner.
+
+```tsx
+import { useSharedState } from 'use-everywhere';
+
+function Counter() {
+  const [count, setCount] = useSharedState('count', 0);
+  return <button onClick={() => setCount((c) => c + 1)}>{count}</button>;
+}
+```
+
+The third argument delimits how far a value travels:
 
 ```tsx
-import {
-  useSharedState,
-  useChannel,
-  useMessage,
-  usePeers,
-  useOpenedWindow,
-  openWindow,
-} from 'use-everywhere';
-
-// useState, but the value exists in every tab/window/worker on this origin.
-const [count, setCount] = useSharedState('count', 0);
-
-// Typed fire-and-forget events between tabs.
-const channel = useChannel<{ 'cart-updated': { items: number } }>('shop');
-useMessage(channel, 'cart-updated', ({ items }) => refresh(items));
-channel.post('cart-updated', { items: 3 });
-
-// Who else is here?
-const peers = usePeers();
-
-// Open a window on ANOTHER origin and await its result.
-const pay = useOpenedWindow(() =>
-  openWindow<ToPayment, FromPayment, Receipt>('https://pay.example.com/checkout', {
-    peerOrigin: 'https://pay.example.com',
-  }),
-);
-// pay.open() from a click handler; pay.status: idle → opening → connected → done
-// pay.result is the child's finish() value; closing early yields 'closed-early'.
+useSharedState('draft', '', { scope: 'everywhere' }); // tabs + windows + workers (default)
+useSharedState('draft', '', { scope: 'tabs' }); // ignore writes from workers
+useSharedState('draft', '', { scope: 'tab' }); // this tab only
 ```
 
-On the opened (child) page:
+## Events: `defineChannel`
+
+Typed fire-and-forget messages for things that _happen_ (state is for things
+that _are_). Not echoed to the sender; no history for late joiners. Bind the
+channel's name and message map once at module level; every component gets
+fully typed hooks with nothing to repeat:
+
+```tsx
+import { defineChannel } from 'use-everywhere';
+import { useState } from 'react';
+
+type ShopEvents = { 'cart-updated': { items: number } };
+const shop = defineChannel<ShopEvents>('shop');
+
+function CartBadge() {
+  const [items, setItems] = useState(0);
+  const send = shop.useSend();
+
+  // Fires when any OTHER tab posts 'cart-updated'.
+  shop.useMessage('cart-updated', (payload) => setItems(payload.items));
+
+  const addToCart = () => {
+    setItems(items + 1); // this tab
+    send('cart-updated', { items: items + 1 }); // every other tab
+  };
+
+  return <button onClick={addToCart}>Cart ({items})</button>;
+}
+```
 
-```ts
+The standalone hooks — `useChannel(name)`, `useMessage(channel, type,
+handler)`, `useSend(channel)` — are the same machinery without the
+module-level binding, for one-off use.
+
+## Presence: `usePeers`
+
+```tsx
+import { usePeers } from 'use-everywhere';
+
+function DuplicateTabWarning() {
+  const peers = usePeers();
+  if (peers.length === 0) return null;
+  return <p>⚠ This page is open in {peers.length} other tab(s).</p>;
+}
+```
+
+## Cross-origin windows: `useOpenedWindow`
+
+Open a window on another domain, exchange typed messages, and await its
+result — the whole lifecycle folded into render state.
+
+```tsx
+import { openWindow, useOpenedWindow } from 'use-everywhere';
+
+type ToPayment = { order: { orderId: string; amount: string } };
+type FromPayment = { progress: { step: string } };
+type Receipt = { receiptId: string; last4: string };
+
+function PayButton() {
+  const pay = useOpenedWindow<ToPayment, FromPayment, Receipt>(() =>
+    openWindow('https://pay.example.com/checkout', {
+      peerOrigin: 'https://pay.example.com', // required — '*' throws
+    }),
+  );
+
+  if (pay.status === 'done') return <p>Paid — receipt {pay.result!.receiptId}</p>;
+  if (pay.status === 'closed-early') return <p>Payment window was closed.</p>;
+
+  return (
+    <button onClick={pay.open} disabled={pay.status !== 'idle'}>
+      {pay.status === 'idle' ? 'Pay in secure window' : 'Waiting for payment…'}
+    </button>
+  );
+}
+```
+
+On the opened page (the other domain), use the core API:
+
+```tsx
 import { connectToOpener } from 'use-everywhere';
 
 const conn = connectToOpener<ToPayment, FromPayment, Receipt>({
   peerOrigin: 'https://shop.example.com',
 });
-conn.on('order', (order) => render(order));
-conn.finish({ receiptId: 'r-123', last4: '4242' }); // resolves the opener's result
+conn.on('order', (order) => setOrder(order)); // e.g. a useState setter
+conn.finish({ receiptId: 'r-123', last4: '4242' }); // resolves the opener's pay.result
 ```
 
+Messages sent before the (possibly slow-loading) child connects are queued,
+never dropped, and every received message is validated by origin, envelope,
+per-connection nonce, and source window.
+
 ## Design notes
 
 - **Shared state never crosses origins.** Two origins are two trust domains;
   the cross-origin channel is explicit, per-message, and typed.
 - **No Provider.** A BroadcastChannel is already global to the origin —
   identity is the channel name, so hooks share module-level singletons.
-- Values must survive structured clone (no functions, DOM nodes, etc.).
+  Imperative access to the same stores: `getSharedStore(name)`.
+- SSR-safe: hooks render initial values on the server via
+  `getServerSnapshot`; no `BroadcastChannel` needed there.
+- Values must survive structured clone (no functions, DOM nodes); state lives
+  as long as at least one context holds it — nothing is persisted.
+- Testing is first-class: inject a `MemoryHub` transport to simulate many tabs
+  in one test. See the [testing guide](https://rxova.github.io/use-everywhere/guides/testing).
 
 This package re-exports the full framework-agnostic surface of
 [`@use-everywhere/core`](https://www.npmjs.com/package/@use-everywhere/core),
 so you never need to install core directly.
 
-Full docs, demo app (including a real cross-origin payment flow), and source:
-[github.com/rxova/use-everywhere](https://github.com/rxova/use-everywhere)
+📖 **[Documentation](https://rxova.github.io/use-everywhere/)** — mental
+model, how sync works, security model, recipes, and generated API reference.
+Source and demo app: [github.com/rxova/use-everywhere](https://github.com/rxova/use-everywhere)
 
 ## License
 

package/dist/index.d.ts

@@ -45,6 +45,27 @@ declare function useMessage<M extends MessageMap, K extends keyof M & string>(ch
 /** 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>;
+
 /** The other tabs/windows/workers currently alive on this origin. */
 declare function usePeers(options?: {
     name?: string;
@@ -74,4 +95,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, DEFAULT_NAME, type OpenedWindowStatus, type ShareScope, type UseOpenedWindow, type UseSharedStateOptions, getSharedStore, useChannel, useClientId, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };
+export { type AnyStore, type ChannelHooks, DEFAULT_NAME, type OpenedWindowStatus, type ShareScope, type UseOpenedWindow, type UseSharedStateOptions, defineChannel, getSharedStore, useChannel, useClientId, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };

package/dist/index.js

@@ -81,6 +81,17 @@ 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/use-peers.ts
 import { useCallback as useCallback2, useSyncExternalStore as useSyncExternalStore2 } from "react";
 var NO_PEERS = Object.freeze([]);
@@ -153,6 +164,7 @@ function useOpenedWindow(factory) {
 export * from "@use-everywhere/core";
 export {
   DEFAULT_NAME,
+  defineChannel,
   getSharedStore,
   useChannel,
   useClientId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-everywhere",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "React hooks for state and messages shared across tabs, windows, and workers",
   "license": "MIT",
   "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
@@ -37,13 +37,46 @@
   "files": [
     "dist"
   ],
+  "size-limit": [
+    {
+      "name": "everything (import *)",
+      "path": "dist/index.js",
+      "import": "*",
+      "limit": "4.2 kB"
+    },
+    {
+      "name": "useSharedState",
+      "path": "dist/index.js",
+      "import": "{ useSharedState }",
+      "limit": "1.5 kB"
+    },
+    {
+      "name": "useChannel + useMessage + useSend",
+      "path": "dist/index.js",
+      "import": "{ useChannel, useMessage, useSend }",
+      "limit": "1 kB"
+    },
+    {
+      "name": "usePeers + useClientId",
+      "path": "dist/index.js",
+      "import": "{ usePeers, useClientId }",
+      "limit": "1.1 kB"
+    },
+    {
+      "name": "useOpenedWindow + openWindow",
+      "path": "dist/index.js",
+      "import": "{ useOpenedWindow, openWindow }",
+      "limit": "1.4 kB"
+    }
+  ],
   "dependencies": {
-    "@use-everywhere/core": "0.1.0"
+    "@use-everywhere/core": "0.2.0"
   },
   "peerDependencies": {
     "react": ">=18"
   },
   "devDependencies": {
+    "@size-limit/preset-small-lib": "^12.1.0",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.2.3",
@@ -51,6 +84,7 @@
     "happy-dom": "^20.10.6",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
+    "size-limit": "^12.1.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^4.1.10"
@@ -58,6 +92,7 @@
   "scripts": {
     "build": "tsup",
     "test": "vitest run --coverage",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "size": "size-limit"
   }
 }