@jigs.design/server 0.3.0 → 0.3.1

package/dist/compile.js

@@ -57,6 +57,17 @@ function compileCatalog(catalog) {
 	return out;
 }
 const TAG = /<([a-z][A-Za-z0-9]*)/g;
+/** Each procedure kind as a diagnostic names it. */
+const KIND_NAMES = {
+	action: "an action",
+	data: "provided data",
+	mutation: "a mutation",
+	query: "a query"
+};
+/** The hook that reads or calls a procedure of `kind`: a provided slot is read like a query. */
+function hookFor(kind) {
+	return kind === "query" || kind === "data" ? "useQuery" : "useMutation";
+}
 function procedureDiagnostics(host, source, uses) {
 	const diagnostics = [];
 	const report = (use, code, message) => {
@@ -83,11 +94,11 @@ function procedureDiagnostics(host, source, uses) {
 		}
 		const procedure = Object.hasOwn(host.procedures, use.name) ? host.procedures[use.name] : void 0;
 		if (procedure === void 0) {
-			report(use, "unknown_procedure", `"${use.name}" is not a query, mutation or action on this host; its handle reports UNKNOWN_PROCEDURE`);
+			report(use, "unknown_procedure", `"${use.name}" is not a query, mutation, action or provided data on this host; its handle reports UNKNOWN_PROCEDURE`);
 			continue;
 		}
-		const expected = procedure.kind === "query" ? "useQuery" : "useMutation";
-		if (expected !== use.hook) report(use, "procedure_kind", `\`${use.hook}("${use.name}")\` names ${procedure.kind === "action" ? "an" : "a"} ${procedure.kind}. Write \`${expected}("${use.name}")\`${procedure.kind === "query" ? "" : " and call `mutate` from a handler"}`);
+		const expected = hookFor(procedure.kind);
+		if (expected !== use.hook) report(use, "procedure_kind", `\`${use.hook}("${use.name}")\` names ${KIND_NAMES[procedure.kind]}. Write \`${expected}("${use.name}")\`${expected === "useQuery" ? "" : " and call `mutate` from a handler"}`);
 	}
 	return diagnostics;
 }
