@skgo/sveltekit-adapter 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@skgo/sveltekit-adapter",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"description": "SvelteKit adapter for skgo: builds a frontend that a Go binary renders and answers",
 	"keywords": [
 		"adapter",
@@ -33,6 +33,7 @@
 		"skgo-adapter/app-server.js",
 		"skgo-adapter/entry.js",
 		"skgo-adapter/env.js",
+		"skgo-adapter/generated.js",
 		"skgo-adapter/identity.js",
 		"skgo-adapter/polyfill.js"
 	],

package/skgo-adapter/entry.js

@@ -22,7 +22,7 @@ import {
 } from '@sveltejs/kit/internal/server';
 import * as devalue from 'skgo:devalue';
 import { decoders, init_transport, parse } from 'skgo:kit/transport';
-import { components } from 'skgo:nodes';
+import { components, universalLoads } from 'skgo:nodes';
 import { transport } from 'skgo:hooks';
 
 /**
@@ -218,7 +218,7 @@ function node_data(node) {
 	});
 }
 
-function build_props(req, url) {
+async function build_props(req, url) {
 	const form = req.form ? devalue.parse(req.form, decoders) : null;
 	const page = {
 		error: req.error ?? null,
@@ -248,7 +248,30 @@ function build_props(req, url) {
 	let data = props.page.data;
 
 	for (let i = 0; i < branch.length; i += 1) {
-		data = { ...data, ...node_data(branch[i]) };
+		const server_data = node_data(branch[i]);
+		const load = universalLoads[branch[i].node];
+		const parent_data = data;
+		const result = load
+			? await load.call(null, {
+				url,
+				params: req.params ?? {},
+				data: server_data,
+				route: { id: req.route_id ?? null },
+				parent: async () => parent_data,
+				depends: () => {},
+				untrack: (fn) => fn(),
+				fetch: () => {
+					throw new Error('skgo: universal load fetch is not supported during rendering');
+				},
+				setHeaders: () => {
+					throw new Error('skgo: universal load setHeaders is not supported during rendering');
+				}
+			})
+			: server_data;
+		if (result != null && Object.getPrototypeOf(result) !== Object.prototype) {
+			throw new Error('skgo: universal load must return a plain object');
+		}
+		data = { ...data, ...result };
 		current_node.data = data;
 
 		if (i < branch.length - 1) {
@@ -344,48 +367,48 @@ globalThis.__skgo_render = function (req_json) {
 	try {
 		const req = JSON.parse(req_json);
 		const url = new URL(req.url);
-		const props = build_props(req, url);
+		const props_promise = build_props(req, url);
 		const state = make_state();
 		const event = make_event(req, url);
-
-		result.status = props.page.status;
-		result.error = req.error ?? null;
-
-		const options = {
-			context: new Map([['__request__', { page: props.page }]]),
-			// kit's own \`csp.script_needs_nonce ? { nonce: csp.nonce } : {
-			// hash: csp.script_needs_hash }\` (page/render.js:198), passed to
-			// Svelte's own renderer so the one inline script Svelte can still
-			// emit on its own — its hydratable-async-block script
-			// (internal/server/renderer.js's #hydratable_block, for a
-			// component's own top-level await) — carries the same nonce or
-			// hash decision the boot script gets from Go (csp.go). Go decided
-			// which branch this request is in before the engine ever ran;
-			// req.csp carries only the answer.
-			csp: req.csp.nonce ? { nonce: req.csp.nonce } : { hash: !!req.csp.hash },
-			// kit's own (page/render.js): the transform every error boundary's
-			// error passes through on its way to the failed snippet. It is
-			// what makes page.status and page.error inside a rendering
-			// component the values kit would give, and what turns an
-			// unexpected throw into Internal Error rather than a stack trace on
-			// the page. A redirect is rethrown, because a redirect is an answer
-			// for the whole document rather than for one boundary.
-			transformError: (e) => {
-				if (e instanceof Redirect) throw e;
-				const handled = handle_error(e);
-				result.error = handled;
-				result.status = handled.status;
-				props.page.error = handled;
-				props.page.status = handled.status;
-				return handled;
-			}
-		};
-		// seed_form runs inside the request store rather than before it: a
-		// keyed submission's call to for(key) needs the request store, the
-		// same as the page component's own call to it does.
-		const promise = with_request_store({ event, state }, () => {
-			seed_form(req, state);
-			return render(Root, { ...options, props });
+		const promise = props_promise.then((props) => {
+			result.status = props.page.status;
+			result.error = req.error ?? null;
+			const options = {
+				context: new Map([['__request__', { page: props.page }]]),
+				// kit's own \`csp.script_needs_nonce ? { nonce: csp.nonce } : {
+				// hash: csp.script_needs_hash }\` (page/render.js:198), passed to
+				// Svelte's own renderer so the one inline script Svelte can still
+				// emit on its own — its hydratable-async-block script
+				// (internal/server/renderer.js's #hydratable_block, for a
+				// component's own top-level await) — carries the same nonce or
+				// hash decision the boot script gets from Go (csp.go). Go decided
+				// which branch this request is in before the engine ever ran;
+				// req.csp carries only the answer.
+				csp: req.csp.nonce ? { nonce: req.csp.nonce } : { hash: !!req.csp.hash },
+				// kit's own (page/render.js): the transform every error boundary's
+				// error passes through on its way to the failed snippet. It is
+				// what makes page.status and page.error inside a rendering
+				// component the values kit would give, and what turns an
+				// unexpected throw into Internal Error rather than a stack trace on
+				// the page. A redirect is rethrown, because a redirect is an answer
+				// for the whole document rather than for one boundary.
+				transformError: (e) => {
+					if (e instanceof Redirect) throw e;
+					const handled = handle_error(e);
+					result.error = handled;
+					result.status = handled.status;
+					props.page.error = handled;
+					props.page.status = handled.status;
+					return handled;
+				}
+			};
+			// seed_form runs inside the request store rather than before it: a
+			// keyed submission's call to for(key) needs the request store, the
+			// same as the page component's own call to it does.
+			return with_request_store({ event, state }, () => {
+				seed_form(req, state);
+				return render(Root, { ...options, props });
+			});
 		});
 
 		Promise.resolve(promise).then(

package/skgo-adapter/env.js

@@ -428,14 +428,21 @@ function basenameOf(file) {
  * kit's build produced, in the manifest's own node order.
  *
  * @param {string} root
- * @param {Array<{ component: string | null }>} nodes
+ * @param {Array<{ component: string | null, universal: string | null }>} nodes
  */
 export function nodeTable(root, nodes) {
 	/** @type {string[]} */
 	const imports = [];
 	/** @type {string[]} */
 	const table = [];
+	const loads = [];
 	nodes.forEach((node, i) => {
+		if (node.universal) {
+			imports.push(`import * as U${i} from ${JSON.stringify(join(root, node.universal))};`);
+			loads.push(`U${i}.load`);
+		} else {
+			loads.push('undefined');
+		}
 		if (!node.component) {
 			table.push('undefined');
 			return;
@@ -443,7 +450,7 @@ export function nodeTable(root, nodes) {
 		imports.push(`import N${i} from ${JSON.stringify(join(root, node.component))};`);
 		table.push(`N${i}`);
 	});
-	return `${imports.join('\n')}\nexport const components = [${table.join(', ')}];\n`;
+	return `${imports.join('\n')}\nexport const components = [${table.join(', ')}];\nexport const universalLoads = [${loads.join(', ')}];\n`;
 }
 
 /**
@@ -565,7 +572,14 @@ function devNodeTable(manifest, root) {
 	const imports = [];
 	/** @type {string[]} */
 	const table = [];
+	const loads = [];
 	for (const [index, node] of manifest.nodes.entries()) {
+		if (node.universal) {
+			imports.push(`import * as U${index} from ${JSON.stringify(resolve(root, node.universal))};`);
+			loads.push(`U${index}.load`);
+		} else {
+			loads.push('undefined');
+		}
 		if (!node.component) {
 			table.push('undefined');
 			continue;
@@ -573,7 +587,7 @@ function devNodeTable(manifest, root) {
 		imports.push(`import N${index} from ${JSON.stringify(resolve(root, node.component))};`);
 		table.push(`N${index}`);
 	}
-	return `${imports.join('\n')}\nexport const components = [${table.join(', ')}];\n`;
+	return `${imports.join('\n')}\nexport const components = [${table.join(', ')}];\nexport const universalLoads = [${loads.join(', ')}];\n`;
 }
 
 /**

package/skgo-adapter/generated.js

@@ -0,0 +1,118 @@
+/**
+ * The shape `skgo generate` promises in `skgo.remotes.json`, checked without a
+ * SvelteKit build around it.
+ *
+ * The adapter refuses a manifest it cannot read before it copies anything into
+ * the build, and the Go module refuses a build whose manifest does not match
+ * what it answers. The checks live here, apart from the adapter entry and its
+ * kit imports, so they can be exercised directly: the paths they validate are
+ * `.ts` in a TypeScript app and `.js` in a JavaScript one, and both are
+ * first-class.
+ *
+ * @param {any} parsed the parsed contents of `skgo.remotes.json`
+ * @returns {{ remotes: string[], loads: string[], actions: string[], endpoints: Record<string, string[]> }}
+ */
+export function validateGenerated(parsed) {
+	if (!Array.isArray(parsed.remotes)) {
+		throw new Error(
+			'skgo: skgo.remotes.json has no `remotes` array. Run `go generate ./...` before building the frontend.'
+		);
+	}
+	for (const id of parsed.remotes) {
+		if (typeof id !== 'string' || !/^[^/]+\/[^/]+$/.test(id)) {
+			throw new Error(
+				`skgo: skgo.remotes.json lists ${JSON.stringify(id)}, which is not a <hash>/<name> id.`
+			);
+		}
+	}
+	if (!Array.isArray(parsed.loads)) {
+		throw new Error(
+			'skgo: skgo.remotes.json has no `loads` array. Run `go generate ./...` before building the frontend.'
+		);
+	}
+	for (const module of parsed.loads) {
+		if (typeof module !== 'string' || !/\/\+(page|layout)\.server\.(ts|js)$/.test(module)) {
+			throw new Error(
+				`skgo: skgo.remotes.json lists ${JSON.stringify(module)}, which is not a +page.server.(ts|js) or +layout.server.(ts|js) path.`
+			);
+		}
+	}
+	if (!Array.isArray(parsed.actions)) {
+		throw new Error('skgo: skgo.remotes.json has no `actions` array. Run `go generate ./...` before building the frontend.');
+	}
+	for (const module of parsed.actions) {
+		if (typeof module !== 'string' || !/\/\+page\.server\.(ts|js)$/.test(module)) {
+			throw new Error(`skgo: skgo.remotes.json lists ${JSON.stringify(module)}, which is not a +page.server.(ts|js) action path.`);
+		}
+	}
+	if (typeof parsed.endpoints !== 'object' || parsed.endpoints === null || Array.isArray(parsed.endpoints)) {
+		throw new Error(
+			'skgo: skgo.remotes.json has no `endpoints` object. Run `go generate ./...` before building the frontend.'
+		);
+	}
+	for (const [id, methods] of Object.entries(parsed.endpoints)) {
+		if (!id.startsWith('/') || !Array.isArray(methods) || methods.length === 0) {
+			throw new Error(
+				`skgo: skgo.remotes.json maps ${JSON.stringify(id)} to ${JSON.stringify(methods)}, which is not a route id and its methods.`
+			);
+		}
+	}
+	return { remotes: parsed.remotes, loads: parsed.loads, actions: parsed.actions, endpoints: parsed.endpoints };
+}
+
+/**
+ * The check for server routes, against the one place kit reports what it
+ * compiled: `builder.routes[].api.methods`, which kit derives by importing each
+ * built `+server.js` and reading its exports
+ * (packages/kit/src/core/postbuild/analyse.js, `analyse_endpoint`). A `fallback`
+ * export travels there as `'*'`, and `skgo generate` writes the same spelling,
+ * so the two lists are compared literally.
+ *
+ * It lives here rather than in the adapter entry so it can be exercised without
+ * a SvelteKit build around it, exactly as `validateGenerated` is. That is what
+ * lets a test prove it accepts `QUERY` and `'*'` and still refuses a mismatch.
+ *
+ * This is the check that makes a hand-written `+server.ts` fail the build rather
+ * than 404 in the browser: kit would compile it, Go would never have been told
+ * about it, and the route would answer nothing.
+ *
+ * @param {{ routes: Array<{ id: string, api: { methods: string[] } }> }} builder
+ * @param {Record<string, string[]>} declared
+ * @returns {Map<string, string[]>} the methods kit compiled, per route id
+ */
+export function checkEndpoints(builder, declared) {
+	/** @type {Map<string, string[]>} */
+	const built = new Map();
+	for (const route of builder.routes) {
+		if (route.api.methods.length > 0) built.set(route.id, [...route.api.methods].sort());
+	}
+
+	/** @type {string[]} */
+	const problems = [];
+	for (const [id, methods] of Object.entries(declared)) {
+		const compiled = built.get(id);
+		if (!compiled) {
+			problems.push(`  generated but not compiled: ${methods.join(', ')} ${id}`);
+			continue;
+		}
+		const want = [...methods].sort().join(', ');
+		const got = compiled.join(', ');
+		if (want !== got) {
+			problems.push(`  ${id}: Go answers ${want}, the built +server module exports ${got}`);
+		}
+	}
+	for (const [id, methods] of built) {
+		if (!(id in declared)) {
+			problems.push(`  compiled but not generated: ${methods.join(', ')} ${id}`);
+		}
+	}
+
+	if (problems.length) {
+		throw new Error(
+			'skgo: skgo.remotes.json does not describe the server routes kit just compiled.\n' +
+				problems.join('\n') +
+				'\n  Every server route is written in Go. Run `go generate ./...`.'
+		);
+	}
+	return built;
+}

package/skgo-adapter.js

@@ -12,6 +12,7 @@ import { basename, dirname, join, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { gojaDevEnvironment, gojaEnvironment, nodeTable, SSR_TARGET } from './skgo-adapter/env.js';
 import { identity } from './skgo-adapter/identity.js';
+import { checkEndpoints, validateGenerated } from './skgo-adapter/generated.js';
 
 // Which skgo this adapter is: the version this package was published at, and a
 // fingerprint taken over its own files. The Go that reads the manifest below
@@ -40,10 +41,11 @@ const KIT_COMPONENTS = join(
  *
  * It also carries the remote-function ids and the server-load module paths
  * forward. `skgo generate` writes `skgo.remotes.json` beside this file when it
- * emits the `.remote.ts` modules and the `+*.server.ts` stubs; the adapter
- * checks that kit really compiled those modules and copies the lists into the
- * build, so the Go binary can refuse to serve a frontend that was built from a
- * different set of Go functions than it answers.
+ * emits the `.remote.ts`/`.remote.js` modules and the `+*.server.ts`/
+ * `+*.server.js` stubs; the adapter checks that kit really compiled those
+ * modules and copies the lists into the build, so the Go binary can refuse to
+ * serve a frontend that was built from a different set of Go functions than it
+ * answers.
  *
  * @param {{ out?: string, precompress?: boolean }} [options]
  * @returns {import('@sveltejs/kit').Adapter}
@@ -200,7 +202,8 @@ export default function skgo({ out = 'build', precompress = true } = {}) {
  *
  * A missing or shapeless file is a failure, not an empty list: an adapter that
  * quietly compares nothing to nothing reports success for an app whose two
- * halves were never checked against each other.
+ * halves were never checked against each other. The shape checks themselves
+ * live in `skgo-adapter/generated.js`, beside the paths they validate.
  *
  * @returns {{ remotes: string[], loads: string[], actions: string[], endpoints: Record<string, string[]> }}
  */
@@ -213,105 +216,7 @@ function readGenerated() {
 			'skgo: skgo.remotes.json is missing. Run `go generate ./...` before building the frontend.'
 		);
 	}
-	const parsed = JSON.parse(raw);
-	if (!Array.isArray(parsed.remotes)) {
-		throw new Error(
-			'skgo: skgo.remotes.json has no `remotes` array. Run `go generate ./...` before building the frontend.'
-		);
-	}
-	for (const id of parsed.remotes) {
-		if (typeof id !== 'string' || !/^[^/]+\/[^/]+$/.test(id)) {
-			throw new Error(
-				`skgo: skgo.remotes.json lists ${JSON.stringify(id)}, which is not a <hash>/<name> id.`
-			);
-		}
-	}
-	if (!Array.isArray(parsed.loads)) {
-		throw new Error(
-			'skgo: skgo.remotes.json has no `loads` array. Run `go generate ./...` before building the frontend.'
-		);
-	}
-	for (const module of parsed.loads) {
-		if (typeof module !== 'string' || !/\/\+(page|layout)\.server\.ts$/.test(module)) {
-			throw new Error(
-				`skgo: skgo.remotes.json lists ${JSON.stringify(module)}, which is not a +page.server.ts or +layout.server.ts path.`
-			);
-		}
-	}
-	if (!Array.isArray(parsed.actions)) {
-		throw new Error('skgo: skgo.remotes.json has no `actions` array. Run `go generate ./...` before building the frontend.');
-	}
-	for (const module of parsed.actions) {
-		if (typeof module !== 'string' || !/\/\+page\.server\.ts$/.test(module)) {
-			throw new Error(`skgo: skgo.remotes.json lists ${JSON.stringify(module)}, which is not a +page.server.ts action path.`);
-		}
-	}
-	if (typeof parsed.endpoints !== 'object' || parsed.endpoints === null || Array.isArray(parsed.endpoints)) {
-		throw new Error(
-			'skgo: skgo.remotes.json has no `endpoints` object. Run `go generate ./...` before building the frontend.'
-		);
-	}
-	for (const [id, methods] of Object.entries(parsed.endpoints)) {
-		if (!id.startsWith('/') || !Array.isArray(methods) || methods.length === 0) {
-			throw new Error(
-				`skgo: skgo.remotes.json maps ${JSON.stringify(id)} to ${JSON.stringify(methods)}, which is not a route id and its methods.`
-			);
-		}
-	}
-	return { remotes: parsed.remotes, loads: parsed.loads, actions: parsed.actions, endpoints: parsed.endpoints };
-}
-
-/**
- * The same check for server routes, against the one place kit reports what it
- * compiled: `builder.routes[].api.methods`, which kit derives by importing each
- * built `+server.js` and reading its exports
- * (packages/kit/src/core/postbuild/analyse.js, `analyse_endpoint`). A `fallback`
- * export travels there as `'*'`, and `skgo generate` writes the same spelling,
- * so the two lists are compared literally.
- *
- * This is the check that makes a hand-written `+server.ts` fail the build rather
- * than 404 in the browser: kit would compile it, Go would never have been told
- * about it, and the route would answer nothing.
- *
- * @param {import('@sveltejs/kit').Builder} builder
- * @param {Record<string, string[]>} declared
- * @returns {Map<string, string[]>} the methods kit compiled, per route id
- */
-function checkEndpoints(builder, declared) {
-	/** @type {Map<string, string[]>} */
-	const built = new Map();
-	for (const route of builder.routes) {
-		if (route.api.methods.length > 0) built.set(route.id, [...route.api.methods].sort());
-	}
-
-	/** @type {string[]} */
-	const problems = [];
-	for (const [id, methods] of Object.entries(declared)) {
-		const compiled = built.get(id);
-		if (!compiled) {
-			problems.push(`  generated but not compiled: ${methods.join(', ')} ${id}`);
-			continue;
-		}
-		const want = [...methods].sort().join(', ');
-		const got = compiled.join(', ');
-		if (want !== got) {
-			problems.push(`  ${id}: Go answers ${want}, the built +server.ts exports ${got}`);
-		}
-	}
-	for (const [id, methods] of built) {
-		if (!(id in declared)) {
-			problems.push(`  compiled but not generated: ${methods.join(', ')} ${id}`);
-		}
-	}
-
-	if (problems.length) {
-		throw new Error(
-			'skgo: skgo.remotes.json does not describe the server routes kit just compiled.\n' +
-				problems.join('\n') +
-				'\n  Every server route is written in Go. Run `go generate ./...`.'
-		);
-	}
-	return built;
+	return validateGenerated(JSON.parse(raw));
 }
 
 /**
@@ -484,16 +389,10 @@ async function readNodes(builder, source, kit) {
 		}
 		const module = await import(pathToFileURL(file).href);
 
-		if (typeof module.universal?.load === 'function') {
-			throw new Error(
-				`skgo: ${module.universal_id} exports a \`load\`. Every load in a skgo app is written in Go; ` +
-					'a universal load would have to run in the browser and in the SSR engine, and skgo runs neither.'
-			);
-		}
-
 		nodes.push({
 			index,
 			server: module.server_id ?? '',
+			universal: typeof module.universal?.load === 'function' ? module.universal_id : null,
 			component: module.component ? componentSource(file, dir) : null,
 			imports: module.imports ?? [],
 			stylesheets: module.stylesheets ?? [],
@@ -510,6 +409,7 @@ async function readNodes(builder, source, kit) {
  * @typedef {{
  *   index: number,
  *   server: string,
+ *   universal: string | null,
  *   component: string | null,
  *   imports: string[],
  *   stylesheets: string[],