raf-effect-atom 0.0.0-stage → 0.0.0

package/dist/ReactRouter.mjs

@@ -0,0 +1,116 @@
+import { dehydrate } from "./Hydration.mjs";
+import { make } from "./RequestRegistry.mjs";
+import { make as make$1 } from "./Loader.mjs";
+import { RegistryProvider } from "./RegistryProvider.mjs";
+import * as Predicate from "effect/Predicate";
+// src/ReactRouter.ts
+/**
+* Connects the loader verbs to React Router's Framework Mode.
+*
+* A root `middleware` gives each server request its own registry, under a
+* router context the app creates. Loaders start atoms with its verbs and
+* return its `dehydrate()` with their data; the route component hydrates it
+* with `HydrationBoundary`, inside the root's `RegistryProvider`. Nothing is
+* imported from `react-router`.
+*
+* **Example**
+*
+* ```tsx
+* // app/atoms.ts
+* import { createContext } from "react-router"
+* import type { RequestAtoms } from "raf-effect-atom/react-router"
+*
+* export const atomsContext = createContext<RequestAtoms>()
+*
+* // app/root.tsx
+* import { atomsMiddleware } from "raf-effect-atom/react-router"
+*
+* export const middleware = [atomsMiddleware(atomsContext)]
+*
+* // app/routes/issue.tsx
+* export async function loader(args: Route.LoaderArgs) {
+*   const atoms = args.context.get(atomsContext)
+*   await atoms.ensure(issue(Number(args.params.id)))
+*   return { atoms: atoms.dehydrate() }
+* }
+*
+* export default function IssueRoute(props: Route.ComponentProps) {
+*   return (
+*     <HydrationBoundary state={props.loaderData.atoms}>
+*       <Issue id={Number(props.params.id)} />
+*     </HydrationBoundary>
+*   )
+* }
+* ```
+*
+* @stability unstable
+* @since 0.1.0
+*/
+/**
+* Creates a root middleware that gives each server request its own
+* registry, under the given router context.
+*
+* **Details**
+*
+* The registry is disposed once the response's body has been sent, or the
+* client has gone: loader data streams its pending promises after the
+* middleware returns, so the atoms behind them must keep running until
+* then. When `next` doesn't return a `Response`, as Data Mode's
+* `query` can, the registry is left to be collected with the request.
+*
+* **Gotchas**
+*
+* It's server middleware: export it as the root route's `middleware`, not
+* `clientMiddleware`. In the browser, the root's `RegistryProvider` holds
+* the registry.
+*
+* @stability unstable
+* @category integrations
+* @since 0.1.0
+*/
+const atomsMiddleware = (context) => async (args, next) => {
+	const registry = make();
+	const loader = make$1(registry);
+	args.context.set(context, {
+		...loader,
+		dehydrate: () => dehydrate(registry),
+		registry
+	});
+	let result;
+	try {
+		result = await next();
+	} catch (error) {
+		registry.dispose();
+		throw error;
+	}
+	if (!isResponse(result)) return result;
+	const body = result.body;
+	if (body === null) {
+		registry.dispose();
+		return result;
+	}
+	return new Response(disposeAfter(body, registry), result);
+};
+const isResponse = (value) => Predicate.hasProperty(value, "body") && Predicate.hasProperty(value, "headers") && Predicate.hasProperty(value, "status");
+const disposeAfter = (body, registry) => {
+	const reader = body.getReader();
+	return new ReadableStream({
+		cancel: async (reason) => {
+			registry.dispose();
+			await reader.cancel(reason);
+		},
+		pull: async (controller) => {
+			try {
+				const chunk = await reader.read();
+				if (chunk.done) {
+					registry.dispose();
+					controller.close();
+				} else controller.enqueue(chunk.value);
+			} catch (error) {
+				registry.dispose();
+				controller.error(error);
+			}
+		}
+	});
+};
+export { RegistryProvider, atomsMiddleware };

package/dist/RegistryProvider.d.mts

