@skmtc/core 0.0.790 → 0.0.792

package/script/oas/requestBody/RequestBody.d.ts

@@ -4,12 +4,276 @@ import type { OasRef } from '../ref/Ref.js';
 import type { OasSchema } from '../schema/Schema.js';
 import type { ToJsonSchemaOptions } from '../schema/Schema.js';
 import type { OpenAPIV3 } from 'openapi-types';
+/**
+ * Constructor fields for {@link OasRequestBody}.
+ */
 export type RequestBodyFields = {
+    /** A description of the request body */
     description?: string | undefined;
+    /** Request content for different media types */
     content: Record<string, OasMediaType>;
+    /** Whether the request body is required */
     required?: boolean | undefined;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
 };
+/**
+ * Represents a Request Body Object in the OpenAPI Specification.
+ *
+ * The `OasRequestBody` class encapsulates the definition of a request body that
+ * can be sent with HTTP operations. It supports multiple content types, schema
+ * validation, and can be marked as required or optional. Request bodies are
+ * commonly used with POST, PUT, PATCH, and sometimes DELETE operations.
+ *
+ * This class provides comprehensive support for request body definitions with
+ * typed content, multiple media type representations, and proper validation.
+ *
+ * ## Key Features
+ *
+ * - **Multiple Content Types**: Support for JSON, XML, form data, binary, and more
+ * - **Schema Validation**: Typed request bodies through schema definitions
+ * - **Required/Optional**: Control whether the request body is mandatory
+ * - **Reference Support**: Can reference reusable request body components
+ * - **Documentation**: Rich description support for API documentation
+ * - **Media Type Flexibility**: Different schemas for different content types
+ *
+ * @example Basic JSON request body
+ * ```typescript
+ * import { OasRequestBody, OasMediaType, OasObject, OasString } from '@skmtc/core';
+ *
+ * const createUserRequest = new OasRequestBody({
+ *   description: 'User data for creating a new user account',
+ *   required: true,
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           name: new OasString({
+ *             description: 'Full name',
+ *             minLength: 1,
+ *             maxLength: 100
+ *           }),
+ *           email: new OasString({
+ *             format: 'email',
+ *             description: 'Email address'
+ *           }),
+ *           password: new OasString({
+ *             minLength: 8,
+ *             description: 'Account password'
+ *           })
+ *         },
+ *         required: ['name', 'email', 'password']
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Multiple content types
+ * ```typescript
+ * const multiFormatRequest = new OasRequestBody({
+ *   description: 'Product data in multiple formats',
+ *   required: true,
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasRef({ $ref: '#/components/schemas/Product' })
+ *     }),
+ *     'application/xml': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           product: new OasRef({ $ref: '#/components/schemas/Product' })
+ *         }
+ *       })
+ *     }),
+ *     'application/x-www-form-urlencoded': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           name: new OasString(),
+ *           price: new OasNumber({ format: 'double' }),
+ *           category_id: new OasInteger()
+ *         }
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example File upload request body
+ * ```typescript
+ * const fileUploadRequest = new OasRequestBody({
+ *   description: 'File upload with metadata',
+ *   required: true,
+ *   content: {
+ *     'multipart/form-data': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           file: new OasString({
+ *             format: 'binary',
+ *             description: 'The file to upload'
+ *           }),
+ *           filename: new OasString({
+ *             description: 'Original filename'
+ *           }),
+ *           description: new OasString({
+ *             description: 'File description',
+ *             required: false
+ *           }),
+ *           tags: new OasArray({
+ *             items: new OasString(),
+ *             description: 'File tags'
+ *           })
+ *         },
+ *         required: ['file', 'filename']
+ *       })
+ *     }),
+ *     'application/octet-stream': new OasMediaType({
+ *       schema: new OasString({
+ *         format: 'binary',
+ *         description: 'Raw binary file content'
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Optional request body for updates
+ * ```typescript
+ * const updateUserRequest = new OasRequestBody({
+ *   description: 'Partial user data for updates (all fields optional)',
+ *   required: false, // Request body itself is optional
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           name: new OasString({ description: 'Updated name' }),
+ *           email: new OasString({
+ *             format: 'email',
+ *             description: 'Updated email'
+ *           }),
+ *           bio: new OasString({ description: 'User biography' }),
+ *           preferences: new OasObject({
+ *             properties: {
+ *               notifications: new OasBoolean(),
+ *               theme: new OasString({ enum: ['light', 'dark'] })
+ *             }
+ *           })
+ *         }
+ *         // No required fields - all updates are optional
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Complex nested data structures
+ * ```typescript
+ * const orderRequest = new OasRequestBody({
+ *   description: 'Complete order with items and shipping',
+ *   required: true,
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           customer: new OasObject({
+ *             properties: {
+ *               id: new OasString(),
+ *               email: new OasString({ format: 'email' })
+ *             },
+ *             required: ['id']
+ *           }),
+ *           items: new OasArray({
+ *             items: new OasObject({
+ *               properties: {
+ *                 productId: new OasString(),
+ *                 quantity: new OasInteger({ minimum: 1 }),
+ *                 customizations: new OasArray({
+ *                   items: new OasString()
+ *                 })
+ *               },
+ *               required: ['productId', 'quantity']
+ *             }),
+ *             minItems: 1
+ *           }),
+ *           shipping: new OasObject({
+ *             properties: {
+ *               address: new OasRef({ $ref: '#/components/schemas/Address' }),
+ *               method: new OasString({ enum: ['standard', 'express', 'overnight'] }),
+ *               instructions: new OasString()
+ *             },
+ *             required: ['address', 'method']
+ *           }),
+ *           couponCode: new OasString({ description: 'Optional discount code' })
+ *         },
+ *         required: ['customer', 'items', 'shipping']
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Form data with validation
+ * ```typescript
+ * const registrationForm = new OasRequestBody({
+ *   description: 'User registration form data',
+ *   required: true,
+ *   content: {
+ *     'application/x-www-form-urlencoded': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           username: new OasString({
+ *             pattern: '^[a-zA-Z0-9_]{3,20}$',
+ *             description: 'Alphanumeric username, 3-20 characters'
+ *           }),
+ *           email: new OasString({
+ *             format: 'email',
+ *             description: 'Valid email address'
+ *           }),
+ *           password: new OasString({
+ *             minLength: 8,
+ *             description: 'Password, minimum 8 characters'
+ *           }),
+ *           confirmPassword: new OasString({
+ *             description: 'Password confirmation'
+ *           }),
+ *           agreeToTerms: new OasBoolean({
+ *             enum: [true],
+ *             description: 'Must accept terms of service'
+ *           })
+ *         },
+ *         required: ['username', 'email', 'password', 'confirmPassword', 'agreeToTerms']
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Using in operation definitions
+ * ```typescript
+ * const createProductOperation = new OasOperation({
+ *   path: '/products',
+ *   method: 'post',
+ *   requestBody: createUserRequest,
+ *   responses: {
+ *     '201': new OasResponse({
+ *       description: 'Product created successfully',
+ *       content: {
+ *         'application/json': new OasMediaType({
+ *           schema: new OasRef({ $ref: '#/components/schemas/Product' })
+ *         })
+ *       }
+ *     }),
+ *     '400': new OasResponse({
+ *       description: 'Invalid request data',
+ *       content: {
+ *         'application/json': new OasMediaType({
+ *           schema: new OasRef({ $ref: '#/components/schemas/ValidationError' })
+ *         })
+ *       }
+ *     })
+ *   }
+ * });
+ * ```
+ */
 export declare class OasRequestBody {
     oasType: 'requestBody';
     description: string | undefined;

package/script/oas/requestBody/RequestBody.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RequestBody.d.ts","sourceRoot":"","sources":["../../../src/oas/requestBody/RequestBody.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACrC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,qBAAa,cAAc;IACzB,OAAO,EAAE,aAAa,CAAgB;IACtC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACrC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;gBACxC,MAAM,EAAE,iBAAiB;IAOrC,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,aAAa,CAAC;IAItC,OAAO,IAAI,cAAc;IAIzB,WAAW,IAAI,cAAc;IAI7B,QAAQ,CAAC,SAAS,GAAE,MAA2B,GAAG,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI1F,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC,iBAAiB;CAYxE"}
+{"version":3,"file":"RequestBody.d.ts","sourceRoot":"","sources":["../../../src/oas/requestBody/RequestBody.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACrC,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9B,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgQG;AACH,qBAAa,cAAc;IACzB,OAAO,EAAE,aAAa,CAAgB;IACtC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACrC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;gBACxC,MAAM,EAAE,iBAAiB;IAOrC,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,aAAa,CAAC;IAItC,OAAO,IAAI,cAAc;IAIzB,WAAW,IAAI,cAAc;IAI7B,QAAQ,CAAC,SAAS,GAAE,MAA2B,GAAG,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI1F,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC,iBAAiB;CAYxE"}

package/script/oas/requestBody/RequestBody.js

@@ -2,6 +2,263 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OasRequestBody = void 0;
 require("../../_dnt.polyfills.js");
+/**
+ * Represents a Request Body Object in the OpenAPI Specification.
+ *
+ * The `OasRequestBody` class encapsulates the definition of a request body that
+ * can be sent with HTTP operations. It supports multiple content types, schema
+ * validation, and can be marked as required or optional. Request bodies are
+ * commonly used with POST, PUT, PATCH, and sometimes DELETE operations.
+ *
+ * This class provides comprehensive support for request body definitions with
+ * typed content, multiple media type representations, and proper validation.
+ *
+ * ## Key Features
+ *
+ * - **Multiple Content Types**: Support for JSON, XML, form data, binary, and more
+ * - **Schema Validation**: Typed request bodies through schema definitions
+ * - **Required/Optional**: Control whether the request body is mandatory
+ * - **Reference Support**: Can reference reusable request body components
+ * - **Documentation**: Rich description support for API documentation
+ * - **Media Type Flexibility**: Different schemas for different content types
+ *
+ * @example Basic JSON request body
+ * ```typescript
+ * import { OasRequestBody, OasMediaType, OasObject, OasString } from '@skmtc/core';
+ *
+ * const createUserRequest = new OasRequestBody({
+ *   description: 'User data for creating a new user account',
+ *   required: true,
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           name: new OasString({
+ *             description: 'Full name',
+ *             minLength: 1,
+ *             maxLength: 100
+ *           }),
+ *           email: new OasString({
+ *             format: 'email',
+ *             description: 'Email address'
+ *           }),
+ *           password: new OasString({
+ *             minLength: 8,
+ *             description: 'Account password'
+ *           })
+ *         },
+ *         required: ['name', 'email', 'password']
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Multiple content types
+ * ```typescript
+ * const multiFormatRequest = new OasRequestBody({
+ *   description: 'Product data in multiple formats',
+ *   required: true,
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasRef({ $ref: '#/components/schemas/Product' })
+ *     }),
+ *     'application/xml': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           product: new OasRef({ $ref: '#/components/schemas/Product' })
+ *         }
+ *       })
+ *     }),
+ *     'application/x-www-form-urlencoded': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           name: new OasString(),
+ *           price: new OasNumber({ format: 'double' }),
+ *           category_id: new OasInteger()
+ *         }
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example File upload request body
+ * ```typescript
+ * const fileUploadRequest = new OasRequestBody({
+ *   description: 'File upload with metadata',
+ *   required: true,
+ *   content: {
+ *     'multipart/form-data': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           file: new OasString({
+ *             format: 'binary',
+ *             description: 'The file to upload'
+ *           }),
+ *           filename: new OasString({
+ *             description: 'Original filename'
+ *           }),
+ *           description: new OasString({
+ *             description: 'File description',
+ *             required: false
+ *           }),
+ *           tags: new OasArray({
+ *             items: new OasString(),
+ *             description: 'File tags'
+ *           })
+ *         },
+ *         required: ['file', 'filename']
+ *       })
+ *     }),
+ *     'application/octet-stream': new OasMediaType({
+ *       schema: new OasString({
+ *         format: 'binary',
+ *         description: 'Raw binary file content'
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Optional request body for updates
+ * ```typescript
+ * const updateUserRequest = new OasRequestBody({
+ *   description: 'Partial user data for updates (all fields optional)',
+ *   required: false, // Request body itself is optional
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           name: new OasString({ description: 'Updated name' }),
+ *           email: new OasString({
+ *             format: 'email',
+ *             description: 'Updated email'
+ *           }),
+ *           bio: new OasString({ description: 'User biography' }),
+ *           preferences: new OasObject({
+ *             properties: {
+ *               notifications: new OasBoolean(),
+ *               theme: new OasString({ enum: ['light', 'dark'] })
+ *             }
+ *           })
+ *         }
+ *         // No required fields - all updates are optional
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Complex nested data structures
+ * ```typescript
+ * const orderRequest = new OasRequestBody({
+ *   description: 'Complete order with items and shipping',
+ *   required: true,
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           customer: new OasObject({
+ *             properties: {
+ *               id: new OasString(),
+ *               email: new OasString({ format: 'email' })
+ *             },
+ *             required: ['id']
+ *           }),
+ *           items: new OasArray({
+ *             items: new OasObject({
+ *               properties: {
+ *                 productId: new OasString(),
+ *                 quantity: new OasInteger({ minimum: 1 }),
+ *                 customizations: new OasArray({
+ *                   items: new OasString()
+ *                 })
+ *               },
+ *               required: ['productId', 'quantity']
+ *             }),
+ *             minItems: 1
+ *           }),
+ *           shipping: new OasObject({
+ *             properties: {
+ *               address: new OasRef({ $ref: '#/components/schemas/Address' }),
+ *               method: new OasString({ enum: ['standard', 'express', 'overnight'] }),
+ *               instructions: new OasString()
+ *             },
+ *             required: ['address', 'method']
+ *           }),
+ *           couponCode: new OasString({ description: 'Optional discount code' })
+ *         },
+ *         required: ['customer', 'items', 'shipping']
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Form data with validation
+ * ```typescript
+ * const registrationForm = new OasRequestBody({
+ *   description: 'User registration form data',
+ *   required: true,
+ *   content: {
+ *     'application/x-www-form-urlencoded': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           username: new OasString({
+ *             pattern: '^[a-zA-Z0-9_]{3,20}$',
+ *             description: 'Alphanumeric username, 3-20 characters'
+ *           }),
+ *           email: new OasString({
+ *             format: 'email',
+ *             description: 'Valid email address'
+ *           }),
+ *           password: new OasString({
+ *             minLength: 8,
+ *             description: 'Password, minimum 8 characters'
+ *           }),
+ *           confirmPassword: new OasString({
+ *             description: 'Password confirmation'
+ *           }),
+ *           agreeToTerms: new OasBoolean({
+ *             enum: [true],
+ *             description: 'Must accept terms of service'
+ *           })
+ *         },
+ *         required: ['username', 'email', 'password', 'confirmPassword', 'agreeToTerms']
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Using in operation definitions
+ * ```typescript
+ * const createProductOperation = new OasOperation({
+ *   path: '/products',
+ *   method: 'post',
+ *   requestBody: createUserRequest,
+ *   responses: {
+ *     '201': new OasResponse({
+ *       description: 'Product created successfully',
+ *       content: {
+ *         'application/json': new OasMediaType({
+ *           schema: new OasRef({ $ref: '#/components/schemas/Product' })
+ *         })
+ *       }
+ *     }),
+ *     '400': new OasResponse({
+ *       description: 'Invalid request data',
+ *       content: {
+ *         'application/json': new OasMediaType({
+ *           schema: new OasRef({ $ref: '#/components/schemas/ValidationError' })
+ *         })
+ *       }
+ *     })
+ *   }
+ * });
+ * ```
+ */
 class OasRequestBody {
     constructor(fields) {
         Object.defineProperty(this, "oasType", {