@orpc/json-schema 2.0.0-beta.47 → 2.0.0-beta.48

package/dist/ref-utils.d.mts

@@ -0,0 +1,44 @@
+/**
+* These utilities assume the schema has only one root-level `$defs` object
+* and exclusively use absolute JSON pointers for `$ref` values.
+*/
+import type { JsonSchema } from "./types.mjs";
+/**
+* Encodes a JSON Pointer segment according to RFC 6901.
+*
+* https://datatracker.ietf.org/doc/html/rfc6901
+*/
+export declare function encodeJsonPointerSegment(segment: string): string;
+/**
+* Decodes a JSON Pointer segment according to RFC 6901.
+*
+* https://datatracker.ietf.org/doc/html/rfc6901
+*/
+export declare function decodeJsonPointerSegment(segment: string): string;
+/**
+* Visits every `$ref` in a schema, traversing the same keywords as {@link mapJsonSchemaRefs}.
+* Shared or cyclic object instances are visited once.
+*/
+export declare function visitJsonSchemaRefs(value: JsonSchema, visit: (ref: string) => void, schemaLevel?: boolean, seen?: Set<object>): void;
+export declare function mapJsonSchemaRefs(value: JsonSchema, map: (ref: string, path: Array<string | number>) => string, schemaLevel?: boolean, path?: Array<string | number>): JsonSchema;
+/**
+* Rewrites recursive root `#` refs by moving the schema body into `$defs`.
+*/
+export declare function hoistRecursiveRefToDef(schema: JsonSchema): JsonSchema;
+/**
+* Resolves a local `$ref` at the **root level** of the given schema, if present.
+*
+* Only handles refs of the form `#/$defs/<name>` pointing into the provided
+* (or schema-embedded) `$defs` map. Nested `$ref`s inside sub-schemas are
+* intentionally left untouched.
+*
+* If the ref cannot be resolved (missing `$defs`, unknown key, etc.) the
+* schema is returned as-is. Chained refs are followed until one repeats,
+* which is kept.
+*
+* @param schema - The schema whose root-level `$ref` should be resolved.
+* @param $defs - Definition map to resolve against. If omitted, falls back to
+*   `schema.$defs`. When provided, takes precedence over any `$defs` embedded
+*   in the schema.
+*/
+export declare function resolveJsonSchemaRootLocalRef(schema: JsonSchema, $defs?: Exclude<JsonSchema, boolean>["$defs"]): JsonSchema;

package/dist/ref-utils.mjs

