@use-everywhere/core 0.10.1 → 0.11.0

package/dist/shared-worker.cjs

@@ -20,34 +20,80 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/shared-worker.ts
 var shared_worker_exports = {};
 __export(shared_worker_exports, {
+  relay: () => relay,
   startRelay: () => startRelay
 });
 module.exports = __toCommonJS(shared_worker_exports);
 function startRelay(scope) {
   const ports = /* @__PURE__ */ new Set();
+  const local = /* @__PURE__ */ new Set();
+  const fanOut = (from, data) => {
+    const dead = [];
+    for (const peer of ports) {
+      if (peer === from) continue;
+      try {
+        peer.postMessage(data);
+      } catch {
+        dead.push(peer);
+      }
+    }
+    for (const corpse of dead) {
+      ports.delete(corpse);
+      local.delete(corpse);
+    }
+  };
   scope.onconnect = (event) => {
     const port = event.ports[0];
     if (!port) return;
     ports.add(port);
-    port.addEventListener("message", (message) => {
-      const dead = [];
-      for (const peer of ports) {
-        if (peer === port) continue;
-        try {
-          peer.postMessage(message.data);
-        } catch {
-          dead.push(peer);
-        }
-      }
-      for (const corpse of dead) ports.delete(corpse);
-    });
+    port.addEventListener("message", (message) => fanOut(port, message.data));
     port.start?.();
   };
+  return {
+    broadcast: (data) => fanOut(null, data),
+    get size() {
+      return ports.size - local.size;
+    },
+    connect() {
+      const listeners = /* @__PURE__ */ new Set();
+      let closed = false;
+      const seat = {
+        // Asynchronous on purpose. `fanOut` runs inside a port's message
+        // listener, and delivering synchronously from there produces the
+        // re-entrancy a real MessagePort never could. Nothing is cloned: every
+        // value reaching this seat already crossed a port boundary and was
+        // structured-cloned there, so there is no live reference to leak.
+        postMessage: (data) => {
+          queueMicrotask(() => {
+            for (const listener of listeners) listener(data);
+          });
+        }
+      };
+      ports.add(seat);
+      local.add(seat);
+      return {
+        kind: "shared-worker",
+        post: (data) => {
+          if (!closed) fanOut(seat, data);
+        },
+        subscribe: (listener) => {
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+        close: () => {
+          if (closed) return;
+          closed = true;
+          listeners.clear();
+          ports.delete(seat);
+          local.delete(seat);
+        }
+      };
+    }
+  };
 }
-if (typeof self !== "undefined" && "onconnect" in self) {
-  startRelay(self);
-}
+var relay = typeof self !== "undefined" && "onconnect" in self ? startRelay(self) : void 0;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  relay,
   startRelay
 });

package/dist/shared-worker.d.cts

@@ -1,3 +1,5 @@
+import { T as Transport } from './transport.types-CV1WZOhy.cjs';
+
 /**
  * The relay that runs *inside* a SharedWorker. Host a one-line module and point
  * `SharedWorkerTransport` at it:
@@ -12,10 +14,25 @@
  * has one job, and making the caller remember to invoke it adds a way to get a
  * worker that accepts connections and forwards nothing.
  *
- * `startRelay` is exported anyway, for a worker that also does other work — an
- * app whose relay owns the WebSocket, say — and for tests, which cannot install
- * a global `onconnect`.
+ * For a worker that also does other work — one that owns the WebSocket, say —
+ * import {@link relay} and join the bus through it:
+ *
+ * ```js
+ * // socket-worker.js
+ * import { relay } from '@use-everywhere/core/shared-worker';
+ * import { createSharedStore } from '@use-everywhere/core';
+ *
+ * const store = createSharedStore('feed', { tick: null }, { transport: () => relay.connect() });
+ * new WebSocket('wss://example.com/feed').onmessage = (e) => store.set('tick', JSON.parse(e.data));
+ * ```
+ *
+ * `startRelay` is exported for tests, which cannot install a global `onconnect`,
+ * and for a scope this module cannot detect. Prefer {@link relay} inside a real
+ * worker: calling `startRelay(self)` there installs a *second* relay over the
+ * one this module already installed, and the first one's ports are then held by
+ * a handler nothing will ever call again.
  */
+
 interface RelayPort {
     postMessage(data: unknown): void;
     start?: () => void;
@@ -28,10 +45,36 @@ interface RelayScope {
         ports: readonly RelayPort[];
     }) => void) | null;
 }
