@jigs.design/server 0.0.0-stage → 0.1.1

package/dist/inputs.js

@@ -0,0 +1,224 @@
+import { lineAt, readArguments } from "./literal.js";
+import { z } from "zod";
+//#region src/inputs.ts
+/** A handle declared as `const name = useMutation("procedure")`. */
+const MUTATION_HANDLE = /(?<![\w$.])(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*useMutation\(\s*(["'`])([A-Za-z_$][\w$]*)\2\s*\)/g;
+const QUERY_CALL = /(?<![\w$.])useQuery\(\s*(["'`])([A-Za-z_$][\w$]*)\1\s*/g;
+/** At most this many problems per call, so one bad literal does not flood the repair. */
+const MAX_PROBLEMS = 3;
+function known(literal) {
+	const out = {
+		open: [],
+		unknown: [],
+		value: void 0
+	};
+	const walk = (node, path) => {
+		switch (node.kind) {
+			case "array": return node.items.map((item, index) => walk(item, [...path, index]));
+			case "dynamic":
+				out.unknown.push(path);
+				return;
+			case "object":
+				if (node.spread) out.open.push(path);
+				return Object.fromEntries([...node.entries].map(([key, value]) => [key, walk(value, [...path, key])]));
+			case "value": return node.value;
+		}
+	};
+	if (literal !== void 0) out.value = walk(literal, []);
+	return out;
+}
+/** The part of `literal` at `path`, when it is written there. */
+function literalAt(literal, path) {
+	let current = literal;
+	for (const part of path) if (current?.kind === "object" && !Number.isInteger(part)) current = current.entries.get(String(part));
+	else if (current?.kind === "array" && Number.isInteger(part)) current = current.items[Number(part)];
+	else return;
+	return current;
+}
+const startsWith = (path, prefix) => prefix.length <= path.length && prefix.every((part, index) => path[index] === part);
+const samePath = (a, b) => a.length === b.length && startsWith(a, b);
+/** A path part that is a key or an index; zod's paths may also hold symbols. */
+function isKey(part) {
+	return typeof part !== "symbol";
+}
+function pathText(path) {
+	return path.map((part, index) => Number.isInteger(part) ? `[${part}]` : index === 0 ? part : `.${part}`).join("");
+}
+const jsonSchemas = /* @__PURE__ */ new WeakMap();
+/**
+* The JSON Schema of an input schema, as input. `defineHost` requires that
+* every input has one; null when it still fails, and then only the schema's
+* own parse is checked.
+*/
+function jsonSchemaOf(schema) {
+	const cached = jsonSchemas.get(schema);
+	if (cached !== void 0) return cached;
+	let converted;
+	try {
+		converted = z.toJSONSchema(schema, { io: "input" });
+	} catch {
+		converted = null;
+	}
+	jsonSchemas.set(schema, converted);
+	return converted;
+}
+/** A node and the alternatives it allows, such as an object or null. */
+function branches(node) {
+	return [node, ...(node.anyOf ?? []).flatMap((branch) => branches(branch))];
+}
+/** A node written as `true`, which takes anything, as a schema. */
+const ANYTHING = {};
+const asNode = (node) => node === true || node === false ? ANYTHING : node;
+/** An object node's fields, and whether it takes keys beyond them. */
+function objectFields(node) {
+	const objects = branches(node).filter((branch) => branch.type === "object" || branch.properties !== void 0);
+	if (objects.length === 0) return null;
+	const fields = /* @__PURE__ */ new Map();
+	let open = false;
+	for (const object of objects) {
+		for (const [key, field] of Object.entries(object.properties ?? {})) fields.set(key, asNode(field));
+		if (object.additionalProperties !== void 0 && object.additionalProperties !== false) open = true;
+	}
+	return {
+		fields,
+		open
+	};
+}
+/** An array node's element, or null for any other node. */
+function arrayElement(node) {
+	for (const branch of branches(node)) {
+		const { items } = branch;
+		if (items !== void 0 && !Array.isArray(items)) return asNode(items);
+	}
+	return null;
+}
+/** The node that checks the value at `path`, when objects and arrays lead there. */
+function nodeAt(root, path) {
+	let current = root;
+	for (const part of path) {
+		if (current === null) return null;
+		current = Number.isInteger(part) ? arrayElement(current) : objectFields(current)?.fields.get(String(part)) ?? null;
+	}
+	return current;
+}
+/** Keys written in `literal` that no object node on its path has. */
+function unknownKeys(node, literal, path) {
+	const element = arrayElement(node);
+	if (literal.kind === "array" && element !== null) return literal.items.flatMap((item, index) => unknownKeys(element, item, [...path, index]));
+	const object = objectFields(node);
+	if (literal.kind !== "object" || object === null) return [];
+	const found = [];
+	for (const [key, value] of literal.entries) {
+		const field = object.fields.get(key);
+		if (field !== void 0) found.push(...unknownKeys(field, value, [...path, key]));
+		else if (!object.open) found.push({
+			fields: [...object.fields.keys()],
+			path: [...path, key]
+		});
+	}
+	return found;
+}
+/** The host's `.describe()` text for a field. */
+function descriptionOf(node) {
+	return node === null ? void 0 : branches(node).find((branch) => branch.description !== void 0)?.description;
+}
+/** What is wrong with one issue, in a few words a model can act on. */
+function problem(issue, written, root) {
+	const path = issue.path.filter(isKey);
+	const field = pathText(path);
+	const name = field === "" ? "the input" : field;
+	const shown = written === void 0 ? "nothing" : JSON.stringify(known(written).value);
+	const hint = descriptionOf(nodeAt(root, path));
+	const about = hint === void 0 ? "" : ` (${hint})`;
+	if (written === void 0 && issue.code === "invalid_type") {
+		const object = field === "" && root !== null ? objectFields(root) : null;
+		return object === null ? `${name} is missing${about}` : `it needs an input: { ${[...object.fields.keys()].join(", ")} }`;
+	}
+	switch (issue.code) {
+		case "invalid_format": return issue.format === "regex" ? `${name} must match ${issue.pattern ?? "its pattern"}${about}, not ${shown}` : `${name} must be a ${issue.format}${about}, not ${shown}`;
+		case "invalid_type": return `${name} must be ${issue.expected === "number" ? "a number" : issue.expected}, not ${shown}${about}`;
+		case "invalid_value": return `${name} must be one of ${issue.values.map((value) => JSON.stringify(value)).join(", ")}, not ${shown}`;
+		default: return `${name}: ${issue.message}${about}`;
+	}
+}
+/**
+* Problems with an input written as a literal, by the procedure's schema:
+* unknown keys, and values the schema refuses. Anything computed is left to
+* run time.
+*/
+function literalProblems(schema, literal) {
+	const problems = [];
+	const root = jsonSchemaOf(schema);
+	if (literal !== void 0) for (const extra of root === null ? [] : unknownKeys(root, literal, [])) {
+		const where = extra.path.slice(0, -1);
+		const takes = extra.fields.length === 0 ? "takes no fields" : `takes ${extra.fields.join(", ")}`;
+		problems.push(`there is no ${pathText(extra.path)}; ${where.length === 0 ? "the input" : pathText(where)} ${takes}`);
+	}
+	const facts = known(literal);
+	let parsed;
+	try {
+		parsed = z.safeParse(schema, facts.value);
+	} catch {
+		return problems;
+	}
+	if (parsed.success) return problems;
+	for (const issue of parsed.error.issues) {
+		const path = issue.path.filter(isKey);
+		const written = literalAt(literal, path);
+		const computed = facts.unknown.some((prefix) => startsWith(path, prefix));
+		const spread = written === void 0 && facts.open.some((open) => samePath(open, path.slice(0, -1)));
+		const unionUnknown = issue.code === "invalid_union" && [...facts.unknown, ...facts.open].some((inner) => startsWith(inner, path));
+		if (issue.code !== "unrecognized_keys" && !computed && !spread && !unionUnknown) problems.push(problem(issue, written, root));
+	}
+	return problems;
+}
+/**
+* Input written as a literal in `useQuery("name", input)` or a mutation
+* handle's `mutate(input)`, checked against the procedure's input schema.
+* Each problem is an error, so the model repairs it instead of the spec
+* failing at run time with `BAD_INPUT` or silently reading nothing.
+*/
+function inputDiagnostics(host, source) {
+	const diagnostics = [];
+	const procedureOf = (name) => Object.hasOwn(host.procedures, name) ? host.procedures[name] : void 0;
+	const report = (index, subject, problems) => {
+		for (const message of problems.slice(0, MAX_PROBLEMS)) diagnostics.push({
+			code: "procedure_input",
+			message: `${subject}: ${message}`,
+			severity: "error",
+			span: { line: lineAt(source, index) }
+		});
+	};
+	for (const match of source.matchAll(QUERY_CALL)) {
+		const name = match[2] ?? "";
+		const procedure = procedureOf(name);
+		if (procedure?.kind !== "query" || procedure.input === void 0) continue;
+		const rest = match.index + match[0].length;
+		const char = source.charAt(rest);
+		if (char !== "," && char !== ")") continue;
+		const [input] = char === ")" ? [] : readArguments(source, rest + 1);
+		if (input?.kind === "dynamic") continue;
+		report(match.index, `useQuery("${name}")`, literalProblems(procedure.input, input));
+	}
+	const handles = /* @__PURE__ */ new Map();
+	for (const match of source.matchAll(MUTATION_HANDLE)) {
+		const handle = match[1] ?? "";
+		const name = match[3] ?? "";
+		const before = handles.get(handle);
+		handles.set(handle, before === void 0 || before === name ? name : null);
+	}
+	for (const [handle, name] of handles) {
+		const procedure = name === null ? void 0 : procedureOf(name);
+		if (name === null || procedure === void 0 || procedure.kind === "query" || procedure.input === void 0) continue;
+		const escaped = handle.replaceAll("$", String.raw`\$`);
+		const call = new RegExp(String.raw`(?<![\w$.])${escaped}\s*\.\s*mutate\(`, "g");
+		for (const match of source.matchAll(call)) {
+			const [input] = readArguments(source, match.index + match[0].length);
+			if (input?.kind === "dynamic") continue;
+			report(match.index, `${handle}.mutate() for "${name}"`, literalProblems(procedure.input, input));
+		}
+	}
+	return diagnostics;
+}
+//#endregion
+export { branches, inputDiagnostics, objectFields };

package/dist/invalidation.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+//#region src/invalidation.ts
+const json = z.json();
+/** One scope's targets; throws when it fails or returns something not JSON. */
+function scoped(name, scope, input, output) {
+	const result = scope(input, output);
+	if (result === true) return [{ name }];
+	return (Array.isArray(result) ? result : [result]).map((entry) => {
+		if (!json.safeParse(entry).success) throw new Error(`The invalidates scope for "${name}" returned a value that is not JSON`);
+		return {
+			input: entry,
+			name
+		};
+	});
+}
+/**
+* The queries a successful mutation refreshes, with the inputs its scopes
+* pick. A scope that throws refreshes its whole query, after `report`.
+*/
+function invalidationsOf(procedure, input, output, report) {
+	const targets = [];
+	for (const name of procedure.invalidates) {
+		const scope = procedure.scopes[name];
+		if (scope === void 0 || scope === true) {
+			targets.push({ name });
+			continue;
+		}
+		try {
+			const run = scope;
+			targets.push(...scoped(name, run, input, output));
+		} catch (error) {
+			report(error instanceof Error ? error : new Error(String(error), { cause: error }));
+			targets.push({ name });
+		}
+	}
+	return targets;
+}
+//#endregion
+export { invalidationsOf };

package/dist/literal.js

@@ -0,0 +1,258 @@
+//#region src/literal.ts
+const IDENTIFIER = /[A-Za-z_$][\w$]*/y;
+const NUMBER = /-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/y;
+const KEYWORD = /(true|false|null)(?![\w$])/y;
+const SPACE = /\s*/y;
+const DYNAMIC = { kind: "dynamic" };
+/** Objects and arrays nested deeper than this are read as `dynamic`, so deep nesting cannot overflow the stack. */
+const MAX_DEPTH = 64;
+function skipSpace(source, index) {
+	if (index >= source.length) return source.length;
+	SPACE.lastIndex = index;
+	SPACE.exec(source);
+	return SPACE.lastIndex;
+}
+/** Index just past the string or template literal that starts at `index`. */
+function skipQuoted(source, index) {
+	const quote = source.charAt(index);
+	let at = index + 1;
+	let depth = 0;
+	while (at < source.length) {
+		const char = source.charAt(at);
+		if (char === "\\") {
+			at += 2;
+			continue;
+		}
+		if (quote === "`" && char === "$" && source.charAt(at + 1) === "{") {
+			depth++;
+			at += 2;
+			continue;
+		}
+		if (depth > 0 && char === "}") depth--;
+		else if (depth === 0 && char === quote) return at + 1;
+		at++;
+	}
+	return Math.min(at, source.length);
+}
+/**
+* Index of the `,` or closing bracket that ends the expression starting at
+* `index`, skipping nested brackets and strings.
+*/
+function skipExpression(source, index) {
+	let depth = 0;
+	let at = index;
+	while (at < source.length) {
+		const char = source.charAt(at);
+		if (char === "\"" || char === "'" || char === "`") {
+			at = skipQuoted(source, at);
+			continue;
+		}
+		if (char === "(" || char === "[" || char === "{") depth++;
+		else if (char === ")" || char === "]" || char === "}") {
+			if (depth === 0) return at;
+			depth--;
+		} else if (char === "," && depth === 0) return at;
+		at++;
+	}
+	return at;
+}
+/** The 1-based line of `source` that `index` is on. */
+function lineAt(source, index) {
+	let line = 1;
+	for (let at = source.indexOf("\n"); at !== -1 && at < index;) {
+		line++;
+		at = source.indexOf("\n", at + 1);
+	}
+	return line;
+}
+/** A string literal's value, or null when it has escapes this does not read. */
+function stringValue(text) {
+	const body = text.slice(1, -1);
+	if (!body.includes("\\")) return body;
+	if (text.startsWith("\"")) try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+	return null;
+}
+/** Whether the expression goes on past a value just read, as in `"a" + b`. */
+function continues(source, index) {
+	const next = source.charAt(skipSpace(source, index));
+	return next !== "" && next !== "," && next !== ")" && next !== "]" && next !== "}";
+}
+/** The value written at `index`, `depth` objects and arrays deep, and where it ends. */
+function readValue(source, index, depth) {
+	const start = skipSpace(source, index);
+	const char = source.charAt(start);
+	let read = null;
+	if (char === "{" || char === "[") {
+		if (depth < MAX_DEPTH) read = char === "{" ? readObject(source, start, depth) : readArray(source, start, depth);
+	} else if (char === "\"" || char === "'" || char === "`") {
+		const end = skipQuoted(source, start);
+		const text = source.slice(start, end);
+		const value = char === "`" ? text.includes("${") || text.includes("\\") ? null : text.slice(1, -1) : stringValue(text);
+		read = {
+			end,
+			literal: value === null ? DYNAMIC : {
+				kind: "value",
+				value
+			}
+		};
+	} else {
+		NUMBER.lastIndex = start;
+		const number = NUMBER.exec(source);
+		KEYWORD.lastIndex = start;
+		const keyword = number === null ? KEYWORD.exec(source) : null;
+		if (number !== null && !/[\w$.]/.test(source.charAt(NUMBER.lastIndex))) read = {
+			end: NUMBER.lastIndex,
+			literal: {
+				kind: "value",
+				value: Number(number[0])
+			}
+		};
+		else if (keyword !== null) {
+			const word = keyword[1];
+			read = {
+				end: KEYWORD.lastIndex,
+				literal: {
+					kind: "value",
+					value: word === "null" ? null : word === "true"
+				}
+			};
+		}
+	}
+	if (read === null || continues(source, read.end)) return {
+		end: skipExpression(source, start),
+		literal: DYNAMIC
+	};
+	return read;
+}
+function readObject(source, start, depth) {
+	const entries = /* @__PURE__ */ new Map();
+	let spread = false;
+	let at = start + 1;
+	let last = -1;
+	for (;;) {
+		at = skipSpace(source, at);
+		if (at <= last) return {
+			end: at,
+			literal: DYNAMIC
+		};
+		last = at;
+		const char = source.charAt(at);
+		if (char === "}") return {
+			end: at + 1,
+			literal: {
+				entries,
+				kind: "object",
+				spread
+			}
+		};
+		if (char === "") return {
+			end: at,
+			literal: DYNAMIC
+		};
+		if (char === ",") {
+			at++;
+			continue;
+		}
+		if (source.startsWith("...", at)) {
+			spread = true;
+			at = skipExpression(source, at + 3);
+			continue;
+		}
+		let key = null;
+		if (char === "\"" || char === "'") {
+			const end = skipQuoted(source, at);
+			key = stringValue(source.slice(at, end));
+			at = end;
+		} else {
+			IDENTIFIER.lastIndex = at;
+			const name = IDENTIFIER.exec(source);
+			if (name !== null) {
+				key = name[0];
+				at = IDENTIFIER.lastIndex;
+			}
+		}
+		at = skipSpace(source, at);
+		if (key === null) {
+			spread = true;
+			at = skipExpression(source, at);
+			continue;
+		}
+		const after = source.charAt(at);
+		if (after === ":") {
+			const value = readValue(source, at + 1, depth + 1);
+			entries.set(key, value.literal);
+			at = value.end;
+		} else if (after === "," || after === "}") entries.set(key, DYNAMIC);
+		else {
+			entries.set(key, DYNAMIC);
+			at = skipExpression(source, at);
+		}
+	}
+}
+function readArray(source, start, depth) {
+	const items = [];
+	let spread = false;
+	let at = start + 1;
+	let last = -1;
+	for (;;) {
+		at = skipSpace(source, at);
+		if (at <= last) return {
+			end: at,
+			literal: DYNAMIC
+		};
+		last = at;
+		const char = source.charAt(at);
+		if (char === "]") return {
+			end: at + 1,
+			literal: spread ? DYNAMIC : {
+				items,
+				kind: "array"
+			}
+		};
+		if (char === "") return {
+			end: at,
+			literal: DYNAMIC
+		};
+		if (char === ",") {
+			at++;
+			continue;
+		}
+		if (source.startsWith("...", at)) {
+			spread = true;
+			at = skipExpression(source, at + 3);
+			continue;
+		}
+		const value = readValue(source, at, depth + 1);
+		items.push(value.literal);
+		at = value.end;
+	}
+}
+/**
+* The arguments of a call whose `(` is just before `index`, up to its `)`:
+* each read as a literal where it is one.
+*/
+function readArguments(source, index) {
+	const args = [];
+	let at = index;
+	let last = -1;
+	for (;;) {
+		at = skipSpace(source, at);
+		if (at <= last) return args;
+		last = at;
+		const char = source.charAt(at);
+		if (char === ")" || char === "") return args;
+		if (char === ",") {
+			at++;
+			continue;
+		}
+		const value = readValue(source, at, 0);
+		args.push(value.literal);
+		at = value.end;
+	}
+}
+//#endregion
+export { lineAt, readArguments };

package/dist/node.d.ts

@@ -0,0 +1,19 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/node.d.ts
+/** A request as Express hands it over: `body` is set when a body parser already ran. */
+type NodeRequest = IncomingMessage & {
+  body?: unknown;
+  originalUrl?: string;
+};
+interface HandlerOwner {
+  handler: (request: Request) => Promise<Response>;
+  maxBodyBytes: number;
+}
+/**
+ * Mounts `pickle.handler` on Express or plain Node. It builds a standard
+ * `Request`, so `context` is the same function on every platform, and aborts
+ * the request's signal when the connection closes early.
+ */
+export declare function nodeHandler(pickle: HandlerOwner): (request: NodeRequest, response: ServerResponse) => void;
+//#endregion
+export {};

package/dist/node.js

@@ -0,0 +1,91 @@
+import { once } from "node:events";
+//#region src/node.ts
+/**
+* The raw body, read only up to one byte past `max`, so the handler refuses
+* an oversized body without this holding it in memory.
+*/
+async function readBody(request, max) {
+	if (request.method === "GET" || request.method === "HEAD") return null;
+	if (request.body !== void 0) return JSON.stringify(request.body);
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of request) {
+		const buffer = Buffer.from(chunk);
+		chunks.push(buffer);
+		size += buffer.byteLength;
+		if (size > max) {
+			request.destroy();
+			break;
+		}
+	}
+	return Uint8Array.from(Buffer.concat(chunks));
+}
+/**
+* Waits for room to write: true on `drain`, false when the connection closes
+* first, which a destroyed response does instead of draining.
+*/
+async function drained(response) {
+	if (response.destroyed) return false;
+	const stop = new AbortController();
+	try {
+		return await Promise.race([once(response, "drain", { signal: stop.signal }).then(() => true), once(response, "close", { signal: stop.signal }).then(() => false)]);
+	} finally {
+		stop.abort();
+	}
+}
+function toHeaders(request) {
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(request.headers)) if (Array.isArray(value)) for (const item of value) headers.append(name, item);
+	else if (value !== void 0) headers.set(name, value);
+	return headers;
+}
+/**
+* Mounts `pickle.handler` on Express or plain Node. It builds a standard
+* `Request`, so `context` is the same function on every platform, and aborts
+* the request's signal when the connection closes early.
+*/
+function nodeHandler(pickle) {
+	return (request, response) => {
+		const abort = new AbortController();
+		response.on("close", () => {
+			if (!response.writableFinished) abort.abort();
+		});
+		(async () => {
+			try {
+				const encrypted = "encrypted" in request.socket;
+				const url = new URL(request.originalUrl ?? request.url ?? "/", `${encrypted ? "https" : "http"}://${request.headers.host ?? "localhost"}`);
+				const body = await readBody(request, pickle.maxBodyBytes);
+				const init = {
+					headers: toHeaders(request),
+					method: request.method ?? "GET",
+					signal: abort.signal
+				};
+				if (body !== null) init.body = body;
+				const reply = await pickle.handler(new Request(url, init));
+				response.statusCode = reply.status;
+				reply.headers.forEach((value, name) => {
+					response.setHeader(name, value);
+				});
+				if (reply.body === null) {
+					response.end();
+					return;
+				}
+				const reader = reply.body.getReader();
+				for (;;) {
+					const chunk = await reader.read();
+					if (chunk.done) break;
+					if (!response.write(chunk.value) && !await drained(response)) {
+						await reader.cancel();
+						return;
+					}
+				}
+				response.end();
+			} catch {
+				if (!response.headersSent) response.statusCode = 500;
+				response.end();
+			}
+		})();
+	};
+}
+//#endregion
+export { nodeHandler };