@skmtc/core 0.0.796 → 0.0.798

package/esm/oas/_helpers/parseFormat.js

@@ -1,4 +1,142 @@
 import * as v from 'valibot';
+/**
+ * Parses and validates OpenAPI schema format values with type safety.
+ *
+ * This function extracts and validates format specifiers from OpenAPI schema objects,
+ * ensuring they conform to expected format types for the given schema. Invalid format
+ * values are removed and logged as warnings through the parse context.
+ *
+ * The format property provides additional semantic information about the expected
+ * structure of string values (like 'email', 'date-time', 'uuid', etc.) and numeric
+ * precision (like 'float', 'double' for numbers, 'int32', 'int64' for integers).
+ *
+ * @template T - The expected type of the format value (usually string)
+ * @template Value - The OpenAPI schema object type
+ *
+ * @param args - Parsing configuration
+ * @returns Parsed format data with the validated format and cleaned schema
+ *
+ * @example String format parsing
+ * ```typescript
+ * import { parseFormat } from '@skmtc/core/oas/_helpers';
+ * import * as v from 'valibot';
+ *
+ * const result = parseFormat({
+ *   value: {
+ *     type: 'string',
+ *     format: 'email',
+ *     maxLength: 100
+ *   },
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.format); // 'email'
+ * console.log(result.value);  // { type: 'string', maxLength: 100 }
+ * ```
+ *
+ * @example Date-time format
+ * ```typescript
+ * const result = parseFormat({
+ *   value: {
+ *     type: 'string',
+ *     format: 'date-time',
+ *     description: 'ISO 8601 timestamp'
+ *   },
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.format); // 'date-time'
+ * // Can be used to generate Date objects in TypeScript
+ * ```
+ *
+ * @example Number precision formats
+ * ```typescript
+ * const result = parseFormat({
+ *   value: {
+ *     type: 'number',
+ *     format: 'float',
+ *     minimum: 0
+ *   },
+ *   valibotSchema: v.string(), // Format is always a string
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.format); // 'float'
+ * // Indicates single-precision floating-point
+ * ```
+ *
+ * @example Integer format specifiers
+ * ```typescript
+ * const result = parseFormat({
+ *   value: {
+ *     type: 'integer',
+ *     format: 'int64',
+ *     description: 'Large integer ID'
+ *   },
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.format); // 'int64'
+ * // Indicates 64-bit signed integer
+ * ```
+ *
+ * @example Invalid format handling
+ * ```typescript
+ * const result = parseFormat({
+ *   value: {
+ *     type: 'string',
+ *     format: 123, // Invalid - should be string
+ *     pattern: '^[a-z]+$'
+ *   } as any,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.format); // undefined (invalid format removed)
+ * console.log(result.value);  // { type: 'string', pattern: '^[a-z]+$' }
+ * // Context will log a warning about the invalid format
+ * ```
+ *
+ * @example Missing format (undefined)
+ * ```typescript
+ * const result = parseFormat({
+ *   value: {
+ *     type: 'string',
+ *     minLength: 1,
+ *     maxLength: 50
+ *   },
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.format); // undefined (no format specified)
+ * console.log(result.value);  // { type: 'string', minLength: 1, maxLength: 50 }
+ * ```
+ *
+ * @example Common string formats
+ * ```typescript
+ * // Standard OpenAPI string formats:
+ * // - 'date': full-date as defined by RFC3339
+ * // - 'date-time': date-time as defined by RFC3339
+ * // - 'time': time as defined by RFC3339
+ * // - 'email': email address as defined by RFC5322
+ * // - 'uri': URI as defined by RFC3986
+ * // - 'uuid': UUID as defined by RFC4122
+ * // - 'binary': binary data (base64 encoded)
+ * // - 'byte': base64 encoded characters
+ * // - 'password': hint for UI to obscure input
+ *
+ * const emailFormat = parseFormat({
+ *   value: { type: 'string', format: 'email' },
+ *   valibotSchema: v.string(),
+ *   context
+ * });
+ * // Can generate validation: v.pipe(v.string(), v.email())
+ * ```
+ */
 export const parseFormat = ({ value, valibotSchema, context }) => {
     const { format, ...rest } = value;
     const parsedFormat = context.provisionalParse({

package/esm/oas/_helpers/parseNullable.d.ts

@@ -1,12 +1,139 @@
 import type { OpenAPIV3 } from 'openapi-types';
 import type { ParseContext } from '../../context/ParseContext.js';
+/**
+ * Arguments for parsing the nullable property from OpenAPI schemas.
+ *
+ * @template Value - The OpenAPI schema object type
+ */
 export type ParseNullableArgs<Value extends OpenAPIV3.SchemaObject> = {
+    /** The OpenAPI schema object containing the nullable property */
     value: Value;
+    /** Parse context for error handling */
     context: ParseContext;
 };
+/**
+ * Return type for parsed nullable data.
+ *
+ * @template Value - The OpenAPI schema object type
+ */
 export type ParseNullableReturn<Value extends OpenAPIV3.SchemaObject> = {
+    /** The validated nullable flag (true, false, or undefined) */
     nullable: boolean | undefined;
+    /** The schema object without the nullable property */
     value: Omit<Value, 'nullable'>;
 };
+/**
+ * Parses and validates the nullable property from OpenAPI schema objects.
+ *
+ * This function extracts and validates the `nullable` property from OpenAPI
+ * schema objects, ensuring it's a valid boolean value. Invalid nullable values
+ * are removed and logged as warnings through the parse context.
+ *
+ * The nullable property determines whether a schema value can be null in addition
+ * to its primary type, which affects type generation and validation logic.
+ *
+ * @template Value - The OpenAPI schema object type
+ *
+ * @param args - Parsing configuration
+ * @returns Parsed nullable data with the validated flag and cleaned schema
+ *
+ * @example Valid nullable property
+ * ```typescript
+ * import { parseNullable } from '@skmtc/core/oas/_helpers';
+ *
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'string',
+ *     nullable: true,
+ *     description: 'An optional string that can be null'
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // true
+ * console.log(result.value);    // { type: 'string', description: 'An optional string that can be null' }
+ * ```
+ *
+ * @example Explicitly non-nullable
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'number',
+ *     nullable: false,
+ *     minimum: 0
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // false
+ * console.log(result.value);    // { type: 'number', minimum: 0 }
+ * ```
+ *
+ * @example Missing nullable property (undefined)
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'string',
+ *     format: 'email'
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // undefined (property not present)
+ * console.log(result.value);    // { type: 'string', format: 'email' }
+ * ```
+ *
+ * @example Invalid nullable value
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'boolean',
+ *     nullable: 'yes', // Invalid - should be boolean
+ *     description: 'A flag'
+ *   } as any,
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // undefined (invalid value removed)
+ * console.log(result.value);    // { type: 'boolean', description: 'A flag' }
+ * // Context will log a warning about the invalid nullable value
+ * ```
+ *
+ * @example Usage in type generation
+ * ```typescript
+ * function generateTypeScript(schema: OpenAPIV3.SchemaObject) {
+ *   const { nullable, value } = parseNullable({ value: schema, context });
+ *
+ *   const baseType = generateBaseType(value);
+ *   const nullableType = nullable ? ` | null` : '';
+ *
+ *   return `${baseType}${nullableType}`;
+ * }
+ *
+ * // Examples:
+ * // nullable: true  -> 'string | null'
+ * // nullable: false -> 'string'
+ * // nullable: undefined -> 'string' (default behavior)
+ * ```
+ *
+ * @example Complex schema with nullable
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'object',
+ *     properties: {
+ *       name: { type: 'string' },
+ *       age: { type: 'number' }
+ *     },
+ *     required: ['name'],
+ *     nullable: true // The entire object can be null
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // true
+ * // Generated type might be: { name: string; age?: number } | null
+ * ```
+ */
 export declare const parseNullable: <Value extends OpenAPIV3.SchemaObject>({ value, context }: ParseNullableArgs<Value>) => ParseNullableReturn<Value>;
 //# sourceMappingURL=parseNullable.d.ts.map

package/esm/oas/_helpers/parseNullable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseNullable.d.ts","sourceRoot":"","sources":["../../../src/oas/_helpers/parseNullable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAGjE,MAAM,MAAM,iBAAiB,CAAC,KAAK,SAAS,SAAS,CAAC,YAAY,IAAI;IACpE,KAAK,EAAE,KAAK,CAAA;IACZ,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,mBAAmB,CAAC,KAAK,SAAS,SAAS,CAAC,YAAY,IAAI;IACtE,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;CAC/B,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,KAAK,SAAS,SAAS,CAAC,YAAY,EAAE,oBAGjE,iBAAiB,CAAC,KAAK,CAAC,KAAG,mBAAmB,CAAC,KAAK,CAgBtD,CAAA"}
+{"version":3,"file":"parseNullable.d.ts","sourceRoot":"","sources":["../../../src/oas/_helpers/parseNullable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAGjE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,KAAK,SAAS,SAAS,CAAC,YAAY,IAAI;IACpE,iEAAiE;IACjE,KAAK,EAAE,KAAK,CAAA;IACZ,uCAAuC;IACvC,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,KAAK,SAAS,SAAS,CAAC,YAAY,IAAI;IACtE,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,sDAAsD;IACtD,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;CAC/B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgHG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,SAAS,SAAS,CAAC,YAAY,EAAE,oBAGjE,iBAAiB,CAAC,KAAK,CAAC,KAAG,mBAAmB,CAAC,KAAK,CAgBtD,CAAA"}

package/esm/oas/_helpers/parseNullable.js

@@ -1,4 +1,117 @@
 import * as v from 'valibot';
+/**
+ * Parses and validates the nullable property from OpenAPI schema objects.
+ *
+ * This function extracts and validates the `nullable` property from OpenAPI
+ * schema objects, ensuring it's a valid boolean value. Invalid nullable values
+ * are removed and logged as warnings through the parse context.
+ *
+ * The nullable property determines whether a schema value can be null in addition
+ * to its primary type, which affects type generation and validation logic.
+ *
+ * @template Value - The OpenAPI schema object type
+ *
+ * @param args - Parsing configuration
+ * @returns Parsed nullable data with the validated flag and cleaned schema
+ *
+ * @example Valid nullable property
+ * ```typescript
+ * import { parseNullable } from '@skmtc/core/oas/_helpers';
+ *
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'string',
+ *     nullable: true,
+ *     description: 'An optional string that can be null'
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // true
+ * console.log(result.value);    // { type: 'string', description: 'An optional string that can be null' }
+ * ```
+ *
+ * @example Explicitly non-nullable
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'number',
+ *     nullable: false,
+ *     minimum: 0
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // false
+ * console.log(result.value);    // { type: 'number', minimum: 0 }
+ * ```
+ *
+ * @example Missing nullable property (undefined)
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'string',
+ *     format: 'email'
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // undefined (property not present)
+ * console.log(result.value);    // { type: 'string', format: 'email' }
+ * ```
+ *
+ * @example Invalid nullable value
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'boolean',
+ *     nullable: 'yes', // Invalid - should be boolean
+ *     description: 'A flag'
+ *   } as any,
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // undefined (invalid value removed)
+ * console.log(result.value);    // { type: 'boolean', description: 'A flag' }
+ * // Context will log a warning about the invalid nullable value
+ * ```
+ *
+ * @example Usage in type generation
+ * ```typescript
+ * function generateTypeScript(schema: OpenAPIV3.SchemaObject) {
+ *   const { nullable, value } = parseNullable({ value: schema, context });
+ *
+ *   const baseType = generateBaseType(value);
+ *   const nullableType = nullable ? ` | null` : '';
+ *
+ *   return `${baseType}${nullableType}`;
+ * }
+ *
+ * // Examples:
+ * // nullable: true  -> 'string | null'
+ * // nullable: false -> 'string'
+ * // nullable: undefined -> 'string' (default behavior)
+ * ```
+ *
+ * @example Complex schema with nullable
+ * ```typescript
+ * const result = parseNullable({
+ *   value: {
+ *     type: 'object',
+ *     properties: {
+ *       name: { type: 'string' },
+ *       age: { type: 'number' }
+ *     },
+ *     required: ['name'],
+ *     nullable: true // The entire object can be null
+ *   },
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.nullable); // true
+ * // Generated type might be: { name: string; age?: number } | null
+ * ```
+ */
 export const parseNullable = ({ value, context }) => {
     const { nullable, ...rest } = value;
     const parsedNullable = context.provisionalParse({

package/esm/oas/example/toExamplesV3.d.ts

@@ -5,18 +5,57 @@ import type { OasRef } from '../ref/Ref.js';
 type ToExampleSimpleV3Args = {
     example: unknown;
 };
+/**
+ * Creates a simple OAS example from a value.
+ *
+ * Converts a raw example value into an OasExample object with basic
+ * fields. Used for simple example scenarios where only the value matters.
+ *
+ * @param args - Arguments containing the example value
+ * @returns OasExample object with the provided value
+ */
 export declare const toExampleSimpleV3: ({ example }: ToExampleSimpleV3Args) => OasExample | OasRef<"example">;
+/**
+ * Arguments for processing OpenAPI v3 examples into OAS example objects.
+ *
+ * Handles both single example and examples collection scenarios,
+ * with context for tracing and error handling.
+ */
 export type ToExamplesV3Args = {
+    /** Single example object (OpenAPI v3 format) */
     example: OpenAPIV3.ExampleObject | undefined;
+    /** Collection of named examples (OpenAPI v3 format) */
     examples: Record<string, OpenAPIV3.ExampleObject | OpenAPIV3.ReferenceObject> | undefined;
+    /** Key name for the example context */
     exampleKey: string;
+    /** Parse context for tracing and error handling */
     context: ParseContext;
 };
+/**
+ * Processes OpenAPI v3 examples into OAS example objects.
+ *
+ * Handles both single example and examples collection scenarios,
+ * converting them to the internal OAS representation. Provides
+ * warnings when both formats are specified simultaneously.
+ *
+ * @param args - Arguments containing example data and context
+ * @returns Record of processed examples, or undefined if no examples
+ */
 export declare const toExamplesV3: ({ example, examples, exampleKey, context }: ToExamplesV3Args) => Record<string, OasExample | OasRef<"example">> | undefined;
 type ToExampleV3Args = {
     example: OpenAPIV3.ExampleObject | OpenAPIV3.ReferenceObject;
     context: ParseContext;
 };
+/**
+ * Processes a single OpenAPI v3 example into an OAS example object.
+ *
+ * Converts OpenAPI v3 example objects or references into the internal
+ * OAS representation, handling both direct examples and $ref references.
+ * Processes specification extensions and maintains all example metadata.
+ *
+ * @param args - Arguments containing the example and parsing context
+ * @returns OasExample object or reference to an example
+ */
 export declare const toExampleV3: ({ example, context }: ToExampleV3Args) => OasExample | OasRef<"example">;
 export {};
 //# sourceMappingURL=toExamplesV3.d.ts.map

package/esm/oas/example/toExamplesV3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toExamplesV3.d.ts","sourceRoot":"","sources":["../../../src/oas/example/toExamplesV3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAG3C,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,eAAO,MAAM,iBAAiB,GAAI,aAE/B,qBAAqB,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAQvD,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAA;IAC5C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;IACzF,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED,eAAO,MAAM,YAAY,GAAI,4CAK1B,gBAAgB,KAAG,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAsBtE,CAAA;AAED,KAAK,eAAe,GAAG;IACrB,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAA;IAC5D,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,sBAGzB,eAAe,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAoBjD,CAAA"}
+{"version":3,"file":"toExamplesV3.d.ts","sourceRoot":"","sources":["../../../src/oas/example/toExamplesV3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAG3C,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,aAE/B,qBAAqB,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAQvD,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAA;IAC5C,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;IACzF,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,4CAK1B,gBAAgB,KAAG,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAsBtE,CAAA;AAED,KAAK,eAAe,GAAG;IACrB,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAA;IAC5D,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,sBAGzB,eAAe,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAoBjD,CAAA"}

package/esm/oas/example/toExamplesV3.js

@@ -2,6 +2,15 @@ import { isRef } from '../../helpers/refFns.js';
 import { toRefV31 } from '../ref/toRefV31.js';
 import { OasExample } from './Example.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+/**
+ * Creates a simple OAS example from a value.
+ *
+ * Converts a raw example value into an OasExample object with basic
+ * fields. Used for simple example scenarios where only the value matters.
+ *
+ * @param args - Arguments containing the example value
+ * @returns OasExample object with the provided value
+ */
 export const toExampleSimpleV3 = ({ example }) => {
     const fields = {
         value: example,
@@ -10,6 +19,16 @@ export const toExampleSimpleV3 = ({ example }) => {
     };
     return new OasExample(fields);
 };
+/**
+ * Processes OpenAPI v3 examples into OAS example objects.
+ *
+ * Handles both single example and examples collection scenarios,
+ * converting them to the internal OAS representation. Provides
+ * warnings when both formats are specified simultaneously.
+ *
+ * @param args - Arguments containing example data and context
+ * @returns Record of processed examples, or undefined if no examples
+ */
 export const toExamplesV3 = ({ example, examples, exampleKey, context }) => {
     if (example && examples) {
         context.logger.warn(`Both example and examples are defined for ${exampleKey}`);
@@ -28,6 +47,16 @@ export const toExamplesV3 = ({ example, examples, exampleKey, context }) => {
     }
     return undefined;
 };
+/**
+ * Processes a single OpenAPI v3 example into an OAS example object.
+ *
+ * Converts OpenAPI v3 example objects or references into the internal
+ * OAS representation, handling both direct examples and $ref references.
+ * Processes specification extensions and maintains all example metadata.
+ *
+ * @param args - Arguments containing the example and parsing context
+ * @returns OasExample object or reference to an example
+ */
 export const toExampleV3 = ({ example, context }) => {
     if (isRef(example)) {
         return toRefV31({ ref: example, refType: 'example', context });

package/esm/oas/object/Object.d.ts

@@ -182,11 +182,17 @@ export declare class OasObject<Nullable extends boolean | undefined = boolean |
      * The default value of the object.
      */
     default: Nullable extends true ? Record<string, unknown> | null | undefined : Record<string, unknown> | undefined;
+    /** Maximum number of properties allowed in the object */
     maxProperties?: number;
+    /** Minimum number of properties required in the object */
     minProperties?: number;
+    /** Whether the object is read-only */
     readOnly?: boolean;
+    /** Whether the object is write-only */
     writeOnly?: boolean;
+    /** Whether the object schema is deprecated */
     deprecated?: boolean;
+    /** Array of valid enum values for the object */
     enums?: Nullable extends true ? (Record<string, unknown> | null)[] | undefined : Record<string, unknown>[] | undefined;
     /**
      * Creates a new OasObject instance.

package/esm/oas/object/Object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../../src/oas/object/Object.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../../src/oas/object/Object.ts"],"names":[],"mappings":"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"}

package/esm/oas/object/Object.js

@@ -205,36 +205,42 @@ export class OasObject {
             writable: true,
             value: void 0
         });
+        /** Maximum number of properties allowed in the object */
         Object.defineProperty(this, "maxProperties", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Minimum number of properties required in the object */
         Object.defineProperty(this, "minProperties", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether the object is read-only */
         Object.defineProperty(this, "readOnly", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether the object is write-only */
         Object.defineProperty(this, "writeOnly", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether the object schema is deprecated */
         Object.defineProperty(this, "deprecated", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Array of valid enum values for the object */
         Object.defineProperty(this, "enums", {
             enumerable: true,
             configurable: true,

package/esm/oas/operation/Operation.d.ts

@@ -11,19 +11,39 @@ import { OasObject } from '../object/Object.js';
 import type { ToJsonSchemaOptions } from '../schema/Schema.js';
 import type { OpenAPIV3 } from 'openapi-types';
 import type { OasSecurityRequirement } from '../securityRequirement/SecurityRequirement.js';
+/**
+ * Fields for configuring an OpenAPI operation object.
+ *
+ * Contains all the properties needed to define a complete OpenAPI operation,
+ * including path information, parameters, request/response specifications,
+ * security requirements, and metadata.
+ */
 export type OperationFields = {
+    /** The API path for this operation */
     path: string;
+    /** The HTTP method for this operation */
     method: Method;
+    /** The parent path item containing this operation */
     pathItem: OasPathItem | undefined;
+    /** Unique identifier for the operation */
     operationId?: string | undefined;
+    /** Brief summary of the operation */
     summary?: string | undefined;
+    /** Tags for organizing operations in documentation */
     tags?: string[] | undefined;
+    /** Detailed description of the operation */
     description?: string | undefined;
+    /** Parameters accepted by this operation */
     parameters?: (OasParameter | OasRef<'parameter'>)[] | undefined;
+    /** Request body specification for this operation */
     requestBody?: OasRequestBody | OasRef<'requestBody'> | undefined;
+    /** Response specifications mapped by status code */
     responses: Record<string, OasResponse | OasRef<'response'>>;
+    /** Security requirements for this operation */
     security?: OasSecurityRequirement[] | undefined;
+    /** Whether this operation is deprecated */
     deprecated?: boolean | undefined;
+    /** OpenAPI specification extensions */
     extensionFields?: Record<string, unknown>;
 };
 type ToRequestBodyMapArgs = {
@@ -138,19 +158,33 @@ type ToRequestBodyMapArgs = {
  * ```
  */
 export declare class OasOperation {
+    /** Type identifier for OAS operation objects */
     oasType: 'operation';
+    /** The API path for this operation */
     path: string;
+    /** The HTTP method for this operation */
     method: Method;
+    /** The parent path item containing this operation */
     pathItem: OasPathItem | undefined;
+    /** Unique identifier for the operation */
     operationId: string | undefined;
+    /** Brief summary of the operation */
     summary: string | undefined;
+    /** Tags for organizing operations in documentation */
     tags: string[] | undefined;
+    /** Detailed description of the operation */
     description: string | undefined;
+    /** Parameters accepted by this operation */
     parameters: (OasParameter | OasRef<'parameter'>)[] | undefined;
+    /** Request body specification for this operation */
     requestBody: OasRequestBody | OasRef<'requestBody'> | undefined;
+    /** Response specifications mapped by status code */
     responses: Record<string, OasResponse | OasRef<'response'>>;
+    /** Security requirements for this operation */
     security: OasSecurityRequirement[] | undefined;
+    /** Whether this operation is deprecated */
     deprecated: boolean | undefined;
+    /** OpenAPI specification extensions */
     extensionFields: Record<string, unknown> | undefined;
     constructor(fields: OperationFields);
     toSuccessResponse(): OasResponse | OasRef<'response'> | undefined;