@skmtc/core 0.0.807 → 0.0.809

package/script/oas/array/array-types.js

@@ -40,9 +40,64 @@ const ref_types_js_1 = require("../ref/ref-types.js");
 /**
  * Valibot schema for validating OpenAPI array data objects.
  *
- * Validates array schemas including item type definitions, length constraints,
- * uniqueness requirements, and enumeration values. Uses lazy evaluation
- * to handle recursive schema references.
+ * This comprehensive schema validates OpenAPI array schemas according to the OpenAPI v3
+ * specification, including item type definitions, length constraints, uniqueness requirements,
+ * and enumeration values. It uses lazy evaluation to handle recursive schema references,
+ * allowing for complex nested array structures and self-referential schemas.
+ *
+ * The schema supports both direct schema definitions and reference objects for the items
+ * property, enabling flexible array type definitions that can reference other schemas
+ * in the document or define inline item types.
+ *
+ * @example Validating a simple array schema
+ * ```typescript
+ * import { oasArrayData } from '@skmtc/core/oas/array';
+ * import * as v from 'valibot';
+ *
+ * const schema = {
+ *   type: 'array',
+ *   items: {
+ *     type: 'string'
+ *   },
+ *   description: 'List of user names',
+ *   minItems: 1,
+ *   maxItems: 100
+ * };
+ *
+ * const validated = v.parse(oasArrayData, schema);
+ * console.log(validated.minItems); // 1
+ * ```
+ *
+ * @example Validating array with reference items
+ * ```typescript
+ * const refArraySchema = {
+ *   type: 'array',
+ *   items: {
+ *     $ref: '#/components/schemas/User'
+ *   },
+ *   title: 'User List',
+ *   uniqueItems: true,
+ *   default: []
+ * };
+ *
+ * const result = v.parse(oasArrayData, refArraySchema);
+ * console.log(result.uniqueItems); // true
+ * ```
+ *
+ * @example Validating constrained arrays
+ * ```typescript
+ * const constrainedArray = {
+ *   type: 'array',
+ *   items: { type: 'number' },
+ *   minItems: 2,
+ *   maxItems: 10,
+ *   uniqueItems: true,
+ *   enums: [[1, 2, 3], [4, 5, 6]]
+ * };
+ *
+ * const validated = v.parse(oasArrayData, constrainedArray);
+ * console.log(validated.maxItems); // 10
+ * ```
  */
 exports.oasArrayData = v.object({
     type: v.literal('array'),
@@ -58,8 +113,45 @@ exports.oasArrayData = v.object({
 /**
  * Valibot schema for array data without the items property.
  *
- * Used for parsing array schemas when the items property is handled separately,
- * typically during schema transformation and validation processes.
+ * This specialized schema validates array schemas when the items property is processed
+ * separately from the main array constraints. It's commonly used during schema parsing
+ * and transformation processes where items need special handling, such as when resolving
+ * references or applying schema merging operations.
+ *
+ * This pattern is useful in multi-phase parsing where array constraints (like min/max
+ * items, uniqueness) are validated independently from the item type definitions,
+ * allowing for more flexible processing pipelines.
+ *
+ * @example Validating array constraints without items
+ * ```typescript
+ * import { oasArrayDataWithoutItems } from '@skmtc/core/oas/array';
+ * import * as v from 'valibot';
+ *
+ * const constraintsOnly = {
+ *   type: 'array',
+ *   title: 'Validation Rules',
+ *   minItems: 1,
+ *   maxItems: 50,
+ *   uniqueItems: true,
+ *   default: []
+ * };
+ *
+ * const validated = v.parse(oasArrayDataWithoutItems, constraintsOnly);
+ * console.log(validated.uniqueItems); // true
+ * ```
+ *
+ * @example Usage in two-phase parsing
+ * ```typescript
+ * function parseArraySchema(schema: unknown) {
+ *   // Phase 1: Validate basic array structure
+ *   const arrayConstraints = v.parse(oasArrayDataWithoutItems, schema);
+ *
+ *   // Phase 2: Process items separately (not shown)
+ *   const items = processItemsSchema((schema as any).items);
+ *
+ *   return { ...arrayConstraints, items };
+ * }
+ * ```
  */
 exports.oasArrayDataWithoutItems = v.object({
     type: v.literal('array'),

package/script/oas/boolean/boolean-types.d.ts

@@ -2,27 +2,99 @@ import * as v from 'valibot';
 /**
  * Valibot schema for validating OpenAPI boolean data objects.
  *
- * Validates boolean schemas including default values and enumeration
- * constraints. Boolean enums typically contain [true, false] or single values.
+ * This schema validates OpenAPI boolean schemas according to the OpenAPI v3 specification,
+ * including optional properties like default values, enumeration constraints, title,
+ * and description metadata. Boolean enums are commonly used to restrict values to
+ * specific boolean constants (e.g., [true] for always-true flags).
+ *
+ * @example Validating a basic boolean schema
+ * ```typescript
+ * import { oasBooleanData } from '@skmtc/core/oas/boolean';
+ * import * as v from 'valibot';
+ *
+ * const schema = {
+ *   type: 'boolean',
+ *   description: 'Whether the feature is enabled',
+ *   default: false
+ * };
+ *
+ * const validated = v.parse(oasBooleanData, schema);
+ * console.log(validated.default); // false
+ * ```
+ *
+ * @example Validating boolean with enumeration
+ * ```typescript
+ * const constrainedBoolean = {
+ *   type: 'boolean',
+ *   title: 'Admin Flag',
+ *   description: 'User admin status',
+ *   enum: [true] // Only true values allowed
+ * };
+ *
+ * const result = v.parse(oasBooleanData, constrainedBoolean);
+ * console.log(result.enum); // [true]
+ * ```
  */
 export declare const oasBooleanData: v.GenericSchema<OasBooleanData>;
 /**
  * Data type for OpenAPI boolean schema objects.
  *
- * Represents boolean schemas with optional default values and enumeration
- * constraints. Used throughout the SKMTC pipeline for boolean type
- * processing and code generation.
+ * Represents the structure of OpenAPI boolean schemas as processed by the SKMTC pipeline.
+ * This type includes all standard OpenAPI boolean schema properties including metadata,
+ * default values, and enumeration constraints. It's used throughout the boolean
+ * processing pipeline for type-safe handling of boolean schema definitions.
+ *
+ * ## Usage in SKMTC Pipeline
+ *
+ * This type is used by:
+ * - Schema parsers to validate incoming boolean schema data
+ * - Boolean processors to transform OpenAPI schemas into OAS objects
+ * - Code generators to access boolean schema metadata and constraints
+ * - Validation systems to ensure schema compliance
+ *
+ * @example Basic boolean schema
+ * ```typescript
+ * import type { OasBooleanData } from '@skmtc/core/oas/boolean';
+ *
+ * const isActiveSchema: OasBooleanData = {
+ *   type: 'boolean',
+ *   title: 'Active Status',
+ *   description: 'Whether the record is active',
+ *   default: true
+ * };
+ * ```
+ *
+ * @example Boolean with enumeration constraints
+ * ```typescript
+ * const adminFlagSchema: OasBooleanData = {
+ *   type: 'boolean',
+ *   description: 'Administrative privileges flag',
+ *   enum: [false, true], // Allow both values
+ *   default: false
+ * };
+ * ```
+ *
+ * @example Read-only boolean flag
+ * ```typescript
+ * const systemFlagSchema: OasBooleanData = {
+ *   type: 'boolean',
+ *   title: 'System Generated',
+ *   description: 'Indicates if the record was system-generated',
+ *   enum: [true], // Always true
+ *   default: true
+ * };
+ * ```
  */
 export type OasBooleanData = {
     /** Type identifier (always 'boolean') */
     type: 'boolean';
-    /** Human-readable title for the boolean */
+    /** Human-readable title for the boolean schema */
     title?: string;
-    /** Detailed description of the boolean's purpose */
+    /** Detailed description explaining the boolean's purpose and usage */
     description?: string;
-    /** Default value for the boolean */
+    /** Default value used when no explicit value is provided */
     default?: boolean;
-    /** Array of valid boolean values (typically [true], [false], or [true, false]) */
+    /** Array of valid boolean values for enumeration constraints */
     enum?: boolean[];
 };
 //# sourceMappingURL=boolean-types.d.ts.map

package/script/oas/boolean/boolean-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boolean-types.d.ts","sourceRoot":"","sources":["../../../src/oas/boolean/boolean-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAMzD,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,yCAAyC;IACzC,IAAI,EAAE,SAAS,CAAA;IACf,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,kFAAkF;IAClF,IAAI,CAAC,EAAE,OAAO,EAAE,CAAA;CACjB,CAAA"}
+{"version":3,"file":"boolean-types.d.ts","sourceRoot":"","sources":["../../../src/oas/boolean/boolean-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAMzD,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,yCAAyC;IACzC,IAAI,EAAE,SAAS,CAAA;IACf,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,EAAE,CAAA;CACjB,CAAA"}

package/script/oas/boolean/boolean-types.js

@@ -38,8 +38,38 @@ const v = __importStar(require("valibot"));
 /**
  * Valibot schema for validating OpenAPI boolean data objects.
  *
- * Validates boolean schemas including default values and enumeration
- * constraints. Boolean enums typically contain [true, false] or single values.
+ * This schema validates OpenAPI boolean schemas according to the OpenAPI v3 specification,
+ * including optional properties like default values, enumeration constraints, title,
+ * and description metadata. Boolean enums are commonly used to restrict values to
+ * specific boolean constants (e.g., [true] for always-true flags).
+ *
+ * @example Validating a basic boolean schema
+ * ```typescript
+ * import { oasBooleanData } from '@skmtc/core/oas/boolean';
+ * import * as v from 'valibot';
+ *
+ * const schema = {
+ *   type: 'boolean',
+ *   description: 'Whether the feature is enabled',
+ *   default: false
+ * };
+ *
+ * const validated = v.parse(oasBooleanData, schema);
+ * console.log(validated.default); // false
+ * ```
+ *
+ * @example Validating boolean with enumeration
+ * ```typescript
+ * const constrainedBoolean = {
+ *   type: 'boolean',
+ *   title: 'Admin Flag',
+ *   description: 'User admin status',
+ *   enum: [true] // Only true values allowed
+ * };
+ *
+ * const result = v.parse(oasBooleanData, constrainedBoolean);
+ * console.log(result.enum); // [true]
+ * ```
  */
 exports.oasBooleanData = v.object({
     type: v.literal('boolean'),

package/script/oas/contact/contact-types.d.ts

@@ -1,9 +1,185 @@
 import * as v from 'valibot';
+/**
+ * Data type for OpenAPI contact information objects.
+ *
+ * This type represents contact information as specified in the OpenAPI v3 specification's
+ * Info Object. Contact information provides details about the person or organization
+ * responsible for the API, including optional name, website URL, and email address.
+ *
+ * The contact information is typically displayed in API documentation and used by
+ * developers to reach out for support, questions, or feedback about the API.
+ *
+ * ## Usage in SKMTC Pipeline
+ *
+ * This type is used by:
+ * - Info processors to validate and structure contact information
+ * - Documentation generators to display API maintainer information
+ * - Client generators to embed support contact details in generated code
+ * - Validation systems to ensure contact information completeness
+ *
+ * @example Basic contact information
+ * ```typescript
+ * import type { OasContactData } from '@skmtc/core/oas/contact';
+ *
+ * const apiContact: OasContactData = {
+ *   oasType: 'contact',
+ *   name: 'API Support Team',
+ *   url: 'https://company.com/support',
+ *   email: 'api-support@company.com'
+ * };
+ * ```
+ *
+ * @example Minimal contact with only email
+ * ```typescript
+ * const minimalContact: OasContactData = {
+ *   oasType: 'contact',
+ *   email: 'support@api-company.com'
+ * };
+ * ```
+ *
+ * @example Contact with name and URL
+ * ```typescript
+ * const teamContact: OasContactData = {
+ *   oasType: 'contact',
+ *   name: 'Development Team',
+ *   url: 'https://github.com/company/api-repo'
+ * };
+ * ```
+ *
+ * @example Integration in OpenAPI Info object
+ * ```typescript
+ * const apiInfo = {
+ *   title: 'My API',
+ *   version: '1.0.0',
+ *   description: 'A comprehensive API for managing resources',
+ *   contact: {
+ *     oasType: 'contact',
+ *     name: 'Jane Doe',
+ *     url: 'https://janedoe.dev',
+ *     email: 'jane@company.com'
+ *   }
+ * };
+ * ```
+ *
+ * @example Empty contact (valid but not recommended)
+ * ```typescript
+ * const emptyContact: OasContactData = {
+ *   oasType: 'contact'
+ *   // All fields are optional, but at least one should be provided
+ * };
+ * ```
+ */
 export type OasContactData = {
+    /** Type identifier for SKMTC internal processing */
     oasType: 'contact';
+    /** The identifying name of the contact person or organization */
     name?: string;
+    /** The URL pointing to the contact information (website, GitHub, etc.) */
     url?: string;
+    /** The email address of the contact person or organization */
     email?: string;
 };
+/**
+ * Valibot schema for validating OpenAPI contact data objects.
+ *
+ * This schema validates OpenAPI contact information according to the OpenAPI v3
+ * specification. All contact fields are optional, allowing for flexible contact
+ * information configurations. The schema ensures proper string formatting for
+ * name, URL, and email fields while maintaining the required `oasType` identifier.
+ *
+ * Note that while all fields are optional according to the OpenAPI specification,
+ * it's recommended to provide at least one contact method for practical API usage.
+ *
+ * @example Validating complete contact information
+ * ```typescript
+ * import { oasContactData } from '@skmtc/core/oas/contact';
+ * import * as v from 'valibot';
+ *
+ * const contact = {
+ *   oasType: 'contact',
+ *   name: 'API Support',
+ *   url: 'https://api.company.com/support',
+ *   email: 'support@company.com'
+ * };
+ *
+ * const validated = v.parse(oasContactData, contact);
+ * console.log(validated.name); // 'API Support'
+ * console.log(validated.email); // 'support@company.com'
+ * ```
+ *
+ * @example Validating partial contact information
+ * ```typescript
+ * const partialContact = {
+ *   oasType: 'contact',
+ *   email: 'help@api.com'
+ *   // name and url are optional and omitted
+ * };
+ *
+ * const result = v.parse(oasContactData, partialContact);
+ * console.log(result.email); // 'help@api.com'
+ * console.log(result.name); // undefined
+ * console.log(result.url); // undefined
+ * ```
+ *
+ * @example Validation error handling
+ * ```typescript
+ * const invalidContact = {
+ *   oasType: 'contact',
+ *   name: 123, // Invalid: should be string
+ *   email: 'valid@email.com'
+ * };
+ *
+ * try {
+ *   v.parse(oasContactData, invalidContact);
+ * } catch (error) {
+ *   console.error('Contact validation failed:', error.message);
+ *   // Handle validation errors appropriately
+ * }
+ * ```
+ *
+ * @example Usage in OpenAPI document processing
+ * ```typescript
+ * function processApiInfo(infoObject: unknown) {
+ *   // Validate the info object structure
+ *   const info = parseInfoObject(infoObject);
+ *
+ *   // If contact information exists, validate it
+ *   if (info.contact) {
+ *     const validatedContact = v.parse(oasContactData, {
+ *       oasType: 'contact',
+ *       ...info.contact
+ *     });
+ *
+ *     console.log(`API maintained by: ${validatedContact.name || 'Unknown'}`);
+ *     console.log(`Support: ${validatedContact.email || 'No email provided'}`);
+ *   }
+ * }
+ * ```
+ *
+ * @example Integration with documentation generators
+ * ```typescript
+ * class DocumentationGenerator {
+ *   generateContactSection(contactData: OasContactData): string {
+ *     const validated = v.parse(oasContactData, contactData);
+ *
+ *     let contactSection = '## Contact Information\n\n';
+ *
+ *     if (validated.name) {
+ *       contactSection += `**Maintainer:** ${validated.name}\n\n`;
+ *     }
+ *
+ *     if (validated.email) {
+ *       contactSection += `**Email:** [${validated.email}](mailto:${validated.email})\n\n`;
+ *     }
+ *
+ *     if (validated.url) {
+ *       contactSection += `**Website:** [${validated.url}](${validated.url})\n\n`;
+ *     }
+ *
+ *     return contactSection;
+ *   }
+ * }
+ * ```
+ */
 export declare const oasContactData: v.GenericSchema<OasContactData>;
 //# sourceMappingURL=contact-types.d.ts.map

package/script/oas/contact/contact-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contact-types.d.ts","sourceRoot":"","sources":["../../../src/oas/contact/contact-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,SAAS,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAKzD,CAAA"}
+{"version":3,"file":"contact-types.d.ts","sourceRoot":"","sources":["../../../src/oas/contact/contact-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,oDAAoD;IACpD,OAAO,EAAE,SAAS,CAAA;IAClB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAKzD,CAAA"}

package/script/oas/contact/contact-types.js

@@ -35,6 +35,108 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.oasContactData = void 0;
 const v = __importStar(require("valibot"));
+/**
+ * Valibot schema for validating OpenAPI contact data objects.
+ *
+ * This schema validates OpenAPI contact information according to the OpenAPI v3
+ * specification. All contact fields are optional, allowing for flexible contact
+ * information configurations. The schema ensures proper string formatting for
+ * name, URL, and email fields while maintaining the required `oasType` identifier.
+ *
+ * Note that while all fields are optional according to the OpenAPI specification,
+ * it's recommended to provide at least one contact method for practical API usage.
+ *
+ * @example Validating complete contact information
+ * ```typescript
+ * import { oasContactData } from '@skmtc/core/oas/contact';
+ * import * as v from 'valibot';
+ *
+ * const contact = {
+ *   oasType: 'contact',
+ *   name: 'API Support',
+ *   url: 'https://api.company.com/support',
+ *   email: 'support@company.com'
+ * };
+ *
+ * const validated = v.parse(oasContactData, contact);
+ * console.log(validated.name); // 'API Support'
+ * console.log(validated.email); // 'support@company.com'
+ * ```
+ *
+ * @example Validating partial contact information
+ * ```typescript
+ * const partialContact = {
+ *   oasType: 'contact',
+ *   email: 'help@api.com'
+ *   // name and url are optional and omitted
+ * };
+ *
+ * const result = v.parse(oasContactData, partialContact);
+ * console.log(result.email); // 'help@api.com'
+ * console.log(result.name); // undefined
+ * console.log(result.url); // undefined
+ * ```
+ *
+ * @example Validation error handling
+ * ```typescript
+ * const invalidContact = {
+ *   oasType: 'contact',
+ *   name: 123, // Invalid: should be string
+ *   email: 'valid@email.com'
+ * };
+ *
+ * try {
+ *   v.parse(oasContactData, invalidContact);
+ * } catch (error) {
+ *   console.error('Contact validation failed:', error.message);
+ *   // Handle validation errors appropriately
+ * }
+ * ```
+ *
+ * @example Usage in OpenAPI document processing
+ * ```typescript
+ * function processApiInfo(infoObject: unknown) {
+ *   // Validate the info object structure
+ *   const info = parseInfoObject(infoObject);
+ *
+ *   // If contact information exists, validate it
+ *   if (info.contact) {
+ *     const validatedContact = v.parse(oasContactData, {
+ *       oasType: 'contact',
+ *       ...info.contact
+ *     });
+ *
+ *     console.log(`API maintained by: ${validatedContact.name || 'Unknown'}`);
+ *     console.log(`Support: ${validatedContact.email || 'No email provided'}`);
+ *   }
+ * }
+ * ```
+ *
+ * @example Integration with documentation generators
+ * ```typescript
+ * class DocumentationGenerator {
+ *   generateContactSection(contactData: OasContactData): string {
+ *     const validated = v.parse(oasContactData, contactData);
+ *
+ *     let contactSection = '## Contact Information\n\n';
+ *
+ *     if (validated.name) {
+ *       contactSection += `**Maintainer:** ${validated.name}\n\n`;
+ *     }
+ *
+ *     if (validated.email) {
+ *       contactSection += `**Email:** [${validated.email}](mailto:${validated.email})\n\n`;
+ *     }
+ *
+ *     if (validated.url) {
+ *       contactSection += `**Website:** [${validated.url}](${validated.url})\n\n`;
+ *     }
+ *
+ *     return contactSection;
+ *   }
+ * }
+ * ```
+ */
 exports.oasContactData = v.object({
     oasType: v.literal('contact'),
     name: v.optional(v.string()),