@astroscope/wormhole 0.2.3 → 1.0.0

package/README.md

@@ -22,6 +22,7 @@ Astro recommends [nanostores](https://docs.astro.build/en/recipes/sharing-state/
 
 - **No secrets in wormholes.** All wormhole data is serialized into an inline `<script>` tag and sent to the browser. Never store tokens, API keys, credentials, or any sensitive data in a wormhole.
 - **`set()` is client-only.** Calling `set()` does not work on the server. Use `open(wormhole, data, fn)` from `@astroscope/wormhole/server` to populate data in middleware.
+- **Values are deeply readonly.** `get()`, `subscribe()` and `useWormhole()` expose the value as `DeepReadonly<T>` — in-place mutation would silently bypass subscribers (and on the server would corrupt the request-scoped store). The only way to update is `set()` with a new value: `wh.set({ ...wh.get(), count: 1 })`.
 
 ## Examples
 
@@ -180,12 +181,24 @@ const wh = defineWormhole<{ count: number }>('counter');
 
 | Method             | Description                                                                                         |
 | ------------------ | --------------------------------------------------------------------------------------------------- |
-| `wh.get()`         | Read current value (from `AsyncLocalStorage` on server, from `globalThis` or local store on client) |
-| `wh.set(data)`     | Update value and notify all subscribers (client-side)                                               |
+| `wh.get()`         | Read current value as `DeepReadonly<T>` (from `AsyncLocalStorage` on server, from `globalThis` or local store on client) |
+| `wh.set(data)`     | Replace value with a new one and notify all subscribers (client-side)                               |
 | `wh.subscribe(fn)` | Listen for changes, returns unsubscribe function                                                    |
 | `wh.name`          | The wormhole name                                                                                   |
 | `wh.key`           | The internal `globalThis` key                                                                       |
 
+### `DeepReadonly<T>`
+
+Exported helper type — recursively `readonly` version of `T`. Wormhole values are exposed with this type; use it in your own function signatures when passing wormhole data around:
+
+```ts
+import type { DeepReadonly } from '@astroscope/wormhole';
+
+function isWithinCart(cart: DeepReadonly<Cart>, id: string) {
+  return cart.items.some((item) => item.productId === id);
+}
+```
+
 ### `open(wh, data, fn)` <sub>server only</sub>
 
 Runs `fn` with `data` available via `wh.get()` for the duration of the call. Uses `AsyncLocalStorage` for request isolation.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { W as Wormhole } from './types-hCfcC5bZ.js';
+import { n as Wormhole, t as DeepReadonly } from "./types-0PQTD8gI.js";
 
+//#region src/define.d.ts
 /**
  * Define a wormhole that transfers state from server middleware to client components.
  *
@@ -7,5 +8,6 @@ import { W as Wormhole } from './types-hCfcC5bZ.js';
  * Never store secrets (tokens, API keys, credentials) in a wormhole.
  */
 declare function defineWormhole<T>(name: string): Wormhole<T>;
-
-export { Wormhole, defineWormhole };
+//#endregion
+export { type DeepReadonly, type Wormhole, defineWormhole };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/define.ts"],"mappings":";;;;;AAQA;;;;iBAAgB,cAAA,IAAkB,IAAA,WAAe,QAAQ,CAAC,CAAA"}

package/dist/index.js

@@ -1,34 +1,37 @@
-// src/define.ts
+//#region src/define.ts
+/**
+* Define a wormhole that transfers state from server middleware to client components.
+*
+* **Security:** wormhole data is serialized into the HTML and sent to the browser.
+* Never store secrets (tokens, API keys, credentials) in a wormhole.
+*/
 function defineWormhole(name) {
-  const listeners = /* @__PURE__ */ new Set();
-  const key = `__wormhole_${name}__`;
-  let store;
-  return {
-    name,
-    key,
-    get() {
-      if (store !== void 0) return store;
-      const getter = globalThis[key];
-      if (typeof getter === "function") return getter();
-      throw new Error(`wormhole "${name}" is not initialized`);
-    },
-    set(data) {
-      if (typeof globalThis.window === "undefined") {
-        throw new Error(
-          `wormhole "${name}" set() cannot be called on the server as it is not request-scoped; use open(wormhole, data, fn) from "@astroscope/wormhole/server" instead`
-        );
-      }
-      store = data;
-      for (const fn of listeners) fn(data);
-    },
-    subscribe(fn) {
-      listeners.add(fn);
-      return () => {
-        listeners.delete(fn);
-      };
-    }
-  };
+	const listeners = /* @__PURE__ */ new Set();
+	const key = `__wormhole_${name}__`;
+	let store;
+	return {
+		name,
+		key,
+		get() {
+			if (store !== void 0) return store;
+			const getter = globalThis[key];
+			if (typeof getter === "function") return getter();
+			throw new Error(`wormhole "${name}" is not initialized`);
+		},
+		set(data) {
+			if (typeof globalThis.window === "undefined") throw new Error(`wormhole "${name}" set() cannot be called on the server as it is not request-scoped; use open(wormhole, data, fn) from "@astroscope/wormhole/server" instead`);
+			store = data;
+			for (const fn of listeners) fn(data);
+		},
+		subscribe(fn) {
+			listeners.add(fn);
+			return () => {
+				listeners.delete(fn);
+			};
+		}
+	};
 }
-export {
-  defineWormhole
-};
+//#endregion
+export { defineWormhole };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/define.ts"],"sourcesContent":["import type { DeepReadonly, Wormhole } from './types.js';\n\n/**\n * Define a wormhole that transfers state from server middleware to client components.\n *\n * **Security:** wormhole data is serialized into the HTML and sent to the browser.\n * Never store secrets (tokens, API keys, credentials) in a wormhole.\n */\nexport function defineWormhole<T>(name: string): Wormhole<T> {\n  const listeners = new Set<(data: DeepReadonly<T>) => void>();\n  const key = `__wormhole_${name}__`;\n  let store: DeepReadonly<T> | undefined;\n\n  return {\n    name,\n    key,\n\n    get(): DeepReadonly<T> {\n      if (store !== undefined) return store;\n\n      const getter = (globalThis as any)[key];\n\n      if (typeof getter === 'function') return getter() as DeepReadonly<T>;\n\n      throw new Error(`wormhole \"${name}\" is not initialized`);\n    },\n\n    set(data: DeepReadonly<T>): void {\n      if (typeof (globalThis as any).window === 'undefined') {\n        throw new Error(\n          `wormhole \"${name}\" set() cannot be called on the server as it is not request-scoped; use open(wormhole, data, fn) from \"@astroscope/wormhole/server\" instead`,\n        );\n      }\n\n      store = data;\n\n      for (const fn of listeners) fn(data);\n    },\n\n    subscribe(fn: (data: DeepReadonly<T>) => void): () => void {\n      listeners.add(fn);\n\n      return () => {\n        listeners.delete(fn);\n      };\n    },\n  };\n}\n"],"mappings":";;;;;;;AAQA,SAAgB,eAAkB,MAA2B;CAC3D,MAAM,4BAAY,IAAI,IAAqC;CAC3D,MAAM,MAAM,cAAc,KAAK;CAC/B,IAAI;CAEJ,OAAO;EACL;EACA;EAEA,MAAuB;GACrB,IAAI,UAAU,KAAA,GAAW,OAAO;GAEhC,MAAM,SAAU,WAAmB;GAEnC,IAAI,OAAO,WAAW,YAAY,OAAO,OAAO;GAEhD,MAAM,IAAI,MAAM,aAAa,KAAK,qBAAqB;EACzD;EAEA,IAAI,MAA6B;GAC/B,IAAI,OAAQ,WAAmB,WAAW,aACxC,MAAM,IAAI,MACR,aAAa,KAAK,4IACpB;GAGF,QAAQ;GAER,KAAK,MAAM,MAAM,WAAW,GAAG,IAAI;EACrC;EAEA,UAAU,IAAiD;GACzD,UAAU,IAAI,EAAE;GAEhB,aAAa;IACX,UAAU,OAAO,EAAE;GACrB;EACF;CACF;AACF"}

package/dist/react/index.d.ts

@@ -1,5 +1,7 @@
-import { W as Wormhole } from '../types-hCfcC5bZ.js';
-
-declare function useWormhole<T>(wormhole: Wormhole<T>): T;
+import { n as Wormhole, t as DeepReadonly } from "../types-0PQTD8gI.js";
 
+//#region src/react/index.d.ts
+declare function useWormhole<T>(wormhole: Wormhole<T>): DeepReadonly<T>;
+//#endregion
 export { useWormhole };
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/react/index.ts"],"mappings":";;;iBAGgB,WAAA,IAAe,QAAA,EAAU,QAAA,CAAS,CAAA,IAAK,YAAA,CAAa,CAAA"}

package/dist/react/index.js

@@ -1,8 +1,9 @@
-// src/react/index.ts
 import { useSyncExternalStore } from "react";
+//#region src/react/index.ts
 function useWormhole(wormhole) {
-  return useSyncExternalStore(wormhole.subscribe, wormhole.get, wormhole.get);
+	return useSyncExternalStore(wormhole.subscribe, wormhole.get, wormhole.get);
 }
-export {
-  useWormhole
-};
+//#endregion
+export { useWormhole };
+
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/react/index.ts"],"sourcesContent":["import { useSyncExternalStore } from 'react';\nimport type { DeepReadonly, Wormhole } from '../types.js';\n\nexport function useWormhole<T>(wormhole: Wormhole<T>): DeepReadonly<T> {\n  return useSyncExternalStore(wormhole.subscribe, wormhole.get, wormhole.get);\n}\n"],"mappings":";;AAGA,SAAgB,YAAe,UAAwC;CACrE,OAAO,qBAAqB,SAAS,WAAW,SAAS,KAAK,SAAS,GAAG;AAC5E"}

package/dist/server.d.ts

@@ -1,5 +1,7 @@
-import { W as Wormhole } from './types-hCfcC5bZ.js';
-
-declare function open<T, R>(wh: Wormhole<T>, data: T, fn: () => R): R;
+import { n as Wormhole, t as DeepReadonly } from "./types-0PQTD8gI.js";
 
+//#region src/server.d.ts
+declare function open<T, R>(wh: Wormhole<T>, data: DeepReadonly<T>, fn: () => R): R;
+//#endregion
 export { open };
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","names":[],"sources":["../src/server.ts"],"mappings":";;;iBAKgB,IAAA,OAAW,EAAA,EAAI,QAAA,CAAS,CAAA,GAAI,IAAA,EAAM,YAAA,CAAa,CAAA,GAAI,EAAA,QAAU,CAAA,GAAI,CAAA"}

package/dist/server.js

@@ -1,15 +1,16 @@
-// src/server.ts
-import { AsyncLocalStorage } from "async_hooks";
-var stores = /* @__PURE__ */ new Map();
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/server.ts
+const stores = /* @__PURE__ */ new Map();
 function open(wh, data, fn) {
-  let als = stores.get(wh.key);
-  if (!als) {
-    als = new AsyncLocalStorage();
-    stores.set(wh.key, als);
-  }
-  globalThis[wh.key] = () => als.getStore();
-  return als.run(data, fn);
+	let als = stores.get(wh.key);
+	if (!als) {
+		als = new AsyncLocalStorage();
+		stores.set(wh.key, als);
+	}
+	globalThis[wh.key] = () => als.getStore();
+	return als.run(data, fn);
 }
-export {
-  open
-};
+//#endregion
+export { open };
+
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\nimport type { DeepReadonly, Wormhole } from './types.js';\n\nconst stores = new Map<string, AsyncLocalStorage<unknown>>();\n\nexport function open<T, R>(wh: Wormhole<T>, data: DeepReadonly<T>, fn: () => R): R {\n  let als = stores.get(wh.key) as AsyncLocalStorage<DeepReadonly<T>> | undefined;\n\n  if (!als) {\n    als = new AsyncLocalStorage<DeepReadonly<T>>();\n    stores.set(wh.key, als as AsyncLocalStorage<unknown>);\n  }\n\n  (globalThis as any)[wh.key] = () => als!.getStore();\n\n  return als.run(data, fn);\n}\n"],"mappings":";;AAGA,MAAM,yBAAS,IAAI,IAAwC;AAE3D,SAAgB,KAAW,IAAiB,MAAuB,IAAgB;CACjF,IAAI,MAAM,OAAO,IAAI,GAAG,GAAG;CAE3B,IAAI,CAAC,KAAK;EACR,MAAM,IAAI,kBAAmC;EAC7C,OAAO,IAAI,GAAG,KAAK,GAAiC;CACtD;CAEA,WAAoB,GAAG,aAAa,IAAK,SAAS;CAElD,OAAO,IAAI,IAAI,MAAM,EAAE;AACzB"}

package/dist/types-0PQTD8gI.d.ts

@@ -0,0 +1,31 @@
+//#region src/types.d.ts
+/**
+ * Recursively marks all properties of `T` as `readonly`.
+ *
+ * Wormhole data is JSON-serializable by design (it is inlined into a `<script>` tag),
+ * so only plain objects, arrays, and primitives need to be handled.
+ */
+type DeepReadonly<T> = T extends ((...args: never[]) => unknown) ? T : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;
+/**
+ * A wormhole transfers state from server middleware to client-side components.
+ *
+ * **Security:** wormhole data is serialized into an inline `<script>` tag and sent to the browser.
+ * Never store secrets (tokens, API keys, credentials) in a wormhole.
+ *
+ * The stored value is exposed as deeply readonly — the only way to change it is `set()`
+ * (client) or `open()` (server) with a new value, which keeps subscribers in sync.
+ */
+interface Wormhole<T> {
+  readonly name: string;
+  readonly key: string;
+  get(): DeepReadonly<T>;
+  /**
+   * Update the wormhole value on the **client only**.
+   * Throws on the server — use `open(wormhole, data, fn)` from `@astroscope/wormhole/server` instead.
+   */
+  set(data: DeepReadonly<T>): void;
+  subscribe(fn: (data: DeepReadonly<T>) => void): () => void;
+}
+//#endregion
+export { Wormhole as n, DeepReadonly as t };
+//# sourceMappingURL=types-0PQTD8gI.d.ts.map

package/dist/types-0PQTD8gI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-0PQTD8gI.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;AAMA;;;;;KAAY,YAAA,MAAkB,CAAA,cAAc,IAAA,yBACxC,CAAA,GACA,CAAA,yCACyB,CAAA,GAAI,YAAA,CAAa,CAAA,CAAE,CAAA,OAC1C,CAAA;;;;;;;;;;UAWW,QAAA;EAAA,SACN,IAAA;EAAA,SACA,GAAA;EACT,GAAA,IAAO,YAAA,CAAa,CAAA;EAfwB;;;;EAoB5C,GAAA,CAAI,IAAA,EAAM,YAAA,CAAa,CAAA;EACvB,SAAA,CAAU,EAAA,GAAK,IAAA,EAAM,YAAA,CAAa,CAAA;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astroscope/wormhole",
-  "version": "0.2.3",
+  "version": "1.0.0",
   "description": "Share dynamic server data with React islands and client scripts — typed, reactive",
   "type": "module",
   "main": "./dist/index.js",
@@ -50,14 +50,15 @@
   },
   "homepage": "https://github.com/entwico/astroscope/tree/main/packages/wormhole#readme",
   "devDependencies": {
-    "@types/react": "^19.2.14",
-    "astro": "^6.1.8",
-    "react": "^19.2.5",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
+    "@types/node": "^26.0.1",
+    "@types/react": "^19.2.17",
+    "astro": "^7.0.3",
+    "react": "^19.2.7",
+    "tsdown": "^0.22.3",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "astro": "^6.0.0",
+    "astro": "^7.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
@@ -66,9 +67,9 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts src/server.ts src/react/index.ts --format esm --dts",
+    "build": "tsdown src/index.ts src/server.ts src/react/index.ts --format esm --dts --no-fixed-extension",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src",
+    "lint": "eslint src --cache",
     "lint:fix": "eslint src --fix"
   }
 }

package/dist/types-hCfcC5bZ.d.ts

@@ -1,19 +0,0 @@
-/**
- * A wormhole transfers state from server middleware to client-side components.
- *
- * **Security:** wormhole data is serialized into an inline `<script>` tag and sent to the browser.
- * Never store secrets (tokens, API keys, credentials) in a wormhole.
- */
-interface Wormhole<T> {
-    readonly name: string;
-    readonly key: string;
-    get(): T;
-    /**
-     * Update the wormhole value on the **client only**.
-     * Throws on the server — use `open(wormhole, data, fn)` from `@astroscope/wormhole/server` instead.
-     */
-    set(data: T): void;
-    subscribe(fn: (data: T) => void): () => void;
-}
-
-export type { Wormhole as W };