@skmtc/core 0.29.0 → 0.31.0

package/script/parse/v3-2/mediaType/toMediaTypeItemV3.js

@@ -0,0 +1,381 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toOptionalMediaTypeItemsV3 = exports.toMediaTypeItemsV3 = exports.toMediaTypeItemV3 = void 0;
+const toSchemasV3_js_1 = require("../schema/toSchemasV3.js");
+const toExamplesV3_js_1 = require("../example/toExamplesV3.js");
+const MediaType_js_1 = require("../../../oas/mediaType/MediaType.js");
+const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const refFns_js_1 = require("../../../helpers/refFns.js");
+const JsonPointer_js_1 = require("../../../types/JsonPointer.js");
+/**
+ * Transforms an OpenAPI v3 media type object into an internal OAS media type representation.
+ *
+ * This function processes OpenAPI v3 MediaType objects, extracting schema definitions,
+ * examples, encoding information, and specification extensions. It creates a structured
+ * internal representation that can be used by the SKMTC pipeline for code generation
+ * and validation.
+ *
+ * The transformation handles all standard OpenAPI v3 MediaType properties including
+ * schema references, inline schemas, examples, encoding specifications, and custom
+ * extension fields that begin with 'x-'.
+ *
+ * @param args - Transformation arguments
+ * @param args.mediaTypeItem - The OpenAPI v3 media type object to process
+ * @param args.mediaType - The media type identifier (MIME type)
+ * @param args.context - Parsing context for tracing and error handling
+ * @returns Structured OAS media type object for internal processing
+ *
+ * @example Transforming JSON media type
+ * ```typescript
+ * import { toMediaTypeItemV3 } from '@skmtc/core/oas/mediaType';
+ *
+ * const jsonMediaType = {
+ *   schema: {
+ *     type: 'object',
+ *     properties: {
+ *       name: { type: 'string' },
+ *       email: { type: 'string', format: 'email' }
+ *     }
+ *   },
+ *   example: {
+ *     name: 'John Doe',
+ *     email: 'john@example.com'
+ *   }
+ * };
+ *
+ * const result = toMediaTypeItemV3({
+ *   mediaTypeItem: jsonMediaType,
+ *   mediaType: 'application/json',
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.mediaType); // 'application/json'
+ * console.log(result.schema); // Processed schema object
+ * ```
+ *
+ * @example Processing form data with encoding
+ * ```typescript
+ * const formMediaType = {
+ *   schema: {
+ *     type: 'object',
+ *     properties: {
+ *       file: { type: 'string', format: 'binary' },
+ *       metadata: { type: 'string' }
+ *     }
+ *   },
+ *   encoding: {
+ *     file: {
+ *       contentType: 'image/png',
+ *       headers: {
+ *         'X-Rate-Limit': {
+ *           schema: { type: 'integer' }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * const result = toMediaTypeItemV3({
+ *   mediaTypeItem: formMediaType,
+ *   mediaType: 'multipart/form-data',
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.encoding); // Processed encoding configuration
+ * ```
+ *
+ * @example Handling multiple examples
+ * ```typescript
+ * const mediaTypeWithExamples = {
+ *   schema: { type: 'string' },
+ *   examples: {
+ *     success: {
+ *       summary: 'Successful response',
+ *       value: 'Operation completed'
+ *     },
+ *     error: {
+ *       summary: 'Error response',
+ *       value: 'Operation failed'
+ *     }
+ *   }
+ * };
+ *
+ * const result = toMediaTypeItemV3({
+ *   mediaTypeItem: mediaTypeWithExamples,
+ *   mediaType: 'text/plain',
+ *   context: parseContext
+ * });
+ *
+ * console.log(Object.keys(result.examples)); // ['success', 'error']
+ * ```
+ */
+const toMediaTypeItemV3 = ({ mediaTypeItem, mediaType, stackTrail, context }) => {
+    const { schema, itemSchema, example, examples, encoding, prefixEncoding, itemEncoding, ...skipped } = mediaTypeItem;
+    const extensionFields = (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({
+        skipped,
+        parent: mediaTypeItem,
+        context,
+        stackTrail,
+        parentType: 'mediaType'
+    });
+    if (encoding !== undefined && (prefixEncoding !== undefined || itemEncoding !== undefined)) {
+        context.logIssue({
+            key: 'encoding',
+            level: 'warning',
+            message: `'encoding' must not be present together with 'prefixEncoding' or 'itemEncoding' in ${mediaType}`,
+            parent: mediaTypeItem,
+            stackTrail,
+            type: 'UNEXPECTED_PROPERTY'
+        });
+    }
+    const fields = {
+        mediaType,
+        encoding,
+        prefixEncoding,
+        itemEncoding,
+        schema: stackTrail.trace('schema', st => (0, toSchemasV3_js_1.toOptionalSchemaV3)({ schema, stackTrail: st, context })),
+        itemSchema: stackTrail.trace('itemSchema', st => (0, toSchemasV3_js_1.toOptionalSchemaV3)({ schema: itemSchema, stackTrail: st, context })),
+        examples: stackTrail.trace('examples', st => (0, toExamplesV3_js_1.toExamplesV3)({
+            example,
+            examples,
+            exampleKey: mediaType,
+            stackTrail: st,
+            context
+        })),
+        extensionFields
+    };
+    return context.withStackTrail(stackTrail, () => new MediaType_js_1.OasMediaType(fields, context));
+};
+exports.toMediaTypeItemV3 = toMediaTypeItemV3;
+/**
+ * Transforms multiple OpenAPI v3 media type objects into internal OAS representations.
+ *
+ * This function processes a complete content map from OpenAPI v3, transforming each
+ * media type entry into its internal OAS representation. It's commonly used to process
+ * the `content` property of request bodies, responses, and parameters that support
+ * multiple media types.
+ *
+ * The function maintains the original media type keys while transforming the values
+ * into structured OAS media type objects. Each transformation is traced for debugging
+ * and error tracking purposes.
+ *
+ * @param args - Transformation arguments
+ * @param args.content - Map of media types to OpenAPI MediaType objects
+ * @param args.context - Parsing context for tracing and error handling
+ * @returns Map of media type strings to processed OAS media type objects
+ *
+ * @example Processing multiple content types
+ * ```typescript
+ * import { toMediaTypeItemsV3 } from '@skmtc/core/oas/mediaType';
+ *
+ * const content = {
+ *   'application/json': {
+ *     schema: {
+ *       type: 'object',
+ *       properties: { message: { type: 'string' } }
+ *     }
+ *   },
+ *   'application/xml': {
+ *     schema: {
+ *       type: 'string'
+ *     }
+ *   },
+ *   'text/plain': {
+ *     schema: {
+ *       type: 'string'
+ *     },
+ *     example: 'Plain text response'
+ *   }
+ * };
+ *
+ * const result = toMediaTypeItemsV3({
+ *   content,
+ *   context: parseContext
+ * });
+ *
+ * console.log(Object.keys(result)); // ['application/json', 'application/xml', 'text/plain']
+ * console.log(result['application/json'].mediaType); // 'application/json'
+ * ```
+ *
+ * @example Processing request body content types
+ * ```typescript
+ * const requestBodyContent = {
+ *   'application/json': {
+ *     schema: { $ref: '#/components/schemas/CreateUserRequest' }
+ *   },
+ *   'application/x-www-form-urlencoded': {
+ *     schema: {
+ *       type: 'object',
+ *       properties: {
+ *         name: { type: 'string' },
+ *         email: { type: 'string' }
+ *       }
+ *     },
+ *     encoding: {
+ *       email: {
+ *         style: 'form',
+ *         explode: false
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * const processed = toMediaTypeItemsV3({
+ *   content: requestBodyContent,
+ *   context: parseContext
+ * });
+ *
+ * // Each media type is processed with its specific configuration
+ * console.log(processed['application/json'].schema); // Reference object
+ * console.log(processed['application/x-www-form-urlencoded'].encoding); // Form encoding config
+ * ```
+ */
+const toMediaTypeItemsV3 = ({ content, stackTrail, context }) => {
+    const output = {};
+    const entries = Object.entries(content);
+    for (const [mediaType, value] of entries) {
+        // A `$ref` is replaced by the Media Type Object it names, so a
+        // referenced media type parses exactly like an inline one.
+        const mediaTypeItem = (0, refFns_js_1.isRef)(value) ? toComponentMediaType({ $ref: value.$ref, context }) : value;
+        if (mediaTypeItem === undefined) {
+            context.logIssue({
+                key: mediaType,
+                level: 'error',
+                message: `Reference ${JSON.stringify(value)} does not resolve to an entry in components.mediaTypes; dropping '${mediaType}'`,
+                parent: value,
+                stackTrail,
+                type: 'INVALID_DEPENDENCY_REF'
+            });
+            continue;
+        }
+        output[mediaType] = stackTrail.trace(mediaType, st => (0, exports.toMediaTypeItemV3)({ mediaTypeItem, mediaType, stackTrail: st, context }));
+    }
+    return output;
+};
+exports.toMediaTypeItemsV3 = toMediaTypeItemsV3;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isMediaTypeObject = (value) => isRecord(value) && !(0, refFns_js_1.isRef)(value);
+/**
+ * The Media Type Object a `$ref` names in `components.mediaTypes`, read off
+ * the raw document. An entry that is itself a `$ref` is followed. `undefined`
+ * when a `$ref` on the chain points elsewhere or names a missing entry, or
+ * when the chain is a cycle.
+ */
+const toComponentMediaType = ({ $ref, context, visited = new Set() }) => {
+    const segments = $ref.startsWith('#') ? (0, JsonPointer_js_1.fromJsonPointer)($ref) : undefined;
+    if (segments?.length !== 3 || segments[0] !== 'components' || segments[1] !== 'mediaTypes') {
+        return undefined;
+    }
+    const [, , name] = segments;
+    if (visited.has(name)) {
+        return undefined;
+    }
+    const { components } = context.documentObject;
+    const mediaTypes = isRecord(components) ? components.mediaTypes : undefined;
+    if (!isRecord(mediaTypes) || !Object.hasOwn(mediaTypes, name)) {
+        return undefined;
+    }
+    const mediaTypeItem = mediaTypes[name];
+    if ((0, refFns_js_1.isRef)(mediaTypeItem)) {
+        return toComponentMediaType({
+            $ref: mediaTypeItem.$ref,
+            context,
+            visited: new Set([...visited, name])
+        });
+    }
+    return isMediaTypeObject(mediaTypeItem) ? mediaTypeItem : undefined;
+};
+/**
+ * Optionally transforms OpenAPI v3 media type objects when content is provided.
+ *
+ * This function provides a safe way to process media type content that may or may not
+ * be present in the OpenAPI specification. It handles the common pattern where content
+ * properties are optional in OpenAPI objects (like responses without bodies or
+ * operations without request bodies).
+ *
+ * When content is undefined, the function returns undefined without processing.
+ * When content is provided, it delegates to `toMediaTypeItemsV3` for full processing.
+ *
+ * @param args - Transformation arguments
+ * @param args.content - Optional map of media types to OpenAPI MediaType objects
+ * @param args.context - Parsing context for tracing and error handling
+ * @returns Map of processed media types if content exists, undefined otherwise
+ *
+ * @example Handling optional response content
+ * ```typescript
+ * import { toOptionalMediaTypeItemsV3 } from '@skmtc/core/oas/mediaType';
+ *
+ * // Response with content
+ * const responseWithContent = {
+ *   description: 'Successful response',
+ *   content: {
+ *     'application/json': {
+ *       schema: { type: 'object' }
+ *     }
+ *   }
+ * };
+ *
+ * const withContent = toOptionalMediaTypeItemsV3({
+ *   content: responseWithContent.content,
+ *   context: parseContext
+ * });
+ * console.log(withContent); // { 'application/json': OasMediaType }
+ *
+ * // Response without content (like 204 No Content)
+ * const responseNoContent = {
+ *   description: 'No content response'
+ * };
+ *
+ * const noContent = toOptionalMediaTypeItemsV3({
+ *   content: responseNoContent.content, // undefined
+ *   context: parseContext
+ * });
+ * console.log(noContent); // undefined
+ * ```
+ *
+ * @example Processing operations with optional request bodies
+ * ```typescript
+ * function processOperation(operation: OpenAPIV3.OperationObject) {
+ *   const requestBodyContent = toOptionalMediaTypeItemsV3({
+ *     content: operation.requestBody?.content,
+ *     context: parseContext
+ *   });
+ *
+ *   if (requestBodyContent) {
+ *     console.log('Operation has request body with media types:');
+ *     console.log(Object.keys(requestBodyContent));
+ *   } else {
+ *     console.log('Operation has no request body');
+ *   }
+ * }
+ * ```
+ *
+ * @example Safe processing in response handlers
+ * ```typescript
+ * class ResponseProcessor {
+ *   processResponse(response: OpenAPIV3.ResponseObject) {
+ *     const mediaTypes = toOptionalMediaTypeItemsV3({
+ *       content: response.content,
+ *       context: this.context
+ *     });
+ *
+ *     // Safe to check without worrying about undefined content
+ *     const hasJsonResponse = mediaTypes && 'application/json' in mediaTypes;
+ *
+ *     if (hasJsonResponse) {
+ *       const jsonMediaType = mediaTypes['application/json'];
+ *       return this.generateJsonResponseHandler(jsonMediaType);
+ *     }
+ *
+ *     return this.generateEmptyResponseHandler();
+ *   }
+ * }
+ * ```
+ */
+const toOptionalMediaTypeItemsV3 = ({ content, stackTrail, context }) => {
+    if (!content) {
+        return;
+    }
+    return (0, exports.toMediaTypeItemsV3)({ content, stackTrail, context });
+};
+exports.toOptionalMediaTypeItemsV3 = toOptionalMediaTypeItemsV3;

package/script/parse/v3-2/methods.d.ts

@@ -0,0 +1,17 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { Method } from '../../types/Method.js';
+/**
+ * The path item fields that hold an Operation Object in OpenAPI 3.2.
+ * `query` is new in 3.2.
+ */
+export declare const pathItemMethods: readonly Method[];
+/**
+ * A 3.2 path item: the `openapi-types` path item plus the `query` operation.
+ */
+export type PathItemObjectV3 = OpenAPIV3.PathItemObject & {
+    query?: OpenAPIV3.OperationObject;
+};
+/**
+ * Returns `key` as a {@link Method} when it is one of {@link pathItemMethods}.
+ */
+export declare const toPathItemMethod: (key: string) => Method | undefined;

package/script/parse/v3-2/methods.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPathItemMethod = exports.pathItemMethods = void 0;
+/**
+ * The path item fields that hold an Operation Object in OpenAPI 3.2.
+ * `query` is new in 3.2.
+ */
+exports.pathItemMethods = [
+    'get',
+    'put',
+    'post',
+    'delete',
+    'options',
+    'head',
+    'patch',
+    'trace',
+    'query'
+];
+/**
+ * Returns `key` as a {@link Method} when it is one of {@link pathItemMethods}.
+ */
+const toPathItemMethod = (key) => {
+    return exports.pathItemMethods.find(method => method === key);
+};
+exports.toPathItemMethod = toPathItemMethod;

package/script/parse/v3-2/number/toNumber.d.ts

@@ -0,0 +1,10 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasNumber } from '../../../oas/number/Number.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToNumberArgs = {
+    value: OpenAPIV3.SchemaObject;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toNumber: ({ context, value, stackTrail }: ToNumberArgs) => OasNumber;

