@typia/utils 12.0.0-dev.20260225

package/src/converters/OpenApiConverter.ts

@@ -0,0 +1,285 @@
+import { OpenApi, OpenApiV3, OpenApiV3_1, SwaggerV2 } from "@typia/interface";
+
+import { OpenApiV3Downgrader } from "./internal/OpenApiV3Downgrader";
+import { OpenApiV3Upgrader } from "./internal/OpenApiV3Upgrader";
+import { OpenApiV3_1Upgrader } from "./internal/OpenApiV3_1Upgrader";
+import { SwaggerV2Downgrader } from "./internal/SwaggerV2Downgrader";
+import { SwaggerV2Upgrader } from "./internal/SwaggerV2Upgrader";
+
+/**
+ * OpenAPI version converter.
+ *
+ * `OpenApiConverter` converts between different OpenAPI specification versions:
+ * Swagger v2.0, OpenAPI v3.0, OpenAPI v3.1, and typia's emended {@link OpenApi}
+ * format. Also converts individual components (schemas, operations, paths).
+ *
+ * Upgrade path (to emended v3.1):
+ *
+ * - Swagger v2.0 → emended v3.1
+ * - OpenAPI v3.0 → emended v3.1
+ * - OpenAPI v3.1 → emended v3.1
+ *
+ * Downgrade path (from emended v3.1):
+ *
+ * - Emended v3.1 → Swagger v2.0
+ * - Emended v3.1 → OpenAPI v3.0
+ *
+ * The emended format normalizes ambiguous expressions: dereferences `$ref`,
+ * merges `allOf`, converts `nullable` to union types, etc.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace OpenApiConverter {
+  /* -----------------------------------------------------------
+    DOCUMENTS
+  ----------------------------------------------------------- */
+  /**
+   * Upgrade document to typia's emended OpenAPI v3.1 format.
+   *
+   * @param document Source document (Swagger v2.0, OpenAPI v3.0/v3.1)
+   * @returns Emended OpenAPI v3.1 document
+   */
+  export function upgradeDocument(
+    document:
+      | SwaggerV2.IDocument
+      | OpenApiV3.IDocument
+      | OpenApiV3_1.IDocument
+      | OpenApi.IDocument,
+  ): OpenApi.IDocument {
+    if (isUpgraded(document)) return document;
+    else if (is_v31(document)) return OpenApiV3_1Upgrader.convert(document);
+    else if (is_v30(document)) return OpenApiV3Upgrader.convert(document);
+    else if (is_v20(document)) return SwaggerV2Upgrader.convert(document);
+    document satisfies never;
+    throw new Error("Invalid OpenAPI document");
+  }
+
+  /**
+   * Downgrade document to Swagger v2.0 format.
+   *
+   * @param document Source emended OpenAPI document
+   * @param version Target version "2.0"
+   * @returns Swagger v2.0 document
+   */
+  export function downgradeDocument(
+    document: OpenApi.IDocument,
+    version: "2.0",
+  ): SwaggerV2.IDocument;
+
+  /**
+   * Downgrade document to OpenAPI v3.0 format.
+   *
+   * @param document Source emended OpenAPI document
+   * @param version Target version "3.0"
+   * @returns OpenAPI v3.0 document
+   */
+  export function downgradeDocument(
+    document: OpenApi.IDocument,
+    version: "3.0",
+  ): OpenApiV3.IDocument;
+
+  /** @internal */
+  export function downgradeDocument(
+    document: OpenApi.IDocument,
+    version: "2.0" | "3.0",
+  ): SwaggerV2.IDocument | OpenApiV3.IDocument {
+    if (version === "2.0") return SwaggerV2Downgrader.downgrade(document);
+    else if (version === "3.0") return OpenApiV3Downgrader.downgrade(document);
+    version satisfies never;
+    throw new Error("Invalid OpenAPI version");
+  }
+
+  /* -----------------------------------------------------------
+    COMPONENTS
+  ----------------------------------------------------------- */
+  /**
+   * Upgrade components to typia's emended format.
+   *
+   * @param input Source components (Swagger v2.0, OpenAPI v3.0/v3.1)
+   * @returns Emended OpenAPI components
+   */
+  export function upgradeComponents(
+    input:
+      | OpenApiV3_1.IComponents
+      | OpenApiV3.IComponents
+      | SwaggerV2.IDocument,
+  ): OpenApi.IComponents {
+    if (is_v20(input)) return SwaggerV2Upgrader.convertComponents(input);
+    return OpenApiV3_1Upgrader.convertComponents(input);
+  }
+
+  /**
+   * Downgrade components to Swagger v2.0 definitions.
+   *
+   * @param input Source emended components
+   * @param version Target version "2.0"
+   * @returns Swagger v2.0 definitions record
+   */
+  export function downgradeComponents(
+    input: OpenApi.IComponents,
+    version: "2.0",
+  ): Record<string, SwaggerV2.IJsonSchema>;
+
+  /**
+   * Downgrade components to OpenAPI v3.0 format.
+   *
+   * @param input Source emended components
+   * @param version Target version "3.0"
+   * @returns OpenAPI v3.0 components
+   */
+  export function downgradeComponents(
+    input: OpenApi.IComponents,
+    version: "3.0",
+  ): OpenApiV3.IComponents;
+
+  /** @internal */
+  export function downgradeComponents(
+    input: OpenApi.IComponents,
+    version: "2.0" | "3.0",
+  ): Record<string, SwaggerV2.IJsonSchema> | OpenApiV3.IComponents {
+    if (version === "2.0")
+      return SwaggerV2Downgrader.downgradeComponents(input).downgraded;
+    return OpenApiV3Downgrader.downgradeComponents(input).downgraded;
+  }
+
+  /* -----------------------------------------------------------
+    SCHEMAS
+  ----------------------------------------------------------- */
+  /**
+   * Upgrade Swagger v2.0 schema to emended format.
+   *
+   * @param props.definitions Swagger v2.0 definitions
+   * @param props.schema Schema to upgrade
+   * @returns Emended JSON schema
+   */
+  export function upgradeSchema(props: {
+    definitions: Record<string, SwaggerV2.IJsonSchema>;
+    schema: SwaggerV2.IJsonSchema;
+  }): OpenApi.IJsonSchema;
+
+  /**
+   * Upgrade OpenAPI v3.0 schema to emended format.
+   *
+   * @param props.components OpenAPI v3.0 components
+   * @param props.schema Schema to upgrade
+   * @returns Emended JSON schema
+   */
+  export function upgradeSchema(props: {
+    components: OpenApiV3.IComponents;
+    schema: OpenApiV3.IJsonSchema;
+  }): OpenApi.IJsonSchema;
+
+  /**
+   * Upgrade OpenAPI v3.1 schema to emended format.
+   *
+   * @param props.components OpenAPI v3.1 components
+   * @param props.schema Schema to upgrade
+   * @returns Emended JSON schema
+   */
+  export function upgradeSchema(props: {
+    components: OpenApiV3_1.IComponents;
+    schema: OpenApiV3_1.IJsonSchema;
+  }): OpenApi.IJsonSchema;
+
+  /** @internal */
+  export function upgradeSchema(
+    props:
+      | {
+          definitions: Record<string, SwaggerV2.IJsonSchema>;
+          schema: SwaggerV2.IJsonSchema;
+        }
+      | {
+          components: OpenApiV3.IComponents;
+          schema: OpenApiV3.IJsonSchema;
+        }
+      | {
+          components: OpenApiV3_1.IComponents;
+          schema: OpenApiV3_1.IJsonSchema;
+        },
+  ): OpenApi.IJsonSchema {
+    if ("definitions" in props)
+      return SwaggerV2Upgrader.convertSchema(props.definitions)(props.schema);
+    return OpenApiV3_1Upgrader.convertSchema(props.components)(props.schema);
+  }
+
+  /**
+   * Downgrade schema to Swagger v2.0 format.
+   *
+   * @param props.components Source emended components
+   * @param props.schema Schema to downgrade
+   * @param props.version Target version "2.0"
+   * @param props.downgraded Target definitions record (mutated)
+   * @returns Swagger v2.0 schema
+   */
+  export function downgradeSchema(props: {
+    components: OpenApi.IComponents;
+    schema: OpenApi.IJsonSchema;
+    version: "2.0";
+    downgraded: Record<string, SwaggerV2.IJsonSchema>;
+  }): SwaggerV2.IJsonSchema;
+
+  /**
+   * Downgrade schema to OpenAPI v3.0 format.
+   *
+   * @param props.components Source emended components
+   * @param props.schema Schema to downgrade
+   * @param props.version Target version "3.0"
+   * @param props.downgraded Target components (mutated)
+   * @returns OpenAPI v3.0 schema
+   */
+  export function downgradeSchema(props: {
+    components: OpenApi.IComponents;
+    schema: OpenApi.IJsonSchema;
+    version: "3.0";
+    downgraded: OpenApiV3.IComponents;
+  }): OpenApiV3.IJsonSchema;
+
+  /** @internal */
+  export function downgradeSchema<Version extends "2.0" | "3.0">(props: {
+    components: OpenApi.IComponents;
+    schema: OpenApi.IJsonSchema;
+    version: Version;
+    downgraded: Version extends "2.0"
+      ? Record<string, SwaggerV2.IJsonSchema>
+      : OpenApiV3.IComponents;
+  }): OpenApiV3.IJsonSchema | SwaggerV2.IJsonSchema {
+    if (props.version === "2.0")
+      return SwaggerV2Downgrader.downgradeSchema({
+        original: props.components,
+        downgraded: props.downgraded as Record<string, SwaggerV2.IJsonSchema>,
+      })(props.schema);
+    return OpenApiV3Downgrader.downgradeSchema({
+      original: props.components,
+      downgraded: props.downgraded,
+    })(props.schema);
+  }
+}
+
+const is_v20 = (input: unknown): input is SwaggerV2.IDocument =>
+  typeof input === "object" &&
+  input !== null &&
+  "swagger" in input &&
+  typeof input.swagger === "string" &&
+  input.swagger.startsWith("2.0");
+
+const is_v30 = (input: unknown): input is OpenApiV3.IDocument =>
+  typeof input === "object" &&
+  input !== null &&
+  "openapi" in input &&
+  typeof input.openapi === "string" &&
+  input.openapi.startsWith("3.0");
+
+const is_v31 = (input: unknown): input is OpenApiV3_1.IDocument =>
+  typeof input === "object" &&
+  input !== null &&
+  "openapi" in input &&
+  typeof input.openapi === "string" &&
+  input.openapi.startsWith("3.1");
+
+const isUpgraded = (input: unknown): input is OpenApi.IDocument =>
+  typeof input === "object" &&
+  input !== null &&
+  "openapi" in input &&
+  typeof input.openapi === "string" &&
+  input.openapi.startsWith("3.1") &&
+  (input as OpenApi.IDocument)["x-samchon-emended-v4"] === true;

