Remote Functions

documentation/docs/30-advanced/20-hooks.md

@@ -143,6 +143,34 @@ export async function handleFetch({ event, request, fetch }) {
 }
 ```
 
+### handleValidationError
+
+This hook is called when a remote function schema validation fails. It is expected to return an object shape matching that of `App.Error`.
+
+Say you have a remote function that expects a string as its argument ...
+
+```js
+/// file: todos.remote.js
+import z from 'zod';
+import { query } from '$app/server';
+
+export getTodo = query(z.string(), id => {
+	// implementation...
+})
+```
+
+... but it is called with a number instead (e.g `getTodos(1)`), then the schema validation will fail. By default, a response with status `400` and just the string `Bad Request` will be returned. Implement `handleValidationError` to return a more informative error object instead. If you use `Zod` this could be a simple as using one its built-in formatters:
+
+```js
+/// file: src/hooks.server.js
+import z from 'zod';
+
+/** @type {import('@sveltejs/kit').HandleValidationError} */
+export const handleValidationError = ({ result }) => {
+  return { message: 'Schema Error', validationErrors: z.treeifyError(result.error)};
+}
+```
+
 ## Shared hooks
 
 The following can be added to `src/hooks.server.js` _and_ `src/hooks.client.js`:

packages/enhanced-img/src/vite-plugin.js

@@ -316,7 +316,7 @@ function stringToNumber(param) {
  * @param {import('vite-imagetools').Picture} image
  */
 function img_to_picture(content, node, image) {
-	/** @type {import('../types/internal.js').Attribute[]} attributes */
+	/** @type {import('../types/internal.js').Attribute[]} */
 	const attributes = node.attributes;
 	const index = attributes.findIndex(
 		(attribute) => 'name' in attribute && attribute.name === 'sizes'

packages/kit/package.json

@@ -18,6 +18,7 @@
 	"homepage": "https://svelte.dev",
 	"type": "module",
 	"dependencies": {
+		"@standard-schema/spec": "^1.0.0",
 		"@sveltejs/acorn-typescript": "^1.0.5",
 		"@types/cookie": "^0.6.0",
 		"acorn": "^8.14.1",
@@ -37,7 +38,7 @@
 		"@types/connect": "^3.4.38",
 		"@types/node": "^18.19.48",
 		"@types/set-cookie-parser": "^2.4.7",
-		"dts-buddy": "^0.6.1",
+		"dts-buddy": "^0.6.2",
 		"rollup": "^4.14.2",
 		"svelte": "^5.35.5",
 		"svelte-preprocess": "^6.0.0",

packages/kit/src/core/config/index.spec.js

@@ -76,6 +76,9 @@ const get_defaults = (prefix = '') => ({
 			publicPrefix: 'PUBLIC_',
 			privatePrefix: ''
 		},
+		experimental: {
+			remoteFunctions: false
+		},
 		files: {
 			assets: join(prefix, 'static'),
 			hooks: {

packages/kit/src/core/config/options.js

@@ -120,6 +120,10 @@ const options = object(
 				privatePrefix: string('')
 			}),
 
+			experimental: object({
+				remoteFunctions: boolean(false)
+			}),
+
 			files: object({
 				assets: string('static'),
 				hooks: object({

packages/kit/src/core/generate_manifest/index.js

@@ -8,6 +8,7 @@ import { compact } from '../../utils/array.js';
 import { join_relative } from '../../utils/filesystem.js';
 import { dedent } from '../sync/utils.js';
 import { find_server_assets } from './find_server_assets.js';
+import { hash } from '../../utils/hash.js';
 import { uneval } from 'devalue';
 
 /**
@@ -100,6 +101,9 @@ export function generate_manifest({ build_data, prerendered, relative_path, rout
 				nodes: [
 					${(node_paths).map(loader).join(',\n')}
 				],
+				remotes: {
+					${build_data.manifest_data.remotes.map((filename) => `'${hash(filename)}': ${loader(join_relative(relative_path, resolve_symlinks(build_data.server_manifest, filename).chunk.file))}`).join(',\n\t\t\t\t\t')}
+				},
 				routes: [
 					${routes.map(route => {
 						if (!route.page && !route.endpoint) return;

packages/kit/src/core/postbuild/analyse.js

@@ -82,7 +82,8 @@ async function analyse({
 	/** @type {import('types').ServerMetadata} */
 	const metadata = {
 		nodes: [],
-		routes: new Map()
+		routes: new Map(),
+		remotes: new Map()
 	};
 
 	const nodes = await Promise.all(manifest._.nodes.map((loader) => loader()));
@@ -164,6 +165,18 @@ async function analyse({
 		});
 	}
 
+	// analyse remotes
+	for (const [hash, load] of Object.entries(manifest._.remotes)) {
+		const modules = await load();
+		const exports = new Map();
+		for (const [name, value] of Object.entries(modules)) {
+			const type = /** @type {import('types').RemoteInfo} */ (value.__)?.type;
+			if (!type) continue;
+			exports.set(type, (exports.get(type) ?? []).concat(name));
+		}
+		metadata.remotes.set(hash, exports);
+	}
+
 	return { metadata, static_exports };
 }
 

packages/kit/src/core/postbuild/fallback.js

@@ -41,7 +41,8 @@ async function generate_fallback({ manifest_path, env }) {
 		},
 		prerendering: {
 			fallback: true,
-			dependencies: new Map()
+			dependencies: new Map(),
+			remote_responses: new Map()
 		},
 		read: (file) => readFileSync(join(config.files.assets, file))
 	});

packages/kit/src/core/postbuild/prerender.js

@@ -14,6 +14,7 @@ import { forked } from '../../utils/fork.js';
 import * as devalue from 'devalue';
 import { createReadableStream } from '@sveltejs/kit/node';
 import generate_fallback from './fallback.js';
+import { stringify_remote_arg } from '../../runtime/shared.js';
 
 export default forked(import.meta.url, prerender);
 
@@ -186,6 +187,7 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env }) {
 	}
 	const seen = new Set();
 	const written = new Set();
+	const remote_responses = new Map();
 
 	/** @type {Map<string, Set<string>>} */
 	const expected_hashlinks = new Map();
@@ -229,7 +231,8 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env }) {
 				throw new Error('Cannot read clientAddress during prerendering');
 			},
 			prerendering: {
-				dependencies
+				dependencies,
+				remote_responses
 			},
 			read: (file) => {
 				// stuff we just wrote
@@ -460,8 +463,25 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env }) {
 		}
 	}
 
+	/** @type {Array<Function & { __: import('types').RemoteInfo & { type: 'prerender'}}>} */
+	const remote_functions = [];
+
+	for (const remote of Object.values(manifest._.remotes)) {
+		const functions = Object.values(await remote()).filter(
+			(value) =>
+				typeof value === 'function' &&
+				/** @type {import('types').RemoteInfo} */ (value.__)?.type === 'prerender'
+		);
+		if (functions.length > 0) {
+			has_prerenderable_routes = true;
+			remote_functions.push(...functions);
+		}
+	}
+
 	if (
-		(config.prerender.entries.length === 0 && route_level_entries.length === 0) ||
+		(config.prerender.entries.length === 0 &&
+			route_level_entries.length === 0 &&
+			remote_functions.length === 0) ||
 		!has_prerenderable_routes
 	) {
 		return { prerendered, prerender_map };
@@ -499,6 +519,32 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env }) {
 		}
 	}
 
+	const transport = (await internal.get_hooks()).transport ?? {};
+	for (const remote_function of remote_functions) {
+		// TODO this writes to /prerender/pages/... eventually, should it go into
+		// /prerender/dependencies like indirect calls due to page prerenders?
+		// Does it really matter?
+		if (remote_function.__.entries) {
+			for (const entry of await remote_function.__.entries()) {
+				void enqueue(
+					null,
+					config.paths.base +
+						'/' +
+						config.appDir +
+						'/remote/' +
+						remote_function.__.id +
+						'/' +
+						stringify_remote_arg(entry, transport)
+				);
+			}
+		} else {
+			void enqueue(
+				null,
+				config.paths.base + '/' + config.appDir + '/remote/' + remote_function.__.id
+			);
+		}
+	}
+
 	await q.done();
 
 	// handle invalid fragment links

packages/kit/src/core/sync/create_manifest_data/index.js

@@ -4,7 +4,7 @@ import process from 'node:process';
 import colors from 'kleur';
 import { lookup } from 'mrmime';
 import { list_files, runtime_directory } from '../../utils.js';
-import { posixify, resolve_entry } from '../../../utils/filesystem.js';
+import { posixify, resolve_entry, walk } from '../../../utils/filesystem.js';
 import { parse_route_id } from '../../../utils/routing.js';
 import { sort_routes } from './sort.js';
 import { isSvelte5Plus } from '../utils.js';
@@ -27,6 +27,7 @@ export default function create_manifest_data({
 	const hooks = create_hooks(config, cwd);
 	const matchers = create_matchers(config, cwd);
 	const { nodes, routes } = create_routes_and_nodes(cwd, config, fallback);
+	const remotes = create_remotes(config);
 
 	for (const route of routes) {
 		for (const param of route.params) {
@@ -41,6 +42,7 @@ export default function create_manifest_data({
 		hooks,
 		matchers,
 		nodes,
+		remotes,
 		routes
 	};
 }
@@ -465,6 +467,24 @@ function create_routes_and_nodes(cwd, config, fallback) {
 	};
 }
 
+/**
+ * @param {import('types').ValidatedConfig} config
+ */
+function create_remotes(config) {
+	if (!config.kit.experimental.remoteFunctions) return [];
+
+	const extensions = config.kit.moduleExtensions.map((ext) => `.remote${ext}`);
+
+	// TODO could files live in other directories, including node_modules?
+	return [config.kit.files.lib, config.kit.files.routes].flatMap((dir) =>
+		fs.existsSync(dir)
+			? walk(dir)
+					.filter((file) => extensions.some((ext) => file.endsWith(ext)))
+					.map((file) => posixify(`${dir}/${file}`))
+			: []
+	);
+}
+
 /**
  * @param {string} project_relative
  * @param {string} file

packages/kit/src/core/sync/write_server.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import process from 'node:process';
-import { hash } from '../../runtime/hash.js';
+import { hash } from '../../utils/hash.js';
 import { posixify, resolve_entry } from '../../utils/filesystem.js';
 import { s } from '../../utils/misc.js';
 import { load_error_page, load_template } from '../config/index.js';
@@ -67,8 +67,9 @@ export async function get_hooks() {
 	let handle;
 	let handleFetch;
 	let handleError;
+	let handleValidationError;
 	let init;
-	${server_hooks ? `({ handle, handleFetch, handleError, init } = await import(${s(server_hooks)}));` : ''}
+	${server_hooks ? `({ handle, handleFetch, handleError, handleValidationError, init } = await import(${s(server_hooks)}));` : ''}
 
 	let reroute;
 	let transport;
@@ -78,6 +79,7 @@ export async function get_hooks() {
 		handle,
 		handleFetch,
 		handleError,
+		handleValidationError,
 		init,
 		reroute,
 		transport

packages/kit/src/exports/index.js

@@ -188,7 +188,7 @@ export function text(body, init) {
  */
 /**
  * Create an `ActionFailure` object. Call when form submission fails.
- * @template {Record<string, unknown> | undefined} [T=undefined]
+ * @template [T=undefined]
  * @param {number} status The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses). Must be in the range 400-599.
  * @param {T} data Data associated with the failure (e.g. validation errors)
  * @overload

packages/kit/src/exports/internal/index.js

@@ -49,7 +49,7 @@ export class SvelteKitError extends Error {
 }
 
 /**
- * @template {Record<string, unknown> | undefined} [T=undefined]
+ * @template [T=undefined]
  */
 export class ActionFailure {
 	/**