@typia/utils 12.0.0-dev.20260309 → 12.0.0-dev.20260311

package/src/validators/OpenApiTypeChecker.ts

@@ -1,297 +1,297 @@
-import { IJsonSchemaTransformError, IResult, OpenApi } from "@typia/interface";
-
-import { OpenApiTypeCheckerBase } from "../utils/internal/OpenApiTypeCheckerBase";
-
-/**
- * Type checker for emended OpenAPI v3.1 JSON schemas.
- *
- * `OpenApiTypeChecker` provides type guard functions for
- * {@link OpenApi.IJsonSchema} (typia's normalized OpenAPI format). Use these to
- * narrow schema types before accessing type-specific properties.
- *
- * Type checkers:
- *
- * - Primitives: {@link isNull}, {@link isBoolean}, {@link isInteger},
- *   {@link isNumber}, {@link isString}
- * - Constants: {@link isConstant}
- * - Collections: {@link isArray}, {@link isTuple}, {@link isObject}
- * - Composition: {@link isOneOf}, {@link isReference}
- * - Special: {@link isUnknown}
- *
- * Also provides schema operations:
- *
- * - {@link visit}: Traverse and transform schemas recursively
- * - {@link covers}: Check if one schema subsumes another
- * - {@link escape}: Unwrap reference schemas
- *
- * For other OpenAPI versions, use {@link OpenApiV3TypeChecker},
- * {@link OpenApiV3_1TypeChecker}, or {@link SwaggerV2TypeChecker}.
- *
- * @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 thing 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;
-  }): boolean =>
-    OpenApiTypeCheckerBase.isRecursiveReference({
-      prefix: "#/components/schemas/",
-      components: props.components,
-      schema: props.schema,
-    });
-
-  /* -----------------------------------------------------------
-    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 successful, 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 IJsonSchemaTransformError}. 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 IJsonSchemaTransformError} either.
-   *
-   * @param props Properties for escaping
-   * @returns Escaped schema, or error with reason
-   */
-  export const escape = (props: {
-    components: OpenApi.IComponents;
-    schema: OpenApi.IJsonSchema;
-    recursive: false | number;
-    accessor?: string;
-    refAccessor?: string;
-  }): IResult<OpenApi.IJsonSchema, IJsonSchemaTransformError> =>
-    OpenApiTypeCheckerBase.escape({
-      ...props,
-      prefix: "#/components/schemas/",
-      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 IJsonSchemaTransformError} value.
-   *
-   * @param props Properties of unreference
-   * @returns Unreferenced schema
-   */
-  export const unreference = (props: {
-    components: OpenApi.IComponents;
-    schema: OpenApi.IJsonSchema;
-    accessor?: string;
-    refAccessor?: string;
-  }): IResult<OpenApi.IJsonSchema, IJsonSchemaTransformError> =>
-    OpenApiTypeCheckerBase.unreference({
-      ...props,
-      prefix: "#/components/schemas/",
-      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 occurring 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;
-    schema: OpenApi.IJsonSchema;
-    accessor?: string;
-    refAccessor?: string;
-  }): void =>
-    OpenApiTypeCheckerBase.visit({
-      ...props,
-      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;
-    y: OpenApi.IJsonSchema;
-  }): boolean =>
-    OpenApiTypeCheckerBase.covers({
-      prefix: "#/components/schemas/",
-      components: props.components,
-      x: props.x,
-      y: props.y,
-    });
-}
+import { IJsonSchemaTransformError, IResult, OpenApi } from "@typia/interface";
+
+import { OpenApiTypeCheckerBase } from "../utils/internal/OpenApiTypeCheckerBase";
+
+/**
+ * Type checker for emended OpenAPI v3.1 JSON schemas.
+ *
+ * `OpenApiTypeChecker` provides type guard functions for
+ * {@link OpenApi.IJsonSchema} (typia's normalized OpenAPI format). Use these to
+ * narrow schema types before accessing type-specific properties.
+ *
+ * Type checkers:
+ *
+ * - Primitives: {@link isNull}, {@link isBoolean}, {@link isInteger},
+ *   {@link isNumber}, {@link isString}
+ * - Constants: {@link isConstant}
+ * - Collections: {@link isArray}, {@link isTuple}, {@link isObject}
+ * - Composition: {@link isOneOf}, {@link isReference}
+ * - Special: {@link isUnknown}
+ *
+ * Also provides schema operations:
+ *
+ * - {@link visit}: Traverse and transform schemas recursively
+ * - {@link covers}: Check if one schema subsumes another
+ * - {@link escape}: Unwrap reference schemas
+ *
+ * For other OpenAPI versions, use {@link OpenApiV3TypeChecker},
+ * {@link OpenApiV3_1TypeChecker}, or {@link SwaggerV2TypeChecker}.
+ *
+ * @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 thing 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;
+  }): boolean =>
+    OpenApiTypeCheckerBase.isRecursiveReference({
+      prefix: "#/components/schemas/",
+      components: props.components,
+      schema: props.schema,
+    });
+
+  /* -----------------------------------------------------------
+    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 successful, 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 IJsonSchemaTransformError}. 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 IJsonSchemaTransformError} either.
+   *
+   * @param props Properties for escaping
+   * @returns Escaped schema, or error with reason
+   */
+  export const escape = (props: {
+    components: OpenApi.IComponents;
+    schema: OpenApi.IJsonSchema;
+    recursive: false | number;
+    accessor?: string;
+    refAccessor?: string;
+  }): IResult<OpenApi.IJsonSchema, IJsonSchemaTransformError> =>
+    OpenApiTypeCheckerBase.escape({
+      ...props,
+      prefix: "#/components/schemas/",
+      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 IJsonSchemaTransformError} value.
+   *
+   * @param props Properties of unreference
+   * @returns Unreferenced schema
+   */
+  export const unreference = (props: {
+    components: OpenApi.IComponents;
+    schema: OpenApi.IJsonSchema;
+    accessor?: string;
+    refAccessor?: string;
+  }): IResult<OpenApi.IJsonSchema, IJsonSchemaTransformError> =>
+    OpenApiTypeCheckerBase.unreference({
+      ...props,
+      prefix: "#/components/schemas/",
+      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 occurring 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;
+    schema: OpenApi.IJsonSchema;
+    accessor?: string;
+    refAccessor?: string;
+  }): void =>
+    OpenApiTypeCheckerBase.visit({
+      ...props,
+      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;
+    y: OpenApi.IJsonSchema;
+  }): boolean =>
+    OpenApiTypeCheckerBase.covers({
+      prefix: "#/components/schemas/",
+      components: props.components,
+      x: props.x,
+      y: props.y,
+    });
+}