@astroscope/wormhole 0.3.0 → 1.1.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.
@@ -196,6 +209,17 @@ import { open } from '@astroscope/wormhole/server';
 return open(myWormhole, { count: 0 }, () => next());
 ```
 
+To open several wormholes at once, pass an array of `[wormhole, data]` pairs — each pair is type-checked against its own wormhole:
+
+```ts
+return open([
+  [cartStore, cart],
+  [sessionStore, session],
+], () => next());
+```
+
+Nested `open()` calls shadow only the wormholes they name; everything else stays visible.
+
 ### `useWormhole(wh)` <sub>React only</sub>
 
 React hook that reads the wormhole and re-renders on changes. Uses `useSyncExternalStore` internally.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { t as Wormhole } from "./types-DHysnZE3.js";
+import { n as Wormhole, t as DeepReadonly } from "./types-Q2gaO_N_.js";
 
 //#region src/define.d.ts
 /**
@@ -9,5 +9,5 @@ import { t as Wormhole } from "./types-DHysnZE3.js";
  */
 declare function defineWormhole<T>(name: string): Wormhole<T>;
 //#endregion
-export { type Wormhole, defineWormhole };
+export { type DeepReadonly, type Wormhole, defineWormhole };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -15,8 +15,9 @@ function defineWormhole(name) {
 		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`);
+			const value = typeof getter === "function" ? getter() : void 0;
+			if (value === void 0) throw new Error(`wormhole "${name}" is not initialized`);
+			return value;
 		},
 		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`);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/define.ts"],"sourcesContent":["import type { 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: T) => void>();\n  const key = `__wormhole_${name}__`;\n  let store: T | undefined;\n\n  return {\n    name,\n    key,\n\n    get(): T {\n      if (store !== undefined) return store;\n\n      const getter = (globalThis as any)[key];\n\n      if (typeof getter === 'function') return getter() as T;\n\n      throw new Error(`wormhole \"${name}\" is not initialized`);\n    },\n\n    set(data: 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: 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,IAAuB;CAC7C,MAAM,MAAM,cAAc,KAAK;CAC/B,IAAI;CAEJ,OAAO;EACL;EACA;EAEA,MAAS;GACP,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,MAAe;GACjB,IAAI,OAAQ,WAAmB,WAAW,aACxC,MAAM,IAAI,MACR,aAAa,KAAK,4IACpB;GAGF,QAAQ;GAER,KAAK,MAAM,MAAM,WAAW,GAAG,IAAI;EACrC;EAEA,UAAU,IAAmC;GAC3C,UAAU,IAAI,EAAE;GAEhB,aAAa;IACX,UAAU,OAAO,EAAE;GACrB;EACF;CACF;AACF"}
