@astroscope/wormhole 0.1.0

package/README.md

@@ -0,0 +1,238 @@
+# @astroscope/wormhole
+
+> **Note:** This package is in active development. APIs may change between versions.
+
+Share dynamic server data with React islands and client scripts — typed, reactive.
+
+## Why this library?
+
+Astro recommends [nanostores](https://docs.astro.build/en/recipes/sharing-state/) for sharing state between islands, but nanostores are client-only — there's no built-in way to hydrate them with server data during SSR.
+
+`@astroscope/wormhole` bridges this gap: populate data in middleware, read it in Astro frontmatter, React islands, or `<script>` blocks — same typed API on server and client. Multiple wormholes per page, reactive updates across all consumers, zero configuration.
+
+**Typical use cases:**
+
+- Shopping cart state shared across header badge, product cards, and checkout
+- Authenticated user / session data available in all islands
+- Feature flags resolved on the server, consumed by client components
+- Server-loaded configuration (theme, locale, permissions) bridged to the UI
+- Any request-scoped data that multiple disconnected islands need to read
+
+## Examples
+
+See the [demo/wormhole](../../demo/wormhole) directory for a working example.
+
+## Installation
+
+```bash
+npm install @astroscope/wormhole
+```
+
+## Usage
+
+### 1. Define a wormhole
+
+Create a shared file imported by both server and client code:
+
+```ts
+// src/wormholes.ts
+import { defineWormhole } from '@astroscope/wormhole';
+
+export type UserState = {
+  user: string;
+  role: string;
+};
+
+export const userState = defineWormhole<UserState>('user');
+```
+
+### 2. Populate in middleware
+
+Use `open()` from the server entry point to provide data during request handling:
+
+```ts
+// src/middleware.ts
+import { open } from '@astroscope/wormhole/server';
+import { defineMiddleware } from 'astro:middleware';
+import { userState } from './wormholes';
+
+export const onRequest = defineMiddleware((ctx, next) => {
+  const data = { user: 'Alice', role: 'admin' };
+
+  return open(userState, data, () => next());
+});
+```
+
+`open()` uses `AsyncLocalStorage` under the hood — each request gets its own isolated data.
+
+### 3. Bridge to the client
+
+Add `<WormholeScript>` to your layout to serialize the data into an inline script:
+
+```astro
+---
+import { WormholeScript } from '@astroscope/wormhole/astro';
+import { userState } from '../wormholes';
+---
+
+<html>
+  <head>
+    <WormholeScript wormhole={userState} />
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+### 4. Read in components
+
+#### Astro frontmatter (SSR)
+
+```astro
+---
+import { userState } from '../wormholes';
+
+const { user } = userState.get();
+---
+
+<p>Hello, {user}</p>
+```
+
+#### React islands
+
+```tsx
+import { useWormhole } from '@astroscope/wormhole/react';
+import { userState } from '../wormholes';
+
+export function UserBadge() {
+  const { user, role } = useWormhole(userState);
+
+  return (
+    <span>
+      {user} ({role})
+    </span>
+  );
+}
+```
+
+#### Astro `<script>` blocks
+
+```astro
+<p>User: <strong id="user">-</strong></p>
+
+<script>
+  import { userState } from '../wormholes';
+
+  document.getElementById('user')!.textContent = userState.get().user;
+
+  userState.subscribe((data) => {
+    document.getElementById('user')!.textContent = data.user;
+  });
+</script>
+```
+
+### 5. Update from the client
+
+Call `set()` to update the wormhole — all `useWormhole()` hooks and `subscribe()` callbacks react immediately:
+
+```tsx
+import { useWormhole } from '@astroscope/wormhole/react';
+import { actions } from 'astro:actions';
+import { userState } from '../wormholes';
+
+export function RoleToggle() {
+  const { user, role } = useWormhole(userState);
+
+  async function toggle() {
+    const newRole = role === 'admin' ? 'viewer' : 'admin';
+    const result = await actions.updateRole({ role: newRole });
+
+    if (!result.error) {
+      userState.set(result.data);
+    }
+  }
+
+  return (
+    <button onClick={toggle}>
+      {user}: {role}
+    </button>
+  );
+}
+```
+
+## API
+
+### `defineWormhole<T>(name)`
+
+Creates a typed wormhole channel. The returned object is universal — works on both server and client.
+
+```ts
+import { defineWormhole } from '@astroscope/wormhole';
+
+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.subscribe(fn)` | Listen for changes, returns unsubscribe function                                                    |
+| `wh.name`          | The wormhole name                                                                                   |
+| `wh.key`           | The internal `globalThis` key                                                                       |
+
+### `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.
+
+```ts
+import { open } from '@astroscope/wormhole/server';
+
+return open(myWormhole, { count: 0 }, () => next());
+```
+
+### `useWormhole(wh)` <sub>React only</sub>
+
+React hook that reads the wormhole and re-renders on changes. Uses `useSyncExternalStore` internally.
+
+```tsx
+import { useWormhole } from '@astroscope/wormhole/react';
+
+const data = useWormhole(myWormhole);
+```
+
+### `<WormholeScript wormhole={wh} />` <sub>Astro only</sub>
+
+Serializes the current wormhole value into an inline `<script>` tag for client hydration.
+
+```astro
+import {WormholeScript} from '@astroscope/wormhole/astro';
+
+<WormholeScript wormhole={myWormhole} />
+```
+
+## How it works
+
+1. **Middleware** calls `open(wh, data, next)` — stores data in `AsyncLocalStorage` and sets `globalThis[key]` to read from it
+2. **`<WormholeScript>`** calls `wh.get()` during SSR, serializes the result into `<script is:inline>globalThis[key] = function(){return data;}</script>`
+3. **Client** calls `wh.get()` — reads from `globalThis[key]()` (the serialized getter)
+4. **`set()`** updates a local store and notifies all subscribers — `useWormhole()` hooks and `subscribe()` callbacks re-render/fire
+
+## Monorepo note
+
+When using this package from a workspace in a monorepo, add `resolve.dedupe` to your Vite config to prevent duplicate React instances:
+
+```ts
+// astro.config.ts
+export default defineConfig({
+  vite: {
+    resolve: {
+      dedupe: ['react', 'react-dom'],
+    },
+  },
+});
+```
+
+## License
+
+MIT

package/dist/define.d.ts

@@ -0,0 +1,5 @@
+import { W as Wormhole } from './types-DkH89ULF.js';
+
+declare function defineWormhole<T>(name: string): Wormhole<T>;
+
+export { Wormhole, defineWormhole };

package/dist/define.js

@@ -0,0 +1,29 @@
+// src/define.ts
+function defineWormhole(name) {
+  const key = `__wormhole_${name}__`;
+  let store;
+  const listeners = /* @__PURE__ */ new Set();
+  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) {
+      store = data;
+      for (const fn of listeners) fn(data);
+    },
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    }
+  };
+}
+export {
+  defineWormhole
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { W as Wormhole } from './types-DkH89ULF.js';
+
+declare function defineWormhole<T>(name: string): Wormhole<T>;
+
+export { Wormhole, defineWormhole };

package/dist/index.js

@@ -0,0 +1,29 @@
+// src/define.ts
+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) {
+      store = data;
+      for (const fn of listeners) fn(data);
+    },
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    }
+  };
+}
+export {
+  defineWormhole
+};

