@hediet/linkrpc 0.0.1 → 0.0.2

package/README.md

@@ -132,6 +132,65 @@ g.shout({ msg: 'boom' });                               // fire-and-forget notif
 Pass the wrong shape and TypeScript stops you at compile time; if a bad value reaches the wire
 anyway, the provider rejects it with a JSON-RPC `-32602 invalidParams`.
 
+## Typed application errors
+
+Checked application errors are opt-in and remain ordinary JSON-RPC errors on the wire. Declare
+stable code/message pairs (and, optionally, a data schema), then attach them to a request:
+
+```ts
+import { applicationError } from '@hediet/linkrpc';
+
+const notFound = applicationError(404, 'Not found');
+const conflict = applicationError(409, 'Conflict', z.object({ currentVersion: z.number() }));
+
+const documents = defineInterface({ id: 'acme.documents' }, {
+    read: requestType(z.object({ id: z.string() }), z.string())
+        .withErrors([notFound, conflict] as const),
+});
+
+connection.register(documents, {
+    read: ({ id }) => id === 'missing' ? notFound.create() : load(id),
+});
+```
+
+Calls are still real promises: `await client.read(...)` succeeds or rejects exactly as before.
+For explicit handling, methods declaring application errors also expose `result()`:
+
+```ts
+const client = connection.get(documents);
+const outcome = await client.read({ id }).result();
+if (!outcome.ok) {
+    if (outcome.error.kind === 'application') {
+        if (outcome.error.code === 409) {
+            console.log(outcome.error.data.currentVersion); // statically typed
+        } else {
+            console.log('Document not found'); // code 404, no data
+        }
+    } else if (outcome.error.kind === 'remote') {
+        console.error(outcome.error.code, outcome.error.message); // undeclared/malformed peer error
+    } else {
+        console.error(outcome.error.cause); // local validation or transport failure
+    }
+}
+```
+
+Promotion to `kind: 'application'` requires an exact code and message match. A descriptor without a
+data schema requires `data` to be absent; one with a schema requires valid data (including explicit
+`null` only when the schema allows it). Unknown or malformed peer errors remain generic remote
+errors. The legacy third `requestType` error-schema argument is still accepted for source
+compatibility, but does not opt a method into checked errors.
+
+Codes must be unique within the method, fit a signed 32-bit integer, and avoid
+`-32768..-32000` and LinkRPC's `-32800` cancellation code. Created errors are branded locally
+so an ordinary success object with similar fields is never mistaken for an error. Payloads
+must be JSON values matching the declared wire schema; encoding does not silently strip
+properties, insert defaults, or turn missing data into `null`.
+
+Interface JSON includes these declarations and their referenced data schemas in the hash.
+CLI-generated definitions expose the same typed constructors through
+`definition.members.method.errors[index].create(...)`. See the
+[Rust/TypeScript interoperability proof](../../../interop/README.md) for both authoring directions.
+
 ## Reflection — discoverability built in
 
 A connection is self-describing. Call `enableReflection()` and it exposes three standard interfaces

package/dist/chunks/{boundedTrafficSubscription-1L592xc7.js → boundedTrafficSubscription-XZ1KwXZC.js}

@@ -4,6 +4,7 @@
 *--------------------------------------------------------------------------------------------*/
 import { any, array, boolean, enum as enum$1, int, literal, nonnegative, number, object, optional, record, string, union, unknown, void as void$1 } from "zod/mini";
 import { toJSONSchema } from "zod/v4/core";
