@sveltejs/kit 3.0.0-next.10 → 3.0.0-next.12

package/src/exports/public.d.ts

@@ -58,7 +58,7 @@ export interface Adapter {
 		 * Test support for `read` from `$app/server`.
 		 * @param details.config The merged adapter-specific route config exported from the route with `export const config`
 		 */
-		read?: (details: { config: any; route: { id: string } }) => boolean;
+		read?: (details: { config: Record<string, any>; route: { id: string } }) => boolean;
 
 		/**
 		 * Test support for `instrumentation.server.js`. To pass, the adapter must support running `instrumentation.server.js` prior to the application code.
@@ -288,7 +288,7 @@ export interface Cookies {
 	/**
 	 * Sets a cookie. This will add a `set-cookie` header to the response, but also make the cookie available via `cookies.get` or `cookies.getAll` during the current request.
 	 *
-	 * The `httpOnly` and `secure` options are `true` by default (except on http://localhost, where `secure` is `false`), and must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP.
+	 * The `httpOnly` is `true` by default, as is `secure`, except during development, when it defaults to `false`. These must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP.
 	 *
 	 * The `path` option is `'/'` by default. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children.
 	 * @param name the name of the cookie
@@ -300,7 +300,7 @@ export interface Cookies {
 	/**
 	 * Deletes a cookie by setting its value to an empty string and setting the expiry date in the past.
 	 *
-	 * The `httpOnly` and `secure` options are `true` by default (except on http://localhost, where `secure` is `false`), and must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP.
+	 * The `httpOnly` is `true` by default, as is `secure`, except during development, when it defaults to `false`. These must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP.
 	 *
 	 * The `path` option is `'/'` by default. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children.
 	 * @param name the name of the cookie
@@ -335,7 +335,7 @@ export interface Cookies {
 	/**
 	 * Serialize a cookie name-value pair into a `Set-Cookie` header string, but don't apply it to the response.
 	 *
-	 * The `httpOnly` and `secure` options are `true` by default (except on http://localhost, where `secure` is `false`), and must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP.
+	 * The `httpOnly` is `true` by default, as is `secure`, except during development, when it defaults to `false`. These must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP.
 	 *
 	 * The `path` option is `'/'` by default. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children.
 	 * @param name the name of the cookie
@@ -365,32 +365,10 @@ export interface KitConfig {
 	/**
 	 * An object containing zero or more aliases used to replace values in `import` statements. These aliases are automatically passed to Vite and TypeScript.
 	 *
-	 * ```js
-	 * /// file: vite.config.js
-	 * import { defineConfig } from 'vite';
-	 * import { sveltekit } from '@sveltejs/kit/vite';
-	 *
-	 * export default defineConfig({
-	 *   plugins: [
-	 *     sveltekit({
-	 *       alias: {
-	 *         // this will match a file
-	 *         'my-file': 'path/to/my-file.js',
-	 *
-	 *         // this will match a directory and its contents
-	 *         // (`my-directory/x` resolves to `path/to/my-directory/x`)
-	 *         'my-directory': 'path/to/my-directory',
-	 *
-	 *         // an alias ending /* will only match
-	 *         // the contents of a directory, not the directory itself
-	 *         'my-directory/*': 'path/to/my-directory/*'
-	 *       }
-	 *     })
-	 *   ]
-	 * });
-	 * ```
+	 * This option is deprecated. Use [subpath imports](https://svelte.dev/docs/kit/$lib) instead.
 	 *
 	 * > [!NOTE] You will need to run `npm run dev` to have SvelteKit automatically generate the required alias configuration in `jsconfig.json` or `tsconfig.json`.
+	 * @deprecated
 	 * @default {}
 	 */
 	alias?: Record<string, string>;
@@ -435,7 +413,7 @@ export interface KitConfig {
 	 *
 	 * > [!NOTE] When `mode` is `'auto'`, SvelteKit will use nonces for dynamically rendered pages and hashes for prerendered pages. Using nonces with prerendered pages is insecure and therefore forbidden.
 	 *
-	 * If this level of configuration is insufficient and you have more dynamic requirements, you can use the [`handle` hook](https://svelte.dev/docs/kit/hooks#Server-hooks-handle) to roll your own CSP.
+	 * If this level of configuration is insufficient and you have more dynamic requirements, you can use the [`handle` hook](https://svelte.dev/docs/kit/hooks#handle) to roll your own CSP.
 	 */
 	csp?: {
 		/**
@@ -833,8 +811,10 @@ export interface KitConfig {
 		 * This has several advantages:
 		 * - The client does not need to load the routing manifest upfront, which can lead to faster initial page loads
 		 * - The list of routes is hidden from public view
-		 * - The server has an opportunity to intercept each navigation (for example through a middleware), enabling (for example) A/B testing opaque to SvelteKit
-
+		 * - The server has an opportunity to intercept each navigation (for example through middleware in front of SvelteKit, such as a reverse proxy or your platform's edge functions), enabling (for example) A/B testing opaque to SvelteKit
+		 *
+		 * Route resolution requests are answered as soon as the route has been looked up, before the `handle` hook is invoked. To intercept them within SvelteKit itself, use the `reroute` hook, which runs for these requests too.
+		 *
 		 * The drawback is that for unvisited paths, resolution will take slightly longer (though this is mitigated by [preloading](https://svelte.dev/docs/kit/link-options#data-sveltekit-preload-data)).
 		 *
 		 * > [!NOTE] When using server-side route resolution and prerendering, the resolution is prerendered along with the route itself.
@@ -844,13 +824,7 @@ export interface KitConfig {
 		 */
 		resolution?: 'client' | 'server';
 	};
-	serviceWorker?: {
-		/**
-		 * Determine which files in your `static` directory will be available in `$service-worker.files`.
-		 * @default (filename) => !/\.DS_Store/.test(filename)
-		 */
-		files?: (file: string) => boolean;
-	} & (
+	serviceWorker?:
 		| {
 				/**
 				 * Whether to automatically register the service worker, if it exists.
@@ -868,19 +842,21 @@ export interface KitConfig {
 				 * @default true
 				 */
 				register?: false;
-		  }
-	);
+		  };
 	/**
 	 * Options for enabling [OpenTelemetry](https://opentelemetry.io/) tracing for SvelteKit operations.
 	 * @default { server: false }
 	 */
 	tracing?: {
 		/**
-		 * Enables server-side [OpenTelemetry](https://opentelemetry.io/) span emission for SvelteKit operations including the [`handle` hook](https://svelte.dev/docs/kit/hooks#Server-hooks-handle), [`load` functions](https://svelte.dev/docs/kit/load), [form actions](https://svelte.dev/docs/kit/form-actions), and [remote functions](https://svelte.dev/docs/kit/remote-functions). Tracing — and more significantly, observability instrumentation — can have a nontrivial overhead, so consider whether you really need it, or if it might be more appropriate to turn it on in development and preview environments only.
+		 * Enables server-side [OpenTelemetry](https://opentelemetry.io/) span emission for SvelteKit operations including the [`handle` hook](https://svelte.dev/docs/kit/hooks#handle), [`load` functions](https://svelte.dev/docs/kit/load), [form actions](https://svelte.dev/docs/kit/form-actions), and [remote functions](https://svelte.dev/docs/kit/remote-functions). Tracing — and more significantly, observability instrumentation — can have a nontrivial overhead, so consider whether you really need it, or if it might be more appropriate to turn it on in development and preview environments only.
 		 * @default false
 		 */
 		server?: boolean;
 	};
+	/**
+	 * @deprecated Add configuration to `tsconfig.json` directly
+	 */
 	typescript?: {
 		/**
 		 * A function that allows you to edit the generated `tsconfig.json`. You can mutate the config (recommended) or return a new one.
@@ -895,9 +871,9 @@ export interface KitConfig {
 	};
 	/**
 	 * Client-side navigation can be buggy if you deploy a new version of your app while people are using it. If the code for the new page is already loaded, it may have stale content; if it isn't, the app's route manifest may point to a JavaScript file that no longer exists.
-	 * SvelteKit helps you solve this problem through version management.
+	 * SvelteKit helps you solve this problem through version management. The current version is included in data, remote, and form action responses via the `x-sveltekit-version` header, so SvelteKit can detect new deployments without polling — for example when a navigation triggers a server `load` function, or when a remote function is called. SvelteKit also checks for new versions when the tab regains focus or becomes visible.
 	 * If SvelteKit encounters an error while loading the page and detects that a new version has been deployed (using the `name` specified here, which defaults to a timestamp of the build) it will fall back to traditional full-page navigation.
-	 * Not all navigations will result in an error though, for example if the JavaScript for the next page is already loaded. If you still want to force a full-page navigation in these cases, use techniques such as setting the `pollInterval` and then using `beforeNavigate`:
+	 * Not all navigations will result in an error though, for example if the JavaScript for the next page is already loaded. If you still want to force a full-page navigation in these cases, use `beforeNavigate`:
 	 * ```html
 	 * /// file: +layout.svelte
 	 * <script>
@@ -912,7 +888,7 @@ export interface KitConfig {
 	 * </script>
 	 * ```
 	 *
-	 * If you set `pollInterval` to a non-zero value, SvelteKit will poll for new versions in the background and set the value of [`updated.current`](https://svelte.dev/docs/kit/$app-state#updated) `true` when it detects one.
+	 * In addition to these checks, SvelteKit polls for new versions on an interval and sets [`updated.current`](https://svelte.dev/docs/kit/$app-state#updated) to `true` when it detects one. Set `pollInterval` to `0` to disable polling (the header- and event-based checks will still run).
 	 */
 	version?: {
 		/**
@@ -939,15 +915,15 @@ export interface KitConfig {
 		 */
 		name?: string;
 		/**
-		 * The interval in milliseconds to poll for version changes. If this is `0`, no polling occurs.
-		 * @default 0
+		 * The interval in milliseconds to poll for version changes. If this is `0`, no polling occurs. SvelteKit also checks for new versions on server responses (via the `x-sveltekit-version` header) and when the tab regains focus or becomes visible, so polling is only needed for long-lived sessions on a single page.
+		 * @default 3600000
 		 */
 		pollInterval?: number;
 	};
 }
 
 /**
- * The [`handle`](https://svelte.dev/docs/kit/hooks#Server-hooks-handle) hook runs every time the SvelteKit server receives a [request](https://svelte.dev/docs/kit/web-standards#Fetch-APIs-Request) and
+ * The [`handle`](https://svelte.dev/docs/kit/hooks#handle) hook runs every time the SvelteKit server receives a [request](https://svelte.dev/docs/kit/web-standards#Fetch-APIs-Request) and
  * determines the [response](https://svelte.dev/docs/kit/web-standards#Fetch-APIs-Response).
  * It receives an `event` object representing the request and a function called `resolve`, which renders the route and generates a `Response`.
  * This allows you to modify response headers or bodies, or bypass SvelteKit entirely (for implementing routes programmatically, for example).
@@ -958,7 +934,7 @@ export type Handle = (input: {
 }) => MaybePromise<Response>;
 
 /**
- * The server-side [`handleError`](https://svelte.dev/docs/kit/hooks#Shared-hooks-handleError) hook runs when an unexpected error is thrown while responding to a request.
+ * The server-side [`handleError`](https://svelte.dev/docs/kit/hooks#handleError) hook runs when an unexpected error is thrown while responding to a request.
  *
  * If an unexpected error is thrown during loading or rendering, this function will be called with the error and the event.
  * Make sure that this function _never_ throws an error.
@@ -974,7 +950,7 @@ export type HandleServerError = (input: {
 }) => MaybePromise<void | AppErrorWithOptionalStatus>;
 
 /**
- * The [`handleValidationError`](https://svelte.dev/docs/kit/hooks#Server-hooks-handleValidationError) hook runs when the argument to a remote function fails validation.
+ * The [`handleValidationError`](https://svelte.dev/docs/kit/hooks#handleValidationError) hook runs when the argument to a remote function fails validation.
  *
  * It will be called with the validation issues and the event, and must return an object shape that matches `App.Error`.
  */
@@ -982,7 +958,7 @@ export type HandleValidationError<Issue extends StandardSchemaV1.Issue = Standar
 	(input: { issues: Issue[]; event: RequestEvent }) => MaybePromise<AppErrorWithOptionalStatus>;
 
 /**
- * The client-side [`handleError`](https://svelte.dev/docs/kit/hooks#Shared-hooks-handleError) hook runs when an unexpected error is thrown while navigating.
+ * The client-side [`handleError`](https://svelte.dev/docs/kit/hooks#handleError) hook runs when an unexpected error is thrown while navigating.
  *
  * If an unexpected error is thrown during loading or the following render, this function will be called with the error and the event.
  * Make sure that this function _never_ throws an error.
@@ -998,7 +974,7 @@ export type HandleClientError = (input: {
 }) => MaybePromise<void | AppErrorWithOptionalStatus>;
 
 /**
- * The [`handleFetch`](https://svelte.dev/docs/kit/hooks#Server-hooks-handleFetch) hook allows you to modify (or replace) the result of an [`event.fetch`](https://svelte.dev/docs/kit/load#Making-fetch-requests) call that runs on the server (or during prerendering) inside an endpoint, `load`, `action`, `handle`, `handleError` or `reroute`.
+ * The [`handleFetch`](https://svelte.dev/docs/kit/hooks#handleFetch) hook allows you to modify (or replace) the result of an [`event.fetch`](https://svelte.dev/docs/kit/load#Making-fetch-requests) call that runs on the server (or during prerendering) inside an endpoint, `load`, `action`, `handle`, `handleError` or `reroute`.
  */
 export type HandleFetch = (input: {
 	event: RequestEvent;
@@ -1007,25 +983,25 @@ export type HandleFetch = (input: {
 }) => MaybePromise<Response>;
 
 /**
- * The [`init`](https://svelte.dev/docs/kit/hooks#Shared-hooks-init) will be invoked before the server responds to its first request
+ * The [`init`](https://svelte.dev/docs/kit/hooks#init) will be invoked before the server responds to its first request
  * @since 2.10.0
  */
 export type ServerInit = () => MaybePromise<void>;
 
 /**
- * The [`init`](https://svelte.dev/docs/kit/hooks#Shared-hooks-init) will be invoked once the app starts in the browser
+ * The [`init`](https://svelte.dev/docs/kit/hooks#init) will be invoked once the app starts in the browser
  * @since 2.10.0
  */
 export type ClientInit = () => MaybePromise<void>;
 
 /**
- * The [`reroute`](https://svelte.dev/docs/kit/hooks#Universal-hooks-reroute) hook allows you to modify the URL before it is used to determine which route to render.
+ * The [`reroute`](https://svelte.dev/docs/kit/hooks#reroute) hook allows you to modify the URL before it is used to determine which route to render.
  * @since 2.3.0
  */
 export type Reroute = (event: { url: URL; fetch: typeof fetch }) => MaybePromise<void | string>;
 
 /**
- * The [`transport`](https://svelte.dev/docs/kit/hooks#Universal-hooks-transport) hook allows you to transport custom types across the server/client boundary.
+ * The [`transport`](https://svelte.dev/docs/kit/hooks#transport) hook allows you to transport custom types across the server/client boundary.
  *
  * Each transporter has a pair of `encode` and `decode` functions. On the server, `encode` determines whether a value is an instance of the custom type and, if so, returns a non-falsy encoding of the value which can be an object or an array (or `false` otherwise).
  *
@@ -1051,7 +1027,7 @@ export type Reroute = (event: { url: URL; fetch: typeof fetch }) => MaybePromise
 export type Transport = Record<string, Transporter>;
 
 /**
- * A member of the [`transport`](https://svelte.dev/docs/kit/hooks#Universal-hooks-transport) hook.
+ * A member of the [`transport`](https://svelte.dev/docs/kit/hooks#transport) hook.
  */
 export interface Transporter<
 	T = any,
@@ -1089,7 +1065,7 @@ export interface LoadEvent<
 	 * - It can be used to make credentialed requests on the server, as it inherits the `cookie` and `authorization` headers for the page request.
 	 * - It can make relative requests on the server (ordinarily, `fetch` requires a URL with an origin when used in a server context).
 	 * - Internal requests (e.g. for `+server.js` routes) go directly to the handler function when running on the server, without the overhead of an HTTP call.
-	 * - During server-side rendering, the response will be captured and inlined into the rendered HTML by hooking into the `text` and `json` methods of the `Response` object. Note that headers will _not_ be serialized, unless explicitly included via [`filterSerializedResponseHeaders`](https://svelte.dev/docs/kit/hooks#Server-hooks-handle)
+	 * - During server-side rendering, the response will be captured and inlined into the rendered HTML by hooking into the `text` and `json` methods of the `Response` object. Note that headers will _not_ be serialized, unless explicitly included via [`filterSerializedResponseHeaders`](https://svelte.dev/docs/kit/hooks#handle)
 	 * - During hydration, the response will be read from the HTML, guaranteeing consistency and preventing an additional network request.
 	 *
 	 * You can learn more about making credentialed requests with cookies [here](https://svelte.dev/docs/kit/load#Cookies)
@@ -1596,7 +1572,7 @@ export interface RequestEvent<
 	 * - It can be used to make credentialed requests on the server, as it inherits the `cookie` and `authorization` headers for the page request.
 	 * - It can make relative requests on the server (ordinarily, `fetch` requires a URL with an origin when used in a server context).
 	 * - Internal requests (e.g. for `+server.js` routes) go directly to the handler function when running on the server, without the overhead of an HTTP call.
-	 * - During server-side rendering, the response will be captured and inlined into the rendered HTML by hooking into the `text` and `json` methods of the `Response` object. Note that headers will _not_ be serialized, unless explicitly included via [`filterSerializedResponseHeaders`](https://svelte.dev/docs/kit/hooks#Server-hooks-handle)
+	 * - During server-side rendering, the response will be captured and inlined into the rendered HTML by hooking into the `text` and `json` methods of the `Response` object. Note that headers will _not_ be serialized, unless explicitly included via [`filterSerializedResponseHeaders`](https://svelte.dev/docs/kit/hooks#handle)
 	 * - During hydration, the response will be read from the HTML, guaranteeing consistency and preventing an additional network request.
 	 *
 	 * You can learn more about making credentialed requests with cookies [here](https://svelte.dev/docs/kit/load#Cookies).
@@ -1607,15 +1583,16 @@ export interface RequestEvent<
 	 */
 	getClientAddress: () => string;
 	/**
-	 * Contains custom data that was added to the request within the [`server handle hook`](https://svelte.dev/docs/kit/hooks#Server-hooks-handle).
+	 * Contains custom data that was added to the request within the [`server handle hook`](https://svelte.dev/docs/kit/hooks#handle).
 	 */
 	locals: App.Locals;
 	/**
 	 * The parameters of the current route - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object.
 	 *
-	 * In the context of a remote function request initiated by the client, this relates to the page the remote function
-	 * was called from, _not_ the URL of the endpoint SvelteKit creates for the remote function. Never use this to determine
-	 * whether or not a user is authorized to access certain data, as these values are part of the request which could be manipulated.
+	 * Inside `query` functions (including `query.batch` and `query.live`), accessing this property throws an error.
+	 * Pass values from the page as arguments to the query instead. Inside `form` and `command` functions it relates to the page
+	 * the remote function was called from, _not_ the URL of the endpoint SvelteKit creates for the remote function. Never use it
+	 * to determine whether or not a user is authorized to access certain data, as these values are part of the request which could be manipulated.
 	 */
 	params: Params;
 	/**
@@ -1633,9 +1610,10 @@ export interface RequestEvent<
 		/**
 		 * The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]`. It is `null` when no route is matched.
 		 *
-		 * In the context of a remote function request initiated by the client, this relates to the page the remote function
-		 * was called from, _not_ the URL of the endpoint SvelteKit creates for the remote function. Never use this to determine
-		 * whether or not a user is authorized to access certain data, as these values are part of the request which could be manipulated.
+		 * Inside `query` functions (including `query.batch` and `query.live`), accessing this property throws an error.
+		 * Pass values from the page as arguments to the query instead. Inside `form` and `command` functions it relates to the page
+		 * the remote function was called from, _not_ the URL of the endpoint SvelteKit creates for the remote function. Never use it
+		 * to determine whether or not a user is authorized to access certain data, as these values are part of the request which could be manipulated.
 		 */
 		id: RouteId;
 	};
@@ -1665,9 +1643,10 @@ export interface RequestEvent<
 	/**
 	 * The requested URL.
 	 *
-	 * In the context of a remote function request initiated by the client, this relates to the page the remote function
-	 * was called from, _not_ the URL of the endpoint SvelteKit creates for the remote function. Never use this to determine
-	 * whether or not a user is authorized to access certain data, as these values are part of the request which could be manipulated.
+	 * Inside `query` functions (including `query.batch` and `query.live`), accessing this property throws an error.
+	 * Pass values from the page as arguments to the query instead. Inside `form` and `command` functions it relates to the page
+	 * the remote function was called from, _not_ the URL of the endpoint SvelteKit creates for the remote function. Never use it
+	 * to determine whether or not a user is authorized to access certain data, as these values are part of the request which could be manipulated.
 	 */
 	url: URL;
 	/**
@@ -2105,7 +2084,7 @@ type AsArgs<Type extends keyof InputTypeMap, Value> = Type extends 'checkbox'
 			? [type: Type, value: Value | (string & {})]
 			: Type extends 'file' | 'file multiple'
 				? [type: Type]
-				: [type: Type] | [type: Type, value: Value | (string & {})];
+				: [type: Type] | [type: Type, value: Value | undefined];
 
 /**
  * Form field accessor type that provides name(), value(), and issues() methods
@@ -2454,16 +2433,35 @@ export interface EnvVarConfig<T> {
 	static?: boolean;
 	/**
 	 * A [Standard Schema](https://standardschema.dev/) validator that is applied to the value when the app starts.
+	 * Alternatively, a function that returns the (possibly transformed) value, or throws an error explaining
+	 * the problem. Returning `undefined` is valid, so a function can describe an optional variable.
 	 * The validator can output any value — not necessarily a string — but public, non-static values must be
 	 * serializable by [devalue](https://github.com/sveltejs/devalue) so that they can be sent to the browser.
 	 *
-	 * If omitted, the value must be a non-empty string.
+	 * If omitted, the value must be set, but may be an empty string.
 	 */
-	schema?: StandardSchemaV1<string | undefined, T>;
+	schema?: StandardSchemaV1<string | undefined, T> | ((value: string | undefined) => T | undefined);
 	/**
 	 * A description of the variable that will be used for inline documentation on hover.
 	 */
 	description?: string;
 }
 
+/**
+ * The return type of [`defineEnvVars`](https://svelte.dev/docs/kit/@sveltejs-kit-env#defineEnvVars).
+ */
+export type DefinedEnvVars<T extends Record<string, EnvVarConfig<any>>> = {
+	readonly [K in keyof T]: EnvVarEntry<T[K]>;
+};
+
+/**
+ * Normalizes an environment variable config's schema (standard schema or function) to standard schema.
+ */
+type EnvVarEntry<C extends EnvVarConfig<any>> =
+	C['schema'] extends StandardSchemaV1<any, any>
+		? C
+		: C['schema'] extends (value: any) => infer R
+			? Omit<C, 'schema'> & { schema: StandardSchemaV1<string | undefined, R> }
+			: C;
+
 export * from './index.js';