@kravc/schema 2.7.5 → 2.8.0-alpha.0

package/dist/Validator.d.ts

@@ -0,0 +1,483 @@
+import Schema from './Schema';
+import type { TargetObject } from './helpers/JsonSchema';
+/**
+ * Validator for validating and normalizing objects against JSON schemas.
+ *
+ * **Intent:**
+ * The Validator class provides a comprehensive solution for validating objects against JSON schemas
+ * with built-in normalization, cleanup, and error handling capabilities. It serves as the primary
+ * interface for ensuring data integrity and consistency in applications that work with structured
+ * data, particularly in API endpoints, data transformation pipelines, and credential systems.
+ *
+ * The validator performs several key operations:
+ * - Validates objects against registered schemas using JSON Schema validation
+ * - Removes attributes not defined in the schema (cleanup)
+ * - Normalizes attribute types (e.g., string '1' → boolean true, string '180' → number 180)
+ * - Handles empty values by optionally nullifying them for non-required fields
+ * - Provides detailed validation errors with structured error information
+ *
+ * **Use Cases:**
+ *
+ * 1. **API Request/Response Validation:**
+ *    - Validate incoming API requests against defined schemas
+ *    - Ensure API responses conform to expected structure
+ *    - Clean up extra fields sent by clients
+ *    - Normalize data from query parameters or form submissions
+ *
+ * 2. **Data Integration & Third-Party Services:**
+ *    - Integrate with external APIs that send loosely-typed data
+ *    - Normalize data from URLs where types are strings (e.g., 'true', '1', '180')
+ *    - Clean up payloads before sending to third-party services (e.g., Telegram, webhooks)
+ *    - Handle data from systems that don't enforce strict typing
+ *
+ * 3. **Credential & Identity Systems:**
+ *    - Validate verifiable credentials against schema definitions
+ *    - Ensure credential subjects conform to expected schemas
+ *    - Normalize credential data from various sources
+ *
+ * 4. **Data Transformation Pipelines:**
+ *    - Normalize data types without full validation
+ *    - Clean up data structures before processing
+ *    - Transform data between different formats while maintaining schema compliance
+ *
+ * 5. **Form & User Input Processing:**
+ *    - Validate and normalize form submissions
+ *    - Handle empty values gracefully (nullify empty strings for optional fields)
+ *    - Clean up null values from nested objects
+ *
+ * **Example - Basic Validation:**
+ * ```typescript
+ * const userSchema = new Schema({
+ *   name: { type: 'string', required: true },
+ *   email: { type: 'string', format: 'email', required: true },
+ *   age: { type: 'number', minimum: 0 }
+ * }, 'User');
+ *
+ * const validator = new Validator([userSchema]);
+ *
+ * const validUser = validator.validate({
+ *   name: 'John Doe',
+ *   email: 'john@example.com',
+ *   age: 30
+ * }, 'User');
+ * // Returns: { name: 'John Doe', email: 'john@example.com', age: 30 }
+ * ```
+ *
+ * **Example - Normalization (String to Type Conversion):**
+ * ```typescript
+ * // Useful when receiving data from URLs or forms where types are strings
+ * const preferencesSchema = new Schema({
+ *   height: { type: 'number' },
+ *   isNotificationEnabled: { type: 'boolean' }
+ * }, 'Preferences');
+ *
+ * const validator = new Validator([preferencesSchema]);
+ *
+ * const normalized = validator.validate({
+ *   height: '180',              // String '180' → number 180
+ *   isNotificationEnabled: '1'  // String '1' → boolean true
+ * }, 'Preferences');
+ * // Returns: { height: 180, isNotificationEnabled: true }
+ * ```
+ *
+ * **Example - Cleanup (Remove Extra Attributes):**
+ * ```typescript
+ * const profileSchema = new Schema({
+ *   name: { type: 'string', required: true },
+ *   email: { type: 'string', required: true }
+ * }, 'Profile');
+ *
+ * const validator = new Validator([profileSchema]);
+ *
+ * const cleaned = validator.validate({
+ *   name: 'John',
+ *   email: 'john@example.com',
+ *   extraField: 'should be removed',
+ *   _internalId: 'should be removed'
+ * }, 'Profile', false, true);
+ * // Returns: { name: 'John', email: 'john@example.com' }
+ * // extraField and _internalId are removed
+ * ```
+ *
+ * **Example - Nullify Empty Values:**
+ * ```typescript
+ * const profileSchema = new Schema({
+ *   name: { type: 'string', required: true },
+ *   gender: { enum: ['Male', 'Female', 'Other'] },  // Optional
+ *   mobileNumber: { type: 'string', pattern: '^\\d+$' }  // Optional
+ * }, 'Profile');
+ *
+ * const validator = new Validator([profileSchema]);
+ *
+ * const result = validator.validate({
+ *   name: 'John',
+ *   gender: '',           // Empty string for optional enum
+ *   mobileNumber: ''      // Empty string for optional pattern field
+ * }, 'Profile', true);    // shouldNullifyEmptyValues = true
+ * // Returns: { name: 'John', gender: null, mobileNumber: null }
+ * // Empty values are converted to null for non-required fields
+ * ```
+ *
+ * **Example - Normalization Only (Without Validation):**
+ * ```typescript
+ * const preferencesSchema = new Schema({
+ *   height: { type: 'number' },
+ *   isNotificationEnabled: { type: 'boolean', default: false }
+ * }, 'Preferences');
+ *
+ * const validator = new Validator([preferencesSchema]);
+ *
+ * // Normalize without validation - useful for partial data
+ * const normalized = validator.normalize({
+ *   height: '180'
+ * }, 'Preferences');
+ * // Returns: { height: 180, isNotificationEnabled: false }
+ * // Applies normalization and defaults without validation
+ * ```
+ *
+ * **Example - Error Handling:**
+ * ```typescript
+ * const validator = new Validator([userSchema]);
+ *
+ * try {
+ *   validator.validate({
+ *     name: '',  // Empty required field
+ *     email: 'invalid-email'  // Invalid format
+ *   }, 'User');
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     const errorDetails = error.toJSON();
+ *     console.error(errorDetails.schemaId);  // 'User'
+ *     console.error(errorDetails.validationErrors);
+ *     // [
+ *     //   { path: '#/name', code: 'MIN_LENGTH', message: '...' },
+ *     //   { path: '#/email', code: 'INVALID_FORMAT', message: '...' }
+ *     // ]
+ *   }
+ * }
+ * ```
+ *
+ * **Example - Schema References:**
+ * ```typescript
+ * const addressSchema = new Schema({
+ *   street: { type: 'string', required: true },
+ *   city: { type: 'string', required: true }
+ * }, 'Address');
+ *
+ * const userSchema = new Schema({
+ *   name: { type: 'string', required: true },
+ *   address: { $ref: 'Address' }
+ * }, 'User');
+ *
+ * const validator = new Validator([addressSchema, userSchema]);
+ *
+ * // Get all schemas referenced by User schema
+ * const referencedIds = validator.getReferenceIds('User');
+ * // Returns: ['Address']
+ * ```
+ *
+ * **Example - Multiple Schemas:**
+ * ```typescript
+ * const statusSchema = new Schema({ enum: ['ACTIVE', 'INACTIVE'] }, 'Status');
+ * const profileSchema = new Schema({
+ *   name: { type: 'string', required: true },
+ *   status: { $ref: 'Status' }
+ * }, 'Profile');
+ *
+ * const validator = new Validator([statusSchema, profileSchema]);
+ *
+ * const result = validator.validate({
+ *   name: 'John',
+ *   status: 'ACTIVE'
+ * }, 'Profile');
+ * ```
+ */
+declare class Validator {
+    private _engine;
+    private _schemasMap;
+    private _jsonSchemasMap;
+    /**
+     * Creates a validator instance for a collection of schemas.
+     *
+     * **Intent:** Initialize a validator with a set of schemas that can be used for validation
+     * and normalization. The constructor validates that all schemas are valid JSON schemas and
+     * that there are no duplicate schema IDs.
+     *
+     * **Use Cases:**
+     * - Initialize a validator with all schemas needed for an application
+     * - Set up a validator for a specific domain or module
+     * - Create validators for different environments (dev, staging, production)
+     *
+     * @param schemas - Array of Schema instances to register with this validator.
+     *                  All schemas must have unique IDs and valid JSON Schema structure.
+     *                  Referenced schemas (via $ref) must be included in this array.
+     *
+     * @throws Error if no schemas are provided
+     * @throws Error if multiple schemas have the same ID
+     * @throws Error if any schema has invalid JSON Schema structure or missing references
+     *
+     * **Example:**
+     * ```typescript
+     * const userSchema = new Schema({ name: { type: 'string' } }, 'User');
+     * const statusSchema = new Schema({ enum: ['ACTIVE', 'INACTIVE'] }, 'Status');
+     *
+     * const validator = new Validator([userSchema, statusSchema]);
+     * ```
+     *
+     * **Example - With Schema References:**
+     * ```typescript
+     * const addressSchema = new Schema({
+     *   street: { type: 'string' }
+     * }, 'Address');
+     *
+     * const userSchema = new Schema({
+     *   name: { type: 'string' },
+     *   address: { $ref: 'Address' }  // References Address schema
+     * }, 'User');
+     *
+     * // Both schemas must be provided
+     * const validator = new Validator([addressSchema, userSchema]);
+     * ```
+     */
+    constructor(schemas: Schema[] | undefined);
+    /**
+     * Validates, cleans, and normalizes an object against a registered schema.
+     *
+     * **Intent:** Perform comprehensive validation and transformation of objects to ensure they
+     * conform to schema definitions. This method combines validation, attribute cleanup, type
+     * normalization, and optional empty value handling in a single operation.
+     *
+     * **Use Cases:**
+     * - Validate API request payloads before processing
+     * - Clean up objects by removing undefined attributes
+     * - Normalize data types from loosely-typed sources (URLs, forms, external APIs)
+     * - Handle empty values gracefully for optional fields
+     * - Prepare data for storage or transmission
+     *
+     * **Processing Pipeline:**
+     * 1. Deep clones the input object
+     * 2. Optionally removes null values (if `shouldCleanupNulls` is true)
+     * 3. Removes attributes not defined in the schema
+     * 4. Normalizes attribute types (string → number/boolean, etc.)
+     * 5. Validates against JSON Schema
+     * 6. Optionally nullifies empty values for non-required fields
+     * 7. Returns validated and normalized object, or throws ValidationError
+     *
+     * @param object - The object to validate and normalize
+     * @param schemaId - The ID of the schema to validate against (must be registered in constructor)
+     * @param shouldNullifyEmptyValues - If true, converts empty strings to null for non-required
+     *                                   fields that fail format/pattern/enum validation. Useful for
+     *                                   handling form submissions where empty fields are sent as ''.
+     * @param shouldCleanupNulls - If true, removes null values from the object before processing.
+     *                            Useful for cleaning up data structures.
+     *
+     * @returns The validated, cleaned, and normalized object
+     *
+     * @throws Error if schema with `schemaId` is not found
+     * @throws ValidationError if validation fails (contains detailed error information)
+     *
+     * **Example - Basic Validation:**
+     * ```typescript
+     * const validator = new Validator([userSchema]);
+     *
+     * const result = validator.validate({
+     *   name: 'John',
+     *   email: 'john@example.com'
+     * }, 'User');
+     * ```
+     *
+     * **Example - With Cleanup:**
+     * ```typescript
+     * const result = validator.validate({
+     *   name: 'John',
+     *   extraField: 'removed',
+     *   nullField: null
+     * }, 'User', false, true);
+     * // extraField and nullField are removed
+     * ```
+     *
+     * **Example - With Normalization:**
+     * ```typescript
+     * const result = validator.validate({
+     *   name: 'John',
+     *   age: '30',              // String → number
+     *   isActive: 'true'        // String → boolean
+     * }, 'User');
+     * // age becomes 30, isActive becomes true
+     * ```
+     *
+     * **Example - Nullify Empty Values:**
+     * ```typescript
+     * const result = validator.validate({
+     *   name: 'John',
+     *   optionalEmail: '',      // Empty string
+     *   optionalPhone: ''       // Empty string
+     * }, 'User', true);
+     * // optionalEmail and optionalPhone become null (if not required)
+     * ```
+     *
+     * **Example - Error Handling:**
+     * ```typescript
+     * try {
+     *   validator.validate({ name: '' }, 'User');
+     * } catch (error) {
+     *   if (error instanceof ValidationError) {
+     *     const details = error.toJSON();
+     *     // Access error.schemaId, error.validationErrors, etc.
+     *   }
+     * }
+     * ```
+     */
+    validate(object: TargetObject, schemaId: string, shouldNullifyEmptyValues?: boolean, shouldCleanupNulls?: boolean): any;
+    /**
+     * Normalizes object attributes using a schema without performing validation.
+     *
+     * **Intent:** Apply type normalization and default values to an object without the strictness
+     * of full validation. This is useful when you want to transform data types but don't need
+     * complete schema compliance, or when working with partial/incomplete data.
+     *
+     * **Use Cases:**
+     * - Normalize data types from loosely-typed sources (URLs, query parameters, forms)
+     * - Apply default values from schemas to partial objects
+     * - Transform data before validation in a separate step
+     * - Prepare data for display or processing without strict validation
+     * - Handle partial updates where not all fields are present
+     *
+     * **What It Does:**
+     * - Deep clones the input object
+     * - Normalizes attribute types (string '1' → boolean true, string '180' → number 180)
+     * - Applies default values from schema definitions
+     * - Does NOT validate required fields, formats, patterns, or enums
+     * - Does NOT remove undefined attributes
+     *
+     * @param object - The object to normalize
+     * @param schemaId - The ID of the schema to use for normalization (must be registered)
+     *
+     * @returns A new object with normalized types and applied defaults
+     *
+     * @throws Error if schema with `schemaId` is not found
+     *
+     * **Example - Type Normalization:**
+     * ```typescript
+     * const preferencesSchema = new Schema({
+     *   height: { type: 'number' },
+     *   isNotificationEnabled: { type: 'boolean', default: false }
+     * }, 'Preferences');
+     *
+     * const validator = new Validator([preferencesSchema]);
+     *
+     * const normalized = validator.normalize({
+     *   height: '180',              // String → number
+     *   isNotificationEnabled: '1'  // String '1' → boolean true
+     * }, 'Preferences');
+     * // Returns: { height: 180, isNotificationEnabled: true }
+     * ```
+     *
+     * **Example - Apply Defaults:**
+     * ```typescript
+     * const userSchema = new Schema({
+     *   name: { type: 'string', required: true },
+     *   status: { enum: ['ACTIVE', 'INACTIVE'], default: 'ACTIVE' },
+     *   role: { enum: ['USER', 'ADMIN'], default: 'USER' }
+     * }, 'User');
+     *
+     * const validator = new Validator([userSchema]);
+     *
+     * const normalized = validator.normalize({
+     *   name: 'John'
+     *   // status and role are not provided
+     * }, 'User');
+     * // Returns: { name: 'John', status: 'ACTIVE', role: 'USER' }
+     * ```
+     *
+     * **Example - Partial Data:**
+     * ```typescript
+     * // Useful for partial updates where validation might fail
+     * const partial = validator.normalize({
+     *   age: '25'  // Only updating age, other fields missing
+     * }, 'User');
+     * // Normalizes age to number without requiring other fields
+     * ```
+     */
+    normalize(object: TargetObject, schemaId: string): any;
+    /**
+     * Returns a map of all registered schemas by their IDs.
+     *
+     * **Intent:** Provide access to all schemas registered with this validator, enabling
+     * inspection, iteration, or programmatic access to schema definitions.
+     *
+     * **Use Cases:**
+     * - Inspect all available schemas
+     * - Iterate over schemas for bulk operations
+     * - Access schema metadata or properties
+     * - Build UI components that list available schemas
+     * - Debug schema registration
+     *
+     * @returns A record mapping schema IDs to Schema instances
+     *
+     * **Example:**
+     * ```typescript
+     * const validator = new Validator([userSchema, statusSchema]);
+     *
+     * const schemas = validator.schemasMap;
+     * // { 'User': Schema instance, 'Status': Schema instance }
+     *
+     * // Access a specific schema
+     * const userSchema = schemas['User'];
+     *
+     * // Iterate over all schemas
+     * Object.keys(schemas).forEach(id => {
+     *   console.log(`Schema ${id} is registered`);
+     * });
+     * ```
+     */
+    get schemasMap(): Record<string, Schema>;
+    /**
+     * Returns the IDs of all schemas referenced by the specified schema.
+     *
+     * **Intent:** Discover schema dependencies by finding all schemas referenced via `$ref`
+     * in a given schema. This is useful for understanding schema relationships and building
+     * dependency graphs.
+     *
+     * **Use Cases:**
+     * - Build schema dependency graphs
+     * - Validate that all referenced schemas are available
+     * - Generate documentation showing schema relationships
+     * - Determine which schemas need to be loaded together
+     * - Debug schema reference issues
+     *
+     * @param schemaId - The ID of the schema to analyze for references
+     *
+     * @returns An array of schema IDs that are referenced by the specified schema
+     *
+     * @throws Error if schema with `schemaId` is not found
+     *
+     * **Example:**
+     * ```typescript
+     * const addressSchema = new Schema({
+     *   street: { type: 'string' }
+     * }, 'Address');
+     *
+     * const userSchema = new Schema({
+     *   name: { type: 'string' },
+     *   address: { $ref: 'Address' },
+     *   status: { $ref: 'Status' }
+     * }, 'User');
+     *
+     * const validator = new Validator([addressSchema, statusSchema, userSchema]);
+     *
+     * const references = validator.getReferenceIds('User');
+     * // Returns: ['Address', 'Status']
+     * ```
+     *
+     * **Example - Nested References:**
+     * ```typescript
+     * // If Address schema also references Country schema
+     * const references = validator.getReferenceIds('User');
+     * // Returns: ['Address', 'Status', 'Country'] (includes nested references)
+     * ```
+     */
+    getReferenceIds(schemaId: string): string[];
+}
+export default Validator;
+//# sourceMappingURL=Validator.d.ts.map

package/dist/Validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Validator.d.ts","sourceRoot":"","sources":["../src/Validator.ts"],"names":[],"mappings":"AAIA,OAAO,MAAM,MAAM,UAAU,CAAC;AAO9B,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,sBAAsB,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+LG;AACH,cAAM,SAAS;IACb,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,eAAe,CAAiB;IAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;gBACS,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS;IAmCzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuFG;IACH,QAAQ,CACN,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,EAChB,wBAAwB,UAAQ,EAChC,kBAAkB,UAAQ;IAwD5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqEG;IACH,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM;IAShD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,IAAI,UAAU,2BAEb;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM;CAKjC;AAED,eAAe,SAAS,CAAC"}