@shivaedev/react 0.0.0 → 0.19.0

package/package.json

@@ -1,10 +1,110 @@
 {
   "name": "@shivaedev/react",
-  "version": "0.0.0",
-  "description": "Placeholder for the ShivaeDev react package.",
-  "license": "MIT",
+  "version": "0.19.0",
+  "description": "React query, action, editor and session hooks for native Effect atoms",
+  "keywords": [
+    "effect"
+  ],
+  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/react#readme",
+  "bugs": {
+    "url": "https://github.com/ShivaeDev/platform/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ShivaeDev/platform.git"
+    "url": "git+https://github.com/ShivaeDev/platform.git",
+    "directory": "packages/react"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {
+    "#test/*": "./src/test-support/*",
+    "#*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "exports": {
+    "./*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./internal/*": null,
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/*.spec.tsx",
+    "!src/**/test-support",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "dependencies": {
+    "@shivaedev/contract": "0.17.0",
+    "@shivaedev/form": "0.7.0",
+    "@shivaedev/test": "0.10.0"
+  },
+  "devDependencies": {
+    "@effect/atom-react": "4.0.5",
+    "@effect/platform-node": "4.0.5",
+    "@effect/sql-pg": "4.0.5",
+    "@effect/sql-sqlite-node": "4.0.5",
+    "@shivaedev/identity": "0.1.0",
+    "@shivaedev/jobs": "0.20.0",
+    "@shivaedev/local-postgres": "0.7.0",
+    "@shivaedev/quality": "0.42.0",
+    "@shivaedev/server": "0.1.0",
+    "@shivaedev/service": "0.5.0",
+    "@shivaedev/sql": "0.22.0",
+    "@shivaedev/test-sql": "0.10.0",
+    "@shivaedev/test-story": "0.21.0",
+    "@tanstack/react-router": "1.170.45",
+    "@types/node": "24.19.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "effect": "4.0.5",
+    "happy-dom": "21.0.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "@effect/atom-react": "4.0.5",
+    "@tanstack/react-router": "1.170.45",
+    "effect": "4.0.5",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "vitest": "5.0.5"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-router": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc --project tsconfig.build.json",
+    "ready": "pnpm typecheck && pnpm test && pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/actionTrace.ts

@@ -0,0 +1,5 @@
+import { Effect } from "effect";
+
+export function actionTrace<A, E, R>(effect: Effect.Effect<A, E, R>, name = "ui.action"): Effect.Effect<A, E, R> {
+	return Effect.withSpan(effect, name, { root: true });
+}

package/src/client/QueryView.ts

@@ -0,0 +1,27 @@
+import { Cause, Option, Result } from "effect";
+import { createElement, Fragment, type ReactNode } from "react";
+import type { QueryState } from "./resultState.ts";
+
+export interface QueryViewProps<A, E> {
+	readonly content: (data: A, query: QueryState<A, E>) => ReactNode;
+	readonly failure: (error: E, query: QueryState<A, E>) => ReactNode;
+	readonly loading: (query: QueryState<A, E>) => ReactNode;
+	readonly query: QueryState<A, E>;
+}
+
+export function QueryView<A, E>({ query, loading, content, failure }: QueryViewProps<A, E>): ReactNode {
+	const error = Option.flatMap(query.cause, (cause) => {
+		const defect = Cause.findDefect(cause);
+		if (Result.isSuccess(defect)) {
+			throw defect.success;
+		}
+		return Cause.findErrorOption(cause);
+	});
+	return createElement(
+		Fragment,
+		null,
+		Option.isSome(query.data) ? content(query.data.value, query) : null,
+		query.pending || (Option.isNone(query.data) && Option.isNone(error)) ? loading(query) : null,
+		Option.isSome(error) ? failure(error.value, query) : null,
+	);
+}

package/src/client/actionCompletion.ts

@@ -0,0 +1,82 @@
+import { RegistryContext } from "@effect/atom-react";
+import { Effect, Predicate } from "effect";
+import type * as Atom from "effect/reactivity/Atom";
+import { useContext, useInsertionEffect, useMemo, useRef } from "react";
+import type { AtomServices } from "#fieldRejection.ts";
+import { NoticeContext } from "#internal/NoticeContext.ts";
+import { publishNotice } from "#internal/noticeStore.ts";
+import type { NoticeFeedback } from "#notices.ts";
+import { useSessionRecheck } from "./sessionBoundary.ts";
+
+export interface ActionOptions<TInput, A, E, R = never> {
+	readonly concurrent?: boolean;
+	readonly notices?: NoticeFeedback<TInput, A, E, R>;
+	readonly onFailure?: (error: E, input: TInput) => void;
+	readonly onSuccess?: (value: A, input: TInput) => void;
+}
+
+export function useActionSource<TInput, A, E, R, TRuntimeError>(
+	source: Atom.AtomResultFn<TInput, A, E> | Atom.AtomRuntime<R, TRuntimeError>,
+	run: ((input: TInput) => Effect.Effect<A, E, AtomServices<R>>) | undefined,
+	options: ActionOptions<TInput, A, E, R>,
+): Atom.AtomResultFn<TInput, A, E | TRuntimeError> {
+	const registry = useContext(RegistryContext);
+	const recheck = useSessionRecheck();
+	const notices = useContext(NoticeContext);
+	const latestRef = useRef({ options, recheck, run });
+	useInsertionEffect(() => {
+		latestRef.current = { options, recheck, run };
+	}, [options, recheck, run]);
+	const concurrent = options.concurrent;
+	const owner = useMemo(() => {
+		const lifetime = { active: false, registry };
+		function rejected(error: E, input: TInput) {
+			return Effect.gen(function* () {
+				if (lifetime.active && Predicate.isTagged(error, "Unauthorized")) {
+					yield* Effect.sync(() => latestRef.current.recheck());
+				}
+				yield* Effect.sync(() => {
+					if (lifetime.active) {
+						latestRef.current.options.onFailure?.(error, input);
+						if ("fn" in source) {
+							publishNotice(notices, source, latestRef.current.options.notices?.onFailure?.(error, input));
+						}
+					}
+				});
+				return yield* Effect.fail(error);
+			});
+		}
+		function completed(value: A, input: TInput) {
+			return Effect.sync(() => {
+				if (lifetime.active) {
+					latestRef.current.options.onSuccess?.(value, input);
+					if ("fn" in source) {
+						publishNotice(notices, source, latestRef.current.options.notices?.onSuccess?.(value, input));
+					}
+				}
+				return value;
+			});
+		}
+		function execute(input: TInput) {
+			return Effect.suspend(() => {
+				const command = latestRef.current.run;
+				if (!command) {
+					return Effect.die(new Error("Missing command Effect"));
+				}
+				return Effect.matchEffect(command(input), {
+					onFailure: (error) => rejected(error, input),
+					onSuccess: (value) => completed(value, input),
+				});
+			});
+		}
+		const atom = "fn" in source ? source.fn(execute, { concurrent }) : source;
+		return { atom, lifetime };
+	}, [source, registry, concurrent, notices]);
+	useInsertionEffect(() => {
+		owner.lifetime.active = true;
+		return () => {
+			owner.lifetime.active = false;
+		};
+	}, [owner]);
+	return owner.atom;
+}

package/src/client/authAction.ts

@@ -0,0 +1,22 @@
+import { Data, Effect } from "effect";
+import * as Atom from "effect/reactivity/Atom";
+
+export class AuthActionUnavailable extends Data.TaggedError("AuthActionUnavailable")<{
+	readonly cause: unknown;
+}> {}
+
+export interface AuthActionResult<A, E> {
+	readonly data: A;
+	readonly error: E | null;
+}
+
+export function authAction<TInput, A, E extends object = never>(
+	run: (input: TInput, signal: AbortSignal) => Promise<AuthActionResult<A, E>>,
+): Atom.AtomResultFn<TInput, A, E | AuthActionUnavailable> {
+	return Atom.fn<TInput>()((input) =>
+		Effect.tryPromise({
+			catch: (cause) => new AuthActionUnavailable({ cause }),
+			try: (signal) => run(input, signal),
+		}).pipe(Effect.flatMap((result) => (result.error === null ? Effect.succeed(result.data) : Effect.fail(result.error)))),
+	);
+}

package/src/client/create.ts

@@ -0,0 +1,55 @@
+import { type Effect, Equal, Option, type Schema } from "effect";
+import type * as Atom from "effect/reactivity/Atom";
+import { useCallback, useState } from "react";
+import { type BrowserDraftConfig, usePersistedDraft } from "@shivaedev/form/client/react.ts";
+import type { Decoded, Encoded, FieldFailure, Fields, Form, Services } from "@shivaedev/form/shape.ts";
+import type { AtomServices, FieldRejectionMapping } from "#fieldRejection.ts";
+import { useSubmissionCallbacks } from "#internal/useSubmissionCallbacks.ts";
+import type { NoticeFeedback } from "#notices.ts";
+import { submission } from "#submission.ts";
+import { type SaveState, useSaveState } from "./saveState.ts";
+export type CreateConfig<TFields extends Fields, TCreated, TSaveError, R, TRuntimeError> = {
+	readonly persistedDraft?: BrowserDraftConfig | undefined;
+	readonly fields: Schema.Struct<TFields>;
+	readonly initialValues: Encoded<TFields>;
+	readonly create: (values: Decoded<TFields>) => Effect.Effect<TCreated, TSaveError, AtomServices<R>>;
+	readonly runtime: Atom.AtomRuntime<Services<TFields, R>, TRuntimeError>;
+	readonly notices?: NoticeFeedback<Decoded<TFields>, TCreated, TSaveError, Services<TFields, R>>;
+} & FieldRejectionMapping<TFields, TSaveError>;
+export interface Create<TFields extends Fields, TCreated, TSaveError, TRuntimeError> extends SaveState<TSaveError | TRuntimeError> {
+	readonly created: Option.Option<TCreated>;
+	readonly form: Form<TFields, TCreated, TSaveError | FieldFailure, TRuntimeError>;
+}
+function editedSince<TV extends object>(current: TV, submitted: TV | undefined): Readonly<Record<string, unknown>> {
+	const before = new Map(Object.entries(submitted ?? current));
+	return Object.fromEntries(Object.entries(current).filter(([name, value]) => !Equal.equals(value, before.get(name))));
+}
+export function useCreate<TFields extends Fields, TCreated, TSaveError, R, TRuntimeError>(
+	config: CreateConfig<TFields, TCreated, TSaveError, R, TRuntimeError>,
+): Create<TFields, TCreated, TSaveError, TRuntimeError> {
+	const persistedDraft = usePersistedDraft(config.persistedDraft);
+	const callbacks = useSubmissionCallbacks(config.fields, config.create, config.rejectField, config.runtime, config.notices);
+	function initialize() {
+		const { fields, initialValues, runtime } = config;
+		function makeSubmission() {
+			return submission({ ...callbacks, fields, initialValues, persistedDraft, runtime });
+		}
+		return { baseline: initialValues, created: Option.none<TCreated>(), current: makeSubmission(), fields, fresh: makeSubmission, runtime };
+	}
+	const [held, hold] = useState(initialize);
+	let entry = held;
+	if (entry.fields !== config.fields || entry.runtime !== config.runtime) {
+		entry = initialize();
+		hold(entry);
+	}
+	const { baseline, created, current, fresh } = entry;
+	const settled = useCallback(
+		(value: TCreated) => {
+			const next = fresh();
+			next.form.values.set({ ...baseline, ...editedSince(current.form.values.value, current.submitted()) });
+			hold({ ...entry, created: Option.some(value), current: next });
+		},
+		[entry, current, fresh, baseline],
+	);
+	return { ...useSaveState(current.form, settled), created, form: current.form };
+}

package/src/client/editor.ts

@@ -0,0 +1,89 @@
+import { type Effect, Option, type Schema } from "effect";
+import type * as AsyncResult from "effect/reactivity/AsyncResult";
+import type * as Atom from "effect/reactivity/Atom";
+import { useCallback, useEffect, useState } from "react";
+import { type BrowserDraftConfig, usePersistedDraft } from "@shivaedev/form/client/react.ts";
+import type { Decoded, Encoded, FieldFailure, Fields, Form, Services } from "@shivaedev/form/shape.ts";
+import type { AtomServices, FieldRejectionMapping } from "#fieldRejection.ts";
+import { loadedQuery } from "#internal/loadedQuery.ts";
+import { useSubmissionCallbacks } from "#internal/useSubmissionCallbacks.ts";
+import type { NoticeFeedback } from "#notices.ts";
+import { submission } from "#submission.ts";
+import { type QueryOptions, type QueryState, useQuery } from "./resultState.ts";
+import { type SaveState, useSaveState } from "./saveState.ts";
+import type { LoadedQueryState } from "./useLoaderQuery.ts";
+export type EditorConfig<TFields extends Fields, TRow, TQueryError, TSaveError, R, TRuntimeError> = {
+	readonly persistedDraft?: BrowserDraftConfig | undefined;
+	readonly query: Atom.Atom<AsyncResult.AsyncResult<TRow, TQueryError>>;
+	readonly fields: Schema.Struct<TFields>;
+	readonly values: (row: TRow) => Encoded<TFields>;
+	readonly save: (values: Decoded<TFields>) => Effect.Effect<TRow, TSaveError, AtomServices<R>>;
+	readonly runtime: Atom.AtomRuntime<Services<TFields, R>, TRuntimeError>;
+	readonly notices?: NoticeFeedback<Decoded<TFields>, TRow, TSaveError, Services<TFields, R>>;
+	readonly queryNotice?: QueryOptions<TQueryError>["notice"];
+} & FieldRejectionMapping<TFields, TSaveError>;
+export interface Editor<TFields extends Fields, TRow, TQueryError, TSaveError, TRuntimeError> extends SaveState<TSaveError | TRuntimeError> {
+	readonly form: Form<TFields, TRow, TSaveError | FieldFailure, TRuntimeError> | undefined;
+	readonly query: QueryState<TRow, TQueryError>;
+}
+export interface LoadedEditor<TFields extends Fields, TRow, TQueryError, TSaveError, TRuntimeError>
+	extends Omit<Editor<TFields, TRow, TQueryError, TSaveError, TRuntimeError>, "form" | "query"> {
+	readonly form: Form<TFields, TRow, TSaveError | FieldFailure, TRuntimeError>;
+	readonly query: LoadedQueryState<TRow, TQueryError>;
+}
+interface Held<TFields extends Fields, TRow, TSaveError, R, TRuntimeError> {
+	readonly fields: Schema.Struct<TFields>;
+	readonly form: Form<TFields, TRow, TSaveError | FieldFailure, TRuntimeError>;
+	readonly query: Atom.Atom<unknown>;
+	readonly runtime: Atom.AtomRuntime<Services<TFields, R>, TRuntimeError>;
+	readonly values: (row: TRow) => Encoded<TFields>;
+}
+export function useEditor<TFields extends Fields, TRow, TQueryError, TSaveError, R, TRuntimeError>(
+	config: EditorConfig<TFields, TRow, TQueryError, TSaveError, R, TRuntimeError> & { readonly loaded: TRow },
+): LoadedEditor<TFields, TRow, TQueryError, TSaveError, TRuntimeError>;
+export function useEditor<TFields extends Fields, TRow, TQueryError, TSaveError, R, TRuntimeError>(
+	config: EditorConfig<TFields, TRow, TQueryError, TSaveError, R, TRuntimeError>,
+): Editor<TFields, TRow, TQueryError, TSaveError, TRuntimeError>;
+export function useEditor<TFields extends Fields, TRow, TQueryError, TSaveError, R, TRuntimeError>(
+	config: EditorConfig<TFields, TRow, TQueryError, TSaveError, R, TRuntimeError> & { readonly loaded?: TRow },
+): Editor<TFields, TRow, TQueryError, TSaveError, TRuntimeError> | LoadedEditor<TFields, TRow, TQueryError, TSaveError, TRuntimeError> {
+	const persistedDraft = usePersistedDraft(config.persistedDraft);
+	const callbacks = useSubmissionCallbacks(config.fields, config.save, config.rejectField, config.runtime, config.notices);
+	const query = useQuery(config.query, config.queryNotice === undefined ? {} : { notice: config.queryNotice });
+	const row = Option.orElse(query.data, () => ("loaded" in config ? Option.some(config.loaded) : Option.none()));
+	const [held, hold] = useState<Held<TFields, TRow, TSaveError, R, TRuntimeError> | undefined>(undefined);
+	let current = held?.query === config.query && held.fields === config.fields && held.runtime === config.runtime ? held : undefined;
+	if (current === undefined && Option.isSome(row)) {
+		current = {
+			fields: config.fields,
+			form: submission({
+				...callbacks,
+				fields: config.fields,
+				initialValues: config.values(row.value),
+				persistedDraft,
+				runtime: config.runtime,
+			}).form,
+			query: config.query,
+			runtime: config.runtime,
+			values: config.values,
+		};
+		hold(current);
+	}
+	const form = current?.form;
+	const values = current?.values;
+	const received = Option.getOrUndefined(row);
+	useEffect(() => {
+		if (form && values && received !== undefined) {
+			form.receive(values(received));
+		}
+	}, [form, values, received]);
+	const settled = useCallback((saved: TRow) => (form && values ? form.receive(values(saved)) : undefined), [form, values]);
+	const saveState = useSaveState(form, settled);
+	if ("loaded" in config) {
+		if (!form) {
+			throw new Error("A loaded editor requires a row");
+		}
+		return { ...saveState, form, query: loadedQuery(query, config.loaded) };
+	}
+	return { ...saveState, form, query };
+}

package/src/client/mountLive.ts

@@ -0,0 +1,57 @@
+import { Cause, type Duration, Option, Predicate } from "effect";
+import * as Atom from "effect/reactivity/Atom";
+import type * as AtomRegistry from "effect/reactivity/AtomRegistry";
+import { type LiveBound, LiveConnection } from "@shivaedev/contract/automaticLive.ts";
+import { recheckUnauthorized } from "#internal/sessionRecheck.ts";
+
+function isLiveBound(value: unknown): value is LiveBound {
+	return Predicate.hasProperty(value, LiveConnection);
+}
+
+function recheckFailure(registry: AtomRegistry.AtomRegistry, failure: Option.Option<Cause.Cause<unknown>>) {
+	const error = Option.flatMap(failure, Cause.findErrorOption);
+	if (Option.isSome(error)) {
+		void recheckUnauthorized(registry, error.value);
+	}
+}
+
+export function mountLive(registry: AtomRegistry.AtomRegistry, client: unknown, coalesceWindow?: Duration.Input) {
+	const releases: Array<() => void> = [];
+	const found = new Set<unknown>();
+	function mount(value: unknown) {
+		if (!isLiveBound(value)) {
+			return;
+		}
+		const live = value[LiveConnection];
+		if (Predicate.hasProperty(live, "connection") && Atom.isAtom(live.connection) && !found.has(live.connection)) {
+			if (
+				coalesceWindow !== undefined
+				&& Predicate.hasProperty(live, "coalesceWindow")
+				&& Atom.isAtom(live.coalesceWindow)
+				&& Atom.isWritable(live.coalesceWindow)
+			) {
+				registry.set(live.coalesceWindow, coalesceWindow);
+			}
+			found.add(live.connection);
+			releases.push(
+				registry.subscribe(
+					Atom.map(live.status, (status) => status.failure),
+					(failure) => recheckFailure(registry, failure),
+					{ immediate: true },
+				),
+			);
+			releases.push(registry.mount(live.connection));
+		}
+	}
+	mount(client);
+	if (typeof client === "object" && client !== null) {
+		for (const value of Object.values(client)) {
+			mount(value);
+		}
+	}
+	return () => {
+		for (const release of releases) {
+			release();
+		}
+	};
+}

package/src/client/pendingCommand.ts

@@ -0,0 +1,42 @@
+import { RegistryContext, useAtomValue } from "@effect/atom-react";
+import { Option } from "effect";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+import * as Atom from "effect/reactivity/Atom";
+import { useContext, useMemo, useState } from "react";
+import { type ActionState, useAction } from "./resultState.ts";
+
+export interface PendingCommandOptions<TInput, TValue> {
+	readonly queries: readonly Atom.Atom<AsyncResult.AsyncResult<unknown, unknown>>[];
+	readonly value: TValue;
+	readonly wanted: (input: TInput) => TValue;
+}
+export interface PendingCommandState<TInput, A, E, TValue> extends ActionState<TInput, A, E> {
+	readonly value: TValue;
+}
+
+export function usePendingCommand<TInput, A, E, TValue>(
+	atom: Atom.AtomResultFn<TInput, A, E>,
+	options: PendingCommandOptions<TInput, TValue>,
+): PendingCommandState<TInput, A, E, TValue> {
+	const action = useAction(atom);
+	const registry = useContext(RegistryContext);
+	const { queries, value, wanted } = options;
+	const waiting = useMemo(() => Atom.make((get) => queries.map((query) => get(query).waiting).some(Boolean)), [queries]);
+	const refreshing = useAtomValue(waiting);
+	const [held, hold] = useState({ atom, registry, value: Option.none<TValue>() });
+	const sameOwner = held.atom === atom && held.registry === registry;
+	const failed = AsyncResult.isFailure(action.result) && !action.pending;
+	const pending = sameOwner && Option.isSome(held.value) && !failed && (action.pending || refreshing);
+	if (!sameOwner || (Option.isSome(held.value) && !pending)) {
+		hold({ atom, registry, value: Option.none() });
+	}
+	return {
+		...action,
+		dispatch: (input) => {
+			hold({ atom, registry, value: Option.some(wanted(input)) });
+			action.dispatch(input);
+		},
+		pending: action.pending || pending,
+		value: pending ? Option.getOrElse(held.value, () => value) : value,
+	};
+}

package/src/client/resultState.ts

@@ -0,0 +1,102 @@
+import { RegistryContext, useAtomRefresh, useAtomSet, useAtomValue } from "@effect/atom-react";
+import { Cause, type Duration, type Effect, Option, Predicate } from "effect";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+import type * as Atom from "effect/reactivity/Atom";
+import type * as AtomRegistry from "effect/reactivity/AtomRegistry";
+import { useContext, useEffect, useState } from "react";
+import { queryCoalesceWindow } from "@shivaedev/contract/queryCoalesceWindow.ts";
+import type { AtomServices } from "#fieldRejection.ts";
+import { acceptLoaderQuery } from "#internal/queryHandoff.ts";
+import { useQueryNotice } from "#internal/useQueryNotice.ts";
+import type { NoticeDescriptor } from "#notices.ts";
+import { type ActionOptions, useActionSource } from "./actionCompletion.ts";
+import { useSessionRecheck } from "./sessionBoundary.ts";
+
+export interface ResultState<A, E> {
+	readonly cause: Option.Option<Cause.Cause<E>>;
+	readonly data: Option.Option<A>;
+	readonly pending: boolean;
+	readonly refreshing: boolean;
+	readonly result: AsyncResult.AsyncResult<A, E>;
+}
+function state<A, E>(result: AsyncResult.AsyncResult<A, E>, data = AsyncResult.value(result)): ResultState<A, E> {
+	return {
+		cause: AsyncResult.cause(result),
+		data,
+		pending: result.waiting,
+		refreshing: result.waiting && Option.isSome(data),
+		result,
+	};
+}
+export function isUnauthorized<E>(cause: Cause.Cause<E>): boolean {
+	return Option.match(Cause.findErrorOption(cause), { onNone: () => false, onSome: (error) => Predicate.isTagged(error, "Unauthorized") });
+}
+function useRecheckOnUnauthorized<A, E>(result: AsyncResult.AsyncResult<A, E>, enabled = true): void {
+	const recheck = useSessionRecheck();
+	useEffect(() => {
+		if (enabled && AsyncResult.isFailure(result) && isUnauthorized(result.cause)) {
+			recheck();
+		}
+	}, [enabled, recheck, result]);
+}
+export interface QueryState<A, E> extends ResultState<A, E> {
+	readonly refresh: () => void;
+}
+export interface QueryOptions<E = unknown> {
+	readonly coalesceWindow?: Duration.Input | undefined;
+	readonly keepPreviousData?: boolean;
+	readonly notice?: (failure: { readonly cause: Cause.Cause<E>; readonly refreshing: boolean }) => NoticeDescriptor | undefined;
+}
+interface HeldQuery<A, E> {
+	readonly atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>;
+	readonly data: Option.Option<A>;
+	readonly dataAtom: Atom.Atom<AsyncResult.AsyncResult<A, E>>;
+	readonly keepPreviousData: boolean;
+	readonly registry: AtomRegistry.AtomRegistry;
+	readonly result: AsyncResult.AsyncResult<A, E>;
+}
+export function useQuery<A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>, options: QueryOptions<E> = {}): QueryState<A, E> {
+	const result = useAtomValue(atom);
+	const registry = useContext(RegistryContext);
+	useEffect(() => acceptLoaderQuery(registry, atom), [registry, atom]);
+	useEffect(() => {
+		if (options.coalesceWindow === undefined) {
+			return;
+		}
+		const window = queryCoalesceWindow(atom);
+		registry.set(window, options.coalesceWindow);
+		return () => registry.set(window, undefined);
+	}, [registry, atom, options.coalesceWindow]);
+	const keepPreviousData = options.keepPreviousData === true;
+	const nativeData = AsyncResult.value(result);
+	const [held, hold] = useState<HeldQuery<A, E>>(() => ({ atom, data: nativeData, dataAtom: atom, keepPreviousData, registry, result }));
+	const previous = held.registry === registry && (held.dataAtom === atom || keepPreviousData) ? held.data : Option.none<A>();
+	const data = Option.orElse(nativeData, () => previous);
+	const dataAtom = Option.isSome(nativeData) || Option.isNone(previous) ? atom : held.dataAtom;
+	// Render state keeps abandoned React renders from changing the committed screen's retained value.
+	if (held.atom !== atom || held.registry !== registry || held.result !== result || held.keepPreviousData !== keepPreviousData) {
+		hold({ atom, data, dataAtom, keepPreviousData, registry, result });
+	}
+	useRecheckOnUnauthorized(result);
+	useQueryNotice(result, Option.isSome(data), options.notice);
+	return { ...state(result, data), refresh: useAtomRefresh(atom) };
+}
+export interface ActionState<TInput, A, E> extends ResultState<A, E> {
+	readonly dispatch: (input: TInput) => void;
+}
+export function useAction<TInput, A, E>(atom: Atom.AtomResultFn<TInput, A, E>): ActionState<TInput, A, E>;
+export function useAction<TInput, A, E, R, TRuntimeError>(
+	runtime: Atom.AtomRuntime<R, TRuntimeError>,
+	run: (input: TInput) => Effect.Effect<A, E, AtomServices<R>>,
+	options?: ActionOptions<NoInfer<TInput>, NoInfer<A>, NoInfer<E>, R>,
+): ActionState<TInput, A, E | TRuntimeError>;
+export function useAction<TInput, A, E, R, TRuntimeError>(
+	source: Atom.AtomResultFn<TInput, A, E> | Atom.AtomRuntime<R, TRuntimeError>,
+	run?: (input: TInput) => Effect.Effect<A, E, AtomServices<R>>,
+	options: ActionOptions<TInput, A, E, R> = {},
+): ActionState<TInput, A, E | TRuntimeError> {
+	const atom = useActionSource(source, run, options);
+	const result = useAtomValue(atom);
+	useRecheckOnUnauthorized(result, run === undefined);
+	return { ...state(result), dispatch: useAtomSet(atom) };
+}

package/src/client/saveState.ts

@@ -0,0 +1,54 @@
+import { RegistryContext, useAtomValue } from "@effect/atom-react";
+import { Option } from "effect";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+import * as Atom from "effect/reactivity/Atom";
+import { useCallback, useContext, useEffect } from "react";
+import { FieldFailure, type Fields, type Form, Invalid } from "@shivaedev/form/shape.ts";
+import { isUnauthorized } from "./resultState.ts";
+import { useSessionRecheck } from "./sessionBoundary.ts";
+
+const idle = Atom.make(AsyncResult.initial());
+const clean = Atom.make(false);
+export interface SaveState<E> {
+	readonly dirty: boolean;
+	readonly failure: Option.Option<E>;
+	readonly revert: () => void;
+	readonly save: () => void;
+	readonly saving: boolean;
+}
+export function useSaveState<TFields extends Fields, A, E, TRuntimeError>(
+	form: Form<TFields, A, E | FieldFailure, TRuntimeError> | undefined,
+	settled: (result: A) => void,
+): SaveState<E | TRuntimeError> {
+	const registry = useContext(RegistryContext);
+	const recheck = useSessionRecheck();
+	const result: AsyncResult.AsyncResult<A, E | TRuntimeError | FieldFailure | Invalid> = useAtomValue(form?.submit ?? idle);
+	const dirty = useAtomValue(form?.dirty ?? clean);
+	useEffect(() => {
+		if (AsyncResult.isFailure(result) && isUnauthorized(result.cause)) {
+			recheck();
+		}
+	}, [recheck, result]);
+	useEffect(
+		() =>
+			form
+			&& registry.subscribe(form.submit, (next) => {
+				if (AsyncResult.isSuccess(next) && !next.waiting) {
+					settled(next.value);
+				}
+			}),
+		[form, registry, settled],
+	);
+	const save = useCallback(() => {
+		if (form === undefined || registry.get(form.submit).waiting) {
+			return;
+		}
+		registry.set(form.submit, undefined);
+	}, [form, registry]);
+	const revert = useCallback(() => form?.revert(), [form]);
+	const failure = Option.filter(
+		AsyncResult.error(result),
+		(error): error is E | TRuntimeError => !(error instanceof FieldFailure || error instanceof Invalid),
+	);
+	return { dirty, failure, revert, save, saving: result.waiting };
+}