diff --git a/README.md b/README.md index ad98e66..db4102d 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,3 @@ -> ## Next version is coming. -> -> This is the `next` version README document. -> -> If you wanna see the latest version, go to the [`v1.0` branch](https://github.com/samchon/openapi/tree/v1.0). - # `@samchon/openapi` ```mermaid flowchart @@ -18,12 +12,12 @@ flowchart lfc --"OpenAI"--> chatgpt("ChatGPT") lfc --"Anthropic"--> claude("Claude") lfc --"Google"--> gemini("Gemini") - lfc --"Meta (Facebook)"--> llama("Llama") + lfc --"Meta"--> llama("Llama") end ``` [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/openapi/blob/master/LICENSE) -[![npm version](https://img.shields.io/npm/v/@samchon/openapi/next.svg)](https://www.npmjs.com/package/@samchon/openapi/next.svg) +[![npm version](https://img.shields.io/npm/v/@samchon/openapi.svg)](https://www.npmjs.com/package/@samchon/openapi.svg) [![Downloads](https://img.shields.io/npm/dm/@samchon/openapi.svg)](https://www.npmjs.com/package/@samchon/openapi) [![Build Status](https://github.com/samchon/openapi/workflows/build/badge.svg)](https://github.com/samchon/openapi/actions?query=workflow%3Abuild) @@ -55,10 +49,10 @@ OpenAPI definitions, converters and LLM function calling application composer. ## Setup ```bash -npm install @samchon/openapi --tag next +npm install @samchon/openapi ``` -Just install by `npm i @samchon/openapi --tag next` command. +Just install by `npm i @samchon/openapi` command. Here is an example code utilizing the `@samchon/openapi` for LLM function calling purpose. @@ -213,7 +207,7 @@ flowchart TD lfc --"OpenAI"--> chatgpt("ChatGPT") lfc --"Anthropic"--> claude("Claude") lfc --"Google"--> gemini("Gemini") - lfc --"Meta (Facebook)"--> llama("Llama") + lfc --"Meta"--> llama("Llama") end ``` @@ -231,9 +225,9 @@ Let's enjoy the fantastic LLM function calling feature very easily with `@samcho - [`IHttpLlmFunction`](https://github.com/samchon/openapi/blob/master/src/structures/ILlmFunction.ts) - Schemas - [`IChatGptSchema`](https://github.com/samchon/openapi/blob/master/src/structures/IChatGptSchema.ts): OpenAI ChatGPT - - [`IClaudeSchema`](https://github.com/samchon/openapi/blob/master/src/structures/IClaudeSchema.ts): Anthropic Claude (same with [`ILlmSchemaV3_1`](https://github.com/samchon/openapi/blob/master/src/structures/ILlmSchemaV3_1.ts)) + - [`IClaudeSchema`](https://github.com/samchon/openapi/blob/master/src/structures/IClaudeSchema.ts): Anthropic Claude - [`IGeminiSchema`](https://github.com/samchon/openapi/blob/master/src/structures/IGeminiSchema.ts): Google Gemini - - [`ILlamaSchema`](https://github.com/samchon/openapi/blob/master/src/structures/ILlamaSchema.ts): Meta (Facebook) Llama (same with [`ILlmSchemaV3_1`](https://github.com/samchon/openapi/blob/master/src/structures/ILlmSchemaV3_1.ts)) + - [`ILlamaSchema`](https://github.com/samchon/openapi/blob/master/src/structures/ILlamaSchema.ts): Meta Llama - [`ILlmSchemaV3`](https://github.com/samchon/openapi/blob/master/src/structures/ILlmSchemaV3.ts): middle layer based on OpenAPI v3.0 specification - [`ILlmSchemaV3_1`](https://github.com/samchon/openapi/blob/master/src/structures/ILlmSchemaV3_1.ts): middle layer based on OpenAPI v3.1 specification - Type Checkers diff --git a/package.json b/package.json index 1b048d4..8883beb 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@samchon/openapi", - "version": "2.0.0-dev.20241202-2", + "version": "2.0.0", "description": "OpenAPI definitions and converters for 'typia' and 'nestia'.", "main": "./lib/index.js", "module": "./lib/index.mjs", diff --git a/src/structures/IOpenApiSchemaError.ts b/src/structures/IOpenApiSchemaError.ts index e9ced8c..6bb818b 100644 --- a/src/structures/IOpenApiSchemaError.ts +++ b/src/structures/IOpenApiSchemaError.ts @@ -1,14 +1,58 @@ import { OpenApi } from "../OpenApi"; +/** + * OpenAPI schema related error. + * + * `IOpenApiSchemaError` is a type representing an error that occured during the + * iteration or transformation of the OpenAPI schema (JSON schema) of + * {@link OpenApi.IJsonSchema} type. + * + * The most `IOpenApiSchemaError` is occured by the transformation process from + * {@link OpenApi.IJsonSchema} to {@link ILlmSchema} type. The transformation can + * be failed by following reasons: + * + * - Unable to find the {@link OpenApi.IJsonSchema.IReference} directing. + * - Non-supported type in LLM schema models + * - Every models do not support {@link OpenApi.IJsonSchema.ITuple} + * - Gemini does not support {@link OpenApi.IJsonSchema.IOneOf} + * - ChatGPT and Gemini do not support {@link OpenApi.IJsonSchema.IObject.additionalProperties} + * + * @author Jeongho Nam - https://github.com/samchon + */ export interface IOpenApiSchemaError { + /** + * Method that caused the error. + */ method: string; + + /** + * Message of the error. + */ message: string; + + /** + * The detailed reasons of the error. + */ reasons: IOpenApiSchemaError.IReason[]; } export namespace IOpenApiSchemaError { + /** + * Detailed reason of the error. + */ export interface IReason { + /** + * Schema that caused the error. + */ schema: OpenApi.IJsonSchema; + + /** + * Accessor to the schema. + */ accessor: string; + + /** + * Message of the reason. + */ message: string; } } diff --git a/src/typings/IResult.ts b/src/typings/IResult.ts index aaf9114..0274470 100644 --- a/src/typings/IResult.ts +++ b/src/typings/IResult.ts @@ -1,11 +1,46 @@ +/** + * Result of an operation that can either succeed or fail. + * + * `IResult` is an union type that represents the result of an operation + * that can either succeed or fail. + * + * You can distinguise the result by checking the {@link IResult.success} value, + * and if it's `true`, the success value is stored in {@link IResult.value}. + * Otherwise, if it's `false`, the error value is stored in {@link IResult.error}. + * + * @template T Type of the success value. + * @template E Type of the error value. + * @author Jeongho Nam - https://github.com/samchon + */ export type IResult = IResult.ISuccess | IResult.IFailure; export namespace IResult { + /** + * Success type of {@link IResult}. + */ export interface ISuccess { + /** + * Success flag. + */ success: true; + + /** + * Success value. + */ value: T; } + + /** + * Failure type of {@link IResult}. + */ export interface IFailure { + /** + * Success flag. + */ success: false; + + /** + * The error value. + */ error: E; } } diff --git a/src/utils/ChatGptTypeChecker.ts b/src/utils/ChatGptTypeChecker.ts index a7894ac..9391e20 100644 --- a/src/utils/ChatGptTypeChecker.ts +++ b/src/utils/ChatGptTypeChecker.ts @@ -5,11 +5,23 @@ export namespace ChatGptTypeChecker { /* ----------------------------------------------------------- TYPE CHECKERS ----------------------------------------------------------- */ + /** + * Test whether the schema is a nul type. + * + * @param schema Target schema + * @returns Whether null type or not + */ export const isNull = ( schema: IChatGptSchema, ): schema is IChatGptSchema.INull => (schema as IChatGptSchema.INull).type === "null"; + /** + * Test whether the schema is an unknown type. + * + * @param schema Target schema + * @returns Whether unknown type or not + */ export const isUnknown = ( schema: IChatGptSchema, ): schema is IChatGptSchema.IUnknown => @@ -17,41 +29,89 @@ export namespace ChatGptTypeChecker { !isAnyOf(schema) && !isReference(schema); + /** + * Test whether the schema is a boolean type. + * + * @param schema Target schema + * @returns Whether boolean type or not + */ export const isBoolean = ( schema: IChatGptSchema, ): schema is IChatGptSchema.IBoolean => (schema as IChatGptSchema.IBoolean).type === "boolean"; + /** + * Test whether the schema is an integer type. + * + * @param schema Target schema + * @returns Whether integer type or not + */ export const isInteger = ( schema: IChatGptSchema, ): schema is IChatGptSchema.IInteger => (schema as IChatGptSchema.IInteger).type === "integer"; + /** + * Test whether the schema is a number type. + * + * @param schema Target schema + * @returns Whether number type or not + */ export const isNumber = ( schema: IChatGptSchema, ): schema is IChatGptSchema.INumber => (schema as IChatGptSchema.INumber).type === "number"; + /** + * Test whether the schema is a string type. + * + * @param schema Target schema + * @returns Whether string type or not + */ export const isString = ( schema: IChatGptSchema, ): schema is IChatGptSchema.IString => (schema as IChatGptSchema.IString).type === "string"; + /** + * Test whether the schema is an array type. + * + * @param schema Target schema + * @returns Whether array type or not + */ export const isArray = ( schema: IChatGptSchema, ): schema is IChatGptSchema.IArray => (schema as IChatGptSchema.IArray).type === "array" && (schema as IChatGptSchema.IArray).items !== undefined; + /** + * Test whether the schema is an object type. + * + * @param schema Target schema + * @returns Whether object type or not + */ export const isObject = ( schema: IChatGptSchema, ): schema is IChatGptSchema.IObject => (schema as IChatGptSchema.IObject).type === "object"; + /** + * Test whether the schema is a reference type. + * + * @param schema Target schema + * @returns Whether reference type or not + */ export const isReference = ( schema: IChatGptSchema, ): schema is IChatGptSchema.IReference => (schema as any).$ref !== undefined; + /** + * Test whether the schema is an union type. + * + * @param schema Target schema + * @returns Whether union type or not + */ export const isAnyOf = ( schema: IChatGptSchema, ): schema is IChatGptSchema.IAnyOf => @@ -60,6 +120,20 @@ export namespace ChatGptTypeChecker { /* ----------------------------------------------------------- OPERATORS ----------------------------------------------------------- */ + /** + * Visit every nested schemas. + * + * Visit every nested schemas of the target, and apply the `props.closure` function. + * + * Here is the list of occuring nested visitings: + * + * - {@link IChatGptSchema.IAnyOf.anyOf} + * - {@link IChatGptSchema.IReference} + * - {@link IChatGptSchema.IObject.properties} + * - {@link IChatGptSchema.IArray.items} + * + * @param props Properties for visiting + */ export const visit = (props: { closure: (schema: IChatGptSchema, accessor: string) => void; $defs?: Record | undefined; @@ -88,6 +162,12 @@ export namespace ChatGptTypeChecker { next(props.schema, props.accessor ?? "$input.schemas"); }; + /** + * Test whether the `x` schema covers the `y` schema. + * + * @param props Properties for testing + * @returns Whether the `x` schema covers the `y` schema + */ export const covers = (props: { $defs?: Record | undefined; x: IChatGptSchema; diff --git a/src/utils/GeminiTypeChecker.ts b/src/utils/GeminiTypeChecker.ts index 44693a8..8ea7982 100644 --- a/src/utils/GeminiTypeChecker.ts +++ b/src/utils/GeminiTypeChecker.ts @@ -11,6 +11,18 @@ export namespace GeminiTypeChecker { /* ----------------------------------------------------------- OPERATORS ----------------------------------------------------------- */ + /** + * Visit every nested schemas. + * + * Visit every nested schemas of the target, and apply the `props.closure` function. + * + * Here is the list of occuring nested visitings: + * + * - {@link IGeminiSchema.IObject.properties} + * - {@link IGeminiSchema.IArray.items} + * + * @param props Properties for visiting + */ export const visit = (props: { closure: (schema: IGeminiSchema, accessor: string) => void; schema: IGeminiSchema; @@ -34,6 +46,12 @@ export namespace GeminiTypeChecker { }); }; + /** + * Test whether the `x` schema covers the `y` schema. + * + * @param props Properties for testing + * @returns Whether the `x` schema covers the `y` schema + */ export const covers = (x: IGeminiSchema, y: IGeminiSchema): boolean => { // CHECK EQUALITY if (x === y) return true; @@ -129,41 +147,98 @@ export namespace GeminiTypeChecker { /* ----------------------------------------------------------- TYPE CHECKERS ----------------------------------------------------------- */ + /** + * Test whether the schema is a boolean type. + * + * @param schema Target schema + * @returns Whether boolean type or not + */ export const isBoolean = ( schema: IGeminiSchema, ): schema is IGeminiSchema.IBoolean => (schema as IGeminiSchema.IBoolean).type === "boolean"; + /** + * Test whether the schema is an integer type. + * + * @param schema Target schema + * @returns Whether integer type or not + */ export const isInteger = ( schema: IGeminiSchema, ): schema is IGeminiSchema.IInteger => (schema as IGeminiSchema.IInteger).type === "integer"; + /** + * Test whether the schema is a number type. + * + * @param schema Target schema + * @returns Whether number type or not + */ export const isNumber = ( schema: IGeminiSchema, ): schema is IGeminiSchema.INumber => (schema as IGeminiSchema.INumber).type === "number"; + /** + * Test whether the schema is a string type. + * + * @param schema Target schema + * @returns Whether string type or not + */ export const isString = ( schema: IGeminiSchema, ): schema is IGeminiSchema.IString => (schema as IGeminiSchema.IString).type === "string"; + /** + * Test whether the schema is an array type. + * + * @param schema Target schema + * @returns Whether array type or not + */ export const isArray = ( schema: IGeminiSchema, ): schema is IGeminiSchema.IArray => (schema as IGeminiSchema.IArray).type === "array"; + /** + * Test whether the schema is an object type. + * + * @param schema Target schema + * @returns Whether object type or not + */ export const isObject = ( schema: IGeminiSchema, ): schema is IGeminiSchema.IObject => (schema as IGeminiSchema.IObject).type === "object"; + /** + * Test whether the schema is a null type. + * + * @param schema Target schema + * @returns Whether null type or not + */ export const isNullOnly = ( schema: IGeminiSchema, ): schema is IGeminiSchema.INullOnly => (schema as IGeminiSchema.INullOnly).type === "null"; + /** + * Test whether the schema is a nullable type. + * + * @param schema Target schema + * @returns Whether nullable type or not + */ + export const isNullable = (schema: IGeminiSchema): boolean => + !isUnknown(schema) && (isNullOnly(schema) || schema.nullable === true); + + /** + * Test whether the schema is an unknown type. + * + * @param schema Target schema + * @returns Whether unknown type or not + */ export const isUnknown = ( schema: IGeminiSchema, ): schema is IGeminiSchema.IUnknown => diff --git a/src/utils/LlmTypeCheckerV3.ts b/src/utils/LlmTypeCheckerV3.ts index 40b49e7..3290989 100644 --- a/src/utils/LlmTypeCheckerV3.ts +++ b/src/utils/LlmTypeCheckerV3.ts @@ -14,15 +14,15 @@ export namespace LlmTypeCheckerV3 { /** * Visit every nested schemas. * - * Visit every nested schemas of the target, and apply the callback function - * to them. + * Visit every nested schemas of the target, and apply the `props.closure` function. * - * If the visitor meets an union type, it will visit every individual schemas - * in the union type. Otherwise meets an object type, it will visit every - * properties and additional properties. If the visitor meets an array type, - * it will visit the item type. + * Here is the list of occuring nested visitings: * - * @param props Target and callback function + * - {@link ILlmSchemaV3.IOneOf.oneOf} + * - {@link ILlmSchemaV3.IObject.additionalProperties} + * - {@link ILlmSchemaV3.IArray.items} + * + * @param props Properties for visiting */ export const visit = (props: { closure: (schema: ILlmSchemaV3, accessor: string) => void; diff --git a/src/utils/LlmTypeCheckerV3_1.ts b/src/utils/LlmTypeCheckerV3_1.ts index 93a7ab6..69fb9da 100644 --- a/src/utils/LlmTypeCheckerV3_1.ts +++ b/src/utils/LlmTypeCheckerV3_1.ts @@ -5,58 +5,133 @@ export namespace LlmTypeCheckerV3_1 { /* ----------------------------------------------------------- TYPE CHECKERS ----------------------------------------------------------- */ + /** + * Test whether the schema is a nul type. + * + * @param schema Target schema + * @returns Whether null type or not + */ export const isNull = ( schema: ILlmSchemaV3_1, ): schema is ILlmSchemaV3_1.INull => OpenApiTypeCheckerBase.isNull(schema); + /** + * Test whether the schema is an unknown type. + * + * @param schema Target schema + * @returns Whether unknown type or not + */ export const isUnknown = ( schema: ILlmSchemaV3_1, ): schema is ILlmSchemaV3_1.IUnknown => OpenApiTypeCheckerBase.isUnknown(schema); + /** + * Test whether the schema is a constant type. + * + * @param schema Target schema + * @returns Whether constant type or not + */ export const isConstant = ( schema: ILlmSchemaV3_1, ): schema is ILlmSchemaV3_1.IConstant => OpenApiTypeCheckerBase.isConstant(schema); + /** + * Test whether the schema is a boolean type. + * + * @param schema Target schema + * @returns Whether boolean type or not + */ export const isBoolean = ( schema: ILlmSchemaV3_1, ): schema is ILlmSchemaV3_1.IBoolean => OpenApiTypeCheckerBase.isBoolean(schema); + /** + * Test whether the schema is an integer type. + * + * @param schema Target schema + * @returns Whether integer type or not + */ export const isInteger = ( schema: ILlmSchemaV3_1, ): schema is ILlmSchemaV3_1.IInteger => OpenApiTypeCheckerBase.isInteger(schema); + /** + * Test whether the schema is a number type. + * + * @param schema Target schema + * @returns Whether number type or not + */ export const isNumber = ( schema: ILlmSchemaV3_1, ): schema is ILlmSchemaV3_1.INumber => OpenApiTypeCheckerBase.isNumber(schema); + /** + * Test whether the schema is a string type. + * + * @param schema Target schema + * @returns Whether string type or not + */ export const isString = ( schema: ILlmSchemaV3_1, ): schema is ILlmSchemaV3_1.IString => OpenApiTypeCheckerBase.isString(schema); + /** + * Test whether the schema is an array type. + * + * @param schema Target schema + * @returns Whether array type or not + */ export const isArray = ( schema: ILlmSchemaV3_1, ): schema is ILlmSchemaV3_1.IArray => OpenApiTypeCheckerBase.isArray(schema); + /** + * Test whether the schema is an object type. + * + * @param schema Target schema + * @returns Whether object type or not + */ export const isObject = ( schema: ILlmSchemaV3_1, ): schema is ILlmSchemaV3_1.IObject => OpenApiTypeCheckerBase.isObject(schema); + /** + * Test whether the schema is a reference type. + * + * @param schema Target schema + * @returns Whether reference type or not + */ export const isReference = ( schema: ILlmSchemaV3_1, ): schema is ILlmSchemaV3_1.IReference => OpenApiTypeCheckerBase.isReference(schema); + /** + * Test whether the schema is an union type. + * + * @param schema Target schema + * @returns Whether union type or not + */ export const isOneOf = ( schema: ILlmSchemaV3_1, ): schema is ILlmSchemaV3_1.IOneOf => OpenApiTypeCheckerBase.isOneOf(schema); + /** + * Test whether the schema is recursive reference type. + * + * Test whether the target schema is a reference type, and test one thign more + * that the reference is self-recursive or not. + * + * @param props Properties for recursive reference test + * @returns Whether the schema is recursive reference type or not + */ export const isRecursiveReference = (props: { $defs?: Record; schema: ILlmSchemaV3_1; @@ -72,6 +147,12 @@ export namespace LlmTypeCheckerV3_1 { /* ----------------------------------------------------------- OPERATORS ----------------------------------------------------------- */ + /** + * Test whether the `x` schema covers the `y` schema. + * + * @param props Properties for testing + * @returns Whether the `x` schema covers the `y` schema + */ export const covers = (props: { $defs?: Record; x: ILlmSchemaV3_1; @@ -86,6 +167,21 @@ export namespace LlmTypeCheckerV3_1 { y: props.y, }); + /** + * Visit every nested schemas. + * + * Visit every nested schemas of the target, and apply the `props.closure` function. + * + * Here is the list of occuring nested visitings: + * + * - {@link ILlmSchemaV3_1.IOneOf.oneOf} + * - {@link ILlmSchemaV3_1.IReference} + * - {@link ILlmSchemaV3_1.IObject.properties} + * - {@link ILlmSchemaV3_1.IObject.additionalProperties} + * - {@link ILlmSchemaV3_1.IArray.items} + * + * @param props Properties for visiting + */ export const visit = (props: { closure: (schema: ILlmSchemaV3_1, accessor: string) => void; $defs?: Record; diff --git a/src/utils/OpenApiTypeChecker.ts b/src/utils/OpenApiTypeChecker.ts index c79fc83..681c82d 100644 --- a/src/utils/OpenApiTypeChecker.ts +++ b/src/utils/OpenApiTypeChecker.ts @@ -3,70 +3,158 @@ import { IOpenApiSchemaError } from "../structures/IOpenApiSchemaError"; import { IResult } from "../typings/IResult"; import { OpenApiTypeCheckerBase } from "./internal/OpenApiTypeCheckerBase"; +/** + * Type checker of OpenAPI type schema. + * + * `OpenApiTypeChecker` is a type checker of {@link OpenApi.IJsonSchema}. + * + * @author Jeongho Nam - https://github.com/samchon + */ export namespace OpenApiTypeChecker { /* ----------------------------------------------------------- TYPE CHECKERS ----------------------------------------------------------- */ + /** + * Test whether the schema is a nul type. + * + * @param schema Target schema + * @returns Whether null type or not + */ export const isNull = ( schema: OpenApi.IJsonSchema, ): schema is OpenApi.IJsonSchema.INull => OpenApiTypeCheckerBase.isNull(schema); + /** + * Test whether the schema is an unknown type. + * + * @param schema Target schema + * @returns Whether unknown type or not + */ export const isUnknown = ( schema: OpenApi.IJsonSchema, ): schema is OpenApi.IJsonSchema.IUnknown => OpenApiTypeCheckerBase.isUnknown(schema); + /** + * Test whether the schema is a constant type. + * + * @param schema Target schema + * @returns Whether constant type or not + */ export const isConstant = ( schema: OpenApi.IJsonSchema, ): schema is OpenApi.IJsonSchema.IConstant => OpenApiTypeCheckerBase.isConstant(schema); + /** + * Test whether the schema is a boolean type. + * + * @param schema Target schema + * @returns Whether boolean type or not + */ export const isBoolean = ( schema: OpenApi.IJsonSchema, ): schema is OpenApi.IJsonSchema.IBoolean => OpenApiTypeCheckerBase.isBoolean(schema); + /** + * Test whether the schema is an integer type. + * + * @param schema Target schema + * @returns Whether integer type or not + */ export const isInteger = ( schema: OpenApi.IJsonSchema, ): schema is OpenApi.IJsonSchema.IInteger => OpenApiTypeCheckerBase.isInteger(schema); + /** + * Test whether the schema is a number type. + * + * @param schema Target schema + * @returns Whether number type or not + */ export const isNumber = ( schema: OpenApi.IJsonSchema, ): schema is OpenApi.IJsonSchema.INumber => OpenApiTypeCheckerBase.isNumber(schema); + /** + * Test whether the schema is a string type. + * + * @param schema Target schema + * @returns Whether string type or not + */ export const isString = ( schema: OpenApi.IJsonSchema, ): schema is OpenApi.IJsonSchema.IString => OpenApiTypeCheckerBase.isString(schema); + /** + * Test whether the schema is an array type. + * + * @param schema Target schema + * @returns Whether array type or not + */ export const isArray = ( schema: OpenApi.IJsonSchema, ): schema is OpenApi.IJsonSchema.IArray => OpenApiTypeCheckerBase.isArray(schema); + /** + * Test whether the schema is a tuple type. + * + * @param schema Target schema + * @returns Whether tuple type or not + */ export const isTuple = ( schema: OpenApi.IJsonSchema, ): schema is OpenApi.IJsonSchema.ITuple => OpenApiTypeCheckerBase.isTuple(schema); + /** + * Test whether the schema is an object type. + * + * @param schema Target schema + * @returns Whether object type or not + */ export const isObject = ( schema: OpenApi.IJsonSchema, ): schema is OpenApi.IJsonSchema.IObject => OpenApiTypeCheckerBase.isObject(schema); + /** + * Test whether the schema is a reference type. + * + * @param schema Target schema + * @returns Whether reference type or not + */ export const isReference = ( schema: OpenApi.IJsonSchema, ): schema is OpenApi.IJsonSchema.IReference => OpenApiTypeCheckerBase.isReference(schema); + /** + * Test whether the schema is an union type. + * + * @param schema Target schema + * @returns Whether union type or not + */ export const isOneOf = ( schema: OpenApi.IJsonSchema, ): schema is OpenApi.IJsonSchema.IOneOf => OpenApiTypeCheckerBase.isOneOf(schema); + /** + * Test whether the schema is recursive reference type. + * + * Test whether the target schema is a reference type, and test one thign more + * that the reference is self-recursive or not. + * + * @param props Properties for recursive reference test + * @returns Whether the schema is recursive reference type or not + */ export const isRecursiveReference = (props: { components: OpenApi.IComponents; schema: OpenApi.IJsonSchema; @@ -80,6 +168,24 @@ export namespace OpenApiTypeChecker { /* ----------------------------------------------------------- OPERATORS ----------------------------------------------------------- */ + /** + * Escape from the {@link OpenApi.IJsonSchema.IReference} type. + * + * Escape from the {@link OpenApi.IJsonSchema.IReference} type, replacing the + * every references to the actual schemas. If the escape is successfull, the returned + * schema never contains any {@link OpenApi.IJsonSchema.IReference} type in its + * structure. + * + * If the schema has a recursive reference, the recursive reference would be repeated + * as much as the `props.recursive` depth. If you've configured the `props.recursive` + * as `false` or `0`, it would be failed and return an {@link IOpenApiSchemaError}. + * Also, if there's a {@link OpenApi.IJsonSchema.IReference} type which cannot find + * the matched type in the {@link OpenApi.IComponents.schemas}, it would also be failed + * and return an {@link IOpenApiSchemaError} either. + * + * @param props Properties for escaping + * @returns Escaped schema, or error with reason + */ export const escape = (props: { components: OpenApi.IComponents; schema: OpenApi.IJsonSchema; @@ -93,6 +199,21 @@ export namespace OpenApiTypeChecker { method: "OpenApiTypeChecker.method", }); + /** + * Unreference the schema. + * + * Unreference the schema, replacing the {@link OpenApi.IJsonSchema.IReference} type + * to the actual schema. Different with {@link escape} is, the `unreference` function + * does not resolve every references in the schema, but resolve only one time. + * + * If there's a {@link OpenApi.IJsonSchema.IReference} type which cannot find + * the matched type in the {@link OpenApi.IComponents.schemas}, and you've called this + * `unreference()` function with the reference, it would also be failed and return an + * {@link IOpenApiSchemaError} value. + * + * @param props Properties of unreference + * @returns Unreferenced schema + */ export const unreference = (props: { components: OpenApi.IComponents; schema: OpenApi.IJsonSchema; @@ -105,6 +226,23 @@ export namespace OpenApiTypeChecker { method: "OpenApiTypeChecker.unreference", }); + /** + * Visit every nested schemas. + * + * Visit every nested schemas of the target, and apply the `props.closure` function. + * + * Here is the list of occuring nested visitings: + * + * - {@link OpenApi.IJsonSchema.IOneOf.oneOf} + * - {@link OpenApi.IJsonSchema.IReference} + * - {@link OpenApi.IJsonSchema.IObject.properties} + * - {@link OpenApi.IJsonSchema.IObject.additionalProperties} + * - {@link OpenApi.IJsonSchema.IArray.items} + * - {@link OpenApi.IJsonSchema.ITuple.prefixItems} + * - {@link OpenApi.IJsonSchema.ITuple.additionalItems} + * + * @param props Properties for visiting + */ export const visit = (props: { closure: (schema: OpenApi.IJsonSchema, accessor: string) => void; components: OpenApi.IComponents; @@ -117,6 +255,12 @@ export namespace OpenApiTypeChecker { prefix: "#/components/schemas/", }); + /** + * Test whether the `x` schema covers the `y` schema. + * + * @param props Properties for testing + * @returns Whether the `x` schema covers the `y` schema + */ export const covers = (props: { components: OpenApi.IComponents; x: OpenApi.IJsonSchema;