@kravc/schema 2.7.5 → 2.8.0-alpha.0

package/src/helpers/got.ts

@@ -0,0 +1,73 @@
+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);
+  const shouldThrow = isUndefined(value);
+
+  if (!shouldThrow) {
+    return value;
+  }
+
+  throw Error(errorTemplate.replace('$PATH', path));
+};
+
+export default got;

package/src/helpers/mapObjectProperties.ts

@@ -0,0 +1,272 @@
+import { isUndefined } from 'lodash';
+
+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,
+  callback: (propertyName: string, propertySchema: PropertySchema, object: TargetObject) => void
+) => {
+  const { enum: enumItems } = jsonSchema as EnumSchema;
+
+  const isEnum = !!enumItems;
+
+  if (isEnum) {
+    return;
+  }
+
+  const objectSchema = jsonSchema as ObjectSchema;
+
+  const hasProperties = !!objectSchema.properties;
+
+  // Guard against malformed schemas without properties
+  if (!hasProperties) {
+    return;
+  }
+
+  const { properties: objectProperties } = objectSchema;
+
+  for (const propertyName in objectProperties) {
+    const property = objectProperties[propertyName];
+
+    callback(propertyName, property, object);
+
+    const value = object[propertyName];
+    const isValueUndefined = isUndefined(value);
+
+    if (isValueUndefined) {
+      continue;
+    }
+
+    const { $ref: refSchemaId } = property as ReferencePropertySchema;
+
+    const isReference = !isUndefined(refSchemaId);
+
+    if (isReference) {
+      const referenceSchema = got(schemasMap, refSchemaId, 'Schema "$PATH" not found');
+
+      const isObjectValue = value && typeof value === 'object' && !Array.isArray(value);
+
+      // Only recursively process if the value is an object (not null, undefined, or primitive)
+      if (isObjectValue) {
+        mapObjectProperties(value as TargetObject, referenceSchema, schemasMap, callback);
+      }
+      continue;
+    }
+
+    const { type } = property as ObjectPropertySchema | ArrayPropertySchema;
+
+    const isObject = type === 'object';
+
+    if (isObject) {
+      const { properties = {} } = property as ObjectPropertySchema;
+
+      const isObjectValue = value && typeof value === 'object' && !Array.isArray(value);
+
+      // Only recursively process if the value is an object (not null, undefined, or primitive)
+      if (isObjectValue) {
+        const nestedJsonSchema = {
+          id: `${objectSchema.id}.${propertyName}.properties`,
+          properties
+        };
+
+        mapObjectProperties(value as TargetObject, nestedJsonSchema, schemasMap, callback);
+      }
+      continue;
+    }
+
+    const isArray = type === 'array';
+
+    if (isArray) {
+      const { items } = property as ArrayPropertySchema;
+
+      const hasItems = !!items;
+      const isArrayValue = Array.isArray(value);
+
+      // Only process if value is an array and items schema is defined
+      if (isArrayValue && hasItems) {
+        const { $ref: itemRefSchemaId } = items as ReferencePropertySchema;
+
+        const { properties: itemObjectProperties = {} } = items as ObjectPropertySchema;
+
+        const isItemReference = !isUndefined(itemRefSchemaId);
+
+        const itemSchema = isItemReference
+          ? got(schemasMap, itemRefSchemaId, 'Schema "$PATH" not found')
+          : {
+            id: `${objectSchema.id}.${propertyName}.items.properties`,
+            properties: itemObjectProperties
+          };
+
+        for (const valueItem of value) {
+          const isObjectItem = valueItem && typeof valueItem === 'object' && !Array.isArray(valueItem);
+
+          // Only recursively process if the item is an object (not null, undefined, or primitive)
+          if (isObjectItem) {
+            mapObjectProperties(valueItem as TargetObject, itemSchema, schemasMap, callback);
+          }
+        }
+      }
+    }
+  }
+};
+
+export default mapObjectProperties;

package/src/helpers/normalizeAttributes.ts

@@ -0,0 +1,247 @@
+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) => {
+  /** Callback to normalize value based on property type defined in schema */
+  const callback = (propertyName: string, propertySchema: PropertySchema, object: TargetObject) => {
+    let value = object[propertyName];
+
+    const type = get(propertySchema, 'type');
+    const defaultValue = get(propertySchema, 'default');
+
+    const hasValue = !isUndefined(value);
+    const hasDefaultValue = !isUndefined(defaultValue);
+    const shouldSetDefaultValue = hasDefaultValue && !hasValue;
+
+    // Set default value if property is undefined and default exists
+    if (shouldSetDefaultValue) {
+      object[propertyName] = defaultValue;
+      value = defaultValue; // Update value reference for normalization
+    }
+
+    const hasType = !!type;
+    const hasValueAfterDefault = !isUndefined(value);
+    const shouldNormalizeValue = hasType && hasValueAfterDefault;
+
+    // Normalize the current value (original or default) if type is defined
+    if (shouldNormalizeValue) {
+      object[propertyName] = normalizeType(type, value);
+    }
+  };
+
+  mapObjectProperties(object, jsonSchema, jsonSchemasMap, callback);
+};
+
+export default normalizeAttributes;