@kravc/schema 2.7.6 → 2.8.0-alpha.1

package/src/helpers/normalizeRequired.ts

@@ -0,0 +1,233 @@
+import { isUndefined } from 'lodash';
+
+import type {
+  JsonSchema,
+  EnumSchema,
+  ObjectSchema,
+  ArrayPropertySchema,
+  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)
+ */
+const normalizeRequired = (jsonSchema: JsonSchema | ObjectPropertySchema | ReferencePropertySchema) => {
+  const { enum: enumItems } = (jsonSchema as EnumSchema);
+
+  const isEnum = !!enumItems;
+
+  if (isEnum) {
+    return;
+  }
+
+  const objectSchema = (jsonSchema as ObjectSchema);
+  const { properties } = objectSchema;
+
+  if (!properties) {
+    return;
+  }
+
+  const required = [];
+
+  for (const propertyName in properties) {
+    const property = properties[propertyName];
+
+    const { $ref: refSchemaId } = (property as ReferencePropertySchema);
+
+    const isReference = !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 as ObjectPropertySchema | ArrayPropertySchema);
+
+    const isObject = type === 'object';
+
+    if (isObject) {
+      normalizeRequired(property as ObjectPropertySchema);
+      continue;
+    }
+
+    const isArray = type === 'array';
+
+    if (isArray) {
+      const { items } = (property as ArrayPropertySchema);
+
+      if (items) {
+        normalizeRequired(items as ObjectPropertySchema | ReferencePropertySchema);
+      }
+
+      continue;
+    }
+  }
+
+  if (required.length > 0) {
+    objectSchema.required = required;
+  }
+};
+
+export default normalizeRequired;

package/src/helpers/normalizeType.ts

@@ -0,0 +1,235 @@
+type ValueType = 'number' | 'integer' | 'boolean' | 'string' | 'object' | 'array';
+
+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: unknown): value is null | undefined =>
+  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: ValueType): boolean => 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: ValueType): boolean => 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: unknown): value is number => 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: unknown): value is boolean => 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: unknown): value is string => 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: string): boolean =>
+  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: number): boolean => !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: string): boolean =>
+  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: string): boolean =>
+  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: ValueType, value: unknown): string | number | boolean | unknown => {
+  // 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;
+};
+
+export default normalizeType;

package/src/helpers/nullifyEmptyValues.ts

