@skmtc/core 0.0.796 → 0.0.797

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"}

package/script/oas/_helpers/parseFormat.js

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

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

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