@skmtc/core 0.0.795 → 0.0.797

package/script/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/script/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/script/oas/_helpers/parseEnum.js

@@ -35,6 +35,110 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseEnum = void 0;
 const v = __importStar(require("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]
+ * ```
+ */
 const parseEnum = ({ value, nullable, valibotSchema, context }) => {
     const { enum: enums, ...rest } = value;
     const parsedEnum = context.provisionalParse({

package/script/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/script/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/script/oas/_helpers/parseExample.js

@@ -35,6 +35,93 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseExample = void 0;
 const v = __importStar(require("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']
+ * ```
+ */
 const parseExample = ({ value, nullable, valibotSchema, context }) => {
     const { example, ...rest } = value;
     const parsedExample = context.provisionalParse({

package/script/oas/_helpers/parseFormat.d.ts

@@ -1,15 +1,169 @@
 import type { OpenAPIV3 } from 'openapi-types';
 import type { ParseContext } from '../../context/ParseContext.js';
 import * as v from 'valibot';
+/**
+ * Arguments for parsing OpenAPI schema format values.
+ *
+ * @template T - The expected type of the format value
+ */
 type ParseFormatArgs<T> = {
+    /** The OpenAPI schema object with processed properties removed */
     value: Omit<OpenAPIV3.SchemaObject, 'nullable' | 'example' | 'enums'>;
+    /** Valibot schema for validating the format value */
     valibotSchema: v.GenericSchema<T>;
+    /** Parse context for error handling */
     context: ParseContext;
 };
+/**
+ * Return type for parsed format data.
+ *
+ * @template T - The expected type of the format value
+ * @template Value - The OpenAPI schema object type
+ */
 type ParseFormatReturn<T, Value extends OpenAPIV3.SchemaObject> = {
+    /** The parsed and validated format string */
     format: T | undefined;
+    /** The schema object without the format property */
     value: Omit<Value, 'format'>;
 };
+/**
+ * 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 declare const parseFormat: <T, Value extends OpenAPIV3.SchemaObject>({ value, valibotSchema, context }: ParseFormatArgs<T>) => ParseFormatReturn<T, Value>;
 export {};
 //# sourceMappingURL=parseFormat.d.ts.map

package/script/oas/_helpers/parseFormat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseFormat.d.ts","sourceRoot":"","sources":["../../../src/oas/_helpers/parseFormat.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,eAAe,CAAC,CAAC,IAAI;IACxB,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC,CAAA;IACrE,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAA;IACjC,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED,KAAK,iBAAiB,CAAC,CAAC,EAAE,KAAK,SAAS,SAAS,CAAC,YAAY,IAAI;IAChE,MAAM,EAAE,CAAC,GAAG,SAAS,CAAA;IACrB,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;CAC7B,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,KAAK,SAAS,SAAS,CAAC,YAAY,EAAE,mCAIlE,eAAe,CAAC,CAAC,CAAC,KAAG,iBAAiB,CAAC,CAAC,EAAE,KAAK,CAgBjD,CAAA"}
+{"version":3,"file":"parseFormat.d.ts","sourceRoot":"","sources":["../../../src/oas/_helpers/parseFormat.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;;;;GAIG;AACH,KAAK,eAAe,CAAC,CAAC,IAAI;IACxB,kEAAkE;IAClE,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC,CAAA;IACrE,qDAAqD;IACrD,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAA;IACjC,uCAAuC;IACvC,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED;;;;;GAKG;AACH,KAAK,iBAAiB,CAAC,CAAC,EAAE,KAAK,SAAS,SAAS,CAAC,YAAY,IAAI;IAChE,6CAA6C;IAC7C,MAAM,EAAE,CAAC,GAAG,SAAS,CAAA;IACrB,oDAAoD;IACpD,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;CAC7B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyIG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,KAAK,SAAS,SAAS,CAAC,YAAY,EAAE,mCAIlE,eAAe,CAAC,CAAC,CAAC,KAAG,iBAAiB,CAAC,CAAC,EAAE,KAAK,CAgBjD,CAAA"}