+/** A running relay: the ports it holds, and the worker's own seat on the bus. */
+interface Relay {
+    /**
+     * Join the relay from inside the worker, as one more peer.
+     *
+     * Returns a `Transport`, so worker-side code uses `createSharedStore` and the
+     * rest of the library exactly as a tab does. That is the point: the wire
+     * format stays the engines' business, and a worker that wants to publish
+     * never has to hand-assemble an envelope the protocol might redefine.
+     */
+    connect(): Transport;
+    /**
+     * Fan raw data out to every connected port.
+     *
+     * The escape hatch, for a worker speaking some protocol of its own. Anything
+     * the library's engines will read should go through {@link connect} instead —
+     * this bypasses them entirely.
+     */
+    broadcast(data: unknown): void;
+    /**
+     * How many ports are attached. A live count of the contexts that opened this
+     * worker, which is what you want in order to idle a socket while nobody is
+     * looking. `connect()` seats are not counted: the worker is not its own tab.
+     */
+    readonly size: number;
+}
 /**
- * Fan every message out to the other connected ports.
+ * Fan every message out to the other connected peers.
  *
- * Two properties the buses above this depend on:
+ * Three properties the buses above this depend on:
  *
  * 1. **No self-echo.** A sender never receives its own message, matching
  *    BroadcastChannel exactly. Without it every store would apply its own
@@ -40,7 +83,17 @@ interface RelayScope {
  *    closing its port leaves an entangled port whose `postMessage` throws; one
  *    of those must not stop delivery to the tabs still listening, so the send
  *    loop is individually guarded and the corpse is pruned.
+ * 3. **The worker is a peer, not a special case.** A local seat from
+ *    {@link Relay.connect} is held in the same set as the ports, so both rules
+ *    above apply to it without a second code path to keep in agreement.
+ */
+declare function startRelay(scope: RelayScope): Relay;
+/**
+ * The relay this module installed on import — present only when the module is
+ * running in a SharedWorker, and `undefined` anywhere else, so that importing
+ * it from a bundler tracing entry points, a test runner, or a server render is
+ * inert rather than a `ReferenceError`.
  */
-declare function startRelay(scope: RelayScope): void;
+declare const relay: Relay | undefined;
 
-export { type RelayPort, type RelayScope, startRelay };
+export { type Relay, type RelayPort, type RelayScope, relay, startRelay };

package/dist/shared-worker.d.ts

@@ -1,3 +1,5 @@
+import { T as Transport } from './transport.types-CV1WZOhy.js';
+
 /**
  * The relay that runs *inside* a SharedWorker. Host a one-line module and point
  * `SharedWorkerTransport` at it:
@@ -12,10 +14,25 @@
  * has one job, and making the caller remember to invoke it adds a way to get a
  * worker that accepts connections and forwards nothing.
  *
- * `startRelay` is exported anyway, for a worker that also does other work — an
- * app whose relay owns the WebSocket, say — and for tests, which cannot install
- * a global `onconnect`.
+ * For a worker that also does other work — one that owns the WebSocket, say —
+ * import {@link relay} and join the bus through it:
+ *
+ * ```js
+ * // socket-worker.js
+ * import { relay } from '@use-everywhere/core/shared-worker';
+ * import { createSharedStore } from '@use-everywhere/core';
+ *
+ * const store = createSharedStore('feed', { tick: null }, { transport: () => relay.connect() });
+ * new WebSocket('wss://example.com/feed').onmessage = (e) => store.set('tick', JSON.parse(e.data));
+ * ```
+ *
+ * `startRelay` is exported for tests, which cannot install a global `onconnect`,
+ * and for a scope this module cannot detect. Prefer {@link relay} inside a real
+ * worker: calling `startRelay(self)` there installs a *second* relay over the
+ * one this module already installed, and the first one's ports are then held by
+ * a handler nothing will ever call again.
  */
+
 interface RelayPort {
     postMessage(data: unknown): void;
     start?: () => void;
@@ -28,10 +45,36 @@ interface RelayScope {
         ports: readonly RelayPort[];
     }) => void) | null;
 }