@@ -0,0 +1,117 @@
+import { get, setOwn } from "@orpc/shared";
+import { JSON_SCHEMA_LOGIC_KEYWORDS, JSON_SCHEMA_RECORD_KEYWORDS } from "./constants.mjs";
+
+export function encodeJsonPointerSegment(segment) {
+	return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+export function decodeJsonPointerSegment(segment) {
+	return segment.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+
+export function visitJsonSchemaRefs(value, visit, schemaLevel = true, seen = new Set()) {
+	if (!value || typeof value !== "object" || seen.has(value)) {
+		return;
+	}
+	seen.add(value);
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			visitJsonSchemaRefs(item, visit, schemaLevel, seen);
+		}
+		return;
+	}
+	for (const key of Object.keys(value)) {
+		const val = value[key];
+		if (key === "$ref" && typeof val === "string") {
+			visit(val);
+		} else if (!schemaLevel) {
+			visitJsonSchemaRefs(val, visit, true, seen);
+		} else if (JSON_SCHEMA_LOGIC_KEYWORDS.has(key) || JSON_SCHEMA_RECORD_KEYWORDS.has(key)) {
+			visitJsonSchemaRefs(val, visit, !JSON_SCHEMA_RECORD_KEYWORDS.has(key), seen);
+		}
+	}
+}
+export function mapJsonSchemaRefs(value, map, schemaLevel = true, path = []) {
+	if (!value || typeof value !== "object") {
+		return value;
+	}
+	if (Array.isArray(value)) {
+		return value.map((item, index) => mapJsonSchemaRefs(item, map, schemaLevel, [...path, index]));
+	}
+	const result = {};
+	for (const key of Object.keys(value)) {
+		const val = value[key];
+		if (key === "$ref" && typeof val === "string") {
+			setOwn(result, key, map(val, [...path, key]));
+		} else if (!schemaLevel) {
+			setOwn(result, key, mapJsonSchemaRefs(val, map, true, [...path, key]));
+		} else if (JSON_SCHEMA_LOGIC_KEYWORDS.has(key) || JSON_SCHEMA_RECORD_KEYWORDS.has(key)) {
+			setOwn(result, key, mapJsonSchemaRefs(val, map, !JSON_SCHEMA_RECORD_KEYWORDS.has(key), [...path, key]));
+		} else {
+			setOwn(result, key, val);
+		}
+	}
+	return result;
+}
+
+export function hoistRecursiveRefToDef(schema) {
+	if (typeof schema !== "object") {
+		return schema;
+	}
+	const isRootRef = (ref) => ref === "#" || ref.startsWith("#/") && !ref.startsWith("#/$defs/") && get(schema, ref.slice(2).split("/").map(decodeJsonPointerSegment)) !== undefined;
+	
+	let hasRootRef = false;
+	visitJsonSchemaRefs(schema, (ref) => {
+		hasRootRef ||= isRootRef(ref);
+	});
+	if (!hasRootRef) {
+		return schema;
+	}
+	const defName = findRecursiveJsonSchemaDefName(schema.$defs);
+	const defRef = `#/$defs/${encodeJsonPointerSegment(defName)}`;
+	const { $defs, ...rest } = mapJsonSchemaRefs(schema, (ref) => isRootRef(ref) ? `${defRef}${ref.slice(1)}` : ref);
+	return {
+		$ref: defRef,
+		$defs: {
+			...$defs,
+			[defName]: rest
+		}
+	};
+}
+
+export function resolveJsonSchemaRootLocalRef(schema, $defs) {
+	if (typeof schema === "boolean") {
+		return schema;
+	}
+	if (arguments.length === 1) {
+		$defs = schema.$defs;
+	}
+	if (!$defs) {
+		return schema;
+	}
+	const followedRefs = new Set();
+	let current = schema;
+	while (typeof current.$ref === "string" && current.$ref.startsWith("#/$defs/") && !followedRefs.has(current.$ref)) {
+		followedRefs.add(current.$ref);
+		const resolved = get($defs, current.$ref.slice("#/$defs/".length).split("/").map(decodeJsonPointerSegment));
+		if (resolved === undefined) {
+			return current;
+		}
+		if (typeof resolved !== "object") {
+			return resolved;
+		}
+		const { $ref: _ref, ...rest } = current;
+		current = {
+			...rest,
+			...resolved
+		};
+	}
+	return current;
+}
+function findRecursiveJsonSchemaDefName(defs) {
+	let index = 0;
+	while (defs?.[`__schema${index}`] !== undefined) {
+		index++;
+	}
+	return `__schema${index}`;
+}

package/dist/smart-coercion-handler-plugin.d.mts

@@ -0,0 +1,22 @@
+import type { Context } from "@orpc/server";
+import type { StandardHandlerOptions, StandardHandlerPlugin } from "@orpc/server/standard";
+import type { JsonSchemaCoercerOptions } from "./coercer.mjs";
+import type { JsonSchemaConverter } from "./convert.mjs";
+export interface SmartCoercionHandlerPluginOptions extends JsonSchemaCoercerOptions {
+	converters?: JsonSchemaConverter[] | undefined;
+}
+/**
+* Coerces incoming request data to match the expected `.input` schema types before validation,
+* based on JSON schemas produced by the configured converters.
+*
+* @see {@link https://orpc.dev/docs/plugins/smart-coercion | Smart Coercion Plugin}
+*/
+export declare class SmartCoercionHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+	name: string;
+	private readonly converter;
+	private readonly coercer;
+	private readonly cache;
+	constructor(options?: SmartCoercionHandlerPluginOptions);
+	init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
+	private coerceValue;
+}

package/dist/smart-coercion-handler-plugin.mjs

