feat: allow serialization/deserialization of custom data types (alternative API) (#13149)

* feat: allow serialization/deserialization of custom data types

* feat: allow serialization/deserialization of custom data types

* feat: allow serialization/deserialization of custom data types

* feat: allow serialization/deserialization of custom data types

* feat: allow serialization/deserialization of custom data types

* add test

* fix bugs

* lint

* improve test name

* lint

* alternative approach

* tweak

* added more tests and moved to basics

* lint

* fix typo

* fix test

* address feedback

* comment

* make it work

* Update packages/kit/src/core/sync/write_client_manifest.js

Co-authored-by: Rich Harris <[email protected]>

* use universal transport hook

* fix

* Update packages/kit/src/core/sync/write_client_manifest.js

* tweaks

* add types, rename to encode/decode

* docs

* regenerate

* changeset

---------

Co-authored-by: Dominic Gannaway <[email protected]>
Co-authored-by: Simon H <[email protected]>
Co-authored-by: Dominic Gannaway <[email protected]>

Author: 3 people

.changeset/fast-dragons-own.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: transport custom types across the server/client boundary

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

@@ -290,6 +290,23 @@ The `lang` parameter will be correctly derived from the returned pathname.
 
 Using `reroute` will _not_ change the contents of the browser's address bar, or the value of `event.url`.
 
+### transport
+
+This is a collection of _transporters_, which allow you to pass custom types — returned from `load` and form actions — across the server/client boundary. Each transporter contains an `encode` function, which encodes values on the server (or returns `false` for anything that isn't an instance of the type) and a corresponding `decode` function:
+
+```js
+/// file: src/hooks.js
+import { Vector } from '$lib/math';
+
+/** @type {import('@sveltejs/kit').Transport} */
+export const transport = {
+	Vector: {
+		encode: (value) => value instanceof Vector && [value.x, value.y],
+		decode: ([x, y]) => new Vector(x, y)
+	}
+};
+```
+
 
 ## Further reading
 

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

@@ -152,10 +152,14 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 					client_hooks_file ? 'client_hooks.handleError || ' : ''
 				}(({ error }) => { console.error(error) }),
 				${client_hooks_file ? 'init: client_hooks.init,' : ''}
-
-				reroute: ${universal_hooks_file ? 'universal_hooks.reroute || ' : ''}(() => {})
+				reroute: ${universal_hooks_file ? 'universal_hooks.reroute || ' : ''}(() => {}),
+				transport: ${universal_hooks_file ? 'universal_hooks.transport || ' : ''}{}
 			};
 
