@typia/utils 12.0.0-dev.20260312 → 12.0.0-dev.20260312-2

package/src/converters/OpenApiConverter.ts

@@ -8,6 +8,7 @@ import {
 
 import { OpenApiV3Downgrader } from "./internal/OpenApiV3Downgrader";
 import { OpenApiV3Upgrader } from "./internal/OpenApiV3Upgrader";
+import { OpenApiV3_1Downgrader } from "./internal/OpenApiV3_1Downgrader";
 import { OpenApiV3_1Upgrader } from "./internal/OpenApiV3_1Upgrader";
 import { OpenApiV3_2Upgrader } from "./internal/OpenApiV3_2Upgrader";
 import { SwaggerV2Downgrader } from "./internal/SwaggerV2Downgrader";
@@ -32,6 +33,7 @@ import { SwaggerV2Upgrader } from "./internal/SwaggerV2Upgrader";
  *
  * - Emended v3.2 → Swagger v2.0
  * - Emended v3.2 → OpenAPI v3.0
+ * - Emended v3.2 → OpenAPI v3.1
  *
  * The emended format normalizes ambiguous expressions: dereferences `$ref`,
  * merges `allOf`, converts `nullable` to union types, etc.
@@ -89,13 +91,21 @@ export namespace OpenApiConverter {
     version: "3.0",
   ): OpenApiV3.IDocument;
 
+  export function downgradeDocument(
+    document: OpenApi.IDocument,
+    version: "3.1",
+  ): OpenApiV3_1.IDocument;
+
   /** @internal */
   export function downgradeDocument(
     document: OpenApi.IDocument,
-    version: "2.0" | "3.0",
-  ): SwaggerV2.IDocument | OpenApiV3.IDocument {
+    version: "2.0" | "3.0" | "3.1",
+  ): SwaggerV2.IDocument | OpenApiV3.IDocument | OpenApiV3_1.IDocument {
     if (version === "2.0") return SwaggerV2Downgrader.downgrade(document);
     else if (version === "3.0") return OpenApiV3Downgrader.downgrade(document);
+    else if (version === "3.1")
+      return OpenApiV3_1Downgrader.downgrade(document);
+
     version satisfies never;
     throw new Error("Invalid OpenAPI version");
   }
@@ -144,13 +154,30 @@ export namespace OpenApiConverter {
     version: "3.0",
   ): OpenApiV3.IComponents;
 
+  /**
+   * Downgrade components to OpenAPI v3.1 format.
+   *
+   * @param input Source emended components
+   * @param version Target version "3.1"
+   * @returns OpenAPI v3.1 components
+   */
+  export function downgradeComponents(
+    input: OpenApi.IComponents,
+    version: "3.1",
+  ): OpenApiV3_1.IComponents;
+
   /** @internal */
   export function downgradeComponents(
     input: OpenApi.IComponents,
-    version: "2.0" | "3.0",
-  ): Record<string, SwaggerV2.IJsonSchema> | OpenApiV3.IComponents {
+    version: "2.0" | "3.0" | "3.1",
+  ):
+    | Record<string, SwaggerV2.IJsonSchema>
+    | OpenApiV3.IComponents
+    | OpenApiV3_1.IComponents {
     if (version === "2.0")
       return SwaggerV2Downgrader.downgradeComponents(input).downgraded;
+    if (version === "3.1")
+      return OpenApiV3_1Downgrader.downgradeComponents(input).downgraded;
     return OpenApiV3Downgrader.downgradeComponents(input).downgraded;
   }
 
@@ -264,23 +291,49 @@ export namespace OpenApiConverter {
     downgraded: OpenApiV3.IComponents;
   }): OpenApiV3.IJsonSchema;
 
+  /**
+   * Downgrade schema to OpenAPI v3.1 format.
+   *
+   * @param props.components Source emended components
+   * @param props.schema Schema to downgrade
+   * @param props.version Target version "3.1"
+   * @param props.downgraded Target components (mutated)
+   * @returns OpenAPI v3.1 schema
+   */
+  export function downgradeSchema(props: {
+    components: OpenApi.IComponents;
+    schema: OpenApi.IJsonSchema;
+    version: "3.1";
+    downgraded: OpenApiV3_1.IComponents;
+  }): OpenApiV3_1.IJsonSchema;
+
   /** @internal */
