Merge pull request #100 from samchon/feat/result

Completed v2 publishing

Author: samchon

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

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",

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;
   }
 }

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<T, E> = IResult.ISuccess<T> | IResult.IFailure<E>;
 export namespace IResult {
+  /**
+   * Success type of {@link IResult}.
+   */
   export interface ISuccess<T> {
+    /**
+     * Success flag.
+     */
     success: true;
+
+    /**
+     * Success value.
+     */
     value: T;
   }
+
+  /**
+   * Failure type of {@link IResult}.
+   */
   export interface IFailure<E> {
+    /**
+     * Success flag.
+     */
     success: false;
+
+    /**
+     * The error value.
+     */
     error: E;
   }
 }

src/utils/ChatGptTypeChecker.ts

@@ -5,53 +5,113 @@ 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 =>
     (schema as IChatGptSchema.IUnknown).type === undefined &&
     !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<string, IChatGptSchema> | 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<string, IChatGptSchema> | undefined;
     x: IChatGptSchema;