+			export const decoders = Object.fromEntries(Object.entries(hooks.transport).map(([k, v]) => [k, v.decode]));
+
+			export const decode = (type, value) => decoders[type](value);
+
 			export { default as root } from '../root.${isSvelte5Plus() ? 'js' : 'svelte'}';
 		`
 	);

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

@@ -71,14 +71,16 @@ export async function get_hooks() {
 	${server_hooks ? `({ handle, handleFetch, handleError, init } = await import(${s(server_hooks)}));` : ''}
 
 	let reroute;
-	${universal_hooks ? `({ reroute } = await import(${s(universal_hooks)}));` : ''}
+	let transport;
+	${universal_hooks ? `({ reroute, transport } = await import(${s(universal_hooks)}));` : ''}
 
 	return {
 		handle,
 		handleFetch,
 		handleError,
-		reroute,
 		init,
+		reroute,
+		transport
 	};
 }
 

packages/kit/src/exports/public.d.ts

@@ -742,6 +742,43 @@ export type ClientInit = () => MaybePromise<void>;
  */
 export type Reroute = (event: { url: URL }) => 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.
+ *
+ * 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).
+ *
+ * In the browser, `decode` turns the encoding back into an instance of the custom type.
+ *
+ * ```ts
+ * import type { Transport } from '@sveltejs/kit';
+ *
+ * declare class MyCustomType {
+ * 	data: any
+ * }
+ *
+ * // hooks.js
+ * export const transport: Transport = {
+ * 	MyCustomType: {
+ * 		encode: (value) => value instanceof MyCustomType && [value.data],
+ * 		decode: ([data]) => new MyCustomType(data)
+ * 	}
+ * };
+ * ```
+ * @since 2.11.0
+ */
+export type Transport = Record<string, Transporter>;
+
+/**
+ * A member of the [`transport`](https://svelte.dev/docs/kit/hooks#Universal-hooks-transport) hook.
+ */
+export interface Transporter<
+	T = any,
+	U = Exclude<any, false | 0 | '' | null | undefined | typeof NaN>
+> {
+	encode: (value: T) => false | U;
+	decode: (data: U) => T;
+}
+
 /**
  * The generic form of `PageLoad` and `LayoutLoad`. You should import those from `./$types` (see [generated types](https://svelte.dev/docs/kit/types#Generated-types))
  * rather than using `Load` directly.

packages/kit/src/runtime/app/forms.js

@@ -1,7 +1,7 @@
 import * as devalue from 'devalue';
 import { DEV } from 'esm-env';
 import { invalidateAll } from './navigation.js';
-import { applyAction } from '../client/client.js';
+import { app, applyAction } from '../client/client.js';
 
 export { applyAction };
 
@@ -29,9 +29,11 @@ export { applyAction };
  */
 export function deserialize(result) {
 	const parsed = JSON.parse(result);
+
 	if (parsed.data) {
-		parsed.data = devalue.parse(parsed.data);
+		parsed.data = devalue.parse(parsed.data, app.decoders);
 	}
+
 	return parsed;
 }
 

packages/kit/src/runtime/client/client.js

@@ -174,7 +174,7 @@ let container;
 /** @type {HTMLElement} */
 let target;
 /** @type {import('./types.js').SvelteKitApp} */
-let app;
+export let app;
 
 /** @type {Array<((url: URL) => boolean)>} */
 const invalidated = [];
@@ -2493,6 +2493,7 @@ async function load_data(url, invalid) {
 		 */
 		function deserialize(data) {
 			return devalue.unflatten(data, {
+				...app.decoders,
 				Promise: (id) => {
 					return new Promise((fulfil, reject) => {
 						deferreds.set(id, { fulfil, reject });

packages/kit/src/runtime/client/types.d.ts

@@ -26,6 +26,10 @@ export interface SvelteKitApp {
 
 	hooks: ClientHooks;
 
+	decode: (type: string, value: any) => any;
+
+	decoders: Record<string, (data: any) => any>;
+
 	root: typeof SvelteComponent;
 }
 
@@ -54,7 +58,7 @@ export type NavigationFinished = {
 	state: NavigationState;
 	props: {
 		constructors: Array<typeof SvelteComponent>;
-		components?: Array<SvelteComponent>;
+		components?: SvelteComponent[];
 		page: Page;
 		form?: Record<string, any> | null;
 		[key: `data_${number}`]: Record<string, any>;

packages/kit/src/runtime/server/data/index.js

@@ -197,6 +197,9 @@ export function get_data_json(event, options, nodes) {
 	const { iterator, push, done } = create_async_iterator();
 
 	const reducers = {
+		...Object.fromEntries(
+			Object.entries(options.hooks.transport).map(([key, value]) => [key, value.encode])
+		),
 		/** @param {any} thing */
 		Promise: (thing) => {
 			if (typeof thing?.then === 'function') {

packages/kit/src/runtime/server/index.js

@@ -76,7 +76,8 @@ export class Server {
 					handle: module.handle || (({ event, resolve }) => resolve(event)),
 					handleError: module.handleError || (({ error }) => console.error(error)),
 					handleFetch: module.handleFetch || (({ request, fetch }) => fetch(request)),
-					reroute: module.reroute || (() => {})
+					reroute: module.reroute || (() => {}),
+					transport: module.transport || {}
 				};
 
 				if (module.init) {
@@ -90,7 +91,8 @@ export class Server {
 						},
 						handleError: ({ error }) => console.error(error),
 						handleFetch: ({ request, fetch }) => fetch(request),
-						reroute: () => {}
+						reroute: () => {},
+						transport: {}
 					};
 				} else {
 					throw error;