@@ -96,8 +107,7 @@ function procedureTable(host, uses) {
 	for (const use of uses) {
 		if (use.name === null || use.tanstack) continue;
 		const procedure = Object.hasOwn(host.procedures, use.name) ? host.procedures[use.name] : void 0;
-		const expected = procedure?.kind === "query" ? "useQuery" : "useMutation";
-		if (procedure === void 0 || expected !== use.hook) continue;
+		if (procedure === void 0 || hookFor(procedure.kind) !== use.hook) continue;
 		table.set(use.name, {
 			invalidates: procedure.kind === "mutation" ? procedure.invalidates : [],
 			kind: procedure.kind

package/dist/core.js

@@ -36,6 +36,10 @@ function strictly(subject, compiled) {
 function noProps(name, props) {
 	if (Object.keys(props).length > 0) throw new JigsError("BAD_INPUT", `"${name}" is a document page, which takes no props`);
 }
+/** An `AbortError`, as `fetch` and other APIs reject with on an aborted signal. */
+function isAbortError(cause) {
+	return cause instanceof Error && cause.name === "AbortError";
+}
 /** A call a policy refused. The procedure stays in the prompt. */
 const denial = (name) => ({ error: {
 	code: "FORBIDDEN",
@@ -91,7 +95,7 @@ function hostFingerprint(host) {
 			kind: procedure.kind,
 			name,
 			output: procedure.output === void 0 ? null : z.toJSONSchema(procedure.output),
-			projection: procedure.kind === "action" || procedure.projection === void 0 ? null : z.toJSONSchema(procedure.projection.schema)
+			projection: procedure.kind === "action" || procedure.kind === "data" || procedure.projection === void 0 ? null : z.toJSONSchema(procedure.projection.schema)
 		})),
 		jigs: host.jigs.map((entry) => [
 			entry.name,
@@ -113,7 +117,7 @@ function defineRun(procedures, handlers) {
 function createJigsServer(options) {
 	const { host } = options;
 	checkMarkdownElements(host.components);
-	for (const [name, procedure] of Object.entries(host.procedures)) if (procedure.kind !== "action" && !Object.hasOwn(options.run, name)) throw new Error(`createJigsServer has no run function for "${name}"`);
+	for (const [name, procedure] of Object.entries(host.procedures)) if (procedure.kind !== "action" && procedure.kind !== "data" && !Object.hasOwn(options.run, name)) throw new Error(`createJigsServer has no run function for "${name}"`);
 	const confirmer = confirmerFor(options);
 	const checker = createChecker(host);
 	const promptOptions = (mode) => options.instructions === void 0 ? { mode } : {
@@ -220,7 +224,11 @@ function createJigsServer(options) {
 	};
 	const dispatch = async (request, context, trace) => {
 		const procedure = Object.hasOwn(host.procedures, request.name) ? host.procedures[request.name] : void 0;
-		const run = procedure?.kind !== "action" && Object.hasOwn(runs, request.name) ? runs[request.name] : void 0;
+		const run = procedure?.kind !== "action" && procedure?.kind !== "data" && Object.hasOwn(runs, request.name) ? runs[request.name] : void 0;
+		if (procedure?.kind === "data") return { error: {
+			code: "BAD_INPUT",
+			message: `"${request.name}" is provided data: it is supplied by the page, not fetched`
+		} };
 		if (procedure === void 0 || procedure.kind !== "action" && run === void 0) return { error: {
 			code: "UNKNOWN_PROCEDURE",
 			message: `"${request.name}" is not a query, mutation or action on this host`
@@ -256,6 +264,10 @@ function createJigsServer(options) {
 		try {
 			result = await run(input, context);
 		} catch (error) {
+			if (context.signal.aborted || isAbortError(error)) {
+				trace.aborted = true;
+				return { error: errorData(null) };
+			}
 			if (isJigsError(error)) return { error: errorData(error) };
 			onError(error, {
 				name: request.name,
@@ -327,6 +339,7 @@ function createJigsServer(options) {
 	const call = async (request, context) => {
 		const started = performance.now();
 		const trace = {
+			aborted: false,
 			gate: null,
 			input: request.input
 		};
@@ -339,7 +352,8 @@ function createJigsServer(options) {
 			name: request.name,
 			outcome: trace.gate ?? "success"
 		};
-		if ("error" in outcome) {
+		if (trace.aborted) report.outcome = "aborted";
+		else if ("error" in outcome) {
 			report.error = outcome.error;
 			report.outcome = trace.gate === "denied" ? "denied" : "error";
 		}
@@ -671,9 +685,17 @@ function createJigsServer(options) {
 		onError,
 		page: pageRequest
 	};
+	const data = (name, value) => {
+		const slot = Object.hasOwn(host.procedures, name) ? host.procedures[name] : void 0;
+		if (slot?.kind !== "data") throw new JigsError("BAD_INPUT", `"${name}" is not provided data on this host`);
+		const parsed = slot.output.safeParse(value);
+		if (!parsed.success) throw new JigsError("BAD_INPUT", `"${name}": ${issuesText(parsed.error)}`);
+		return parsed.data;
+	};
 	const core = {
 		call,
 		compile,
+		data,
 		events,
 		frame,
 		handler: createHandler({

package/dist/inputs.js

@@ -3,6 +3,11 @@ 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;
+/**
+* What may follow a provided slot's name in `useQuery`: the call's end, or
+* an empty input (`undefined` or `null`) before or without options.
+*/
+const NO_INPUT = /^(?:,\s*)?\)|^,\s*(?:undefined|null)(?![\w$])/;
 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;
@@ -192,8 +197,18 @@ function inputDiagnostics(host, source) {
 	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;
+		if (procedure?.kind === "data") {
+			if (NO_INPUT.test(source.slice(rest))) continue;
+			diagnostics.push({
+				code: "data_takes_no_input",
+				message: `useQuery("${name}") reads provided data, which takes no input. Drop the input; the app provides this data`,
+				severity: "error",
+				span: { line: lineAt(source, match.index) }
+			});
+			continue;
+		}
+		if (procedure?.kind !== "query" || procedure.input === void 0) continue;
 		const char = source.charAt(rest);
 		if (char !== "," && char !== ")") continue;
 		const [input] = char === ")" ? [] : readArguments(source, rest + 1);

package/dist/model-server.js

@@ -122,6 +122,7 @@ function createModelServer(internals, core, options) {
 		call: core.call,
 		chat,
 		compile: core.compile,
+		data: core.data,
 		events: core.events,
 		frame: core.frame,
 		handler: createHandler({

package/dist/types.d.ts

@@ -2,8 +2,8 @@ import { Advice, DesignCheckCode, Placement } from "./design.js";
 import { ConfirmationStore } from "./confirm.js";
 import { EditFailureReason } from "@jigs.design/compiler";
 import { PromptMode } from "@jigs.design/prompt";
-import { ActionDefinition, CallPolicy, Catalog, Host, InputOf, JigDefinition, MutationDefinition, OutputOf, PageName, ProcedureDefinition, Procedures, QueryDefinition } from "@jigs.design/host";
-import { ChatBlock, ChatBlockStatus, Diagnostic, Invalidation, JigsErrorData, Message, PageInvalidation, PageProps, PageRef, Program, SessionEvent } from "@jigs.design/protocol";
+import { ActionDefinition, CallPolicy, Catalog, DataDefinition, Host, InputOf, JigDefinition, MutationDefinition, OutputOf, PageName, ProcedureDefinition, Procedures, QueryDefinition } from "@jigs.design/host";
+import { ChatBlock, ChatBlockStatus, Diagnostic, Invalidation, JigsErrorData, JsonValue, Message, PageInvalidation, PageProps, PageRef, Program, SessionEvent } from "@jigs.design/protocol";
 import { z } from "zod";
 //#region src/types.d.ts
 /**
@@ -159,9 +159,10 @@ type DeepReadonly<T> = T extends object ? { readonly [K in keyof T]: DeepReadonl
 type RunOutput<P extends ProcedureDefinition> = DeepReadonly<OutputOf<P>>;
 /**
  * One function per query and mutation. Actions have none: the page handles
- * them, and the server only checks their input.
+ * them, and the server only checks their input. Provided data has none
+ * either: the page supplies it.
  */
-export type RunFunctions<TProcedures extends Procedures, TContext> = { readonly [K in keyof TProcedures as TProcedures[K] extends ActionDefinition ? never : K]: (input: InputOf<TProcedures[K]>, call: CallContext<TContext>) => RunOutput<TProcedures[K]> | Promise<RunOutput<TProcedures[K]>>; };
+export type RunFunctions<TProcedures extends Procedures, TContext> = { readonly [K in keyof TProcedures as TProcedures[K] extends ActionDefinition | DataDefinition ? never : K]: (input: InputOf<TProcedures[K]>, call: CallContext<TContext>) => RunOutput<TProcedures[K]> | Promise<RunOutput<TProcedures[K]>>; };
 export type ContextFunction<TContext> = (request: Request) => TContext | Promise<TContext>;
 /** The names of a host's mutations. */
 type MutationName<TProcedures extends Procedures> = { [K in keyof TProcedures & string]: TProcedures[K] extends MutationDefinition ? K : never; }[keyof TProcedures & string];
@@ -180,7 +181,7 @@ export type PolicyCall<TProcedures extends Procedures, TContext> = { [K in Mutat
  * as "requires-action" when the server asks the page, and once as
  * "confirmed" when it ran with the user's approval.
  */
-export type CallReportOutcome = "confirmed" | "denied" | "error" | "requires-action" | "success";
+export type CallReportOutcome = "aborted" | "confirmed" | "denied" | "error" | "requires-action" | "success";
 /**
  * One call to a query, mutation or action, or one page request, as
  * `onCall` receives it.
@@ -189,7 +190,7 @@ export interface CallReport<TContext> {
   ctx: TContext;
   /** From the call's arrival to its outcome, in milliseconds. */
   durationMs: number;
-  /** What the browser received, when `outcome` is not "success". */
+  /** What the browser received, when `outcome` is "denied" or "error". */
   error?: JigsErrorData;
   /**
    * The parsed input, or the input as the browser sent it when the call
@@ -205,7 +206,9 @@ export interface CallReport<TContext> {
   /**
    * "denied" when a policy or a bad confirmation refused the call, or
    * `pagePolicy` a page; "error" for any other failure, including one
-   * `run` threw and a page no list has.
+   * `run` threw and a page no list has; "aborted" when `run` rejected
+   * after the browser abandoned the call (its `signal` aborted), which
+   * does not reach `onError`.
    */
   outcome: CallReportOutcome;
 }
@@ -642,6 +645,14 @@ export interface JigsServer<TContext, TPageName extends string = never> {
     diagnostics: ReadonlyArray<Diagnostic>;
     program: Program;
   }>;
+  /**
+   * `value` parsed with the schema of provided slot `name`, for a page
+   * that wants it checked before it passes it to `JigsView` as `data`.
+   * Throws `JigsError("BAD_INPUT")` when it does not match, or when `name`
+   * is not provided data on this host. The view does not check it: a value
+   * that does not match renders as the program reads it.
+   */
+  data: (name: string, value: JsonValue) => JsonValue;
   /**
    * The push stream for `request`, whose `ctx` the caller already has: a
    * foreign `Origin` is `403`, a server without `events` answers `204`, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jigs.design/server",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "createJigsServer: checks and streams programs, runs procedures, and serves the sandbox frame.",
   "license": "MIT",
   "repository": {
@@ -29,11 +29,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@jigs.design/compiler": "0.3.0",
-    "@jigs.design/prompt": "0.3.0",
-    "@jigs.design/protocol": "0.3.0",
-    "@jigs.design/runtime": "0.3.0",
-    "@jigs.design/host": "0.3.0"
+    "@jigs.design/host": "0.3.1",
+    "@jigs.design/compiler": "0.3.1",
+    "@jigs.design/protocol": "0.3.1",
+    "@jigs.design/runtime": "0.3.1",
+    "@jigs.design/prompt": "0.3.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0"