package/script/parse/v3-2/number/toNumber.js

@@ -0,0 +1,152 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toNumber = void 0;
+const Number_js_1 = require("../../../oas/number/Number.js");
+const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const number_types_js_1 = require("../../../oas/number/number-types.js");
+const parseNullable_js_1 = require("../_helpers/parseNullable.js");
+const parseEnum_js_1 = require("../_helpers/parseEnum.js");
+const parseExample_js_1 = require("../_helpers/parseExample.js");
+const parseDefault_js_1 = require("../_helpers/parseDefault.js");
+const v = __importStar(require("valibot"));
+const toNumber = ({ context, value, stackTrail }) => {
+    const { nullable, value: valueWithoutNullable } = (0, parseNullable_js_1.parseNullable)({
+        value,
+        context,
+        stackTrail
+    });
+    const { example: unparsedExample, ...valueWithoutExample } = valueWithoutNullable;
+    const example = (0, parseExample_js_1.parseExample)({
+        value: unparsedExample,
+        context,
+        parent: valueWithoutNullable,
+        nullable,
+        check: isNumber,
+        toMessage: item => `Removed invalid example. Expected "number", got: ${item}`,
+        stackTrail
+    });
+    const { enum: unparsedEnums, ...valueWithoutEnums } = valueWithoutExample;
+    const enums = (0, parseEnum_js_1.parseEnum)({
+        value: unparsedEnums,
+        nullable,
+        stackTrail,
+        parent: valueWithoutExample,
+        context,
+        check: isNumber,
+        toMessage: item => `Removed invalid enum. Expected "number", got: ${item}`
+    });
+    const { default: unparsedDefaultValue, ...valueWithoutDefault } = valueWithoutEnums;
+    const defaultValue = (0, parseDefault_js_1.parseDefault)({
+        value: unparsedDefaultValue,
+        context,
+        parent: valueWithoutEnums,
+        nullable,
+        check: isNumber,
+        toMessage: item => `Removed invalid default. Expected "number", got: ${item}`,
+        stackTrail
+    });
+    return toParsedNumber({
+        context,
+        nullable,
+        example,
+        enums,
+        defaultValue,
+        value: valueWithoutDefault,
+        stackTrail
+    });
+};
+exports.toNumber = toNumber;
+const toParsedNumber = ({ context, nullable, example, enums, defaultValue, value: valueWithoutEnums, stackTrail }) => {
+    const { format: unparsedFormat, ...valueWithoutFormat } = valueWithoutEnums;
+    const format = parseNumberFormat({
+        format: unparsedFormat,
+        context,
+        stackTrail,
+        parent: valueWithoutEnums
+    });
+    if (!v.is(number_types_js_1.oasNumberData, valueWithoutFormat)) {
+        v.parse(number_types_js_1.oasNumberData, valueWithoutFormat);
+    }
+    const { type: _type, title, description, multipleOf, maximum, exclusiveMaximum, minimum, exclusiveMinimum, readOnly, writeOnly, deprecated, ...skipped } = valueWithoutFormat;
+    const extensionFields = (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({
+        skipped,
+        parent: valueWithoutFormat,
+        context,
+        stackTrail,
+        parentType: 'schema:number'
+    });
+    return context.withStackTrail(stackTrail, () => new Number_js_1.OasNumber({
+        title,
+        description,
+        nullable,
+        default: defaultValue,
+        extensionFields,
+        example,
+        enums,
+        format,
+        multipleOf,
+        maximum,
+        exclusiveMaximum,
+        minimum,
+        readOnly,
+        writeOnly,
+        exclusiveMinimum,
+        deprecated
+    }, context));
+};
+const parseNumberFormat = ({ format, context, parent, stackTrail }) => {
+    if (format === undefined) {
+        return undefined;
+    }
+    if (!v.is(number_types_js_1.numberFormat, format)) {
+        // `format` is an open vocabulary; a value the IR's numberFormat can't
+        // hold (e.g. `decimal`) is dropped. Recorded at `debug` — the dropped
+        // hint is informational, not a correctness issue.
+        context.logIssue({
+            key: 'format',
+            level: 'debug',
+            message: `Invalid format: ${format}`,
+            parent,
+            stackTrail,
+            type: 'INVALID_FORMAT'
+        });
+        return undefined;
+    }
+    return format;
+};
+const isNumber = (value) => {
+    return typeof value === 'number';
+};

package/script/parse/v3-2/object/toAdditionalPropertiesV3.d.ts

@@ -0,0 +1,11 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { OasSchema } from '../../../oas/schema/Schema.js';
+import type { OasRef } from '../../../oas/ref/Ref.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToAdditionalPropertiesV3Args = {
+    additionalProperties: boolean | OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toAdditionalPropertiesV3: ({ additionalProperties, stackTrail, context }: ToAdditionalPropertiesV3Args) => OasSchema | OasRef<"schema"> | boolean | undefined;

package/script/parse/v3-2/object/toAdditionalPropertiesV3.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toAdditionalPropertiesV3 = void 0;
+const toSchemasV3_js_1 = require("../schema/toSchemasV3.js");
+const toAdditionalPropertiesV3 = ({ additionalProperties, stackTrail, context }) => {
+    if (typeof additionalProperties === 'boolean') {
+        return additionalProperties;
+    }
+    if (additionalProperties === undefined) {
+        return undefined;
+    }
+    return (0, toSchemasV3_js_1.toSchemaV3)({ schema: additionalProperties, stackTrail, context });
+};
+exports.toAdditionalPropertiesV3 = toAdditionalPropertiesV3;

package/script/parse/v3-2/object/toObject.d.ts

@@ -0,0 +1,10 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasObject } from '../../../oas/object/Object.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToObjectArgs = {
+    value: OpenAPIV3.SchemaObject;
+    context: ParseContextType;
+    stackTrail: StackTrail;
+};
+export declare const toObject: ({ value, context, stackTrail }: ToObjectArgs) => OasObject;