@kravc/schema 2.7.5 → 2.8.0-alpha.0

package/dist/helpers/normalizeRequired.d.ts

@@ -0,0 +1,159 @@
+import type { JsonSchema, ObjectPropertySchema, ReferencePropertySchema } from './JsonSchema';
+/**
+ * Normalizes required field declarations in JSON schemas by converting property-level
+ * `required` flags to schema-level `required` arrays and `x-required` metadata flags.
+ *
+ * **Intent:**
+ * This function transforms JSON schemas from a property-centric required field model
+ * (where each property has its own `required: true/false` flag) to the standard JSON Schema
+ * format (where required fields are listed in a top-level `required` array). This normalization
+ * ensures compatibility with JSON Schema validators while preserving the original required
+ * field information through the `x-required` extension attribute.
+ *
+ * **Use Cases:**
+ * 1. **Schema Standardization**: Convert custom schema formats to standard JSON Schema format
+ *    for validator compatibility
+ * 2. **Schema Transformation**: Prepare schemas for validation libraries that expect
+ *    required fields in array format
+ * 3. **Metadata Preservation**: Maintain required field information in both standard format
+ *    (`required` array) and extension format (`x-required` flag) for different use cases
+ * 4. **Schema Processing Pipeline**: Normalize schemas before validation, credential generation,
+ *    or API documentation generation
+ *
+ * **Behavior:**
+ * - Mutates the input schema in-place
+ * - Moves `required: true` from property level to schema-level `required` array
+ * - Sets `x-required: true` on properties that were marked as required
+ * - Deletes the `required` property from individual property schemas
+ * - Recursively processes nested object properties
+ * - Recursively processes array items (including nested objects within arrays)
+ * - Skips reference properties (`$ref`) as they are resolved elsewhere
+ * - Skips EnumSchema (returns early)
+ * - Only sets `required` array if at least one field is required
+ *
+ * **Examples:**
+ *
+ * ```typescript
+ * // Example 1: Simple object schema
+ * const schema = {
+ *   id: 'User',
+ *   properties: {
+ *     name: { type: 'string', required: true },
+ *     email: { type: 'string', required: true },
+ *     age: { type: 'number', required: false }
+ *   }
+ * };
+ *
+ * normalizeRequired(schema);
+ * // Result:
+ * // schema.required = ['name', 'email']
+ * // schema.properties.name['x-required'] = true
+ * // schema.properties.email['x-required'] = true
+ * // schema.properties.name.required = undefined (deleted)
+ * // schema.properties.email.required = undefined (deleted)
+ * ```
+ *
+ * ```typescript
+ * // Example 2: Nested objects
+ * const schema = {
+ *   id: 'Order',
+ *   properties: {
+ *     user: {
+ *       type: 'object',
+ *       required: true,
+ *       properties: {
+ *         name: { type: 'string', required: true },
+ *         address: {
+ *           type: 'object',
+ *           properties: {
+ *             street: { type: 'string', required: true }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * normalizeRequired(schema);
+ * // Result:
+ * // schema.required = ['user']
+ * // schema.properties.user['x-required'] = true
+ * // schema.properties.user.required = ['name']
+ * // schema.properties.user.properties.name['x-required'] = true
+ * // schema.properties.user.properties.address.required = ['street']
+ * // schema.properties.user.properties.address.properties.street['x-required'] = true
+ * ```
+ *
+ * ```typescript
+ * // Example 3: Arrays with object items
+ * const schema = {
+ *   id: 'Order',
+ *   properties: {
+ *     items: {
+ *       type: 'array',
+ *       required: true,
+ *       items: {
+ *         type: 'object',
+ *         properties: {
+ *           productId: { type: 'string', required: true },
+ *           quantity: { type: 'number', required: true }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * normalizeRequired(schema);
+ * // Result:
+ * // schema.required = ['items']
+ * // schema.properties.items['x-required'] = true
+ * // schema.properties.items.items.required = ['productId', 'quantity']
+ * // schema.properties.items.items.properties.productId['x-required'] = true
+ * // schema.properties.items.items.properties.quantity['x-required'] = true
+ * ```
+ *
+ * ```typescript
+ * // Example 4: Mixed structure
+ * const schema = {
+ *   id: 'Profile',
+ *   properties: {
+ *     name: { type: 'string', required: true },
+ *     address: {
+ *       type: 'object',
+ *       required: true,
+ *       properties: {
+ *         street: { type: 'string', required: true },
+ *         city: { type: 'string' }
+ *       }
+ *     },
+ *     tags: {
+ *       type: 'array',
+ *       items: {
+ *         type: 'object',
+ *         properties: {
+ *           label: { type: 'string', required: true }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * normalizeRequired(schema);
+ * // Result:
+ * // schema.required = ['name', 'address']
+ * // All nested required fields are normalized recursively
+ * ```
+ *
+ * **Limitations:**
+ * - Only processes schemas with a `properties` field (ObjectSchema or ObjectPropertySchema)
+ * - EnumSchema is accepted but returns early without processing
+ * - Reference properties (`$ref`) are skipped and not processed
+ * - The function mutates the input schema object
+ * - Does not resolve `$ref` references (they must be resolved separately)
+ *
+ * @param jsonSchema - The JSON schema to normalize (ObjectSchema, ObjectPropertySchema, or ReferencePropertySchema)
+ * @returns void (mutates the input schema in-place)
+ */
+declare const normalizeRequired: (jsonSchema: JsonSchema | ObjectPropertySchema | ReferencePropertySchema) => void;
+export default normalizeRequired;
+//# sourceMappingURL=normalizeRequired.d.ts.map