package/dist/react/index.d.ts

@@ -0,0 +1,5 @@
+import { W as Wormhole } from '../types-DkH89ULF.js';
+
+declare function useWormhole<T>(wormhole: Wormhole<T>): T;
+
+export { useWormhole };

package/dist/react/index.js

@@ -0,0 +1,8 @@
+// src/react/index.ts
+import { useSyncExternalStore } from "react";
+function useWormhole(wormhole) {
+  return useSyncExternalStore(wormhole.subscribe, wormhole.get, wormhole.get);
+}
+export {
+  useWormhole
+};

package/dist/react.d.ts

@@ -0,0 +1,5 @@
+import { W as Wormhole } from './types-DkH89ULF.js';
+
+declare function useWormhole<T>(wh: Wormhole<T>): T;
+
+export { useWormhole };

package/dist/react.js

@@ -0,0 +1,8 @@
+// src/react.ts
+import { useSyncExternalStore } from "react";
+function useWormhole(wh) {
+  return useSyncExternalStore(wh.subscribe, wh.get, wh.get);
+}
+export {
+  useWormhole
+};

package/dist/server.d.ts

@@ -0,0 +1,5 @@
+import { W as Wormhole } from './types-DkH89ULF.js';
+
+declare function open<T, R>(wh: Wormhole<T>, data: T, fn: () => R): R;
+
+export { open };

package/dist/server.js

@@ -0,0 +1,15 @@
+// src/server.ts
+import { AsyncLocalStorage } from "async_hooks";
+var 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);
+}
+export {
+  open
+};

package/dist/types-DkH89ULF.d.ts

@@ -0,0 +1,9 @@
+interface Wormhole<T> {
+    readonly name: string;
+    readonly key: string;
+    get(): T;
+    set(data: T): void;
+    subscribe(fn: (data: T) => void): () => void;
+}
+
+export type { Wormhole as W };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@astroscope/wormhole",
+  "version": "0.1.0",
+  "description": "Share dynamic server data with React islands and client scripts — typed, reactive",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./astro": {
+      "import": "./src/astro/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src/astro"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smnbbrv/astroscope.git",
+    "directory": "packages/wormhole"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "ssr",
+    "state",
+    "islands",
+    "react"
+  ],
+  "author": "smnbbrv",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/smnbbrv/astroscope/issues"
+  },
+  "homepage": "https://github.com/smnbbrv/astroscope/tree/main/packages/wormhole#readme",
+  "scripts": {
+    "build": "tsup src/index.ts src/server.ts src/react/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint 'src/**/*.{ts,tsx}'",
+    "lint:fix": "eslint 'src/**/*.{ts,tsx}' --fix"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.13",
+    "astro": "^5.17.1",
+    "react": "^19.2.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}

package/src/astro/WormholeScript.astro

@@ -0,0 +1,21 @@
+---
+interface Props {
+  wormhole: { readonly name: string; readonly key: string; get(): unknown };
+}
+
+const { wormhole } = Astro.props;
+const data = wormhole.get();
+const key = wormhole.key;
+---
+
+{
+  data ? (
+    <script is:inline define:vars={{ data, key }}>
+      globalThis[key] = function(){return data;}
+    </script>
+  ) : (
+    <script is:inline define:vars={{ wormholeName: wormhole.name }}>
+      console.error(`[wormhole] "${wormholeName}" has no data — is the middleware configured?`);
+    </script>
+  )
+}

package/src/astro/index.ts

@@ -0,0 +1,2 @@
+// @ts-expect-error: Astro types
+export { default as WormholeScript } from './WormholeScript.astro';