+{"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      const value = typeof getter === 'function' ? (getter() as DeepReadonly<T> | undefined) : undefined;\n\n      if (value === undefined) {\n        throw new Error(`wormhole \"${name}\" is not initialized`);\n      }\n\n      return value;\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;GACnC,MAAM,QAAQ,OAAO,WAAW,aAAc,OAAO,IAAoC,KAAA;GAEzF,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MAAM,aAAa,KAAK,qBAAqB;GAGzD,OAAO;EACT;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,7 +1,7 @@
-import { t as Wormhole } from "../types-DHysnZE3.js";
+import { n as Wormhole, t as DeepReadonly } from "../types-Q2gaO_N_.js";
 
 //#region src/react/index.d.ts
-declare function useWormhole<T>(wormhole: Wormhole<T>): T;
+declare function useWormhole<T>(wormhole: Wormhole<T>): DeepReadonly<T>;
 //#endregion
 export { useWormhole };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/react/index.ts"],"mappings":";;;iBAGgB,WAAA,IAAe,QAAA,EAAU,QAAA,CAAS,CAAA,IAAK,CAAA"}
+{"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.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/react/index.ts"],"sourcesContent":["import { useSyncExternalStore } from 'react';\nimport type { Wormhole } from '../types.js';\n\nexport function useWormhole<T>(wormhole: Wormhole<T>): T {\n  return useSyncExternalStore(wormhole.subscribe, wormhole.get, wormhole.get);\n}\n"],"mappings":";;AAGA,SAAgB,YAAe,UAA0B;CACvD,OAAO,qBAAqB,SAAS,WAAW,SAAS,KAAK,SAAS,GAAG;AAC5E"}
+{"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,7 +1,24 @@
-import { t as Wormhole } from "./types-DHysnZE3.js";
+import { n as Wormhole, t as DeepReadonly } from "./types-Q2gaO_N_.js";
 
 //#region src/server.d.ts
-declare function open<T, R>(wh: Wormhole<T>, data: T, fn: () => R): R;
+/** One [wormhole, data] pair per element — data is checked against its own wormhole's T. */
+type WormholeEntries<Ts extends readonly unknown[]> = { [K in keyof Ts]: readonly [Wormhole<Ts[K]>, DeepReadonly<Ts[K]>] };
+/**
+ * Open a wormhole for the duration of `fn` — `wormhole.get()` returns `data`
+ * anywhere in the async execution rooted at `fn`.
+ */
+declare function open<T, R>(wormhole: Wormhole<T>, data: DeepReadonly<T>, fn: () => R): R;
+/**
+ * Open several wormholes at once for the duration of `fn`.
+ *
+ * ```typescript
+ * return open([
+ *   [cartStore, cart],
+ *   [sessionStore, session],
+ * ], () => next());
+ * ```
+ */
+declare function open<Ts extends readonly unknown[], R>(entries: readonly [...WormholeEntries<Ts>], fn: () => R): R;
 //#endregion
 export { open };
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","names":[],"sources":["../src/server.ts"],"mappings":";;;iBAKgB,IAAA,OAAW,EAAA,EAAI,QAAA,CAAS,CAAA,GAAI,IAAA,EAAM,CAAA,EAAG,EAAA,QAAU,CAAA,GAAI,CAAA"}
+{"version":3,"file":"server.d.ts","names":[],"sources":["../src/server.ts"],"mappings":";;;;KAIK,eAAA,gDACS,EAAA,aAAe,QAAA,CAAS,EAAA,CAAG,CAAA,IAAK,YAAA,CAAa,EAAA,CAAG,CAAA;;;;;iBAa9C,IAAA,OAAW,QAAA,EAAU,QAAA,CAAS,CAAA,GAAI,IAAA,EAAM,YAAA,CAAa,CAAA,GAAI,EAAA,QAAU,CAAA,GAAI,CAAA;;;;;;;;;;;iBAWvE,IAAA,mCAAuC,OAAA,eAAsB,eAAA,CAAgB,EAAA,IAAM,EAAA,QAAU,CAAA,GAAI,CAAA"}

package/dist/server.js

@@ -1,14 +1,14 @@
 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);
