@kravc/schema 2.7.5 → 2.8.0-alpha.0

package/src/helpers/__tests__/validateId.test.ts

@@ -0,0 +1,118 @@
+import validateId from '../validateId';
+
+const name = 'testId';
+
+describe('validateId(name, value)', () => {
+  describe('valid inputs', () => {
+    describe('URLs', () => {
+      it('should accept HTTP URLs', () => {
+        expect(() => validateId(name, 'http://example.com')).not.toThrow();
+        expect(() => validateId(name, 'http://example.com/path')).not.toThrow();
+        expect(() => validateId(name, 'http://example.com:8080/path?query=value')).not.toThrow();
+      });
+
+      it('should accept HTTPS URLs', () => {
+        expect(() => validateId(name, 'https://example.com')).not.toThrow();
+        expect(() => validateId(name, 'https://example.com/path')).not.toThrow();
+        expect(() => validateId(name, 'https://example.com:443/path#fragment')).not.toThrow();
+      });
+
+      it('should accept other URL schemes', () => {
+        expect(() => validateId(name, 'ftp://example.com')).not.toThrow();
+      });
+
+      it('should accept URLs without protocol', () => {
+        expect(() => validateId(name, 'example.com')).not.toThrow();
+        expect(() => validateId(name, 'subdomain.example.com')).not.toThrow();
+      });
+
+      it('should accept IP address URLs', () => {
+        expect(() => validateId(name, 'http://192.168.1.1')).not.toThrow();
+        expect(() => validateId(name, 'https://8.8.8.8')).not.toThrow();
+      });
+
+      it('should accept URLs with special characters', () => {
+        expect(() => validateId(name, 'https://example.com/path%20with%20spaces')).not.toThrow();
+        expect(() => validateId(name, 'https://example.com/path?key=value&other=123')).not.toThrow();
+      });
+    });
+
+    describe('DIDs', () => {
+      it('should accept valid DIDs', () => {
+        expect(() => validateId(name, 'did:example:123456789')).not.toThrow();
+        expect(() => validateId(name, 'did:web:example.com')).not.toThrow();
+        expect(() => validateId(name, 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK')).not.toThrow();
+      });
+
+      it('should accept DIDs case-insensitively', () => {
+        expect(() => validateId(name, 'DID:example:123456789')).not.toThrow();
+        expect(() => validateId(name, 'Did:example:123456789')).not.toThrow();
+        expect(() => validateId(name, 'dId:example:123456789')).not.toThrow();
+      });
+
+      it('should accept DIDs with various methods', () => {
+        expect(() => validateId(name, 'did:ethr:0x1234567890abcdef')).not.toThrow();
+        expect(() => validateId(name, 'did:ion:EiClkZMDZhPKV7e3j4wUmxLukn6YxvfN8v2F2b3X5r8tQ')).not.toThrow();
+        expect(() => validateId(name, 'did:peer:123456789')).not.toThrow();
+      });
+
+      it('should accept bare did: prefix (no method or id)', () => {
+        expect(() => validateId(name, 'did:')).not.toThrow();
+      });
+    });
+  });
+
+  describe('invalid inputs', () => {
+    describe('missing value', () => {
+      it('should throw when value is empty string', () => {
+        expect(() => validateId(name, '')).toThrow('Parameter "testId" is required');
+      });
+
+      it('should throw when value is null', () => {
+        expect(() => validateId(name, null)).toThrow('Parameter "testId" is required');
+      });
+
+      it('should throw when value is undefined', () => {
+        expect(() => validateId(name, undefined)).toThrow('Parameter "testId" is required');
+      });
+    });
+
+    describe('malformed value', () => {
+      it('should throw when value is not a URL or DID', () => {
+        expect(() => validateId(name, 'not-a-url-or-did')).toThrow(
+          'Parameter "testId" must be a URL, received: "not-a-url-or-did"'
+        );
+        expect(() => validateId(name, 'just some text')).toThrow(
+          'Parameter "testId" must be a URL, received: "just some text"'
+        );
+      });
+
+      it('should throw when value is incomplete DID prefix without colon or method', () => {
+        expect(() => validateId(name, 'did')).toThrow(
+          'Parameter "testId" must be a URL, received: "did"'
+        );
+        expect(() => validateId(name, 'did ')).toThrow(
+          'Parameter "testId" must be a URL, received: "did "'
+        );
+      });
+
+      it('should throw when value is whitespace-only', () => {
+        expect(() => validateId(name, '   ')).toThrow(
+          'Parameter "testId" must be a URL, received: "   "'
+        );
+      });
+    });
+  });
+
+  describe('error messages', () => {
+    it('should include parameter name in required error', () => {
+      expect(() => validateId('schemaId', '')).toThrow('Parameter "schemaId" is required');
+    });
+
+    it('should include parameter name in invalid-format error', () => {
+      expect(() => validateId('myParam', 'invalid')).toThrow(
+        'Parameter "myParam" must be a URL, received: "invalid"'
+      );
+    });
+  });
+});

package/src/helpers/cleanupAttributes.ts

@@ -0,0 +1,151 @@
+import { isUndefined } from 'lodash';
+
+import got from './got';
+import type {
+  JsonSchema,
+  EnumSchema,
+  TargetObject,
+  ObjectSchema,
+  JsonSchemasMap,
+  ArrayPropertySchema,
+  ObjectPropertySchema,
+  ReferencePropertySchema
+} from './JsonSchema';
+
+/**
+ * Removes properties from an object that are not defined in the JSON schema.
+ * 
+ * **Intent:**
+ * This function ensures that objects conform to their schema definition by removing
+ * any properties that are not explicitly defined in the schema. It performs a deep
+ * cleanup, recursively processing nested objects, arrays, and schema references.
+ * 
+ * **Use Cases:**
+ * - **Third-party API integrations**: When integrating with external services (e.g., Telegram)
+ *   that may send additional fields you don't want to process, this function allows you
+ *   to define a minimal schema and automatically strip unwanted properties.
+ * - **Data sanitization**: Clean up objects received from external sources or user input
+ *   before validation or processing, ensuring only expected fields are present.
+ * - **Schema enforcement**: Enforce strict schema compliance by removing any properties
+ *   that don't match the defined schema structure.
+ * - **Pre-validation cleanup**: Remove extraneous properties before schema validation to
+ *   prevent validation errors from unexpected fields.
+ * 
+ * **Behavior:**
+ * - Mutates the input object in-place (does not return a new object)
+ * - Recursively processes nested objects, arrays, and schema references ($ref)
+ * - Skips enum schemas (returns early without modification)
+ * - Only processes object values (skips null, undefined, and primitive values)
+ * - Handles array items by cleaning each object item according to the array's item schema
+ * 
+ * @param object - The target object to clean up (mutated in-place)
+ * @param jsonSchema - The JSON schema defining allowed properties
+ * @param schemasMap - Optional map of schema IDs to schema definitions for resolving $ref references
+ */
+const cleanupAttributes = (
+  object: TargetObject,
+  jsonSchema: JsonSchema,
+  schemasMap: JsonSchemasMap = {}
+) => {
+  const { enum: enumItems } = (jsonSchema as EnumSchema);
+
+  const isEnum = !!enumItems;
+
+  if (isEnum) {
+    return;
+  }
+
+  const objectSchema = (jsonSchema as ObjectSchema);
+
+  // Guard against malformed schemas without properties
+  if (!objectSchema.properties) {
+    return;
+  }
+
+  for (const fieldName in object) {
+    const property = objectSchema.properties[fieldName];
+
+    const isPropertyUndefined = isUndefined(property);
+
+    if (isPropertyUndefined) {
+      // NOTE: Delete object property if it's not defined in the object schema:
+      delete object[fieldName];
+      continue;
+    }
+
+    const { $ref: refSchemaId } = (property as ReferencePropertySchema);
+
+    const isReference = !isUndefined(refSchemaId);
+
+    if (isReference) {
+      const referenceSchema = got(schemasMap, refSchemaId, 'Schema "$PATH" not found');
+      const fieldValue = object[fieldName];
+
+      // Only recursively cleanup if the value is an object (not null, undefined, or primitive)
+      if (fieldValue && typeof fieldValue === 'object' && !Array.isArray(fieldValue)) {
+        cleanupAttributes(fieldValue as TargetObject, referenceSchema, schemasMap);
+      }
+      continue;
+    }
+
+    const { type } = (property as ObjectPropertySchema | ArrayPropertySchema);
+
+    const isObject = type === 'object';
+
+    if (isObject) {
+      const { properties = {} } = (property as ObjectPropertySchema);
+
+      const fieldValue = object[fieldName];
+
+      const isObjectValue = fieldValue &&
+        typeof fieldValue === 'object' &&
+        !Array.isArray(fieldValue);
+
+      if (isObjectValue) {
+        const nestedJsonSchema = {
+          id: `${objectSchema.id}.${fieldName}.properties`,
+          properties
+        };
+
+        cleanupAttributes(fieldValue as TargetObject, nestedJsonSchema, schemasMap);
+      }
+      continue;
+    }
+
+    const isArray = type === 'array';
+
+    if (isArray) {
+      const { items } = (property as ArrayPropertySchema);
+
+      const fieldValue = object[fieldName];
+      const isArrayValue = Array.isArray(fieldValue);
+
+      if (isArrayValue && items) {
+        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}.${fieldName}.items.properties`,
+            properties: itemObjectProperties
+          };
+
+        for (const item of fieldValue) {
+          const isObjectItem = item &&
+            typeof item === 'object' &&
+            !Array.isArray(item);
+
+          if (isObjectItem) {
+            cleanupAttributes(item as TargetObject, itemSchema, schemasMap);
+          }
+        }
+      }
+    }
+  }
+};
+
+export default cleanupAttributes;

package/src/helpers/cleanupNulls.ts

@@ -0,0 +1,106 @@
+import { isObject, cloneDeep } from 'lodash';
+
+import { type TargetObject } from './JsonSchema';
+
+const { isArray } = Array;
+
+/**
+ * Recursively removes null properties from an object.
+ * 
+ * **Intent:**
+ * This function provides a deep cleanup of objects by removing all properties
+ * that have `null` values. It's designed to sanitize objects before validation,
+ * storage, or transmission by eliminating explicitly null fields.
+ * 
+ * **Use Cases:**
+ * - **Pre-validation cleanup**: Remove null values before schema validation to
+ *   prevent validation errors from optional fields that were explicitly set to null.
+ *   This is particularly useful when `shouldCleanupNulls` is enabled in the Validator,
+ *   allowing you to clean objects before `cleanupAttributes` removes undefined properties.
+ * - **Data sanitization**: Clean objects received from external sources (APIs, user input,
+ *   databases) by removing null properties that may have been set during data transformation
+ *   or migration processes.
+ * - **API response normalization**: Prepare objects for API responses by removing null fields,
+ *   reducing payload size and ensuring consistent data structures across different endpoints.
+ * - **Database operations**: Clean objects before database storage or updates, removing
+ *   null fields that might cause issues with database constraints or indexing.
+ * - **JSON serialization optimization**: Reduce JSON payload size by removing null properties
+ *   before serialization, which is especially beneficial for large objects or high-frequency
+ *   API calls.
+ * - **Optional field handling**: Remove explicitly null optional fields that weren't provided
+ *   by the user, distinguishing between "field not provided" (undefined) and "field set to null".
+ * 
+ * **Behavior:**
+ * - Returns a deep clone of the input object (does not mutate the original)
+ * - Recursively processes nested objects and arrays at all depth levels
+ * - Only removes properties with `null` values (preserves `undefined`, `0`, `false`, `''`, etc.)
+ * - Skips non-object values (returns early for primitives)
+ * - Handles arrays by recursively processing each item
+ * - Preserves object structure and non-null values exactly as they are
+ * 
+ * @param target - The target object to clean (processed recursively, not mutated)
+ */
+const cleanupNulls = (target: TargetObject) => {
+  const shouldSkip = !isObject(target);
+
+  if (shouldSkip) {
+    return;
+  }
+
+  for (const key in target) {
+    const value = target[key];
+
+    if (isArray(value)) {
+      for (const item of value) {
+        cleanupNulls(item);
+      }
+
+      continue;
+    }
+
+    if (isObject(value)) {
+      cleanupNulls(value as Record<string, unknown>);
+
+      continue;
+    }
+
+    const isNull = value === null;
+
+    if (isNull) {
+      delete target[key];
+    }
+  }
+};
+
+/**
+ * Returns a deep copy of the object with all null properties removed.
+ * 
+ * This is the main exported function that creates a clone of the input object
+ * and removes all null properties recursively before returning it.
+ * 
+ * @param object - The object to clean (will be cloned, original is not modified)
+ * @returns A new object with all null properties removed recursively
+ * 
+ * @example
+ * ```typescript
+ * const dirty = {
+ *   name: 'John',
+ *   age: null,
+ *   address: {
+ *     street: 'Main St',
+ *     zip: null
+ *   }
+ * };
+ * 
+ * const clean = cleanupNulls(dirty);
+ * // Result: { name: 'John', address: { street: 'Main St' } }
+ * // Original 'dirty' object is unchanged
+ * ```
+ */
+export default function (object: Record<string, unknown>) {
+  const clone = cloneDeep(object);
+
+  cleanupNulls(clone);
+
+  return clone;
+};

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;