@kravc/schema 2.7.5 → 2.8.0-alpha.0

package/dist/helpers/JsonSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonSchema.js","sourceRoot":"","sources":["../../src/helpers/JsonSchema.ts"],"names":[],"mappings":""}

package/dist/helpers/cleanupAttributes.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"cleanupAttributes.d.ts","sourceRoot":"","sources":["../../src/helpers/cleanupAttributes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EAEV,YAAY,EAEZ,cAAc,EAIf,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,QAAA,MAAM,iBAAiB,GACrB,QAAQ,YAAY,EACpB,YAAY,UAAU,EACtB,aAAY,cAAmB,SAqGhC,CAAC;AAEF,eAAe,iBAAiB,CAAC"}

package/dist/helpers/cleanupAttributes.js

@@ -0,0 +1,113 @@
+"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"));
+/**
+ * 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, jsonSchema, schemasMap = {}) => {
+    const { enum: enumItems } = jsonSchema;
+    const isEnum = !!enumItems;
+    if (isEnum) {
+        return;
+    }
+    const objectSchema = jsonSchema;
+    // Guard against malformed schemas without properties
+    if (!objectSchema.properties) {
+        return;
+    }
+    for (const fieldName in object) {
+        const property = objectSchema.properties[fieldName];
+        const isPropertyUndefined = (0, lodash_1.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;
+        const isReference = !(0, lodash_1.isUndefined)(refSchemaId);
+        if (isReference) {
+            const referenceSchema = (0, got_1.default)(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, referenceSchema, schemasMap);
+            }
+            continue;
+        }
+        const { type } = property;
+        const isObject = type === 'object';
+        if (isObject) {
+            const { properties = {} } = property;
+            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, nestedJsonSchema, schemasMap);
+            }
+            continue;
+        }
+        const isArray = type === 'array';
+        if (isArray) {
+            const { items } = property;
+            const fieldValue = object[fieldName];
+            const isArrayValue = Array.isArray(fieldValue);
+            if (isArrayValue && items) {
+                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}.${fieldName}.items.properties`,
+                        properties: itemObjectProperties
+                    };
+                for (const item of fieldValue) {
+                    const isObjectItem = item &&
+                        typeof item === 'object' &&
+                        !Array.isArray(item);
+                    if (isObjectItem) {
+                        cleanupAttributes(item, itemSchema, schemasMap);
+                    }
+                }
+            }
+        }
+    }
+};
+exports.default = cleanupAttributes;
+//# sourceMappingURL=cleanupAttributes.js.map

package/dist/helpers/cleanupAttributes.js.map

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

package/dist/helpers/cleanupNulls.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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>): Record<string, unknown>;
+//# sourceMappingURL=cleanupNulls.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cleanupNulls.d.ts","sourceRoot":"","sources":["../../src/helpers/cleanupNulls.ts"],"names":[],"mappings":"AA0EA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,OAAO,WAAW,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,2BAMvD"}

package/dist/helpers/cleanupNulls.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+const lodash_1 = require("lodash");
+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) => {
+    const shouldSkip = !(0, lodash_1.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 ((0, lodash_1.isObject)(value)) {
+            cleanupNulls(value);
+            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
+ * ```
+ */
+function default_1(object) {
+    const clone = (0, lodash_1.cloneDeep)(object);
+    cleanupNulls(clone);
+    return clone;
+}
+;
+//# sourceMappingURL=cleanupNulls.js.map

package/dist/helpers/cleanupNulls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanupNulls.js","sourceRoot":"","sources":["../../src/helpers/cleanupNulls.ts"],"names":[],"mappings":";;AAmGA,4BAMC;AAzGD,mCAA6C;AAI7C,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,YAAY,GAAG,CAAC,MAAoB,EAAE,EAAE;IAC5C,MAAM,UAAU,GAAG,CAAC,IAAA,iBAAQ,EAAC,MAAM,CAAC,CAAC;IAErC,IAAI,UAAU,EAAE,CAAC;QACf,OAAO;IACT,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAE1B,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,YAAY,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC;YAED,SAAS;QACX,CAAC;QAED,IAAI,IAAA,iBAAQ,EAAC,KAAK,CAAC,EAAE,CAAC;YACpB,YAAY,CAAC,KAAgC,CAAC,CAAC;YAE/C,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,KAAK,KAAK,IAAI,CAAC;QAE9B,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,mBAAyB,MAA+B;IACtD,MAAM,KAAK,GAAG,IAAA,kBAAS,EAAC,MAAM,CAAC,CAAC;IAEhC,YAAY,CAAC,KAAK,CAAC,CAAC;IAEpB,OAAO,KAAK,CAAC;AACf,CAAC;AAAA,CAAC"}

package/dist/helpers/getReferenceIds.d.ts

@@ -0,0 +1,169 @@
+import Schema from '../Schema';
+/**
+ * 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
+ */
+declare const getReferenceIds: (schema: Schema, schemasMap: Record<string, Schema>) => string[];
+export default getReferenceIds;
+//# sourceMappingURL=getReferenceIds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"getReferenceIds.d.ts","sourceRoot":"","sources":["../../src/helpers/getReferenceIds.ts"],"names":[],"mappings":"AAEA,OAAO,MAAM,MAAM,WAAW,CAAC;AAU/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoKG;AACH,QAAA,MAAM,eAAe,GAAI,QAAQ,MAAM,EAAE,YAAY,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAAM,EA6FnF,CAAC;AAEF,eAAe,eAAe,CAAC"}