package/src/converters/index.ts

@@ -0,0 +1,5 @@
+export * from "./LlmSchemaConverter";
+export * from "./OpenApiConverter";
+
+/** @internal */
+export * from "./internal/OpenApiExclusiveEmender";

package/src/converters/internal/LlmDescriptionInverter.ts

@@ -0,0 +1,178 @@
+import { OpenApi } from "@typia/interface";
+
+import { OpenApiExclusiveEmender } from "./OpenApiExclusiveEmender";
+
+export namespace LlmDescriptionInverter {
+  export const numeric = (
+    description: string | undefined,
+  ): Pick<
+    OpenApi.IJsonSchema.INumber,
+    | "minimum"
+    | "maximum"
+    | "exclusiveMinimum"
+    | "exclusiveMaximum"
+    | "multipleOf"
+    | "description"
+  > => {
+    if (description === undefined) return {};
+
+    const lines: string[] = description.split("\n");
+    return OpenApiExclusiveEmender.emend({
+      minimum: find({
+        type: "number",
+        name: "minimum",
+        lines,
+      }),
+      maximum: find({
+        type: "number",
+        name: "maximum",
+        lines,
+      }),
+      exclusiveMinimum: find({
+        type: "number",
+        name: "exclusiveMinimum",
+        lines,
+      }),
+      exclusiveMaximum: find({
+        type: "number",
+        name: "exclusiveMaximum",
+        lines,
+      }),
+      multipleOf: find({
+        type: "number",
+        name: "multipleOf",
+        lines,
+      }),
+      description: describe(lines, [
+        "minimum",
+        "maximum",
+        "exclusiveMinimum",
+        "exclusiveMaximum",
+        "multipleOf",
+      ]),
+    });
+  };
+
+  export const string = (
+    description: string | undefined,
+  ): Pick<
+    OpenApi.IJsonSchema.IString,
+    | "format"
+    | "pattern"
+    | "contentMediaType"
+    | "minLength"
+    | "maxLength"
+    | "description"
+  > => {
+    if (description === undefined) return {};
+
+    const lines: string[] = description.split("\n");
+    return {
+      format: find({
+        type: "string",
+        name: "format",
+        lines,
+      }),
+      pattern: find({
+        type: "string",
+        name: "pattern",
+        lines,
+      }),
+      contentMediaType: find({
+        type: "string",
+        name: "contentMediaType",
+        lines,
+      }),
+      minLength: find({
+        type: "number",
+        name: "minLength",
+        lines,
+      }),
+      maxLength: find({
+        type: "number",
+        name: "maxLength",
+        lines,
+      }),
+      description: describe(lines, [
+        "format",
+        "pattern",
+        "contentMediaType",
+        "minLength",
+        "maxLength",
+      ]),
+    };
+  };
+
+  export const array = (
+    description: string | undefined,
+  ): Pick<
+    OpenApi.IJsonSchema.IArray,
+    "minItems" | "maxItems" | "uniqueItems" | "description"
+  > => {
+    if (description === undefined) return {};
+
+    const lines: string[] = description.split("\n");
+    return {
+      minItems: find({
+        type: "number",
+        name: "minItems",
+        lines,
+      }),
+      maxItems: find({
+        type: "number",
+        name: "maxItems",
+        lines,
+      }),
+      uniqueItems: find({
+        type: "boolean",
+        name: "uniqueItems",
+        lines,
+      }),
+      description: describe(lines, ["minItems", "maxItems", "uniqueItems"]),
+    };
+  };
+
+  const find = <Type extends "boolean" | "number" | "string">(props: {
+    type: Type;
+    name: string;
+    lines: string[];
+  }):
+    | (Type extends "boolean" ? true : Type extends "number" ? number : string)
+    | undefined => {
+    if (props.type === "boolean")
+      return props.lines.some((line) => line.startsWith(`@${props.name}`))
+        ? (true as any)
+        : (undefined as any);
+    for (const line of props.lines) {
+      if (line.startsWith(`@${props.name} `) === false) continue;
+      const value: string = line.replace(`@${props.name} `, "").trim();
+      if (props.type === "number")
+        return (isNaN(Number(value)) ? undefined : Number(value)) satisfies
+          | number
+          | undefined as any;
+      return value as any;
+    }
+    return undefined as any;
+  };
+
+  const describe = (lines: string[], tags: string[]): string | undefined => {
+    const ret: string = trimArray(
+      lines
+        .map((str) => str.trim())
+        .filter((str) =>
+          tags.every((tag) => str.startsWith(`@${tag}`) === false),
+        ),
+    ).join("\n");
+    return ret.length === 0 ? undefined : ret;
+  };
+
+  const trimArray = (array: string[]): string[] => {
+    let first: number = 0;
+    let last: number = array.length - 1;
+
+    for (; first < array.length; ++first)
+      if (array[first]!.trim().length !== 0) break;
+    for (; last >= 0; --last) if (array[last]!.trim().length !== 0) break;
+    return array.slice(first, last + 1);
+  };
+}

