@kravc/schema 2.7.6 → 2.8.0-alpha.0

package/dist/helpers/mapObjectProperties.js

@@ -0,0 +1,229 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const lodash_1 = require("lodash");
+const got_1 = __importDefault(require("./got"));
+/**
+ * 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, jsonSchema, schemasMap, callback) => {
+    const { enum: enumItems } = jsonSchema;
+    const isEnum = !!enumItems;
+    if (isEnum) {
+        return;
+    }
+    const objectSchema = jsonSchema;
+    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 = (0, lodash_1.isUndefined)(value);
+        if (isValueUndefined) {
+            continue;
+        }
+        const { $ref: refSchemaId } = property;
+        const isReference = !(0, lodash_1.isUndefined)(refSchemaId);
+        if (isReference) {
+            const referenceSchema = (0, got_1.default)(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, referenceSchema, schemasMap, callback);
+            }
+            continue;
+        }
+        const { type } = property;
+        const isObject = type === 'object';
+        if (isObject) {
+            const { properties = {} } = property;
+            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, nestedJsonSchema, schemasMap, callback);
+            }
+            continue;
+        }
+        const isArray = type === 'array';
+        if (isArray) {
+            const { items } = property;
+            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;
+                const { properties: itemObjectProperties = {} } = items;
+                const isItemReference = !(0, lodash_1.isUndefined)(itemRefSchemaId);
+                const itemSchema = isItemReference
+                    ? (0, got_1.default)(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, itemSchema, schemasMap, callback);
+                    }
+                }
+            }
+        }
+    }
+};
+exports.default = mapObjectProperties;
+//# sourceMappingURL=mapObjectProperties.js.map

package/dist/helpers/mapObjectProperties.js.map

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

package/dist/helpers/normalizeAttributes.d.ts

@@ -0,0 +1,213 @@
+import type { TargetObject, JsonSchema, JsonSchemasMap } 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)
+ */
+declare const normalizeAttributes: (object: TargetObject, jsonSchema: JsonSchema, jsonSchemasMap: JsonSchemasMap) => void;
+export default normalizeAttributes;
+//# sourceMappingURL=normalizeAttributes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeAttributes.d.ts","sourceRoot":"","sources":["../../src/helpers/normalizeAttributes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAkB,MAAM,cAAc,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgNG;AACH,QAAA,MAAM,mBAAmB,GAAI,QAAQ,YAAY,EAAE,YAAY,UAAU,EAAE,gBAAgB,cAAc,SA6BxG,CAAC;AAEF,eAAe,mBAAmB,CAAC"}