@use-everywhere/core 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,7 @@
 # @use-everywhere/core
 
 Framework-agnostic engine for cross-tab shared state, typed events, peer
-presence, and secure cross-origin window channels.
+presence, and secure cross-origin window channels. Zero dependencies.
 
 ```bash
 npm i @use-everywhere/core
@@ -12,22 +12,158 @@ npm i @use-everywhere/core
 
 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. Every message is validated by origin, envelope brand, a
   per-connection nonce, and the source window.
 
+## Shared state
+
+One object that exists in every tab, window, and worker on your origin.
+Writes broadcast patches; replicas converge last-writer-wins; tabs opened
+later hydrate to the current value via a hello/snapshot handshake.
+
+```ts
+import { createSharedStore } from '@use-everywhere/core';
+
+const store = createSharedStore('checkout', { step: 0, payment: 'idle' });
+
+// Imperative writes through the proxy — they sync everywhere:
+store.state.step++;
+
+// Or explicit (supports functional updates):
+store.set('payment', 'processing');
+store.set('step', (prev) => prev + 1);
+
+// React to changes from any tab, worker, or this one:
+store.subscribe((key, value, meta) => {
+  console.log(`${String(key)} = ${value}`, meta.self ? '(me)' : `(peer ${meta.clientId})`);
+});
+
+// Immutable snapshot, replaced per change (useSyncExternalStore-compatible):
+store.getSnapshot(); // { step: 1, payment: 'processing' }
+```
+
+Options let you delimit what a store accepts — e.g. ignore writes coming from
+workers:
+
+```ts
+createSharedStore('ui', { theme: 'light' }, { accept: (meta) => meta.kind !== 'worker' });
+```
+
+## Typed events
+
+Fire-and-forget messages between contexts. No history: a tab that joins later
+never sees old events (use shared state for anything a late joiner must know).
+
+```ts
+import { createChannel } from '@use-everywhere/core';
+
+type AuthEvents = { 'logged-out': undefined; 'session-renewed': { expiresAt: number } };
+
+const channel = createChannel<AuthEvents>('auth');
+
+const off = channel.on('logged-out', (_payload, meta) => {
+  console.log(`tab ${meta.clientId} logged out`);
+  window.location.assign('/login');
+});
+
+channel.post('logged-out', undefined); // delivered to every OTHER context
+```
+
+## Presence
+
+Who else is on this origin right now? Heartbeat-based, with instant goodbyes
+on clean tab closes and pruning (~5s) for crashed ones.
+
+```ts
+import { createPresence } from '@use-everywhere/core';
+
+const presence = createPresence('app');
+presence.subscribe(() => {
+  console.log(presence.getPeers()); // [{ id: 'p8m1q4', kind: 'tab', lastSeen: … }]
+});
+```
+
+## Cross-origin window channel
+
+The case BroadcastChannel cannot do: a checkout on domain A opens a payment
+page on domain B, and the payment page must report back.
+
+```ts
+// On the opener (https://shop.example.com):
+import { openWindow } from '@use-everywhere/core';
+
+type ToPayment = { order: { orderId: string; amount: string } };
+type FromPayment = { progress: { step: string } };
+type Receipt = { receiptId: string; last4: string };
+
+const opened = openWindow<ToPayment, FromPayment, Receipt>(
+  'https://pay.example.com/checkout',
+  { peerOrigin: 'https://pay.example.com' }, // required — '*' throws
+);
+
+opened.post('order', { orderId: '48-291', amount: '$69.03' }); // queued until the child is ready
+opened.on('progress', ({ step }) => console.log('payment step:', step));
+
+const receipt = await opened.result; // the child's finish() value
+// rejects with WindowClosedError if the user closes the window first
+```
+
+```ts
+// On the opened page (https://pay.example.com):
+import { connectToOpener } from '@use-everywhere/core';
+
+const conn = connectToOpener<ToPayment, FromPayment, Receipt>({
+  peerOrigin: 'https://shop.example.com',
+});
+
+conn.on('order', (order) => showOrderSummary(order)); // your UI code
+conn.finish({ receiptId: 'r-123', last4: '4242' }); // resolves the opener's `result`
+conn.close();
+```
+
+The handshake retries until the (possibly slow-loading) child connects, and
+both sides queue outgoing messages until then — nothing is dropped. Every
+received message must pass four gates: exact origin, library envelope, a
+per-connection nonce carried in the child URL, and (on the opener) the source
+window itself.
+
+## Testing
+
+Every engine accepts an injected transport, so "many tabs" fits in one test —
+no browser required:
+
+```ts
+import { createSharedStore, MemoryHub } from '@use-everywhere/core';
+
+const hub = new MemoryHub();
+const tabA = createSharedStore('t', { n: 0 }, { transport: () => hub.connect() });
+const tabB = createSharedStore('t', { n: 0 }, { transport: () => hub.connect() });
+
+tabA.set('n', 1);
+await new Promise((r) => setTimeout(r, 0));
+tabB.getSnapshot().n; // 1
+```
+
+`openWindow`/`connectToOpener` take equivalent seams (`openFn`, `localWindow`,
+`opener`, `cid`) for driving window flows with fakes.
+
 ## Design notes
 
 - **Shared state never crosses origins.** Two origins are two trust domains;
   the cross-origin channel is explicit, per-message, and typed.
-- Same-origin state sync uses per-key `[counter, clientId]` clocks
-  (last-writer-wins, deterministic tie-break) and a hello/snapshot handshake so
-  late-joining tabs hydrate instantly.
-- Values must survive structured clone (no functions, DOM nodes, etc.).
+- Values must survive structured clone (no functions, DOM nodes, class
+  instances).
+- State lives exactly as long as some context holds it — nothing is persisted.
+- SSR-safe: without `BroadcastChannel`, engines fall back to a local no-op
+  transport.
 
-Full docs, demo app (including a real cross-origin payment flow), and source:
+📖 **[Documentation](https://rxova.github.io/use-everywhere/)** — mental
+model, how sync works, security model, recipes, and generated API reference.
+Source and demo app (with a real cross-origin payment flow):
 [github.com/rxova/use-everywhere](https://github.com/rxova/use-everywhere)
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-everywhere/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Cross-tab shared state, events, presence, and cross-origin window channels",
   "license": "MIT",
   "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
@@ -36,9 +36,55 @@
   "files": [
     "dist"
   ],
+  "size-limit": [
+    {
+      "name": "everything (import *)",
+      "path": "dist/index.js",
+      "import": "*",
+      "limit": "3.5 kB"
+    },
+    {
+      "name": "createSharedStore",
+      "path": "dist/index.js",
+      "import": "{ createSharedStore }",
+      "limit": "1.3 kB"
+    },
+    {
+      "name": "createChannel",
+      "path": "dist/index.js",
+      "import": "{ createChannel }",
+      "limit": "900 B"
+    },
+    {
+      "name": "createPresence",
+      "path": "dist/index.js",
+      "import": "{ createPresence }",
+      "limit": "1 kB"
+    },
+    {
+      "name": "openWindow (opener side)",
+      "path": "dist/index.js",
+      "import": "{ openWindow }",
+      "limit": "1.15 kB"
+    },
+    {
+      "name": "connectToOpener (child side)",
+      "path": "dist/index.js",
+      "import": "{ connectToOpener }",
+      "limit": "1 kB"
+    },
+    {
+      "name": "MemoryHub (test transport)",
+      "path": "dist/index.js",
+      "import": "{ MemoryHub }",
+      "limit": "300 B"
+    }
+  ],
   "devDependencies": {
+    "@size-limit/preset-small-lib": "^12.1.0",
     "@vitest/coverage-v8": "^4.1.10",
     "happy-dom": "^20.10.6",
+    "size-limit": "^12.1.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^4.1.10"
@@ -46,6 +92,7 @@
   "scripts": {
     "build": "tsup",
     "test": "vitest run --coverage",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "size": "size-limit"
   }
 }