raf-effect-atom 0.0.0-stage → 0.0.0

package/dist/Loader.mjs

@@ -0,0 +1,232 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
+import { hydrated } from "./Hydration.mjs";
+import { isDevelopment } from "./internal/development.mjs";
+import { keyOf, take } from "./internal/leases.mjs";
+import { isRequestRegistry } from "./RequestRegistry.mjs";
+import * as Atom from "effect/reactivity/Atom";
+import * as Predicate from "effect/Predicate";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+// src/Loader.ts
+/**
+* Starts atoms from route loaders, before anything renders, so nothing
+* waterfalls.
+*
+* Each verb starts an `AsyncResult` atom in the registry and takes a lease
+* on it, so the registry's idle TTL can't evict it before the route renders
+* and `useAtomResult` takes it over:
+*
+* | Verb       | Starts the atom                 | Waits                         | Has a value already   |
+* | ---------- | ------------------------------- | ----------------------------- | --------------------- |
+* | `prefetch` | if it isn't in the registry     | never                         | leaves it alone       |
+* | `ensure`   | if it isn't in the registry     | only while it's `Initial`     | returns it at once    |
+* | `fetch`    | if it isn't, or refreshes it    | until the new result settles  | refreshes, then waits |
+*
+* Typed failures don't reject: `ensure` and `fetch` return the settled
+* `AsyncResult`, so a loader can redirect on a tag and otherwise let a
+* boundary render the failure. Only defects and interruptions reject.
+*
+* The verbs are Effects that need the `AtomRegistry`; `make` gives the same
+* verbs as Promises over one registry, for loaders that are async functions.
+*
+* @stability unstable
+* @since 0.1.0
+*/
+var Loader_exports = /* @__PURE__ */ __exportAll({
+	LeaseTTL: () => LeaseTTL,
+	ensure: () => ensure,
+	fetch: () => fetch,
+	make: () => make,
+	prefetch: () => prefetch
+});
+/**
+* How long a loader's lease keeps an atom mounted when no component takes it
+* over. Default 30 seconds.
+*
+* **Details**
+*
+* A lease ends when `useAtomResult` mounts the atom, or when this time has
+* passed, after which the registry's idle TTL applies as usual. On a request
+* registry, leases last until the registry is disposed.
+*
+* @stability unstable
+* @category references
+* @since 0.1.0
+*/
+const LeaseTTL = Context.Reference("raf-effect-atom/Loader/LeaseTTL", { defaultValue: () => Duration.seconds(30) });
+const start = Effect.fnUntraced(function* (atom) {
+	const registry = yield* AtomRegistry.AtomRegistry;
+	const request = isRequestRegistry(registry);
+	if (request && !Atom.isSerializable(atom) && (yield* isDevelopment)) return yield* Effect.die(/* @__PURE__ */ new Error(`raf-effect-atom: a loader started ${String(atom)}, which isn't serializable, so the browser would request it again. Give it a serialization key, such as AtomRpc's serializationKey option.`));
+	const ttl = request ? void 0 : Duration.toMillis(yield* LeaseTTL);
+	const target = hydrated(atom);
+	const key = keyOf(target);
+	const existed = registry.getNodes().has(key) || Predicate.isString(key) && registry.preloadedSerializable.has(key);
+	take(registry, target, ttl);
+	return {
+		existed,
+		registry,
+		request,
+		target
+	};
+});
+const isSettled = (result) => AsyncResult.isNotInitial(result) && !result.waiting;
+const settled = (registry, atom, isDone) => Effect.callback((resume) => {
+	const current = registry.get(atom);
+	if (isDone(current)) {
+		resume(Effect.succeed(current));
+		return;
+	}
+	const cancel = registry.subscribe(atom, (value) => {
+		if (isDone(value)) {
+			cancel();
+			resume(Effect.succeed(value));
+		}
+	});
+	return Effect.sync(cancel);
+}).pipe(Effect.flatMap(rejectDefects));
+const rejectDefects = (result) => {
+	if (AsyncResult.isFailure(result) && Option.isNone(Cause.findErrorOption(result.cause))) {
+		const defects = result.cause;
+		return Effect.failCause(defects);
+	}
+	return Effect.succeed(result);
+};
+/**
+* Starts an atom without waiting for it.
+*
+* **When to use**
+*
+* Use for data the route needs but its loader doesn't: it streams in while
+* the route renders.
+*
+* **Details**
+*
+* Starts the atom if it isn't in the registry, and leaves it alone if it is.
+* Takes a lease either way.
+*
+* **Example**
+*
+* ```ts
+* import { Effect } from "effect"
+* import { Loader } from "raf-effect-atom"
+*
+* const program = Loader.prefetch(comments(1))
+* ```
+*
+* @stability unstable
+* @category verbs
+* @since 0.1.0
+*/
+const prefetch = Effect.fnUntraced(function* (atom) {
+	yield* start(atom);
+});
+/**
+* Starts an atom and returns its settled result, waiting only while it has
+* none.
+*
+* **When to use**
+*
+* Use when the loader needs the result, such as to redirect on a tag, or
+* when the route shouldn't render without it.
+*
+* **Details**
+*
+* An atom with a result returns it at once, without refetching. On a request
+* registry, it also waits out a refresh in flight, so the server never
+* renders a result that's about to change. A typed failure is returned as
+* the result; a defect or an interruption fails the Effect.
+*
+* **Example**
+*
+* ```ts
+* import { Effect } from "effect"
+* import { AsyncResult } from "effect/reactivity"
+* import { Loader } from "raf-effect-atom"
+*
+* const program = Effect.gen(function* () {
+*   const result = yield* Loader.ensure(issue(1))
+*   return AsyncResult.isSuccess(result) ? result.value.title : "missing"
+* })
+* ```
+*
+* @stability unstable
+* @category verbs
+* @since 0.1.0
+*/
+const ensure = Effect.fnUntraced(function* (atom) {
+	const started = yield* start(atom);
+	return yield* settled(started.registry, started.target, started.request ? isSettled : AsyncResult.isNotInitial);
+});
+/**
+* Starts an atom, or refreshes it if it has a result, and returns the new
+* settled result.
+*
+* **When to use**
+*
+* Use when the loader must not see a result from before it ran, such as
+* after a mutation.
+*
+* **Details**
+*
+* Waits until the result settles and isn't refreshing. A typed failure is
+* returned as the result; a defect or an interruption fails the Effect.
+*
+* @stability unstable
+* @category verbs
+* @since 0.1.0
+*/
+const fetch = Effect.fnUntraced(function* (atom) {
+	const started = yield* start(atom);
+	const { registry, target } = started;
+	if (started.existed && isSettled(registry.get(target))) {
+		const node = registry.getNodes().get(keyOf(target));
+		registry.refresh(node?.atom ?? target);
+	}
+	return yield* settled(registry, target, isSettled);
+});
+/**
+* Creates the Promise verbs over one registry.
+*
+* **When to use**
+*
+* Use in a framework integration, in loaders that are async functions, or
+* in an event handler that starts an atom before the state change that
+* renders its reader, for state that can't be in the URL, such as a
+* search-as-you-type query. In Effect code, use
+* the verbs directly with the `AtomRegistry` provided.
+*
+* **Example**
+*
+* ```ts
+* import { Loader, RequestRegistry } from "raf-effect-atom"
+*
+* const loader = Loader.make(RequestRegistry.make())
+* loader.prefetch(comments(1))
+* const result = await loader.ensure(issue(1))
+* ```
+*
+* @stability unstable
+* @category constructors
+* @since 0.1.0
+*/
+const make = (registry, options) => {
+	const leaseTTL = options?.leaseTTL === void 0 ? void 0 : Duration.fromInputUnsafe(options.leaseTTL);
+	const provide = (effect) => {
+		const provided = Effect.provideService(effect, AtomRegistry.AtomRegistry, registry);
+		return leaseTTL === void 0 ? provided : Effect.provideService(provided, LeaseTTL, leaseTTL);
+	};
+	return {
+		ensure: (atom) => Effect.runPromise(provide(ensure(atom))),
+		fetch: (atom) => Effect.runPromise(provide(fetch(atom))),
+		prefetch: (atom) => {
+			Effect.runSync(provide(prefetch(atom)));
+		}
+	};
+};
+export { LeaseTTL, Loader_exports, ensure, fetch, make, prefetch };