package/dist/helpers/normalizeRequired.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeRequired.d.ts","sourceRoot":"","sources":["../../src/helpers/normalizeRequired.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EAIV,oBAAoB,EACpB,uBAAuB,EACxB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0JG;AACH,QAAA,MAAM,iBAAiB,GAAI,YAAY,UAAU,GAAG,oBAAoB,GAAG,uBAAuB,SAgEjG,CAAC;AAEF,eAAe,iBAAiB,CAAC"}

package/dist/helpers/normalizeRequired.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const lodash_1 = require("lodash");
+/**
+ * Normalizes required field declarations in JSON schemas by converting property-level
+ * `required` flags to schema-level `required` arrays and `x-required` metadata flags.
+ *
+ * **Intent:**
+ * This function transforms JSON schemas from a property-centric required field model
+ * (where each property has its own `required: true/false` flag) to the standard JSON Schema
+ * format (where required fields are listed in a top-level `required` array). This normalization
+ * ensures compatibility with JSON Schema validators while preserving the original required
+ * field information through the `x-required` extension attribute.
+ *
+ * **Use Cases:**
+ * 1. **Schema Standardization**: Convert custom schema formats to standard JSON Schema format
+ *    for validator compatibility
+ * 2. **Schema Transformation**: Prepare schemas for validation libraries that expect
+ *    required fields in array format
+ * 3. **Metadata Preservation**: Maintain required field information in both standard format
+ *    (`required` array) and extension format (`x-required` flag) for different use cases
+ * 4. **Schema Processing Pipeline**: Normalize schemas before validation, credential generation,
+ *    or API documentation generation
+ *
+ * **Behavior:**
+ * - Mutates the input schema in-place
+ * - Moves `required: true` from property level to schema-level `required` array
+ * - Sets `x-required: true` on properties that were marked as required
+ * - Deletes the `required` property from individual property schemas
+ * - Recursively processes nested object properties
+ * - Recursively processes array items (including nested objects within arrays)
+ * - Skips reference properties (`$ref`) as they are resolved elsewhere
+ * - Skips EnumSchema (returns early)
+ * - Only sets `required` array if at least one field is required
+ *
+ * **Examples:**
+ *
+ * ```typescript
+ * // Example 1: Simple object schema
+ * const schema = {
+ *   id: 'User',
+ *   properties: {
+ *     name: { type: 'string', required: true },
+ *     email: { type: 'string', required: true },
+ *     age: { type: 'number', required: false }
+ *   }
+ * };
+ *
+ * normalizeRequired(schema);
+ * // Result:
+ * // schema.required = ['name', 'email']
+ * // schema.properties.name['x-required'] = true
+ * // schema.properties.email['x-required'] = true
+ * // schema.properties.name.required = undefined (deleted)
+ * // schema.properties.email.required = undefined (deleted)
+ * ```
+ *
+ * ```typescript
+ * // Example 2: Nested objects
+ * const schema = {
+ *   id: 'Order',
+ *   properties: {
+ *     user: {
+ *       type: 'object',
+ *       required: true,
+ *       properties: {
+ *         name: { type: 'string', required: true },
+ *         address: {
+ *           type: 'object',
+ *           properties: {
+ *             street: { type: 'string', required: true }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * normalizeRequired(schema);
+ * // Result:
+ * // schema.required = ['user']
+ * // schema.properties.user['x-required'] = true
+ * // schema.properties.user.required = ['name']
+ * // schema.properties.user.properties.name['x-required'] = true
+ * // schema.properties.user.properties.address.required = ['street']
+ * // schema.properties.user.properties.address.properties.street['x-required'] = true
+ * ```
+ *
+ * ```typescript
+ * // Example 3: Arrays with object items
+ * const schema = {
+ *   id: 'Order',
+ *   properties: {
+ *     items: {
+ *       type: 'array',
+ *       required: true,
+ *       items: {
+ *         type: 'object',
+ *         properties: {
+ *           productId: { type: 'string', required: true },
+ *           quantity: { type: 'number', required: true }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * normalizeRequired(schema);
+ * // Result:
+ * // schema.required = ['items']
+ * // schema.properties.items['x-required'] = true
+ * // schema.properties.items.items.required = ['productId', 'quantity']
+ * // schema.properties.items.items.properties.productId['x-required'] = true
+ * // schema.properties.items.items.properties.quantity['x-required'] = true
+ * ```
+ *
+ * ```typescript
+ * // Example 4: Mixed structure
+ * const schema = {
+ *   id: 'Profile',
+ *   properties: {
+ *     name: { type: 'string', required: true },
+ *     address: {
+ *       type: 'object',
+ *       required: true,
+ *       properties: {
+ *         street: { type: 'string', required: true },
+ *         city: { type: 'string' }
+ *       }
+ *     },
+ *     tags: {
+ *       type: 'array',
+ *       items: {
+ *         type: 'object',
+ *         properties: {
+ *           label: { type: 'string', required: true }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * normalizeRequired(schema);
+ * // Result:
+ * // schema.required = ['name', 'address']
+ * // All nested required fields are normalized recursively
+ * ```
+ *
+ * **Limitations:**
+ * - Only processes schemas with a `properties` field (ObjectSchema or ObjectPropertySchema)
+ * - EnumSchema is accepted but returns early without processing
+ * - Reference properties (`$ref`) are skipped and not processed
+ * - The function mutates the input schema object
+ * - Does not resolve `$ref` references (they must be resolved separately)
+ *
+ * @param jsonSchema - The JSON schema to normalize (ObjectSchema, ObjectPropertySchema, or ReferencePropertySchema)
+ * @returns void (mutates the input schema in-place)
+ */
+const normalizeRequired = (jsonSchema) => {
+    const { enum: enumItems } = jsonSchema;
+    const isEnum = !!enumItems;
+    if (isEnum) {
+        return;
+    }
+    const objectSchema = jsonSchema;
+    const { properties } = objectSchema;
+    if (!properties) {
+        return;
+    }
+    const required = [];
+    for (const propertyName in properties) {
+        const property = properties[propertyName];
+        const { $ref: refSchemaId } = property;
+        const isReference = !(0, lodash_1.isUndefined)(refSchemaId);
+        // Handle required flag for all properties (including references)
+        if (property.required) {
+            property['x-required'] = true;
+            required.push(propertyName);
+        }
+        // Delete required property for all properties (whether true or false)
+        delete property.required;
+        // Skip recursive processing for reference properties
+        if (isReference) {
+            continue;
+        }
+        const { type } = property;
+        const isObject = type === 'object';
+        if (isObject) {
+            normalizeRequired(property);
+            continue;
+        }
+        const isArray = type === 'array';
+        if (isArray) {
+            const { items } = property;
+            if (items) {
+                normalizeRequired(items);
+            }
+            continue;
+        }
+    }
+    if (required.length > 0) {
+        objectSchema.required = required;
+    }
+};
+exports.default = normalizeRequired;
+//# sourceMappingURL=normalizeRequired.js.map

