@thomasfosterau/effect-sveltekit 0.5.0 → 0.7.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright © 2026 [Thomas Foster](https://thomasfoster.au/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -3,21 +3,24 @@
 Effect integration for SvelteKit: load/action/endpoint wrappers, remote
 functions, an `effectKit()` Vite plugin, and an Effect HTTP deployment adapter.
 
-It depends on
+It lists
 [`@thomasfosterau/effect-svelte`](https://www.npmjs.com/package/@thomasfosterau/effect-svelte)
-for the Svelte runes hooks.
+as a dependency, so a compatible version is always installed alongside it. To
+import its Svelte runes hooks (`useDerived`, `AsyncResult`, …) in your own
+code, add it to your app's dependencies too: pnpm only lets a package import
+what it lists itself.
 
 ## Install
 
 ```bash
-pnpm add @thomasfosterau/effect-sveltekit effect@rc svelte @sveltejs/kit
+pnpm add @thomasfosterau/effect-sveltekit effect svelte @sveltejs/kit
 # the Effect deployment adapter additionally needs:
-pnpm add @effect/platform-node@rc
+pnpm add @effect/platform-node
 ```
 
-`effect` (`>=4.0.0-rc.118`) and `svelte` (`^5.40.0`) are required peers;
+`effect` (`>=4.0.2`) and `svelte` (`^5.40.0`) are required peers;
 `@sveltejs/kit` (`^3.0.0`), `vite` (for `./vite`) and
-`@effect/platform-node` (`>=4.0.0-rc.118`, for `./adapter`) are optional. The
+`@effect/platform-node` (`>=4.0.2`, for `./adapter`) are optional. The
 HTTP modules that lived in `@effect/platform` in v3 are part of `effect` itself
 in v4 (`effect/http`), so no other Effect package is needed. Keep a single copy
 of `effect`, and keep `effect` and `@effect/platform-node` on the same
@@ -38,26 +41,26 @@ export const load = serverLoad((event) => Effect.succeed({ id: event.params.id }
 The same wrappers exist for actions, endpoints and hooks, on the default
 per-request runtime or on your own services (see
 [App-wide runtime](#app-wide-runtime-share-your-services-across-requests)); the
-`effectKit()` Vite plugin lets route files export bare Effects instead.
+optional `effectKit()` Vite plugin lets route files export bare Effects instead.
 
 ## API
 
-| Entry point                        | What it provides                                                                                                                                                                                                                                                  |
-| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@thomasfosterau/effect-sveltekit` | Universal helpers: `load` / `makeUniversalRuntime`, the `Remote` call namespace, `Hooks` (`reroute`, `transport`), `ResponseHeaders`, `sveltekitConfig` / `readConfig`, `apiClient`                                                                               |
-| `…/server`                         | Server wrappers (`serverLoad`, `action`, `actions`, `endpoint`), `Hooks`, `Endpoint`, `makeServerRuntime`, the per-request runtime seam (`makeRuntimeAdapter` / `RequestRuntime`), `Errors`, `RemoteFunction`, request decoding (`decodeParams`, `decodeJson`, …) |
-| `…/client`                         | Browser-only `Navigation`, `State`, `Remote`, `Realtime`, `Forms` and `Hooks` namespaces, and `useRemoteQuery`                                                                                                                                                    |
-| `…/vite`                           | The `effectKit()` Vite plugin (auto-wraps bare-Effect route exports)                                                                                                                                                                                              |
-| `…/adapter`                        | The Effect HTTP deployment adapter (`effectAdapter`)                                                                                                                                                                                                              |
-| `…/adapter/handler`                | The SvelteKit app as an Effect HTTP app (`makeHandler`, `makeHandlerWith`, `AssetSource`, `toWebHandler`)                                                                                                                                                         |
-| `…/adapter/serve`                  | The Node server the adapter's `index.js` runs (`serve`, `layer`)                                                                                                                                                                                                  |
-| `…/testing`                        | A fake `RequestEvent` and runners for unit-testing server wrappers and remote functions (`TestRequestEvent`, `runServerLoad`, `runAction`, `runEndpoint`, `runRemote`)                                                                                            |
-| `…/internal/auto`                  | Referenced by `effectKit()`'s generated code; not a public API                                                                                                                                                                                                    |
+| Entry point                        | What it provides                                                                                                                                                                                                                                                                                                            |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@thomasfosterau/effect-sveltekit` | Universal helpers: `load` / `makeUniversalRuntime`, the `Remote` call namespace, `Hooks` (`reroute`, `transport`), `ResponseHeaders`, `sveltekitConfig` / `readConfig`, `apiClient`                                                                                                                                         |
+| `…/server`                         | Server wrappers (`serverLoad`, `action`, `actions`, `endpoint`), `Hooks`, `Endpoint`, `makeServerRuntime`, the per-request runtime seam (`makeRuntimeAdapter` / `RequestRuntime`), `Errors`, `RemoteFunction` / `RemoteFunctionUsageError`, `KitError` / `KitErrorBody`, request decoding (`decodeParams`, `decodeJson`, …) |
+| `…/client`                         | Browser-only `Navigation`, `State` (incl. the `CurrentPage` service), `Remote`, `Realtime`, `Forms` and `Hooks` namespaces, and `useRemoteQuery` / `RemoteQueryResult`                                                                                                                                                      |
+| `…/vite`                           | The `effectKit()` Vite plugin (auto-wraps bare-Effect route exports)                                                                                                                                                                                                                                                        |
+| `…/adapter`                        | The Effect HTTP deployment adapter (`effectAdapter`)                                                                                                                                                                                                                                                                        |
+| `…/adapter/handler`                | The SvelteKit app as an Effect HTTP app (`makeHandler`, `makeHandlerWith`, `AssetSource`, `toWebHandler`, the `SvelteKitServerError` / `AssetFetchError` defects)                                                                                                                                                           |
+| `…/adapter/serve`                  | The Node server the adapter's `index.js` runs (`serve`, `layer`)                                                                                                                                                                                                                                                            |
+| `…/testing`                        | A fake `RequestEvent` and runners for unit-testing server wrappers and remote functions (`TestRequestEvent`, `runServerLoad`, `runAction`, `runEndpoint`, `runRemote`)                                                                                                                                                      |
+| `…/internal/auto`                  | Referenced by `effectKit()`'s generated code; not a public API                                                                                                                                                                                                                                                              |
 
 ### At a glance
 
 - **Effects as route exports** — explicit wrappers, app-wide runtimes (services
-  built once per process), or the `effectKit()` plugin.
+  built once per process), or, optionally, the `effectKit()` plugin.
 - **Bring-your-own per-request runtime** — `makeRuntimeAdapter(provider, opts)`
   binds the server wrappers to a `RequestRuntime` provider, so the handler
   effect's services are your own application catalogue (not `SvelteKitServices`).
@@ -81,8 +84,9 @@ per-request runtime or on your own services (see
   `Hooks.markerTransporter` for non-round-tripping wrappers) and **`$env` ⇄
   Effect `Config`**.
 - **Client navigation/state** — the `Navigation` (`goto`/`invalidate`/… plus
-  `beforeNavigate`/`afterNavigate`/`onNavigate` streams) and `State` (`page`)
-  namespaces.
+  `beforeNavigate`/`afterNavigate`/`onNavigate` streams) and `State` (`page`,
+  `navigating` and `updated` streams, `checkForUpdate`, and the `CurrentPage`
+  service) namespaces.
 - **Effect deployment adapter** — the generated app is a platform-neutral
   Effect `HttpApp` (`makeHandlerWith`): serve it as a production Node HTTP server
   (`effect/http` + `@effect/platform-node`, the default) or as a Web
@@ -91,51 +95,6 @@ per-request runtime or on your own services (see
   (`AssetSource.fileSystem` for Node, `AssetSource.cloudflareAssets(env.ASSETS)`
   for Workers, or any custom source — R2, KV, a CDN passthrough).
 
-### SvelteKit Vite plugin (recommended)
-
-```ts
-// vite.config.ts
-import { sveltekit } from "@sveltejs/kit/vite";
-import { effectKit } from "@thomasfosterau/effect-sveltekit/vite";
-
-export default {
-  plugins: [effectKit(), sveltekit()],
-};
-```
-
-With the plugin installed, you can return an Effect (or a function returning
-an Effect) directly from any standard SvelteKit route file (`+page.ts`,
-`+page.server.ts`, `+layout(.server).ts`, `+server.ts`,
-`hooks.(server|client).ts`):
-
-```ts
-// +page.server.ts
-import { Effect } from "effect";
-
-export const load = (event) => Effect.succeed({ id: event.params.id });
-```
-
-The plugin rewrites the export so it goes through the same runtime as the
-explicit wrappers below; plain promise/value-returning functions pass through
-unchanged.
-
-#### Supported exports
-
-| File                | Exports auto-wrapped                                                   |
-| ------------------- | ---------------------------------------------------------------------- |
-| `+page.ts`          | `load`                                                                 |
-| `+page.server.ts`   | `load`, `actions`                                                      |
-| `+layout.ts`        | `load`                                                                 |
-| `+layout.server.ts` | `load`                                                                 |
-| `+server.ts`        | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD`, `fallback` |
-| `hooks.ts`          | `reroute`                                                              |
-| `hooks.server.ts`   | `handle`, `handleFetch`, `handleError`, `init`                         |
-| `hooks.client.ts`   | `handleError`, `init`                                                  |
-
-Config exports like `prerender`, `ssr`, `csr`, and `trailingSlash` — and the
-universal `transport` hook (which is plain data, not a function) — are never
-touched.
-
 ### App-wide runtime (share your services across requests)
 
 Define your application's Effect services once as a `Layer`; the layer is
@@ -170,20 +129,13 @@ The runtime exposes `serverLoad`, `action`, `actions`, `handle`, `handleFetch`,
 For universal `load` functions there is a browser-safe counterpart,
 `makeUniversalRuntime`, in `@thomasfosterau/effect-sveltekit`.
 
-To make the same services available to bare-Effect exports handled by the
-Vite plugin, point the plugin at the runtime module:
-
-```ts
-// vite.config.ts
-effectKit({ serverRuntime: "#lib/server/runtime.ts" });
-```
-
 #### One runtime per request
 
-Wire the runtime's `handle` hook (or the auto-wrapped `handle` from the Vite
-plugin) in `src/hooks.server.ts`. It creates a **per-request runtime** — the
-application layer's services plus the request's `HttpClient`/`SvelteKitRequestEvent`,
-built once and sharing a single request scope — and stores it on `event.locals`:
+Wire the runtime's `handle` hook (or the auto-wrapped `handle` from the
+[Vite plugin](#sveltekit-vite-plugin-optional)) in `src/hooks.server.ts`. It
+creates a **per-request runtime** — the application layer's services plus the
+request's `HttpClient`/`SvelteKitRequestEvent`, built once and sharing a single
+request scope — and stores it on `event.locals`:
 
 ```ts
 // src/hooks.server.ts
@@ -215,6 +167,64 @@ export const handle = runtime.handle(({ event, resolve }) =>
 Wrappers from a _different_ runtime, or requests without `handle` wired, fall
 back to building the request services per call, so this is backward compatible.
 
+### SvelteKit Vite plugin (optional)
+
+The explicit wrappers above are the primary API. The `effectKit()` Vite plugin
+is an optional convenience on top of them:
+
+```ts
+// vite.config.ts
+import { sveltekit } from "@sveltejs/kit/vite";
+import { effectKit } from "@thomasfosterau/effect-sveltekit/vite";
+
+export default {
+  plugins: [effectKit(), sveltekit()],
+};
+```
+
+With the plugin installed, you can return an Effect (or a function returning
+an Effect) directly from any standard SvelteKit route file (`+page.ts`,
+`+page.server.ts`, `+layout(.server).ts`, `+server.ts`,
+`hooks.(server|client).ts`):
+
+```ts
+// +page.server.ts
+import { Effect } from "effect";
+
+export const load = (event) => Effect.succeed({ id: event.params.id });
+```
+
+The plugin rewrites the export so it goes through the same runtime as the
+explicit wrappers; plain promise/value-returning functions pass through
+unchanged. SvelteKit's generated `$types` cannot see through the rewrite, so
+type a plugin-wrapped route's `data` prop yourself; explicit wrappers return
+real SvelteKit functions, so route `$types` work as usual.
+
+To make an app-wide runtime's services available to bare-Effect exports, point
+the plugin at the runtime module:
+
+```ts
+// vite.config.ts
+effectKit({ serverRuntime: "#lib/server/runtime.ts" });
+```
+
+#### Supported exports
+
+| File                | Exports auto-wrapped                                                   |
+| ------------------- | ---------------------------------------------------------------------- |
+| `+page.ts`          | `load`                                                                 |
+| `+page.server.ts`   | `load`, `actions`                                                      |
+| `+layout.ts`        | `load`                                                                 |
+| `+layout.server.ts` | `load`                                                                 |
+| `+server.ts`        | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD`, `fallback` |
+| `hooks.ts`          | `reroute`                                                              |
+| `hooks.server.ts`   | `handle`, `handleFetch`, `handleError`, `init`                         |
+| `hooks.client.ts`   | `handleError`, `init`                                                  |
+
+Config exports like `prerender`, `ssr`, `csr`, and `trailingSlash` — and the
+universal `transport` hook (which is plain data, not a function) — are never
+touched.
+
 ### Effect deployment adapter
 
 A SvelteKit [adapter](https://svelte.dev/docs/kit/adapters) (like
@@ -363,7 +373,8 @@ import {
   // $app/navigation: promise wrappers (goto, invalidate, ...) and lifecycle
   // events as Effect Streams (beforeNavigate/afterNavigate/onNavigate)
   Navigation,
-  // $app/state: the current page as a Stream of snapshots
+  // $app/state: page / navigating / updated as Streams, plus the
+  // CurrentPage service
   State,
   // remote-function helpers (callQuery, callCommand, liveQueryStream, ...)
   Remote,
@@ -377,6 +388,14 @@ import {
 //      Remote.callQuery(getTodos), State.page()
 ```
 
+`Navigation.goto`, `invalidate`, `invalidateAll`, `refreshAll`, `preloadData`
+and `preloadCode` fail with `Navigation.NavigationError` when SvelteKit rejects
+or throws: for example, `goto` to a URL outside the app, `preloadData` for an
+`href` outside the app, a navigation whose `beforeNavigate` / `onNavigate`
+callback throws, or any of them run during server rendering. The error's
+`operation` names the wrapper and its `cause` is SvelteKit's original reason;
+recover with `Effect.catchTag("NavigationError", ...)`.
+
 `Navigation.beforeNavigate()` / `Navigation.afterNavigate()` bridge
 `$app/navigation`'s callback-registration functions to `Stream`s,
 `Navigation.onNavigate(fn => Effect)` runs an Effect per navigation (forwarding
@@ -385,6 +404,31 @@ any cleanup the Effect yields), and `State.page()` emits a shallow snapshot of
 SvelteKit functions they wrap, these must be called during component
 initialization (at the top of `<script>`).
 
+The rest of `State` watches `$app/state` directly, so it works anywhere on the
+client (not only during component initialization):
+
+| Export                   | What it is                                                                                                                                                   |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `State.navigating()`     | `Stream<Option<NavigatingSnapshot>>` — `Some` while a navigation is in flight (`type`, `from`, `to`, `willUnload`, `delta`, `complete`), `None` when idle    |
+| `State.updated()`        | `Stream<boolean>` — `updated.current`: whether a new app version has been deployed                                                                           |
+| `State.checkForUpdate()` | `Effect<boolean, UpdateCheckError>` — `updated.check()` now; fails with `UpdateCheckError` if the check rejects                                              |
+| `State.CurrentPage`      | A `Context` service: `get` (snapshot the page now) and `changes` (a stream that also emits on shallow routing and form results); provide `CurrentPage.layer` |
+
+Each stream emits the current value on the next Svelte flush, then on every
+change, and stops watching when it ends or is interrupted. None of them fail.
+
+```ts
+import { State } from "@thomasfosterau/effect-sveltekit/client";
+import { Effect } from "effect";
+
+// Any client Effect can read the page once CurrentPage.layer is provided
+// (e.g. in the layer behind your client runtime).
+const logPath = Effect.gen(function* () {
+  const page = yield* (yield* State.CurrentPage).get;
+  yield* Effect.logInfo(`at ${page.url.pathname}`);
+}).pipe(Effect.provide(State.CurrentPage.layer));
+```
+
 ### `transport` hook from Effect Schema
 
 Move custom types (`Option`, `DateTime`, branded types, `Schema.Class`
@@ -528,10 +572,61 @@ Effects (no explicit wrapper) when the `effectKit()` Vite plugin is enabled.
 
 For SvelteKit page `actions`, the `Forms` namespace
 (`@thomasfosterau/effect-sveltekit/client`) expresses progressive enhancement
-with Effects: `Forms.enhance({ onSubmit, onResult })` builds a `SubmitFunction`
-for `use:enhance`, and `Forms.applyAction` / `Forms.deserialize` wrap the
-`$app/forms` helpers. (This complements `Remote.submitForm`, which covers remote
-forms.)
+with Effects: `Forms.enhance({ onSubmit, onResult, onError }, { runtime })`
+builds a `SubmitFunction` for `use:enhance`, and `Forms.applyAction` /
+`Forms.deserialize` wrap the `$app/forms` helpers. `Forms.applyAction` fails
+with `Forms.ApplyActionError` (SvelteKit's original reason as its `cause`) when
+SvelteKit rejects or throws: for example, when the navigation that follows a
+`redirect` result fails, or when it runs during server rendering.
+
+The handlers (and `onError`) run on `runtime`, a `Context` or `ManagedRuntime`.
+It is required, and checked to provide every service they require, as soon as
+any handler requires one: there is no ambient runtime to fall back on, so such 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 `Forms.enhance` 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, before handlers
+whose parameters are not annotated), 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 `Forms.enhance` for handlers requiring any `R` forwards its options as
+`...options: Forms.EnhanceOptionsArgs<R>`, which keeps them optional exactly
+when `R` is `never` (an `EnhanceOptions<R>`, whose runtime is optional, does not
+type-check there).
+
+`onSubmit` and `onResult` may fail. The `onError` handler receives the error,
+typed as the union of their error types, and runs on the same runtime; it must
+not fail itself. Write `onError` after the other handlers: written before one
+whose parameters are not annotated, it still type-checks, but its `error`
+parameter is `unknown`. A failed `onSubmit` also cancels the submission, and a
+failed `onResult` does not fall back to SvelteKit's default behaviour. Without
+`onError`, a failure is treated like a defect: the promise SvelteKit awaits
+rejects with the error, SvelteKit sends no request after a failed `onSubmit`
+and applies no default result after a failed `onResult`, and the browser
+reports an unhandled rejection. Defects and interruptions always take that path
+rather than reaching `onError`.
+
+```ts
+const submit = Forms.enhance({
+  onResult: ({ result }) => Forms.applyAction(result),
+  // error: ApplyActionError
+  onError: (error) => Effect.logWarning("applyAction failed", error.cause),
+});
+
+const submitAndRecover = Forms.enhance({
+  // Or recover inside the handler, so onResult cannot fail.
+  onResult: ({ result }) =>
+    Forms.applyAction(result).pipe(
+      Effect.catchTag("ApplyActionError", (error) =>
+        Effect.logWarning("applyAction failed", error.cause),
+      ),
+    ),
+});
+```
+
+(This complements `Remote.submitForm`, which covers remote forms.)
 
 ## Recipes
 

package/dist/Hooks.d.ts

@@ -1,6 +1,6 @@
 import { MarkerTransporterOptions, TransportEntry, markerTransporter, transport, transporter } from "./transport.js";
 import { responseHeadersTransporter } from "./response-headers.js";
-import { Effect } from "effect";
+import * as Effect from "effect/Effect";
 import * as HttpClient from "effect/http/HttpClient";
 import { Reroute } from "@sveltejs/kit/hooks";
 declare namespace Hooks_d_exports {
@@ -23,10 +23,10 @@ declare namespace Hooks_d_exports {
  * );
  * ```
  */
-declare function reroute(fn: (event: {
+export declare function reroute(fn: (event: {
   url: URL;
   fetch: typeof globalThis.fetch;
 }) => Effect.Effect<string | void, unknown, HttpClient.HttpClient>): Reroute;
 //#endregion
-export { Hooks_d_exports, type MarkerTransporterOptions, type TransportEntry, markerTransporter, reroute, responseHeadersTransporter, transport, transporter };
+export { Hooks_d_exports, type MarkerTransporterOptions, type TransportEntry, markerTransporter, responseHeadersTransporter, transport, transporter };
 //# sourceMappingURL=Hooks.d.ts.map

package/dist/Hooks.js

@@ -2,7 +2,7 @@ import { __exportAll } from "./_virtual/_rolldown/runtime.js";
 import { defaultUniversalRuntime } from "./internal/default-runtime.js";
 import { markerTransporter, transport, transporter } from "./transport.js";
 import { responseHeadersTransporter } from "./response-headers.js";
-import "effect";
+import "effect/Effect";
 //#region src/Hooks.ts
 var Hooks_exports = /* @__PURE__ */ __exportAll({
 	markerTransporter: () => markerTransporter,

package/dist/Hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"Hooks.js","names":[],"sources":["../src/Hooks.ts"],"sourcesContent":["/**\n * Effect helpers for SvelteKit's universal hooks (`src/hooks.ts`), exposed as\n * the `Hooks` namespace of `@thomasfosterau/effect-sveltekit`.\n *\n * The `reroute` hook is expressed as an Effect (running on the universal\n * runtime, with an `HttpClient` backed by the event's `fetch`), and the\n * universal `transport` hook is built from Effect schemas via {@link transport}\n * / {@link transporter}.\n *\n * @example\n * ```ts\n * // src/hooks.ts\n * import { Hooks } from '@thomasfosterau/effect-sveltekit';\n * import { Effect, Schema } from 'effect';\n *\n * export const reroute = Hooks.reroute((event) =>\n *   Effect.succeed(event.url.pathname === '/old' ? '/new' : undefined),\n * );\n *\n * export const transport = Hooks.transport({\n *   Option: Schema.Option(Schema.Number),\n *   Date: Schema.Date,\n * });\n * ```\n */\n\nimport type { Reroute } from \"@sveltejs/kit/hooks\";\nimport { Effect } from \"effect\";\nimport type * as HttpClient from \"effect/http/HttpClient\";\nimport { defaultUniversalRuntime } from \"./internal/default-runtime.js\";\n\n/**\n * Wraps an Effect-based function as the SvelteKit universal\n * [`reroute`](https://svelte.dev/docs/kit/hooks#Universal-hooks-reroute) hook,\n * which rewrites the URL before routing. The effect runs on both the server and\n * the client and gets an `HttpClient` backed by the event's `fetch`.\n *\n * @example\n * ```ts\n * // src/hooks.ts\n * import { Hooks } from '@thomasfosterau/effect-sveltekit';\n * import { Effect } from 'effect';\n *\n * export const reroute = Hooks.reroute((event) =>\n *   Effect.succeed(event.url.pathname === '/old' ? '/new' : undefined),\n * );\n * ```\n */\nexport function reroute(\n  fn: (event: {\n    url: URL;\n    fetch: typeof globalThis.fetch;\n  }) => Effect.Effect<string | void, unknown, HttpClient.HttpClient>,\n): Reroute {\n  return (event) => defaultUniversalRuntime().runPromise(event.fetch, fn(event));\n}\n\n/**\n * The universal `transport` hook built from Effect schemas: `transport`\n * assembles a whole `transport` object from a record of entries, `transporter`\n * builds a single round-tripping entry from a `Schema.Codec`, and\n * `markerTransporter` builds a deliberately-lossy entry for a non-POJO wrapper\n * whose contents should not round-trip. See {@link transport} for details.\n */\nexport {\n  transport,\n  transporter,\n  markerTransporter,\n  type MarkerTransporterOptions,\n  type TransportEntry,\n} from \"./transport.js\";\n\n/**\n * The `transport` entry for the {@link ResponseHeaders} response-headers buffer\n * (`Hooks.transport({ ResponseHeaders: Hooks.responseHeadersTransporter })`).\n */\nexport { responseHeadersTransporter } from \"./response-headers.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,SAAgB,QACd,IAIS;CACT,QAAQ,UAAU,wBAAwB,CAAC,CAAC,WAAW,MAAM,OAAO,GAAG,KAAK,CAAC;AAC/E"}
+{"version":3,"file":"Hooks.js","names":[],"sources":["../src/Hooks.ts"],"sourcesContent":["/**\n * Effect helpers for SvelteKit's universal hooks (`src/hooks.ts`), exposed as\n * the `Hooks` namespace of `@thomasfosterau/effect-sveltekit`.\n *\n * The `reroute` hook is expressed as an Effect (running on the universal\n * runtime, with an `HttpClient` backed by the event's `fetch`), and the\n * universal `transport` hook is built from Effect schemas via {@link transport}\n * / {@link transporter}.\n *\n * @example\n * ```ts\n * // src/hooks.ts\n * import { Hooks } from '@thomasfosterau/effect-sveltekit';\n * import { Effect, Schema } from 'effect';\n *\n * export const reroute = Hooks.reroute((event) =>\n *   Effect.succeed(event.url.pathname === '/old' ? '/new' : undefined),\n * );\n *\n * export const transport = Hooks.transport({\n *   Option: Schema.Option(Schema.Number),\n *   Date: Schema.Date,\n * });\n * ```\n */\n\nimport type { Reroute } from \"@sveltejs/kit/hooks\";\nimport * as Effect from \"effect/Effect\";\nimport type * as HttpClient from \"effect/http/HttpClient\";\nimport { defaultUniversalRuntime } from \"./internal/default-runtime.js\";\n\n/**\n * Wraps an Effect-based function as the SvelteKit universal\n * [`reroute`](https://svelte.dev/docs/kit/hooks#Universal-hooks-reroute) hook,\n * which rewrites the URL before routing. The effect runs on both the server and\n * the client and gets an `HttpClient` backed by the event's `fetch`.\n *\n * @example\n * ```ts\n * // src/hooks.ts\n * import { Hooks } from '@thomasfosterau/effect-sveltekit';\n * import { Effect } from 'effect';\n *\n * export const reroute = Hooks.reroute((event) =>\n *   Effect.succeed(event.url.pathname === '/old' ? '/new' : undefined),\n * );\n * ```\n */\nexport function reroute(\n  fn: (event: {\n    url: URL;\n    fetch: typeof globalThis.fetch;\n  }) => Effect.Effect<string | void, unknown, HttpClient.HttpClient>,\n): Reroute {\n  return (event) => defaultUniversalRuntime().runPromise(event.fetch, fn(event));\n}\n\n/**\n * The universal `transport` hook built from Effect schemas: `transport`\n * assembles a whole `transport` object from a record of entries, `transporter`\n * builds a single round-tripping entry from a `Schema.Codec`, and\n * `markerTransporter` builds a deliberately-lossy entry for a non-POJO wrapper\n * whose contents should not round-trip. See {@link transport} for details.\n */\nexport {\n  transport,\n  transporter,\n  markerTransporter,\n  type MarkerTransporterOptions,\n  type TransportEntry,\n} from \"./transport.js\";\n\n/**\n * The `transport` entry for the {@link ResponseHeaders} response-headers buffer\n * (`Hooks.transport({ ResponseHeaders: Hooks.responseHeadersTransporter })`).\n */\nexport { responseHeadersTransporter } from \"./response-headers.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,SAAgB,QACd,IAIS;CACT,QAAQ,UAAU,wBAAwB,CAAC,CAAC,WAAW,MAAM,OAAO,GAAG,KAAK,CAAC;AAC/E"}

package/dist/Navigation.d.ts

@@ -1,32 +1,85 @@
-import { Effect, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import * as Schema from "effect/Schema";
 import { AfterNavigate, BeforeNavigate, OnNavigate, goto, invalidate, preloadCode, preloadData, refreshAll } from "$app/navigation";
 declare namespace Navigation_d_exports {
-  export { afterNavigate$1 as afterNavigate, beforeNavigate$1 as beforeNavigate, goto$1 as goto, invalidate$1 as invalidate, invalidateAll$1 as invalidateAll, onNavigate$1 as onNavigate, preloadCode$1 as preloadCode, preloadData$1 as preloadData, refreshAll$1 as refreshAll };
+  export { NavigationError, afterNavigate$1 as afterNavigate, beforeNavigate$1 as beforeNavigate, goto$1 as goto, invalidate$1 as invalidate, invalidateAll$1 as invalidateAll, onNavigate$1 as onNavigate, preloadCode$1 as preloadCode, preloadData$1 as preloadData, refreshAll$1 as refreshAll };
 }
+declare const NavigationError_base: Schema.Class<NavigationError, Schema.TaggedStruct<"NavigationError", {
+  /** The wrapper whose SvelteKit call failed. */
+  readonly operation: Schema.Literals<readonly ["goto", "invalidate", "invalidateAll", "refreshAll", "preloadData", "preloadCode"]>;
+  /** The rejection reason, or the value thrown, as SvelteKit produced it. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
 /**
- * Navigate to `url`. Wraps `$app/navigation`'s `goto`. SvelteKit rejects a URL
- * outside the app (external, or not matching a route); a rejection surfaces as
- * a defect.
+ * A `$app/navigation` promise wrapper ({@link goto}, {@link invalidate},
+ * {@link invalidateAll}, {@link refreshAll}, {@link preloadData},
+ * {@link preloadCode}) rejected or threw. `operation` names the wrapper and
+ * `cause` is SvelteKit's original reason, unchanged.
+ *
+ * SvelteKit 3 rejects `goto` with a URL outside the app (external, or matching
+ * no route) and `preloadData` with a URL outside the app; `invalidate` throws on
+ * a `resource` that cannot be parsed even relative to the current URL;
+ * `preloadCode` rejects when a route's code fails to load; a navigation (including one that follows a `load` redirect during
+ * `invalidate` / `refreshAll`) rejects when a `beforeNavigate` / `onNavigate`
+ * callback throws; and every one of them throws when called during server
+ * rendering. Recover with `Effect.catchTag("NavigationError", ...)`.
+ */
+export declare class NavigationError extends NavigationError_base {}
+/**
+ * Navigate to `url`. Wraps `$app/navigation`'s `goto`.
+ *
+ * Fails with a {@link NavigationError} if SvelteKit rejects: a URL outside the
+ * app (external, or not matching a route) rejects, as does a navigation whose
+ * `beforeNavigate` / `onNavigate` callback throws, or a call during server
+ * rendering. For an external URL, set `window.location` instead.
  */
-declare const goto$1: (...args: Parameters<typeof goto>) => Effect.Effect<void>;
-/** Re-run `load` functions that depend on `resource`. Wraps `invalidate`. */
-declare const invalidate$1: (...args: Parameters<typeof invalidate>) => Effect.Effect<void>;
+declare const goto$1: (...args: Parameters<typeof goto>) => Effect.Effect<void, NavigationError>;
+/**
+ * Re-run `load` functions that depend on `resource`. Wraps `invalidate`.
+ *
+ * Fails with a {@link NavigationError} if SvelteKit rejects or throws: a
+ * `resource` string that cannot be parsed even relative to the current URL
+ * throws, as does a call during server rendering, and the navigation that
+ * follows a `load` redirect can reject.
+ */
+declare const invalidate$1: (...args: Parameters<typeof invalidate>) => Effect.Effect<void, NavigationError>;
 /**
  * Re-run every `load` function for the active page. Wraps `invalidateAll`.
  *
+ * Fails with a {@link NavigationError} if SvelteKit rejects or throws: for
+ * example, when the navigation that follows a `load` redirect fails, or when
+ * called during server rendering.
+ *
  * @deprecated SvelteKit 3 deprecates `invalidateAll`; use {@link refreshAll},
  * which also refreshes active remote functions and keeps `page.state`.
  */
-declare const invalidateAll$1: () => Effect.Effect<void>;
-/** Refresh active remote functions (and, by default, `load`s). Wraps `refreshAll`. */
-declare const refreshAll$1: (...args: Parameters<typeof refreshAll>) => Effect.Effect<void>;
-/** Preload the data for `href`. Wraps `preloadData`. */
-declare const preloadData$1: (href: string) => Effect.Effect<Awaited<ReturnType<typeof preloadData>>>;
+declare const invalidateAll$1: () => Effect.Effect<void, NavigationError>;
+/**
+ * Refresh active remote functions (and, by default, `load`s). Wraps `refreshAll`.
+ *
+ * Fails with a {@link NavigationError} if SvelteKit rejects or throws: for
+ * example, when the navigation that follows a `load` redirect fails, or when
+ * called during server rendering.
+ */
+declare const refreshAll$1: (...args: Parameters<typeof refreshAll>) => Effect.Effect<void, NavigationError>;
+/**
+ * Preload the data for `href`. Wraps `preloadData`, succeeding with SvelteKit's
+ * result (`loaded`, `redirect`, or `error` when a `load` fails).
+ *
+ * Fails with a {@link NavigationError} if SvelteKit rejects: an `href` outside
+ * the app rejects, as does a call during server rendering.
+ */
+declare const preloadData$1: (href: string) => Effect.Effect<Awaited<ReturnType<typeof preloadData>>, NavigationError>;
 /**
  * Preload the code for the route `id` (e.g. `/blog/[slug]`, without
  * `paths.base`). Wraps `preloadCode`.
+ *
+ * Fails with a {@link NavigationError} if SvelteKit rejects: a route module
+ * that fails to load rejects, as does a call during server rendering (and, in
+ * development, an `id` not starting with `/`).
  */
-declare const preloadCode$1: (...args: Parameters<typeof preloadCode>) => Effect.Effect<void>;
+declare const preloadCode$1: (...args: Parameters<typeof preloadCode>) => Effect.Effect<void, NavigationError>;
 /**
  * Registers a `beforeNavigate` callback and exposes every navigation about to
  * happen as an Effect `Stream`. Call during component initialization.
@@ -34,9 +87,9 @@ declare const preloadCode$1: (...args: Parameters<typeof preloadCode>) => Effect
  * Unlike the promise-returning navigation functions above, this is a
  * **callback-registration** function: it must be called *synchronously during
  * component initialization* (SvelteKit wires it to the component's lifecycle).
- * It registers its callback eagerly and feeds an internal `Queue`, returning a
- * `Stream` backed by that queue — the same push-based bridge as `SignalEmitter`
- * in `@thomasfosterau/effect-svelte`. Call it at the top level of `<script>`,
+ * It registers its callback eagerly and feeds an internal unbounded `Queue`,
+ * returning a `Stream` backed by that queue: a push-based bridge that buffers
+ * every event for its single consumer. Call it at the top level of `<script>`,
  * exactly where you'd call the bare `beforeNavigate`.
  *
  * @example