-  export function downgradeSchema<Version extends "2.0" | "3.0">(props: {
+  export function downgradeSchema<Version extends "2.0" | "3.0" | "3.1">(props: {
     components: OpenApi.IComponents;
     schema: OpenApi.IJsonSchema;
     version: Version;
     downgraded: Version extends "2.0"
       ? Record<string, SwaggerV2.IJsonSchema>
-      : OpenApiV3.IComponents;
-  }): OpenApiV3.IJsonSchema | SwaggerV2.IJsonSchema {
+      : Version extends "3.1"
+        ? OpenApiV3_1.IComponents
+        : OpenApiV3.IComponents;
+  }):
+    | OpenApiV3.IJsonSchema
+    | OpenApiV3_1.IJsonSchema
+    | SwaggerV2.IJsonSchema {
     if (props.version === "2.0")
       return SwaggerV2Downgrader.downgradeSchema({
         original: props.components,
         downgraded: props.downgraded as Record<string, SwaggerV2.IJsonSchema>,
       })(props.schema);
+    if (props.version === "3.1")
+      return OpenApiV3_1Downgrader.downgradeSchema({
+        original: props.components,
+        downgraded: props.downgraded as OpenApiV3_1.IComponents,
+      })(props.schema);
     return OpenApiV3Downgrader.downgradeSchema({
       original: props.components,
-      downgraded: props.downgraded,
+      downgraded: props.downgraded as OpenApiV3.IComponents,
     })(props.schema);
   }
 }

package/src/converters/internal/OpenApiV3_1Downgrader.ts

