raf-effect-atom 0.0.0-stage → 0.1.0

package/dist/Next.mjs

@@ -0,0 +1,64 @@
+import { dehydrate as dehydrate$1, ensure as ensure$1, fetch as fetch$1, getRegistry as getRegistry$1, prefetch as prefetch$1 } from "./internal/next.mjs";
+import { HydrateAtoms } from "./NextClient.mjs";
+import { RegistryProvider } from "./RegistryProvider.mjs";
+// src/Next.ts
+/**
+* Returns the request registry of the server render in progress.
+*
+* **Details**
+*
+* Made once per request through React's `cache`, and disposed through
+* `cacheSignal` when React finishes the render, after the last streamed
+* result has been sent.
+*
+* **Gotchas**
+*
+* Only server components share it: outside a server component render,
+* `cache` doesn't cache, so each call makes a new registry.
+*
+* @stability unstable
+* @category registry
+* @since 0.1.0
+*/
+const getRegistry = getRegistry$1;
+/**
+* `Loader.prefetch` on the request's registry: starts a source's atom, to
+* stream it, and returns its handle.
+*
+* @stability unstable
+* @category verbs
+* @since 0.1.0
+*/
+const prefetch = prefetch$1;
+/**
+* `Loader.ensure` on the request's registry: starts a source's atom, waits
+* for its result, and returns its handle.
+*
+* @stability unstable
+* @category verbs
+* @since 0.1.0
+*/
+const ensure = ensure$1;
+/**
+* `Loader.fetch` on the request's registry: starts or refreshes a source's
+* atom, waits for the new result, and returns its handle.
+*
+* @stability unstable
+* @category verbs
+* @since 0.1.0
+*/
+const fetch = fetch$1;
+/**
+* `Hydration.dehydrate` on the request's registry, for `HydrateAtoms`.
+*
+* **Gotchas**
+*
+* Includes the atoms started so far, so call it after the server component's
+* verbs. Each `HydrateAtoms` hydrates what its own `dehydrate()` saw.
+*
+* @stability unstable
+* @category dehydration
+* @since 0.1.0
+*/
+const dehydrate = dehydrate$1;
+export { HydrateAtoms, RegistryProvider, dehydrate, ensure, fetch, getRegistry, prefetch };

package/dist/NextClient.d.mts

@@ -0,0 +1,32 @@
+import { HydrationBoundaryProps } from "./ReactHydration.mjs";
+import * as React from "react";
+/**
+ * Hydrates the state a server component dehydrated with `dehydrate()`,
+ * streamed results included.
+ *
+ * **Details**
+ *
+ * React serializes the state's promises with the server component's
+ * payload, so a result still loading streams in when it settles, and
+ * `useAtomResult` waits for it instead of requesting it again.
+ *
+ * **Example**
+ *
+ * ```tsx
+ * import { dehydrate, ensure, HydrateAtoms } from "raf-effect-atom/next"
+ *
+ * export default async function IssuePage(props: { params: Promise<{ id: string }> }) {
+ *   const handle = await ensure(issue, Number((await props.params).id))
+ *   return (
+ *     <HydrateAtoms state={dehydrate()}>
+ *       <Issue issue={handle} />
+ *     </HydrateAtoms>
+ *   )
+ * }
+ * ```
+ *
+ * @stability unstable
+ * @category components
+ * @since 0.1.0
+ */
+export declare const HydrateAtoms: (props: HydrationBoundaryProps) => React.ReactNode;

package/dist/NextClient.mjs

@@ -0,0 +1,44 @@
+"use client";
+import { HydrationBoundary } from "./ReactHydration.mjs";
+import { jsx } from "react/jsx-runtime";
+// src/NextClient.tsx
+/**
+* The client components of `raf-effect-atom/next`.
+*
+* @stability unstable
+* @since 0.1.0
+*/
+/**
+* Hydrates the state a server component dehydrated with `dehydrate()`,
+* streamed results included.
+*
+* **Details**
+*
+* React serializes the state's promises with the server component's
+* payload, so a result still loading streams in when it settles, and
+* `useAtomResult` waits for it instead of requesting it again.
+*
+* **Example**
+*
+* ```tsx
+* import { dehydrate, ensure, HydrateAtoms } from "raf-effect-atom/next"
+*
+* export default async function IssuePage(props: { params: Promise<{ id: string }> }) {
+*   const handle = await ensure(issue, Number((await props.params).id))
+*   return (
+*     <HydrateAtoms state={dehydrate()}>
+*       <Issue issue={handle} />
+*     </HydrateAtoms>
+*   )
+* }
+* ```
+*
+* @stability unstable
+* @category components
+* @since 0.1.0
+*/
+const HydrateAtoms = (props) => /* @__PURE__ */ jsx(HydrationBoundary, {
+	state: props.state,
+	children: props.children
+});
+export { HydrateAtoms };

package/dist/ReactHydration.d.mts

