@thomasfosterau/effect-sveltekit 0.5.0 → 0.6.0

package/dist/forms.d.ts

@@ -1,29 +1,92 @@
-import { EnhanceHandlers, EnhanceOptions, EnhanceRuntime, ResultOptions, SubmitInput } from "./internal/enhance.js";
+import { EnhanceHandlerKey, EnhanceHandlers, EnhanceHandlersBy, EnhanceOptions, EnhanceOptionsArgs, EnhanceRuntime, HandlerErrors, HandlerKeys, OnErrorAccepts, OnErrorInput, RequiredServices, ResultOptions, SubmitInput } from "./internal/enhance.js";
 import "./forms.js";
 import { Effect } from "effect";
 import { ActionResult } from "$app/forms";
 declare namespace forms_d_exports {
-  export { EnhanceHandlers, EnhanceOptions, EnhanceRuntime, ResultOptions, SubmitInput, applyAction$1 as applyAction, deserialize$1 as deserialize, enhance };
+  export { ApplyActionError, EnhanceHandlers, EnhanceOptions, EnhanceOptionsArgs, EnhanceRuntime, ResultOptions, SubmitInput, applyAction$1 as applyAction, deserialize$1 as deserialize, enhance };
 }
 /**
  * Build a `SubmitFunction` for `use:enhance` from Effect-based handlers.
  *
  * `onSubmit` runs before the request (call `input.cancel()` to abort);
  * `onResult` runs on the response with SvelteKit's `update()`. Omit `onResult`
- * to keep SvelteKit's default behaviour. Pass `{ runtime }` when the handlers
- * require application services.
+ * to keep SvelteKit's default behaviour. When the handlers (or `onError`)
+ * require application services, pass `{ runtime }` (a `Context` or
+ * `ManagedRuntime` providing them): it is then required, and a call without it
+ * does not type-check. Each handler may require different services; the runtime
+ * must provide all of them. A missing runtime is reported on the call, and one
+ * that lacks a service on the runtime, never on a handler; the message may at
+ * first name only the services of the handlers TypeScript types first (such as
+ * an `onError` passed by name), and the rest once the runtime provides those.
+ * Handlers that require no services run on the default runtime, and the options
+ * may be omitted; an effect typed as requiring `any` or `unknown` is treated as
+ * requiring no services, so no runtime is demanded. A function that wraps
+ * `enhance` for handlers requiring any `R` forwards its options as
+ * `...options: EnhanceOptionsArgs<R>` (or takes a required
+ * `{ runtime: EnhanceRuntime<R> }`): an `EnhanceOptions<R>`, whose runtime is
+ * optional, does not type-check there.
+ *
+ * Either handler may fail. Add an `onError` handler to handle the error
+ * (typed as the union of the handlers' error types when written after them;
+ * `unknown` when written before a handler with unannotated parameters): a
+ * failed `onSubmit` also cancels the submission, and a failed `onResult` does
+ * not fall back to SvelteKit's default behaviour. Without `onError`, or for a
+ * defect or interruption, the promise SvelteKit awaits rejects (with the error
+ * itself for a failure), which SvelteKit leaves unhandled.
+ *
+ * @example
+ * ```ts
+ * const submit = Forms.enhance({
+ *   onResult: ({ result }) => Forms.applyAction(result),
+ *   // error: ApplyActionError
+ *   onError: (error) => Effect.logWarning("applyAction failed", error.cause),
+ * });
+ * ```
+ */
+declare const enhance: <RSubmit = unknown, RResult = unknown, RError = unknown, ESubmit = any, EResult = any, Keys extends EnhanceHandlerKey = never, E = OnErrorInput<HandlerErrors<Keys, ESubmit, EResult>>>(handlers: EnhanceHandlersBy<RSubmit, RResult, RError, ESubmit, EResult, E> & HandlerKeys<Keys> & NoInfer<OnErrorAccepts<RError, HandlerErrors<Keys, ESubmit, EResult>, E>>, ...rest: NoInfer<EnhanceOptionsArgs<RequiredServices<RSubmit> | RequiredServices<RResult> | RequiredServices<RError>>>) => import("$app/forms").SubmitFunction;
+declare const ApplyActionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "ApplyActionError";
+} & Readonly<A>;
+/**
+ * {@link applyAction} rejected or threw. `cause` is SvelteKit's original
+ * reason, unchanged.
+ *
+ * SvelteKit 3 throws when `applyAction` is called during server rendering, and
+ * follows a `redirect` result with a client-side navigation that rejects if it
+ * fails: for example, a `location` that cannot be parsed even relative to the
+ * page's base URL, or a `beforeNavigate` / `onNavigate` callback that throws. Recover with
+ * `Effect.catchTag("ApplyActionError", ...)`.
  */
-declare const enhance: <R = never>(handlers: EnhanceHandlers<R>, options?: EnhanceOptions<R>) => import("$app/forms").SubmitFunction;
+declare class ApplyActionError extends ApplyActionError_base<{
+  /** The rejection reason, or the value thrown, as SvelteKit produced it. */
+  readonly cause: unknown;
+}> {}
 /**
  * Apply an `ActionResult` to the page (updating `page.form` / `page.status`,
  * resetting the form, etc.) as an Effect. Wraps `$app/forms`' `applyAction`.
+ *
+ * Fails with an {@link ApplyActionError} if SvelteKit rejects or throws: for
+ * example, when the navigation that follows a `redirect` result fails, or when
+ * called during server rendering.
+ *
+ * {@link enhance}'s `onResult` can return it directly; its `onError` handler
+ * then receives the `ApplyActionError`. Without `onError`, the error rejects
+ * the promise SvelteKit awaits.
+ *
+ * @example
+ * ```ts
+ * const submit = Forms.enhance({
+ *   onResult: ({ result }) => Forms.applyAction(result),
+ *   onError: (error) => Effect.logWarning("applyAction failed", error.cause),
+ * });
+ * ```
  */
-declare const applyAction$1: <Success extends Record<string, unknown> | undefined = Record<string, unknown>, Failure extends Record<string, unknown> | undefined = Record<string, unknown>>(result: ActionResult<Success, Failure>) => Effect.Effect<void>;
+declare const applyAction$1: <Success extends Record<string, unknown> | undefined = Record<string, unknown>, Failure extends Record<string, unknown> | undefined = Record<string, unknown>>(result: ActionResult<Success, Failure>) => Effect.Effect<void, ApplyActionError>;
 /**
  * Deserialize a raw form-action response body into an `ActionResult`, as an
  * Effect. Wraps `$app/forms`' `deserialize`; a malformed body fails the effect.
  */
 declare const deserialize$1: <Success extends Record<string, unknown> | undefined = Record<string, unknown>, Failure extends Record<string, unknown> | undefined = Record<string, unknown>>(result: string) => Effect.Effect<ActionResult<Success, Failure>, unknown>;
 //#endregion
-export { type EnhanceHandlers, type EnhanceOptions, type EnhanceRuntime, type ResultOptions, type SubmitInput, applyAction$1 as applyAction, deserialize$1 as deserialize, enhance, forms_d_exports };
+export { ApplyActionError, type EnhanceHandlers, type EnhanceOptions, type EnhanceOptionsArgs, type EnhanceRuntime, type ResultOptions, type SubmitInput, applyAction$1 as applyAction, deserialize$1 as deserialize, enhance, forms_d_exports };
 //# sourceMappingURL=forms.d.ts.map