+import { z } from "zod";
 //#region src/schema/normalize.ts
 /**
 * Keys that describe structural shape and are part of the decidable subset.
@@ -153,6 +154,43 @@ function _constPropNames(props) {
 }
 //#endregion
 //#region src/schema/memberTypes.ts
+const applicationErrorBrand = Symbol("linkrpc.applicationError");
+function applicationError(code, message, dataSchema) {
+	assertApplicationErrorCode(code);
+	if (typeof message !== "string") throw new Error("Application error message must be a string.");
+	const create = dataSchema === void 0 ? function() {
+		if (arguments.length !== 0) throw new Error(`Application error ${code} does not accept data.`);
+		return Object.freeze({
+			kind: "application",
+			code,
+			message,
+			[applicationErrorBrand]: true
+		});
+	} : function(data) {
+		if (arguments.length !== 1) throw new Error(`Application error ${code} requires exactly one data value.`);
+		return Object.freeze({
+			kind: "application",
+			code,
+			message,
+			[applicationErrorBrand]: true,
+			data
+		});
+	};
+	return Object.freeze({
+		code,
+		message,
+		...dataSchema === void 0 ? {} : { dataSchema },
+		create
+	});
+}
+/** Runtime nominal check for values produced by an application-error descriptor. */
+function isApplicationErrorValue(value) {
+	return typeof value === "object" && value !== null && value[applicationErrorBrand] === true;
+}
+function assertApplicationErrorCode(code) {
+	if (!Number.isInteger(code) || code < -2147483648 || code > 2147483647) throw new Error(`Application error code ${code} must be a signed 32-bit integer.`);
+	if (code >= -32768 && code <= -32e3 || code === -32800) throw new Error(`Application error code ${code} is reserved by JSON-RPC or LinkRPC.`);
+}
 var RequestType = class RequestType {
 	paramsSchema;
 	resultSchema;
@@ -160,22 +198,45 @@ var RequestType = class RequestType {
 	docs;
 	clientStreamSchema;
 	serverStreamSchema;
+	applicationErrors;
 	kind = "request";
-	constructor(paramsSchema, resultSchema, errorSchema, docs = {}, clientStreamSchema, serverStreamSchema) {
+	constructor(paramsSchema, resultSchema, errorSchema, docs = {}, clientStreamSchema, serverStreamSchema, applicationErrors = []) {
 		this.paramsSchema = paramsSchema;
 		this.resultSchema = resultSchema;
 		this.errorSchema = errorSchema;
 		this.docs = docs;
 		this.clientStreamSchema = clientStreamSchema;
 		this.serverStreamSchema = serverStreamSchema;
+		this.applicationErrors = applicationErrors;
+		const seen = /* @__PURE__ */ new Set();
+		for (const error of applicationErrors) {
+			assertApplicationErrorCode(error.code);
+			if (typeof error.message !== "string") throw new Error("Application error message must be a string.");
+			if (seen.has(error.code)) throw new Error(`Duplicate application error code ${error.code}.`);
+			seen.add(error.code);
+		}
+		this.applicationErrors = Object.freeze([...applicationErrors]);
+		this.errors = this.applicationErrors;
 	}
+	/** Declared checked errors, retained as a tuple for generated-contract consumers. */
+	errors;
 	/**
 	* Return a copy of this request type with stream payload schemas
 	* attached. Pass `undefined` for either direction to leave it
 	* closed.
+	* `NoInfer` keeps a contextual MemberMap's `any` stream slots from
+	* widening undeclared directions; only the supplied schemas infer payloads.
 	*/
 	withStream(opts) {
-		return new RequestType(this.paramsSchema, this.resultSchema, this.errorSchema, this.docs, opts.client, opts.server);
+		return new RequestType(this.paramsSchema, this.resultSchema, this.errorSchema, this.docs, opts.client, opts.server, this.applicationErrors);
+	}
+	/**
+	* Return a copy with an explicit, typed set of checked application errors.
+	* The legacy third `requestType` schema remains accepted for compatibility,
+	* but does not opt a method into checked errors.
+	*/
+	withErrors(errors) {
+		return new RequestType(this.paramsSchema, this.resultSchema, this.errorSchema, this.docs, this.clientStreamSchema, this.serverStreamSchema, errors);
 	}
 };
 var NotificationType = class {
@@ -578,6 +639,181 @@ function stripNonNormative(value, isRoot = false) {
 	return out;
 }
 //#endregion
+//#region src/schema/assertSchemaReferences.ts
+const componentPrefix = "#/components/schemas/";
+function componentSchemaRef(name) {
+	return componentPrefix + name.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function componentSchemaName(ref) {
+	if (!ref.startsWith(componentPrefix)) throw new Error(`Invalid component reference: ${ref}`);
+	const token = ref.slice(21);
+	if (token.includes("/") || /~(?:[^01]|$)/.test(token)) throw new Error(`Invalid component reference token: ${ref}`);
+	return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+/**
+* Check the finite schema graph without interpreting JSON literal payloads.
+* A reference/union-only cycle is invalid; descending into an object member
+* or an array item guards a cycle, but does not imply the schema is nonempty.
+*/
+function assertSchemaReferences(roots, components = {}) {
+	const nodes = /* @__PURE__ */ new Set();
+	const pending = [...roots, ...Object.values(components)];
+	const unguarded = /* @__PURE__ */ new Map();
+	while (pending.length > 0) {
+		const node = pending.pop();
+		if (typeof node === "boolean" || nodes.has(node)) continue;
+		nodes.add(node);
+		const edges = [];
+		if ("$ref" in node) {
+			const name = componentSchemaName(node.$ref);
+			if (!Object.hasOwn(components, name)) throw new Error(`Unresolved component reference: ${node.$ref}`);
+			edges.push(components[name]);
+		}
+		if ("anyOf" in node) edges.push(...node.anyOf);
+		if ("oneOf" in node) edges.push(...node.oneOf);
+		unguarded.set(node, edges);
+		pending.push(...edges);
+		if ("type" in node && node.type === "object") pending.push(...Object.values(node.properties ?? {}), node.additionalProperties);
+		if ("type" in node && node.type === "array") {
+			if ("prefixItems" in node) pending.push(...node.prefixItems);
+			if (node.items !== void 0) pending.push(node.items);
+		}
+	}
+	const visiting = /* @__PURE__ */ new Set();
+	const checked = /* @__PURE__ */ new Set();
+	const visit = (node) => {
+		if (typeof node === "boolean" || checked.has(node)) return;
+		if (visiting.has(node)) throw new Error("Unguarded recursive schema: cycle does not descend into a child value");
+		visiting.add(node);
+		for (const child of unguarded.get(node) ?? []) visit(child);
+		visiting.delete(node);
+		checked.add(node);
+	};
+	for (const node of nodes) visit(node);
+}
+//#endregion
+//#region src/schema/schemaToZod.ts
+/**
+* Create a recursive LinkRPC-schema validator materializer. Component
+* references are lazy, so self and mutual recursion remain guarded.
+*/
+function createSchemaToZod(components = {}) {
+	assertSchemaReferences([], components);
+	const refs = /* @__PURE__ */ new Map();
+	const component = (name) => {
+		const existing = refs.get(name);
+		if (existing !== void 0) return existing;
+		const source = components[name];
+		if (source === void 0) throw new Error(`schemaToZod: dangling component reference "${name}"`);
+		const lazy = z.lazy(() => compile(source));
+		refs.set(name, lazy);
+		return lazy;
+	};
+	const compile = (schema) => {
+		if (schema === true) return z.unknown();
+		if (schema === false) return z.never();
+		const raw = schema;
+		if (Array.isArray(raw.type)) return union$1(raw.type.map((type) => compile({
+			...raw,
+			type
+		})));
+		let base;
+		if ("$ref" in schema) base = component(componentSchemaName(schema.$ref));
+		else if ("const" in schema) base = valueSchema(schema.const);
+		else if ("enum" in schema) base = union$1(schema.enum.map(valueSchema));
+		else if ("anyOf" in schema) base = union$1(schema.anyOf.map(compile));
+		else if ("oneOf" in schema) base = union$1(schema.oneOf.map(compile));
+		else if (isAnnotationOnlySchema(raw)) base = z.unknown();
+		else switch (schema.type) {
+			case "null":
+				base = z.null();
+				break;
+			case "boolean":
+				base = z.boolean();
+				break;
+			case "string":
+				base = stringSchema(schema.format);
+				break;
+			case "integer":
+				base = z.number().int();
+				break;
+			case "number":
+				base = z.number();
+				break;
+			case "array":
+				if ("prefixItems" in schema) {
+					const tuple = z.tuple(schema.prefixItems.map(compile));
+					base = schema.items !== void 0 && schema.items !== false ? tuple.rest(compile(schema.items)) : tuple;
+				} else base = z.array(compile(schema.items));
+				break;
+			case "object": {
+				const required = new Set(schema.required ?? []);
+				const shape = {};
+				for (const [name, property] of Object.entries(schema.properties)) {
+					const validator = compile(property);
+					shape[name] = required.has(name) ? validator : validator.optional();
+				}
+				const object = z.object(shape);
+				if (schema.additionalProperties === false) base = object.strict();
+				else if (schema.additionalProperties === true) base = object.loose();
+				else base = object.catchall(compile(schema.additionalProperties));
+				break;
+			}
+		}
+		return base;
+	};
+	return { toZod(schema) {
+		assertSchemaReferences([schema], components);
+		return compile(schema);
+	} };
+}
+function isAnnotationOnlySchema(schema) {
+	return ![
+		"$ref",
+		"const",
+		"enum",
+		"anyOf",
+		"oneOf",
+		"type",
+		"properties",
+		"items",
+		"prefixItems",
+		"additionalProperties"
+	].some((key) => Object.hasOwn(schema, key));
+}
+function schemaToZod(schema, components = {}) {
+	return createSchemaToZod(components).toZod(schema);
+}
+function union$1(items) {
+	if (items.length === 0) return z.never();
+	if (items.length === 1) return items[0];
+	return z.union(items);
+}
+function valueSchema(expected) {
+	return z.unknown().refine((actual) => jsonValueEqual(actual, expected), { message: `Expected ${JSON.stringify(expected)}` });
+}
+function jsonValueEqual(actual, expected) {
+	if (Object.is(actual, expected)) return true;
+	if (Array.isArray(actual) && Array.isArray(expected)) return actual.length === expected.length && actual.every((value, index) => jsonValueEqual(value, expected[index]));
+	if (actual !== null && expected !== null && typeof actual === "object" && typeof expected === "object" && !Array.isArray(actual) && !Array.isArray(expected)) {
+		const actualRecord = actual;
+		const expectedRecord = expected;
+		const keys = Object.keys(actualRecord);
+		return keys.length === Object.keys(expectedRecord).length && keys.every((key) => Object.hasOwn(expectedRecord, key) && jsonValueEqual(actualRecord[key], expectedRecord[key]));
+	}
+	return false;
+}
+function stringSchema(format) {
+	switch (format) {
+		case "email": return z.email();
+		case "uri":
+		case "url": return z.url();
+		case "uuid": return z.uuid();
+		case "date-time": return z.iso.datetime();
+		default: return z.string();
+	}
+}
+//#endregion
 //#region src/connection/interfaceDefinition.ts
 const interfaceDefinitionState = /* @__PURE__ */ new WeakMap();
 var InterfaceDefinition = class {
@@ -588,6 +824,7 @@ var InterfaceDefinition = class {
 	constructor(info, members, opts = {}) {
 		this.info = info;
 		this.members = members;
+		validateInterfaceErrors(opts.frozenSchema);
 		interfaceDefinitionState.set(this, {
 			frozenSchema: opts.frozenSchema,
 			schemaCache: void 0,
@@ -639,6 +876,14 @@ function toMethodSchema(name, member, components) {
 		};
 		if (member.clientStreamSchema !== void 0) m.clientStream = convertMemberSchema(name, "clientStream", member.clientStreamSchema, components);
 		if (member.serverStreamSchema !== void 0) m.serverStream = convertMemberSchema(name, "serverStream", member.serverStreamSchema, components);
+		if (member.applicationErrors.length > 0) m.errors = member.applicationErrors.map((error) => {
+			const result = {
+				code: error.code,
+				message: error.message
+			};
+			if (error.dataSchema !== void 0) result.data = convertMemberSchema(name, `error=${error.code}`, error.dataSchema, components);
+			return result;
+		});
 		if (docs.description !== void 0) m.description = docs.description;
 		if (docs.comment !== void 0) m.comment = docs.comment;
 		if (docs.annotations !== void 0) m.annotations = docs.annotations;
@@ -650,6 +895,20 @@ function toMethodSchema(name, member, components) {
 	if (docs.annotations !== void 0) m.annotations = docs.annotations;
 	return m;
 }
+function validateInterfaceErrors(schema) {
+	if (schema === void 0) return;
+	for (const [methodName, method] of Object.entries(schema.methods)) {
+		if (method.result === void 0 && method.errors !== void 0) throw new Error(`Notification "${methodName}" cannot declare application errors.`);
+		const seen = /* @__PURE__ */ new Set();
+		for (const error of method.errors ?? []) {
+			if (typeof error.message !== "string") throw new Error(`Application error message on "${methodName}" must be a string.`);
+			if (!Number.isInteger(error.code) || error.code < -2147483648 || error.code > 2147483647) throw new Error(`Application error code ${error.code} on "${methodName}" must be a signed 32-bit integer.`);
+			if (error.code >= -32768 && error.code <= -32e3 || error.code === -32800) throw new Error(`Application error code ${error.code} on "${methodName}" is reserved by JSON-RPC or LinkRPC.`);
+			if (seen.has(error.code)) throw new Error(`Duplicate application error code ${error.code} on "${methodName}".`);
+			seen.add(error.code);
+		}
+	}
+}
 function convertMemberSchema(methodName, position, schema, components) {
 	return zodToSvcJsonSchema(schema, {
 		methodName,
@@ -686,7 +945,9 @@ function defineInterface(info, members) {
 * consumers see the real wire contract. Member-level params / results /
 * streams use `z.any()` because no zod source is available — call-site
 * validation is therefore a no-op and the caller is responsible for
-* shape-checking inputs and outputs.
+* shape-checking inputs and outputs. Declared application-error payloads
+* are materialized and validated because recognizing a typed error must
+* never rely on its code alone.
 *
 * Methods with no `result` descriptor become notifications; methods with
 * `clientStream` / `serverStream` get pass-through stream payload
@@ -699,7 +960,7 @@ function interfaceFromSchema(schema) {
 			members[name] = new NotificationType(any());
 			continue;
 		}
-		const base = new RequestType(any(), any(), void$1());
+		const base = new RequestType(any(), any(), void$1()).withErrors((method.errors ?? []).map((error) => error.data === void 0 ? applicationError(error.code, error.message) : applicationError(error.code, error.message, schemaToZod(error.data, schema.components?.schemas))));
 		members[name] = method.clientStream !== void 0 || method.serverStream !== void 0 ? base.withStream({
 			client: method.clientStream !== void 0 ? any() : void 0,
 			server: method.serverStream !== void 0 ? any() : void 0
@@ -1121,6 +1382,6 @@ function capPayload(value, maxBytes) {
 	return preview;
 }
 //#endregion
-export { NotificationType as A, defineInterface as C, sha256 as D, computeInterfaceHash as E, normalizeJsonSchema as F, notificationType as M, requestType as N, jcsCanonicalize as O, zodToSvcJsonSchema as P, InterfaceDefinition as S, EXTENSION_PREFIX as T, zTrafficEvent as _, topologyInterface as a, zTrafficTransitEvent as b, zParticipantDescriptorSource as c, zTopologyLink as d, zTopologyLinkEndpoint as f, zTopologyTransportInfo as g, zTopologyTransportEndpoint as h, nodeInterface as i, RequestType as j, jcsCanonicalizeBytes as k, zRouteClaim as l, zTopologyPort as m, TrafficFlowFilter as n, trafficInterface as o, zTopologyNode as p, TrafficWatchFlowTracker as r, zParticipantDescriptor as s, BoundedTrafficSubscription as t, zTopologyGraph as u, zTrafficOverflowEvent as v, interfaceFromSchema as w, zTrafficWatchResult as x, zTrafficTransitEndpoint as y };
+export { EXTENSION_PREFIX as A, requestType as B, defineInterface as C, assertSchemaReferences as D, schemaToZod as E, NotificationType as F, normalizeJsonSchema as H, RequestType as I, applicationError as L, sha256 as M, jcsCanonicalize as N, componentSchemaName as O, jcsCanonicalizeBytes as P, isApplicationErrorValue as R, InterfaceDefinition as S, createSchemaToZod as T, zodToSvcJsonSchema as V, zTrafficEvent as _, topologyInterface as a, zTrafficTransitEvent as b, zParticipantDescriptorSource as c, zTopologyLink as d, zTopologyLinkEndpoint as f, zTopologyTransportInfo as g, zTopologyTransportEndpoint as h, nodeInterface as i, computeInterfaceHash as j, componentSchemaRef as k, zRouteClaim as l, zTopologyPort as m, TrafficFlowFilter as n, trafficInterface as o, zTopologyNode as p, TrafficWatchFlowTracker as r, zParticipantDescriptor as s, BoundedTrafficSubscription as t, zTopologyGraph as u, zTrafficOverflowEvent as v, interfaceFromSchema as w, zTrafficWatchResult as x, zTrafficTransitEndpoint as y, notificationType as z };
 
-//# sourceMappingURL=boundedTrafficSubscription-1L592xc7.js.map
+//# sourceMappingURL=boundedTrafficSubscription-XZ1KwXZC.js.map