@@ -0,0 +1,40 @@
+import * as React from "react";
+/**
+ * Provides the app's registry: a request registry while the framework
+ * renders the app on the server, and one registry for the page's lifetime
+ * in the browser.
+ *
+ * **When to use**
+ *
+ * Put it in the root layout, around `children`, in place of
+ * `@effect/atom-react`'s `RegistryProvider`, which would share one registry
+ * between requests' server renders.
+ *
+ * **Details**
+ *
+ * `defaultIdleTTL` is how many milliseconds the browser's registry keeps an
+ * atom no component reads, 400 by default, as `@effect/atom-react`'s default
+ * registry does. An atom's own `Atom.setIdleTTL` or `Atom.keepAlive` wins.
+ * It's read once, when the registry is made. The server's request registry
+ * lives for one request, so it has none.
+ *
+ * **Example**
+ *
+ * ```tsx
+ * import { RegistryProvider } from "raf-effect-atom/next" // or "raf-effect-atom/react-router"
+ *
+ * export default function RootLayout(props: { children: React.ReactNode }) {
+ *   return (
+ *     <RegistryProvider defaultIdleTTL={60_000}>{props.children}</RegistryProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @stability unstable
+ * @category components
+ * @since 0.1.0
+ */
+export declare const RegistryProvider: (props: {
+  readonly children?: React.ReactNode | undefined;
+  readonly defaultIdleTTL?: number | undefined;
+}) => React.ReactNode;

package/dist/RegistryProvider.mjs

@@ -0,0 +1,55 @@
+"use client";
+import { make } from "./internal/registry.mjs";
+import { RegistryContext } from "@effect/atom-react";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+// src/RegistryProvider.tsx
+/**
+* The registry provider shared by the Next.js and React Router integrations.
+*
+* @stability unstable
+* @since 0.1.0
+*/
+/**
+* Provides the app's registry: a request registry while the framework
+* renders the app on the server, and one registry for the page's lifetime
+* in the browser.
+*
+* **When to use**
+*
+* Put it in the root layout, around `children`, in place of
+* `@effect/atom-react`'s `RegistryProvider`, which would share one registry
+* between requests' server renders.
+*
+* **Details**
+*
+* `defaultIdleTTL` is how many milliseconds the browser's registry keeps an
+* atom no component reads, 400 by default, as `@effect/atom-react`'s default
+* registry does. An atom's own `Atom.setIdleTTL` or `Atom.keepAlive` wins.
+* It's read once, when the registry is made. The server's request registry
+* lives for one request, so it has none.
+*
+* **Example**
+*
+* ```tsx
+* import { RegistryProvider } from "raf-effect-atom/next" // or "raf-effect-atom/react-router"
+*
+* export default function RootLayout(props: { children: React.ReactNode }) {
+*   return (
+*     <RegistryProvider defaultIdleTTL={60_000}>{props.children}</RegistryProvider>
+*   )
+* }
+* ```
+*
+* @stability unstable
+* @category components
+* @since 0.1.0
+*/
+const RegistryProvider = (props) => {
+	const [registry] = React.useState(() => make({ defaultIdleTTL: props.defaultIdleTTL }));
+	return /* @__PURE__ */ jsx(RegistryContext.Provider, {
+		value: registry,
+		children: props.children
+	});
+};
+export { RegistryProvider };

package/dist/RequestRegistry.d.mts

@@ -0,0 +1,54 @@
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+import * as Layer from "effect/Layer";
+declare namespace RequestRegistry_d_exports {
+  export { isRequestRegistry, layer, make };
+}
+/**
+ * Creates the registry for one server request.
+ *
+ * **Details**
+ *
+ * It's an ordinary `AtomRegistry`, marked as a request registry. On a
+ * request registry, `ensure` waits like `fetch` does, nothing revalidates in
+ * the background, and a loader's lease lasts until the registry is disposed.
+ * In development, the loader verbs refuse an atom that isn't serializable,
+ * because the browser would request it again.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { RequestRegistry } from "raf-effect-atom"
+ *
+ * const registry = RequestRegistry.make()
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: () => AtomRegistry.AtomRegistry;
+/**
+ * A layer that provides a request registry as the `AtomRegistry`, disposed
+ * when the layer's scope closes.
+ *
+ * **When to use**
+ *
+ * Use when the request is handled in Effect, around the loaders' verbs and
+ * `dehydrate`.
+ *
+ * @see {@link make} for the registry it provides
+ *
+ * @stability unstable
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<AtomRegistry.AtomRegistry>;
+/**
+ * Returns whether a registry was made by `make`, for one server request.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.1.0
+ */
+export declare const isRequestRegistry: (registry: AtomRegistry.AtomRegistry) => boolean;
+export { RequestRegistry_d_exports };

