raf-effect-atom 0.0.0-stage → 0.0.0

package/dist/Waterfalls.mjs

@@ -0,0 +1,107 @@
+"use client";
+import { get } from "./internal/pending.mjs";
+import { hydrated } from "./Hydration.mjs";
+import { keyOf } from "./internal/leases.mjs";
+import { prefetch } from "./Loader.mjs";
+import { ModeContext, isStarted } from "./internal/waterfalls.mjs";
+import * as Predicate from "effect/Predicate";
+import * as Effect from "effect/Effect";
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+import { RegistryContext } from "@effect/atom-react";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+// src/Waterfalls.tsx
+/**
+* Request waterfalls: the escape hatch for atoms only a render can start,
+* and the development check that finds the others.
+*
+* @stability unstable
+* @since 0.1.0
+*/
+/**
+* Sets how `useAtomResult` reports request waterfalls in the tree below.
+*
+* **When to use**
+*
+* Put it in the root layout, around the app. `"throw"` turns every atom a
+* component starts on its own into an error in development, which a person
+* or a coding agent can't miss.
+*
+* **Details**
+*
+* Production builds don't check: the check sits behind
+* `process.env.NODE_ENV !== "production"`, which bundlers replace at build
+* time, so it's left out of the bundle, and this component renders only its
+* children.
+*
+* **Example**
+*
+* ```tsx
+* import { WaterfallDetection } from "raf-effect-atom"
+*
+* function App(props: { readonly children: React.ReactNode }) {
+*   return <WaterfallDetection mode="throw">{props.children}</WaterfallDetection>
+* }
+* ```
+*
+* @stability unstable
+* @category components
+* @since 0.1.0
+*/
+const WaterfallDetection = (props) => process.env.NODE_ENV === "production" ? props.children : /* @__PURE__ */ jsx(ModeContext, {
+	value: props.mode,
+	children: props.children
+});
+/**
+* Starts an atom during render and returns it, for an input only a render
+* knows, such as a debounced search query.
+*
+* **When to use**
+*
+* As an escape hatch, when no loader, server component or event handler can
+* start the atom: each call is a request waterfall, a round trip after the
+* render that found the input. Prefer putting the state that picks the data
+* in the URL, where a loader reads it, or a procedure that resolves the input
+* on the server. Searching a codebase for `useWaterfall` lists its
+* waterfalls.
+*
+* **Details**
+*
+* - Starts the atom like `Loader.prefetch`, with a lease that
+*   `useAtomResult` takes over when the component mounts, and only if
+*   nothing started it yet: re-renders start nothing.
+* - A result the server is still streaming is awaited by `useAtomResult`,
+*   not started again.
+* - `useAtomResult` doesn't report an atom started this way.
+*
+* **Gotchas**
+*
+* Pass it the atom a loader would start, inside an error boundary's `wrap`:
+* `useAtomResult(boundary.wrap(useWaterfall(user(id))))`. The wrapper isn't
+* serializable, so the server couldn't send it to the browser.
+*
+* **Example**
+*
+* ```tsx
+* import { useAtomResult, useWaterfall } from "raf-effect-atom"
+*
+* function Author(props: { readonly userId: UserId }) {
+*   const result = useAtomResult(useWaterfall(user(props.userId)))
+*   // ...
+* }
+* ```
+*
+* @see {@link WaterfallDetection} for the development check it opts out of
+*
+* @stability unstable
+* @category hooks
+* @since 0.1.0
+*/
+const useWaterfall = (atom) => {
+	const registry = React.useContext(RegistryContext);
+	const target = hydrated(atom);
+	const key = keyOf(target);
+	if (!(Predicate.isString(key) && get(registry, key) !== void 0) && !isStarted(registry, target)) Effect.runSync(Effect.provideService(prefetch(atom), AtomRegistry.AtomRegistry, registry));
+	return atom;
+};
+export { WaterfallDetection, useWaterfall };

package/dist/_virtual/_rolldown/runtime.mjs

@@ -0,0 +1,12 @@
+// \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+export { __exportAll };

package/dist/index.d.mts

@@ -0,0 +1,7 @@
+import { Loader_d_exports } from "./Loader.mjs";
+import { HydrationBoundary, HydrationBoundaryProps } from "./ReactHydration.mjs";
+import { Hydration_d_exports } from "./Hydration.mjs";
+import { RequestRegistry_d_exports } from "./RequestRegistry.mjs";
+import { useAtomResult } from "./Hooks.mjs";
+import { WaterfallDetection, WaterfallMode, useWaterfall } from "./Waterfalls.mjs";
+export { Hydration_d_exports as Hydration, HydrationBoundary, HydrationBoundaryProps, Loader_d_exports as Loader, RequestRegistry_d_exports as RequestRegistry, WaterfallDetection, WaterfallMode, useAtomResult, useWaterfall };