package/dist/Next.d.mts

@@ -0,0 +1,66 @@
+import { SettledResult } from "./Loader.mjs";
+import { HydrateAtoms } from "./NextClient.mjs";
+import { RegistryProvider } from "./RegistryProvider.mjs";
+import * as Atom from "effect/reactivity/Atom";
+import * as EffectHydration from "effect/reactivity/Hydration";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+/**
+ * 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
+ */
+export declare const getRegistry: () => AtomRegistry.AtomRegistry;
+/**
+ * `Loader.prefetch` on the request's registry: starts an atom, to stream it.
+ *
+ * @stability unstable
+ * @category verbs
+ * @since 0.1.0
+ */
+export declare const prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => void;
+/**
+ * `Loader.ensure` on the request's registry: starts an atom and returns its
+ * settled result.
+ *
+ * @stability unstable
+ * @category verbs
+ * @since 0.1.0
+ */
+export declare const ensure: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Promise<SettledResult<A, E>>;
+/**
+ * `Loader.fetch` on the request's registry: starts or refreshes an atom and
+ * returns the new settled result.
+ *
+ * @stability unstable
+ * @category verbs
+ * @since 0.1.0
+ */
+export declare const fetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Promise<SettledResult<A, E>>;
+/**
+ * `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
+ */
+export declare const dehydrate: () => Array<EffectHydration.DehydratedAtom>;
+export { HydrateAtoms, RegistryProvider };

package/dist/Next.mjs

@@ -0,0 +1,63 @@
+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 an atom, to stream it.
+*
+* @stability unstable
+* @category verbs
+* @since 0.1.0
+*/
+const prefetch = prefetch$1;
+/**
+* `Loader.ensure` on the request's registry: starts an atom and returns its
+* settled result.
+*
+* @stability unstable
+* @category verbs
+* @since 0.1.0
+*/
+const ensure = ensure$1;
+/**
+* `Loader.fetch` on the request's registry: starts or refreshes an atom and
+* returns the new settled result.
+*
+* @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,33 @@
+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 id = Number((await props.params).id)
+ *   await ensure(issue(id))
+ *   return (
+ *     <HydrateAtoms state={dehydrate()}>
+ *       <Issue id={id} />
+ *     </HydrateAtoms>
+ *   )
+ * }
+ * ```
+ *
+ * @stability unstable
+ * @category components
+ * @since 0.1.0
+ */
+export declare const HydrateAtoms: (props: HydrationBoundaryProps) => React.ReactNode;

package/dist/NextClient.mjs

@@ -0,0 +1,45 @@
+"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 id = Number((await props.params).id)
+*   await ensure(issue(id))
+*   return (
+*     <HydrateAtoms state={dehydrate()}>
+*       <Issue id={id} />
+*     </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 id={id} />
+ * </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 id={id} />
+* </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 { Loader } from "./Loader.mjs";
+import { RegistryProvider } from "./RegistryProvider.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 };