@orpc/json-schema 2.0.0-beta.4 → 2.0.0-beta.41

package/dist/index.d.ts

@@ -1,19 +1,59 @@
-import * as Draft2020 from 'json-schema-typed/draft-2020-12';
-export { Format as JsonSchemaFormat, TypeName as JsonSchemaType } from 'json-schema-typed/draft-2020-12';
+import { OpenAPIV3_2 } from '@openapi-spec/types';
 import { AnySchema, RouterContract } from '@orpc/contract';
 export { AnySchema, Schema } from '@orpc/contract';
-import { Promisable } from '@orpc/shared';
 import { Context } from '@orpc/server';
 import { StandardHandlerPlugin, StandardHandlerOptions } from '@orpc/server/standard';
 import { ClientContext } from '@orpc/client';
 import { StandardLinkPlugin, StandardLinkOptions } from '@orpc/client/standard';
 import { StandardJSONSchemaV1 } from '@standard-schema/spec';
 
-type JsonSchema = Draft2020.JSONSchema;
-type JsonSchemaKeywords = typeof Draft2020.keywords[number];
+/**
+ * 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}
+ */
+type JsonSchema<Value = any> = OpenAPIV3_2.SchemaObject<Value>;
+/**
+ * The declared JSON Schema keywords, the index signature is filtered out.
+ */
+type JsonSchemaKeywords = keyof {
+    [K in keyof OpenAPIV3_2.SchemaObjectFields as string extends K ? never : K]: unknown;
+};
+declare enum JsonSchemaType {
+    Array = "array",
+    Boolean = "boolean",
+    Integer = "integer",
+    Null = "null",
+    Number = "number",
+    Object = "object",
+    String = "string"
+}
+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"
+}
 declare enum JsonSchemaXNativeType {
     BigInt = "bigint",
-    RegExp = "regexp",
     Date = "date",
     Url = "url",
     Set = "set",
@@ -90,21 +130,32 @@ declare function flattenJsonUnionSchema(schema: JsonSchema): JsonSchema[];
 declare function matchArrayableJsonSchema(schema: JsonSchema): undefined | [itemSchema: JsonSchema, arraySchema: JsonArraySchema];
 declare function deduplicateJsonSchemas(schemas: JsonSchema[]): JsonSchema[];
 
+/**
+ * The conversion direction: `input` targets the schema's input type, `output` targets its output type.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/standard-schema | Standard Schema Integration}
+ */
 type JsonSchemaConverterDirection = 'input' | 'output';
+/**
+ * Interface for converting validation schemas into JSON Schema representations,
+ * used by tools such as the OpenAPI Generator and Smart Coercion plugins.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/standard-schema | Standard Schema Integration}
+ */
 interface JsonSchemaConverter {
     /**
      * Determines whether this converter can handle the given schema.
      */
-    condition(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): Promisable<boolean>;
+    condition(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): boolean;
     /**
      * Converts an ORPC schema to a JSON Schema representation.
      */
-    convert(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): Promisable<[jsonSchema: JsonSchema, optional: boolean]>;
+    convert(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): [jsonSchema: JsonSchema, optional: boolean];
 }
 declare class DelegatingJsonSchemaConverter implements Pick<JsonSchemaConverter, 'convert'> {
     private readonly converters;
     constructor(converters?: JsonSchemaConverter[]);
-    convert(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): Promise<[jsonSchema: JsonSchema, optional: boolean]>;
+    convert(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): [jsonSchema: JsonSchema, optional: boolean];
 }
 
 /**
@@ -124,6 +175,11 @@ declare function encodeJsonPointerSegment(segment: string): string;
  * https://datatracker.ietf.org/doc/html/rfc6901
  */
 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.
+ */
+declare function visitJsonSchemaRefs(value: JsonSchema, visit: (ref: string) => void, schemaLevel?: boolean, seen?: Set<object>): void;
 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`.
@@ -137,7 +193,8 @@ declare function hoistRecursiveRefToDef(schema: JsonSchema): JsonSchema;
  * intentionally left untouched.
  *
  * If the ref cannot be resolved (missing `$defs`, unknown key, etc.) the
- * schema is returned as-is.
+ * 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
@@ -149,6 +206,12 @@ declare function resolveJsonSchemaRootLocalRef(schema: JsonSchema, $defs?: Exclu
 interface SmartCoercionHandlerPluginOptions {
     converters?: undefined | JsonSchemaConverter[];
 }
+/**
+ * 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}
+ */
 declare class SmartCoercionHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
     name: string;
     private readonly converter;
@@ -162,6 +225,12 @@ declare class SmartCoercionHandlerPlugin<T extends Context> implements StandardH
 interface SmartCoercionLinkPluginOptions {
     converters?: undefined | JsonSchemaConverter[];
 }
+/**
+ * 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}
+ */
 declare class SmartCoercionLinkPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
     private readonly contract;
     name: string;
@@ -177,11 +246,18 @@ declare class SmartCoercionLinkPlugin<T extends ClientContext> implements Standa
     private coerceValue;
 }
 
+/**
+ * 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.
+ */
+declare function isStandardSchemaOptional(schema: AnySchema, direction: JsonSchemaConverterDirection): boolean;
 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];
 }
 
-export { DelegatingJsonSchemaConverter, JsonSchemaCoercer, JsonSchemaXNativeType, SmartCoercionHandlerPlugin, SmartCoercionLinkPlugin, StandardJsonSchemaConverter, combineJsonObjectSchemaEntries, combineJsonSchemasWithComposition, decodeJsonPointerSegment, deduplicateJsonSchemas, encodeJsonPointerSegment, ensureJsonSchemaObject, extractJsonObjectSchemaEntries, flattenJsonUnionSchema, hoistRecursiveRefToDef, isJsonArraySchema, isJsonFileSchema, isJsonObjectSchema, isJsonPrimitiveSchema, isUnconstrainedSchema, mapJsonSchemaRefs, matchArrayableJsonSchema, resolveJsonSchemaRootLocalRef };
+export { DelegatingJsonSchemaConverter, JsonSchemaCoercer, JsonSchemaFormat, JsonSchemaType, JsonSchemaXNativeType, SmartCoercionHandlerPlugin, SmartCoercionLinkPlugin, StandardJsonSchemaConverter, combineJsonObjectSchemaEntries, combineJsonSchemasWithComposition, decodeJsonPointerSegment, deduplicateJsonSchemas, encodeJsonPointerSegment, ensureJsonSchemaObject, extractJsonObjectSchemaEntries, flattenJsonUnionSchema, hoistRecursiveRefToDef, isJsonArraySchema, isJsonFileSchema, isJsonObjectSchema, isJsonPrimitiveSchema, isStandardSchemaOptional, isUnconstrainedSchema, mapJsonSchemaRefs, matchArrayableJsonSchema, resolveJsonSchemaRootLocalRef, visitJsonSchemaRefs };
 export type { JsonArraySchema, JsonFileSchema, JsonObjectSchema, JsonObjectSchemaEntry, JsonSchema, JsonSchemaConverter, JsonSchemaConverterDirection, JsonSchemaKeywords, SmartCoercionHandlerPluginOptions, SmartCoercionLinkPluginOptions };