@@ -0,0 +1,42 @@
+import { toArray } from "@orpc/shared";
+import { JsonSchemaCoercer } from "./coercer.mjs";
+import { DelegatingJsonSchemaConverter } from "./convert.mjs";
+import { StandardJsonSchemaConverter } from "./standard-json-schema-converter.mjs";
+
+export class SmartCoercionHandlerPlugin {
+	name = "~smart-coercion";
+	converter;
+	coercer;
+	cache = new WeakMap();
+	constructor(options = {}) {
+		this.converter = new DelegatingJsonSchemaConverter([...toArray(options.converters), new StandardJsonSchemaConverter()]);
+		this.coercer = new JsonSchemaCoercer(options);
+	}
+	init(options) {
+		return {
+			...options,
+			clientInterceptors: [({ next, input, ...interceptorOptions }) => {
+				const inputSchemas = interceptorOptions.procedure["~orpc"].inputSchemas;
+				if (!inputSchemas) {
+					return next();
+				}
+				const coercedInput = this.coerceValue(inputSchemas, input);
+				return next({
+					...interceptorOptions,
+					input: coercedInput
+				});
+			}, ...toArray(options.clientInterceptors)]
+		};
+	}
+	coerceValue(schemas, value) {
+		for (const schema of schemas) {
+			let converted = this.cache.get(schema);
+			if (!converted) {
+				converted = this.converter.convert(schema, "input");
+				this.cache.set(schema, converted);
+			}
+			value = this.coercer.coerce(converted, value);
+		}
+		return value;
+	}
+}

package/dist/smart-coercion-link-plugin.d.mts

@@ -0,0 +1,28 @@
+import type { ClientContext } from "@orpc/client";
+import type { StandardLinkOptions, StandardLinkPlugin } from "@orpc/client/standard";
+import type { RouterContract } from "@orpc/contract";
+import type { JsonSchemaCoercerOptions } from "./coercer.mjs";
+import type { JsonSchemaConverter } from "./convert.mjs";
+export interface SmartCoercionLinkPluginOptions extends JsonSchemaCoercerOptions {
+	converters?: JsonSchemaConverter[] | undefined;
+}
+/**
+* Coerces server responses to match the expected `.output` or `.errors` schema types before validation,
+* based on JSON schemas produced by the configured converters.
+*
+* @see {@link https://orpc.dev/docs/plugins/smart-coercion | Smart Coercion Plugin}
+*/
+export declare class SmartCoercionLinkPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
+	private readonly contract;
+	name: string;
+	/**
+	* Output and error values should be coerced before validation.
+	*/
+	after: string[];
+	private readonly converter;
+	private readonly coercer;
+	private readonly cache;
+	constructor(contract: RouterContract, options?: SmartCoercionLinkPluginOptions);
+	init(options: StandardLinkOptions<T>): StandardLinkOptions<T>;
+	private coerceValue;
+}

package/dist/smart-coercion-link-plugin.mjs

@@ -0,0 +1,61 @@
+import { cloneORPCError, ORPCError } from "@orpc/client";
+import { getProcedureContractOrThrow } from "@orpc/contract";
+import { getOwn, toArray } from "@orpc/shared";
+import { JsonSchemaCoercer } from "./coercer.mjs";
+import { DelegatingJsonSchemaConverter } from "./convert.mjs";
+import { StandardJsonSchemaConverter } from "./standard-json-schema-converter.mjs";
+
+export class SmartCoercionLinkPlugin {
+	contract;
+	name = "~smart-coercion";
+	
+	after = ["~response-validation"];
+	converter;
+	coercer;
+	cache = new WeakMap();
+	constructor(contract, options = {}) {
+		this.contract = contract;
+		this.converter = new DelegatingJsonSchemaConverter([...toArray(options.converters), new StandardJsonSchemaConverter()]);
+		this.coercer = new JsonSchemaCoercer(options);
+	}
+	init(options) {
+		return {
+			...options,
+			interceptors: [...toArray(options.interceptors), async ({ next, path }) => {
+				const procedure = getProcedureContractOrThrow(this.contract, path);
+				try {
+					const output = await next();
+					const outputSchemas = procedure["~orpc"].outputSchemas;
+					if (!outputSchemas) {
+						return output;
+					}
+					const coercedOutput = this.coerceValue(outputSchemas, output);
+					return coercedOutput;
+				} catch (error) {
+					if (!(error instanceof ORPCError) || !error.defined) {
+						throw error;
+					}
+					const errorMap = procedure["~orpc"].errorMap;
+					const dataSchema = getOwn(errorMap, error.code)?.data;
+					if (!dataSchema) {
+						throw error;
+					}
+					const cloned = cloneORPCError(error);
+					cloned.data = this.coerceValue([dataSchema], cloned.data);
+					throw cloned;
+				}
+			}]
+		};
+	}
+	coerceValue(schemas, value) {
+		for (const schema of schemas) {
+			let converted = this.cache.get(schema);
+			if (!converted) {
+				converted = this.converter.convert(schema, "output");
+				this.cache.set(schema, converted);
+			}
+			value = this.coercer.coerce(converted, value);
+		}
+		return value;
+	}
+}

