@kravc/schema 2.7.6 → 2.8.0-alpha.1

package/src/helpers/getReferenceIds.ts

@@ -0,0 +1,273 @@
+import { isUndefined, uniq } from 'lodash';
+
+import Schema from '../Schema';
+import got from './got';
+import {
+  EnumSchema,
+  ObjectSchema,
+  ArrayPropertySchema,
+  ObjectPropertySchema,
+  ReferencePropertySchema,
+} from './JsonSchema';
+
+/**
+ * Recursively extracts all referenced schema IDs from a schema structure.
+ *
+ * **Intent:** Traverse a schema's entire structure (including nested objects and arrays)
+ * to collect all schema IDs that are referenced via `$ref` properties. This enables
+ * dependency resolution, schema bundling, and validation of schema completeness.
+ *
+ * **Use Cases:**
+ * - **Dependency Resolution:** Identify all schemas that a given schema depends on,
+ *   ensuring they are loaded before validation
+ * - **Schema Bundling:** Collect all related schemas into a single bundle for
+ *   distribution or storage
+ * - **Validation Preparation:** Pre-load all referenced schemas to ensure complete
+ *   validation context
+ * - **Dependency Graph Building:** Understand the relationships and dependencies
+ *   between schemas in a schema registry
+ * - **Schema Analysis:** Analyze schema complexity by identifying all dependencies
+ * - **Circular Reference Detection:** (Note: current implementation does not handle
+ *   circular references and will recurse infinitely)
+ *
+ * **Behavior:**
+ * - Returns an empty array for enum schemas (they don't reference other schemas)
+ * - Recursively traverses nested object properties
+ * - Handles array items that reference schemas or contain object properties
+ * - Follows nested references to collect transitive dependencies
+ * - Returns unique schema IDs (deduplicates if same schema is referenced multiple times)
+ * - Throws an error if a referenced schema is not found in the schemasMap
+ *
+ * **Example - Simple Reference:**
+ * ```typescript
+ * const userSchema = new Schema({
+ *   profile: { $ref: 'Profile' }
+ * }, 'User');
+ *
+ * const profileSchema = new Schema({
+ *   name: { type: 'string' }
+ * }, 'Profile');
+ *
+ * const schemasMap = { 'Profile': profileSchema };
+ * const referenceIds = getReferenceIds(userSchema, schemasMap);
+ * // Returns: ['Profile']
+ * ```
+ *
+ * **Example - Multiple References:**
+ * ```typescript
+ * const orderSchema = new Schema({
+ *   customer: { $ref: 'Customer' },
+ *   product: { $ref: 'Product' },
+ *   shipping: { $ref: 'Address' }
+ * }, 'Order');
+ *
+ * const schemasMap = {
+ *   'Customer': customerSchema,
+ *   'Product': productSchema,
+ *   'Address': addressSchema
+ * };
+ * const referenceIds = getReferenceIds(orderSchema, schemasMap);
+ * // Returns: ['Customer', 'Product', 'Address']
+ * ```
+ *
+ * **Example - Nested References:**
+ * ```typescript
+ * const userSchema = new Schema({
+ *   profile: { $ref: 'Profile' }
+ * }, 'User');
+ *
+ * const profileSchema = new Schema({
+ *   address: { $ref: 'Address' }
+ * }, 'Profile');
+ *
+ * const addressSchema = new Schema({
+ *   street: { type: 'string' }
+ * }, 'Address');
+ *
+ * const schemasMap = {
+ *   'Profile': profileSchema,
+ *   'Address': addressSchema
+ * };
+ * const referenceIds = getReferenceIds(userSchema, schemasMap);
+ * // Returns: ['Profile', 'Address'] (includes transitive dependencies)
+ * ```
+ *
+ * **Example - Array with Reference Items:**
+ * ```typescript
+ * const orderSchema = new Schema({
+ *   items: {
+ *     type: 'array',
+ *     items: { $ref: 'OrderItem' }
+ *   }
+ * }, 'Order');
+ *
+ * const schemasMap = { 'OrderItem': orderItemSchema };
+ * const referenceIds = getReferenceIds(orderSchema, schemasMap);
+ * // Returns: ['OrderItem']
+ * ```
+ *
+ * **Example - Nested Object Properties:**
+ * ```typescript
+ * const userSchema = new Schema({
+ *   contact: {
+ *     type: 'object',
+ *     properties: {
+ *       address: { $ref: 'Address' }
+ *     }
+ *   }
+ * }, 'User');
+ *
+ * const schemasMap = { 'Address': addressSchema };
+ * const referenceIds = getReferenceIds(userSchema, schemasMap);
+ * // Returns: ['Address']
+ * ```
+ *
+ * **Example - Complex Mixed Structure:**
+ * ```typescript
+ * const orderSchema = new Schema({
+ *   customer: { $ref: 'Customer' },
+ *   items: {
+ *     type: 'array',
+ *     items: {
+ *       type: 'object',
+ *       properties: {
+ *         product: { $ref: 'Product' }
+ *       }
+ *     }
+ *   },
+ *   shipping: {
+ *     type: 'object',
+ *     properties: {
+ *       address: { $ref: 'Address' }
+ *     }
+ *   }
+ * }, 'Order');
+ *
+ * const schemasMap = {
+ *   'Customer': customerSchema,
+ *   'Product': productSchema,
+ *   'Address': addressSchema
+ * };
+ * const referenceIds = getReferenceIds(orderSchema, schemasMap);
+ * // Returns: ['Customer', 'Product', 'Address']
+ * ```
+ *
+ * **Example - Duplicate References:**
+ * ```typescript
+ * const schema = new Schema({
+ *   field1: { $ref: 'SharedSchema' },
+ *   field2: { $ref: 'SharedSchema' }
+ * }, 'Test');
+ *
+ * const schemasMap = { 'SharedSchema': sharedSchema };
+ * const referenceIds = getReferenceIds(schema, schemasMap);
+ * // Returns: ['SharedSchema'] (deduplicated)
+ * ```
+ *
+ * @param schema - The schema to extract references from
+ * @param schemasMap - A map of schema IDs to Schema instances, used to resolve
+ *   referenced schemas and traverse nested references
+ * @returns An array of unique schema IDs that are referenced (directly or indirectly)
+ *   by the given schema
+ * @throws Error if a referenced schema is not found in the schemasMap
+ *
+ * **Limitations:**
+ * - Does not handle circular references (will cause infinite recursion)
+ * - Requires all referenced schemas to be present in schemasMap
+ */
+const getReferenceIds = (schema: Schema, schemasMap: Record<string, Schema>): string[] => {
+  /** Returns schema from the map by ID */
+  const getSchema = (id: string) => got(schemasMap, id, 'Schema "$PATH" not found');
+
+  let referenceIds: string[] = [];
+
+  const { jsonSchema } = schema;
+  const { enum: isEnum } = (jsonSchema as EnumSchema);
+
+  if (isEnum) {
+    return [];
+  }
+
+  const objectSchema = (jsonSchema as ObjectSchema);
+
+  for (const propertyName in objectSchema.properties) {
+    const property = objectSchema.properties[propertyName];
+
+    const { $ref: refSchemaId } = (property as ReferencePropertySchema);
+
+    const isReference = !isUndefined(refSchemaId);
+
+    if (isReference) {
+      const refJsonSchema = getSchema(refSchemaId);
+      const nestedReferenceIds = getReferenceIds(refJsonSchema, schemasMap);
+
+      referenceIds = [
+        refSchemaId,
+        ...referenceIds,
+        ...nestedReferenceIds
+      ];
+
+      continue;
+    }
+
+    const { type } = (property as ArrayPropertySchema | ObjectPropertySchema);
+
+    const isObject = type === 'object';
+
+    if (isObject) {
+      // istanbul ignore next - unreachable defensive code: properties is always set by normalizeProperties in Schema constructor
+      const { properties = {} } = (property as ObjectPropertySchema);
+
+      const nestedSchema = new Schema(properties, `${objectSchema.id}.${propertyName}.properties`);
+      const nestedReferenceIds = getReferenceIds(nestedSchema, schemasMap);
+
+      referenceIds = [
+        ...referenceIds,
+        ...nestedReferenceIds
+      ];
+
+      continue;
+    }
+
+    const isArray = type === 'array';
+
+    if (!isArray) {
+      continue;
+    }
+
+    const { items } = (property as ArrayPropertySchema);
+
+    const itemRefSchemaId = (items as ReferencePropertySchema).$ref;
+
+    if (itemRefSchemaId) {
+      const itemJsonSchema = getSchema(itemRefSchemaId);
+      const nestedReferenceIds = getReferenceIds(itemJsonSchema, schemasMap);
+
+      referenceIds = [
+        itemRefSchemaId,
+        ...referenceIds,
+        ...nestedReferenceIds
+      ];
+
+      continue;
+    }
+
+    const itemProperties = (items as ObjectPropertySchema).properties;
+
+    if (itemProperties) {
+      const itemSchema = new Schema(itemProperties, `${objectSchema.id}.${propertyName}.items.properties`);
+      const itemReferenceIds = getReferenceIds(itemSchema, schemasMap);
+
+      referenceIds = [
+        ...referenceIds,
+        ...itemReferenceIds
+      ];
+
+      continue;
+    }
+  }
+
+  return uniq(referenceIds);
+};
+
+export default getReferenceIds;

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;