kanun 0.1.8 → 1.0.2

package/dist/index.d.ts

@@ -45,6 +45,100 @@ declare abstract class IRuleContract {
   trans(path: string, params?: GenericObject): string;
 }
 //#endregion
+//#region src/Rules/in.d.ts
+declare class In extends BaseRule {
+  /**
+   * The name of the rule.
+   */
+  rule: string;
+  /**
+   * The accepted values.
+   */
+  values: (string | number)[];
+  /**
+   * Create a new In rule instance.
+   */
+  constructor(values: (string | number)[]);
+  /**
+   * Convert the rule to a validation string.
+   */
+  toString(): string;
+}
+//#endregion
+//#region src/Rules/notIn.d.ts
+declare class NotIn extends BaseRule {
+  /**
+   * The name of the rule.
+   */
+  rule: string;
+  /**
+   * The accepted values.
+   */
+  values: (string | number)[];
+  /**
+   * Create a new NotIn rule instance.
+   */
+  constructor(values: (string | number)[]);
+  /**
+   * Convert the rule to a validation string.
+   */
+  toString(): string;
+}
+//#endregion
+//#region src/Rules/regex.d.ts
+declare class Regex extends IRuleContract {
+  /**
+   * The Regular expression to validate
+   */
+  regex: RegExp;
+  /**
+   * Flag that decides whether the value should match the regular expression or not
+   */
+  shouldMatch: boolean;
+  constructor(regex: RegExp, shouldMatch?: boolean);
+  passes(value: any): boolean;
+  getMessage(): string;
+}
+//#endregion
+//#region src/Rules/requiredIf.d.ts
+declare class RequiredIf extends BaseRule {
+  /**
+   * The condition that validates the attribute
+   */
+  condition: boolean | CallableFunction;
+  /**
+   * Create a new required validation rule based on a condition.
+   */
+  constructor(condition: boolean | CallableFunction);
+  /**
+   * Convert the rule to a validation string.
+   */
+  toString(): string;
+}
+//#endregion
+//#region src/Contracts/ValidationRuleName.d.ts
+type ValidationRuleAutocompleteKind = 'plain' | 'paramable';
+interface ValidationRuleAutocompleteMap {}
+/**
+ * Backward-compatible alias for older plugin augmentations.
+ */
+interface CustomValidationRuleNameMap {}
+type LiteralUnion<T extends U, U = string> = T | (U & Record<never, never>);
+type PluginValidationRuleNameMap = ValidationRuleAutocompleteMap & CustomValidationRuleNameMap;
+type CustomParamableValidationRuleName = Extract<{ [K in keyof PluginValidationRuleNameMap]: PluginValidationRuleNameMap[K] extends 'paramable' ? K : never }[keyof PluginValidationRuleNameMap], string>;
+type CustomPlainRuleName = Extract<{ [K in keyof PluginValidationRuleNameMap]: PluginValidationRuleNameMap[K] extends 'plain' ? K : never }[keyof PluginValidationRuleNameMap], string>;
+type ParamableValidationRuleName = 'accepted_if' | 'after' | 'after_or_equal' | 'before' | 'before_or_equal' | 'between' | 'date_equals' | 'datetime' | 'declined_if' | 'digits_between' | 'different' | 'exists' | 'ends_with' | 'gt' | 'gte' | 'in' | 'includes' | 'lt' | 'lte' | 'max' | 'min' | 'not_in' | 'not_includes' | 'required_if' | 'required_unless' | 'required_with' | 'required_with_all' | 'required_without' | 'required_without_all' | 'same' | 'size' | 'starts_with' | 'unique' | CustomParamableValidationRuleName;
+type PlainRuleName = 'accepted' | 'alpha' | 'alpha_dash' | 'alpha_num' | 'array' | 'array_unique' | 'bail' | 'boolean' | 'confirmed' | 'date' | 'declined' | 'digits' | 'email' | 'integer' | 'json' | 'not_regex' | 'nullable' | 'numeric' | 'object' | 'present' | 'regex' | 'required' | 'sometimes' | 'string' | 'url' | 'hex' | 'uuid' | CustomPlainRuleName;
+type ValidationRuleName = ParamableValidationRuleName | PlainRuleName;
+type MethodRules = Regex | In | NotIn | RequiredIf;
+type ParamableRuleString = `${ParamableValidationRuleName}:${string}`;
+type ValidationRuleString = LiteralUnion<ValidationRuleName | ParamableRuleString>;
+/**
+ * Single rule value (supports autocomplete + arbitrary strings + RuleContract instances)
+ */
+type ValidationRuleEntry = ValidationRuleString | IRuleContract | MethodRules;
+type ValidationRuleSet = ValidationRuleEntry | readonly ValidationRuleEntry[] | LiteralUnion<`${ValidationRuleName}${string & `|${string}`}` | `${ParamableRuleString}${string & `|${string}`}`>;
+//#endregion
 //#region src/payloads/replaceAttributePayload.d.ts
 declare class replaceAttributePayload {
   /**
@@ -71,7 +165,7 @@ declare class replaceAttributePayload {
 }
 //#endregion
 //#region src/Contracts/BaseContract.d.ts
-type InitialRule = string | ValidationCallback | IRuleContract | BaseRule;
+type InitialRule = ValidationRuleEntry | ValidationCallback | BaseRule;
 type TRule = string | IRuleContract;
 type NestedStringMap = {
   [key: string]: string | NestedStringMap;
@@ -279,6 +373,33 @@ declare class ErrorBag {
   clone(): ErrorBag;
 }
 //#endregion
+//#region src/Rules/registerRule.d.ts
+declare function register(rule: string, validate: (value: any, parameters?: string[], attribute?: string) => boolean | Promise<boolean>, replaceMessage?: (message: string, paramters: string[], data?: object, getDisplayableAttribute?: GenericCallable) => string): boolean;
+declare function registerImplicit(rule: string, validate: (value: any, parameters?: string[] | number[], attribute?: string) => boolean | Promise<boolean>, replaceMessage?: (message: string, paramters: string[], data?: object, getDisplayableAttribute?: GenericCallable) => string): void;
+//#endregion
+//#region src/Plugin.d.ts
+interface ValidationValueInspector {
+  type: string;
+  matches: (value: any) => boolean;
+  size?: (value: any) => number;
+}
+interface ValidatorPluginApi {
+  registerRule: typeof register;
+  registerImplicitRule: typeof registerImplicit;
+  registerValueInspector: (inspector: ValidationValueInspector) => void;
+  extendTranslations: (translations: GenericObject) => void;
+}
+interface ValidatorPlugin {
+  name: string;
+  install: (api: ValidatorPluginApi) => void;
+}
+declare function definePlugin(plugin: ValidatorPlugin): ValidatorPlugin;
+declare function usePlugin(plugin: ValidatorPlugin): void;
+declare function registerValueInspector(inspector: ValidationValueInspector): void;
+declare function getValidationValueInspector(value: any): ValidationValueInspector | undefined;
+declare function getValidationMessageType(value: any, hasNumericRule?: boolean): string;
+declare function getValidationSize(value: any, hasNumericRule?: boolean): number;
+//#endregion
 //#region src/BaseValidator.d.ts
 declare class BaseValidator<D extends GenericObject = GenericObject> {
   /**
@@ -321,15 +442,68 @@ declare class BaseValidator<D extends GenericObject = GenericObject> {
    * Object of custom attribute name;
    */
   customAttributes: CustomAttributes<D>;
+  /**
+   * Arbitrary per-validator context for plugins.
+   */
+  private context;
   constructor(data: D, rules: InitialRules<D>, customMessages?: CustomMessages<D>, customAttributes?: CustomAttributes<D>);
+  static use(plugin: ValidatorPlugin): typeof BaseValidator;
+  static useContext(context?: GenericObject): typeof BaseValidator;
+  use(plugin: ValidatorPlugin): this;
   setData<ND extends GenericObject>(data: ND): BaseValidator<ND>;
   setRules(rules: InitialRules<D>): this;
   setLang(lang: string): this;
+  /**
+   * Set the validator's context.
+   */
+  withContext(context?: GenericObject): this;
+  /**
+   * Get the validator's context.
+   * This is useful for custom rules that need access to additional data or services.
+   *
+   * @returns The current context object
+   */
+  getContext(): GenericObject;
+  /**
+   * Get the current language used by the validator.
+   *
+   * @returns
+   */
   getLang(): string;
+  /**
+   * Set custom error messages for the validator.
+   *
+   * @param customMessages
+   * @returns
+   */
   setCustomMessages(customMessages?: CustomMessages<D>): this;
+  /**
+   * Set custom attribute names for the validator.
+   *
+   * @param customAttributes
+   * @returns
+   */
   setCustomAttributes(customAttributes?: CustomAttributes<D>): this;
+  /**
+   * Set whether the validator should stop validating after the first failure.
+   *
+   * @param stopOnFirstFailure
+   * @returns
+   */
   stopOnFirstFailure(stopOnFirstFailure?: boolean): this;
+  /**
+   * Get the error messages related to the validation.
+   *
+   * @returns
+   */
   errors(): ErrorBag;
+  /**
+   * Clear the error messages for the given keys.
+   * If no keys are provided, all error messages will be cleared.
+   *
+   * @param keys  The keys of the error messages to clear
+   * @returns     The updated ErrorBag instance
+   */
   clearErrors(keys?: string[]): ErrorBag;
   /**
    * Create a new ErrorBag instance and set the custom errors, thus removing previous error messages
@@ -349,6 +523,9 @@ declare class BaseValidator<D extends GenericObject = GenericObject> {
   validateAsync(key?: string, value?: any): Promise<boolean>;
   /**
    * Get the displayable name of the attribute.
+   *
+   * @param attribute
+   * @returns
    */
   getDisplayableAttribute(attribute: string): string;
   private addCustomErrors;
@@ -581,88 +758,6 @@ declare abstract class IValidationRule {
   passes(value: any, attribute: string): boolean | Promise<boolean>;
 }
 //#endregion
-//#region src/Rules/in.d.ts
-declare class In extends BaseRule {
-  /**
-   * The name of the rule.
-   */
-  rule: string;
-  /**
-   * The accepted values.
-   */
-  values: (string | number)[];
-  /**
-   * Create a new In rule instance.
-   */
-  constructor(values: (string | number)[]);
-  /**
-   * Convert the rule to a validation string.
-   */
-  toString(): string;
-}
-//#endregion
-//#region src/Rules/notIn.d.ts
-declare class NotIn extends BaseRule {
-  /**
-   * The name of the rule.
-   */
-  rule: string;
-  /**
-   * The accepted values.
-   */
-  values: (string | number)[];
-  /**
-   * Create a new NotIn rule instance.
-   */
-  constructor(values: (string | number)[]);
-  /**
-   * Convert the rule to a validation string.
-   */
-  toString(): string;
-}
-//#endregion
-//#region src/Rules/regex.d.ts
-declare class Regex extends IRuleContract {
-  /**
-   * The Regular expression to validate
-   */
-  regex: RegExp;
-  /**
-   * Flag that decides whether the value should match the regular expression or not
-   */
-  shouldMatch: boolean;
-  constructor(regex: RegExp, shouldMatch?: boolean);
-  passes(value: any): boolean;
-  getMessage(): string;
-}
-//#endregion
-//#region src/Rules/requiredIf.d.ts
-declare class RequiredIf extends BaseRule {
-  /**
-   * The condition that validates the attribute
-   */
-  condition: boolean | CallableFunction;
-  /**
-   * Create a new required validation rule based on a condition.
-   */
-  constructor(condition: boolean | CallableFunction);
-  /**
-   * Convert the rule to a validation string.
-   */
-  toString(): string;
-}
-//#endregion
-//#region src/Contracts/ValidationRuleName.d.ts
-type ParamableValidationRuleName = 'accepted_if' | 'after' | 'after_or_equal' | 'before' | 'before_or_equal' | 'between' | 'date_equals' | 'datetime' | 'declined_if' | 'digits_between' | 'different' | 'exists' | 'ends_with' | 'gt' | 'gte' | 'in' | 'includes' | 'lt' | 'lte' | 'max' | 'min' | 'not_in' | 'not_includes' | 'required_if' | 'required_unless' | 'required_with' | 'required_with_all' | 'required_without' | 'required_without_all' | 'same' | 'size' | 'starts_with' | 'unique';
-type PlainRuleName = 'accepted' | 'alpha' | 'alpha_dash' | 'alpha_num' | 'array' | 'array_unique' | 'bail' | 'boolean' | 'confirmed' | 'date' | 'declined' | 'digits' | 'email' | 'integer' | 'json' | 'not_regex' | 'nullable' | 'numeric' | 'object' | 'present' | 'regex' | 'required' | 'sometimes' | 'string' | 'url' | 'hex' | 'uuid';
-type ValidationRuleName = ParamableValidationRuleName | PlainRuleName;
-type MethodRules = Regex | In | NotIn | RequiredIf;
-/**
- * Single rule value (supports autocomplete + arbitrary strings + RuleContract instances)
- */
-type RuleName = ValidationRuleName | `${ParamableValidationRuleName}:${string}` | IRuleContract | MethodRules;
-type ValidationRuleSet = RuleName | RuleName[] | `${ValidationRuleName}${string & `|${string}`}`;
-//#endregion
 //#region src/Contracts/ValidatorContracts.d.ts
 /**
  * Parse rule names from rule string or string[] definitions
@@ -695,6 +790,8 @@ declare class IValidator<D extends Record<string, any> = any, R extends RulesFor
    */
   static make<D extends Record<string, any>, R extends RulesForData<D>>(data: D, rules: R, messages: Partial<Record<MessagesForRules<R>, string>>): IValidator<D, R>;
   static useDatabase(driver: IDatabaseDriver): typeof IValidator;
+  static use(plugin: ValidatorPlugin): typeof IValidator;
+  static useContext(context: Record<string, any>): typeof IValidator;
   /**
    * Run the validator and store results.
    */
@@ -719,6 +816,9 @@ declare class IValidator<D extends Record<string, any> = any, R extends RulesFor
    * Stop validation on first failure.
    */
   stopOnFirstFailure(): this;
+  use(plugin: ValidatorPlugin): this;
+  withContext(context: Record<string, any>): this;
+  getContext(): Record<string, any>;
   /**
    * Get the data that passed validation.
    */
@@ -777,6 +877,29 @@ declare class IValidator<D extends Record<string, any> = any, R extends RulesFor
   getDatabaseDriver(): IDatabaseDriver | undefined;
 }
 //#endregion