package/dist/helpers/normalizeRequired.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeRequired.js","sourceRoot":"","sources":["../../src/helpers/normalizeRequired.ts"],"names":[],"mappings":";;AAAA,mCAAqC;AAWrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0JG;AACH,MAAM,iBAAiB,GAAG,CAAC,UAAuE,EAAE,EAAE;IACpG,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAI,UAAyB,CAAC;IAEvD,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC;IAE3B,IAAI,MAAM,EAAE,CAAC;QACX,OAAO;IACT,CAAC;IAED,MAAM,YAAY,GAAI,UAA2B,CAAC;IAClD,MAAM,EAAE,UAAU,EAAE,GAAG,YAAY,CAAC;IAEpC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO;IACT,CAAC;IAED,MAAM,QAAQ,GAAG,EAAE,CAAC;IAEpB,KAAK,MAAM,YAAY,IAAI,UAAU,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;QAE1C,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,GAAI,QAAoC,CAAC;QAEpE,MAAM,WAAW,GAAG,CAAC,IAAA,oBAAW,EAAC,WAAW,CAAC,CAAC;QAE9C,iEAAiE;QACjE,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACtB,QAAQ,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;YAC9B,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC9B,CAAC;QAED,sEAAsE;QACtE,OAAO,QAAQ,CAAC,QAAQ,CAAC;QAEzB,qDAAqD;QACrD,IAAI,WAAW,EAAE,CAAC;YAChB,SAAS;QACX,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,GAAI,QAAuD,CAAC;QAE1E,MAAM,QAAQ,GAAG,IAAI,KAAK,QAAQ,CAAC;QAEnC,IAAI,QAAQ,EAAE,CAAC;YACb,iBAAiB,CAAC,QAAgC,CAAC,CAAC;YACpD,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,KAAK,OAAO,CAAC;QAEjC,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,EAAE,KAAK,EAAE,GAAI,QAAgC,CAAC;YAEpD,IAAI,KAAK,EAAE,CAAC;gBACV,iBAAiB,CAAC,KAAuD,CAAC,CAAC;YAC7E,CAAC;YAED,SAAS;QACX,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,YAAY,CAAC,QAAQ,GAAG,QAAQ,CAAC;IACnC,CAAC;AACH,CAAC,CAAC;AAEF,kBAAe,iBAAiB,CAAC"}

