@skmtc/core 0.29.0 → 0.31.0

package/script/parse/v3-2/link/toLinksV3.d.ts

@@ -0,0 +1,16 @@
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import type { OpenAPIV3 } from 'openapi-types';
+import { OasLink } from '../../../oas/link/Link.js';
+import type { OasRef } from '../../../oas/ref/Ref.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToLinksV3Args = {
+    links: Record<string, OpenAPIV3.ReferenceObject | OpenAPIV3.LinkObject> | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toLinksV3: ({ links, stackTrail, context }: ToLinksV3Args) => Record<string, OasLink | OasRef<"link">> | undefined;
+export type ToLinkV3Args = {
+    link: OpenAPIV3.ReferenceObject | OpenAPIV3.LinkObject;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};

package/script/parse/v3-2/link/toLinksV3.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toLinksV3 = void 0;
+const toRefV31_js_1 = require("../ref/toRefV31.js");
+const toServerV3_js_1 = require("../server/toServerV3.js");
+const refFns_js_1 = require("../../../helpers/refFns.js");
+const Link_js_1 = require("../../../oas/link/Link.js");
+const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const toLinksV3 = ({ links, stackTrail, context }) => {
+    if (!links) {
+        return undefined;
+    }
+    const output = {};
+    for (const [key, value] of Object.entries(links)) {
+        output[key] = stackTrail.trace(key, st => toLinkV3({ link: value, stackTrail: st, context }));
+    }
+    return output;
+};
+exports.toLinksV3 = toLinksV3;
+const toLinkV3 = ({ link, stackTrail, context }) => {
+    if ((0, refFns_js_1.isRef)(link)) {
+        return (0, toRefV31_js_1.toRefV31)({ ref: link, refType: 'link', stackTrail, context });
+    }
+    const { operationRef, operationId, parameters, requestBody, description, server, ...skipped } = link;
+    const extensionFields = (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({
+        skipped,
+        parent: link,
+        context,
+        stackTrail,
+        parentType: 'link'
+    });
+    const fields = {
+        operationRef,
+        operationId,
+        parameters,
+        requestBody,
+        description,
+        server: server !== undefined
+            ? stackTrail.trace('server', st => (0, toServerV3_js_1.toServerV3)({ server, stackTrail: st, context }))
+            : undefined,
+        extensionFields
+    };
+    return new Link_js_1.OasLink(fields);
+};

package/script/parse/v3-2/mediaType/toMediaTypeItemV3.d.ts

@@ -0,0 +1,323 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasMediaType } from '../../../oas/mediaType/MediaType.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/**
+ * An OpenAPI 3.2 Media Type Object: the 3.0/3.1 fields plus the fields for
+ * sequential and multipart array media types.
+ */
+export type MediaTypeObjectV32 = OpenAPIV3.MediaTypeObject & {
+    itemSchema?: OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject;
+    prefixEncoding?: Record<string, unknown>[];
+    itemEncoding?: Record<string, unknown>;
+};
+/**
+ * Arguments for transforming an OpenAPI v3 media type item into an OAS media type.
+ */
+export type ToMediaTypeItemV3Args = {
+    /** The OpenAPI v3 media type object to transform */
+    mediaTypeItem: MediaTypeObjectV32;
+    /** The media type string (e.g., 'application/json', 'text/plain') */
+    mediaType: string;
+    /** The stack trail for tracing */
+    stackTrail: StackTrail;
+    /** The parsing context for tracing and processing */
+    context: ParseContextType;
+};
+/**
+ * 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']
+ * ```
+ */
+export declare const toMediaTypeItemV3: ({ mediaTypeItem, mediaType, stackTrail, context }: ToMediaTypeItemV3Args) => OasMediaType;
+/**
+ * Arguments for transforming multiple OpenAPI v3 media type items.
+ */
+export type ToMediaTypeItemsV3Args = {
+    /** Map of media type strings to MediaType objects or `components.mediaTypes` references */
+    content: Record<string, MediaTypeObjectV32 | OpenAPIV3.ReferenceObject>;
+    /** The stack trail for tracing */
+    stackTrail: StackTrail;
+    /** The parsing context for tracing and processing */
+    context: ParseContextType;
+};
+/**
+ * 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
+ * ```
+ */
+export declare const toMediaTypeItemsV3: ({ content, stackTrail, context }: ToMediaTypeItemsV3Args) => Record<string, OasMediaType>;
+/**
+ * Arguments for optionally transforming OpenAPI v3 media type items.
+ */
+export type ToOptionalMediaTypeItemsV3Args = {
+    /** Optional map of media type strings to MediaType objects or `components.mediaTypes` references */
+    content: Record<string, MediaTypeObjectV32 | OpenAPIV3.ReferenceObject> | undefined;
+    /** The stack trail for tracing */
+    stackTrail: StackTrail;
+    /** The parsing context for tracing and processing */
+    context: ParseContextType;
+};
+/**
+ * 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();
+ *   }
+ * }
+ * ```
+ */
+export declare const toOptionalMediaTypeItemsV3: ({ content, stackTrail, context }: ToOptionalMediaTypeItemsV3Args) => Record<string, OasMediaType> | undefined;