@@ -0,0 +1,318 @@
+import { OpenApi, OpenApiV3_1 } from "@typia/interface";
+
+import { OpenApiTypeChecker } from "../../validators/OpenApiTypeChecker";
+
+export namespace OpenApiV3_1Downgrader {
+  export interface IComponentsCollection {
+    original: OpenApi.IComponents;
+    downgraded: OpenApiV3_1.IComponents;
+  }
+
+  export const downgrade = (input: OpenApi.IDocument): OpenApiV3_1.IDocument => {
+    const collection: IComponentsCollection = downgradeComponents(
+      input.components,
+    );
+    return {
+      openapi: "3.1.0",
+      servers: input.servers,
+      info: input.info,
+      components: collection.downgraded,
+      paths: input.paths
+        ? Object.fromEntries(
+            Object.entries(input.paths)
+              .filter(([_, v]) => v !== undefined)
+              .map(
+                ([key, value]) =>
+                  [key, downgradePathItem(collection)(value)] as const,
+              ),
+          )
+        : undefined,
+      webhooks: input.webhooks
+        ? Object.fromEntries(
+            Object.entries(input.webhooks)
+              .filter(([_, v]) => v !== undefined)
+              .map(
+                ([key, value]) =>
+                  [key, downgradePathItem(collection)(value)] as const,
+              ),
+          )
+        : undefined,
+      security: input.security,
+      tags: input.tags,
+    };
+  };
+
+  /* -----------------------------------------------------------
+    OPERATORS
+  ----------------------------------------------------------- */
+  const downgradePathItem =
+    (collection: IComponentsCollection) =>
+    (pathItem: OpenApi.IPath): OpenApiV3_1.IPath => {
+      // Collect non-standard operations for x-additionalOperations
+      const xAdditionalOperations: Record<string, OpenApiV3_1.IOperation> = {};
+
+      // query method goes to x-additionalOperations
+      if (pathItem.query) {
+        xAdditionalOperations["query"] = downgradeOperation(collection)(pathItem.query);
+      }
+
+      // additionalOperations also go to x-additionalOperations
+      if (pathItem.additionalOperations) {
+        for (const [key, value] of Object.entries(pathItem.additionalOperations)) {
+          if (value !== undefined) {
+            xAdditionalOperations[key] = downgradeOperation(collection)(value);
+          }
+        }
+      }
+
+      return {
+        ...(pathItem as any),
+        ...(pathItem.get
+          ? { get: downgradeOperation(collection)(pathItem.get) }
+          : undefined),
+        ...(pathItem.put
+          ? { put: downgradeOperation(collection)(pathItem.put) }
+          : undefined),
+        ...(pathItem.post
+          ? { post: downgradeOperation(collection)(pathItem.post) }
+          : undefined),
+        ...(pathItem.delete
+          ? { delete: downgradeOperation(collection)(pathItem.delete) }
+          : undefined),
+        ...(pathItem.options
+          ? { options: downgradeOperation(collection)(pathItem.options) }
+          : undefined),
+        ...(pathItem.head
+          ? { head: downgradeOperation(collection)(pathItem.head) }
+          : undefined),
+        ...(pathItem.patch
+          ? { patch: downgradeOperation(collection)(pathItem.patch) }
+          : undefined),
+        ...(pathItem.trace
+          ? { trace: downgradeOperation(collection)(pathItem.trace) }
+          : undefined),
+        ...(Object.keys(xAdditionalOperations).length > 0
+          ? { "x-additionalOperations": xAdditionalOperations }
+          : undefined),
+        // Remove v3.2-only properties from spread
+        query: undefined,
+        additionalOperations: undefined,
+      };
+    };
+
+  const downgradeOperation =
+    (collection: IComponentsCollection) =>
+    (input: OpenApi.IOperation): OpenApiV3_1.IOperation => ({
+      ...input,
+      parameters: input.parameters
+        ? input.parameters.map(downgradeParameter(collection))
+        : undefined,
+      requestBody: input.requestBody
+        ? downgradeRequestBody(collection)(input.requestBody)
+        : undefined,
+      responses: input.responses
+        ? Object.fromEntries(
+            Object.entries(input.responses)
+              .filter(([_, v]) => v !== undefined)
+              .map(([key, value]) => [
+                key,
+                downgradeResponse(collection)(value),
+              ]),
+          )
+        : undefined,
+    });
+
+  const downgradeParameter =
+    (collection: IComponentsCollection) =>
+    (
+      input: OpenApi.IOperation.IParameter,
+    ): OpenApiV3_1.IOperation.IParameter => ({
+      ...input,
+      in: input.in === "querystring" ? "query" : input.in,
+      schema: downgradeSchema(collection)(input.schema),
+    });
+
+  const downgradeRequestBody =
+    (collection: IComponentsCollection) =>
+    (
+      input: OpenApi.IOperation.IRequestBody,
+    ): OpenApiV3_1.IOperation.IRequestBody => ({
+      ...input,
+      content: input.content
+        ? downgradeContent(collection)(input.content)
+        : undefined,
+    });
+
+  const downgradeResponse =
+    (collection: IComponentsCollection) =>
+    (input: OpenApi.IOperation.IResponse): OpenApiV3_1.IOperation.IResponse => ({
+      ...input,
+      content: input.content
+        ? downgradeContent(collection)(input.content)
+        : undefined,
+      headers: input.headers
+        ? Object.fromEntries(
+            Object.entries(input.headers)
+              .filter(([_, v]) => v !== undefined)
+              .map(([key, value]) => [
+                key,
+                {
+                  ...value,
+                  schema: downgradeSchema(collection)(value.schema),
+                },
+              ]),
+          )
+        : undefined,
+    });
+
+  const downgradeContent =
+    (collection: IComponentsCollection) =>
+    (
+      record: OpenApi.IOperation.IContent,
+    ): Record<string, OpenApiV3_1.IOperation.IMediaType> =>
+      Object.fromEntries(
+        Object.entries(record)
+          .filter(([_, v]) => v !== undefined)
+          .map(
+            ([key, value]) =>
+              [
+                key,
+                {
+                  ...value,
+                  schema: value?.schema
+                    ? downgradeSchema(collection)(value.schema)
+                    : undefined,
+                  // itemSchema is v3.2-only, remove it
+                  itemSchema: undefined,
+                },
+              ] as const,
+          ),
+      );
+
+  /* -----------------------------------------------------------
+    DEFINITIONS
+  ----------------------------------------------------------- */
+  export const downgradeComponents = (
+    input: OpenApi.IComponents,
+  ): IComponentsCollection => {
+    const collection: IComponentsCollection = {
+      original: input,
+      downgraded: {
+        securitySchemes: input.securitySchemes
+          ? downgradeSecuritySchemes(input.securitySchemes)
+          : undefined,
+      },
+    };
+    if (input.schemas) {
+      collection.downgraded.schemas = {};
+      for (const [key, value] of Object.entries(input.schemas))
+        if (value !== undefined)
+          collection.downgraded.schemas[key] =
+            downgradeSchema(collection)(value);
+    }
+    return collection;
+  };
+
+  export const downgradeSchema =
+    (collection: IComponentsCollection) =>
+    (input: OpenApi.IJsonSchema): OpenApiV3_1.IJsonSchema => {
+      const union: OpenApiV3_1.IJsonSchema[] = [];
+      const attribute: OpenApiV3_1.IJsonSchema.__IAttribute = {
+        title: input.title,
+        description: input.description,
+        deprecated: input.deprecated,
+        readOnly: input.readOnly,
+        writeOnly: input.writeOnly,
+        example: input.example,
+        examples: input.examples,
+        ...Object.fromEntries(
+          Object.entries(input).filter(
+            ([key, value]) => key.startsWith("x-") && value !== undefined,
+          ),
+        ),
+      };
+      const visit = (schema: OpenApi.IJsonSchema): void => {
+        if (OpenApiTypeChecker.isNull(schema))
+          union.push({ type: "null" });
+        else if (OpenApiTypeChecker.isConstant(schema))
+          union.push({ const: schema.const });
+        else if (
+          OpenApiTypeChecker.isBoolean(schema) ||
+          OpenApiTypeChecker.isInteger(schema) ||
+          OpenApiTypeChecker.isNumber(schema) ||
+          OpenApiTypeChecker.isString(schema) ||
+          OpenApiTypeChecker.isReference(schema)
+        )
+          union.push({ ...schema });
+        else if (OpenApiTypeChecker.isArray(schema))
+          union.push({
+            ...schema,
+            items: downgradeSchema(collection)(schema.items),
+          });
+        else if (OpenApiTypeChecker.isTuple(schema))
+          union.push({
+            ...schema,
+            prefixItems: schema.prefixItems.map(
+              downgradeSchema(collection),
+            ),
+            additionalItems:
+              typeof schema.additionalItems === "object"
+                ? downgradeSchema(collection)(schema.additionalItems)
+                : schema.additionalItems,
+          });
+        else if (OpenApiTypeChecker.isObject(schema))
+          union.push({
+            ...schema,
+            properties: schema.properties
+              ? Object.fromEntries(
+                  Object.entries(schema.properties)
+                    .filter(([_, v]) => v !== undefined)
+                    .map(([key, value]) => [
+                      key,
+                      downgradeSchema(collection)(value),
+                    ]),
+                )
+              : undefined,
+            additionalProperties:
+              typeof schema.additionalProperties === "object"
+                ? downgradeSchema(collection)(schema.additionalProperties)
+                : schema.additionalProperties,
+            required: schema.required,
+          });
+        else if (OpenApiTypeChecker.isOneOf(schema))
+          schema.oneOf.forEach(visit);
+      };
+      visit(input);
+      return {
+        ...(union.length === 0
+          ? { type: undefined }
+          : union.length === 1
+            ? { ...union[0] }
+            : { oneOf: union }),
+        ...attribute,
+      };
+    };
+
+  const downgradeSecuritySchemes = (
+    input: Record<string, OpenApi.ISecurityScheme>,
+  ): Record<string, OpenApiV3_1.ISecurityScheme> =>
+    Object.fromEntries(
+      Object.entries(input)
+        .filter(([_, v]) => v !== undefined)
+        .map(([key, value]) => [key, downgradeSecurityScheme(value)]),
+    );
+
+  const downgradeSecurityScheme = (
+    input: OpenApi.ISecurityScheme,
+  ): OpenApiV3_1.ISecurityScheme => {
+    if (input.type === "oauth2") {
+      const { deviceAuthorization: _, ...flows } = input.flows;
+      return {
+        type: "oauth2",
+        flows,
+        description: input.description,
+      };
+    }
+    return { ...input } as OpenApiV3_1.ISecurityScheme;
+  };
+}