package/dist/helpers/normalizeType.d.ts

@@ -0,0 +1,81 @@
+type ValueType = 'number' | 'integer' | 'boolean' | 'string' | 'object' | 'array';
+/**
+ * Normalizes a value to match a specified JSON Schema type.
+ *
+ * ## Intent
+ *
+ * This function is designed to coerce values into their expected types based on JSON Schema
+ * type definitions. It's particularly useful when processing data from external sources (like
+ * form inputs, query parameters, or API responses) where values may arrive as strings but
+ * need to be converted to their proper types according to a schema definition.
+ *
+ * The function performs type coercion where appropriate, but preserves the original value
+ * when conversion is not possible or when the value is already of the correct type. This
+ * makes it safe to use in data normalization pipelines without losing information.
+ *
+ * ## Use Cases
+ *
+ * 1. **Schema-based data normalization**: When processing objects against JSON Schema
+ *    definitions, ensuring property values match their declared types.
+ *
+ * 2. **Form data processing**: Converting string values from HTML forms (which are always
+ *    strings) to their expected types (numbers, booleans) based on schema definitions.
+ *
+ * 3. **API response normalization**: Normalizing API responses where types may be ambiguous
+ *    or incorrectly serialized (e.g., numbers as strings, booleans as strings).
+ *
+ * 4. **Configuration parsing**: Parsing configuration values from environment variables or
+ *    config files where everything is initially a string but needs type coercion.
+ *
+ * ## Behavior by Type
+ *
+ * - **number/integer**: Attempts to convert strings and booleans to numbers. Preserves
+ *   original value if conversion fails or value is already a number.
+ *
+ * - **boolean**: Converts numbers (0 → false, non-zero → true) and recognized string
+ *   values ('yes', 'true', '1' → true; 'no', 'false', '0' → false). Preserves original
+ *   value for unrecognized strings or non-convertible types.
+ *
+ * - **string/object/array**: Returns the value as-is (no conversion performed).
+ *
+ * - **null/undefined**: Always preserved regardless of target type.
+ *
+ * ## Examples
+ *
+ * ### Number Conversion
+ * ```typescript
+ * normalizeType('number', '123')      // → 123
+ * normalizeType('number', '45.67')    // → 45.67
+ * normalizeType('number', '0')        // → 0
+ * normalizeType('number', true)       // → 1
+ * normalizeType('number', 'abc')      // → 'abc' (conversion failed, original preserved)
+ * ```
+ *
+ * ### Boolean Conversion
+ * ```typescript
+ * normalizeType('boolean', 0)         // → false
+ * normalizeType('boolean', 1)         // → true
+ * normalizeType('boolean', 'yes')     // → true
+ * normalizeType('boolean', 'true')    // → true
+ * normalizeType('boolean', '1')       // → true
+ * normalizeType('boolean', 'no')      // → false
+ * normalizeType('boolean', 'false')   // → false
+ * normalizeType('boolean', 'maybe')   // → 'maybe' (unrecognized, original preserved)
+ * ```
+ *
+ * ### Type Preservation
+ * ```typescript
+ * normalizeType('string', 'hello')    // → 'hello'
+ * normalizeType('string', 123)        // → 123 (no conversion for string type)
+ * normalizeType('object', { a: 1 })   // → { a: 1 }
+ * normalizeType('array', [1, 2, 3])   // → [1, 2, 3]
+ * normalizeType('number', null)       // → null (null always preserved)
+ * ```
+ *
+ * @param type - The target JSON Schema type ('number', 'integer', 'boolean', 'string', 'object', 'array')
+ * @param value - The value to normalize (can be any type)
+ * @returns The normalized value, or the original value if normalization is not applicable
+ */
+declare const normalizeType: (type: ValueType, value: unknown) => string | number | boolean | unknown;
+export default normalizeType;
+//# sourceMappingURL=normalizeType.d.ts.map