package/dist/standard-json-schema-converter.d.mts

@@ -0,0 +1,16 @@
+import type { AnySchema } from "@orpc/contract";
+import type { StandardJSONSchemaV1 } from "@standard-schema/spec";
+import type { JsonSchemaConverter, JsonSchemaConverterDirection } from "./convert.mjs";
+import type { JsonSchema } from "./types.mjs";
+/**
+* Returns true when the schema accepts `undefined` in the given direction,
+* found by validating `undefined` against it. For `output`, the validated value must also be `undefined`.
+*
+* Returns false when validation throws or is async. An async result is never left as an unhandled rejection.
+*/
+export declare function isStandardSchemaOptional(schema: AnySchema, direction: JsonSchemaConverterDirection): boolean;
+export declare class StandardJsonSchemaConverter implements JsonSchemaConverter {
+	condition(schema: AnySchema | undefined, _direction: JsonSchemaConverterDirection): boolean;
+	convert(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): [jsonSchema: JsonSchema, optional: boolean];
+	convertInternal(schema: StandardJSONSchemaV1 & AnySchema, direction: JsonSchemaConverterDirection): [jsonSchema: JsonSchema, optional: boolean];
+}

package/dist/standard-json-schema-converter.mjs

@@ -0,0 +1,30 @@
+import { isTypescriptObject } from "@orpc/shared";
+
+export function isStandardSchemaOptional(schema, direction) {
+	try {
+		const result = schema["~standard"].validate(undefined);
+		if (result instanceof Promise) {
+			result.catch(() => {});
+			return false;
+		}
+		return !result.issues && (direction === "input" || result.value === undefined);
+	} catch {
+		return false;
+	}
+}
+export class StandardJsonSchemaConverter {
+	condition(schema, _direction) {
+		return Boolean(schema && "jsonSchema" in schema["~standard"] && isTypescriptObject(schema["~standard"].jsonSchema) && "input" in schema["~standard"].jsonSchema && typeof schema["~standard"].jsonSchema.input === "function" && "output" in schema["~standard"].jsonSchema && typeof schema["~standard"].jsonSchema.output === "function");
+	}
+	convert(schema, direction) {
+		return this.convertInternal(schema, direction);
+	}
+	convertInternal(schema, direction) {
+		try {
+			const jsonSchema = direction === "input" ? schema["~standard"].jsonSchema.input({ target: "draft-2020-12" }) : schema["~standard"].jsonSchema.output({ target: "draft-2020-12" });
+			return [jsonSchema, isStandardSchemaOptional(schema, direction)];
+		} catch {
+			return [{}, true];
+		}
+	}
+}

package/dist/types.d.mts

