reslib 1.1.0 → 2.0.0

package/build/validator/rules.types.d.ts

@@ -0,0 +1,167 @@
+import { ClassConstructor } from '../types';
+/**
+ * ## Validator Rule Name
+ *
+ * Represents a valid reference key for any registered validation rule.
+ *
+ * This type acts as the central vocabulary for the validation system, generated
+ * directly from the keys of `ValidatorRuleParamTypes`. It ensures that any rule
+ * name used in your code (whether as a string literal or object key) corresponds
+ * to a known, well-defined validation rule.
+ *
+ * ### Usage
+ * You encounter `ValidatorRuleName` in two primary contexts:
+ * 1. **String Rules**: When using "Named Rules" for parameterless validation.
+ * 2. **Object Rules**: As the key in a rule object to specify which rule to apply.
+ *
+ * ### Examples
+ * ```typescript
+ * // As a type annotation:
+ * const myRules: ValidatorRuleName[] = ["Required", "Email"];
+ *
+ * // In object rules:
+ * const ruleObj = {
+ *   MinLength: [5],  // "MinLength" is a ValidatorRuleName
+ *   Required: []     // "Required" is a ValidatorRuleName
+ * };
+ *
+ * // In custom lookups (e.g., getting a rule function):
+ * const ruleFn = Validator.getRule("Email");
+ * ```
+ *
+ * ### Type Safety
+ * Because this is a string union type derived from the keys of the parameter map,
+ * TypeScript will produce an error if you try to use a misspelled or non-existent rule definition.
+ *
+ * ```typescript
+ * const valid: ValidatorRuleName = "Required";    // ✅
+ * const invalid: ValidatorRuleName = "Reguired";  // ❌ Type error: '"Reguired"' is not assignable...
+ * ```
+ *
+ * @public
+ * @see {@link ValidatorRuleParamTypes} - The source definition map.
+ */
+export type ValidatorRuleName = keyof ValidatorRuleParamTypes & string;
+/**
+ * ## Validation Rules Parameter Map
+ *
+ * Central type definition mapping validation rule names to their parameter signatures.
+ * This interface serves as the authoritative source for all built-in validation rules,
+ * defining the exact parameter types each rule accepts.
+ *
+ * ### Purpose
+ * Provides compile-time type safety for validation rule parameters across the entire
+ * validation system. Each property represents a built-in validation rule and its
+ * expected parameter structure. This is a static interface with no generics.
+ *
+ * ### Type Structure
+ * - **Key**: Rule name (string literal from {@link ValidatorRuleName})
+ * - **Value**: Parameter array type (extends {@link ValidatorRuleParams})
+ *
+ * ### Parameter Type Patterns
+ * - **Empty Arrays `[]`**: Rules that take no parameters (e.g., "Required", "Email")
+ * - **Complex Parameters**: Rules with mixed required/optional parameters
+ *
+ * ### Usage in Type System
+ * This interface is used throughout the validator to:
+ * - Type-check rule parameters at compile time
+ * - Generate {@link ValidatorRuleName} union type
+ * - Create {@link ValidatorRuleFunctionsMap} registry type
+ * - Validate rule definitions in rule implementation files
+ *
+ * ### Rule Categories
+ *
+ * #### Presence Validation
+ * - **Required**: Ensures value is present and not empty
+ * - **Nullable**: Allows null/undefined values (skips validation)
+ * - **Optional**: Allows undefined values (skips validation)
+ * - **Empty**: Allows empty strings (validation skipped if "")
+ *
+ * #### Type Validation
+ * - **String**: Validates value is a string
+ * - **Number**: Validates value is a number
+ * - **NonNullString**: Validates value is a non-null string
+ *
+ * #### String Validation
+ * - **MinLength**: Minimum character length requirement
+ * - **MaxLength**: Maximum character length limit
+ * - **Length**: Exact length or length range (min and optional max)
+ * - **FileName**: Valid file name format
+ *
+ * #### Numeric Validation
+ * - **NumberGT**: Value must be greater than specified number
+ * - **NumberGTE**: Value must be >= specified number
+ * - **NumberLT**: Value must be less than specified number
+ * - **NumberLTE**: Value must be <= specified number
+ * - **NumberEQ**: Value must equal specified number
+ * - **NumberNE**: Value must differ from specified number
+ *
+ * #### Format Validation
+ * - **Email**: Valid email address format
+ * - **Url**: Valid URL format
+ * - **PhoneNumber**: Valid phone number (with optional country code)
+ * - **EmailOrPhoneNumber**: Valid email or phone number
+ *
+ * ### Parameter Examples
+ * ```typescript
+ * // Rules with no parameters
+ * Required: ValidatorRuleParams<[]>;           // "Required"
+ * Email: ValidatorRuleParams<[]>;              // "Email"
+ *
+ * // Rules with single parameters
+ * MinLength: ValidatorRuleParams<[number]>;    // {MinLength:[5]}
+ * NumberEQ: ValidatorRuleParams<[number]>;  // "NumberEQ[42]"
+ *
+ * // Rules with optional parameters
+ * PhoneNumber: ValidatorRuleParams<[CountryCode?]>; // "PhoneNumber" or "PhoneNumber[US]"
+ *
+ * // Rules with multiple parameters
+ * Length: ValidatorRuleParams<[number, number?]>; // "Length[5]" or "Length[5,10]"
+ * ```
+ *
+ * ### Extending the Rules Map
+ * When adding new validation rules:
+ * 1. Add the rule name and parameter type to this interface
+ * 2. Implement the rule function in the appropriate rule file
+ * 3. Register the rule in the validator's rule registry
+ * 4. Update rule name unions and type definitions as needed
+ *
+ * ### Relationship to Validation System
+ * - **Foundation**: Base type for all rule definitions
+ * - **Type Safety**: Ensures parameter type checking
+ * - **Rule Discovery**: Used to generate valid rule names
+ * - **Function Signatures**: Defines parameter types for rule functions
+ * - **Runtime Validation**: Parameters validated against these types
+ *
+ * @public
+ * @template Context - Type of the optional validation context
+ * @see {@link ValidatorRuleName} - Union type derived from this interface's keys
+ * @see {@link ValidatorRuleFunctionsMap} - Registry type using this interface
+ * @see {@link ValidatorRuleParams} - Base parameter type for all rules
+ * @see {@link Validator} - Main validator class that uses these rules
+ */
+export interface ValidatorRuleParamTypes<Context = unknown> {
+}
+/**
+ * ## Validator Class Input
+ *
+ * Represents a partial data object corresponding to a target class structure.
+ * Used for describing the input data for class-based validation without requiring
+ * a full instance of the class.
+ *
+ * @template TClass - The class constructor
+ *
+ * @public
+ */
+export type ValidatorClassInput<TClass extends ClassConstructor = ClassConstructor> = Partial<Record<ValidatorClassKeys<TClass>, any>>;
+/**
+ * ## Validator Class Keys
+ *
+ * Type alias for extracting the valid property keys from a target class or constructor.
+ * Used to ensure type safety when referencing properties of validated class instances.
+ *
+ * @template TClass - The class constructor
+ *
+ * @public
+ */
+export type ValidatorClassKeys<TClass extends ClassConstructor> = keyof InstanceType<TClass>;

package/build/validator/rules.types.js

@@ -0,0 +1 @@
+'use strict';