package/dist/helpers/normalizeType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeType.d.ts","sourceRoot":"","sources":["../../src/helpers/normalizeType.ts"],"names":[],"mappings":"AAAA,KAAK,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AA2FlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,QAAA,MAAM,aAAa,GAAI,MAAM,SAAS,EAAE,OAAO,OAAO,KAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAgEpF,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/dist/helpers/normalizeType.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const BOOLEAN_STRING_TRUE_VALUES = ['yes', 'true', '1'];
+const BOOLEAN_STRING_FALSE_VALUES = ['no', 'false', '0'];
+/**
+ * Checks if a value is null or undefined.
+ *
+ * @param value - The value to check
+ * @returns True if the value is null or undefined, false otherwise
+ */
+const isNullOrUndefined = (value) => value === null || value === undefined;
+/**
+ * Checks if a JSON Schema type is numeric (number or integer).
+ *
+ * @param type - The JSON Schema type to check
+ * @returns True if the type is 'number' or 'integer', false otherwise
+ */
+const isNumericType = (type) => type === 'number' || type === 'integer';
+/**
+ * Checks if a JSON Schema type is boolean.
+ *
+ * @param type - The JSON Schema type to check
+ * @returns True if the type is 'boolean', false otherwise
+ */
+const isBooleanType = (type) => type === 'boolean';
+/**
+ * Type guard that checks if a value is a number.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a number, false otherwise
+ */
+const isNumberValue = (value) => typeof value === 'number';
+/**
+ * Type guard that checks if a value is a boolean.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a boolean, false otherwise
+ */
+const isBooleanValue = (value) => typeof value === 'boolean';
+/**
+ * Type guard that checks if a value is a string.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a string, false otherwise
+ */
+const isStringValue = (value) => typeof value === 'string';
+/**
+ * Checks if a string is empty or contains only whitespace characters.
+ *
+ * @param value - The string to check
+ * @returns True if the string is empty or whitespace-only, false otherwise
+ */
+const isEmptyOrWhitespaceString = (value) => value === '' || value.trim() === '';
+/**
+ * Checks if a number is valid (not NaN).
+ *
+ * @param value - The number to check
+ * @returns True if the number is valid (not NaN), false otherwise
+ */
+const isValidNumber = (value) => !isNaN(value);
+/**
+ * Checks if a string represents a boolean true value.
+ * Recognized values (case-insensitive): 'yes', 'true', '1'.
+ *
+ * @param value - The string to check
+ * @returns True if the string represents a boolean true value, false otherwise
+ */
+const isBooleanTrueString = (value) => BOOLEAN_STRING_TRUE_VALUES.includes(value.toLowerCase());
+/**
+ * Checks if a string represents a boolean false value.
+ * Recognized values (case-insensitive): 'no', 'false', '0'.
+ *
+ * @param value - The string to check
+ * @returns True if the string represents a boolean false value, false otherwise
+ */
+const isBooleanFalseString = (value) => BOOLEAN_STRING_FALSE_VALUES.includes(value.toLowerCase());
+/**
+ * Normalizes a value to match a specified JSON Schema type.
+ *
+ * ## Intent
+ *
+ * This function is designed to coerce values into their expected types based on JSON Schema
+ * type definitions. It's particularly useful when processing data from external sources (like
+ * form inputs, query parameters, or API responses) where values may arrive as strings but
+ * need to be converted to their proper types according to a schema definition.
+ *
+ * The function performs type coercion where appropriate, but preserves the original value
+ * when conversion is not possible or when the value is already of the correct type. This
+ * makes it safe to use in data normalization pipelines without losing information.
+ *
+ * ## Use Cases
+ *
+ * 1. **Schema-based data normalization**: When processing objects against JSON Schema
+ *    definitions, ensuring property values match their declared types.
+ *
+ * 2. **Form data processing**: Converting string values from HTML forms (which are always
+ *    strings) to their expected types (numbers, booleans) based on schema definitions.
+ *
+ * 3. **API response normalization**: Normalizing API responses where types may be ambiguous
+ *    or incorrectly serialized (e.g., numbers as strings, booleans as strings).
+ *
+ * 4. **Configuration parsing**: Parsing configuration values from environment variables or
+ *    config files where everything is initially a string but needs type coercion.
+ *
+ * ## Behavior by Type
+ *
+ * - **number/integer**: Attempts to convert strings and booleans to numbers. Preserves
+ *   original value if conversion fails or value is already a number.
+ *
+ * - **boolean**: Converts numbers (0 → false, non-zero → true) and recognized string
+ *   values ('yes', 'true', '1' → true; 'no', 'false', '0' → false). Preserves original
+ *   value for unrecognized strings or non-convertible types.
+ *
+ * - **string/object/array**: Returns the value as-is (no conversion performed).
+ *
+ * - **null/undefined**: Always preserved regardless of target type.
+ *
+ * ## Examples
+ *
+ * ### Number Conversion
+ * ```typescript
+ * normalizeType('number', '123')      // → 123
+ * normalizeType('number', '45.67')    // → 45.67
+ * normalizeType('number', '0')        // → 0
+ * normalizeType('number', true)       // → 1
+ * normalizeType('number', 'abc')      // → 'abc' (conversion failed, original preserved)
+ * ```
+ *
+ * ### Boolean Conversion
+ * ```typescript
+ * normalizeType('boolean', 0)         // → false
+ * normalizeType('boolean', 1)         // → true
+ * normalizeType('boolean', 'yes')     // → true
+ * normalizeType('boolean', 'true')    // → true
+ * normalizeType('boolean', '1')       // → true
+ * normalizeType('boolean', 'no')      // → false
+ * normalizeType('boolean', 'false')   // → false
+ * normalizeType('boolean', 'maybe')   // → 'maybe' (unrecognized, original preserved)
+ * ```
+ *
+ * ### Type Preservation
+ * ```typescript
+ * normalizeType('string', 'hello')    // → 'hello'
+ * normalizeType('string', 123)        // → 123 (no conversion for string type)
+ * normalizeType('object', { a: 1 })   // → { a: 1 }
+ * normalizeType('array', [1, 2, 3])   // → [1, 2, 3]
+ * normalizeType('number', null)       // → null (null always preserved)
+ * ```
+ *
+ * @param type - The target JSON Schema type ('number', 'integer', 'boolean', 'string', 'object', 'array')
+ * @param value - The value to normalize (can be any type)
+ * @returns The normalized value, or the original value if normalization is not applicable
+ */
+const normalizeType = (type, value) => {
+    // Preserve null and undefined values regardless of target type
+    if (isNullOrUndefined(value)) {
+        return value;
+    }
+    // Handle number and integer types
+    if (isNumericType(type)) {
+        // If already a number, return as-is
+        if (isNumberValue(value)) {
+            return value;
+        }
+        // Convert booleans to numbers: true → 1, false → 0
+        if (isBooleanValue(value)) {
+            return value ? 1 : 0;
+        }
+        // Attempt conversion for strings
+        if (isStringValue(value)) {
+            // Preserve empty strings and whitespace-only strings
+            if (isEmptyOrWhitespaceString(value)) {
+                return value;
+            }
+            const converted = Number(value);
+            // Check if conversion was successful (not NaN)
+            if (isValidNumber(converted)) {
+                return converted;
+            }
+        }
+        // Return original value if conversion failed or type is not convertible
+        return value;
+    }
+    // Handle boolean type
+    if (isBooleanType(type)) {
+        // If already a boolean, return as-is
+        if (isBooleanValue(value)) {
+            return value;
+        }
+        // Convert numbers: 0 → false, non-zero → true
+        if (isNumberValue(value)) {
+            return Boolean(value);
+        }
+        // Convert recognized string values
+        if (isStringValue(value)) {
+            if (isBooleanTrueString(value)) {
+                return true;
+            }
+            if (isBooleanFalseString(value)) {
+                return false;
+            }
+        }
+        // Return original value for unrecognized strings or non-convertible types
+        return value;
+    }
+    // For string, object, and array types, return value as-is (no conversion)
+    return value;
+};
+exports.default = normalizeType;
+//# sourceMappingURL=normalizeType.js.map

package/dist/helpers/normalizeType.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeType.js","sourceRoot":"","sources":["../../src/helpers/normalizeType.ts"],"names":[],"mappings":"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"}