package/dist/RequestRegistry.mjs

@@ -0,0 +1,76 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
+import * as Effect from "effect/Effect";
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+import * as Layer from "effect/Layer";
+// src/RequestRegistry.ts
+/**
+* A registry per server request.
+*
+* `@effect/atom-react`'s default `RegistryContext` is one registry for the
+* whole module, which on a server would share one user's results with every
+* other request. Each framework integration makes a request registry with
+* `make`, provides it through `RegistryContext`, and dehydrates it into the
+* response.
+*
+* @stability unstable
+* @since 0.1.0
+*/
+var RequestRegistry_exports = /* @__PURE__ */ __exportAll({
+	isRequestRegistry: () => isRequestRegistry,
+	layer: () => layer,
+	make: () => make
+});
+const requestRegistries = /* @__PURE__ */ new WeakSet();
+/**
+* Creates the registry for one server request.
+*
+* **Details**
+*
+* It's an ordinary `AtomRegistry`, marked as a request registry. On a
+* request registry, `ensure` waits like `fetch` does, nothing revalidates in
+* the background, and a loader's lease lasts until the registry is disposed.
+* In development, the loader verbs refuse an atom that isn't serializable,
+* because the browser would request it again.
+*
+* **Example**
+*
+* ```ts
+* import { RequestRegistry } from "raf-effect-atom"
+*
+* const registry = RequestRegistry.make()
+* ```
+*
+* @stability unstable
+* @category constructors
+* @since 0.1.0
+*/
+const make = () => {
+	const registry = AtomRegistry.make();
+	requestRegistries.add(registry);
+	return registry;
+};
+/**
+* A layer that provides a request registry as the `AtomRegistry`, disposed
+* when the layer's scope closes.
+*
+* **When to use**
+*
+* Use when the request is handled in Effect, around the loaders' verbs and
+* `dehydrate`.
+*
+* @see {@link make} for the registry it provides
+*
+* @stability unstable
+* @category layers
+* @since 0.1.0
+*/
+const layer = Layer.effect(AtomRegistry.AtomRegistry, Effect.acquireRelease(Effect.sync(() => make()), (registry) => Effect.sync(() => registry.dispose())));
+/**
+* Returns whether a registry was made by `make`, for one server request.
+*
+* @stability unstable
+* @category guards
+* @since 0.1.0
+*/
+const isRequestRegistry = (registry) => requestRegistries.has(registry);
+export { RequestRegistry_exports, isRequestRegistry, layer, make };

package/dist/TanStackRouter.d.mts