package/src/converters/internal/LlmParametersComposer.ts

@@ -0,0 +1,52 @@
+import { IJsonSchemaTransformError, IResult, OpenApi } from "@typia/interface";
+
+import { OpenApiTypeChecker } from "../../validators/OpenApiTypeChecker";
+
+/** @internal */
+export namespace LlmParametersFinder {
+  export const parameters = (props: {
+    components: OpenApi.IComponents;
+    schema: OpenApi.IJsonSchema.IObject | OpenApi.IJsonSchema.IReference;
+    method: string;
+    accessor?: string;
+    refAccessor?: string;
+  }): IResult<OpenApi.IJsonSchema.IObject, IJsonSchemaTransformError> => {
+    const entity: IResult<OpenApi.IJsonSchema, IJsonSchemaTransformError> =
+      OpenApiTypeChecker.unreference(props);
+    if (entity.success === false) return entity;
+    else if (OpenApiTypeChecker.isObject(entity.value) === false)
+      return reportError({
+        ...props,
+        message: "LLM only accepts object type as parameters.",
+      });
+    else if (!!entity.value.additionalProperties)
+      return reportError({
+        ...props,
+        message: "LLM does not allow additional properties on parameters.",
+      });
+    return {
+      success: true,
+      value: entity.value,
+    };
+  };
+
+  const reportError = (props: {
+    method: string;
+    message: string;
+    schema: OpenApi.IJsonSchema;
+    accessor?: string;
+  }): IResult.IFailure<IJsonSchemaTransformError> => ({
+    success: false,
+    error: {
+      method: props.method,
+      message: `failed to compose LLM schema.`,
+      reasons: [
+        {
+          schema: props.schema,
+          message: props.message,
+          accessor: props.accessor ?? "$input.schema",
+        },
+      ],
+    },
+  });
+}

