@sveltejs/kit 1.0.0-next.521 → 1.0.0-next.523

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltejs/kit",
-  "version": "1.0.0-next.521",
+  "version": "1.0.0-next.523",
   "repository": {
     "type": "git",
     "url": "https://github.com/sveltejs/kit",

package/src/core/adapt/builder.js

@@ -5,7 +5,7 @@ import { pipeline } from 'stream';
 import { promisify } from 'util';
 import { copy, rimraf, mkdirp } from '../../utils/filesystem.js';
 import { generate_manifest } from '../generate_manifest/index.js';
-import { affects_path } from '../../utils/routing.js';
+import { get_route_segments } from '../../utils/routing.js';
 
 const pipe = promisify(pipeline);
 
@@ -48,14 +48,11 @@ export function create_builder({ config, build_data, routes, prerendered, log })
 
 				return {
 					id: route.id,
-					segments: route.id
-						.split('/')
-						.filter(affects_path)
-						.map((segment) => ({
-							dynamic: segment.includes('['),
-							rest: segment.includes('[...'),
-							content: segment
-						})),
+					segments: get_route_segments(route.id).map((segment) => ({
+						dynamic: segment.includes('['),
+						rest: segment.includes('[...'),
+						content: segment
+					})),
 					pattern: route.pattern,
 					methods: Array.from(methods)
 				};

package/src/core/config/options.js

@@ -88,7 +88,7 @@ const options = object(
 			// TODO: remove this for the 1.0 release
 			amp: error(
 				(keypath) =>
-					`${keypath} has been removed. See https://kit.svelte.dev/docs/seo#amp for details on how to support AMP`
+					`${keypath} has been removed. See https://kit.svelte.dev/docs/seo#manual-setup-amp for details on how to support AMP`
 			),
 
 			appDir: validate('_app', (input, keypath) => {
@@ -321,7 +321,7 @@ const options = object(
 			// TODO remove this for 1.0
 			ssr: error(
 				(keypath) =>
-					`${keypath} has been removed — use the handle hook instead: https://kit.svelte.dev/docs/hooks#handle`
+					`${keypath} has been removed — use the handle hook instead: https://kit.svelte.dev/docs/hooks#server-hooks-handle`
 			),
 
 			// TODO remove this for 1.0

package/src/core/prerender/prerender.js

@@ -9,7 +9,7 @@ import { crawl } from './crawl.js';
 import { escape_html_attr } from '../../utils/escape.js';
 import { logger } from '../utils.js';
 import { load_config } from '../config/index.js';
-import { affects_path } from '../../utils/routing.js';
+import { get_route_segments } from '../../utils/routing.js';
 import { get_option } from '../../runtime/server/utils.js';
 
 /**
@@ -370,7 +370,7 @@ export async function prerender() {
 			for (const [id, prerender] of prerender_map) {
 				if (prerender) {
 					if (id.includes('[')) continue;
-					const path = `/${id.split('/').filter(affects_path).join('/')}`;
+					const path = `/${get_route_segments(id).join('/')}`;
 					enqueue(null, config.paths.base + path);
 				}
 			}

package/src/core/sync/create_manifest_data/index.js

@@ -207,7 +207,7 @@ function create_routes_and_nodes(cwd, config, fallback) {
 			}
 		};
 
-		walk(0, '', '', null);
+		walk(0, '/', '', null);
 
 		if (routes.length === 1) {
 			const root = routes[0];
@@ -223,7 +223,7 @@ function create_routes_and_nodes(cwd, config, fallback) {
 		// If there's no routes directory, we'll just create a single empty route. This ensures the root layout and
 		// error components are included in the manifest, which is needed for subsequent build/dev commands to work
 		routes.push({
-			id: '',
+			id: '/',
 			segment: '',
 			pattern: /^$/,
 			names: [],

package/src/core/sync/create_manifest_data/sort.js

@@ -1,4 +1,4 @@
-import { affects_path } from '../../../utils/routing.js';
+import { get_route_segments } from '../../../utils/routing.js';
 
 /**
  * @typedef {{
@@ -133,13 +133,11 @@ export function sort_routes(routes) {
 
 /** @param {string} id */
 function split_route_id(id) {
-	return (
+	return get_route_segments(
 		id
 			// remove all [[optional]] parts unless they're at the very end
 			.replace(/\[\[[^\]]+\]\](?!$)/g, '')
-			.split('/')
-			.filter((segment) => segment !== '' && affects_path(segment))
-	);
+	).filter(Boolean);
 }
 
 /**

package/src/runtime/client/fetcher.js

@@ -29,7 +29,7 @@ if (import.meta.env.DEV) {
 		const heuristic = can_inspect_stack_trace ? stack.includes('load_node') : loading;
 		if (heuristic) {
 			console.warn(
-				`Loading ${url} using \`window.fetch\`. For best results, use the \`fetch\` that is passed to your \`load\` function: https://kit.svelte.dev/docs/load#input-fetch`
+				`Loading ${url} using \`window.fetch\`. For best results, use the \`fetch\` that is passed to your \`load\` function: https://kit.svelte.dev/docs/load#making-fetch-requests`
 			);
 		}
 

package/src/runtime/server/page/load_data.js

@@ -184,7 +184,7 @@ export async function load_data({
 						const included = resolve_opts.filterSerializedResponseHeaders(lower, value);
 						if (!included) {
 							throw new Error(
-								`Failed to get response header "${lower}" — it must be included by the \`filterSerializedResponseHeaders\` option: https://kit.svelte.dev/docs/hooks#handle (at ${event.routeId})`
+								`Failed to get response header "${lower}" — it must be included by the \`filterSerializedResponseHeaders\` option: https://kit.svelte.dev/docs/hooks#server-hooks-handle (at ${event.routeId})`
 							);
 						}
 					}

package/src/runtime/server/page/render.js

@@ -179,7 +179,7 @@ export async function render_response({
 		const match = /\[(\d+)\]\.data\.(.+)/.exec(error.path);
 		if (match) {
 			throw new Error(
-				`Data returned from \`load\` while rendering /${event.routeId} is not serializable: ${error.message} (data.${match[2]})`
+				`Data returned from \`load\` while rendering ${event.routeId} is not serializable: ${error.message} (data.${match[2]})`
 			);
 		}
 		throw error;

package/src/runtime/server/utils.js

@@ -83,7 +83,7 @@ export function data_response(data, event) {
 		const error = /** @type {any} */ (e);
 		const match = /\[(\d+)\]\.data\.(.+)/.exec(error.path);
 		const message = match
-			? `Data returned from \`load\` while rendering /${event.routeId} is not serializable: ${error.message} (data.${match[2]})`
+			? `Data returned from \`load\` while rendering ${event.routeId} is not serializable: ${error.message} (data.${match[2]})`
 			: error.message;
 		return new Response(JSON.stringify(message), { headers, status: 500 });
 	}

package/src/utils/routing.js

@@ -13,12 +13,10 @@ export function parse_route_id(id) {
 	let add_trailing_slash = true;
 
 	const pattern =
-		id === ''
+		id === '/'
 			? /^\/$/
 			: new RegExp(
-					`^${id
-						.split(/(?:\/|$)/)
-						.filter(affects_path)
+					`^${get_route_segments(id)
 						.map((segment, i, segments) => {
 							const decoded_segment = decodeURIComponent(segment);
 							// special case — /[...rest]/ could contain zero segments
@@ -97,10 +95,21 @@ export function parse_route_id(id) {
  * Returns `false` for `(group)` segments
  * @param {string} segment
  */
-export function affects_path(segment) {
+function affects_path(segment) {
 	return !/^\([^)]+\)$/.test(segment);
 }
 
+/**
+ * Splits a route id into its segments, removing segments that
+ * don't affect the path (i.e. groups). The root route is represented by `/`
+ * and will be returned as `['']`.
+ * @param {string} route
+ * @returns string[]
+ */
+export function get_route_segments(route) {
+	return route.slice(1).split('/').filter(affects_path);
+}
+
 /**
  * @param {RegExpMatchArray} match
  * @param {string[]} names

package/types/index.d.ts

@@ -271,18 +271,108 @@ export interface LoadEvent<
 	Data extends Record<string, unknown> | null = Record<string, any> | null,
 	ParentData extends Record<string, unknown> = Record<string, any>
 > extends NavigationEvent<Params> {
+	/**
+	 * `fetch` is equivalent to the [native `fetch` web API](https://developer.mozilla.org/en-US/docs/Web/API/fetch), with a few additional features:
+	 *
+	 * - 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. Note that headers will _not_ be serialized, unless explicitly included via [`filterSerializedResponseHeaders`](https://kit.svelte.dev/docs/hooks#server-hooks-handle)
+	 * - during hydration, the response will be read from the HTML, guaranteeing consistency and preventing an additional network request
+	 *
+	 * > Cookies will only be passed through if the target host is the same as the SvelteKit application or a more specific subdomain of it.
+	 */
 	fetch: typeof fetch;
+	/**
+	 * Contains the data returned by the route's server `load` function (in `+layout.server.js` or `+page.server.js`), if any.
+	 */
 	data: Data;
+	/**
+	 * If you need to set headers for the response, you can do so using the this method. This is useful if you want the page to be cached, for example:
+	 *
+	 *	```js
+	 *	/// file: src/routes/blog/+page.js
+	 *	export async function load({ fetch, setHeaders }) {
+	 *		const url = `https://cms.example.com/articles.json`;
+	 *		const response = await fetch(url);
+	 *
+	 *		setHeaders({
+	 *			age: response.headers.get('age'),
+	 *			'cache-control': response.headers.get('cache-control')
+	 *		});
+	 *
+	 *		return response.json();
+	 *	}
+	 *	```
+	 *
+	 * Setting the same header multiple times (even in separate `load` functions) is an error — you can only set a given header once.
+	 *
+	 * You cannot add a `set-cookie` header with `setHeaders` — use the [`cookies`](https://kit.svelte.dev/docs/types#sveltejs-kit-cookies) API in a server-only `load` function instead.
+	 *
+	 * `setHeaders` has no effect when a `load` function runs in the browser.
+	 */
 	setHeaders: (headers: Record<string, string>) => void;
+	/**
+	 * `await parent()` returns data from parent `+layout.js` `load` functions.
+	 * Implicitly, a missing `+layout.js` is treated as a `({ data }) => data` function, meaning that it will return and forward data from parent `+layout.server.js` files.
+	 *
+	 * Be careful not to introduce accidental waterfalls when using `await parent()`. If for example you only want to merge parent data into the returned output, call it _after_ fetching your other data.
+	 */
 	parent: () => Promise<ParentData>;
+	/**
+	 * This function declares that the `load` function has a _dependency_ on one or more URLs or custom identifiers, which can subsequently be used with [`invalidate()`](/docs/modules#$app-navigation-invalidate) to cause `load` to rerun.
+	 *
+	 * Most of the time you won't need this, as `fetch` calls `depends` on your behalf — it's only necessary if you're using a custom API client that bypasses `fetch`.
+	 *
+	 * URLs can be absolute or relative to the page being loaded, and must be [encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding).
+	 *
+	 * Custom identifiers have to be prefixed with one or more lowercase letters followed by a colon to conform to the [URI specification](https://www.rfc-editor.org/rfc/rfc3986.html).
+	 *
+	 * The following example shows how to use `depends` to register a dependency on a custom identifier, which is `invalidate`d after a button click, making the `load` function rerun.
+	 *
+	 * ```js
+	 * /// file: src/routes/+page.js
+	 * let count = 0;
+	 * export async function load({ depends }) {
+	 * 	depends('increase:count');
+	 *
+	 * 	return { count: count++ };
+	 * }
+	 * ```
+	 *
+	 * ```html
+	 * /// file: src/routes/+page.svelte
+	 * <script>
+	 * 	import { invalidate } from '$app/navigation';
+	 *
+	 * 	export let data;
+	 *
+	 * 	const increase = async () => {
+	 * 		await invalidate('increase:count');
+	 * 	}
+	 * </script>
+	 *
+	 * <p>{data.count}<p>
+	 * <button on:click={increase}>Increase Count</button>
+	 * ```
+	 */
 	depends: (...deps: string[]) => void;
 }
 
 export interface NavigationEvent<
 	Params extends Partial<Record<string, string>> = Partial<Record<string, string>>
 > {
+	/**
+	 * The parameters of the current page - e.g. for a route like `/blog/[slug]`, the `slug` parameter
+	 */
 	params: Params;
+	/**
+	 * The route ID of the current page - e.g. for `src/routes/blog/[slug]`, it would be `blog/[slug]`
+	 */
 	routeId: string | null;
+	/**
+	 * The URL of the current page
+	 */
 	url: URL;
 }
 
@@ -342,15 +432,70 @@ export interface ParamMatcher {
 export interface RequestEvent<
 	Params extends Partial<Record<string, string>> = Partial<Record<string, string>>
 > {
+	/**
+	 * Get or set cookies related to the current request
+	 */
 	cookies: Cookies;
+	/**
+	 * `fetch` is equivalent to the [native `fetch` web API](https://developer.mozilla.org/en-US/docs/Web/API/fetch), with a few additional features:
+	 *
+	 * - 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
+	 *
+	 * > Cookies will only be passed through if the target host is the same as the SvelteKit application or a more specific subdomain of it.
+	 */
 	fetch: typeof fetch;
+	/**
+	 * The client's IP address, set by the adapter.
+	 */
 	getClientAddress: () => string;
+	/**
+	 * Contains custom data that was added to the request within the [`handle hook`](https://kit.svelte.dev/docs/hooks#server-hooks-handle).
+	 */
 	locals: App.Locals;
+	/**
+	 * The parameters of the current page or endpoint - e.g. for a route like `/blog/[slug]`, the `slug` parameter
+	 */
 	params: Params;
+	/**
+	 * Additional data made available through the adapter.
+	 */
 	platform: Readonly<App.Platform>;
+	/**
+	 * The original request object
+	 */
 	request: Request;
+	/**
+	 * The route ID of the current page - e.g. for `src/routes/blog/[slug]`, it would be `blog/[slug]`
+	 */
 	routeId: string | null;
+	/**
+	 * If you need to set headers for the response, you can do so using the this method. This is useful if you want the page to be cached, for example:
+	 *
+	 *	```js
+	 *	/// file: src/routes/blog/+page.js
+	 *	export async function load({ fetch, setHeaders }) {
+	 *		const url = `https://cms.example.com/articles.json`;
+	 *		const response = await fetch(url);
+	 *
+	 *		setHeaders({
+	 *			age: response.headers.get('age'),
+	 *			'cache-control': response.headers.get('cache-control')
+	 *		});
+	 *
+	 *		return response.json();
+	 *	}
+	 *	```
+	 *
+	 * Setting the same header multiple times (even in separate `load` functions) is an error — you can only set a given header once.
+	 *
+	 * You cannot add a `set-cookie` header with `setHeaders` — use the [`cookies`](https://kit.svelte.dev/docs/types#sveltejs-kit-cookies) API instead.
+	 */
 	setHeaders: (headers: Record<string, string>) => void;
+	/**
+	 * The URL of the current page or endpoint
+	 */
 	url: URL;
 }
 
@@ -415,7 +560,49 @@ export interface ServerLoadEvent<
 	Params extends Partial<Record<string, string>> = Partial<Record<string, string>>,
 	ParentData extends Record<string, any> = Record<string, any>
 > extends RequestEvent<Params> {
+	/**
+	 * `await parent()` returns data from parent `+layout.server.js` `load` functions.
+	 *
+	 * Be careful not to introduce accidental waterfalls when using `await parent()`. If for example you only want to merge parent data into the returned output, call it _after_ fetching your other data.
+	 */
 	parent: () => Promise<ParentData>;
+	/**
+	 * This function declares that the `load` function has a _dependency_ on one or more URLs or custom identifiers, which can subsequently be used with [`invalidate()`](/docs/modules#$app-navigation-invalidate) to cause `load` to rerun.
+	 *
+	 * Most of the time you won't need this, as `fetch` calls `depends` on your behalf — it's only necessary if you're using a custom API client that bypasses `fetch`.
+	 *
+	 * URLs can be absolute or relative to the page being loaded, and must be [encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding).
+	 *
+	 * Custom identifiers have to be prefixed with one or more lowercase letters followed by a colon to conform to the [URI specification](https://www.rfc-editor.org/rfc/rfc3986.html).
+	 *
+	 * The following example shows how to use `depends` to register a dependency on a custom identifier, which is `invalidate`d after a button click, making the `load` function rerun.
+	 *
+	 * ```js
+	 * /// file: src/routes/+page.js
+	 * let count = 0;
+	 * export async function load({ depends }) {
+	 * 	depends('increase:count');
+	 *
+	 * 	return { count: count++ };
+	 * }
+	 * ```
+	 *
+	 * ```html
+	 * /// file: src/routes/+page.svelte
+	 * <script>
+	 * 	import { invalidate } from '$app/navigation';
+	 *
+	 * 	export let data;
+	 *
+	 * 	const increase = async () => {
+	 * 		await invalidate('increase:count');
+	 * 	}
+	 * </script>
+	 *
+	 * <p>{data.count}<p>
+	 * <button on:click={increase}>Increase Count</button>
+	 * ```
+	 */
 	depends: (...deps: string[]) => void;
 }