package/dist/index.mjs

@@ -0,0 +1,7 @@
+import { Hydration_exports } from "./Hydration.mjs";
+import { RequestRegistry_exports } from "./RequestRegistry.mjs";
+import { Loader_exports } from "./Loader.mjs";
+import { useAtomResult } from "./Hooks.mjs";
+import { HydrationBoundary } from "./ReactHydration.mjs";
+import { WaterfallDetection, useWaterfall } from "./Waterfalls.mjs";
+export { Hydration_exports as Hydration, HydrationBoundary, Loader_exports as Loader, RequestRegistry_exports as RequestRegistry, WaterfallDetection, useAtomResult, useWaterfall };

package/dist/internal/development.mjs

@@ -0,0 +1,6 @@
+import * as Effect from "effect/Effect";
+import * as Config from "effect/Config";
+// src/internal/development.ts
+/** Whether `NODE_ENV` isn't `production`, read through `Config`. */
+const isDevelopment = Config.String("NODE_ENV").pipe(Config.withDefault("development"), Effect.map((env) => env !== "production"), Effect.orElseSucceed(() => true));
+export { isDevelopment };

package/dist/internal/leases.mjs

@@ -0,0 +1,39 @@
+import * as Atom from "effect/reactivity/Atom";
+// src/internal/leases.ts
+const leases = /* @__PURE__ */ new WeakMap();
+/** The registry's key for an atom: its serialization key, or the atom. */
+const keyOf = (atom) => Atom.isSerializable(atom) ? atom[Atom.SerializableTypeId].key : atom;
+/**
+* Mounts `atom` until `release`, or until `ttl` milliseconds pass. Taking a
+* lease the atom already has restarts its timer.
+*/
+const take = (registry, atom, ttl) => {
+	let byKey = leases.get(registry);
+	if (byKey === void 0) {
+		byKey = /* @__PURE__ */ new Map();
+		leases.set(registry, byKey);
+	}
+	const key = keyOf(atom);
+	let lease = byKey.get(key);
+	if (lease === void 0) {
+		const unmount = registry.mount(atom);
+		const owner = byKey;
+		const created = {
+			release: () => {
+				clearTimeout(created.timer);
+				owner.delete(key);
+				unmount();
+			},
+			timer: void 0
+		};
+		byKey.set(key, created);
+		lease = created;
+	}
+	clearTimeout(lease.timer);
+	lease.timer = ttl === void 0 ? void 0 : setTimeout(lease.release, ttl);
+};
+/** Releases `atom`'s lease, if it has one. */
+const release = (registry, atom) => {
+	leases.get(registry)?.get(keyOf(atom))?.release();
+};
+export { keyOf, release, take };

package/dist/internal/next.mjs

@@ -0,0 +1,16 @@
+import { dehydrate as dehydrate$1 } from "../Hydration.mjs";
+import { make } from "../RequestRegistry.mjs";
+import { make as make$1 } from "../Loader.mjs";
+import * as React from "react";
+// src/internal/next.ts
+const getRegistry = React.cache(() => {
+	const registry = make();
+	React.cacheSignal()?.addEventListener("abort", () => registry.dispose(), { once: true });
+	return registry;
+});
+const getLoader = React.cache(() => make$1(getRegistry()));
+const prefetch = (atom) => getLoader().prefetch(atom);
+const ensure = (atom) => getLoader().ensure(atom);
+const fetch = (atom) => getLoader().fetch(atom);
+const dehydrate = () => dehydrate$1(getRegistry());
+export { dehydrate, ensure, fetch, getRegistry, prefetch };

package/dist/internal/pending.mjs