@@ -0,0 +1,84 @@
+import * as EffectHydration from "effect/reactivity/Hydration";
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+import { AnyRouter } from "@tanstack/react-router";
+/**
+ * The key `setupRouterAtoms` adds to the router's dehydrated state.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface DehydratedRouterAtoms {
+  readonly "raf-effect-atom": ReadonlyArray<EffectHydration.DehydratedAtom>;
+}
+/**
+ * Options for `setupRouterAtoms`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface RouterAtomsOptions<TRouter extends AnyRouter> {
+  /** The registry the router context's loader verbs run on. */
+  readonly registry: AtomRegistry.AtomRegistry;
+  readonly router: TRouter;
+}
+/**
+ * Creates the registry for one `getRouter` call: a request registry on the
+ * server, and in the browser a registry like `@effect/atom-react`'s
+ * `RegistryProvider` makes.
+ *
+ * **Details**
+ *
+ * - The server is anywhere without a `window`. To decide otherwise, make
+ *   the registry with `RequestRegistry.make` on the server and
+ *   `AtomRegistry.make` in the browser.
+ * - `defaultIdleTTL` is how many milliseconds the browser's registry keeps
+ *   an atom no component reads, 400 by default, as `@effect/atom-react`'s
+ *   default registry does. An atom's own `Atom.setIdleTTL` or
+ *   `Atom.keepAlive` wins. The server's request registry lives for one
+ *   request, so it has none.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { makeRegistry } from "raf-effect-atom/tanstack-router"
+ *
+ * // Keeps an issue the user navigated away from for a minute.
+ * const registry = makeRegistry({ defaultIdleTTL: 60_000 })
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeRegistry: (options?: {
+  readonly defaultIdleTTL?: number | undefined;
+}) => AtomRegistry.AtomRegistry;
+/**
+ * Provides a registry to a TanStack router's app and streams it from the
+ * server to the browser.
+ *
+ * **Details**
+ *
+ * - Wraps the app in `RegistryContext.Provider` through the router's `Wrap`
+ *   option, inside any `Wrap` it has already.
+ * - On the server, adds `Hydration.dehydrate(registry)` to the router's
+ *   dehydrated state once the loaders have run, so results still loading
+ *   cross as promises on the router's stream, and disposes the registry when
+ *   the response finishes.
+ * - In the browser, hydrates the registry from that state before the app
+ *   renders.
+ *
+ * **Gotchas**
+ *
+ * The server's registry must be a request registry and the browser's must
+ * not, so it throws otherwise: a registry shared between requests would send
+ * one user's results to another. Only atoms in the registry when the loaders
+ * finish are sent; one first read while rendering runs again in the browser.
+ *
+ * @stability unstable
+ * @category integrations
+ * @since 0.1.0
+ */
+export declare const setupRouterAtoms: <TRouter extends AnyRouter>(options: RouterAtomsOptions<TRouter>) => void;

package/dist/TanStackRouter.mjs

