@use-everywhere/core 0.3.0 → 0.4.1

package/dist/index.d.cts

@@ -0,0 +1,445 @@
+/**
+ * Minimal message bus. Implementations: BroadcastChannelTransport (same-origin),
+ * NoopTransport (SSR / local-only), MemoryTransport (tests). A transport never
+ * echoes a client's own posts back to it.
+ */
+interface Transport {
+    post(data: unknown): void;
+    subscribe(listener: (data: unknown) => void): () => void;
+    close(): void;
+}
+
+type MessageMap = Record<string, unknown>;
+type PeerKind = 'tab' | 'worker' | (string & {});
+/** Per-key logical clock: [counter, clientId]. Ties break by clientId. */
+type Version = readonly [counter: number, clientId: string];
+interface Peer {
+    id: string;
+    kind: PeerKind;
+    lastSeen: number;
+}
+interface MessageMeta {
+    clientId: string;
+    kind: PeerKind;
+    self: boolean;
+}
+interface CommonOptions {
+    /** Transport factory, mainly for tests. Defaults to defaultTransport. */
+    transport?: (name: string) => Transport;
+    /** What this client announces itself as. Defaults to 'worker' when there is no document, else 'tab'. */
+    kind?: PeerKind;
+}
+
+interface Channel<M extends MessageMap> {
+    readonly name: string;
+    readonly clientId: string;
+    /** Fire-and-forget to every other tab/window/worker on this origin. Not echoed to self. */
+    post<K extends keyof M & string>(type: K, payload: M[K]): void;
+    on<K extends keyof M & string>(type: K, handler: (payload: M[K], meta: MessageMeta) => void): () => void;
+    close(): void;
+}
+
+/** Typed pub/sub over the same-origin bus. */
+declare function createChannel<M extends MessageMap>(name: string, options?: CommonOptions): Channel<M>;
+
+/**
+ * What goes to disk. The version clocks travel *with* the values — that is the
+ * whole point: a reopened tab re-enters the last-writer-wins race with its real
+ * term instead of a fresh zero, so a restored value can legitimately beat, or
+ * legitimately lose to, whatever the live tabs are holding.
+ */
+interface Persisted {
+    v: 1;
+    state: Record<string, unknown>;
+    versions: Record<string, Version>;
+}
+interface PersistAdapter {
+    /**
+     * Prefer a synchronous read. An async adapter cannot hydrate before the store
+     * is handed back, so a write made in that gap can be clobbered by the restore.
+     */
+    read(): Persisted | undefined | Promise<Persisted | undefined>;
+    write(snapshot: Persisted): void | Promise<void>;
+    remove?(): void | Promise<void>;
+}
+interface PersistOptions {
+    adapter: PersistAdapter;
+    /** Persist only these keys. Default: every key that has been written. */
+    keys?: string[];
+    /** Coalesce writes for this long. Default 100. */
+    debounceMs?: number;
+}
+
+interface SharedStoreOptions extends CommonOptions {
+    /**
+     * Gatekeeper for incoming remote writes (patches and snapshot merges):
+     * return false to ignore them. Lets callers delimit how much is shared —
+     * e.g. accept only writes from other tabs, not from workers.
+     */
+    accept?: (meta: MessageMeta) => boolean;
+    /** Restore this store on creation and write it back as it changes. */
+    persist?: PersistOptions;
+}
+interface SharedStore<S extends Record<string, unknown>> {
+    readonly clientId: string;
+    /** Live proxy for imperative use: `store.state.count++` syncs everywhere. */
+    readonly state: S;
+    /** Immutable snapshot, replaced whenever a change is applied. Safe for useSyncExternalStore. */
+    getSnapshot(): Readonly<S>;
+    /** The per-key version clocks behind the snapshot. Referentially stable, like getSnapshot. */
+    getVersions(): Readonly<Record<string, Version>>;
+    set<K extends keyof S & string>(key: K, value: S[K] | ((prev: S[K]) => S[K])): void;
+    subscribe(fn: (key: keyof S & string, value: unknown, meta: MessageMeta) => void): () => void;
+    subscribeKey(key: keyof S & string, fn: () => void): () => void;
+    /**
+     * Register a key lazily at version [0, clientId] — any patch or snapshot a
+     * peer has already made for it wins over the initial value. No-op if the
+     * key already exists.
+     */
+    registerKey<K extends keyof S & string>(key: K, initial: S[K]): void;
+    close(): void;
+}
+
+/**
+ * State synced across every same-origin tab/window/worker: per-key
+ * last-writer-wins version clocks and a hello/snapshot late-joiner handshake.
+ * Create at most one store per name per tab (the React package memoizes).
+ */
+declare function createSharedStore<S extends Record<string, unknown>>(name: string, initial: S, options?: SharedStoreOptions): SharedStore<S>;
+
+/** Everything on the same-origin bus, multiplexed by scope over one BroadcastChannel per name. */
+type BusWire = {
+    v: 1;
+    scope: 'state';
+    type: 'patch';
+    key: string;
+    value: unknown;
+    version: Version;
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'state';
+    type: 'hello';
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'state';
+    type: 'snapshot';
+    clientId: string;
+    kind: PeerKind;
+    state: Record<string, unknown>;
+    versions: Record<string, Version>;
+} | {
+    v: 1;
+    scope: 'presence';
+    type: 'hello' | 'ping' | 'bye';
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'leader';
+    type: 'hello';
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'leader';
+    type: 'claim' | 'heartbeat' | 'resign';
+    /** The claimant's term. Arbitrated with newer() — the same clock the store uses. */
+    term: Version;
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'event';
+    type: string;
+    payload: unknown;
+    clientId: string;
+    kind: PeerKind;
+    msgId: string;
+};
+interface BusOptions extends CommonOptions {
+    /** Presence heartbeat interval in ms. Default 2000. */
+    heartbeatMs?: number;
+}
+
+interface PresenceOptions extends BusOptions {
+    /** Peers silent for longer than this are dropped. Default 5000ms. */
+    pruneAfterMs?: number;
+}
+interface Presence {
+    readonly clientId: string;
+    /** Stable array snapshot (replaced on change) — safe for useSyncExternalStore. */
+    getPeers(): readonly Peer[];
+    subscribe(fn: () => void): () => void;
+    close(): void;
+}
+
+/**
+ * Tracks the other tabs/windows/workers on this bus. Any message from a peer
+ * counts as a liveness signal (state patches, events, and presence pings all
+ * piggyback); explicit 'bye' or silence past pruneAfterMs removes them.
+ */
+declare function createPresence(name: string, options?: PresenceOptions): Presence;
+
+/**
+ * Deliberately extends CommonOptions, not BusOptions: `heartbeatMs` here means
+ * the leader's re-announce interval, which is a different thing from the bus's
+ * presence ping. See the note in leader.ts about forwarding to getBus.
+ */
+interface LeaderOptions extends CommonOptions {
+    /** How often the leader re-announces itself, in ms. Default 1000. */
+    heartbeatMs?: number;
+    /** How long a follower tolerates silence before calling the seat empty, in ms. Default 3000. */
+    leaseMs?: number;
+    /** May this client hold the leadership? Default true. */
+    eligible?: boolean;
+}
+interface LeaderSnapshot {
+    /** The current leader's clientId, or null while the seat is empty. */
+    readonly leaderId: string | null;
+    readonly isLeader: boolean;
+}
+interface Leader {
+    readonly clientId: string;
+    /** Frozen; a new object only when the leader actually changes. */
+    getSnapshot(): LeaderSnapshot;
+    subscribe(fn: () => void): () => void;
+    /** Give up the seat now. Peers take over immediately rather than waiting for the lease. */
+    resign(): void;
+    /** Turn candidacy on or off. Eligibility is a property of the tab, not a component. */
+    setEligible(eligible: boolean): void;
+    close(): void;
+}
+
+/**
+ * Elects exactly one client on the bus to hold a seat: the tab that owns the
+ * WebSocket, polls, or refreshes the token, while the others stand by.
+ *
+ * Lease and claim, with a sticky incumbent. A leader re-announces every
+ * heartbeatMs; followers give up on it after leaseMs of silence and claim the
+ * seat with a higher term. Terms are Versions, arbitrated by the same newer()
+ * the store uses, so simultaneous claims resolve deterministically instead of
+ * flapping.
+ *
+ * Leadership is advisory. It is not a distributed lock, and a hidden tab whose
+ * timers are throttled can lose a lease it deserved to keep.
+ */
+declare function createLeader(name: string, options?: LeaderOptions): Leader;
+
+type StorageLike = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+/**
+ * Persist to any Storage-shaped thing.
+ *
+ * `storage` may be a thunk, and that is the form the built-in adapters use:
+ * merely *reading* `globalThis.localStorage` throws SecurityError when storage
+ * is blocked (a sandboxed iframe, third-party cookies off), so evaluating it at
+ * module scope would blow up on import — before any try/catch here could help.
+ * Behind a thunk, every access happens inside one.
+ *
+ * Blocked storage, corrupt JSON, a foreign schema, or a full quota all degrade
+ * to a silent no-op. Persistence is best-effort; it must never break the store.
+ */
+declare function webStorageAdapter(storage: StorageLike | (() => StorageLike | undefined), key: string): PersistAdapter;
+/** Survives closing every tab. */
+declare function localStorageAdapter(key: string): PersistAdapter;
+/** Survives reloads, but dies with the tab. */
+declare function sessionStorageAdapter(key: string): PersistAdapter;
+
+interface MessageEventLike {
+    data: unknown;
+    origin: string;
+    source: unknown;
+}
+/** The subset of Window we post to (the other side). */
+interface WindowLike {
+    postMessage(data: unknown, targetOrigin: string): void;
+    closed?: boolean;
+    close?(): void;
+}
+/** The subset of Window we listen on (our side). */
+interface WindowEventTarget {
+    addEventListener(type: string, listener: (event: MessageEventLike) => void): void;
+    removeEventListener(type: string, listener: (event: MessageEventLike) => void): void;
+}
+interface OpenWindowOptions {
+    /** Exact origin of the page being opened, e.g. 'https://pay.example.com'. Required. */
+    peerOrigin: string;
+    /** window.open feature string, e.g. 'popup,width=480,height=640'. */
+    features?: string;
+    /** Give up on the ready handshake after this long. Default 15000ms. */
+    readyTimeoutMs?: number;
+    /** Dev only: accept messages from any origin and post with targetOrigin '*'. */
+    allowAnyOrigin?: boolean;
+    /** Test seam. Defaults to window.open. */
+    openFn?: (url: string, target: string, features?: string) => WindowLike | null;
+    /** Test seam. Defaults to the global window. */
+    localWindow?: WindowEventTarget;
+}
+interface OpenedWindow<Out extends MessageMap, In extends MessageMap, R> {
+    /** The opened window, or null if the popup was blocked. */
+    readonly window: WindowLike | null;
+    /** Resolves once the child completes the ready handshake. */
+    readonly ready: Promise<void>;
+    /** Queued until the handshake completes — nothing is dropped while the child loads. */
+    post<K extends keyof Out & string>(type: K, payload: Out[K]): void;
+    on<K extends keyof In & string>(type: K, handler: (payload: In[K]) => void): () => void;
+    /** The child's finish() value. Rejects WindowClosedError / HandshakeTimeoutError. */
+    readonly result: Promise<R>;
+    /** Resolves when the child window is gone (with or without a result). */
+    readonly closed: Promise<void>;
+    /** Close the child window. */
+    close(): void;
+}
+interface ConnectToOpenerOptions {
+    /** Exact origin of the page that opened this window. Required. */
+    peerOrigin: string;
+    /** Give up on the ready handshake after this long. Default 15000ms. */
+    readyTimeoutMs?: number;
+    /** Dev only: accept messages from any origin and post with targetOrigin '*'. */
+    allowAnyOrigin?: boolean;
+    /** Test seam. Defaults to window.opener. */
+    opener?: WindowLike | null;
+    /** Test seam. Defaults to the global window. */
+    localWindow?: WindowEventTarget;
+    /** Test seam. Defaults to the ue-cid query parameter. */
+    cid?: string;
+}
+interface OpenerConnection<In extends MessageMap, Out extends MessageMap, R> {
+    /** Resolves once the opener acknowledges the ready handshake. */
+    readonly ready: Promise<void>;
+    /** Queued until the handshake completes. */
+    post<K extends keyof Out & string>(type: K, payload: Out[K]): void;
+    on<K extends keyof In & string>(type: K, handler: (payload: In[K]) => void): () => void;
+    /** Deliver the terminal result to the opener. Does not close the window. */
+    finish(result: R): void;
+    /** Tell the opener we're going away, then close this window. */
+    close(): void;
+}
+
+declare const CID_PARAM = "ue-cid";
+/**
+ * Open a window (possibly on another origin) and get a typed 1:1 channel to it.
+ * The child must call connectToOpener(). Every received message is validated:
+ * event.origin, envelope brand, per-connection nonce, and event.source.
+ */
+declare function openWindow<Out extends MessageMap, In extends MessageMap, R = unknown>(url: string | URL, options: OpenWindowOptions): OpenedWindow<Out, In, R>;
+/**
+ * Call from the opened (child) window to connect back to its opener.
+ * Throws synchronously when there is no opener or no ue-cid parameter —
+ * i.e. the page was not opened via openWindow().
+ */
+declare function connectToOpener<In extends MessageMap, Out extends MessageMap, R = unknown>(options: ConnectToOpenerOptions): OpenerConnection<In, Out, R>;
+
+/** The opened window closed before delivering a result. */
+declare class WindowClosedError extends Error {
+    constructor(message?: string);
+}
+
+/** The ready/ready-ack handshake never completed. */
+declare class HandshakeTimeoutError extends Error {
+    constructor(message?: string);
+}
+
+/** Is `a` newer than `b`? Last-writer-wins; equal counters break ties by clientId. */
+declare function newer(a: Version, b: Version | undefined): boolean;
+
+/**
+ * The bus name used when a caller does not pick one. A BroadcastChannel is
+ * global to the origin, so identity is the name string — everything that
+ * omits a name lands on this one bus.
+ */
+declare const DEFAULT_NAME = "use-everywhere";
+
+/** One wire crossing the bus, in either direction. */
+interface BusEvent {
+    /** The bus name the wire crossed. */
+    readonly name: string;
+    /** 'out' is posted by this client; 'in' is received from a peer. */
+    readonly direction: 'in' | 'out';
+    readonly wire: BusWire;
+}
+type BusObserver = (event: BusEvent) => void;
+interface DebugOptions {
+    /** Bus name to log. Defaults to the default store/channel name. */
+    name?: string;
+    /** Where to write. Defaults to console.log. */
+    log?: (...args: unknown[]) => void;
+}
+
+/**
+ * Watch every wire crossing the named bus, in both directions. Outbound wires
+ * are the interesting half: a post goes straight to the transport, so without
+ * this seam nothing this client says is visible to it.
+ *
+ * Works for buses that do not exist yet — observe first, create later.
+ */
+declare function observeBus(name: string, fn: BusObserver): () => void;
+/** Log every wire on a bus to the console. Returns a function to stop. */
+declare function enableDebug(options?: DebugOptions): () => void;
+
+/**
+ * Get the shared bus for `name`, creating it on first use. Callers must call
+ * bus.release() exactly once when done. When a custom transport factory is
+ * given (tests), every call creates an isolated bus — one call = one simulated client.
+ */
+/**
+ * Names of the buses currently alive on this page. Buses built with a custom
+ * transport (tests) bypass the registry, so they are not listed.
+ */
+declare function getBusNames(): string[];
+
+/** Same-origin transport over a real BroadcastChannel. */
+declare class BroadcastChannelTransport implements Transport {
+    private bc;
+    private listeners;
+    constructor(name: string);
+    post(data: unknown): void;
+    subscribe(listener: (data: unknown) => void): () => void;
+    close(): void;
+}
+
+/**
+ * Silent local transport: nothing leaves this context, nothing arrives.
+ * Used for SSR and for state scoped to a single tab.
+ */
+declare class NoopTransport implements Transport {
+    post(): void;
+    subscribe(): () => void;
+    close(): void;
+}
+
+declare function isBroadcastChannelAvailable(): boolean;
+/** Default factory: real BroadcastChannel when available, otherwise a local no-op. */
+declare function defaultTransport(name: string): Transport;
+
+/** One simulated client on a MemoryHub. Create via hub.connect(). */
+declare class MemoryTransport implements Transport {
+    private hub;
+    private listeners;
+    private closed;
+    constructor(hub: MemoryHub);
+    post(data: unknown): void;
+    subscribe(listener: (data: unknown) => void): () => void;
+    close(): void;
+    /** @internal */
+    deliver(data: unknown): void;
+}
+
+/**
+ * In-memory hub for tests: N transports attached to one hub, each post is
+ * delivered to every *other* transport on a microtask (mirrors BroadcastChannel's
+ * async, no-self-echo delivery).
+ */
+declare class MemoryHub {
+    private transports;
+    connect(): MemoryTransport;
+    /** @internal */
+    broadcast(from: MemoryTransport, data: unknown): void;
+    /** @internal */
+    disconnect(transport: MemoryTransport): void;
+}
+
+export { BroadcastChannelTransport, type BusEvent, type BusObserver, type BusWire, CID_PARAM, type Channel, type CommonOptions, type ConnectToOpenerOptions, DEFAULT_NAME, type DebugOptions, HandshakeTimeoutError, type Leader, type LeaderOptions, type LeaderSnapshot, MemoryHub, MemoryTransport, type MessageEventLike, type MessageMap, type MessageMeta, NoopTransport, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type PersistAdapter, type PersistOptions, type Persisted, type Presence, type PresenceOptions, type SharedStore, type SharedStoreOptions, type StorageLike, type Transport, type Version, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createLeader, createPresence, createSharedStore, defaultTransport, enableDebug, getBusNames, isBroadcastChannelAvailable, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter };

