@skmtc/core 0.0.796 → 0.0.797

package/esm/oas/_helpers/parseDefault.js

@@ -1,4 +1,132 @@
 import * as v from 'valibot';
+/**
+ * Parses and validates OpenAPI schema default values with type safety.
+ *
+ * This function extracts and validates default values from OpenAPI schema objects,
+ * ensuring they conform to the expected type and handling nullable schemas correctly.
+ * Invalid default values are removed and logged as warnings through the parse context.
+ *
+ * The function provides full type safety, with the return type reflecting whether
+ * null values are allowed based on the nullable parameter. This ensures that
+ * generated code maintains proper type constraints for default values.
+ *
+ * @template T - The expected type of the default value
+ * @template Nullable - Whether the schema allows null as a default
+ * @template Value - The OpenAPI schema object type
+ *
+ * @param args - Parsing configuration
+ * @returns Parsed default data with the validated default value and cleaned schema
+ *
+ * @example Basic string default parsing
+ * ```typescript
+ * import { parseDefault } from '@skmtc/core/oas/_helpers';
+ * import * as v from 'valibot';
+ *
+ * const result = parseDefault({
+ *   value: {
+ *     type: 'string',
+ *     default: 'hello world',
+ *     minLength: 5
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.default); // 'hello world'
+ * console.log(result.value);   // { type: 'string', minLength: 5 }
+ * ```
+ *
+ * @example Nullable default value
+ * ```typescript
+ * const result = parseDefault({
+ *   value: {
+ *     type: 'string',
+ *     default: null,
+ *     format: 'email'
+ *   },
+ *   nullable: true,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.default); // null (valid for nullable schema)
+ * // Type: string | null | undefined
+ * ```
+ *
+ * @example Number default with constraints
+ * ```typescript
+ * const result = parseDefault({
+ *   value: {
+ *     type: 'number',
+ *     default: 42,
+ *     minimum: 0,
+ *     maximum: 100
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.number(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.default); // 42
+ * console.log(result.value);   // { type: 'number', minimum: 0, maximum: 100 }
+ * ```
+ *
+ * @example Invalid default handling
+ * ```typescript
+ * const result = parseDefault({
+ *   value: {
+ *     type: 'boolean',
+ *     default: 'not a boolean', // Invalid default
+ *     description: 'A boolean flag'
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.boolean(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.default); // undefined (invalid default removed)
+ * // Context will log a warning about the invalid default
+ * ```
+ *
+ * @example Array default value
+ * ```typescript
+ * const result = parseDefault({
+ *   value: {
+ *     type: 'array',
+ *     items: { type: 'string' },
+ *     default: ['item1', 'item2']
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.array(v.string()),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.default); // ['item1', 'item2']
+ * ```
+ *
+ * @example Object default value
+ * ```typescript
+ * const result = parseDefault({
+ *   value: {
+ *     type: 'object',
+ *     properties: {
+ *       name: { type: 'string' },
+ *       age: { type: 'number' }
+ *     },
+ *     default: { name: 'John', age: 30 }
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.object({
+ *     name: v.string(),
+ *     age: v.number()
+ *   }),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.default); // { name: 'John', age: 30 }
+ * ```
+ */
 export const parseDefault = ({ value, nullable, valibotSchema, context }) => {
     const { default: defaultValue, ...rest } = value;
     const parsedDefault = context.provisionalParse({

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

@@ -1,16 +1,140 @@
 import type { OpenAPIV3 } from 'openapi-types';
 import type { ParseContext } from '../../context/ParseContext.js';
 import * as v from 'valibot';
+/**
+ * Arguments for parsing OpenAPI schema enum values.
+ *
+ * @template T - The expected type of enum values
+ * @template Nullable - Whether the schema allows null values
+ * @template Value - The OpenAPI schema object type
+ */
 type ParseEnumArgs<T, Nullable extends boolean | undefined, Value extends OpenAPIV3.SchemaObject> = {
+    /** The OpenAPI schema object without nullable property */
     value: Omit<Value, 'nullable'>;
+    /** Whether the schema allows null values */
     nullable: Nullable;
+    /** Valibot schema for validating enum values */
     valibotSchema: v.GenericSchema<T>;
+    /** Parse context for error handling */
     context: ParseContext;
 };
+/**
+ * Return type for parsed enum data.
+ *
+ * @template T - The expected type of enum values
+ * @template Nullable - Whether the schema allows null values
+ * @template Value - The OpenAPI schema object type
+ */
 type ParseEnumReturn<T, Nullable extends boolean | undefined, Value extends OpenAPIV3.SchemaObject> = {
+    /** The parsed and validated enum array */
     enum: Nullable extends true ? (T | null)[] | undefined : T[] | undefined;
+    /** The schema object without enum and nullable properties */
     value: Omit<Value, 'nullable' | 'enum'>;
 };
+/**
+ * Parses and validates OpenAPI schema enum values with type safety.
+ *
+ * This function extracts and validates enum arrays from OpenAPI schema objects,
+ * ensuring all enum values conform to the expected type and handling nullable
+ * schemas correctly. Invalid enum values are removed and logged as warnings
+ * through the parse context.
+ *
+ * The function provides full type safety, with the return type reflecting whether
+ * null values are allowed in the enum array based on the nullable parameter.
+ *
+ * @template T - The expected type of enum values
+ * @template Nullable - Whether the schema allows null values in enums
+ * @template Value - The OpenAPI schema object type
+ *
+ * @param args - Parsing configuration
+ * @returns Parsed enum data with the validated enum array and cleaned schema
+ *
+ * @example Basic string enum parsing
+ * ```typescript
+ * import { parseEnum } from '@skmtc/core/oas/_helpers';
+ * import * as v from 'valibot';
+ *
+ * const result = parseEnum({
+ *   value: {
+ *     type: 'string',
+ *     enum: ['active', 'inactive', 'pending'],
+ *     description: 'User status'
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.enum); // ['active', 'inactive', 'pending']
+ * console.log(result.value); // { type: 'string', description: 'User status' }
+ * ```
+ *
+ * @example Nullable enum parsing
+ * ```typescript
+ * const result = parseEnum({
+ *   value: {
+ *     type: 'string',
+ *     enum: ['red', 'green', 'blue', null],
+ *     description: 'Optional color selection'
+ *   },
+ *   nullable: true,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.enum); // ['red', 'green', 'blue', null]
+ * // Type: (string | null)[] | undefined
+ * ```
+ *
+ * @example Number enum parsing
+ * ```typescript
+ * const result = parseEnum({
+ *   value: {
+ *     type: 'number',
+ *     enum: [1, 2, 3, 5, 8, 13],
+ *     description: 'Fibonacci subset'
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.number(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.enum); // [1, 2, 3, 5, 8, 13]
+ * ```
+ *
+ * @example Invalid enum handling
+ * ```typescript
+ * const result = parseEnum({
+ *   value: {
+ *     type: 'number',
+ *     enum: [1, 'invalid', 3], // Contains invalid value
+ *     description: 'Mixed enum (invalid)'
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.number(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.enum); // undefined (entire enum removed due to invalid value)
+ * // Context will log a warning about the invalid enum
+ * ```
+ *
+ * @example Boolean enum (essentially optional boolean)
+ * ```typescript
+ * const result = parseEnum({
+ *   value: {
+ *     type: 'boolean',
+ *     enum: [true, false],
+ *     description: 'Explicit boolean enum'
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.boolean(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.enum); // [true, false]
+ * ```
+ */
 export declare const parseEnum: <T, Nullable extends boolean | undefined, Value extends OpenAPIV3.SchemaObject>({ value, nullable, valibotSchema, context }: ParseEnumArgs<T, Nullable, Value>) => ParseEnumReturn<T, Nullable, Value>;
 export {};
 //# sourceMappingURL=parseEnum.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"parseEnum.d.ts","sourceRoot":"","sources":["../../../src/oas/_helpers/parseEnum.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,KAAK,aAAa,CAChB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,IAClC;IACF,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;IAC9B,QAAQ,EAAE,QAAQ,CAAA;IAClB,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAA;IACjC,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED,KAAK,eAAe,CAClB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,IAClC;IACF,IAAI,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,GAAG,CAAC,EAAE,GAAG,SAAS,CAAA;IACxE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,CAAA;CACxC,CAAA;AAED,eAAO,MAAM,SAAS,GACpB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,EACpC,6CAKC,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,KAAG,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAgBxE,CAAA"}
+{"version":3,"file":"parseEnum.d.ts","sourceRoot":"","sources":["../../../src/oas/_helpers/parseEnum.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;;GAMG;AACH,KAAK,aAAa,CAChB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,IAClC;IACF,0DAA0D;IAC1D,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;IAC9B,4CAA4C;IAC5C,QAAQ,EAAE,QAAQ,CAAA;IAClB,gDAAgD;IAChD,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAA;IACjC,uCAAuC;IACvC,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED;;;;;;GAMG;AACH,KAAK,eAAe,CAClB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,IAClC;IACF,0CAA0C;IAC1C,IAAI,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,GAAG,CAAC,EAAE,GAAG,SAAS,CAAA;IACxE,6DAA6D;IAC7D,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,CAAA;CACxC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuGG;AACH,eAAO,MAAM,SAAS,GACpB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,EACpC,6CAKC,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,KAAG,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAgBxE,CAAA"}

package/esm/oas/_helpers/parseEnum.js

@@ -1,4 +1,108 @@
 import * as v from 'valibot';
+/**
+ * Parses and validates OpenAPI schema enum values with type safety.
+ *
+ * This function extracts and validates enum arrays from OpenAPI schema objects,
+ * ensuring all enum values conform to the expected type and handling nullable
+ * schemas correctly. Invalid enum values are removed and logged as warnings
+ * through the parse context.
+ *
+ * The function provides full type safety, with the return type reflecting whether
+ * null values are allowed in the enum array based on the nullable parameter.
+ *
+ * @template T - The expected type of enum values
+ * @template Nullable - Whether the schema allows null values in enums
+ * @template Value - The OpenAPI schema object type
+ *
+ * @param args - Parsing configuration
+ * @returns Parsed enum data with the validated enum array and cleaned schema
+ *
+ * @example Basic string enum parsing
+ * ```typescript
+ * import { parseEnum } from '@skmtc/core/oas/_helpers';
+ * import * as v from 'valibot';
+ *
+ * const result = parseEnum({
+ *   value: {
+ *     type: 'string',
+ *     enum: ['active', 'inactive', 'pending'],
+ *     description: 'User status'
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.enum); // ['active', 'inactive', 'pending']
+ * console.log(result.value); // { type: 'string', description: 'User status' }
+ * ```
+ *
+ * @example Nullable enum parsing
+ * ```typescript
+ * const result = parseEnum({
+ *   value: {
+ *     type: 'string',
+ *     enum: ['red', 'green', 'blue', null],
+ *     description: 'Optional color selection'
+ *   },
+ *   nullable: true,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.enum); // ['red', 'green', 'blue', null]
+ * // Type: (string | null)[] | undefined
+ * ```
+ *
+ * @example Number enum parsing
+ * ```typescript
+ * const result = parseEnum({
+ *   value: {
+ *     type: 'number',
+ *     enum: [1, 2, 3, 5, 8, 13],
+ *     description: 'Fibonacci subset'
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.number(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.enum); // [1, 2, 3, 5, 8, 13]
+ * ```
+ *
+ * @example Invalid enum handling
+ * ```typescript
+ * const result = parseEnum({
+ *   value: {
+ *     type: 'number',
+ *     enum: [1, 'invalid', 3], // Contains invalid value
+ *     description: 'Mixed enum (invalid)'
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.number(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.enum); // undefined (entire enum removed due to invalid value)
+ * // Context will log a warning about the invalid enum
+ * ```
+ *
+ * @example Boolean enum (essentially optional boolean)
+ * ```typescript
+ * const result = parseEnum({
+ *   value: {
+ *     type: 'boolean',
+ *     enum: [true, false],
+ *     description: 'Explicit boolean enum'
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.boolean(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.enum); // [true, false]
+ * ```
+ */
 export const parseEnum = ({ value, nullable, valibotSchema, context }) => {
     const { enum: enums, ...rest } = value;
     const parsedEnum = context.provisionalParse({

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

@@ -1,16 +1,123 @@
 import type { OpenAPIV3 } from 'openapi-types';
 import type { ParseContext } from '../../context/ParseContext.js';
 import * as v from 'valibot';
+/**
+ * Arguments for parsing OpenAPI schema examples.
+ *
+ * @template T - The expected type of the example value
+ * @template Nullable - Whether the schema allows null values
+ * @template Value - The OpenAPI schema object type
+ */
 type ParseExampleArgs<T, Nullable extends boolean | undefined, Value extends OpenAPIV3.SchemaObject> = {
+    /** The OpenAPI schema object without nullable property */
     value: Omit<Value, 'nullable'>;
+    /** Whether the schema allows null values */
     nullable: Nullable;
+    /** Valibot schema for validating the example */
     valibotSchema: v.GenericSchema<T>;
+    /** Parse context for error handling */
     context: ParseContext;
 };
+/**
+ * Return type for parsed example data.
+ *
+ * @template T - The expected type of the example value
+ * @template Nullable - Whether the schema allows null values
+ * @template Value - The OpenAPI schema object type
+ */
 type ParseExampleReturn<T, Nullable extends boolean | undefined, Value extends OpenAPIV3.SchemaObject> = {
+    /** The parsed and validated example value */
     example: Nullable extends true ? T | null | undefined : T | undefined;
+    /** The schema object without example and nullable properties */
     value: Omit<Value, 'nullable' | 'example'>;
 };
+/**
+ * Parses and validates OpenAPI schema examples with type safety.
+ *
+ * This function extracts and validates example values from OpenAPI schema objects,
+ * ensuring they conform to the expected type and handling nullable schemas correctly.
+ * Invalid examples are removed and logged as warnings through the parse context.
+ *
+ * The function provides full type safety, with the return type reflecting whether
+ * null values are allowed based on the nullable parameter.
+ *
+ * @template T - The expected type of the example value
+ * @template Nullable - Whether the schema allows null values
+ * @template Value - The OpenAPI schema object type
+ *
+ * @param args - Parsing configuration
+ * @returns Parsed example data with the validated example and cleaned schema
+ *
+ * @example Basic string example parsing
+ * ```typescript
+ * import { parseExample } from '@skmtc/core/oas/_helpers';
+ * import * as v from 'valibot';
+ *
+ * const result = parseExample({
+ *   value: {
+ *     type: 'string',
+ *     example: 'hello world',
+ *     format: 'text'
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.example); // 'hello world'
+ * console.log(result.value);   // { type: 'string', format: 'text' }
+ * ```
+ *
+ * @example Nullable schema example
+ * ```typescript
+ * const result = parseExample({
+ *   value: {
+ *     type: 'string',
+ *     example: null,
+ *     minLength: 1
+ *   },
+ *   nullable: true,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.example); // null (valid for nullable schema)
+ * // Type: string | null | undefined
+ * ```
+ *
+ * @example Invalid example handling
+ * ```typescript
+ * const result = parseExample({
+ *   value: {
+ *     type: 'number',
+ *     example: 'not a number', // Invalid example
+ *     minimum: 0
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.number(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.example); // undefined (invalid example removed)
+ * // Context will log a warning about the invalid example
+ * ```
+ *
+ * @example Array example parsing
+ * ```typescript
+ * const result = parseExample({
+ *   value: {
+ *     type: 'array',
+ *     items: { type: 'string' },
+ *     example: ['item1', 'item2', 'item3']
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.array(v.string()),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.example); // ['item1', 'item2', 'item3']
+ * ```
+ */
 export declare const parseExample: <T, Nullable extends boolean | undefined, Value extends OpenAPIV3.SchemaObject>({ value, nullable, valibotSchema, context }: ParseExampleArgs<T, Nullable, Value>) => ParseExampleReturn<T, Nullable, Value>;
 export {};
 //# sourceMappingURL=parseExample.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"parseExample.d.ts","sourceRoot":"","sources":["../../../src/oas/_helpers/parseExample.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,KAAK,gBAAgB,CACnB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,IAClC;IACF,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;IAC9B,QAAQ,EAAE,QAAQ,CAAA;IAClB,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAA;IACjC,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED,KAAK,kBAAkB,CACrB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,IAClC;IACF,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,GAAG,SAAS,CAAA;IACrE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC,CAAA;CAC3C,CAAA;AAED,eAAO,MAAM,YAAY,GACvB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,EACpC,6CAKC,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,KAAG,kBAAkB,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAgB9E,CAAA"}
+{"version":3,"file":"parseExample.d.ts","sourceRoot":"","sources":["../../../src/oas/_helpers/parseExample.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;;GAMG;AACH,KAAK,gBAAgB,CACnB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,IAClC;IACF,0DAA0D;IAC1D,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;IAC9B,4CAA4C;IAC5C,QAAQ,EAAE,QAAQ,CAAA;IAClB,gDAAgD;IAChD,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAA;IACjC,uCAAuC;IACvC,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED;;;;;;GAMG;AACH,KAAK,kBAAkB,CACrB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,IAClC;IACF,6CAA6C;IAC7C,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,GAAG,SAAS,CAAA;IACrE,gEAAgE;IAChE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC,CAAA;CAC3C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,eAAO,MAAM,YAAY,GACvB,CAAC,EACD,QAAQ,SAAS,OAAO,GAAG,SAAS,EACpC,KAAK,SAAS,SAAS,CAAC,YAAY,EACpC,6CAKC,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,KAAG,kBAAkB,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAgB9E,CAAA"}

package/esm/oas/_helpers/parseExample.js

@@ -1,4 +1,91 @@
 import * as v from 'valibot';
+/**
+ * Parses and validates OpenAPI schema examples with type safety.
+ *
+ * This function extracts and validates example values from OpenAPI schema objects,
+ * ensuring they conform to the expected type and handling nullable schemas correctly.
+ * Invalid examples are removed and logged as warnings through the parse context.
+ *
+ * The function provides full type safety, with the return type reflecting whether
+ * null values are allowed based on the nullable parameter.
+ *
+ * @template T - The expected type of the example value
+ * @template Nullable - Whether the schema allows null values
+ * @template Value - The OpenAPI schema object type
+ *
+ * @param args - Parsing configuration
+ * @returns Parsed example data with the validated example and cleaned schema
+ *
+ * @example Basic string example parsing
+ * ```typescript
+ * import { parseExample } from '@skmtc/core/oas/_helpers';
+ * import * as v from 'valibot';
+ *
+ * const result = parseExample({
+ *   value: {
+ *     type: 'string',
+ *     example: 'hello world',
+ *     format: 'text'
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.example); // 'hello world'
+ * console.log(result.value);   // { type: 'string', format: 'text' }
+ * ```
+ *
+ * @example Nullable schema example
+ * ```typescript
+ * const result = parseExample({
+ *   value: {
+ *     type: 'string',
+ *     example: null,
+ *     minLength: 1
+ *   },
+ *   nullable: true,
+ *   valibotSchema: v.string(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.example); // null (valid for nullable schema)
+ * // Type: string | null | undefined
+ * ```
+ *
+ * @example Invalid example handling
+ * ```typescript
+ * const result = parseExample({
+ *   value: {
+ *     type: 'number',
+ *     example: 'not a number', // Invalid example
+ *     minimum: 0
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.number(),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.example); // undefined (invalid example removed)
+ * // Context will log a warning about the invalid example
+ * ```
+ *
+ * @example Array example parsing
+ * ```typescript
+ * const result = parseExample({
+ *   value: {
+ *     type: 'array',
+ *     items: { type: 'string' },
+ *     example: ['item1', 'item2', 'item3']
+ *   },
+ *   nullable: false,
+ *   valibotSchema: v.array(v.string()),
+ *   context: parseContext
+ * });
+ *
+ * console.log(result.example); // ['item1', 'item2', 'item3']
+ * ```
+ */
 export const parseExample = ({ value, nullable, valibotSchema, context }) => {
     const { example, ...rest } = value;
     const parsedExample = context.provisionalParse({