+/** A running relay: the ports it holds, and the worker's own seat on the bus. */
+interface Relay {
+    /**
+     * Join the relay from inside the worker, as one more peer.
+     *
+     * Returns a `Transport`, so worker-side code uses `createSharedStore` and the
+     * rest of the library exactly as a tab does. That is the point: the wire
+     * format stays the engines' business, and a worker that wants to publish
+     * never has to hand-assemble an envelope the protocol might redefine.
+     */
+    connect(): Transport;
+    /**
+     * Fan raw data out to every connected port.
+     *
+     * The escape hatch, for a worker speaking some protocol of its own. Anything
+     * the library's engines will read should go through {@link connect} instead —
+     * this bypasses them entirely.
+     */
+    broadcast(data: unknown): void;
+    /**
+     * How many ports are attached. A live count of the contexts that opened this
+     * worker, which is what you want in order to idle a socket while nobody is
+     * looking. `connect()` seats are not counted: the worker is not its own tab.
+     */
+    readonly size: number;
+}
 /**
- * Fan every message out to the other connected ports.
+ * Fan every message out to the other connected peers.
  *
- * Two properties the buses above this depend on:
+ * Three properties the buses above this depend on:
  *
  * 1. **No self-echo.** A sender never receives its own message, matching
  *    BroadcastChannel exactly. Without it every store would apply its own
@@ -40,7 +83,17 @@ interface RelayScope {
  *    closing its port leaves an entangled port whose `postMessage` throws; one
  *    of those must not stop delivery to the tabs still listening, so the send
  *    loop is individually guarded and the corpse is pruned.
+ * 3. **The worker is a peer, not a special case.** A local seat from
+ *    {@link Relay.connect} is held in the same set as the ports, so both rules
+ *    above apply to it without a second code path to keep in agreement.
+ */
+declare function startRelay(scope: RelayScope): Relay;
+/**
+ * The relay this module installed on import — present only when the module is
+ * running in a SharedWorker, and `undefined` anywhere else, so that importing
+ * it from a bundler tracing entry points, a test runner, or a server render is
+ * inert rather than a `ReferenceError`.
  */
-declare function startRelay(scope: RelayScope): void;
+declare const relay: Relay | undefined;
 
-export { type RelayPort, type RelayScope, startRelay };
+export { type Relay, type RelayPort, type RelayScope, relay, startRelay };

package/dist/shared-worker.js

@@ -1,28 +1,73 @@
 // src/shared-worker.ts
 function startRelay(scope) {
   const ports = /* @__PURE__ */ new Set();
+  const local = /* @__PURE__ */ new Set();
+  const fanOut = (from, data) => {
+    const dead = [];
+    for (const peer of ports) {
+      if (peer === from) continue;
+      try {
+        peer.postMessage(data);
+      } catch {
+        dead.push(peer);
+      }
+    }
+    for (const corpse of dead) {
+      ports.delete(corpse);
+      local.delete(corpse);
+    }
+  };
   scope.onconnect = (event) => {
     const port = event.ports[0];
     if (!port) return;
     ports.add(port);
-    port.addEventListener("message", (message) => {
-      const dead = [];
-      for (const peer of ports) {
-        if (peer === port) continue;
-        try {
-          peer.postMessage(message.data);
-        } catch {
-          dead.push(peer);
-        }
-      }
-      for (const corpse of dead) ports.delete(corpse);
-    });
+    port.addEventListener("message", (message) => fanOut(port, message.data));
     port.start?.();
   };
+  return {
+    broadcast: (data) => fanOut(null, data),
+    get size() {
+      return ports.size - local.size;
+    },
+    connect() {
+      const listeners = /* @__PURE__ */ new Set();
+      let closed = false;
+      const seat = {
+        // Asynchronous on purpose. `fanOut` runs inside a port's message
+        // listener, and delivering synchronously from there produces the
+        // re-entrancy a real MessagePort never could. Nothing is cloned: every
+        // value reaching this seat already crossed a port boundary and was
+        // structured-cloned there, so there is no live reference to leak.
+        postMessage: (data) => {
+          queueMicrotask(() => {
+            for (const listener of listeners) listener(data);
+          });
+        }
+      };
+      ports.add(seat);
+      local.add(seat);
+      return {
+        kind: "shared-worker",
+        post: (data) => {
+          if (!closed) fanOut(seat, data);
+        },
+        subscribe: (listener) => {
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+        close: () => {
+          if (closed) return;
+          closed = true;
+          listeners.clear();
+          ports.delete(seat);
+          local.delete(seat);
+        }
+      };
+    }
+  };
 }
-if (typeof self !== "undefined" && "onconnect" in self) {
-  startRelay(self);
-}
+var relay = typeof self !== "undefined" && "onconnect" in self ? startRelay(self) : void 0;
 export {
+  relay,
   startRelay
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-everywhere/core",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Cross-tab shared state, events, presence, and cross-origin window channels",
   "license": "MIT",
   "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
@@ -143,7 +143,7 @@
       "name": "SharedWorker relay (shared-worker subpath)",
       "path": "dist/shared-worker.js",
       "import": "*",
-      "limit": "280 B"
+      "limit": "410 B"
     },
     {
       "name": "MemoryHub (testing subpath)",