package/dist/index.js

@@ -211,6 +211,24 @@ function newer(a, b) {
   return !b || a[0] > b[0] || a[0] === b[0] && a[1] > b[1];
 }
 
+// src/dev-freeze.ts
+var inDev = false;
+try {
+  inDev = process.env.NODE_ENV !== "production";
+} catch {
+}
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return;
+  Object.freeze(value);
+  for (const key of Object.keys(value)) {
+    deepFreeze(value[key]);
+  }
+}
+function freezeShared(value) {
+  if (inDev) deepFreeze(value);
+  return value;
+}
+
 // src/shared-store.ts
 function createSharedStore(name, initial, options = {}) {
   const bus = getBus(name, options);
@@ -218,7 +236,10 @@ function createSharedStore(name, initial, options = {}) {
   const accept = options.accept;
   const state = { ...initial };
   const versions = {};
-  for (const k in state) versions[k] = [0, clientId];
+  for (const k in state) {
+    versions[k] = [0, clientId];
+    freezeShared(state[k]);
+  }
   let snapshot = Object.freeze({ ...state });
   let versionsSnapshot = Object.freeze({ ...versions });
   const listeners = /* @__PURE__ */ new Set();
@@ -233,7 +254,7 @@ function createSharedStore(name, initial, options = {}) {
   function applyRemote(key, value, version, meta) {
     if (!newer(version, versions[key])) return;
     versions[key] = version;
-    state[key] = value;
+    state[key] = freezeShared(value);
     notify(key, value, meta);
   }
   const unsubscribe = bus.subscribe((wire) => {
@@ -264,7 +285,7 @@ function createSharedStore(name, initial, options = {}) {
   function setKey(key, value) {
     const version = [(versions[key]?.[0] ?? 0) + 1, clientId];
     versions[key] = version;
-    state[key] = value;
+    state[key] = freezeShared(value);
     bus.post({
       v: 1,
       scope: "state",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-everywhere/core",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Cross-tab shared state, events, presence, and cross-origin window channels",
   "license": "MIT",
   "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
@@ -25,12 +25,19 @@
   },
   "type": "module",
   "sideEffects": false,
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [
@@ -99,18 +106,22 @@
     }
   ],
   "devDependencies": {
-    "@size-limit/preset-small-lib": "^12.1.0",
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@size-limit/preset-small-lib": "^13.0.1",
     "@vitest/coverage-v8": "^4.1.10",
-    "happy-dom": "^20.10.6",
-    "size-limit": "^12.1.0",
-    "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
+    "happy-dom": "^20.11.1",
+    "publint": "^0.3.21",
+    "size-limit": "^13.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   },
   "scripts": {
     "build": "tsup",
     "test": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
-    "size": "size-limit"
+    "size": "size-limit",
+    "check:exports": "publint --strict && attw --pack .",
+    "pack:smoke": "node --import tsx ../tooling/pack-smoke.ts"
   }
 }