@kravc/schema 2.8.0-alpha.6 → 2.8.0-alpha.8

package/src/helpers/got.ts

@@ -2,65 +2,9 @@ import { get, isUndefined } from 'lodash';
 
 const DEFAULT_ERROR_TEMPLATE = 'Value is undefined for "$PATH"';
 
-/**
- * Safe required property access: returns a value at `path` or throws if it is `undefined`.
- *
- * **Intent:** Provide strict, fail-fast access to nested object properties. Unlike `lodash/get`,
- * which returns `undefined` for missing keys, `got` treats missing data as an error and throws
- * with a clear message including the path. Use it when the property is required and absence
- * indicates a bug or invalid input.
- *
- * **Use cases:**
- * - **Schema / config lookups:** Fetching a schema or config by ID from a map where absence
- *   means invalid reference (e.g. `got(schemasMap, schemaId, 'Schema "$PATH" not found')`).
- * - **Validated config access:** Reading required config or options after validation, when
- *   you want to avoid `undefined` checks downstream.
- * - **Strict data traversal:** Walking nested structures (APIs, parsed JSON) where missing
- *   keys should fail immediately with a descriptive error instead of propagating `undefined`.
- *
- * **Behavior:** Only `undefined` triggers an error. Falsy but defined values (`null`, `0`,
- * `false`, `''`, `[]`, `{}`) are returned as-is. Uses lodash `get` path syntax: dot notation
- * (`a.b.c`), bracket notation (`items[0]`), or mixed (`data.items[0].id`).
- *
- * @param object - Root object to read from.
- * @param path - Lodash-style path (e.g. `'user.profile.name'`, `'items[0].id'`).
- * @param errorTemplate - Error message template; `$PATH` is replaced with `path`. Default:
- *   `'Value is undefined for "$PATH"'`.
- * @returns The value at `path`.
- * @throws {Error} When the value at `path` is `undefined`.
- *
- * @example
- * // Simple property
- * got({ name: 'Jane' }, 'name');
- * // => 'Jane'
- *
- * @example
- * // Nested path
- * got({ user: { profile: { role: 'admin' } } }, 'user.profile.role');
- * // => 'admin'
- *
- * @example
- * // Array index
- * got({ items: ['a', 'b'] }, 'items[0]');
- * // => 'a'
- *
- * @example
- * // Falsy but defined values are returned
- * got({ count: 0, enabled: false }, 'count');
- * // => 0
- *
- * @example
- * // Custom error for schema lookups
- * got(schemasMap, schemaId, 'Schema "$PATH" not found');
- * // => schema for schemaId, or throws with that message
- *
- * @example
- * // Missing property throws
- * got({ name: 'Jane' }, 'age');
- * // throws Error('Value is undefined for "age"')
- */
-function got<T>(object: Record<string, T>, path: string, errorTemplate: string = DEFAULT_ERROR_TEMPLATE): T {
-  const value = get(object, path);
+/** Safe required property access: returns a value at `path` or throws if it is `undefined`. */
+function got<T>(object: T, path: string, errorTemplate: string = DEFAULT_ERROR_TEMPLATE): T[keyof T]{
+  const value = get(object, path) as T[keyof T];
   const shouldThrow = isUndefined(value);
 
   if (!shouldThrow) {

package/src/helpers/mapObjectProperties.ts

@@ -1,168 +1,16 @@
 import { isUndefined } from 'lodash';
+import { type JsonSchema } from 'z-schema';
 
 import got from './got';
-import type {
-  JsonSchema,
-  EnumSchema,
-  ObjectSchema,
-  TargetObject,
-  PropertySchema,
-  JsonSchemasMap,
-  ArrayPropertySchema,
-  ObjectPropertySchema,
-  ReferencePropertySchema,
-} from './JsonSchema';
 
 /**
  * Recursively traverses an object's properties based on a JSON schema and applies a callback
  * function to each property. Handles nested objects, arrays, and schema references ($ref).
- *
- * **Intent:**
- * This function provides a generic way to iterate over object properties in a schema-aware manner,
- * enabling operations like normalization, validation, transformation, or cleanup to be applied
- * consistently across complex nested data structures. It abstracts away the complexity of
- * traversing nested objects, arrays, and schema references, allowing callers to focus on
- * implementing their specific property-level logic.
- *
- * **Use Cases:**
- * - **Normalization**: Apply type conversions or default values to properties based on schema definitions
- *   (see `normalizeAttributes.ts` for example)
- * - **Validation**: Check property values against schema constraints
- * - **Transformation**: Modify or transform property values based on schema metadata
- * - **Cleanup**: Remove invalid properties or sanitize data structures
- * - **Data Processing**: Extract, aggregate, or analyze properties across nested structures
- * - **Schema-driven Operations**: Any operation that needs to process object properties according
- *   to their schema definitions
- *
- * **Behavior:**
- * - Skips enum schemas (returns immediately without calling callback)
- * - Calls callback for all properties defined in the schema, even if their values are null
- * - Skips recursion into undefined values (callback is still called, but nested traversal stops)
- * - Recursively processes nested objects by creating nested schema contexts
- * - Recursively processes array items, handling both inline object schemas and references
- * - Resolves schema references ($ref) using the provided schemasMap
- *
- * **Examples:**
- *
- * @example
- * // Example 1: Normalize property values based on schema types
- * const schema = new Schema({
- *   name: { type: 'string' },
- *   age: { type: 'number' },
- *   active: { type: 'boolean' }
- * }, 'user-schema');
- *
- * const user = {
- *   name: 'John',
- *   age: '30', // string that should be number
- *   active: 'true' // string that should be boolean
- * };
- *
- * mapObjectProperties(user, schema.jsonSchema, {}, (propName, propSchema, obj) => {
- *   if (propSchema.type === 'number') {
- *     obj[propName] = Number(obj[propName]);
- *   } else if (propSchema.type === 'boolean') {
- *     obj[propName] = obj[propName] === 'true' || obj[propName] === true;
- *   }
- * });
- * // Result: { name: 'John', age: 30, active: true }
- *
- * @example
- * // Example 2: Process nested objects
- * const schema = new Schema({
- *   profile: {
- *     type: 'object',
- *     properties: {
- *       firstName: { type: 'string' },
- *       lastName: { type: 'string' }
- *     }
- *   }
- * }, 'user-schema');
- *
- * const user = {
- *   profile: {
- *     firstName: 'John',
- *     lastName: 'Doe'
- *   }
- * };
- *
- * const processedProps: string[] = [];
- * mapObjectProperties(user, schema.jsonSchema, {}, (propName) => {
- *   processedProps.push(propName);
- * });
- * // processedProps: ['profile', 'firstName', 'lastName']
- *
- * @example
- * // Example 3: Handle schema references ($ref)
- * const addressSchema = new Schema({
- *   street: { type: 'string' },
- *   city: { type: 'string' }
- * }, 'address-schema');
- *
- * const userSchema = new Schema({
- *   name: { type: 'string' },
- *   address: { $ref: 'address-schema' }
- * }, 'user-schema');
- *
- * const user = {
- *   name: 'John',
- *   address: {
- *     street: '123 Main St',
- *     city: 'New York'
- *   }
- * };
- *
- * const schemasMap = {
- *   'address-schema': addressSchema.jsonSchema
- * };
- *
- * mapObjectProperties(user, userSchema.jsonSchema, schemasMap, (propName) => {
- *   console.log(`Processing: ${propName}`);
- * });
- * // Output:
- * // Processing: name
- * // Processing: address
- * // Processing: street
- * // Processing: city
- *
- * @example
- * // Example 4: Process arrays with object items
- * const schema = new Schema({
- *   tags: {
- *     type: 'array',
- *     items: {
- *       type: 'object',
- *       properties: {
- *         name: { type: 'string' },
- *         value: { type: 'string' }
- *       }
- *     }
- *   }
- * }, 'item-schema');
- *
- * const item = {
- *   tags: [
- *     { name: 'tag1', value: 'value1' },
- *     { name: 'tag2', value: 'value2' }
- *   ]
- * };
- *
- * mapObjectProperties(item, schema.jsonSchema, {}, (propName, propSchema, obj) => {
- *   if (propSchema.type === 'string') {
- *     obj[propName] = String(obj[propName]).toUpperCase();
- *   }
- * });
- * // Result: tags array items have uppercase name and value properties
- *
- * @param object - The target object to traverse
- * @param jsonSchema - The JSON schema defining the object structure
- * @param schemasMap - Map of schema IDs to schema objects for resolving $ref references
- * @param callback - Function called for each property with (propertyName, propertySchema, object)
  */
 const mapObjectProperties = (
   object: TargetObject,
   jsonSchema: JsonSchema,
-  schemasMap: JsonSchemasMap,
+  schemasMap: Record<string, JsonSchema>,
   callback: (propertyName: string, propertySchema: PropertySchema, object: TargetObject) => void
 ) => {
   const { enum: enumItems } = jsonSchema as EnumSchema;
@@ -226,7 +74,7 @@ const mapObjectProperties = (
         const nestedJsonSchema = {
           id: `${objectSchema.id}.${propertyName}.properties`,
           properties
-        };
+        } as JsonSchema;
 
         mapObjectProperties(value as TargetObject, nestedJsonSchema, schemasMap, callback);
       }
@@ -254,7 +102,7 @@ const mapObjectProperties = (
           : {
             id: `${objectSchema.id}.${propertyName}.items.properties`,
             properties: itemObjectProperties
-          };
+          }  as JsonSchema;;
 
         for (const valueItem of value) {
           const isObjectItem = valueItem && typeof valueItem === 'object' && !Array.isArray(valueItem);

package/src/helpers/normalizeAttributes.ts

@@ -1,219 +1,15 @@
+import { type JsonSchema } from 'z-schema';
 import { get, isUndefined } from 'lodash';
 
 import normalizeType from './normalizeType';
 import mapObjectProperties from './mapObjectProperties';
-import type { TargetObject, JsonSchema, JsonSchemasMap, PropertySchema } from './JsonSchema';
 
-/**
- * Normalizes object attribute values based on a JSON Schema definition.
- *
- * ## Intent
- *
- * This function ensures that object properties conform to their schema definitions by:
- * 1. Setting default values for properties that are undefined (but not null)
- * 2. Normalizing existing values to match their schema-defined types (e.g., converting
- *    string "123" to number 123, or string "true" to boolean true)
- *
- * The function operates recursively, processing nested objects, arrays, and referenced
- * schemas ($ref) to ensure all properties throughout the object tree are normalized
- * according to their respective schema definitions.
- *
- * This is particularly useful in data processing pipelines where data may come from
- * external sources (forms, APIs, databases) with inconsistent types, but needs to be
- * normalized before validation or further processing.
- *
- * ## Use Cases
- *
- * 1. **Form data processing**: HTML forms submit all values as strings. This function
- *    converts them to their expected types (numbers, booleans) based on schema definitions
- *    and fills in default values for missing fields.
- *
- * 2. **API response normalization**: When consuming APIs that return loosely-typed data
- *    (e.g., numbers as strings, booleans as strings), this function ensures values match
- *    the expected schema types before validation or business logic processing.
- *
- * 3. **Configuration object initialization**: Setting default values and normalizing types
- *    for configuration objects based on their schema definitions, ensuring consistent
- *    structure and types throughout the application.
- *
- * 4. **Data migration and transformation**: Normalizing data structures during migration
- *    or transformation processes where source data may have inconsistent types but target
- *    schema requires specific types.
- *
- * 5. **Pre-validation normalization**: Preparing objects for schema validation by ensuring
- *    types are correct and defaults are applied, reducing validation errors and improving
- *    data quality.
- *
- * ## Behavior
- *
- * - **Default values**: Properties that are `undefined` will be set to their schema-defined
- *   default value (if one exists). Properties that are `null` are left as `null` and will
- *   not receive default values. Default values are also normalized according to their type
- *   (e.g., a default string "123" with type "number" will be converted to the number 123).
- *
- * - **Type normalization**: Properties with existing values (including default values that
- *   were just set) are normalized to match their schema type using `normalizeType`. This
- *   includes converting strings to numbers/booleans where appropriate, while preserving the
- *   original value if conversion is not possible.
- *
- * - **Recursive processing**: The function processes nested objects, arrays, and schema
- *   references ($ref) recursively, ensuring all nested properties are normalized.
- *
- * - **Non-destructive**: The function mutates the input object in place. If you need to
- *   preserve the original, create a deep copy before calling this function.
- *
- * ## Examples
- *
- * ### Basic Usage: Default Values and Type Normalization
- * ```typescript
- * import Schema from './Schema';
- * import normalizeAttributes from './normalizeAttributes';
- *
- * const schema = new Schema({
- *   name: { type: 'string', default: 'Anonymous' },
- *   age: { type: 'number' },
- *   isActive: { type: 'boolean', default: false }
- * }, 'user-schema');
- *
- * const user = {
- *   age: '25'  // string that should be a number
- * };
- *
- * normalizeAttributes(user, schema.jsonSchema, {});
- *
- * // Result:
- * // {
- * //   name: 'Anonymous',      // default value applied
- * //   age: 25,                // string converted to number
- * //   isActive: false         // default value applied
- * // }
- * ```
- *
- * ### Nested Objects
- * ```typescript
- * const schema = new Schema({
- *   address: {
- *     type: 'object',
- *     properties: {
- *       street: { type: 'string', default: 'Unknown' },
- *       zipCode: { type: 'number' }
- *     }
- *   }
- * }, 'profile-schema');
- *
- * const profile = {
- *   address: {
- *     zipCode: '12345'  // string that should be a number
- *   }
- * };
- *
- * normalizeAttributes(profile, schema.jsonSchema, {});
- *
- * // Result:
- * // {
- * //   address: {
- * //     street: 'Unknown',  // default value applied
- * //     zipCode: 12345      // string converted to number
- * //   }
- * // }
- * ```
- *
- * ### Arrays with Schema References
- * ```typescript
- * const itemSchema = new Schema({
- *   id: { type: 'number' },
- *   name: { type: 'string', default: 'Unnamed' }
- * }, 'item-schema');
- *
- * const schema = new Schema({
- *   items: {
- *     type: 'array',
- *     items: { $ref: 'item-schema' }
- *   }
- * }, 'collection-schema');
- *
- * const collection = {
- *   items: [
- *     { id: '1' },           // id is a string, should be number
- *     { id: '2', name: 'Item 2' }
- *   ]
- * };
- *
- * const schemasMap = {
- *   'item-schema': itemSchema.jsonSchema
- * };
- *
- * normalizeAttributes(collection, schema.jsonSchema, schemasMap);
- *
- * // Result:
- * // {
- * //   items: [
- * //     { id: 1, name: 'Unnamed' },  // id normalized, default name applied
- * //     { id: 2, name: 'Item 2' }    // id normalized, existing name preserved
- * //   ]
- * // }
- * ```
- *
- * ### Boolean Normalization
- * ```typescript
- * const schema = new Schema({
- *   enabled: { type: 'boolean', default: false },
- *   verified: { type: 'boolean' }
- * }, 'settings-schema');
- *
- * const settings = {
- *   verified: 'yes'  // string that should be boolean
- * };
- *
- * normalizeAttributes(settings, schema.jsonSchema, {});
- *
- * // Result:
- * // {
- * //   enabled: false,   // default value applied
- * //   verified: true    // string "yes" converted to boolean true
- * // }
- * ```
- *
- * ### Handling Null Values
- * ```typescript
- * const schema = new Schema({
- *   optionalField: { type: 'string', default: 'default-value' }
- * }, 'test-schema');
- *
- * const obj1 = {};                    // undefined → default applied
- * const obj2 = { optionalField: null }; // null → no default applied
- *
- * normalizeAttributes(obj1, schema.jsonSchema, {});
- * normalizeAttributes(obj2, schema.jsonSchema, {});
- *
- * // obj1: { optionalField: 'default-value' }
- * // obj2: { optionalField: null }  // null preserved, default not applied
- * ```
- *
- * ### Default Value Normalization
- * ```typescript
- * const schema = new Schema({
- *   count: { type: 'number', default: '42' },      // default is string, type is number
- *   enabled: { type: 'boolean', default: 'true' }   // default is string, type is boolean
- * }, 'config-schema');
- *
- * const config = {};
- *
- * normalizeAttributes(config, schema.jsonSchema, {});
- *
- * // Result:
- * // {
- * //   count: 42,      // default string "42" normalized to number
- * //   enabled: true   // default string "true" normalized to boolean
- * // }
- * ```
- *
- * @param object - The target object to normalize (mutated in place)
- * @param jsonSchema - The JSON Schema definition describing the object structure
- * @param jsonSchemasMap - Map of schema IDs to schema definitions, used for resolving $ref references
- * @returns void (mutates the input object)
- */
-const normalizeAttributes = (object: TargetObject, jsonSchema: JsonSchema, jsonSchemasMap: JsonSchemasMap) => {
+/** Normalizes object attribute values based on a JSON Schema definition. */
+const normalizeAttributes = (
+  object: TargetObject,
+  jsonSchema: JsonSchema,
+  jsonSchemasMap: Record<string, JsonSchema>
+) => {
   /** Callback to normalize value based on property type defined in schema */
   const callback = (propertyName: string, propertySchema: PropertySchema, object: TargetObject) => {
     let value = object[propertyName];

package/src/helpers/normalizeProperties.ts

@@ -1,177 +1,6 @@
 import { get, set, isUndefined } from 'lodash';
 
-import type {
-  EnumSchema,
-  PropertiesSchema,
-  ObjectPropertySchema,
-  ReferencePropertySchema,
-  ArrayPropertySchema
-} from './JsonSchema';
-
-/**
- * Normalizes JSON schema properties by ensuring all properties have an explicit `type` attribute.
- * 
- * **Intent:**
- * This function transforms schemas that may have implicit or missing type information into
- * fully normalized schemas with explicit types. It recursively processes nested structures
- * (objects and arrays) to ensure type consistency throughout the schema hierarchy.
- * 
- * **Use Cases:**
- * - **Schema Validation Preparation**: Ensures schemas are ready for validation where type
- *   information is required by validators or processing tools
- * - **External Schema Normalization**: Normalizes schemas imported from external sources
- *   (e.g., OpenAPI specs, YAML schemas) that may omit type information
- * - **Type Inference**: Automatically infers types from structural hints (e.g., presence of
- *   `properties` implies `object`, presence of `items` implies `array`)
- * - **Schema Consistency**: Guarantees consistent schema structure before further processing
- *   or transformation
- * - **Default Type Assignment**: Provides sensible defaults (e.g., `string` for primitives)
- *   when type cannot be inferred
- * 
- * **Behavior:**
- * - **Enum Schemas**: Sets `type` to `'string'` if missing (preserves existing type if present)
- * - **Reference Properties**: Skips `$ref` properties (they don't need type normalization)
- * - **Type Inference Priority** (when type is missing):
- *   1. If property has `properties` → sets `type: 'object'`
- *   2. Else if property has `items` → sets `type: 'array'`
- *   3. Else → sets `type: 'string'` (default)
- * - **Object Properties**: 
- *   - Infers `type: 'object'` from presence of `properties` (if type not already set)
- *   - Creates empty `properties: {}` if `type: 'object'` but no properties exist
- *   - Recursively normalizes nested object properties
- *   - Note: If both `properties` and `items` exist, `properties` takes precedence
- * - **Array Properties**:
- *   - Infers `type: 'array'` from presence of `items` (if type not already set)
- *   - Sets default `items: { type: 'string' }` if array has no items
- *   - Normalizes item schemas: sets `type: 'object'` if items have `properties` (not undefined)
- *     - `properties: null` → treated as having properties (sets type to 'object')
- *     - `properties: undefined` → treated as not having properties (no type set)
- *     - Empty object `{}` → treated as not having properties (no type set)
- *   - Recursively normalizes nested properties within array items
- * - **Primitive Properties**: Sets `type: 'string'` as default when no type, items, or properties exist
- * - **Existing Types**: Never overrides existing type values (even if structure suggests different type)
- * - **Edge Cases**:
- *   - Empty schemas (`{}`) are handled gracefully
- *   - Properties with conflicting structure (e.g., `type: 'object'` with `items`) are normalized
- *     according to the explicit type, ignoring conflicting structural hints
- * 
- * **Examples:**
- * 
- * @example Enum schema normalization
- * ```typescript
- * const schema: EnumSchema = { enum: ['red', 'green', 'blue'] };
- * normalizeProperties(schema);
- * // Result: { enum: ['red', 'green', 'blue'], type: 'string' }
- * ```
- * 
- * @example Object type inference
- * ```typescript
- * const schema: PropertiesSchema = {
- *   user: {
- *     properties: {
- *       name: {}
- *     }
- *   }
- * };
- * normalizeProperties(schema);
- * // Result:
- * // {
- * //   user: {
- * //     type: 'object',
- * //     properties: {
- * //       name: { type: 'string' }
- * //     }
- * //   }
- * // }
- * ```
- * 
- * @example Array type inference
- * ```typescript
- * const schema: PropertiesSchema = {
- *   tags: {
- *     items: { type: 'string' }
- *   }
- * };
- * normalizeProperties(schema);
- * // Result:
- * // {
- * //   tags: {
- * //     type: 'array',
- * //     items: { type: 'string' }
- * //   }
- * // }
- * ```
- * 
- * @example Complex nested structure
- * ```typescript
- * const schema: PropertiesSchema = {
- *   profile: {
- *     properties: {
- *       name: {},
- *       addresses: {
- *         items: {
- *           properties: {
- *             street: {},
- *             city: {}
- *           }
- *         }
- *       }
- *     }
- *   }
- * };
- * normalizeProperties(schema);
- * // Result:
- * // {
- * //   profile: {
- * //     type: 'object',
- * //     properties: {
- * //       name: { type: 'string' },
- * //       addresses: {
- * //         type: 'array',
- * //         items: {
- * //           type: 'object',
- * //           properties: {
- * //             street: { type: 'string' },
- * //             city: { type: 'string' }
- * //           }
- * //         }
- * //       }
- * //     }
- * //   }
- * // }
- * ```
- * 
- * @example Reference properties are skipped
- * ```typescript
- * const schema: PropertiesSchema = {
- *   refField: { $ref: '#/definitions/User' },
- *   normalField: {}
- * };
- * normalizeProperties(schema);
- * // Result:
- * // {
- * //   refField: { $ref: '#/definitions/User' }, // Unchanged
- * //   normalField: { type: 'string' }
- * // }
- * ```
- * 
- * @example Default type assignment
- * ```typescript
- * const schema: PropertiesSchema = {
- *   title: {},
- *   count: { type: 'number' }
- * };
- * normalizeProperties(schema);
- * // Result:
- * // {
- * //   title: { type: 'string' }, // Default assigned
- * //   count: { type: 'number' }  // Existing preserved
- * // }
- * ```
- * 
- * @param schema - The schema to normalize (either an EnumSchema or PropertiesSchema)
- * @modifies The schema object is mutated in place with normalized types
- */
+/** Normalizes JSON schema properties by ensuring all properties have an explicit `type` attribute. */
 const normalizeProperties = (schema: EnumSchema | PropertiesSchema) => {
   const { enum: isEnum } = (schema as EnumSchema);