package/dist/forms.js

@@ -1,6 +1,6 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
 import { makeSubmitFunction } from "./internal/enhance.js";
-import { Effect } from "effect";
+import { Data, Effect } from "effect";
 import { applyAction, deserialize } from "$app/forms";
 //#region src/forms.ts
 /**
@@ -34,6 +34,7 @@ import { applyAction, deserialize } from "$app/forms";
 * ```
 */
 var forms_exports = /* @__PURE__ */ __exportAll({
+	ApplyActionError: () => ApplyActionError,
 	applyAction: () => applyAction$1,
 	deserialize: () => deserialize$1,
 	enhance: () => enhance
@@ -43,15 +44,75 @@ var forms_exports = /* @__PURE__ */ __exportAll({
 *
 * `onSubmit` runs before the request (call `input.cancel()` to abort);
 * `onResult` runs on the response with SvelteKit's `update()`. Omit `onResult`
-* to keep SvelteKit's default behaviour. Pass `{ runtime }` when the handlers
-* require application services.
+* to keep SvelteKit's default behaviour. When the handlers (or `onError`)
+* require application services, pass `{ runtime }` (a `Context` or
+* `ManagedRuntime` providing them): it is then required, and a call without it
+* does not type-check. Each handler may require different services; the runtime
+* must provide all of them. A missing runtime is reported on the call, and one
+* that lacks a service on the runtime, never on a handler; the message may at
+* first name only the services of the handlers TypeScript types first (such as
+* an `onError` passed by name), and the rest once the runtime provides those.
+* Handlers that require no services run on the default runtime, and the options
+* may be omitted; an effect typed as requiring `any` or `unknown` is treated as
+* requiring no services, so no runtime is demanded. A function that wraps
+* `enhance` for handlers requiring any `R` forwards its options as
+* `...options: EnhanceOptionsArgs<R>` (or takes a required
+* `{ runtime: EnhanceRuntime<R> }`): an `EnhanceOptions<R>`, whose runtime is
+* optional, does not type-check there.
+*
+* Either handler may fail. Add an `onError` handler to handle the error
+* (typed as the union of the handlers' error types when written after them;
+* `unknown` when written before a handler with unannotated parameters): a
+* failed `onSubmit` also cancels the submission, and a failed `onResult` does
+* not fall back to SvelteKit's default behaviour. Without `onError`, or for a
+* defect or interruption, the promise SvelteKit awaits rejects (with the error
+* itself for a failure), which SvelteKit leaves unhandled.
+*
+* @example
+* ```ts
+* const submit = Forms.enhance({
+*   onResult: ({ result }) => Forms.applyAction(result),
+*   // error: ApplyActionError
+*   onError: (error) => Effect.logWarning("applyAction failed", error.cause),
+* });
+* ```
 */
 const enhance = makeSubmitFunction;
 /**
+* {@link applyAction} rejected or threw. `cause` is SvelteKit's original
+* reason, unchanged.
+*
+* SvelteKit 3 throws when `applyAction` is called during server rendering, and
+* follows a `redirect` result with a client-side navigation that rejects if it
+* fails: for example, a `location` that cannot be parsed even relative to the
+* page's base URL, or a `beforeNavigate` / `onNavigate` callback that throws. Recover with
+* `Effect.catchTag("ApplyActionError", ...)`.
+*/
+var ApplyActionError = class extends Data.TaggedError("ApplyActionError") {};
+/**
 * Apply an `ActionResult` to the page (updating `page.form` / `page.status`,
 * resetting the form, etc.) as an Effect. Wraps `$app/forms`' `applyAction`.
+*
+* Fails with an {@link ApplyActionError} if SvelteKit rejects or throws: for
+* example, when the navigation that follows a `redirect` result fails, or when
+* called during server rendering.
+*
+* {@link enhance}'s `onResult` can return it directly; its `onError` handler
+* then receives the `ApplyActionError`. Without `onError`, the error rejects
+* the promise SvelteKit awaits.
+*
+* @example
+* ```ts
+* const submit = Forms.enhance({
+*   onResult: ({ result }) => Forms.applyAction(result),
+*   onError: (error) => Effect.logWarning("applyAction failed", error.cause),
+* });
+* ```
 */
-const applyAction$1 = (result) => Effect.promise(() => applyAction(result));
+const applyAction$1 = (result) => Effect.tryPromise({
+	try: () => applyAction(result),
+	catch: (cause) => new ApplyActionError({ cause })
+});
 /**
 * Deserialize a raw form-action response body into an `ActionResult`, as an
 * Effect. Wraps `$app/forms`' `deserialize`; a malformed body fails the effect.
@@ -61,6 +122,6 @@ const deserialize$1 = (result) => Effect.try({
 	catch: (error) => error
 });
 //#endregion
-export { applyAction$1 as applyAction, deserialize$1 as deserialize, enhance, forms_exports };
+export { ApplyActionError, applyAction$1 as applyAction, deserialize$1 as deserialize, enhance, forms_exports };
 
 //# sourceMappingURL=forms.js.map

package/dist/forms.js.map

@@ -1 +1 @@
-{"version":3,"file":"forms.js","names":["applyAction","kitApplyAction","deserialize","kitDeserialize"],"sources":["../src/forms.ts"],"sourcesContent":["/**\n * Effect bridge for SvelteKit's native form actions\n * ([`$app/forms`](https://svelte.dev/docs/kit/$app-forms)) — the `Forms`\n * namespace of `@thomasfosterau/effect-sveltekit/client`.\n *\n * This complements `Remote.submitForm` (which covers *remote* forms): here the\n * progressive-enhancement `use:enhance` flow for page `actions` is expressed\n * with Effects, and `applyAction` / `deserialize` are wrapped so a hand-rolled\n * `fetch` submission can be finished off inside an Effect pipeline.\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { enhance } from '$app/forms';\n *   import { Forms } from '@thomasfosterau/effect-sveltekit/client';\n *   import { Effect } from 'effect';\n *\n *   const submit = Forms.enhance({\n *     onSubmit: () => Effect.sync(() => { saving = true; }),\n *     onResult: ({ result, update }) =>\n *       Effect.gen(function* () {\n *         yield* Effect.promise(() => update());\n *         saving = false;\n *       }),\n *   });\n * </script>\n *\n * <form method=\"POST\" use:enhance={submit}>...</form>\n * ```\n */\n\nimport { applyAction as kitApplyAction, deserialize as kitDeserialize } from \"$app/forms\";\nimport type { ActionResult } from \"$app/forms\";\nimport { Effect } from \"effect\";\nimport { makeSubmitFunction } from \"./internal/enhance.js\";\n\nexport type {\n  EnhanceHandlers,\n  EnhanceOptions,\n  EnhanceRuntime,\n  SubmitInput,\n  ResultOptions,\n} from \"./internal/enhance.js\";\n\n/**\n * Build a `SubmitFunction` for `use:enhance` from Effect-based handlers.\n *\n * `onSubmit` runs before the request (call `input.cancel()` to abort);\n * `onResult` runs on the response with SvelteKit's `update()`. Omit `onResult`\n * to keep SvelteKit's default behaviour. Pass `{ runtime }` when the handlers\n * require application services.\n */\nexport const enhance = makeSubmitFunction;\n\n/**\n * Apply an `ActionResult` to the page (updating `page.form` / `page.status`,\n * resetting the form, etc.) as an Effect. Wraps `$app/forms`' `applyAction`.\n */\nexport const applyAction = <\n  Success extends Record<string, unknown> | undefined = Record<string, unknown>,\n  Failure extends Record<string, unknown> | undefined = Record<string, unknown>,\n>(\n  result: ActionResult<Success, Failure>,\n): Effect.Effect<void> => Effect.promise(() => kitApplyAction(result));\n\n/**\n * Deserialize a raw form-action response body into an `ActionResult`, as an\n * Effect. Wraps `$app/forms`' `deserialize`; a malformed body fails the effect.\n */\nexport const deserialize = <\n  Success extends Record<string, unknown> | undefined = Record<string, unknown>,\n  Failure extends Record<string, unknown> | undefined = Record<string, unknown>,\n>(\n  result: string,\n): Effect.Effect<ActionResult<Success, Failure>, unknown> =>\n  Effect.try({\n    try: () => kitDeserialize<Success, Failure>(result),\n    catch: (error) => error,\n  });\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,MAAa,UAAU;;;;;AAMvB,MAAaA,iBAIX,WACwB,OAAO,cAAcC,YAAe,MAAM,CAAC;;;;;AAMrE,MAAaC,iBAIX,WAEA,OAAO,IAAI;CACT,WAAWC,YAAiC,MAAM;CAClD,QAAQ,UAAU;AACpB,CAAC"}
+{"version":3,"file":"forms.js","names":["applyAction","kitApplyAction","deserialize","kitDeserialize"],"sources":["../src/forms.ts"],"sourcesContent":["/**\n * Effect bridge for SvelteKit's native form actions\n * ([`$app/forms`](https://svelte.dev/docs/kit/$app-forms)) — the `Forms`\n * namespace of `@thomasfosterau/effect-sveltekit/client`.\n *\n * This complements `Remote.submitForm` (which covers *remote* forms): here the\n * progressive-enhancement `use:enhance` flow for page `actions` is expressed\n * with Effects, and `applyAction` / `deserialize` are wrapped so a hand-rolled\n * `fetch` submission can be finished off inside an Effect pipeline.\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { enhance } from '$app/forms';\n *   import { Forms } from '@thomasfosterau/effect-sveltekit/client';\n *   import { Effect } from 'effect';\n *\n *   const submit = Forms.enhance({\n *     onSubmit: () => Effect.sync(() => { saving = true; }),\n *     onResult: ({ result, update }) =>\n *       Effect.gen(function* () {\n *         yield* Effect.promise(() => update());\n *         saving = false;\n *       }),\n *   });\n * </script>\n *\n * <form method=\"POST\" use:enhance={submit}>...</form>\n * ```\n */\n\nimport { applyAction as kitApplyAction, deserialize as kitDeserialize } from \"$app/forms\";\nimport type { ActionResult } from \"$app/forms\";\nimport { Data, Effect } from \"effect\";\nimport { makeSubmitFunction } from \"./internal/enhance.js\";\n\nexport type {\n  EnhanceHandlers,\n  EnhanceOptions,\n  EnhanceOptionsArgs,\n  EnhanceRuntime,\n  SubmitInput,\n  ResultOptions,\n} from \"./internal/enhance.js\";\n\n/**\n * Build a `SubmitFunction` for `use:enhance` from Effect-based handlers.\n *\n * `onSubmit` runs before the request (call `input.cancel()` to abort);\n * `onResult` runs on the response with SvelteKit's `update()`. Omit `onResult`\n * to keep SvelteKit's default behaviour. When the handlers (or `onError`)\n * require application services, pass `{ runtime }` (a `Context` or\n * `ManagedRuntime` providing them): it is then required, and a call without it\n * does not type-check. Each handler may require different services; the runtime\n * must provide all of them. A missing runtime is reported on the call, and one\n * that lacks a service on the runtime, never on a handler; the message may at\n * first name only the services of the handlers TypeScript types first (such as\n * an `onError` passed by name), and the rest once the runtime provides those.\n * Handlers that require no services run on the default runtime, and the options\n * may be omitted; an effect typed as requiring `any` or `unknown` is treated as\n * requiring no services, so no runtime is demanded. A function that wraps\n * `enhance` for handlers requiring any `R` forwards its options as\n * `...options: EnhanceOptionsArgs<R>` (or takes a required\n * `{ runtime: EnhanceRuntime<R> }`): an `EnhanceOptions<R>`, whose runtime is\n * optional, does not type-check there.\n *\n * Either handler may fail. Add an `onError` handler to handle the error\n * (typed as the union of the handlers' error types when written after them;\n * `unknown` when written before a handler with unannotated parameters): a\n * failed `onSubmit` also cancels the submission, and a failed `onResult` does\n * not fall back to SvelteKit's default behaviour. Without `onError`, or for a\n * defect or interruption, the promise SvelteKit awaits rejects (with the error\n * itself for a failure), which SvelteKit leaves unhandled.\n *\n * @example\n * ```ts\n * const submit = Forms.enhance({\n *   onResult: ({ result }) => Forms.applyAction(result),\n *   // error: ApplyActionError\n *   onError: (error) => Effect.logWarning(\"applyAction failed\", error.cause),\n * });\n * ```\n */\nexport const enhance = makeSubmitFunction;\n\n/**\n * {@link applyAction} rejected or threw. `cause` is SvelteKit's original\n * reason, unchanged.\n *\n * SvelteKit 3 throws when `applyAction` is called during server rendering, and\n * follows a `redirect` result with a client-side navigation that rejects if it\n * fails: for example, a `location` that cannot be parsed even relative to the\n * page's base URL, or a `beforeNavigate` / `onNavigate` callback that throws. Recover with\n * `Effect.catchTag(\"ApplyActionError\", ...)`.\n */\nexport class ApplyActionError extends Data.TaggedError(\"ApplyActionError\")<{\n  /** The rejection reason, or the value thrown, as SvelteKit produced it. */\n  readonly cause: unknown;\n}> {}\n\n/**\n * Apply an `ActionResult` to the page (updating `page.form` / `page.status`,\n * resetting the form, etc.) as an Effect. Wraps `$app/forms`' `applyAction`.\n *\n * Fails with an {@link ApplyActionError} if SvelteKit rejects or throws: for\n * example, when the navigation that follows a `redirect` result fails, or when\n * called during server rendering.\n *\n * {@link enhance}'s `onResult` can return it directly; its `onError` handler\n * then receives the `ApplyActionError`. Without `onError`, the error rejects\n * the promise SvelteKit awaits.\n *\n * @example\n * ```ts\n * const submit = Forms.enhance({\n *   onResult: ({ result }) => Forms.applyAction(result),\n *   onError: (error) => Effect.logWarning(\"applyAction failed\", error.cause),\n * });\n * ```\n */\nexport const applyAction = <\n  Success extends Record<string, unknown> | undefined = Record<string, unknown>,\n  Failure extends Record<string, unknown> | undefined = Record<string, unknown>,\n>(\n  result: ActionResult<Success, Failure>,\n): Effect.Effect<void, ApplyActionError> =>\n  Effect.tryPromise({\n    try: () => kitApplyAction(result),\n    catch: (cause) => new ApplyActionError({ cause }),\n  });\n\n/**\n * Deserialize a raw form-action response body into an `ActionResult`, as an\n * Effect. Wraps `$app/forms`' `deserialize`; a malformed body fails the effect.\n */\nexport const deserialize = <\n  Success extends Record<string, unknown> | undefined = Record<string, unknown>,\n  Failure extends Record<string, unknown> | undefined = Record<string, unknown>,\n>(\n  result: string,\n): Effect.Effect<ActionResult<Success, Failure>, unknown> =>\n  Effect.try({\n    try: () => kitDeserialize<Success, Failure>(result),\n    catch: (error) => error,\n  });\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmFA,MAAa,UAAU;;;;;;;;;;;AAYvB,IAAa,mBAAb,cAAsC,KAAK,YAAY,kBAAkB,CAAC,CAGvE,CAAC;;;;;;;;;;;;;;;;;;;;;AAsBJ,MAAaA,iBAIX,WAEA,OAAO,WAAW;CAChB,WAAWC,YAAe,MAAM;CAChC,QAAQ,UAAU,IAAI,iBAAiB,EAAE,MAAM,CAAC;AAClD,CAAC;;;;;AAMH,MAAaC,iBAIX,WAEA,OAAO,IAAI;CACT,WAAWC,YAAiC,MAAM;CAClD,QAAQ,UAAU;AACpB,CAAC"}

package/dist/internal/app-state.d.ts

@@ -1,4 +1,5 @@
-import { Stream } from "effect";
+import { Effect, Option, Stream } from "effect";
+import { NavigationTarget, NavigationType } from "$app/navigation";
 //#region src/internal/app-state.d.ts
 /**
  * The fields of SvelteKit's `page` we snapshot. Mirrors the shape of
@@ -14,6 +15,7 @@ interface PageSnapshot<P extends ReadonlyPage = ReadonlyPage> {
   readonly data: P["data"];
   readonly state: P["state"];
   readonly form: P["form"];
+  readonly shallow: P["shallow"];
 }
 /**
  * The subset of `Page` fields the snapshot reads. Deliberately loose (the value
@@ -32,7 +34,40 @@ interface ReadonlyPage {
   readonly data: Record<string, unknown>;
   readonly state: unknown;
   readonly form: unknown;
+  readonly shallow: unknown;
+}
+/**
+ * A snapshot of an in-flight SvelteKit navigation, as `$app/state`'s
+ * `navigating` exposes it. `delta` is the history step count for a `popstate`
+ * navigation and `null` otherwise; `complete` resolves when the navigation
+ * finishes and rejects if it fails or is aborted.
+ */
+interface NavigatingSnapshot {
+  readonly type: Exclude<NavigationType, "enter">;
+  readonly from: NavigationTarget | null;
+  readonly to: NavigationTarget | null;
+  readonly willUnload: boolean;
+  readonly delta: number | null;
+  readonly complete: Promise<void>;
+}
+declare const UpdateCheckError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "UpdateCheckError";
+} & Readonly<A>;
+/**
+ * `updated.check()` rejected. SvelteKit resolves `false` when the version
+ * request fails, so this signals misuse (e.g. calling it during server
+ * rendering, where there is no `window`) rather than a network error.
+ */
+declare class UpdateCheckError extends UpdateCheckError_base<{
+  readonly cause: unknown;
+}> {}
+/** The service shape behind `State.CurrentPage`. */
+interface CurrentPageShape<P extends ReadonlyPage = ReadonlyPage> {
+  /** Snapshots the current page when run. */
+  readonly get: Effect.Effect<PageSnapshot<P>>;
+  /** The current page, then a fresh snapshot whenever any of its fields changes. */
+  readonly changes: Stream.Stream<PageSnapshot<P>>;
 }
 //#endregion
-export { PageSnapshot, ReadonlyPage };
+export { CurrentPageShape, NavigatingSnapshot, PageSnapshot, ReadonlyPage, UpdateCheckError };
 //# sourceMappingURL=app-state.d.ts.map

package/dist/internal/app-state.js

@@ -1,18 +1,6 @@
-import { Effect, Queue, Stream } from "effect";
+import { Data, Effect, Option, Queue, Stream } from "effect";
 //#region src/internal/app-state.ts
 /**
-* Pure, `$app/*`-free core for the `$app/state` bridge in `../State.ts`.
-*
-* The public `page` can't be unit-tested directly because importing it
-* pulls in `$app/navigation` and `$app/state` (SvelteKit virtual modules that
-* only exist inside a build). The snapshotting and the "emit now, then after
-* each navigation" plumbing live here instead, parameterised over the
-* navigation registrar and a `readPage` thunk, so they can be driven with
-* stand-ins in tests while the public wrapper stays a thin pass-through.
-*
-* @internal
-*/
-/**
 * Builds a shallow snapshot of the `page` fields that matter. We copy the
 * fields rather than forwarding the live `$app/state` proxy so downstream Effect
 * consumers see a stable value (the proxy mutates in place on every
@@ -29,7 +17,8 @@ function snapshotPage(page) {
 		error: page.error,
 		data: page.data,
 		state: page.state,
-		form: page.form
+		form: page.form,
+		shallow: page.shallow
 	};
 }
 /**
@@ -46,7 +35,61 @@ function pageSnapshotStream(registerAfterNavigate, readPage) {
 	});
 	return Stream.fromQueue(queue);
 }
+/**
+* A `Stream` of `read()`: the current value, then a new one each time `watch`
+* reports a change. Cold and lazy — each run opens its own watcher and disposes
+* it when the stream ends or is interrupted. Never fails; a throwing `watch`
+* surfaces as a defect (the stream dies with what it threw, with no watcher
+* left to dispose).
+*/
+function watchedStream(watch, read) {
+	return Stream.callback((queue) => Effect.acquireRelease(Effect.sync(() => watch(read, (value) => {
+		Queue.offerUnsafe(queue, value);
+	})), (dispose) => Effect.sync(dispose)));
+}
+/**
+* Copies `navigating` into a plain {@link NavigatingSnapshot}, or `None` when
+* no navigation is in flight (`type` is `null`). Reads every field, so a
+* watcher tracks the whole object.
+*/
+function snapshotNavigating(navigating) {
+	const { type, from, to, willUnload, delta, complete } = navigating;
+	if (type === null || willUnload === null || complete === null) return Option.none();
+	return Option.some({
+		type,
+		from,
+		to,
+		willUnload,
+		delta: delta ?? null,
+		complete
+	});
+}
+/**
+* `updated.check()` rejected. SvelteKit resolves `false` when the version
+* request fails, so this signals misuse (e.g. calling it during server
+* rendering, where there is no `window`) rather than a network error.
+*/
+var UpdateCheckError = class extends Data.TaggedError("UpdateCheckError") {};
+/**
+* Runs `check` (SvelteKit's `updated.check`) as an Effect that succeeds with
+* whether a new version is available and fails with {@link UpdateCheckError}
+* if the promise rejects (or `check` throws).
+*/
+function checkForUpdateWith(check) {
+	return Effect.tryPromise({
+		try: () => check(),
+		catch: (cause) => new UpdateCheckError({ cause })
+	});
+}
+/** Builds a {@link CurrentPageShape} reading `readPage()` and watching it with `watch`. */
+function makeCurrentPage(readPage, watch) {
+	const read = () => snapshotPage(readPage());
+	return {
+		get: Effect.sync(read),
+		changes: watchedStream(watch, read)
+	};
+}
 //#endregion
-export { pageSnapshotStream, snapshotPage };
+export { UpdateCheckError, checkForUpdateWith, makeCurrentPage, pageSnapshotStream, snapshotNavigating, snapshotPage, watchedStream };
 
 //# sourceMappingURL=app-state.js.map

package/dist/internal/app-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"app-state.js","names":[],"sources":["../../src/internal/app-state.ts"],"sourcesContent":["/**\n * Pure, `$app/*`-free core for the `$app/state` bridge in `../State.ts`.\n *\n * The public `page` can't be unit-tested directly because importing it\n * pulls in `$app/navigation` and `$app/state` (SvelteKit virtual modules that\n * only exist inside a build). The snapshotting and the \"emit now, then after\n * each navigation\" plumbing live here instead, parameterised over the\n * navigation registrar and a `readPage` thunk, so they can be driven with\n * stand-ins in tests while the public wrapper stays a thin pass-through.\n *\n * @internal\n */\n\nimport { Effect, Queue, Stream } from \"effect\";\n\n/**\n * The fields of SvelteKit's `page` we snapshot. Mirrors the shape of\n * `@sveltejs/kit`'s `Page`, but as a plain readonly record rather than the live\n * mutating proxy.\n */\nexport interface PageSnapshot<P extends ReadonlyPage = ReadonlyPage> {\n  readonly url: P[\"url\"];\n  readonly params: P[\"params\"];\n  readonly route: P[\"route\"];\n  readonly status: P[\"status\"];\n  readonly error: P[\"error\"];\n  readonly data: P[\"data\"];\n  readonly state: P[\"state\"];\n  readonly form: P[\"form\"];\n}\n\n/**\n * The subset of `Page` fields the snapshot reads. Deliberately loose (the value\n * types are `unknown` / broad) so SvelteKit's `Page` — whose `params` / `data`\n * / `error` / `state` are app-specific — satisfies the constraint, while\n * `PageSnapshot<P>` recovers the precise field types from `P`.\n */\nexport interface ReadonlyPage {\n  // SvelteKit 3 types `page.url` as an immutable `ReadonlyURL` (from\n  // `$app/state`); everything but `searchParams` is enough here.\n  readonly url: Readonly<Omit<URL, \"searchParams\">>;\n  readonly params: Record<string, string | undefined>;\n  readonly route: { readonly id: string | null };\n  readonly status: number;\n  readonly error: unknown;\n  readonly data: Record<string, unknown>;\n  readonly state: unknown;\n  readonly form: unknown;\n}\n\n/**\n * Builds a shallow snapshot of the `page` fields that matter. We copy the\n * fields rather than forwarding the live `$app/state` proxy so downstream Effect\n * consumers see a stable value (the proxy mutates in place on every\n * navigation, which would make a captured reference unreliable). Nested values\n * (`url`, `data`, ...) are *not* deep-cloned: they're replaced wholesale on each\n * navigation, so a shallow copy is enough to distinguish snapshots.\n */\nexport function snapshotPage<P extends ReadonlyPage>(page: P): PageSnapshot<P> {\n  return {\n    url: page.url,\n    params: page.params,\n    route: page.route,\n    status: page.status,\n    error: page.error,\n    data: page.data,\n    state: page.state,\n    form: page.form,\n  };\n}\n\n/**\n * Emits a snapshot of `readPage()` immediately, then again every time\n * `registerAfterNavigate`'s callback fires (i.e. after each navigation). Backed\n * by an unbounded queue, exposed as a `Stream` — the same push bridge as the\n * navigation-event helpers.\n */\nexport function pageSnapshotStream<P extends ReadonlyPage>(\n  registerAfterNavigate: (callback: () => void) => void,\n  readPage: () => P,\n): Stream.Stream<PageSnapshot<P>> {\n  const queue = Effect.runSync(Queue.unbounded<PageSnapshot<P>>());\n  // Initial value: the current page, so consumers start from a known state.\n  Queue.offerUnsafe(queue, snapshotPage(readPage()));\n  // afterNavigate fires once on mount too, but emitting up front means a\n  // late-subscribing consumer still sees the current page without waiting for a\n  // navigation.\n  registerAfterNavigate(() => {\n    Queue.offerUnsafe(queue, snapshotPage(readPage()));\n  });\n  return Stream.fromQueue(queue);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA0DA,SAAgB,aAAqC,MAA0B;CAC7E,OAAO;EACL,KAAK,KAAK;EACV,QAAQ,KAAK;EACb,OAAO,KAAK;EACZ,QAAQ,KAAK;EACb,OAAO,KAAK;EACZ,MAAM,KAAK;EACX,OAAO,KAAK;EACZ,MAAM,KAAK;CACb;AACF;;;;;;;AAQA,SAAgB,mBACd,uBACA,UACgC;CAChC,MAAM,QAAQ,OAAO,QAAQ,MAAM,UAA2B,CAAC;CAE/D,MAAM,YAAY,OAAO,aAAa,SAAS,CAAC,CAAC;CAIjD,4BAA4B;EAC1B,MAAM,YAAY,OAAO,aAAa,SAAS,CAAC,CAAC;CACnD,CAAC;CACD,OAAO,OAAO,UAAU,KAAK;AAC/B"}
+{"version":3,"file":"app-state.js","names":[],"sources":["../../src/internal/app-state.ts"],"sourcesContent":["/**\n * Pure, `$app/*`-free core for the `$app/state` bridge in `../State.ts`.\n *\n * The public helpers can't be unit-tested in plain Node because importing them\n * pulls in `$app/navigation` and `$app/state` (SvelteKit virtual modules that\n * only exist inside a build). The snapshotting, the \"emit now, then after each\n * navigation\" plumbing and the watch-to-`Stream` bridge live here instead,\n * parameterised over the navigation registrar, a {@link Watch} function and\n * read thunks, so they can be driven with stand-ins in tests while the public\n * wrappers stay thin pass-throughs. The only runes code is `watch.svelte.ts`.\n *\n * @internal\n */\n\nimport type { NavigationTarget, NavigationType } from \"$app/navigation\";\nimport { Data, Effect, Option, Queue, Stream } from \"effect\";\n\n/**\n * The fields of SvelteKit's `page` we snapshot. Mirrors the shape of\n * `@sveltejs/kit`'s `Page`, but as a plain readonly record rather than the live\n * mutating proxy.\n */\nexport interface PageSnapshot<P extends ReadonlyPage = ReadonlyPage> {\n  readonly url: P[\"url\"];\n  readonly params: P[\"params\"];\n  readonly route: P[\"route\"];\n  readonly status: P[\"status\"];\n  readonly error: P[\"error\"];\n  readonly data: P[\"data\"];\n  readonly state: P[\"state\"];\n  readonly form: P[\"form\"];\n  readonly shallow: P[\"shallow\"];\n}\n\n/**\n * The subset of `Page` fields the snapshot reads. Deliberately loose (the value\n * types are `unknown` / broad) so SvelteKit's `Page` — whose `params` / `data`\n * / `error` / `state` are app-specific — satisfies the constraint, while\n * `PageSnapshot<P>` recovers the precise field types from `P`.\n */\nexport interface ReadonlyPage {\n  // SvelteKit 3 types `page.url` as an immutable `ReadonlyURL` (from\n  // `$app/state`); everything but `searchParams` is enough here.\n  readonly url: Readonly<Omit<URL, \"searchParams\">>;\n  readonly params: Record<string, string | undefined>;\n  readonly route: { readonly id: string | null };\n  readonly status: number;\n  readonly error: unknown;\n  readonly data: Record<string, unknown>;\n  readonly state: unknown;\n  readonly form: unknown;\n  // SvelteKit 3: the target of the current shallow navigation, or `null`.\n  readonly shallow: unknown;\n}\n\n/**\n * Builds a shallow snapshot of the `page` fields that matter. We copy the\n * fields rather than forwarding the live `$app/state` proxy so downstream Effect\n * consumers see a stable value (the proxy mutates in place on every\n * navigation, which would make a captured reference unreliable). Nested values\n * (`url`, `data`, ...) are *not* deep-cloned: they're replaced wholesale on each\n * navigation, so a shallow copy is enough to distinguish snapshots.\n */\nexport function snapshotPage<P extends ReadonlyPage>(page: P): PageSnapshot<P> {\n  return {\n    url: page.url,\n    params: page.params,\n    route: page.route,\n    status: page.status,\n    error: page.error,\n    data: page.data,\n    state: page.state,\n    form: page.form,\n    shallow: page.shallow,\n  };\n}\n\n/**\n * Emits a snapshot of `readPage()` immediately, then again every time\n * `registerAfterNavigate`'s callback fires (i.e. after each navigation). Backed\n * by an unbounded queue, exposed as a `Stream` — the same push bridge as the\n * navigation-event helpers.\n */\nexport function pageSnapshotStream<P extends ReadonlyPage>(\n  registerAfterNavigate: (callback: () => void) => void,\n  readPage: () => P,\n): Stream.Stream<PageSnapshot<P>> {\n  const queue = Effect.runSync(Queue.unbounded<PageSnapshot<P>>());\n  // Initial value: the current page, so consumers start from a known state.\n  Queue.offerUnsafe(queue, snapshotPage(readPage()));\n  // afterNavigate fires once on mount too, but emitting up front means a\n  // late-subscribing consumer still sees the current page without waiting for a\n  // navigation.\n  registerAfterNavigate(() => {\n    Queue.offerUnsafe(queue, snapshotPage(readPage()));\n  });\n  return Stream.fromQueue(queue);\n}\n\n// ─── Watching rune state ─────────────────────────────────────────────────────\n\n/**\n * Observes a reactive read: calls `onValue` with `read()` once, then again\n * whenever something `read` touched changes, until the returned disposer runs.\n * The real implementation is `watch` in `./watch.svelte.ts`.\n */\nexport type Watch = <A>(read: () => A, onValue: (value: A) => void) => () => void;\n\n/**\n * A `Stream` of `read()`: the current value, then a new one each time `watch`\n * reports a change. Cold and lazy — each run opens its own watcher and disposes\n * it when the stream ends or is interrupted. Never fails; a throwing `watch`\n * surfaces as a defect (the stream dies with what it threw, with no watcher\n * left to dispose).\n */\nexport function watchedStream<A>(watch: Watch, read: () => A): Stream.Stream<A> {\n  return Stream.callback<A>((queue) =>\n    Effect.acquireRelease(\n      Effect.sync(() =>\n        watch(read, (value) => {\n          Queue.offerUnsafe(queue, value);\n        }),\n      ),\n      (dispose) => Effect.sync(dispose),\n    ),\n  );\n}\n\n// ─── navigating ──────────────────────────────────────────────────────────────\n\n/**\n * A snapshot of an in-flight SvelteKit navigation, as `$app/state`'s\n * `navigating` exposes it. `delta` is the history step count for a `popstate`\n * navigation and `null` otherwise; `complete` resolves when the navigation\n * finishes and rejects if it fails or is aborted.\n */\nexport interface NavigatingSnapshot {\n  readonly type: Exclude<NavigationType, \"enter\">;\n  readonly from: NavigationTarget | null;\n  readonly to: NavigationTarget | null;\n  readonly willUnload: boolean;\n  readonly delta: number | null;\n  readonly complete: Promise<void>;\n}\n\n/**\n * The shape of `$app/state`'s `navigating`: every field is `null` while no\n * navigation is in flight.\n */\nexport interface ReadonlyNavigating {\n  readonly type: NavigatingSnapshot[\"type\"] | null;\n  readonly from: NavigationTarget | null;\n  readonly to: NavigationTarget | null;\n  readonly willUnload: boolean | null;\n  readonly delta?: number | null | undefined;\n  readonly complete: Promise<void> | null;\n}\n\n/**\n * Copies `navigating` into a plain {@link NavigatingSnapshot}, or `None` when\n * no navigation is in flight (`type` is `null`). Reads every field, so a\n * watcher tracks the whole object.\n */\nexport function snapshotNavigating(\n  navigating: ReadonlyNavigating,\n): Option.Option<NavigatingSnapshot> {\n  const { type, from, to, willUnload, delta, complete } = navigating;\n  if (type === null || willUnload === null || complete === null) return Option.none();\n  return Option.some({ type, from, to, willUnload, delta: delta ?? null, complete });\n}\n\n// ─── updated ─────────────────────────────────────────────────────────────────\n\n/**\n * `updated.check()` rejected. SvelteKit resolves `false` when the version\n * request fails, so this signals misuse (e.g. calling it during server\n * rendering, where there is no `window`) rather than a network error.\n */\nexport class UpdateCheckError extends Data.TaggedError(\"UpdateCheckError\")<{\n  readonly cause: unknown;\n}> {}\n\n/**\n * Runs `check` (SvelteKit's `updated.check`) as an Effect that succeeds with\n * whether a new version is available and fails with {@link UpdateCheckError}\n * if the promise rejects (or `check` throws).\n */\nexport function checkForUpdateWith(\n  check: () => Promise<boolean>,\n): Effect.Effect<boolean, UpdateCheckError> {\n  return Effect.tryPromise({\n    try: () => check(),\n    catch: (cause) => new UpdateCheckError({ cause }),\n  });\n}\n\n// ─── CurrentPage ─────────────────────────────────────────────────────────────\n\n/** The service shape behind `State.CurrentPage`. */\nexport interface CurrentPageShape<P extends ReadonlyPage = ReadonlyPage> {\n  /** Snapshots the current page when run. */\n  readonly get: Effect.Effect<PageSnapshot<P>>;\n  /** The current page, then a fresh snapshot whenever any of its fields changes. */\n  readonly changes: Stream.Stream<PageSnapshot<P>>;\n}\n\n/** Builds a {@link CurrentPageShape} reading `readPage()` and watching it with `watch`. */\nexport function makeCurrentPage<P extends ReadonlyPage>(\n  readPage: () => P,\n  watch: Watch,\n): CurrentPageShape<P> {\n  const read = (): PageSnapshot<P> => snapshotPage(readPage());\n  return { get: Effect.sync(read), changes: watchedStream(watch, read) };\n}\n"],"mappings":";;;;;;;;;;AA+DA,SAAgB,aAAqC,MAA0B;CAC7E,OAAO;EACL,KAAK,KAAK;EACV,QAAQ,KAAK;EACb,OAAO,KAAK;EACZ,QAAQ,KAAK;EACb,OAAO,KAAK;EACZ,MAAM,KAAK;EACX,OAAO,KAAK;EACZ,MAAM,KAAK;EACX,SAAS,KAAK;CAChB;AACF;;;;;;;AAQA,SAAgB,mBACd,uBACA,UACgC;CAChC,MAAM,QAAQ,OAAO,QAAQ,MAAM,UAA2B,CAAC;CAE/D,MAAM,YAAY,OAAO,aAAa,SAAS,CAAC,CAAC;CAIjD,4BAA4B;EAC1B,MAAM,YAAY,OAAO,aAAa,SAAS,CAAC,CAAC;CACnD,CAAC;CACD,OAAO,OAAO,UAAU,KAAK;AAC/B;;;;;;;;AAkBA,SAAgB,cAAiB,OAAc,MAAiC;CAC9E,OAAO,OAAO,UAAa,UACzB,OAAO,eACL,OAAO,WACL,MAAM,OAAO,UAAU;EACrB,MAAM,YAAY,OAAO,KAAK;CAChC,CAAC,CACH,IACC,YAAY,OAAO,KAAK,OAAO,CAClC,CACF;AACF;;;;;;AAqCA,SAAgB,mBACd,YACmC;CACnC,MAAM,EAAE,MAAM,MAAM,IAAI,YAAY,OAAO,aAAa;CACxD,IAAI,SAAS,QAAQ,eAAe,QAAQ,aAAa,MAAM,OAAO,OAAO,KAAK;CAClF,OAAO,OAAO,KAAK;EAAE;EAAM;EAAM;EAAI;EAAY,OAAO,SAAS;EAAM;CAAS,CAAC;AACnF;;;;;;AASA,IAAa,mBAAb,cAAsC,KAAK,YAAY,kBAAkB,CAAC,CAEvE,CAAC;;;;;;AAOJ,SAAgB,mBACd,OAC0C;CAC1C,OAAO,OAAO,WAAW;EACvB,WAAW,MAAM;EACjB,QAAQ,UAAU,IAAI,iBAAiB,EAAE,MAAM,CAAC;CAClD,CAAC;AACH;;AAaA,SAAgB,gBACd,UACA,OACqB;CACrB,MAAM,aAA8B,aAAa,SAAS,CAAC;CAC3D,OAAO;EAAE,KAAK,OAAO,KAAK,IAAI;EAAG,SAAS,cAAc,OAAO,IAAI;CAAE;AACvE"}

package/dist/internal/enhance.d.ts

@@ -9,30 +9,128 @@ type ResultCallback = Extract<Awaited<ReturnType<SubmitFunction>>, (...args: nev
 type ResultOptions = Parameters<ResultCallback>[0];
 /** A runtime the handler effects can run against (a `Context` or `ManagedRuntime`). */
 type EnhanceRuntime<R> = Context.Context<R> | ManagedRuntime.ManagedRuntime<R, never>;
-/** Effect-based handlers for the two phases of an enhanced form submission. */
-interface EnhanceHandlers<R = never> {
+/**
+ * Effect-based handlers for the two phases of an enhanced form submission,
+ * plus `onError` for the errors they fail with. `ESubmit` / `EResult` are the
+ * errors `onSubmit` / `onResult` may fail with, and `E` (their union by
+ * default) the error `onError` receives. Each handler is called as a method of
+ * the handlers object, so `this` in a handler written as a method is that
+ * object.
+ */
+interface EnhanceHandlers<R = never, ESubmit = never, EResult = never, E = ESubmit | EResult> {
   /**
    * Runs before the request is sent. Call `input.cancel()` to abort the
    * submission (the result phase then never runs). Use for optimistic UI or
    * validation.
+   *
+   * If it fails with `ESubmit`, the submission is cancelled and the error goes
+   * to {@link EnhanceHandlers.onError | onError}.
    */
-  readonly onSubmit?: (input: SubmitInput) => Effect.Effect<void, never, R>;
+  readonly onSubmit?: ((input: SubmitInput) => Effect.Effect<void, ESubmit, R>) | undefined;
   /**
    * Runs once the action responds, with the `ActionResult` and SvelteKit's
    * `update()` (which applies the default behaviour — updating `page.form`,
    * resetting the form, invalidating). If omitted, SvelteKit's default
    * behaviour applies automatically.
+   *
+   * If it fails with `EResult`, the error goes to
+   * {@link EnhanceHandlers.onError | onError}; SvelteKit's default behaviour
+   * is not applied in its place.
    */
-  readonly onResult?: (options: ResultOptions) => Effect.Effect<void, never, R>;
+  readonly onResult?: ((options: ResultOptions) => Effect.Effect<void, EResult, R>) | undefined;
+  /**
+   * Handles an error `onSubmit` or `onResult` failed with (`E`, the union of
+   * their error types), as `Effect.catch` would. It runs on the same runtime
+   * and must not fail itself.
+   *
+   * Write it after `onSubmit` / `onResult` for `error` to be inferred
+   * precisely. Written before a handler whose parameters are not annotated
+   * (such as `onResult: ({ result }) => ...`), it still type-checks, but
+   * `error` is `unknown`: TypeScript types `onError`'s parameter before it has
+   * seen that handler's error type. An annotated parameter (or a function
+   * passed by name) must accept every error the handlers fail with, in either
+   * order.
+   *
+   * Only failures reach it: a defect or interruption (in a handler or in
+   * `onError`) still rejects the promise SvelteKit awaits, as does a failure
+   * when `onError` is omitted (rejecting with the error itself, as if the
+   * handler ended in `Effect.orDie`). SvelteKit does not catch that rejection:
+   * it sends no request after a rejected `onSubmit`, applies no default result
+   * after a rejected `onResult`, and the browser reports an unhandled
+   * rejection.
+   */
+  readonly onError?: ((error: E) => Effect.Effect<void, never, R>) | undefined;
 }
 /** Options for {@link makeSubmitFunction}. */
 interface EnhanceOptions<R = never> {
   /**
-   * The runtime to run the handler effects against. Omit when the handlers
-   * require no services (`R = never`); they then run on the default runtime.
+   * The runtime to run the handler effects against, providing every service
+   * `R` they require. Required when the handlers (or `onError`) require
+   * services; omit it when they require none (`R = never`), and they run on
+   * the default runtime.
    */
-  readonly runtime?: EnhanceRuntime<R>;
+  readonly runtime?: EnhanceRuntime<R> | undefined;
+}
+/**
+ * The options argument of `Forms.enhance`, as a rest tuple: optional when the
+ * handlers require no services (`R = never`), and otherwise required, with a
+ * `runtime` that provides `R`. There is no ambient runtime to fall back on, so
+ * handlers that require services and run without one would die with a
+ * missing-service defect. A function that wraps `Forms.enhance` for a generic
+ * `R` takes its options as `...options: EnhanceOptionsArgs<R>` and forwards
+ * them unchanged.
+ */
+type EnhanceOptionsArgs<R> = [R] extends [never] ? [options?: EnhanceOptions<never> | undefined] : [options: EnhanceOptions<R> & {
+  readonly runtime: EnhanceRuntime<R>;
+}];
+/** The handler names {@link makeSubmitFunction} accepts. */
+type EnhanceHandlerKey = keyof EnhanceHandlers;
+/**
+ * Records which handlers a handlers object names: `Keys` is inferred from the
+ * object's keys, which TypeScript knows before it types any handler.
+ */
+type HandlerKeys<Keys extends EnhanceHandlerKey> = { readonly [Key in Keys]?: unknown; };
+/** Whether `Errors` includes a handler error not inferred yet ({@link ErrorNotInferred}). */
+type IsErrorNotInferred<Errors> = 0 extends 1 & Errors ? true : false;
+/**
+ * The services a handler requires: `R`, or none while it is not inferred
+ * ({@link ServicesNotInferred}), as for an absent handler.
+ *
+ * Since `unknown` must count as none, so does every requirements type that
+ * `unknown` is assignable to: an effect typed as requiring `any` or `unknown`
+ * (to which a union with `unknown` collapses), such as one annotated
+ * `Effect.Effect<void, never, any>`, is treated as requiring no services, so
+ * no runtime is demanded for it. Such a type names no service a runtime could
+ * be checked against, and only a top type fits every handler in TypeScript's
+ * first inference pass.
+ */
+type RequiredServices<R> = unknown extends R ? never : R;
+/** The errors of the handlers named in `Keys`. */
+type HandlerErrors<Keys extends EnhanceHandlerKey, ESubmit, EResult> = ("onSubmit" extends Keys ? ESubmit : never) | ("onResult" extends Keys ? EResult : never);
+/**
+ * The error an unannotated `onError` receives: the handlers' errors, or
+ * `unknown` while one of them is not inferred yet (`onError` written before a
+ * handler whose parameters are not annotated).
+ */
+type OnErrorInput<Errors> = IsErrorNotInferred<Errors> extends true ? unknown : Errors;
+/**
+ * Requires `onError` to accept every error in `Errors` when its parameter is
+ * annotated (`E` is then inferred from the annotation). The check waits while
+ * a handler's error is not inferred yet, and applies once it is.
+ */
+type OnErrorAccepts<R, Errors, E> = IsErrorNotInferred<Errors> extends true ? unknown : [Errors] extends [E] ? unknown : OnErrorMustAccept<R, Errors>;
+/** The `onError` that {@link OnErrorAccepts} requires. */
+interface OnErrorMustAccept<R, Errors> {
+  readonly onError?: ((error: Errors) => Effect.Effect<void, never, R>) | undefined;
 }
+/**
+ * The handlers {@link makeSubmitFunction} accepts: {@link EnhanceHandlers},
+ * with each handler's requirements in a parameter of its own (`RSubmit`,
+ * `RResult`, `RError`). TypeScript infers one candidate per handler and does
+ * not union them, so a single requirements parameter would reject handlers
+ * that require different services even when the runtime provides them all.
+ */
+type EnhanceHandlersBy<RSubmit, RResult, RError, ESubmit, EResult, E> = Pick<EnhanceHandlers<RSubmit, ESubmit, EResult, E>, "onSubmit"> & Pick<EnhanceHandlers<RResult, ESubmit, EResult, E>, "onResult"> & Pick<EnhanceHandlers<RError, ESubmit, EResult, E>, "onError">;
 //#endregion
-export { EnhanceHandlers, EnhanceOptions, EnhanceRuntime, ResultOptions, SubmitInput };
+export { EnhanceHandlerKey, EnhanceHandlers, EnhanceHandlersBy, EnhanceOptions, EnhanceOptionsArgs, EnhanceRuntime, HandlerErrors, HandlerKeys, IsErrorNotInferred, OnErrorAccepts, OnErrorInput, OnErrorMustAccept, RequiredServices, ResultOptions, SubmitInput };
 //# sourceMappingURL=enhance.d.ts.map

package/dist/internal/enhance.js

@@ -1,6 +1,6 @@
 import { Context, Effect } from "effect";
 //#region src/internal/enhance.ts
-/** Run an `Effect<A, never, R>` on the given runtime (or the default when none). */
+/** Run an `Effect<A, E, R>` on the given runtime (or the default when none). */
 const runPromiseWith = (runtime) => (effect) => {
 	if (runtime === void 0) return Effect.runPromise(effect);
 	return Context.isContext(runtime) ? Effect.runPromiseWith(runtime)(effect) : runtime.runPromise(effect);
@@ -8,14 +8,38 @@ const runPromiseWith = (runtime) => (effect) => {
 /**
 * Build a SvelteKit `SubmitFunction` from Effect-based handlers. See
 * `Forms.enhance` for the public entry point and documentation.
+*
+* The type parameters are inferred, never written. `RSubmit`, `RResult` and
+* `RError` are the services each handler requires (see
+* {@link EnhanceHandlersBy}). `Keys` names the handlers present, and `E` (the
+* error `onError` receives) is computed from their errors, or inferred from
+* `onError`'s parameter annotation and then checked against them, so a
+* handlers object type-checks whatever its property order (see
+* {@link EnhanceHandlers.onError}). The options argument, and its `runtime`,
+* are required when the handlers require any service, and the runtime must
+* provide all of them (see {@link EnhanceOptionsArgs}).
+*
+* When a call does not type-check, TypeScript may report it against its first
+* inference pass, which skips handlers whose parameters are not annotated. The
+* defaults of the handler parameters ({@link ErrorNotInferred},
+* {@link ServicesNotInferred}) accept any handler, so a missing or wrong
+* runtime is reported on the call or on the runtime, never on a handler.
 */
-const makeSubmitFunction = (handlers, options) => {
+const makeSubmitFunction = (handlers, ...rest) => {
+	const options = rest[0];
 	const run = runPromiseWith(options?.runtime);
+	const phases = handlers;
+	const onError = handlers.onError;
+	const handleError = onError === void 0 ? void 0 : (error) => onError.call(handlers, error);
 	return async (input) => {
-		if (handlers.onSubmit) await run(handlers.onSubmit(input));
-		if (!handlers.onResult) return void 0;
-		const onResult = handlers.onResult;
-		return (resultOptions) => run(onResult(resultOptions));
+		const submit = phases.onSubmit?.(input);
+		if (submit !== void 0) await run(handleError === void 0 ? submit : submit.pipe(Effect.catch((error) => Effect.sync(() => input.cancel()).pipe(Effect.andThen(handleError(error))))));
+		const { onResult } = phases;
+		if (!onResult) return void 0;
+		return (resultOptions) => {
+			const result = onResult.call(handlers, resultOptions);
+			return run(handleError === void 0 ? result : result.pipe(Effect.catch(handleError)));
+		};
 	};
 };
 //#endregion