raf-effect-atom 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,10 +1,31 @@
 # Changelog
 
+## [0.2.3](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.2.2...raf-effect-atom%400.2.3) (2026-10-23)
+
+### Features
+
+* **raf-effect-atom:** run Effect code on a loader's registry with Loader.Loader.run ([d26307d](https://github.com/KATT/raf-effect-atom/commit/d26307dc6279106ebd9d26078c88e4ad10a8cbc9))
+
+## [0.2.2](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.2.1...raf-effect-atom%400.2.2) (2026-10-23)
+
+### Features
+
+- **raf-effect-atom:** stop a loader's wait when its request is aborted ([b1f2f16](https://github.com/KATT/raf-effect-atom/commit/b1f2f16fcce9cd5dd1ba18fa653b40c805eebd93)), references [#41](https://github.com/KATT/raf-effect-atom/issues/41) [#40](https://github.com/KATT/raf-effect-atom/issues/40) [#40](https://github.com/KATT/raf-effect-atom/issues/40) [#41](https://github.com/KATT/raf-effect-atom/issues/41)
+
+### Bug Fixes
+
+- **raf-effect-atom:** refuse to hydrate a shared registry during server rendering ([2f793a6](https://github.com/KATT/raf-effect-atom/commit/2f793a63627482bdf2f0e2891829f5191077cfc7))
+
+### Documentation
+
+- **raf-effect-atom:** date clientAtomsMiddleware to 0.2.1, the release it shipped in ([c2a4288](https://github.com/KATT/raf-effect-atom/commit/c2a4288f4c5b63575e019712edc9fdc49a052bd2))
+- record that the packages' module state is keyed by what one request owns ([22b23f9](https://github.com/KATT/raf-effect-atom/commit/22b23f947544f8c4459ef172e8b21499403059c4))
+
 ## [0.2.1](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.2.0...raf-effect-atom%400.2.1) (2026-10-23)
 
 ### Features
 
-* **raf-effect-atom:** run React Router loaders in the browser after the first page ([bee00a9](https://github.com/KATT/raf-effect-atom/commit/bee00a981fd24fcdc9d746053dcd73dbc7ebc853)), references [#41](https://github.com/KATT/raf-effect-atom/issues/41) [#41](https://github.com/KATT/raf-effect-atom/issues/41)
+- **raf-effect-atom:** run React Router loaders in the browser after the first page ([bee00a9](https://github.com/KATT/raf-effect-atom/commit/bee00a981fd24fcdc9d746053dcd73dbc7ebc853)), references [#41](https://github.com/KATT/raf-effect-atom/issues/41) [#41](https://github.com/KATT/raf-effect-atom/issues/41)
 
 ## [0.2.0](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.1.0...raf-effect-atom%400.2.0) (2026-10-23)
 

package/dist/Hooks.mjs

@@ -1,16 +1,13 @@
 "use client";
 import { stream } from "./internal/pending.mjs";
 import { hydrated } from "./Hydration.mjs";
-import { isDevelopment } from "./internal/development.mjs";
 import { keyOf, release } from "./internal/leases.mjs";
 import { atomOf } from "./internal/handles.mjs";
-import { isRequestRegistry } from "./RequestRegistry.mjs";
-import { isServer } from "./internal/registry.mjs";
+import { requireRequestRegistry } from "./internal/registry.mjs";
 import { ModeContext, check } from "./internal/waterfalls.mjs";
 import * as Atom from "effect/reactivity/Atom";
 import * as Predicate from "effect/Predicate";
 import * as Cause from "effect/Cause";
-import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as AsyncResult from "effect/reactivity/AsyncResult";
 import { RegistryContext, useAtomSuspense } from "@effect/atom-react";
@@ -111,7 +108,7 @@ const sourceOf = (atom) => {
 const useAtomResult = (source, handle) => {
 	const registry = React.useContext(RegistryContext);
 	const atom = atomOf(source, handle.args);
-	if (isServer() && !isRequestRegistry(registry) && Effect.runSync(isDevelopment)) throw new Error("raf-effect-atom: useAtomResult rendered on the server without a request registry, so results would be shared between requests. Provide RequestRegistry.make() through RegistryContext, as the framework integrations do.");
+	requireRequestRegistry(registry, "useAtomResult");
 	const target = sourceOf(atom);
 	const started = hydrated(target);
 	const read = target === atom ? hydrated(atom) : atom;

package/dist/Loader.d.mts

@@ -5,7 +5,7 @@ import * as Effect from "effect/Effect";
 import * as AsyncResult from "effect/reactivity/AsyncResult";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 declare namespace Loader_d_exports {
-  export { LeaseTTL, Loader, SettledResult, ensure, fetch, make, prefetch, result };
+  export { LeaseTTL, Loader, MakeOptions, SettledResult, ensure, fetch, make, prefetch, result };
 }
 /**
  * A settled `AsyncResult`: what `ensure` and `fetch` return.
@@ -165,6 +165,32 @@ export interface Loader {
    * the seed resolves.
    */
   readonly prefetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Handle<S>;
+  /**
+   * Runs an Effect that needs the registry, such as the Effect verbs in an
+   * `Effect.gen`, as a Promise that rejects with its squashed cause.
+   * Aborting `signal`, or the one the verbs were made with, interrupts it,
+   * and the Promise rejects with the abort reason.
+   */
+  readonly run: <A, E>(effect: Effect.Effect<A, E, AtomRegistry.AtomRegistry>, options?: {
+    readonly signal?: AbortSignal | undefined;
+  }) => Promise<A>;
+}
+/**
+ * Options for `make`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.2
+ */
+export interface MakeOptions {
+  /** How long a lease lasts in the browser. See {@link LeaseTTL}. */
+  readonly leaseTTL?: Duration.Input | undefined;
+  /**
+   * The request's or the navigation's abort signal. Aborting it interrupts
+   * the `ensure`, `fetch` and `run` calls still waiting, which reject with
+   * its reason. The atoms they started keep loading.
+   */
+  readonly signal?: AbortSignal | undefined;
 }
 /**
  * Creates the Promise verbs over one registry.
@@ -174,15 +200,22 @@ export interface Loader {
  * 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.
+ * search-as-you-type query. In Effect code, use the verbs directly, and run
+ * the Effect on the registry with `run`.
+ *
+ * **Details**
+ *
+ * With a `signal`, an aborted request or navigation stops waiting: `ensure`,
+ * `fetch` and `run` reject with the signal's reason, and the atoms they
+ * started keep loading. The React Router and Next.js integrations pass the
+ * request's.
  *
  * **Example**
  *
  * ```ts
  * import { Loader, RequestRegistry } from "raf-effect-atom"
  *
- * const loader = Loader.make(RequestRegistry.make())
+ * const loader = Loader.make(RequestRegistry.make(), { signal: request.signal })
  * const comments = loader.prefetch(commentPage, 1, 0)
  * const issueHandle = await loader.ensure(issue, 1)
  * ```
@@ -191,7 +224,5 @@ export interface Loader {
  * @category constructors
  * @since 0.1.0
  */
-export declare const make: (registry: AtomRegistry.AtomRegistry, options?: {
-  readonly leaseTTL?: Duration.Input | undefined;
-}) => Loader;
+export declare const make: (registry: AtomRegistry.AtomRegistry, options?: MakeOptions) => Loader;
 export { Loader_d_exports };

package/dist/Loader.mjs

@@ -250,6 +250,10 @@ const result = (handle) => {
 	if (settledResult === void 0) throw new Error("raf-effect-atom: Loader.result got a handle that no ensure or fetch returned here. Only the code that ran the verb has its result: a handle that crossed the network is a copy. Read it with useAtomResult instead.");
 	return settledResult;
 };
+const runPromise = (effect, signal) => Effect.runPromise(effect, { signal }).catch((error) => {
+	throw signal?.aborted ? signal.reason : error;
+});
+const either = (first, second) => first === void 0 || second === void 0 ? first ?? second : AbortSignal.any([first, second]);
 /**
 * Creates the Promise verbs over one registry.
 *
@@ -258,15 +262,22 @@ const result = (handle) => {
 * 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.
+* search-as-you-type query. In Effect code, use the verbs directly, and run
+* the Effect on the registry with `run`.
+*
+* **Details**
+*
+* With a `signal`, an aborted request or navigation stops waiting: `ensure`,
+* `fetch` and `run` reject with the signal's reason, and the atoms they
+* started keep loading. The React Router and Next.js integrations pass the
+* request's.
 *
 * **Example**
 *
 * ```ts
 * import { Loader, RequestRegistry } from "raf-effect-atom"
 *
-* const loader = Loader.make(RequestRegistry.make())
+* const loader = Loader.make(RequestRegistry.make(), { signal: request.signal })
 * const comments = loader.prefetch(commentPage, 1, 0)
 * const issueHandle = await loader.ensure(issue, 1)
 * ```
@@ -277,20 +288,22 @@ const result = (handle) => {
 */
 const make = (registry, options) => {
 	const leaseTTL = options?.leaseTTL === void 0 ? void 0 : Duration.fromInputUnsafe(options.leaseTTL);
+	const signal = options?.signal;
 	const provide = (effect) => {
 		const provided = Effect.provideService(effect, AtomRegistry.AtomRegistry, registry);
 		return leaseTTL === void 0 ? provided : Effect.provideService(provided, LeaseTTL, leaseTTL);
 	};
 	return {
-		ensure: (source, ...args) => Effect.runPromise(provide(ensure(source, ...args))),
-		fetch: (source, ...args) => Effect.runPromise(provide(fetch(source, ...args))),
+		ensure: (source, ...args) => runPromise(provide(ensure(source, ...args)), signal),
+		fetch: (source, ...args) => runPromise(provide(fetch(source, ...args)), signal),
 		prefetch: (source, ...args) => {
 			const atom = atomOf(source, args);
 			afterSeed(registry, () => {
 				Effect.runSync(provide(start(atom)));
 			});
 			return make$1(args, atom);
-		}
+		},
+		run: (effect, runOptions) => runPromise(provide(effect), either(signal, runOptions?.signal))
 	};
 };
 export { LeaseTTL, Loader_exports, ensure, fetch, make, prefetch, result };

package/dist/Next.d.mts

@@ -67,7 +67,9 @@ export declare const makeRequestAtoms: (options?: Options) => RequestAtoms;
  *
  * 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.
+ * result has been sent. The verbs take the same signal: when React aborts
+ * the render, such as for a navigation the browser left, the `ensure` and
+ * `fetch` calls still waiting reject with its reason.
  *
  * **Gotchas**
  *
@@ -106,6 +108,26 @@ export declare const ensure: <S extends Source>(source: S, ...args: ArgsOf<S>) =
  * @since 0.1.0
  */
 export declare const fetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Promise<LoadedHandle<S>>;
+/**
+ * `Loader.Loader`'s `run` on the request's registry: runs an Effect that
+ * needs the registry, such as the Effect verbs in an `Effect.gen`.
+ *
+ * **Example**
+ *
+ * ```ts
+ * const handles = await run(
+ *   Effect.gen(function* () {
+ *     const issueHandle = yield* Loader.ensure(issue, id)
+ *     return { comments: yield* Loader.prefetch(commentPage, id, 0), issue: issueHandle }
+ *   })
+ * )
+ * ```
+ *
+ * @stability unstable
+ * @category verbs
+ * @since 0.2.3
+ */
+export declare const run: Loader["run"];
 /**
  * `Hydration.dehydrate` on the request's registry, for `HydrateAtoms`.
  *

package/dist/Next.mjs

@@ -48,7 +48,9 @@ const atoms = make();
 *
 * 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.
+* result has been sent. The verbs take the same signal: when React aborts
+* the render, such as for a navigation the browser left, the `ensure` and
+* `fetch` calls still waiting reject with its reason.
 *
 * **Gotchas**
 *
@@ -88,6 +90,26 @@ const ensure = atoms.ensure;
 */
 const fetch = atoms.fetch;
 /**
+* `Loader.Loader`'s `run` on the request's registry: runs an Effect that
+* needs the registry, such as the Effect verbs in an `Effect.gen`.
+*
+* **Example**
+*
+* ```ts
+* const handles = await run(
+*   Effect.gen(function* () {
+*     const issueHandle = yield* Loader.ensure(issue, id)
+*     return { comments: yield* Loader.prefetch(commentPage, id, 0), issue: issueHandle }
+*   })
+* )
+* ```
+*
+* @stability unstable
+* @category verbs
+* @since 0.2.3
+*/
+const run = atoms.run;
+/**
 * `Hydration.dehydrate` on the request's registry, for `HydrateAtoms`.
 *
 * **Gotchas**
@@ -108,4 +130,4 @@ const fetch = atoms.fetch;
 * @since 0.1.0
 */
 const dehydrate = atoms.dehydrate;
-export { HydrateAtoms, RegistryProvider, dehydrate, ensure, fetch, getRegistry, makeRequestAtoms, prefetch };
+export { HydrateAtoms, RegistryProvider, dehydrate, ensure, fetch, getRegistry, makeRequestAtoms, prefetch, run };

package/dist/ReactHydration.d.mts

@@ -35,6 +35,12 @@ export interface HydrationBoundaryProps {
  * there, so an `effect-atom-boundary` boundary sees their failures before
  * its children read them and renders its handler on the server.
  *
+ * **Gotchas**
+ *
+ * In development, it throws during server rendering when the registry isn't
+ * a request registry, such as `@effect/atom-react`'s default one, which
+ * every request shares: one request's state would reach the others.
+ *
  * **Example**
  *
  * ```tsx

package/dist/ReactHydration.mjs

@@ -1,7 +1,7 @@
 "use client";
 import { split } from "./internal/pending.mjs";
 import { sourceOf } from "./internal/sources.mjs";
-import { isServer } from "./internal/registry.mjs";
+import { isServer, requireRequestRegistry } from "./internal/registry.mjs";
 import { HydrationBoundary, RegistryContext } from "@effect/atom-react";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
@@ -36,6 +36,12 @@ import { jsx } from "react/jsx-runtime";
 * there, so an `effect-atom-boundary` boundary sees their failures before
 * its children read them and renders its handler on the server.
 *
+* **Gotchas**
+*
+* In development, it throws during server rendering when the registry isn't
+* a request registry, such as `@effect/atom-react`'s default one, which
+* every request shares: one request's state would reach the others.
+*
 * **Example**
 *
 * ```tsx
@@ -55,6 +61,7 @@ const HydrationBoundary$1 = (props) => {
 	const state = props.state;
 	const source = isServer() ? sourceOf(state) : void 0;
 	const registry = source ?? context;
+	requireRequestRegistry(registry, "HydrationBoundary");
 	const settled = React.useMemo(() => state === void 0 || source !== void 0 ? void 0 : split(registry, state), [
 		registry,
 		source,

package/dist/ReactRouter.d.mts

@@ -70,6 +70,10 @@ export interface AtomsMiddlewareOptions {
  * `seed` runs on the new registry before `next`, so every loader's atoms
  * start with what it sets.
  *
+ * The verbs take the request's `signal`: when the client goes before the
+ * response, such as a navigation that leaves while its loaders wait, the
+ * `ensure` and `fetch` calls still waiting reject with its reason.
+ *
  * **Gotchas**
  *
  * It's server middleware: export it as the root route's `middleware`, not
@@ -110,6 +114,9 @@ export declare const atomsMiddleware: (context: AtomsContext, options?: AtomsMid
  * The registry is the one the mounted `RegistryProvider` provides. Its
  * `dehydrate` returns nothing, so a loader's data has the same shape in
  * the browser and on the server, and `HydrationBoundary` has nothing to do.
+ * The verbs take the navigation's `signal`: when another navigation
+ * interrupts it, the `ensure` and `fetch` calls still waiting reject with
+ * its reason, and the atoms keep loading.
  *
  * **Gotchas**
  *
@@ -131,7 +138,7 @@ export declare const atomsMiddleware: (context: AtomsContext, options?: AtomsMid
  *
  * @stability unstable
  * @category integrations
- * @since 0.2.0
+ * @since 0.2.1
  */
 export declare const clientAtomsMiddleware: (context: AtomsContext) => <Result>(args: MiddlewareArgs, next: () => Promise<Result>) => Promise<Result>;
 export { RegistryProvider };

package/dist/ReactRouter.mjs

@@ -69,6 +69,10 @@ import * as Predicate from "effect/Predicate";
 * `seed` runs on the new registry before `next`, so every loader's atoms
 * start with what it sets.
 *
+* The verbs take the request's `signal`: when the client goes before the
+* response, such as a navigation that leaves while its loaders wait, the
+* `ensure` and `fetch` calls still waiting reject with its reason.
+*
 * **Gotchas**
 *
 * It's server middleware: export it as the root route's `middleware`, not
@@ -99,7 +103,7 @@ const atomsMiddleware = (context, options) => async (args, next) => {
 		registry.dispose();
 		throw error;
 	}
-	const loader = make$1(registry);
+	const loader = make$1(registry, { signal: args.request.signal });
 	args.context.set(context, {
 		...loader,
 		dehydrate: () => dehydrate(registry),
@@ -142,19 +146,6 @@ const disposeAfter = (body, registry) => {
 		}
 	});
 };
-const browserAtoms = /* @__PURE__ */ new WeakMap();
-const browserAtomsOf = (registry) => {
-	let atoms = browserAtoms.get(registry);
-	if (atoms === void 0) {
-		atoms = {
-			...make$1(registry),
-			dehydrate: () => [],
-			registry
-		};
-		browserAtoms.set(registry, atoms);
-	}
-	return atoms;
-};
 /**
 * Creates a root client middleware that gives client loaders the browser's
 * registry, under the context `atomsMiddleware` uses on the server.
@@ -173,6 +164,9 @@ const browserAtomsOf = (registry) => {
 * The registry is the one the mounted `RegistryProvider` provides. Its
 * `dehydrate` returns nothing, so a loader's data has the same shape in
 * the browser and on the server, and `HydrationBoundary` has nothing to do.
+* The verbs take the navigation's `signal`: when another navigation
+* interrupts it, the `ensure` and `fetch` calls still waiting reject with
+* its reason, and the atoms keep loading.
 *
 * **Gotchas**
 *
@@ -194,12 +188,16 @@ const browserAtomsOf = (registry) => {
 *
 * @stability unstable
 * @category integrations
-* @since 0.2.0
+* @since 0.2.1
 */
 const clientAtomsMiddleware = (context) => (args, next) => {
 	const registry = current();
 	if (registry === void 0) throw new Error("clientAtomsMiddleware found no mounted RegistryProvider: render raf-effect-atom/react-router's RegistryProvider around the app in the root layout.");
-	args.context.set(context, browserAtomsOf(registry));
+	args.context.set(context, {
+		...make$1(registry, { signal: args.request.signal }),
+		dehydrate: () => [],
+		registry
+	});
 	return next();
 };
 export { RegistryProvider, atomsMiddleware, clientAtomsMiddleware };

package/dist/internal/next.mjs

@@ -3,13 +3,16 @@ import { make as make$1, settled } from "../RequestRegistry.mjs";
 import { make as make$2 } from "../Loader.mjs";
 import * as React from "react";
 // src/internal/next.ts
+const renderSignal = () => {
+	return React.cacheSignal();
+};
 const make = (options) => {
 	const getRegistry = React.cache(() => {
 		const registry = make$1(options);
-		React.cacheSignal()?.addEventListener("abort", () => registry.dispose(), { once: true });
+		renderSignal()?.addEventListener("abort", () => registry.dispose(), { once: true });
 		return registry;
 	});
-	const getLoader = React.cache(() => make$2(getRegistry()));
+	const getLoader = React.cache(() => make$2(getRegistry(), { signal: renderSignal() ?? void 0 }));
 	return {
 		dehydrate: async () => {
 			const registry = getRegistry();
@@ -19,7 +22,8 @@ const make = (options) => {
 		ensure: (source, ...args) => getLoader().ensure(source, ...args),
 		fetch: (source, ...args) => getLoader().fetch(source, ...args),
 		getRegistry,
-		prefetch: (source, ...args) => getLoader().prefetch(source, ...args)
+		prefetch: (source, ...args) => getLoader().prefetch(source, ...args),
+		run: (effect, runOptions) => getLoader().run(effect, runOptions)
 	};
 };
 export { make };

package/dist/internal/registry.mjs

@@ -1,8 +1,18 @@
-import { make as make$1 } from "../RequestRegistry.mjs";
+import { isDevelopment } from "./development.mjs";
+import { isRequestRegistry, make as make$1 } from "../RequestRegistry.mjs";
+import * as Effect from "effect/Effect";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 import { scheduleTask } from "@effect/atom-react";
 // src/internal/registry.ts
 const isServer = () => !("window" in globalThis);
+/**
+* In development, throws when `rendered` renders on the server without a
+* request registry: in one every request shares, such as
+* `@effect/atom-react`'s default `RegistryContext`.
+*/
+const requireRequestRegistry = (registry, rendered) => {
+	if (isServer() && !isRequestRegistry(registry) && Effect.runSync(isDevelopment)) throw new Error(`raf-effect-atom: ${rendered} rendered on the server without a request registry, so results would be shared between requests. Provide RequestRegistry.make() through RegistryContext, as the framework integrations do.`);
+};
 /** `@effect/atom-react`'s default registry keeps an unused atom this long. */
 const defaultIdleTTL = 400;
 /**
@@ -27,4 +37,4 @@ const mount = (registry) => {
 };
 /** The browser registry of the mounted `RegistryProvider`, if one is. */
 const current = () => mounted;
-export { current, isServer, make, mount };
+export { current, isServer, make, mount, requireRequestRegistry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raf-effect-atom",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Render-as-you-fetch for Effect Atom: start atoms from route loaders and stream them into the browser, typed failures intact",
   "keywords": [
     "effect",