+//#region src/Context.d.ts
+type ValidatorContext = Record<string, any>;
+/**
+ * Get the current validator context.
+ *
+ * @returns
+ */
+declare function getValidatorContext(): ValidatorContext;
+/**
+ * Use a context for the current validator instance and all of its children.
+ *
+ * @param context
+ * @returns
+ */
+declare function useValidatorContext(context?: ValidatorContext): ValidatorContext;
+/**
+ * Run a function with a given validator context.
+ *
+ * @param context The context to use during the execution of the callback
+ * @param callback The function to execute with the given context
+ */
+declare function runWithValidatorContext<T>(context: ValidatorContext, callback: () => T): T;
+//#endregion
 //#region src/Rules/password.d.ts
 declare class Password$1 extends IRuleContract {
   /**
@@ -865,10 +988,6 @@ declare class Password$1 extends IRuleContract {
   static default(): IRuleContract | Password$1;
 }
 //#endregion
-//#region src/Rules/registerRule.d.ts
-declare function register(rule: string, validate: (value: any, parameters?: string[], attribute?: string) => boolean | Promise<boolean>, replaceMessage?: (message: string, paramters: string[], data?: object, getDisplayableAttribute?: GenericCallable) => string): boolean;
-declare function registerImplicit(rule: string, validate: (value: any, parameters?: string[] | number[], attribute?: string) => boolean | Promise<boolean>, replaceMessage?: (message: string, paramters: string[], data?: object, getDisplayableAttribute?: GenericCallable) => string): void;
-//#endregion
 //#region src/rule.d.ts
 declare function requiredIf(callback: boolean | CallableFunction): RequiredIf;
 declare function ruleIn(values: (string | number)[]): In;
@@ -1020,12 +1139,36 @@ declare class Validator<D extends Record<string, any> = any, R extends RulesForD
   private errorBagName;
   private registeredCustomRules;
   private shouldStopOnFirstFailure;
+  private context;
   constructor(data: D, rules: R, messages?: Partial<Record<MessagesForRules<R>, string>>);
   /**
    * Validate the data and return the instance
    */
   static make<D extends Record<string, any>, R extends RulesForData<D>>(data: D, rules: R, messages?: Partial<Record<MessagesForRules<R>, string>>): Validator<D, R>;
   static useDatabase(driver: IDatabaseDriver): typeof Validator;
+  /**
+   * Set the validator's context.
+   *
+   * @param context
+   * @returns
+   */
+  static useContext(context?: Record<string, any>): typeof Validator;
+  /**
+   * Register a plugin with the validator.
+   * Plugins can add rules, messages, and even override existing rules and messages.
+   *
+   * @param plugin The plugin to register
+   * @returns The Validator class for chaining
+   */
+  static use(plugin: ValidatorPlugin): typeof Validator;
+  /**
+   * Register a plugin with the validator.
+   * Plugins can add rules, messages, and even override existing rules and messages.
+   *
+   * @param plugin The plugin to register
+   * @returns The Validator instance for chaining
+   */
+  use(plugin: ValidatorPlugin): this;
   /**
    * Run the validator and store results.
    */
@@ -1050,6 +1193,21 @@ declare class Validator<D extends Record<string, any> = any, R extends RulesForD
    * Stop validation on first failure.
    */
   stopOnFirstFailure(): this;
+  /**
+   * Set the validator's context.
+   * This is useful for custom rules that need access to additional data or services.
+   *
+   * @param context
+   * @returns
+   */
+  withContext(context?: Record<string, any>): this;
+  /**
+   * Get the validator's context.
+   * This is useful for custom rules that need access to additional data or services.
+   *
+   * @returns The current context object
+   */
+  getContext(): Record<string, any>;
   /**
    * Get the data that passed validation.
    */
@@ -1144,6 +1302,10 @@ declare class Lang {
    * Store the translations passed by the user
    */
   static translations: GenericObject;
+  /**
+   * Store translations contributed by plugins.
+   */
+  static translationExtensions: GenericObject;
   /**
    * Stores the messages that are already loaded
    */
@@ -1169,6 +1331,10 @@ declare class Lang {
    * @param translations
    */
   static setTranslationObject(translations: GenericObject): void;
+  /**
+   * Merge additional translations into the global catalog.
+   */
+  static extendTranslationObject(translations: GenericObject): void;
   /**
    * Set the default lang that should be used. And assign the default messages
    *
@@ -1194,6 +1360,7 @@ declare class Lang {
    * @returns
    */
   static load(lang: string): void;
+  private static resetLoadedMessages;
 }
 //#endregion
 //#region src/Providers/ValidationServiceProvider.d.ts
@@ -1341,6 +1508,32 @@ declare function convertValuesToNull(values: string[]): (string | null)[];
  * @returns
  */
 declare const plural: (word: string, count: number) => string;
+/**
+ * Determine if a value is an object. Arrays and null are not considered objects.
+ *
+ * @param value
+ * @returns
+ */
+declare function isObject(value: unknown): value is GenericObject;
+/**
+ * Deeply merge two objects.
+ * The source object will overwrite the target object when there is a conflict.
+ * Arrays and non-object values will be overwritten, not merged.
+ *
+ * @param target
+ * @param source
+ * @returns
+ */
+declare function mergeDeep(target: GenericObject, source: GenericObject): GenericObject;
+/**
+ * Deeply find a value in an object using a dot-notated path.
+ * Returns undefined if the path does not exist.
+ *
+ * @param obj
+ * @param path
+ * @returns
+ */
+declare function deepFindMessage(obj: GenericObject, path: string): any;
 //#endregion
 //#region src/utilities/object.d.ts
 /**
@@ -1368,21 +1561,6 @@ declare function deepSet(target: any, path: string | string[], value: any): void
  * @returns
  */
 declare function dotify(obj: GenericObject, ignoreRulesArray?: boolean, withBaseObjectType?: boolean): GenericObject;
-/**
- * Check if the value is an object
- *
- * @param value
- * @returns
- */
-declare function isObject(value: any): any;
-/**
- * Deeply merge nested objects
- *
- * @param target
- * @param source
- * @returns
- */
-declare function mergeDeep(target: GenericObject, source: GenericObject): GenericObject;
 /**
  * Check if objects are deep equal
  *
@@ -1442,4 +1620,4 @@ declare class ValidationException extends Error {
   getResponse(): any;
 }
 //#endregion
-export { BaseValidationRuleClass, BaseValidator, CustomAttributes, CustomErrors, CustomMessages, CustomValidationRules, DotPaths, ErrorBag, ErrorMessage, Errors, ExtendedRules, ExtractRules, FieldMessages, GenericCallable, GenericObject, IDatabaseDriver, IMessageBag, IValidationRule, IValidator, ImplicitAttributes, ImplicitRule, InitialRule, InitialRules, Lang, MessageBag, Messages, MessagesForRules, NestedStringMap, ParamableValidationRuleName, Password, PlainRuleName, ReplaceAttributeInterface, Rules, RulesForData, TRule, ValidatedByRules, ValidationCallback, ValidationDataInterface, ValidationDatabaseExistsInput, ValidationException, ValidationMessageProvider, ValidationRule, ValidationRuleCallable, ValidationRuleName, ValidationRuleParserInterface, ValidationRuleSet, ValidationServiceProvider, Validator, addImplicitRule, buildValidationMethodName, compare, convertValuesToBoolean, convertValuesToNull, convertValuesToNumber, deepEqual, deepFind, deepSet, dotify, getFormattedAttribute, getKeyCombinations, getMessage, getNumericRules, getSize, isArrayOfRules, isImplicitRule, isInteger, isNumericRule, isObject, isRule, isSizeRule, make, mergeDeep, notRegex, plural, regex, register, registerImplicit, requiredIf, ruleIn, ruleNotIn, sameType, toDate, toSnakeCase };
+export { BaseValidationRuleClass, BaseValidator, CustomAttributes, CustomErrors, CustomMessages, CustomParamableValidationRuleName, CustomPlainRuleName, CustomValidationRuleNameMap, CustomValidationRules, DotPaths, ErrorBag, ErrorMessage, Errors, ExtendedRules, ExtractRules, FieldMessages, GenericCallable, GenericObject, IDatabaseDriver, IMessageBag, IValidationRule, IValidator, ImplicitAttributes, ImplicitRule, InitialRule, InitialRules, Lang, MessageBag, Messages, MessagesForRules, NestedStringMap, ParamableValidationRuleName, Password, PlainRuleName, ReplaceAttributeInterface, Rules, RulesForData, TRule, ValidatedByRules, ValidationCallback, ValidationDataInterface, ValidationDatabaseExistsInput, ValidationException, ValidationMessageProvider, ValidationRule, ValidationRuleAutocompleteKind, ValidationRuleAutocompleteMap, ValidationRuleCallable, ValidationRuleEntry, ValidationRuleName, ValidationRuleParserInterface, ValidationRuleSet, ValidationServiceProvider, ValidationValueInspector, Validator, ValidatorPlugin, ValidatorPluginApi, addImplicitRule, buildValidationMethodName, compare, convertValuesToBoolean, convertValuesToNull, convertValuesToNumber, deepEqual, deepFind, deepFindMessage, deepSet, definePlugin, dotify, getFormattedAttribute, getKeyCombinations, getMessage, getNumericRules, getSize, getValidationMessageType, getValidationSize, getValidationValueInspector, getValidatorContext, isArrayOfRules, isImplicitRule, isInteger, isNumericRule, isObject, isRule, isSizeRule, make, mergeDeep, notRegex, plural, regex, register, registerImplicit, registerValueInspector, requiredIf, ruleIn, ruleNotIn, runWithValidatorContext, sameType, toDate, toSnakeCase, usePlugin, useValidatorContext };