+const als = globalThis[Symbol.for("@astroscope/wormhole/als")] ??= new AsyncLocalStorage();
+function open(...args) {
+	const [entries, fn] = Array.isArray(args[0]) ? args : [[[args[0], args[1]]], args[2]];
+	const ctx = new Map(als.getStore());
+	for (const [wormhole, data] of entries) {
+		ctx.set(wormhole.key, data);
+		globalThis[wormhole.key] ??= () => als.getStore()?.get(wormhole.key);
 	}
-	globalThis[wh.key] = () => als.getStore();
-	return als.run(data, fn);
+	return als.run(ctx, fn);
 }
 //#endregion
 export { open };

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\nimport type { Wormhole } from './types.js';\n\nconst stores = new Map<string, AsyncLocalStorage<unknown>>();\n\nexport function open<T, R>(wh: Wormhole<T>, data: T, fn: () => R): R {\n  let als = stores.get(wh.key) as AsyncLocalStorage<T> | undefined;\n\n  if (!als) {\n    als = new AsyncLocalStorage<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,MAAS,IAAgB;CACnE,IAAI,MAAM,OAAO,IAAI,GAAG,GAAG;CAE3B,IAAI,CAAC,KAAK;EACR,MAAM,IAAI,kBAAqB;EAC/B,OAAO,IAAI,GAAG,KAAK,GAAiC;CACtD;CAEA,WAAoB,GAAG,aAAa,IAAK,SAAS;CAElD,OAAO,IAAI,IAAI,MAAM,EAAE;AACzB"}
+{"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\n/** One [wormhole, data] pair per element — data is checked against its own wormhole's T. */\ntype WormholeEntries<Ts extends readonly unknown[]> = {\n  [K in keyof Ts]: readonly [Wormhole<Ts[K]>, DeepReadonly<Ts[K]>];\n};\n\n// a single ALS holds an immutable map of all open wormholes; keyed on globalThis\n// so the vite-runner and native module instances share one context\nconst als: AsyncLocalStorage<ReadonlyMap<string, unknown>> = ((globalThis as any)[\n  Symbol.for('@astroscope/wormhole/als')\n] ??= new AsyncLocalStorage());\n\n/**\n * Open a wormhole for the duration of `fn` — `wormhole.get()` returns `data`\n * anywhere in the async execution rooted at `fn`.\n */\nexport function open<T, R>(wormhole: Wormhole<T>, data: DeepReadonly<T>, fn: () => R): R;\n/**\n * Open several wormholes at once for the duration of `fn`.\n *\n * ```typescript\n * return open([\n *   [cartStore, cart],\n *   [sessionStore, session],\n * ], () => next());\n * ```\n */\nexport function open<Ts extends readonly unknown[], R>(entries: readonly [...WormholeEntries<Ts>], fn: () => R): R;\nexport function open(...args: unknown[]): unknown {\n  const [entries, fn] = (Array.isArray(args[0]) ? args : [[[args[0], args[1]]], args[2]]) as [\n    readonly (readonly [Wormhole<unknown>, unknown])[],\n    () => unknown,\n  ];\n\n  const ctx = new Map(als.getStore());\n\n  for (const [wormhole, data] of entries) {\n    ctx.set(wormhole.key, data);\n\n    (globalThis as any)[wormhole.key] ??= () => als.getStore()?.get(wormhole.key);\n  }\n\n  return als.run(ctx, fn);\n}\n"],"mappings":";;AAUA,MAAM,MAAwD,WAC5D,OAAO,IAAI,0BAA0B,OACjC,IAAI,kBAAkB;AAkB5B,SAAgB,KAAK,GAAG,MAA0B;CAChD,MAAM,CAAC,SAAS,MAAO,MAAM,QAAQ,KAAK,EAAE,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,KAAK,EAAE,CAAC,GAAG,KAAK,EAAE;CAKrF,MAAM,MAAM,IAAI,IAAI,IAAI,SAAS,CAAC;CAElC,KAAK,MAAM,CAAC,UAAU,SAAS,SAAS;EACtC,IAAI,IAAI,SAAS,KAAK,IAAI;EAE1B,WAAoB,SAAS,eAAe,IAAI,SAAS,CAAC,EAAE,IAAI,SAAS,GAAG;CAC9E;CAEA,OAAO,IAAI,IAAI,KAAK,EAAE;AACxB"}

package/dist/types-Q2gaO_N_.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<in out 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-Q2gaO_N_.d.ts.map

package/dist/types-Q2gaO_N_.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-Q2gaO_N_.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;;;;;;;;;;UAaW,QAAA;EAAA,SACN,IAAA;EAAA,SACA,GAAA;EACT,GAAA,IAAO,YAAA,CAAa,CAAA;EAjBwB;;;;EAsB5C,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.3.0",
+  "version": "1.1.0",
   "description": "Share dynamic server data with React islands and client scripts — typed, reactive",
   "type": "module",
   "main": "./dist/index.js",

package/src/astro/WormholeScript.astro

@@ -4,12 +4,20 @@ interface Props {
 }
 
 const { wormhole } = Astro.props;
-const data = wormhole.get();
+
+let data: unknown;
+
+try {
+  data = wormhole.get();
+} catch {
+  data = undefined;
+}
+
 const key = wormhole.key;
 ---
 
 {
-  data ? (
+  data !== undefined ? (
     <script is:inline define:vars={{ data, key }}>
       globalThis[key] = function(){return data;}
     </script>

package/dist/types-DHysnZE3.d.ts

@@ -1,21 +0,0 @@
-//#region src/types.d.ts
-/**
- * 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;
-}
-//#endregion
-export { Wormhole as t };
-//# sourceMappingURL=types-DHysnZE3.d.ts.map

package/dist/types-DHysnZE3.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types-DHysnZE3.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;AAMA;;;;;UAAiB,QAAA;EAAA,SACN,IAAA;EAAA,SACA,GAAA;EACT,GAAA,IAAO,CAAA;EAFE;;;;EAOT,GAAA,CAAI,IAAA,EAAM,CAAA;EACV,SAAA,CAAU,EAAA,GAAK,IAAA,EAAM,CAAA;AAAA"}