@@ -0,0 +1,75 @@
+import * as Hydration from "effect/reactivity/Hydration";
+import * as Predicate from "effect/Predicate";
+// src/internal/pending.ts
+const held = /* @__PURE__ */ new WeakMap();
+const pending = /* @__PURE__ */ new WeakMap();
+/** Each key's latest stream, kept once it settles. */
+const streams = /* @__PURE__ */ new WeakMap();
+/** The promise of a streamed result still on its way, if there is one. */
+const get = (registry, key) => pending.get(registry)?.get(key);
+/**
+* The promise of a key's streamed result, settled or not. A component that
+* suspended on it with `React.use` must call `React.use` again when React
+* retries it, or React reports a conditional `use`. Once settled, it's
+* marked fulfilled the way React marks the thenables it tracks, so `use`
+* returns at once instead of suspending again.
+*/
+const stream = (registry, key) => streams.get(registry)?.get(key);
+const hold = (registry, entry, result) => {
+	let entries = held.get(registry);
+	if (entries === void 0) {
+		entries = /* @__PURE__ */ new WeakSet();
+		held.set(registry, entries);
+	}
+	if (entries.has(entry)) return;
+	entries.add(entry);
+	let byKey = pending.get(registry);
+	if (byKey === void 0) {
+		byKey = /* @__PURE__ */ new Map();
+		pending.set(registry, byKey);
+	}
+	if (byKey.has(entry.key)) return;
+	let latest = streams.get(registry);
+	if (latest === void 0) {
+		latest = /* @__PURE__ */ new Map();
+		streams.set(registry, latest);
+	}
+	const owner = byKey;
+	const done = () => {
+		owner.delete(entry.key);
+	};
+	const fulfilled = () => {
+		Object.assign(promise, {
+			status: "fulfilled",
+			value: void 0
+		});
+	};
+	const promise = Promise.resolve(result).then((value) => {
+		done();
+		if (!Predicate.isSymbol(value)) {
+			const resolved = {
+				...entry,
+				resultPromise: void 0,
+				value
+			};
+			Hydration.hydrate(registry, [resolved]);
+		}
+		fulfilled();
+	}, () => {
+		done();
+		fulfilled();
+	});
+	owner.set(entry.key, promise);
+	latest.set(entry.key, promise);
+};
+/**
+* Holds back each streamed entry of `state` until its promise resolves, and
+* returns the settled ones.
+*/
+const split = (registry, state) => {
+	const settled = [];
+	for (const entry of Hydration.toValues(Array.from(state))) if (entry.resultPromise === void 0) settled.push(entry);
+	else hold(registry, entry, entry.resultPromise);
+	return settled;
+};
+export { get, split, stream };

package/dist/internal/registry.mjs

@@ -0,0 +1,16 @@
+import { make as make$1 } from "../RequestRegistry.mjs";
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+import { scheduleTask } from "@effect/atom-react";
+// src/internal/registry.ts
+const isServer = () => !("window" in globalThis);
+/** `@effect/atom-react`'s default registry keeps an unused atom this long. */
+const defaultIdleTTL = 400;
+/**
+* A request registry on the server, and in the browser a registry like
+* `@effect/atom-react`'s `RegistryProvider` makes.
+*/
+const make = (options) => isServer() ? make$1() : AtomRegistry.make({
+	defaultIdleTTL: options?.defaultIdleTTL ?? defaultIdleTTL,
+	scheduleTask
+});
+export { isServer, make };

package/dist/internal/sources.mjs

@@ -0,0 +1,14 @@
+// src/internal/sources.ts
+/** The registry each `dehydrate` result came from, while it's referenced. */
+const sources = /* @__PURE__ */ new WeakMap();
+const remember = (state, registry) => {
+	sources.set(state, registry);
+	return state;
+};
+/**
+* The registry `state` was dehydrated from, when it's the same object
+* `dehydrate` returned: during server rendering by a framework that passes
+* loader data to components without serializing it, such as React Router.
+*/
+const sourceOf = (state) => state === void 0 ? void 0 : sources.get(state);
+export { remember, sourceOf };

package/dist/internal/waterfalls.d.mts

@@ -0,0 +1,5 @@
+import "effect/reactivity/Atom";
+import "effect/reactivity/AtomRegistry";
+import "react";
+/** What a development read does when it starts an atom nothing started. */
+export type Mode = "off" | "throw" | "warn";

package/dist/internal/waterfalls.mjs

