@thomasfosterau/effect-sveltekit 0.5.0 → 0.6.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

@@ -10,14 +10,14 @@ for the Svelte runes hooks.
 ## 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,7 +38,7 @@ 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
 
@@ -46,7 +46,7 @@ per-request runtime or on your own services (see
 | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@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`                                                                                                                                                    |
+| `…/client`                         | Browser-only `Navigation`, `State` (incl. the `CurrentPage` service), `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`)                                                                                                                                                         |
@@ -57,7 +57,7 @@ per-request runtime or on your own services (see
 ### 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 +81,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 +92,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 +126,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 +164,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 +370,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 +385,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 +401,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 +569,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/Navigation.d.ts

@@ -1,32 +1,85 @@
 import { Effect, Stream } from "effect";
 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: 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: "NavigationError";
+} & Readonly<A>;
 /**
- * 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", ...)`.
+ */
+declare class NavigationError extends NavigationError_base<{
+  /** The wrapper whose SvelteKit call failed. */
+  readonly operation: "goto" | "invalidate" | "invalidateAll" | "refreshAll" | "preloadData" | "preloadCode";
+  /** The rejection reason, or the value thrown, as SvelteKit produced it. */
+  readonly cause: unknown;
+}> {}
+/**
+ * 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
@@ -115,5 +168,5 @@ declare function afterNavigate$1(): Stream.Stream<AfterNavigate>;
  */
 declare function onNavigate$1(fn: (navigation: OnNavigate) => Effect.Effect<(() => void) | void>, runEffect?: <X>(effect: Effect.Effect<X>) => Promise<X>): void;
 //#endregion
-export { Navigation_d_exports, 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, Navigation_d_exports, 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 };
 //# sourceMappingURL=Navigation.d.ts.map

package/dist/Navigation.js

@@ -1,6 +1,6 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
 import { onNavigateWith, registeredStream } from "./internal/navigation-events.js";
-import { Effect } from "effect";
+import { Data, Effect } from "effect";
 import { afterNavigate, beforeNavigate, goto, invalidate, invalidateAll, onNavigate, preloadCode, preloadData, refreshAll } from "$app/navigation";
 //#region src/Navigation.ts
 /**
@@ -11,8 +11,12 @@ import { afterNavigate, beforeNavigate, goto, invalidate, invalidateAll, onNavig
 * `Effect`, so navigation composes inside Effect pipelines (sequencing,
 * retries, `Effect.race`, tracing spans, ...). Alongside them sit the
 * client-side lifecycle callbacks (`beforeNavigate`, `afterNavigate`,
-* `onNavigate`) bridged to Effect. These run on the client only — calling them
-* during SSR throws, exactly as the underlying `$app/navigation` functions do.
+* `onNavigate`) bridged to Effect. These run on the client only.
+*
+* When SvelteKit rejects (for example, `goto` to a URL outside the app) or
+* throws (for example, any of them run during server rendering), the wrapper
+* fails with a {@link NavigationError} that names the operation and carries
+* SvelteKit's original reason as its `cause`.
 *
 * @example
 * ```svelte
@@ -34,6 +38,7 @@ import { afterNavigate, beforeNavigate, goto, invalidate, invalidateAll, onNavig
 * ```
 */
 var Navigation_exports = /* @__PURE__ */ __exportAll({
+	NavigationError: () => NavigationError,
 	afterNavigate: () => afterNavigate$1,
 	beforeNavigate: () => beforeNavigate$1,
 	goto: () => goto$1,
@@ -45,29 +50,85 @@ var Navigation_exports = /* @__PURE__ */ __exportAll({
 	refreshAll: () => refreshAll$1
 });
 /**
-* 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", ...)`.
+*/
+var NavigationError = class extends Data.TaggedError("NavigationError") {};
+/**
+* Runs a `$app/navigation` call as an Effect, so a rejection, or a synchronous
+* throw, fails with a {@link NavigationError} instead of becoming a defect.
+*/
+const fromNavigation = (operation, thunk) => Effect.tryPromise({
+	try: () => thunk(),
+	catch: (cause) => new NavigationError({
+		operation,
+		cause
+	})
+});
+/**
+* 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.
 */
-const goto$1 = (...args) => Effect.promise(() => goto(...args));
-/** Re-run `load` functions that depend on `resource`. Wraps `invalidate`. */
-const invalidate$1 = (...args) => Effect.promise(() => invalidate(...args));
+const goto$1 = (...args) => fromNavigation("goto", () => goto(...args));
+/**
+* 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.
+*/
+const invalidate$1 = (...args) => fromNavigation("invalidate", () => invalidate(...args));
 /**
 * 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`.
 */
-const invalidateAll$1 = () => Effect.promise(() => invalidateAll());
-/** Refresh active remote functions (and, by default, `load`s). Wraps `refreshAll`. */
-const refreshAll$1 = (...args) => Effect.promise(() => refreshAll(...args));
-/** Preload the data for `href`. Wraps `preloadData`. */
-const preloadData$1 = (href) => Effect.promise(() => preloadData(href));
+const invalidateAll$1 = () => fromNavigation("invalidateAll", () => invalidateAll());
+/**
+* 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.
+*/
+const refreshAll$1 = (...args) => fromNavigation("refreshAll", () => refreshAll(...args));
+/**
+* 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.
+*/
+const preloadData$1 = (href) => fromNavigation("preloadData", () => preloadData(href));
 /**
 * 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 `/`).
 */
-const preloadCode$1 = (...args) => Effect.promise(() => preloadCode(...args));
+const preloadCode$1 = (...args) => fromNavigation("preloadCode", () => preloadCode(...args));
 /**
 * Registers a `beforeNavigate` callback and exposes every navigation about to
 * happen as an Effect `Stream`. Call during component initialization.
@@ -75,9 +136,9 @@ const preloadCode$1 = (...args) => Effect.promise(() => preloadCode(...args));
 * 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
@@ -162,6 +223,6 @@ function onNavigate$1(fn, runEffect = Effect.runPromise) {
 	onNavigateWith(onNavigate, fn, runEffect);
 }
 //#endregion
-export { Navigation_exports, 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, Navigation_exports, 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 };
 
 //# sourceMappingURL=Navigation.js.map