@@ -0,0 +1,134 @@
+import { dehydrate, hydrate } from "./Hydration.mjs";
+import { isRequestRegistry } from "./RequestRegistry.mjs";
+import { make } from "./internal/registry.mjs";
+import * as Predicate from "effect/Predicate";
+import { RegistryContext } from "@effect/atom-react";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+// src/TanStackRouter.tsx
+/**
+* Connects the loader verbs to TanStack Router and TanStack Start.
+*
+* `getRouter` runs once per request on the server and once in the browser.
+* It makes the registry with `makeRegistry`, puts `Loader.make(registry)` on
+* the router context for the loaders, and calls `setupRouterAtoms`, which
+* provides the registry to the app and sends it from the server to the
+* browser through the router's own dehydration.
+*
+* **Example**
+*
+* ```tsx
+* import { createRouter } from "@tanstack/react-router"
+* import { Loader } from "raf-effect-atom"
+* import { makeRegistry, setupRouterAtoms } from "raf-effect-atom/tanstack-router"
+*
+* export function getRouter() {
+*   const registry = makeRegistry()
+*   const router = createRouter({
+*     routeTree,
+*     context: { atoms: Loader.make(registry) }
+*   })
+*   setupRouterAtoms({ router, registry })
+*   return router
+* }
+* ```
+*
+* @stability unstable
+* @since 0.1.0
+*/
+/**
+* Creates the registry for one `getRouter` call: a request registry on the
+* server, and in the browser a registry like `@effect/atom-react`'s
+* `RegistryProvider` makes.
+*
+* **Details**
+*
+* - The server is anywhere without a `window`. To decide otherwise, make
+*   the registry with `RequestRegistry.make` on the server and
+*   `AtomRegistry.make` in the browser.
+* - `defaultIdleTTL` is how many milliseconds the browser's registry keeps
+*   an atom no component reads, 400 by default, as `@effect/atom-react`'s
+*   default registry does. An atom's own `Atom.setIdleTTL` or
+*   `Atom.keepAlive` wins. The server's request registry lives for one
+*   request, so it has none.
+*
+* **Example**
+*
+* ```ts
+* import { makeRegistry } from "raf-effect-atom/tanstack-router"
+*
+* // Keeps an issue the user navigated away from for a minute.
+* const registry = makeRegistry({ defaultIdleTTL: 60_000 })
+* ```
+*
+* @stability unstable
+* @category constructors
+* @since 0.1.0
+*/
+const makeRegistry = (options) => make(options);
+const hasRouterAtoms = (value) => Predicate.hasProperty(value, "raf-effect-atom") && Array.isArray(value["raf-effect-atom"]);
+/**
+* Provides a registry to a TanStack router's app and streams it from the
+* server to the browser.
+*
+* **Details**
+*
+* - Wraps the app in `RegistryContext.Provider` through the router's `Wrap`
+*   option, inside any `Wrap` it has already.
+* - On the server, adds `Hydration.dehydrate(registry)` to the router's
+*   dehydrated state once the loaders have run, so results still loading
+*   cross as promises on the router's stream, and disposes the registry when
+*   the response finishes.
+* - In the browser, hydrates the registry from that state before the app
+*   renders.
+*
+* **Gotchas**
+*
+* The server's registry must be a request registry and the browser's must
+* not, so it throws otherwise: a registry shared between requests would send
+* one user's results to another. Only atoms in the registry when the loaders
+* finish are sent; one first read while rendering runs again in the browser.
+*
+* @stability unstable
+* @category integrations
+* @since 0.1.0
+*/
+const setupRouterAtoms = (options) => {
+	const router = options.router;
+	const registry = options.registry;
+	if (router.isServer !== isRequestRegistry(registry)) throw new Error(router.isServer ? "raf-effect-atom: setupRouterAtoms got a server router without a request registry, which would share results between requests. Make it with makeRegistry or RequestRegistry.make." : "raf-effect-atom: setupRouterAtoms got a browser router with a request registry. Make it with makeRegistry or AtomRegistry.make.");
+	const Wrap = router.options.Wrap ?? React.Fragment;
+	router.options.Wrap = (props) => /* @__PURE__ */ jsx(RegistryContext.Provider, {
+		value: registry,
+		children: /* @__PURE__ */ jsx(Wrap, { children: props.children })
+	});
+	if (router.isServer) {
+		let disposed = false;
+		router.serverSsrLifecycle = {
+			...router.serverSsrLifecycle,
+			onServerSsrAttach: [...router.serverSsrLifecycle?.onServerSsrAttach ?? [], (serverSsr) => {
+				serverSsr.onCleanup(() => {
+					disposed = true;
+					registry.dispose();
+				});
+			}]
+		};
+		const dehydrate$1 = router.options.dehydrate;
+		router.options.dehydrate = async () => {
+			const dehydrated = await dehydrate$1?.();
+			if (disposed) return dehydrated;
+			const atoms = { "raf-effect-atom": dehydrate(registry) };
+			return Predicate.isObject(dehydrated) ? {
+				...dehydrated,
+				...atoms
+			} : atoms;
+		};
+	} else {
+		const hydrate$1 = router.options.hydrate;
+		router.options.hydrate = async (dehydrated) => {
+			await hydrate$1?.(dehydrated);
+			if (hasRouterAtoms(dehydrated)) hydrate(registry, dehydrated["raf-effect-atom"]);
+		};
+	}
+};
+export { makeRegistry, setupRouterAtoms };

package/dist/Waterfalls.d.mts

@@ -0,0 +1,98 @@
+import { Mode } from "./internal/waterfalls.mjs";
+import * as Atom from "effect/reactivity/Atom";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+import * as React from "react";
+/**
+ * What `useAtomResult` does in development when a read starts an atom that
+ * no loader, server component, event handler or `useWaterfall` started.
+ *
+ * - `"warn"`: `console.warn` once per atom, naming it. The default.
+ * - `"throw"`: throw to the nearest error boundary, so the page can't be
+ *   used until the atom starts before render.
+ * - `"off"`: don't check.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export type WaterfallMode = Mode;
+/**
+ * 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
+ */
+export declare const WaterfallDetection: (props: {
+  readonly children?: React.ReactNode | undefined;
+  readonly mode: WaterfallMode;
+}) => React.ReactNode;
+/**
+ * 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
+ */
+export declare const useWaterfall: <Self extends Atom.Atom<AsyncResult.AsyncResult<unknown, unknown>>>(atom: Self) => Self;