@@ -0,0 +1,83 @@
+import { keyOf } from "./leases.mjs";
+import * as Predicate from "effect/Predicate";
+import * as Option from "effect/Option";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+import * as React from "react";
+// src/internal/waterfalls.ts
+const ModeContext = React.createContext("warn");
+const docs = "https://raf-effect-atom.katt.dev/docs/request-waterfalls";
+/** Whether the registry has `atom`'s node, or a hydrated value for it. */
+const isStarted = (registry, atom) => {
+	const key = keyOf(atom);
+	return registry.getNodes().has(key) || Predicate.isString(key) && registry.preloadedSerializable.has(key);
+};
+const isLoading = (node) => {
+	const value = Option.getOrUndefined(node.valueOption());
+	return AsyncResult.isAsyncResult(value) && AsyncResult.isInitial(value);
+};
+/**
+* The nodes `registry.get` created that load on their own: `Initial`, with
+* no `Initial` parent. A derived atom over a source that is loading or
+* loaded isn't one, so reading through `Atom.map` or a wrapper over an atom
+* a loader started reports nothing.
+*/
+const startedLoading = (registry, atom, before) => {
+	const root = registry.getNodes().get(keyOf(atom));
+	const started = [];
+	const seen = /* @__PURE__ */ new Set();
+	const queue = root === void 0 ? [] : [root];
+	for (const node of queue) {
+		if (seen.has(node) || before.has(keyOf(node.atom))) continue;
+		seen.add(node);
+		if (isLoading(node) && !Array.from(node.parents).some(isLoading)) started.push(node);
+		queue.push(...node.parents);
+	}
+	return started;
+};
+const nameOf = (atom) => {
+	const key = keyOf(atom);
+	return atom.label?.[0] ?? (Predicate.isString(key) ? key : "an atom");
+};
+const message = (read, started) => `raf-effect-atom: rendering ${read === started ? `read ${read}` : `read ${read}, which started ${started}`} before anything else had started it, so its request waits for this render: a request waterfall. Start it before render, in the route's loader or the server component (atoms.prefetch or atoms.ensure). If the state that picks it, such as a page, a filter or an open dialog, isn't in the URL, put it there so the loader can. As escape hatches for state that can't be in the URL: start it in the event handler that changes the state (Loader.make(registry).prefetch), or, if its input only exists in render, read it with useAtomResult(useWaterfall(atom)). ${docs}`;
+const warned = /* @__PURE__ */ new WeakMap();
+/**
+* The nodes a read started in throw mode, with the error. React renders a
+* component that threw once more before it gives up, and that render finds
+* the node, so the error stays with the node.
+*/
+const thrown = /* @__PURE__ */ new WeakMap();
+/**
+* Reads `atom`, reporting by `mode` when the read starts an atom no loader,
+* server component, event handler or `useWaterfall` started. Development
+* only: callers skip it in production builds.
+*/
+const check = (registry, atom, mode) => {
+	if (mode === "off") return;
+	if (isStarted(registry, atom)) {
+		const node = registry.getNodes().get(keyOf(atom));
+		const error = mode === "throw" && node ? thrown.get(node) : void 0;
+		if (error !== void 0) throw error;
+		return;
+	}
+	const before = new Set(registry.getNodes().keys());
+	registry.get(atom);
+	const first = startedLoading(registry, atom, before)[0];
+	if (first === void 0) return;
+	const text = message(nameOf(atom), nameOf(first.atom));
+	if (mode === "throw") {
+		const error = new Error(text);
+		const node = registry.getNodes().get(keyOf(atom));
+		if (node !== void 0) thrown.set(node, error);
+		throw error;
+	}
+	let seen = warned.get(registry);
+	if (seen === void 0) {
+		seen = /* @__PURE__ */ new Set();
+		warned.set(registry, seen);
+	}
+	if (!seen.has(text)) {
+		seen.add(text);
+		console.warn(text);
+	}
+};
+export { ModeContext, check, isStarted };

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "raf-effect-atom",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Render-as-you-fetch for Effect Atom: start atoms from route loaders and stream them into the browser, typed failures intact",
+  "keywords": [
+    "effect",
+    "effect-atom",
+    "react",
+    "render-as-you-fetch",
+    "ssr",
+    "suspense"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "KATT",
+    "email": "alexander@n1s.se"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KATT/raf-effect-atom.git",
+    "directory": "packages/raf-effect-atom"
+  },
+  "homepage": "https://raf-effect-atom.katt.dev",
+  "bugs": {
+    "url": "https://github.com/KATT/raf-effect-atom/issues"
+  },
+  "files": [
+    "dist/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./next": "./dist/Next.mjs",
+    "./react-router": "./dist/ReactRouter.mjs",
+    "./tanstack-router": "./dist/TanStackRouter.mjs"
+  },
+  "peerDependencies": {
+    "@effect/atom-react": "^4.0.6",
+    "@tanstack/react-router": "^1.170.46",
+    "effect": "^4.0.6",
+    "react": "^19.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-router": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@effect/atom-react": "4.0.6",
+    "@effect/vitest": "4.0.6",
+    "@tanstack/react-router": "1.170.46",
+    "@testing-library/react": "16.3.3",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitest/coverage-v8": "5.0.5",
+    "effect": "4.0.6",
+    "effect-atom-boundary": "0.0.0",
+    "happy-dom": "21.0.4",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "react-error-boundary": "6.1.6",
+    "react-router": "8.5.0",
+    "react-server-dom-webpack": "19.3.1",
+    "tstyche": "7.2.5",
+    "typescript": "7.0.2",
+    "vite-plus": "1.4.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test && pnpm test-types",
+    "test-types": "tstyche",
+    "typecheck": "tsc",
+    "publish:npm": "pnpm pack --out package.tgz && npm publish package.tgz --access public"
+  }
 }