@@ -0,0 +1,207 @@
+import { get, set } from 'lodash';
+import { schemaSymbol, jsonSymbol, type SchemaErrorDetail } from 'z-schema';
+
+import type { TargetObject } from './JsonSchema';
+
+/**
+ * Format error codes that indicate validation failures due to format mismatches.
+ * These errors can potentially be resolved by converting empty strings to null.
+ */
+const FORMAT_ERROR_CODES = [
+  'PATTERN',
+  'ENUM_MISMATCH',
+  'INVALID_FORMAT'
+] as const;
+
+/**
+ * Values that are considered "empty" and can be safely converted to null.
+ */
+const EMPTY_VALUES = [''] as const;
+
+/**
+ * Converts empty string values to null for specific format validation errors.
+ * 
+ * **Intent:**
+ * This function provides a post-validation normalization strategy that attempts to
+ * resolve format validation errors by converting empty strings to null. This is
+ * particularly useful when dealing with optional fields where an empty string
+ * represents "no value provided" rather than an invalid format. By converting
+ * empty strings to null, the validation may pass if the schema allows null values
+ * for optional fields.
+ * 
+ * **Use Cases:**
+ * - **Optional field normalization**: When optional string fields receive empty
+ *   strings from user input or API responses, converting them to null allows
+ *   validation to succeed if the schema permits null values for optional fields.
+ *   This is especially common with form inputs that submit empty strings instead
+ *   of omitting fields entirely.
+ * - **Format error recovery**: After schema validation fails with format errors
+ *   (pattern mismatch, enum mismatch, invalid format), this function attempts to
+ *   resolve errors by nullifying empty strings. This enables graceful handling
+ *   of optional fields that failed format validation due to empty values.
+ * - **API integration**: When integrating with external APIs or services that
+ *   send empty strings for optional fields, this function normalizes the data
+ *   to use null instead, which is often more semantically correct for optional
+ *   fields in JSON schemas.
+ * - **Data transformation pipeline**: As part of a validation and normalization
+ *   pipeline, this function can be used to clean and normalize data before
+ *   further processing or storage, ensuring consistent representation of
+ *   "missing" values.
+ * - **User input handling**: When processing user-submitted forms or data where
+ *   empty string inputs should be treated as "not provided" rather than invalid,
+ *   this function converts them to null for proper schema validation.
+ * 
+ * **Behavior:**
+ * - Returns a deep clone of the input object (does not mutate the original)
+ * - Only processes format-related errors (PATTERN, ENUM_MISMATCH, INVALID_FORMAT)
+ * - Skips required attributes (marked with `x-required: true`)
+ * - Only converts empty strings (`''`) to null, preserving other values
+ * - Supports nested paths and array indices
+ * - Returns both the modified object and remaining validation errors that
+ *   couldn't be resolved
+ * 
+ * **Examples:**
+ * 
+ * ```typescript
+ * // Example 1: Basic usage with pattern error
+ * const object = { email: '' };
+ * const error = {
+ *   code: 'PATTERN',
+ *   path: '#/email',
+ *   // ... other error properties
+ * };
+ * const [result, remainingErrors] = nullifyEmptyValues(object, [error]);
+ * // result: { email: null }
+ * // remainingErrors: []
+ * ```
+ * 
+ * ```typescript
+ * // Example 2: Required fields are not nullified
+ * const object = { requiredField: '', optionalField: '' };
+ * const requiredError = {
+ *   code: 'PATTERN',
+ *   path: '#/requiredField',
+ *   // schema has x-required: true
+ * };
+ * const optionalError = {
+ *   code: 'PATTERN',
+ *   path: '#/optionalField',
+ *   // schema has no x-required or x-required: false
+ * };
+ * const [result, remainingErrors] = nullifyEmptyValues(
+ *   object,
+ *   [requiredError, optionalError]
+ * );
+ * // result: { requiredField: '', optionalField: null }
+ * // remainingErrors: [requiredError] // required field error remains
+ * ```
+ * 
+ * ```typescript
+ * // Example 3: Nested paths and arrays
+ * const object = {
+ *   user: {
+ *     profile: {
+ *       bio: '',
+ *       tags: ['', 'tag1', '']
+ *     }
+ *   }
+ * };
+ * const errors = [
+ *   { code: 'PATTERN', path: '#/user/profile/bio' },
+ *   { code: 'INVALID_FORMAT', path: '#/user/profile/tags/0' },
+ *   { code: 'ENUM_MISMATCH', path: '#/user/profile/tags/2' }
+ * ];
+ * const [result, remainingErrors] = nullifyEmptyValues(object, errors);
+ * // result: {
+ * //   user: {
+ * //     profile: {
+ * //       bio: null,
+ * //       tags: [null, 'tag1', null]
+ * //     }
+ * //   }
+ * // }
+ * // remainingErrors: []
+ * ```
+ * 
+ * ```typescript
+ * // Example 4: Non-format errors are not processed
+ * const object = { field: '' };
+ * const formatError = { code: 'PATTERN', path: '#/field' };
+ * const typeError = { code: 'INVALID_TYPE', path: '#/field' };
+ * const [result, remainingErrors] = nullifyEmptyValues(
+ *   object,
+ *   [formatError, typeError]
+ * );
+ * // result: { field: null }
+ * // remainingErrors: [typeError] // type error remains
+ * ```
+ * 
+ * ```typescript
+ * // Example 5: Non-empty values are preserved
+ * const object = { field: 'invalid-value' };
+ * const error = { code: 'PATTERN', path: '#/field' };
+ * const [result, remainingErrors] = nullifyEmptyValues(object, [error]);
+ * // result: { field: 'invalid-value' } // unchanged
+ * // remainingErrors: [error] // error remains
+ * ```
+ * 
+ * @param object - The target object to process (will be deep cloned, not mutated)
+ * @param validationErrors - Array of schema validation errors from z-schema
+ * @returns A tuple containing:
+ *   - `[0]`: Deep clone of the object with empty strings converted to null where applicable
+ *   - `[1]`: Array of validation errors that couldn't be resolved (required fields,
+ *            non-format errors, or errors for non-empty values)
+ */
+const nullifyEmptyValues = (
+  object: TargetObject,
+  validationErrors: SchemaErrorDetail[]
+): [TargetObject, SchemaErrorDetail[]] => {
+  // Create a deep clone to avoid mutating the original object
+  const result = JSON.parse(JSON.stringify(object)) as TargetObject;
+  const remainingErrors: SchemaErrorDetail[] = [];
+
+  for (const error of validationErrors) {
+    const { code, path: pathString } = error;
+    const schema = get(error, schemaSymbol) as Record<string, unknown> | undefined;
+    const isAttributeRequired = schema?.['x-required'] === true;
+    const isFormatError = FORMAT_ERROR_CODES.includes(code as typeof FORMAT_ERROR_CODES[number]);
+
+    const shouldSkipRequiredAttribute = isAttributeRequired;
+    const shouldSkipNonFormatError = !isFormatError;
+
+    // Skip required attributes - they should not be nullified
+    if (shouldSkipRequiredAttribute) {
+      remainingErrors.push(error);
+      continue;
+    }
+
+    // Only process format-related errors
+    if (shouldSkipNonFormatError) {
+      remainingErrors.push(error);
+      continue;
+    }
+
+    // Parse the JSON path (e.g., '#/user/profile/field' -> ['user', 'profile', 'field'])
+    const path = pathString.replace(/^#\//, '').split('/').filter(Boolean);
+
+    // Get the actual value from the error's JSON context
+    const json = get(error, jsonSymbol) as TargetObject;
+    const value = get(json, path);
+
+    const isEmptyValue = EMPTY_VALUES.includes(value as typeof EMPTY_VALUES[number]);
+    const shouldSkipNonEmptyValue = !isEmptyValue;
+
+    // Only nullify if the value is actually empty
+    if (shouldSkipNonEmptyValue) {
+      remainingErrors.push(error);
+      continue;
+    }
+
+    // Set the value to null in the result object
+    set(result, path, null);
+  }
+
+  return [result, remainingErrors];
+};
+
+export default nullifyEmptyValues;