@regle/rules 1.13.1 → 1.14.0

package/dist/regle-rules.d.ts

@@ -2,132 +2,346 @@ import { CommonAlphaOptions, CommonComparisonOptions, ExtendedRulesDeclarations,
 import { ComputedRef, MaybeRef, MaybeRefOrGetter, Ref } from "vue";
 import { EmptyObject } from "type-fest";
 /**
- * The withMessage wrapper lets you associate an error message with a rule. Pass your rule as the first argument and the error message as the second.
+ * The `withMessage` wrapper lets you associate an error message with a rule.
+ * Pass your rule as the first argument and the error message as the second.
  *
+ * @param rule - The rule to wrap (can be inline function or rule definition)
+ * @param newMessage - The error message (string or function returning a string)
+ *
+ * @example
  * ```ts
+ * import { withMessage } from '@regle/rules';
+ *
  * const { r$ } = useRegle({ name: '' }, {
-    name: {
-      customRule1: withMessage((value) => !!value, "Custom Error"),
-      customRule2: withMessage(customRuleInlineWithMetaData, "Custom Error"),
-      customRule3: withMessage(
-        customRuleInlineWithMetaData,
-        ({ $value, foo }) => `Custom Error: ${$value} ${foo}`
-      ),
-    }
-  })
- * ```
- * Docs: {@link https://reglejs.dev/core-concepts/rules/rule-wrappers#withmessage}
+ *   name: {
+ *     // With a static message
+ *     customRule1: withMessage((value) => !!value, "Custom Error"),
+ *     // With dynamic message using metadata
+ *     customRule2: withMessage(
+ *       customRuleInlineWithMetaData,
+ *       ({ $value, foo }) => `Custom Error: ${$value} ${foo}`
+ *     ),
+ *   }
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/rule-wrappers#withmessage Documentation}
  */
 declare function withMessage<TValue$1 extends any, TParams$1 extends any[], TReturn$1 extends RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>, TMetadata$1 extends RegleRuleMetadataDefinition = (TReturn$1 extends Promise<infer M> ? M : TReturn$1), TAsync$1 extends boolean = (TReturn$1 extends Promise<any> ? true : false)>(rule: RegleRuleWithParamsDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>, newMessage: RegleRuleDefinitionWithMetadataProcessor<TValue$1, RegleRuleMetadataConsumer<TValue$1, TParams$1, TMetadata$1>, string | string[]>): RegleRuleWithParamsDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>;
 declare function withMessage<TValue$1 extends any, TParams$1 extends unknown[], TReturn$1 extends RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>, TMetadata$1 extends RegleRuleMetadataDefinition = (TReturn$1 extends Promise<infer M> ? M : TReturn$1), TAsync$1 extends boolean = (TReturn$1 extends Promise<any> ? true : false)>(rule: RegleRuleDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>, newMessage: RegleRuleDefinitionWithMetadataProcessor<TValue$1, RegleRuleMetadataConsumer<TValue$1, TParams$1, TMetadata$1>, string | string[]>): RegleRuleDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>;
 declare function withMessage<TValue$1 extends any, TParams$1 extends any[], TReturn$1 extends RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>, TAsync$1 extends boolean = (TReturn$1 extends Promise<any> ? true : false)>(rule: InlineRuleDeclaration<TValue$1, TParams$1, TReturn$1>, newMessage: RegleRuleDefinitionWithMetadataProcessor<TValue$1, RegleRuleMetadataConsumer<TValue$1, TParams$1, TReturn$1 extends Promise<infer M> ? M : TReturn$1>, string | string[]>): RegleRuleDefinition<TValue$1, TParams$1, TAsync$1, TReturn$1 extends Promise<infer M> ? M : TReturn$1>;
 declare function withMessage<TValue$1 extends any, TParams$1 extends any[], TReturn$1 extends RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>, TMetadata$1 extends RegleRuleMetadataDefinition = (TReturn$1 extends Promise<infer M> ? M : TReturn$1), TAsync$1 extends boolean = (TReturn$1 extends Promise<any> ? true : false)>(rule: (...args: any[]) => RegleRuleDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>, newMessage: RegleRuleDefinitionWithMetadataProcessor<TValue$1, RegleRuleMetadataConsumer<TValue$1, TParams$1, TMetadata$1>, string | string[]>): RegleRuleWithParamsDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>;
 /**
- * The withTooltip wrapper allows you to display additional messages for your field that aren’t necessarily errors. Tooltips are aggregated and accessible via $fields.xxx.$tooltips .
+ * The `withTooltip` wrapper allows you to display additional messages for your field that aren't necessarily errors.
+ * Tooltips are aggregated and accessible via `$tooltips` property.
+ *
+ * @param rule - The rule to wrap (can be inline function or rule definition)
+ * @param newTooltip - The tooltip message (string or function returning a string)
+ *
+ * @example
+ * ```ts
+ * import { withTooltip, minLength } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ password: '' }, {
+ *   password: {
+ *     minLength: withTooltip(
+ *       minLength(8),
+ *       'Password should be at least 8 characters for better security'
+ *     ),
+ *   }
+ * })
+ *
+ * // Access tooltips via:
+ * // r$.password.$tooltips
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/rule-wrappers#withtooltip Documentation}
  */
 declare function withTooltip<TValue$1 extends any, TParams$1 extends any[], TReturn$1 extends RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>, TMetadata$1 extends RegleRuleMetadataDefinition = (TReturn$1 extends Promise<infer M> ? M : TReturn$1), TAsync$1 extends boolean = (TReturn$1 extends Promise<any> ? true : false)>(rule: RegleRuleWithParamsDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>, newTooltip: RegleRuleDefinitionWithMetadataProcessor<TValue$1, RegleRuleMetadataConsumer<TValue$1, TParams$1, TMetadata$1>, string | string[]>): RegleRuleWithParamsDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>;
 declare function withTooltip<TValue$1 extends any, TParams$1 extends any[], TReturn$1 extends RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>, TMetadata$1 extends RegleRuleMetadataDefinition = (TReturn$1 extends Promise<infer M> ? M : TReturn$1), TAsync$1 extends boolean = (TReturn$1 extends Promise<any> ? true : false)>(rule: RegleRuleDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>, newTooltip: RegleRuleDefinitionWithMetadataProcessor<TValue$1, RegleRuleMetadataConsumer<TValue$1, TParams$1, TMetadata$1>, string | string[]>): RegleRuleDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>;
 declare function withTooltip<TValue$1 extends any, TParams$1 extends any[], TReturn$1 extends RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>, TAsync$1 extends boolean = (TReturn$1 extends Promise<any> ? true : false)>(rule: InlineRuleDeclaration<TValue$1, TParams$1, TReturn$1>, newTooltip: RegleRuleDefinitionWithMetadataProcessor<TValue$1, RegleRuleMetadataConsumer<TValue$1, TParams$1, TReturn$1 extends Promise<infer M> ? M : TReturn$1>, string | string[]>): RegleRuleDefinition<TValue$1, TParams$1, TAsync$1, TReturn$1 extends Promise<infer M> ? M : TReturn$1>;
 /**
- * withAsync works like withParams, but is specifically designed for async rules that depend on external values.
+ * `withAsync` works like `withParams`, but is specifically designed for async rules that depend on external values.
+ *
+ * @param rule - The async rule function
+ * @param depsArray - Array of reactive dependencies (refs or getters)
  *
+ * @example
  * ```ts
- *import { withAsync } from '@regle/rules';
-
-  const base = ref('foo');
-
-  const { r$ } = useRegle({ name: '' }, {
-    name: {
-      customRule: withAsync(async (value, param) => {
-        await someAsyncCall(param)
-      }, [base])
-    }
-  })
+ * import { withAsync } from '@regle/rules';
+ *
+ * const base = ref('foo');
+ *
+ * const { r$ } = useRegle({ name: '' }, {
+ *   name: {
+ *     customRule: withAsync(async (value, param) => {
+ *       await someAsyncCall(param)
+ *     }, [base])
+ *   }
+ * })
  * ```
- * Docs: {@link https://reglejs.dev/core-concepts/rules/rule-wrappers#withasync}
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/rule-wrappers#withasync Documentation}
  */
 declare function withAsync<TValue$1, TParams$1 extends (Ref<unknown> | (() => unknown))[] = [], TReturn$1 extends Promise<RegleRuleMetadataDefinition> = Promise<RegleRuleMetadataDefinition>, TMetadata$1 extends RegleRuleMetadataDefinition = (TReturn$1 extends Promise<infer M> ? M : TReturn$1)>(rule: InlineRuleDeclaration<TValue$1, TParams$1, TReturn$1>, depsArray?: [...TParams$1]): RegleRuleDefinition<TValue$1, UnwrapRegleUniversalParams<TParams$1>, true, TMetadata$1>;
 declare function withAsync<TValue$1 extends any, TParams$1 extends any[], TMetadata$1 extends RegleRuleMetadataDefinition>(rule: RegleRuleWithParamsDefinition<TValue$1, TParams$1, true, TMetadata$1>, depsArray?: [...TParams$1]): RegleRuleWithParamsDefinition<TValue$1, TParams$1, true, TMetadata$1>;
 /**
- * The withParams wrapper allows your rule to depend on external parameters, such as a reactive property in your component or store.
+ * The `withParams` wrapper allows your rule to depend on external parameters,
+ * such as a reactive property in your component or store.
  *
- * By default, useRegle observes changes automatically when rules are defined using getter functions or computed properties.
+ * By default, `useRegle` observes changes automatically when rules are defined using getter functions or computed properties.
+ * However, sometimes dependencies cannot be tracked automatically; use `withParams` to manually define them.
  *
+ * @param rule - The rule function or definition
+ * @param depsArray - Array of reactive dependencies (refs or getters)
+ *
+ * @example
  * ```ts
  * import { withParams } from '@regle/rules';
-
-    const base = ref('foo');
-
-    const { r$ } = useRegle({ name: '' }, {
-      name: {
-        customRule: withParams((value, param) => value === param, [base]),
-        // or
-        customRule: withParams((value, param) => value === param, [() => base.value]),
-      }
-    })
- * ```
- * Docs: {@link https://reglejs.dev/core-concepts/rules/rule-wrappers#withparams}
+ *
+ * const base = ref('foo');
+ *
+ * const { r$ } = useRegle({ name: '' }, {
+ *   name: {
+ *     customRule: withParams((value, param) => value === param, [base]),
+ *     // or with getter
+ *     customRule: withParams((value, param) => value === param, [() => base.value]),
+ *   }
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/rule-wrappers#withparams Documentation}
  */
 declare function withParams<TValue$1, TParams$1 extends (Ref<unknown> | (() => unknown))[] = [], TReturn$1 extends RegleRuleMetadataDefinition = RegleRuleMetadataDefinition, TMetadata$1 extends RegleRuleMetadataDefinition = (TReturn$1 extends Promise<infer M> ? M : TReturn$1), TAsync$1 extends boolean = (TReturn$1 extends Promise<any> ? true : false)>(rule: InlineRuleDeclaration<TValue$1, TParams$1, TReturn$1> | RegleRuleDefinition<TValue$1, any[], TAsync$1, TMetadata$1>, depsArray: [...TParams$1]): RegleRuleDefinition<TValue$1, UnwrapRegleUniversalParams<TParams$1>, TAsync$1, TMetadata$1>;
 declare function withParams<TValue$1 extends any, TParams$1 extends any[], TReturn$1 extends RegleRuleMetadataDefinition = RegleRuleMetadataDefinition, TMetadata$1 extends RegleRuleMetadataDefinition = (TReturn$1 extends Promise<infer M> ? M : TReturn$1), TAsync$1 extends boolean = (TReturn$1 extends Promise<any> ? true : false)>(rule: RegleRuleWithParamsDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>, depsArray: [...TParams$1]): RegleRuleWithParamsDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>;
 /**
- * The applyIf operator is similar to requiredIf, but it can be used with any rule.
+ * The `applyIf` operator is similar to `requiredIf`, but it can be used with **any rule**.
  * It simplifies conditional rule declarations.
  *
+ * @param _condition - The condition to check (ref, getter, or value)
+ * @param rule - The rule to apply conditionally
+ * @returns A rule that only applies when the condition is truthy
+ *
  * @example
  * ```ts
+ * import { minLength, applyIf } from '@regle/rules';
+ *
  * const condition = ref(false);
- * const { r$ } = useRegle({name: ''}, {
+ *
+ * const { r$ } = useRegle({ name: '' }, {
  *   name: {
  *     minLength: applyIf(condition, minLength(6))
  *   },
  * });
- *
  * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/rules-operators#applyif Documentation}
  */
 declare function applyIf<TRule extends FormRuleDeclaration<any>>(_condition: MaybeRefOrGetter<Maybe<boolean>>, rule: TRule): TRule extends InlineRuleDeclaration<infer TValue, infer TParams, infer TReturn> ? RegleRuleDefinition<TValue, [...TParams, condition: boolean], TReturn extends Promise<any> ? true : false, TReturn extends Promise<infer M> ? M : TReturn> : TRule extends FormRuleDeclaration<infer TValue, infer TParams, any, infer TMetadata, infer TAsync> ? RegleRuleDefinition<TValue, [...TParams, condition: boolean], TAsync, TMetadata> : TRule;
 /**
- * This is almost a must have for optional fields. It checks if any value you provided is defined (including arrays and objects). You can base your validator result on this.
+ * Checks if any value you provide is defined (including arrays and objects).
+ * This is almost a must-have for optional fields when writing custom rules.
+ *
+ * `isFilled` also acts as a type guard.
+ *
+ * By default, it considers an empty array as `false`. You can override this behavior with `considerEmptyArrayInvalid`.
+ *
+ * @param value - The target value to check
+ * @param considerEmptyArrayInvalid - When `false`, empty arrays are considered filled (default: `true`)
+ * @returns `true` if the value is filled, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * import { createRule } from '@regle/core';
+ * import { isFilled } from '@regle/rules';
  *
- * isFilled also acts as a type guard.
+ * const rule = createRule({
+ *   validator(value: unknown) {
+ *     if (isFilled(value)) {
+ *       return check(value);
+ *     }
+ *     return true;
+ *   },
+ *   message: 'Error'
+ * })
+ * ```
  *
- * @param value - the target value
- * @param [considerEmptyArrayInvalid=true] - will return true if set to `false`. (default: `true`)
+ * @see {@link https://reglejs.dev/core-concepts/rules/validations-helpers#isfilled Documentation}
  */
 declare function isFilled<T extends unknown>(value: T, considerEmptyArrayInvalid?: boolean): value is NonNullable<T>;
 /**
- * This is a type guard that will check if the passed value is a real Number. This also returns false for NaN, so this is better than typeof value === "number".
+ * Type guard that checks if the passed value is a real `Number`.
+ * Returns `false` for `NaN`, making it safer than `typeof value === "number"`.
+ *
+ * @param value - The value to check
+ * @returns `true` if value is a valid number (not `NaN`), `false` otherwise
+ *
+ * @example
+ * ```ts
+ * import { createRule, type Maybe } from '@regle/core';
+ * import { isFilled, isNumber } from '@regle/rules';
+ *
+ * const rule = createRule({
+ *   validator(value: Maybe<number | string>) {
+ *     if (isFilled(value) && isNumber(value)) {
+ *       return checkNumber(value);
+ *     }
+ *     return true;
+ *   },
+ *   message: 'Error'
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/validations-helpers#isnumber Documentation}
  */
 declare function isNumber(value: unknown): value is number;
 /**
- * This utility can take multiple regular expressions as arguments. It checks the input's validity and tests it against the provided regex patterns.
+ * Tests a value against one or more regular expressions.
+ * Returns `true` if the value is empty or matches **all** provided patterns.
+ *
+ * @param _value - The value to test
+ * @param expr - One or more RegExp patterns to match against
+ * @returns `true` if empty or all patterns match, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * import { createRule, type Maybe } from '@regle/core';
+ * import { isFilled, matchRegex } from '@regle/rules';
+ *
+ * const regex = createRule({
+ *   validator(value: Maybe<string>, regexps: RegExp[]) {
+ *     if (isFilled(value)) {
+ *       return matchRegex(value, ...regexps);
+ *     }
+ *     return true;
+ *   },
+ *   message: 'Error'
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/validations-helpers#matchregex Documentation}
  */
 declare function matchRegex(_value: string | number | null | undefined, ...expr: RegExp[]): boolean;
 /**
- * This helper will return the length of any data type you pass. It works with strings, arrays, objects and numbers.
+ * Returns the length/size of any data type. Works with strings, arrays, objects and numbers.
+ *
+ * @param value - The value to get the size of
+ * @returns The length of strings/arrays, number of keys for objects, or the number itself
+ *
+ * @example
+ * ```ts
+ * import { createRule, type Maybe } from '@regle/core';
+ * import { isFilled, getSize } from '@regle/rules';
+ *
+ * const rule = createRule({
+ *   validator(value: Maybe<string | Array<number>>) {
+ *     if (isFilled(value)) {
+ *       return getSize(value) > 6;
+ *     }
+ *     return true;
+ *   },
+ *   message: 'Error'
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/validations-helpers#getsize Documentation}
  */
 declare function getSize(value: MaybeRef<string | any[] | Record<string, any> | number>): number;
 /**
- * This utility converts any string (or number) into a number using the Number constructor.
+ * Converts any string (or number) into a number using the `Number` constructor.
+ *
+ * @param argument - The value to convert
+ * @returns The converted number (⚠️ Warning: returned value can be `NaN`)
+ *
+ * @example
+ * ```ts
+ * import { toNumber, isNumber } from '@regle/rules';
+ *
+ * const num = toNumber('42'); // 42
+ * const invalid = toNumber('abc'); // NaN
+ *
+ * // Always check for NaN when using toNumber
+ * if (!isNaN(toNumber(value))) {
+ *   // Safe to use as number
+ * }
+ * ```
  *
- * @returns ⚠️ Warning, returned value can be NaN
+ * @see {@link https://reglejs.dev/core-concepts/rules/validations-helpers#tonumber Documentation}
  */
 declare function toNumber<T extends number | string | undefined>(argument: T): number;
 /**
- * This is the inverse of isFilled. It will check if the value is in any way empty (including arrays and objects)
+ * Checks if a value is empty in any way (including arrays and objects).
+ * This is the inverse of `isFilled`.
+ *
+ * `isEmpty` also acts as a type guard.
+ *
+ * By default, it considers an empty array as `true`. You can override this behavior with `considerEmptyArrayInvalid`.
+ *
+ * @param value - The target value to check
+ * @param considerEmptyArrayInvalid - When `false`, empty arrays are not considered empty (default: `true`)
+ * @returns `true` if the value is empty, `false` otherwise
  *
- * isEmpty also acts as a type guard.
+ * @example
+ * ```ts
+ * import { createRule, type Maybe } from '@regle/core';
+ * import { isEmpty } from '@regle/rules';
  *
- * @param value - the target value
- * @param [considerEmptyArrayInvalid=true] - will return false if set to `false`. (default: `true`)
+ * const rule = createRule({
+ *   validator(value: Maybe<string>) {
+ *     if (isEmpty(value)) {
+ *       return true;
+ *     }
+ *     return check(value);
+ *   },
+ *   message: 'Error'
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/validations-helpers#isempty Documentation}
  */
 declare function isEmpty(value: unknown, considerEmptyArrayInvalid?: boolean): value is null | undefined | [] | EmptyObject;
 /**
- * This is a useful helper that can check if the provided value is a Date, it is used internally for date rules. This can also check strings.
+ * Checks if the provided value is a valid Date. Used internally for date rules.
+ * Can also validate date strings.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid Date or date string, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * import { createRule, type Maybe } from '@regle/core';
+ * import { isFilled, isDate } from '@regle/rules';
+ *
+ * const rule = createRule({
+ *   validator(value: Maybe<string | Date>) {
+ *     if (isFilled(value) && isDate(value)) {
+ *       return checkDate(value);
+ *     }
+ *     return true;
+ *   },
+ *   message: 'Error'
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/validations-helpers#isdate Documentation}
  */
 declare function isDate(value: unknown): value is Date | string;
 /**
- * This utility will coerce any string, number or Date value into a Date using the Date constructor.
+ * Coerces any string, number, or Date value into a `Date` using the `Date` constructor.
+ *
+ * @param argument - The value to convert to a Date
+ * @returns A new Date object (may be invalid if input cannot be parsed)
+ *
+ * @example
+ * ```ts
+ * import { toDate } from '@regle/rules';
+ *
+ * const date1 = toDate('2024-01-15'); // Date object
+ * const date2 = toDate(1705276800000); // Date from timestamp
+ * const date3 = toDate(new Date()); // Clone of Date
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/validations-helpers#todate Documentation}
  */
 declare function toDate(argument: Maybe<Date | number | string>): Date;
 type ExtractValueFromRules<T extends any[]> = T extends [infer F, ...infer R] ? F extends RegleRuleDefinition<infer V, any, any, any> ? [V, ...ExtractValueFromRules<R>] : F extends InlineRuleDeclaration<infer V, any> ? [V, ...ExtractValueFromRules<R>] : [F, ...ExtractValueFromRules<R>] : [];
@@ -145,78 +359,277 @@ type GuessMetadataFromRules<T extends any[], TMeta = ExtractMetadata<ExtractMeta
 type FilterTuple<T extends any[]> = T extends [infer F, ...infer R] ? [F] extends [[]] ? [...FilterTuple<R>] : [F, ...FilterTuple<R>] : [];
 type UnwrapTuples<T extends any[]> = FilterTuple<T> extends [infer U extends any[]] ? U : FilterTuple<T>;
 /**
- * The and operator combines multiple rules and validates successfully only if all provided rules are valid.
+ * The `and` operator combines multiple rules and validates successfully only if **all** provided rules are valid.
+ *
+ * @param rules - Two or more rules to combine
+ * @returns A combined rule that passes when all provided rules pass
+ *
+ * @example
+ * ```ts
+ * import { useRegle } from '@regle/core';
+ * import { and, startsWith, endsWith, withMessage } from '@regle/rules';
+ *
+ * const { r$ } = useRegle(
+ *   { regex: '' },
+ *   {
+ *     regex: {
+ *       myError: withMessage(
+ *         and(startsWith('^'), endsWith('$')),
+ *         ({ $params: [start, end] }) =>
+ *           `Regex should start with "${start}" and end with "${end}"`
+ *       ),
+ *     },
+ *   }
+ * );
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/rules-operators#and Documentation}
  */
 declare function and<const TRules extends [FormRuleDeclaration<any, any>, ...FormRuleDeclaration<any, any>[]]>(...rules: [...TRules]): RegleRuleDefinition<ExtractValueFromRules<TRules>[number], UnwrapTuples<ExtractParamsFromRules<TRules>>, GuessAsyncFromRules<TRules>, GuessMetadataFromRules<TRules>>;
 /**
- * The or operator validates successfully if at least one of the provided rules is valid.
+ * The `or` operator validates successfully if **at least one** of the provided rules is valid.
+ *
+ * @param rules - Two or more rules to combine
+ * @returns A combined rule that passes when any of the provided rules pass
+ *
+ * @example
+ * ```ts
+ * import { useRegle } from '@regle/core';
+ * import { or, startsWith, endsWith, withMessage } from '@regle/rules';
+ *
+ * const { r$ } = useRegle(
+ *   { regex: '' },
+ *   {
+ *     regex: {
+ *       myError: withMessage(
+ *         or(startsWith('^'), endsWith('$')),
+ *         ({ $params: [start, end] }) =>
+ *           `Field should start with "${start}" or end with "${end}"`
+ *       ),
+ *     },
+ *   }
+ * );
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/rules-operators#or Documentation}
  */
 declare function or<TRules extends [FormRuleDeclaration<any, any>, ...FormRuleDeclaration<any, any>[]]>(...rules: [...TRules]): RegleRuleDefinition<ExtractValueFromRules<TRules>[number], UnwrapTuples<ExtractParamsFromRules<TRules>>, GuessAsyncFromRules<TRules>, GuessMetadataFromRules<TRules>>;
 /**
- * The not operator passes when the provided rule fails and fails when the rule passes. It can be combined with other rules.
+ * The `not` operator passes when the provided rule **fails** and fails when the rule **passes**.
+ * It can be combined with other rules.
+ *
+ * @param rule - The rule to negate
+ * @param message - Optional custom error message
+ * @returns A negated rule
+ *
+ * @example
+ * ```ts
+ * import { useRegle } from '@regle/core';
+ * import { not, required, sameAs, withMessage } from '@regle/rules';
+ * import { ref } from 'vue';
+ *
+ * const form = ref({ oldPassword: '', newPassword: '' });
+ *
+ * const { r$ } = useRegle(form, {
+ *   oldPassword: { required },
+ *   newPassword: {
+ *     notEqual: withMessage(
+ *       not(sameAs(() => form.value.oldPassword)),
+ *       'Your new password must not be the same as your old password'
+ *     ),
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/rules-operators#not Documentation}
  */
 declare function not<TValue$1, TParams$1 extends any[] = [], TReturn$1 extends RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition> = RegleRuleMetadataDefinition, TMetadata$1 extends RegleRuleMetadataDefinition = (TReturn$1 extends Promise<infer M> ? M : TReturn$1), TAsync$1 extends boolean = (TReturn$1 extends Promise<any> ? true : false)>(rule: RegleRuleDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1> | InlineRuleDeclaration<TValue$1, TParams$1, TReturn$1>, message?: RegleRuleDefinitionWithMetadataProcessor<TValue$1, RegleRuleMetadataConsumer<TValue$1, TParams$1, TMetadata$1>, string | string[]>): RegleRuleDefinition<TValue$1, TParams$1, TAsync$1, TMetadata$1>;
 /**
- * The assignIf is a shorthand for conditional destructuring assignment.
- * It allows to apply multiple rules to a field conditionally.
+ * The `assignIf` is a shorthand for conditional destructuring assignment.
+ * It allows applying **multiple rules** to a field conditionally.
+ *
+ * @param _condition - The condition to check (ref, getter, or value)
+ * @param rules - An object of rules to apply conditionally
+ * @returns A computed ref containing the rules that only apply when the condition is truthy
  *
  * @example
  * ```ts
+ * import { required, email, minLength, assignIf } from '@regle/rules';
+ *
  * const condition = ref(false);
  *
  * const { r$ } = useRegle(ref({ name: '', email: '' }), {
  *   name: assignIf(condition, { required, minLength: minLength(4) }),
  *   email: { email },
- * })
+ * });
  * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/rules-operators#assignif Documentation}
  */
 declare function assignIf<TValue$1 extends unknown = any, TCustomRules extends Partial<ExtendedRulesDeclarations> = Partial<ExtendedRulesDeclarations>, TRulesDelc extends RegleRuleDecl<TValue$1, TCustomRules> = RegleRuleDecl<TValue$1, TCustomRules>>(_condition: MaybeRefOrGetter<Maybe<boolean>>, rules: MaybeRefOrGetter<TRulesDelc>, otherwiseRules?: MaybeRefOrGetter<TRulesDelc>): ComputedRef<TRulesDelc>;
 /**
  * Allows only alphabetic characters.
  *
- * @param [options] - Alpha rules options
- * */
+ * @param options - Optional configuration for alpha validation
+ *
+ * @example
+ * ```ts
+ * import { alpha } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ name: '' }, {
+ *   name: {
+ *     alpha,
+ *     // or with symbols allowed
+ *     alpha: alpha({ allowSymbols: true }),
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#alpha Documentation}
+ */
 declare const alpha: RegleRuleWithParamsDefinition<string, [options?: CommonAlphaOptions | undefined], false, boolean, MaybeInput<string>, string>;
 /**
  * Allows only alphanumeric characters.
  *
- * @param [options] - Alpha rules options
+ * @param options - Optional configuration for alphanumeric validation
+ *
+ * @example
+ * ```ts
+ * import { alphaNum } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ name: '' }, {
+ *   name: {
+ *     alphaNum,
+ *     // or with symbols allowed
+ *     alphaNum: alphaNum({ allowSymbols: true }),
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#alphanum Documentation}
  */
 declare const alphaNum: RegleRuleWithParamsDefinition<string | number, [options?: CommonAlphaOptions | undefined], false, boolean, MaybeInput<string>>;
 /**
- * Checks if a number is in specified bounds. min and max are both inclusive.
+ * Checks if a number is in specified bounds. `min` and `max` are both inclusive by default.
+ *
+ * @param min - The minimum limit
+ * @param max - The maximum limit
+ * @param options - Optional configuration (e.g., `{ allowEqual: false }` for exclusive bounds)
+ *
+ * @example
+ * ```ts
+ * import { between } from '@regle/rules';
+ *
+ * const maxCount = ref(6);
  *
- * @param min - the minimum limit
- * @param max - the maximum limit
+ * const { r$ } = useRegle({ count: 0 }, {
+ *   count: {
+ *     between: between(1, 6),
+ *     // or with reactive max
+ *     between: between(1, maxCount, { allowEqual: false }),
+ *     // or with getter
+ *     between: between(() => maxCount.value, 10)
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#between Documentation}
  */
 declare const between: RegleRuleWithParamsDefinition<number, [min: number, max: number, options?: CommonComparisonOptions], false, boolean, MaybeInput<number>>;
 /**
- * Requires a value to be a native boolean type
+ * Requires a value to be a native boolean type.
+ *
+ * Mainly used for typing with `InferInput`.
+ *
+ * @example
+ * ```ts
+ * import { type InferInput } from '@regle/core';
+ * import { boolean } from '@regle/rules';
+ *
+ * const rules = {
+ *   checkbox: { boolean },
+ * }
+ *
+ * const state = ref<InferInput<typeof rules>>({});
+ * ```
  *
- * Mainly used for typing
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#boolean Documentation}
  */
 declare const boolean: RegleRuleDefinition<unknown, [], false, boolean, MaybeInput<boolean>, unknown>;
 /**
- * Requires a boolean value to be true. This is useful for checkbox inputs.
+ * Requires a boolean value to be `true`. This is useful for checkbox inputs like "accept terms".
+ *
+ * @example
+ * ```ts
+ * import { checked } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ confirm: false }, {
+ *   confirm: { checked },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#checked Documentation}
  */
 declare const checked: RegleRuleDefinition<boolean, [], false, boolean, MaybeInput<boolean>>;
 /**
  * Checks if the string contains the specified substring.
  *
- * @param part - the part the value needs to contain
+ * @param part - The substring the value must contain
+ *
+ * @example
+ * ```ts
+ * import { contains } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ bestLib: '' }, {
+ *   bestLib: {
+ *     contains: contains('regle')
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#contains Documentation}
  */
 declare const contains: RegleRuleWithParamsDefinition<string, [part: MaybeInput<string>], false, boolean, MaybeInput<string>>;
 /**
- * Requires a value to be a native Date constructor
+ * Requires a value to be a native `Date` constructor.
+ *
+ * Mainly used for typing with `InferInput`.
+ *
+ * @example
+ * ```ts
+ * import { type InferInput } from '@regle/core';
+ * import { date } from '@regle/rules';
  *
- * Mainly used for typing
+ * const rules = {
+ *   birthday: { date },
+ * }
+ *
+ * const state = ref<InferInput<typeof rules>>({});
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#date Documentation}
  */
 declare const date: RegleRuleDefinition<unknown, [], false, boolean, MaybeInput<Date>, unknown>;
 /**
  * Checks if the date is after the given parameter.
  *
- * @param after - the date to compare to
- * @param options - comparison options
+ * @param after - The date to compare to (can be a `Date`, string, ref, or getter)
+ * @param options - Optional configuration (e.g., `{ allowEqual: false }`)
+ *
+ * @example
+ * ```ts
+ * import { dateAfter } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ birthday: null as Date | null }, {
+ *   birthday: {
+ *     dateAfter: dateAfter(new Date()),
+ *     // or with options
+ *     dateAfter: dateAfter(new Date(), { allowEqual: false }),
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#dateafter Documentation}
  */
 declare const dateAfter: RegleRuleWithParamsDefinition<string | Date, [after: MaybeInput<string | Date>, options?: CommonComparisonOptions], false, true | {
   $valid: false;
@@ -228,8 +641,23 @@ declare const dateAfter: RegleRuleWithParamsDefinition<string | Date, [after: Ma
 /**
  * Checks if the date is before the given parameter.
  *
- * @param before - the date to compare to
- * @param options - comparison options
+ * @param before - The date to compare to (can be a `Date`, string, ref, or getter)
+ * @param options - Optional configuration (e.g., `{ allowEqual: false }`)
+ *
+ * @example
+ * ```ts
+ * import { dateBefore } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ birthday: null as Date | null }, {
+ *   birthday: {
+ *     dateBefore: dateBefore(new Date()),
+ *     // or with options
+ *     dateBefore: dateBefore(new Date(), { allowEqual: false }),
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#datebefore Documentation}
  */
 declare const dateBefore: RegleRuleWithParamsDefinition<string | Date, [before: MaybeInput<string | Date>, options?: CommonComparisonOptions], false, true | {
   $valid: false;
@@ -241,101 +669,368 @@ declare const dateBefore: RegleRuleWithParamsDefinition<string | Date, [before:
 /**
  * Checks if the date falls between the specified bounds.
  *
- * @param before - the minimum limit
- * @param after - the maximum limit
- * @param options - comparison options
+ * @param before - The minimum date limit
+ * @param after - The maximum date limit
+ * @param options - Optional configuration (e.g., `{ allowEqual: false }`)
+ *
+ * @example
+ * ```ts
+ * import { dateBetween } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ birthday: null as Date | null }, {
+ *   birthday: {
+ *     dateBetween: dateBetween(new Date(), new Date(2030, 3, 1)),
+ *     // or with options
+ *     dateBetween: dateBetween(new Date(), new Date(2030, 3, 1), { allowEqual: false }),
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#datebetweeen Documentation}
  */
 declare const dateBetween: RegleRuleWithParamsDefinition<string | Date, [before: MaybeInput<string | Date>, after: MaybeInput<string | Date>, options?: CommonComparisonOptions], false, boolean, MaybeInput<string | Date>>;
 /**
  * Allows positive and negative decimal numbers.
+ *
+ * @example
+ * ```ts
+ * import { decimal } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ price: 0 }, {
+ *   price: { decimal },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#decimal Documentation}
  */
 declare const decimal: RegleRuleDefinition<string | number, [], false, boolean, MaybeInput<number | undefined>>;
 /**
  * Validates email addresses. Always verify on the server to ensure the address is real and not already in use.
+ *
+ * @example
+ * ```ts
+ * import { email } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ email: '' }, {
+ *   email: { email },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#email Documentation}
  */
 declare const email: RegleRuleDefinition<string, [], false, boolean, MaybeInput<string>>;
 /**
  * Checks if the string ends with the specified substring.
  *
- * @param part - the value the field must end with
+ * @param part - The substring the value must end with
+ *
+ * @example
+ * ```ts
+ * import { endsWith } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ firstName: '' }, {
+ *   firstName: { endsWith: endsWith('foo') },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#endswith Documentation}
  */
 declare const endsWith: RegleRuleWithParamsDefinition<string, [part: MaybeInput<string>], false, boolean, MaybeInput<string>>;
 /**
- * Requires the input value to have a strict specified length, inclusive. Works with arrays, objects and strings.
+ * Requires the input value to have a strict specified length. Works with arrays, objects and strings.
+ *
+ * @param count - The exact required length
+ *
+ * @example
+ * ```ts
+ * import { exactLength } from '@regle/rules';
+ *
+ * const exactValue = ref(6);
  *
- * @param count - the required length
+ * const { r$ } = useRegle({ name: '' }, {
+ *   name: {
+ *     exactLength: exactLength(6),
+ *     // or with reactive value
+ *     exactLength: exactLength(exactValue),
+ *     // or with getter
+ *     exactLength: exactLength(() => exactValue.value)
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#exactlength Documentation}
  */
 declare const exactLength: RegleRuleWithParamsDefinition<string | any[] | Record<PropertyKey, any>, [count: number], false, boolean>;
 /**
  * Requires a field to have a strict numeric value.
+ *
+ * @param count - The exact required numeric value
+ *
+ * @example
+ * ```ts
+ * import { exactValue } from '@regle/rules';
+ *
+ * const exactCount = ref(6);
+ *
+ * const { r$ } = useRegle({ count: 0 }, {
+ *   count: {
+ *     exactValue: exactValue(6),
+ *     // or with reactive value
+ *     exactValue: exactValue(exactCount),
+ *     // or with getter
+ *     exactValue: exactValue(() => exactCount.value)
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#exactvalue Documentation}
  */
 declare const exactValue: RegleRuleWithParamsDefinition<number, [count: number], false, boolean, MaybeInput<number>>;
 /**
- * Allows only hexadecimal values.
+ * Validates hexadecimal values.
+ *
+ * @example
+ * ```ts
+ * import { hexadecimal } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ hexadecimal: '' }, {
+ *   hexadecimal: { hexadecimal },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#hexadecimal Documentation}
  */
 declare const hexadecimal: RegleRuleDefinition<string, [], false, boolean, MaybeInput<string>>;
 /**
  * Allows only integers (positive and negative).
+ *
+ * @example
+ * ```ts
+ * import { integer } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ count: 0 }, {
+ *   count: { integer },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#integer Documentation}
  */
 declare const integer: RegleRuleDefinition<string | number, [], false, boolean, MaybeInput<number>>;
 /**
- * Validates IPv4 addresses in dotted decimal notation 127.0.0.1.
+ * Validates IPv4 addresses in dotted decimal notation (e.g., `127.0.0.1`).
+ *
+ * @example
+ * ```ts
+ * import { ipv4Address } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ address: '' }, {
+ *   address: { ipv4Address },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#ipv4address Documentation}
  */
 declare const ipv4Address: RegleRuleDefinition<string, [], false, boolean, MaybeInput<string>>;
 /**
- * Allow only one possible literal value
+ * Allow only one possible literal value.
+ *
+ * @param literal - The literal value to match
+ *
+ * @example
+ * ```ts
+ * import { literal } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ status: '' }, {
+ *   status: { literal: literal('active') },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#literal Documentation}
  */
 declare function literal<const TValue$1 extends string | number>(literal: MaybeRefOrGetter<TValue$1>): RegleRuleDefinition<TValue$1, [literal: TValue$1], false, boolean, MaybeInput<TValue$1>, string | number>;
 /**
- * Validates MAC addresses. Call as a function to specify a custom separator (e.g., ':' or an empty string for 00ff1122334455).
+ * Validates MAC addresses. Call as a function to specify a custom separator (e.g., `':'` or an empty string for `00ff1122334455`).
+ *
+ * @param separator - The custom separator (default: `':'`)
+ *
+ * @example
+ * ```ts
+ * import { macAddress } from '@regle/rules';
  *
- * @param separator - the custom separator
+ * const { r$ } = useRegle({ address: '' }, {
+ *   address: {
+ *     macAddress,
+ *     // or with custom separator
+ *     macAddress: macAddress('-')
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#macaddress Documentation}
  */
 declare const macAddress: RegleRuleWithParamsDefinition<string, [separator?: string | undefined], false, boolean, MaybeInput<string>>;
 /**
  * Requires the input value to have a maximum specified length, inclusive. Works with arrays, objects and strings.
  *
- * @param max - the maximum length
- * @param options - comparison options
+ * @param max - The maximum length
+ * @param options - Optional configuration (e.g., `{ allowEqual: false }`)
+ *
+ * @example
+ * ```ts
+ * import { maxLength } from '@regle/rules';
+ *
+ * const maxValue = ref(6);
+ *
+ * const { r$ } = useRegle({ name: '' }, {
+ *   name: {
+ *     maxLength: maxLength(6),
+ *     // or with reactive value
+ *     maxLength: maxLength(maxValue),
+ *     // or with getter
+ *     maxLength: maxLength(() => maxValue.value)
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#maxlength Documentation}
  */
-declare const maxLength: RegleRuleWithParamsDefinition<string | any[] | Record<PropertyKey, any>, [count: number, options?: CommonComparisonOptions], false, boolean>;
+declare const maxLength: RegleRuleWithParamsDefinition<string | any[] | Record<PropertyKey, any>, [max: number, options?: CommonComparisonOptions], false, boolean>;
 /**
  * Requires a field to have a specified maximum numeric value.
  *
- * @param max - the maximum value
- * @param options - comparison options
+ * @param max - The maximum value
+ * @param options - Optional configuration (e.g., `{ allowEqual: false }`)
+ *
+ * @example
+ * ```ts
+ * import { maxValue } from '@regle/rules';
+ *
+ * const maxCount = ref(6);
+ *
+ * const { r$ } = useRegle({ count: 0 }, {
+ *   count: {
+ *     maxValue: maxValue(6),
+ *     // or with options
+ *     maxValue: maxValue(maxCount, { allowEqual: false }),
+ *     // or with getter
+ *     maxValue: maxValue(() => maxCount.value)
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#maxvalue Documentation}
  */
-declare const maxValue: RegleRuleWithParamsDefinition<number | string, [count: number | string, options?: CommonComparisonOptions], false, boolean, MaybeInput<number | string>>;
+declare const maxValue: RegleRuleWithParamsDefinition<number | string, [max: number | string, options?: CommonComparisonOptions], false, boolean, MaybeInput<number | string>>;
 /**
  * Requires the input value to have a minimum specified length, inclusive. Works with arrays, objects and strings.
  *
- * @param min - the minimum value
- * @param options - comparison options
+ * @param min - The minimum length
+ * @param options - Optional configuration (e.g., `{ allowEqual: false }`)
+ *
+ * @example
+ * ```ts
+ * import { minLength } from '@regle/rules';
+ *
+ * const minValue = ref(6);
+ *
+ * const { r$ } = useRegle({ name: '' }, {
+ *   name: {
+ *     minLength: minLength(6),
+ *     // or with reactive value
+ *     minLength: minLength(minValue),
+ *     // or with getter
+ *     minLength: minLength(() => minValue.value)
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#minlength Documentation}
  */
-declare const minLength: RegleRuleWithParamsDefinition<string | any[] | Record<PropertyKey, any>, [count: number, options?: CommonComparisonOptions], false, boolean>;
+declare const minLength: RegleRuleWithParamsDefinition<string | any[] | Record<PropertyKey, any>, [min: number, options?: CommonComparisonOptions], false, boolean>;
 /**
  * Requires a field to have a specified minimum numeric value.
  *
- * @param count - the minimum count
- * @param options - comparison options
+ * @param min - The minimum value
+ * @param options - Optional configuration (e.g., `{ allowEqual: false }`)
+ *
+ * @example
+ * ```ts
+ * import { minValue } from '@regle/rules';
+ *
+ * const minCount = ref(6);
+ *
+ * const { r$ } = useRegle({ count: 0 }, {
+ *   count: {
+ *     minValue: minValue(6),
+ *     // or with options
+ *     minValue: minValue(minCount, { allowEqual: false }),
+ *     // or with getter
+ *     minValue: minValue(() => minCount.value)
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#minvalue Documentation}
  */
-declare const minValue: RegleRuleWithParamsDefinition<number | string, [count: number | string, options?: CommonComparisonOptions], false, boolean, MaybeInput<number | string>>;
+declare const minValue: RegleRuleWithParamsDefinition<number | string, [min: number | string, options?: CommonComparisonOptions], false, boolean, MaybeInput<number | string>>;
 type EnumLike = {
   [k: string]: string | number;
   [nu: number]: string;
 };
 /**
- * Validate against a native Typescript enum value.
+ * Validate against a native TypeScript enum value. Similar to Zod's `nativeEnum`.
+ *
+ * @param enumLike - The TypeScript enum to validate against
+ *
+ * @example
+ * ```ts
+ * import { nativeEnum } from '@regle/rules';
+ *
+ * enum Foo {
+ *   Bar, Baz
+ * }
+ *
+ * const { r$ } = useRegle({ type: '' }, {
+ *   type: { nativeEnum: nativeEnum(Foo) },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#nativeenum Documentation}
  */
 declare function nativeEnum<T extends EnumLike>(enumLike: T): RegleRuleDefinition<MaybeInput<T[keyof T]>, [enumLike: T], false, boolean, MaybeInput<T[keyof T]>, string | number>;
 /**
- * Requires a value to be a native number type
+ * Requires a value to be a native number type.
+ *
+ * Mainly used for typing with `InferInput`.
+ *
+ * @example
+ * ```ts
+ * import { type InferInput } from '@regle/core';
+ * import { number } from '@regle/rules';
+ *
+ * const rules = {
+ *   count: { number },
+ * }
+ *
+ * const state = ref<InferInput<typeof rules>>({});
+ * ```
  *
- * Mainly used for typing
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#number Documentation}
  */
 declare const number: RegleRuleDefinition<unknown, [], false, boolean, MaybeInput<number>, unknown>;
 /**
  * Allows only numeric values (including numeric strings).
+ *
+ * @example
+ * ```ts
+ * import { numeric } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ count: 0 }, {
+ *   count: { numeric },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#numeric Documentation}
  */
 declare const numeric: RegleRuleDefinition<string | number, [], false, boolean, MaybeInput<string | number>>;
 interface OneOfFn {
@@ -345,26 +1040,105 @@ interface OneOfFn {
 }
 /**
  * Allow only one of the values from a fixed Array of possible entries.
+ *
+ * @param options - Array of allowed values
+ *
+ * @example
+ * ```ts
+ * import { oneOf } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ aliment: 'Fish' }, {
+ *   aliment: {
+ *     oneOf: oneOf(['Fish', 'Meat', 'Bone'])
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#oneof Documentation}
  */
 declare const oneOf: OneOfFn;
 /**
  * Checks if the value matches one or more regular expressions.
+ *
+ * @param regexp - A single RegExp or an array of RegExp patterns
+ *
+ * @example
+ * ```ts
+ * import { regex } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ name: '' }, {
+ *   name: {
+ *     regex: regex(/^foo/),
+ *     // or with multiple patterns
+ *     regex: regex([/^bar/, /baz$/]),
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#regex Documentation}
  */
 declare const regex: RegleRuleWithParamsDefinition<string | number, [regexp: RegExp | RegExp[]], false, boolean, MaybeInput<string | number>>;
 /**
  * Requires non-empty data. Checks for empty arrays and strings containing only whitespaces.
+ *
+ * @example
+ * ```ts
+ * import { required } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ name: '' }, {
+ *   name: { required },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#required Documentation}
  */
 declare const required: RegleRuleDefinition<unknown, [], false, boolean, unknown>;
 /**
- * Requires non-empty data, only if provided data property, ref, or a function resolves to true.
+ * Requires non-empty data, only if provided data property, ref, or a function resolves to `true`.
+ *
+ * @param condition - The condition to enable the required rule (can be a ref, getter, or value)
+ *
+ * @example
+ * ```ts
+ * import { requiredIf } from '@regle/rules';
+ *
+ * const form = ref({ name: '', condition: false });
+ * const conditionRef = ref(false);
+ *
+ * const { r$ } = useRegle(form, {
+ *   name: {
+ *     required: requiredIf(() => form.value.condition),
+ *     // or with a ref
+ *     required: requiredIf(conditionRef),
+ *   },
+ * })
+ * ```
  *
- * @param condition - the condition to enable the required rule
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#requiredif Documentation}
  */
 declare const requiredIf: RegleRuleWithParamsDefinition<unknown, [condition: boolean], false, boolean>;
 /**
- * Requires non-empty data, only if provided data property, ref, or a function resolves to false.
+ * Requires non-empty data, only if provided data property, ref, or a function resolves to `false`.
+ *
+ * @param condition - The condition to disable the required rule (can be a ref, getter, or value)
+ *
+ * @example
+ * ```ts
+ * import { requiredUnless } from '@regle/rules';
+ *
+ * const form = ref({ name: '', condition: false });
+ * const conditionRef = ref(false);
+ *
+ * const { r$ } = useRegle(form, {
+ *   name: {
+ *     required: requiredUnless(() => form.value.condition),
+ *     // or with a ref
+ *     required: requiredUnless(conditionRef)
+ *   },
+ * })
+ * ```
  *
- * @param condition - the condition to disable the required rule
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#requiredunless Documentation}
  */
 declare const requiredUnless: RegleRuleWithParamsDefinition<unknown, [condition: boolean], false, boolean>;
 interface SameAsFn {
@@ -373,29 +1147,103 @@ interface SameAsFn {
   (target: MaybeRefOrGetter<unknown>, otherName?: MaybeRefOrGetter<string>): RegleRuleDefinition<unknown, [target: any, otherName?: string], false, boolean, unknown extends MaybeInput<infer M> ? M : MaybeInput<unknown>>;
 }
 /**
- * Checks if the value matches the specified property or ref.
+ * Checks if the value matches the specified property or ref. Useful for password confirmation fields.
+ *
+ * @param target - The target value to compare against (can be a ref or getter)
+ * @param otherName - Optional name for the other field (used in error message)
+ *
+ * @example
+ * ```ts
+ * import { sameAs } from '@regle/rules';
+ *
+ * const form = ref({
+ *   password: '',
+ *   confirmPassword: '',
+ * });
+ *
+ * const { r$ } = useRegle(form, {
+ *   confirmPassword: {
+ *     sameAs: sameAs(() => form.value.password),
+ *   }
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#sameas Documentation}
  */
 declare const sameAs: SameAsFn;
 /**
  * Checks if the string starts with the specified substring.
  *
- * @private part - the value the field must start with
+ * @param part - The substring the value must start with
+ *
+ * @example
+ * ```ts
+ * import { startsWith } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ bestLib: '' }, {
+ *   bestLib: {
+ *     startsWith: startsWith('regle')
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#startswith Documentation}
  */
 declare const startsWith: RegleRuleWithParamsDefinition<string, [part: MaybeInput<string>], false, boolean, MaybeInput<string>>;
 /**
- * Requires a value to be a native string type
+ * Requires a value to be a native string type.
+ *
+ * Mainly used for typing with `InferInput`.
+ *
+ * @example
+ * ```ts
+ * import { type InferInput } from '@regle/core';
+ * import { string } from '@regle/rules';
+ *
+ * const rules = {
+ *   firstName: { string },
+ * }
+ *
+ * const state = ref<InferInput<typeof rules>>({});
+ * ```
  *
- * Mainly used for typing
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#string Documentation}
  */
 declare const string: RegleRuleDefinition<unknown, [], false, boolean, MaybeInput<string>, unknown>;
 /**
  * Define the input type of a rule. No runtime validation.
  *
  * Override any input type set by other rules.
+ *
+ * @example
+ * ```ts
+ * import { type InferInput } from '@regle/core';
+ * import { type } from '@regle/rules';
+ *
+ * const rules = {
+ *   firstName: { type: type<string>() },
+ *   status: { type: type<'active' | 'inactive'>() },
+ * }
+ *
+ * const state = ref<InferInput<typeof rules>>({});
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#type Documentation}
  */
 declare function type<T>(): RegleRuleDefinition<unknown, [], false, boolean, MaybeInput<T>>;
 /**
  * Validates URLs.
+ *
+ * @example
+ * ```ts
+ * import { url } from '@regle/rules';
+ *
+ * const { r$ } = useRegle({ bestUrl: '' }, {
+ *   bestUrl: { url },
+ * })
+ * ```
+ *
+ * @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#url Documentation}
  */
 declare const url: RegleRuleDefinition<string, [], false, boolean, MaybeInput<string>>;
 export { EnumLike, alpha, alphaNum, and, applyIf, assignIf, between, boolean, checked, contains, date, dateAfter, dateBefore, dateBetween, decimal, email, endsWith, exactLength, exactValue, getSize, hexadecimal, integer, ipv4Address, isDate, isEmpty, isFilled, isNumber, literal, macAddress, matchRegex, maxLength, maxValue, minLength, minValue, nativeEnum, not, number, numeric, oneOf, or, regex, required, requiredIf, requiredUnless, sameAs, startsWith, string, toDate, toNumber, type, url, withAsync, withMessage, withParams, withTooltip };