@@ -0,0 +1,52 @@
+import * as Hydration from "effect/reactivity/Hydration";
+import * as React from "react";
+/**
+ * Props for `HydrationBoundary`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface HydrationBoundaryProps {
+  readonly children?: React.ReactNode | undefined;
+  /** The state `Hydration.dehydrate` returned on the server. */
+  readonly state?: Iterable<Hydration.DehydratedAtom> | undefined;
+}
+/**
+ * Hydrates the state a server registry dehydrated, streamed results
+ * included.
+ *
+ * **When to use**
+ *
+ * Use where the server's state reaches the React tree as a prop, such as
+ * React Server Components props or a React Router loader's data. A router
+ * that hydrates before rendering calls `Hydration.hydrate` instead.
+ *
+ * **Details**
+ *
+ * Settled values go to `@effect/atom-react`'s `HydrationBoundary`, which
+ * hydrates new atoms during render and existing ones after commit. Each
+ * streamed result is held until it arrives, so `useAtomResult` waits for it
+ * instead of requesting it again.
+ *
+ * During server rendering, when `state` is the array `dehydrate` returned,
+ * as React Router passes a loader's data to the server render, the children
+ * read the registry it came from instead of a copy. The loaders' atoms are
+ * there, so an `effect-atom-boundary` boundary sees their failures before
+ * its children read them and renders its handler on the server.
+ *
+ * **Example**
+ *
+ * ```tsx
+ * import { HydrationBoundary } from "raf-effect-atom"
+ *
+ * <HydrationBoundary state={loaderData.atoms}>
+ *   <IssuePage issue={loaderData.issue} />
+ * </HydrationBoundary>
+ * ```
+ *
+ * @stability unstable
+ * @category components
+ * @since 0.1.0
+ */
+export declare const HydrationBoundary: (props: HydrationBoundaryProps) => React.ReactNode;

package/dist/ReactHydration.mjs

@@ -0,0 +1,71 @@
+"use client";
+import { split } from "./internal/pending.mjs";
+import { sourceOf } from "./internal/sources.mjs";
+import { isServer } from "./internal/registry.mjs";
+import { HydrationBoundary, RegistryContext } from "@effect/atom-react";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+// src/ReactHydration.tsx
+/**
+* Applies a server registry's dehydrated state to the nearest
+* `RegistryContext`, while rendering.
+*
+* @stability unstable
+* @since 0.1.0
+*/
+/**
+* Hydrates the state a server registry dehydrated, streamed results
+* included.
+*
+* **When to use**
+*
+* Use where the server's state reaches the React tree as a prop, such as
+* React Server Components props or a React Router loader's data. A router
+* that hydrates before rendering calls `Hydration.hydrate` instead.
+*
+* **Details**
+*
+* Settled values go to `@effect/atom-react`'s `HydrationBoundary`, which
+* hydrates new atoms during render and existing ones after commit. Each
+* streamed result is held until it arrives, so `useAtomResult` waits for it
+* instead of requesting it again.
+*
+* During server rendering, when `state` is the array `dehydrate` returned,
+* as React Router passes a loader's data to the server render, the children
+* read the registry it came from instead of a copy. The loaders' atoms are
+* there, so an `effect-atom-boundary` boundary sees their failures before
+* its children read them and renders its handler on the server.
+*
+* **Example**
+*
+* ```tsx
+* import { HydrationBoundary } from "raf-effect-atom"
+*
+* <HydrationBoundary state={loaderData.atoms}>
+*   <IssuePage issue={loaderData.issue} />
+* </HydrationBoundary>
+* ```
+*
+* @stability unstable
+* @category components
+* @since 0.1.0
+*/
+const HydrationBoundary$1 = (props) => {
+	const context = React.useContext(RegistryContext);
+	const state = props.state;
+	const source = isServer() ? sourceOf(state) : void 0;
+	const registry = source ?? context;
+	const settled = React.useMemo(() => state === void 0 || source !== void 0 ? void 0 : split(registry, state), [
+		registry,
+		source,
+		state
+	]);
+	return /* @__PURE__ */ jsx(RegistryContext.Provider, {
+		value: registry,
+		children: /* @__PURE__ */ jsx(HydrationBoundary, {
+			state: settled,
+			children: props.children
+		})
+	});
+};
+export { HydrationBoundary$1 as HydrationBoundary };

package/dist/ReactRouter.d.mts

@@ -0,0 +1,63 @@
+import { RegistryProvider } from "./RegistryProvider.mjs";
+import { Loader } from "./Loader.mjs";
+import * as EffectHydration from "effect/reactivity/Hydration";
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+/**
+ * One request's registry, with the loader verbs over it.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface RequestAtoms extends Loader {
+  /** `Hydration.dehydrate` on the request's registry, for loader data. */
+  readonly dehydrate: () => Array<EffectHydration.DehydratedAtom>;
+  readonly registry: AtomRegistry.AtomRegistry;
+}
+/**
+ * The router context `atomsMiddleware` sets: what `react-router`'s
+ * `createContext<RequestAtoms>()` returns.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface AtomsContext {
+  readonly defaultValue?: RequestAtoms | undefined;
+}
+/**
+ * The parts of React Router's middleware arguments `atomsMiddleware` uses.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface MiddlewareArgs {
+  readonly context: {
+    readonly set: (context: AtomsContext, value: RequestAtoms) => void;
+  };
+}
+/**
+ * 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
+ */
+export declare const atomsMiddleware: (context: AtomsContext) => <Result>(args: MiddlewareArgs, next: () => Promise<Result>) => Promise<Result>;
+export { RegistryProvider };

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)
+*   const handle = await atoms.ensure(issue, Number(args.params.id))
+*   return { atoms: atoms.dehydrate(), issue: handle }
+* }
+*
+* export default function IssueRoute(props: Route.ComponentProps) {
+*   return (
+*     <HydrationBoundary state={props.loaderData.atoms}>
+*       <Issue issue={props.loaderData.issue} />
+*     </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 };