@@ -0,0 +1,51 @@
+import type * as OpenAPIV3_2 from "@openapi-spec/types/v3.2";
+/**
+* A JSON Schema (draft 2020-12) representation used across oRPC's JSON schema tooling.
+*
+* @remarks
+* It is also the OpenAPI 3.2 Schema Object, so converted schemas embed into OpenAPI documents as-is.
+*
+* @see {@link https://orpc.dev/docs/integrations/standard-schema | Standard Schema Integration}
+*/
+export type JsonSchema<Value = any> = OpenAPIV3_2.SchemaObject<Value>;
+/**
+* The declared JSON Schema keywords, the index signature is filtered out.
+*/
+export type JsonSchemaKeywords = keyof { [K in keyof OpenAPIV3_2.SchemaObjectFields as string extends K ? never : K]: unknown };
+export declare enum JsonSchemaType {
+	Array = "array",
+	Boolean = "boolean",
+	Integer = "integer",
+	Null = "null",
+	Number = "number",
+	Object = "object",
+	String = "string"
+}
+export declare enum JsonSchemaFormat {
+	Date = "date",
+	DateTime = "date-time",
+	Duration = "duration",
+	Email = "email",
+	Hostname = "hostname",
+	IDNEmail = "idn-email",
+	IDNHostname = "idn-hostname",
+	IPv4 = "ipv4",
+	IPv6 = "ipv6",
+	IRI = "iri",
+	IRIReference = "iri-reference",
+	JSONPointer = "json-pointer",
+	RegEx = "regex",
+	RelativeJSONPointer = "relative-json-pointer",
+	Time = "time",
+	URI = "uri",
+	URIReference = "uri-reference",
+	URITemplate = "uri-template",
+	UUID = "uuid"
+}
+export declare enum JsonSchemaXNativeType {
+	BigInt = "bigint",
+	Date = "date",
+	Url = "url",
+	Set = "set",
+	Map = "map"
+}

package/dist/types.mjs

@@ -0,0 +1,40 @@
+export let JsonSchemaType = /* @__PURE__ */ function(JsonSchemaType) {
+	JsonSchemaType["Array"] = "array";
+	JsonSchemaType["Boolean"] = "boolean";
+	JsonSchemaType["Integer"] = "integer";
+	JsonSchemaType["Null"] = "null";
+	JsonSchemaType["Number"] = "number";
+	JsonSchemaType["Object"] = "object";
+	JsonSchemaType["String"] = "string";
+	return JsonSchemaType;
+}({});
+export let JsonSchemaFormat = /* @__PURE__ */ function(JsonSchemaFormat) {
+	JsonSchemaFormat["Date"] = "date";
+	JsonSchemaFormat["DateTime"] = "date-time";
+	JsonSchemaFormat["Duration"] = "duration";
+	JsonSchemaFormat["Email"] = "email";
+	JsonSchemaFormat["Hostname"] = "hostname";
+	JsonSchemaFormat["IDNEmail"] = "idn-email";
+	JsonSchemaFormat["IDNHostname"] = "idn-hostname";
+	JsonSchemaFormat["IPv4"] = "ipv4";
+	JsonSchemaFormat["IPv6"] = "ipv6";
+	JsonSchemaFormat["IRI"] = "iri";
+	JsonSchemaFormat["IRIReference"] = "iri-reference";
+	JsonSchemaFormat["JSONPointer"] = "json-pointer";
+	JsonSchemaFormat["RegEx"] = "regex";
+	JsonSchemaFormat["RelativeJSONPointer"] = "relative-json-pointer";
+	JsonSchemaFormat["Time"] = "time";
+	JsonSchemaFormat["URI"] = "uri";
+	JsonSchemaFormat["URIReference"] = "uri-reference";
+	JsonSchemaFormat["URITemplate"] = "uri-template";
+	JsonSchemaFormat["UUID"] = "uuid";
+	return JsonSchemaFormat;
+}({});
+export let JsonSchemaXNativeType = /* @__PURE__ */ function(JsonSchemaXNativeType) {
+	JsonSchemaXNativeType["BigInt"] = "bigint";
+	JsonSchemaXNativeType["Date"] = "date";
+	JsonSchemaXNativeType["Url"] = "url";
+	JsonSchemaXNativeType["Set"] = "set";
+	JsonSchemaXNativeType["Map"] = "map";
+	return JsonSchemaXNativeType;
+}({});

package/dist/utils.d.mts