package/src/converters/internal/OpenApiConstraintShifter.ts

@@ -0,0 +1,154 @@
+import { OpenApi } from "@typia/interface";
+
+import { OpenApiExclusiveEmender } from "./OpenApiExclusiveEmender";
+
+export namespace OpenApiConstraintShifter {
+  export const shiftArray = <
+    Schema extends Pick<
+      OpenApi.IJsonSchema.IArray,
+      "description" | "minItems" | "maxItems" | "uniqueItems"
+    >,
+  >(
+    schema: Schema,
+  ): Omit<Schema, "minItems" | "maxItems" | "uniqueItems"> => {
+    const tags: string[] = [];
+    if (schema.minItems !== undefined) {
+      tags.push(`@minItems ${schema.minItems}`);
+      delete schema.minItems;
+    }
+    if (schema.maxItems !== undefined) {
+      tags.push(`@maxItems ${schema.maxItems}`);
+      delete schema.maxItems;
+    }
+    if (schema.uniqueItems !== undefined) {
+      if (schema.uniqueItems === true) tags.push(`@uniqueItems`);
+      delete schema.uniqueItems;
+    }
+    schema.description = writeTagWithDescription({
+      description: schema.description,
+      tags,
+    });
+    return schema;
+  };
+
+  export const shiftNumeric = <
+    Schema extends Pick<
+      OpenApi.IJsonSchema.INumber | OpenApi.IJsonSchema.IInteger,
+      | "description"
+      | "minimum"
+      | "maximum"
+      | "exclusiveMinimum"
+      | "exclusiveMaximum"
+      | "multipleOf"
+      | "default"
+    >,
+  >(
+    schema: Schema,
+  ): Omit<
+    Schema,
+    | "minimum"
+    | "maximum"
+    | "exclusiveMinimum"
+    | "exclusiveMaximum"
+    | "multipleOf"
+    | "default"
+  > => {
+    Object.assign(schema, OpenApiExclusiveEmender.emend(schema));
+
+    const tags: string[] = [];
+    if (schema.minimum !== undefined) {
+      tags.push(`@minimum ${schema.minimum}`);
+      delete schema.minimum;
+    }
+    if (schema.maximum !== undefined) {
+      tags.push(`@maximum ${schema.maximum}`);
+      delete schema.maximum;
+    }
+    if (schema.exclusiveMinimum !== undefined) {
+      tags.push(`@exclusiveMinimum ${schema.exclusiveMinimum}`);
+      delete schema.exclusiveMinimum;
+    }
+    if (schema.exclusiveMaximum !== undefined) {
+      tags.push(`@exclusiveMaximum ${schema.exclusiveMaximum}`);
+      delete schema.exclusiveMaximum;
+    }
+    if (schema.multipleOf !== undefined) {
+      tags.push(`@multipleOf ${schema.multipleOf}`);
+      delete schema.multipleOf;
+    }
+    schema.description = writeTagWithDescription({
+      description: schema.description,
+      tags,
+    });
+    if (schema.default !== undefined) {
+      tags.push(`@default ${schema.default}`);
+      delete schema.default;
+    }
+    return schema;
+  };
+
+  export const shiftString = <
+    Schema extends Pick<
+      OpenApi.IJsonSchema.IString,
+      | "description"
+      | "minLength"
+      | "maxLength"
+      | "format"
+      | "pattern"
+      | "contentMediaType"
+      | "default"
+    >,
+  >(
+    schema: Schema,
+  ): Omit<
+    Schema,
+    | "minLength"
+    | "maxLength"
+    | "format"
+    | "pattern"
+    | "contentMediaType"
+    | "default"
+  > => {
+    const tags: string[] = [];
+    if (schema.minLength !== undefined) {
+      tags.push(`@minLength ${schema.minLength}`);
+      delete schema.minLength;
+    }
+    if (schema.maxLength !== undefined) {
+      tags.push(`@maxLength ${schema.maxLength}`);
+      delete schema.maxLength;
+    }
+    if (schema.format !== undefined) {
+      tags.push(`@format ${schema.format}`);
+      delete schema.format;
+    }
+    if (schema.pattern !== undefined) {
+      tags.push(`@pattern ${schema.pattern}`);
+      delete schema.pattern;
+    }
+    if (schema.contentMediaType !== undefined) {
+      tags.push(`@contentMediaType ${schema.contentMediaType}`);
+      delete schema.contentMediaType;
+    }
+    if (schema.default !== undefined) {
+      tags.push(`@default ${schema.default}`);
+      delete schema.default;
+    }
+    schema.description = writeTagWithDescription({
+      description: schema.description,
+      tags,
+    });
+    return schema;
+  };
+}
+
+const writeTagWithDescription = (props: {
+  description: string | undefined;
+  tags: string[];
+}): string | undefined => {
+  if (props.tags.length === 0) return props.description;
+  return [
+    ...(props.description?.length ? [props.description, "\n"] : []),
+    ...props.tags,
+  ].join("\n");
+};