effect-atom-tanstack-solid-router 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 [these people](https://github.com/carloitaben/effect-atom-tanstack-router/graphs/contributors)
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# effect-atom-tanstack-solid-router
+
+TanStack Router SSR hydration integration for Effect Atom, mirroring `@tanstack/router-ssr-query-core`.
+
+## Usage
+
+First, add `AtomRegistry` to your root route context.
+
+```ts
+// src/routes/__root.tsx
+import { createRootRouteWithContext } from "@tanstack/solid-router"
+import type { AtomRegistry } from "effect/unstable/reactivity/AtomRegistry"
+
+export const Route = createRootRouteWithContext<{
+  registry: AtomRegistry
+}>()({
+  // ...
+})
+```
+
+Then, setup the atom registry and the integration.
+
+```ts
+// src/router.tsx
+import { createRouter } from "@tanstack/solid-router"
+import { setupRouterAtomIntegration } from "effect-atom-tanstack-solid-router"
+import * as AtomRegistry from "effect/unstable/reactivity/AtomRegistry"
+
+export function getRouter() {
+  const registry = AtomRegistry.make({ scheduleTask })
+
+  const router = createRouter({
+    context: { registry },
+    // ...
+  })
+
+  setupRouterAtomIntegration({
+    router,
+    registry,
+  })
+
+  return router
+}
+```
+
+There are two ways to interact with an atom, depending on whether the loader needs the data.
+
+### Streaming
+
+Kick off loading without waiting. The atom starts fetching on the server, then streams to the client while the component suspends on it. Use this when the loader itself doesn't need the value.
+
+```ts
+loader: ({ context }) => {
+  context.registry.get(postsAtom)
+}
+```
+
+### Blocking
+
+Await the atom and return data from the loader. Use this when the loader needs the value.
+
+```ts
+import { awaitAtomSettled } from "effect-atom-tanstack-solid-router"
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult"
+
+loader: async ({ params: { postId }, context }) => {
+  const data = await awaitAtomSettled(context.registry, postAtom(postId))
+
+  return {
+    title: AsyncResult.getOrThrow(data).title,
+  }
+}
+```
+
+> [!WARNING]
+> Atoms must be marked `Atom.serializable()` and require `Atom.keepAlive` for them to be picked up by the integration.

package/dist/index.d.mts

@@ -0,0 +1,27 @@
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+import * as Atom from "effect/unstable/reactivity/Atom";
+import { AnyRouter } from "@tanstack/solid-router";
+import { AtomRegistry } from "effect/unstable/reactivity/AtomRegistry";
+//#region src/index.d.ts
+type DehydratedAtomEntry = {
+  readonly key: string;
+  readonly value: unknown;
+};
+type DehydratedRouterAtomState = {
+  atom: {
+    readonly initial?: Array<DehydratedAtomEntry>;
+    readonly stream: ReadableStream<Array<DehydratedAtomEntry>>;
+  };
+};
+type RouterAtomIntegrationOptions<TRouter extends AnyRouter> = {
+  readonly router: TRouter;
+  readonly registry: AtomRegistry;
+  readonly wrapRegistry?: boolean;
+};
+declare function setupRouterAtomIntegration<TRouter extends AnyRouter>(opts: RouterAtomIntegrationOptions<TRouter>): void;
+/**
+ * Waits for an atom to leave `AsyncResult.Initial` before resolving.
+ */
+declare const awaitAtomSettled: <A, E>(registry: AtomRegistry, atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Promise<AsyncResult.AsyncResult<A, E>>;
+//#endregion
+export { DehydratedRouterAtomState, RouterAtomIntegrationOptions, awaitAtomSettled, setupRouterAtomIntegration };

package/dist/index.mjs

@@ -0,0 +1,141 @@
+import { RegistryContext } from "@effect/atom-solid";
+import { isServer } from "@tanstack/router-core/isServer";
+import * as Option from "effect/Option";
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+import * as Atom from "effect/unstable/reactivity/Atom";
+import { createComponent } from "solid-js";
+//#region src/index.ts
+const isSettled = (value) => !AsyncResult.isAsyncResult(value) || !AsyncResult.isInitial(value);
+const encode = (atom, value) => atom[Atom.SerializableTypeId].encode(value);
+const keyOf = (atom) => atom[Atom.SerializableTypeId].key;
+function setupRouterAtomIntegration(opts) {
+	const { router, registry } = opts;
+	if (opts.wrapRegistry !== false) {
+		const originalWrap = router.options.Wrap;
+		router.options.Wrap = (props) => createComponent(RegistryContext.Provider, {
+			value: registry,
+			get children() {
+				return originalWrap ? originalWrap(props) : props.children;
+			}
+		});
+	}
+	if (isServer || router.isServer) {
+		const originalDehydrate = router.options.dehydrate;
+		router.options.dehydrate = async () => {
+			const originalDehydrated = await originalDehydrate?.();
+			const initial = [];
+			const sentKeys = /* @__PURE__ */ new Set();
+			for (const node of registry.getNodes().values()) {
+				if (!Atom.isSerializable(node.atom)) continue;
+				const value = node.value();
+				if (!isSettled(value)) continue;
+				const key = keyOf(node.atom);
+				initial.push({
+					key,
+					value: encode(node.atom, value)
+				});
+				sentKeys.add(key);
+			}
+			let controller;
+			const stream = new ReadableStream({ start(c) {
+				controller = c;
+			} });
+			let closed = false;
+			let pending;
+			const flushPending = () => {
+				const batch = pending;
+				pending = void 0;
+				if (!batch || batch.size === 0) return;
+				try {
+					controller.enqueue(Array.from(batch.values()));
+				} catch {}
+			};
+			const schedule = (entry) => {
+				if (closed || sentKeys.has(entry.key)) return;
+				sentKeys.add(entry.key);
+				if (!pending) {
+					pending = /* @__PURE__ */ new Map();
+					queueMicrotask(flushPending);
+				}
+				pending.set(entry.key, entry);
+			};
+			const unsubscribes = /* @__PURE__ */ new Set();
+			const watch = (atom) => {
+				if (!Atom.isSerializable(atom) || sentKeys.has(keyOf(atom))) return;
+				const unsubscribe = registry.subscribe(atom, (value) => {
+					if (!isSettled(value)) return;
+					unsubscribe();
+					unsubscribes.delete(unsubscribe);
+					schedule({
+						key: keyOf(atom),
+						value: encode(atom, value)
+					});
+				});
+				unsubscribes.add(unsubscribe);
+			};
+			for (const node of registry.getNodes().values()) watch(node.atom);
+			const originalOnNodeAdded = registry.onNodeAdded;
+			registry.onNodeAdded = (node) => {
+				originalOnNodeAdded?.(node);
+				watch(node.atom);
+			};
+			const finalize = () => {
+				if (closed) return;
+				closed = true;
+				flushPending();
+				registry.onNodeAdded = originalOnNodeAdded;
+				for (const unsubscribe of unsubscribes) unsubscribe();
+				unsubscribes.clear();
+				try {
+					controller.close();
+				} catch {}
+			};
+			Option.getOrThrowWith(Option.fromUndefinedOr(router.serverSsr), () => /* @__PURE__ */ new Error("Router SSR is unavailable. Call setupRouterAtomIntegration only after TanStack Start initializes server SSR.")).onRenderFinished(finalize);
+			router.serverSsrLifecycle = {
+				...router.serverSsrLifecycle,
+				onServerSsrAttach: [...router.serverSsrLifecycle?.onServerSsrAttach ?? [], (serverSsr) => serverSsr.onCleanup(finalize)]
+			};
+			return {
+				...originalDehydrated,
+				atom: {
+					...initial.length > 0 && { initial },
+					stream
+				}
+			};
+		};
+		return;
+	}
+	const originalHydrate = router.options.hydrate;
+	router.options.hydrate = async (dehydrated) => {
+		await originalHydrate?.(dehydrated);
+		const atomState = dehydrated?.atom;
+		if (!atomState) return;
+		if (atomState.initial) for (const entry of atomState.initial) registry.setSerializable(entry.key, entry.value);
+		const reader = atomState.stream.getReader();
+		const pump = ({ done, value }) => {
+			if (done) return;
+			for (const entry of value) registry.setSerializable(entry.key, entry.value);
+			return reader.read().then(pump);
+		};
+		reader.read().then(pump).catch((error) => {
+			console.error("[atom-start-ssr] error reading atom stream:", error);
+		});
+	};
+}
+/**
+* Waits for an atom to leave `AsyncResult.Initial` before resolving.
+*/
+const awaitAtomSettled = (registry, atom) => {
+	const current = registry.get(atom);
+	if (!AsyncResult.isInitial(current)) return Promise.resolve(current);
+	return new Promise((resolve) => {
+		const unsubscribe = registry.subscribe(atom, (value) => {
+			if (!AsyncResult.isInitial(value)) {
+				resolve(value);
+				unsubscribe();
+			}
+		});
+	});
+};
+//#endregion
+export { awaitAtomSettled, setupRouterAtomIntegration };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "effect-atom-tanstack-solid-router",
+  "version": "0.1.0",
+  "description": "TanStack Router SSR hydration integration for Effect Atom",
+  "homepage": "https://github.com/carloitaben/effect-atom-tanstack-router#readme",
+  "bugs": "https://github.com/carloitaben/effect-atom-tanstack-router/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carloitaben/effect-atom-tanstack-router.git"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@effect/atom-solid": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@tanstack/router-core": "^1.171.27",
+    "@tanstack/solid-router": "^1.170.30",
+    "@types/react": "^19.0.8",
+    "effect": "4.0.0-rc.112",
+    "solid-js": "^1.9.15",
+    "tsdown": "^0.22.14",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "peerDependencies": {
+    "@effect/atom-solid": ">=4.0.0-beta",
+    "@tanstack/router-core": "^1.171.27",
+    "@tanstack/solid-router": ">=1.170.30",
+    "effect": ">=4.0.0-beta",
+    "solid-js": ">=1.9.0 <2.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest",
+    "typecheck": "tsc"
+  }
+}