@@ -0,0 +1,40 @@
+/**
+* These utilities assume the schema has only one root-level `$defs` object
+* and exclusively use absolute JSON pointers for `$ref` values.
+*/
+import type { JsonSchema } from "./types.mjs";
+export declare function isJsonPrimitiveSchema(schema: JsonSchema): schema is JsonSchema & object;
+export type JsonFileSchema = JsonSchema & object & {
+	type: "string";
+	contentMediaType?: string;
+};
+/**
+* Returns true when the schema is a file-like string schema.
+*/
+export declare function isJsonFileSchema(schema: JsonSchema): schema is JsonFileSchema;
+/**
+* Returns true when a file schema appears anywhere in the schema, such as in a property, a composition, or a def.
+*/
+export declare function containsJsonFileSchema(schema: JsonSchema): boolean;
+export type JsonObjectSchema = JsonSchema & object & {
+	type: "object";
+};
+/**
+* Returns true when the schema is an object schema.
+*/
+export declare function isJsonObjectSchema(schema: JsonSchema): schema is JsonObjectSchema;
+export type JsonArraySchema = JsonSchema & object & {
+	type: "array";
+};
+/**
+* Returns true when the schema is an array schema.
+*/
+export declare function isJsonArraySchema(schema: JsonSchema): schema is JsonArraySchema;
+/**
+* Returns true when the schema does not apply any recognized constraints.
+*/
+export declare function isUnconstrainedSchema(schema: JsonSchema): boolean;
+/**
+* Ensures a JSON Schema is represented as an object schema document.
+*/
+export declare function ensureJsonSchemaObject(schema: JsonSchema): Exclude<JsonSchema, boolean>;

package/dist/utils.mjs

@@ -0,0 +1,50 @@
+import { findDeepMatches, isPlainObject } from "@orpc/shared";
+import { JSON_SCHEMA_LOGIC_KEYWORDS, JSON_SCHEMA_PRIMITIVE_TYPES } from "./constants.mjs";
+export function isJsonPrimitiveSchema(schema) {
+	if (typeof schema === "boolean") {
+		return false;
+	}
+	if (typeof schema.type === "string" && JSON_SCHEMA_PRIMITIVE_TYPES.has(schema.type)) {
+		return true;
+	}
+	if (schema.const !== undefined) {
+		return true;
+	}
+	if (schema.enum !== undefined) {
+		return true;
+	}
+	return false;
+}
+
+export function isJsonFileSchema(schema) {
+	return typeof schema !== "boolean" && schema.type === "string" && (typeof schema.contentMediaType === "string" || schema.format === "binary" || schema.contentEncoding === "binary");
+}
+
+export function containsJsonFileSchema(schema) {
+	return findDeepMatches((v) => isPlainObject(v) && isJsonFileSchema(v), schema).values.length > 0;
+}
+
+export function isJsonObjectSchema(schema) {
+	return typeof schema !== "boolean" && schema.type === "object";
+}
+
+export function isJsonArraySchema(schema) {
+	return typeof schema !== "boolean" && schema.type === "array";
+}
+
+export function isUnconstrainedSchema(schema) {
+	if (typeof schema === "boolean") {
+		return schema;
+	}
+	if (Object.keys(schema).every((k) => !JSON_SCHEMA_LOGIC_KEYWORDS.has(k))) {
+		return true;
+	}
+	return false;
+}
+
+export function ensureJsonSchemaObject(schema) {
+	if (typeof schema === "boolean") {
+		return schema ? {} : { not: {} };
+	}
+	return schema;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@orpc/json-schema",
   "type": "module",
-  "version": "2.0.0-beta.47",
+  "version": "2.0.0-beta.48",
   "description": "JSON Schema conversion and smart request coercion for oRPC and OpenAPI",
   "license": "MIT",
   "funding": [
@@ -35,11 +35,11 @@
     "dist"
   ],
   "dependencies": {
-    "@openapi-spec/types": "~0.4.0",
-    "@orpc/client": "2.0.0-beta.47",
-    "@orpc/contract": "2.0.0-beta.47",
-    "@orpc/server": "2.0.0-beta.47",
-    "@orpc/shared": "2.0.0-beta.47",
+    "@openapi-spec/types": "~0.6.0",
+    "@orpc/client": "2.0.0-beta.48",
+    "@orpc/contract": "2.0.0-beta.48",
+    "@orpc/server": "2.0.0-beta.48",
+    "@orpc/shared": "2.0.0-beta.48",
     "@standard-schema/spec": "^1.1.0"
   },
   "devDependencies": {