@regle/rules 1.13.0 → 1.14.0-beta.3

package/dist/regle-rules.js

@@ -106,19 +106,27 @@ function withParams(rule, depsArray) {
 }
 
 /**
-* 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}
 */
 function applyIf(_condition, rule) {
 	let _type;
@@ -162,12 +170,34 @@ function isFile(value) {
 }
 
 /**
-* 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`.
 *
-* isEmpty also acts as a type guard.
+* @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
+*
+* @example
+* ```ts
+* import { createRule, type Maybe } from '@regle/core';
+* import { isEmpty } from '@regle/rules';
+*
+* const rule = createRule({
+*   validator(value: Maybe<string>) {
+*     if (isEmpty(value)) {
+*       return true;
+*     }
+*     return check(value);
+*   },
+*   message: 'Error'
+* })
+* ```
 *
-* @param value - the target value
-* @param [considerEmptyArrayInvalid=true] - will return false if set to `false`. (default: `true`)
+* @see {@link https://reglejs.dev/core-concepts/rules/validations-helpers#isempty Documentation}
 */
 function isEmpty(value, considerEmptyArrayInvalid = true) {
 	if (value === void 0 || value === null) return true;
@@ -186,7 +216,29 @@ function isObject(obj) {
 }
 
 /**
-* 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}
 */
 function isDate(value) {
 	if (isEmpty(value)) return false;
@@ -205,7 +257,21 @@ function isDate(value) {
 }
 
 /**
-* 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}
 */
 function toDate(argument) {
 	const argStr = Object.prototype.toString.call(argument);
@@ -217,19 +283,63 @@ function toDate(argument) {
 }
 
 /**
-* 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
 *
-* isFilled also acts as a type guard.
+* @example
+* ```ts
+* import { createRule } from '@regle/core';
+* import { isFilled } from '@regle/rules';
+*
+* 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}
 */
 function isFilled(value, considerEmptyArrayInvalid = true) {
 	return !isEmpty(typeof value === "string" ? value.trim() : value, considerEmptyArrayInvalid);
 }
 
 /**
-* 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}
 */
 function isNumber(value) {
 	if (value == null) return false;
@@ -239,7 +349,30 @@ function isNumber(value) {
 }
 
 /**
-* 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}
 */
 function matchRegex(_value, ...expr) {
 	if (isEmpty(_value)) return true;
@@ -251,7 +384,28 @@ function matchRegex(_value, ...expr) {
 }
 
 /**
-* 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}
 */
 function getSize(value) {
 	const _value = unref(value);
@@ -265,9 +419,25 @@ function getSize(value) {
 }
 
 /**
-* 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`)
 *
-* @returns ⚠️ 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
+* }
+* ```
+*
+* @see {@link https://reglejs.dev/core-concepts/rules/validations-helpers#tonumber Documentation}
 */
 function toNumber(argument) {
 	if (typeof argument === "number") return argument;
@@ -282,7 +452,31 @@ function toNumber(argument) {
 }
 
 /**
-* 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}
 */
 function and(...rules) {
 	const isAnyRuleAsync = rules.some((rule) => {
@@ -348,7 +542,31 @@ function and(...rules) {
 }
 
 /**
-* 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}
 */
 function or(...rules) {
 	const isAnyRuleAsync = rules.some((rule) => {
@@ -405,7 +623,33 @@ function or(...rules) {
 }
 
 /**
-* 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}
 */
 function not(rule, message) {
 	let _type;
@@ -439,26 +683,39 @@ function not(rule, message) {
 	else return newRule;
 }
 
+function mapRulesWithCondition(condition, rules, trueCheck) {
+	return Object.entries(toValue(rules)).map(([key, rule]) => {
+		if (typeof rule === "function" || isObject(rule) && "_validator" in rule) return [key, applyIf(trueCheck ? condition : () => !toValue(condition), rule)];
+		return [key, rule];
+	});
+}
 /**
-* 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}
 */
-function assignIf(_condition, rules) {
+function assignIf(_condition, rules, otherwiseRules) {
 	return computed(() => {
-		return Object.fromEntries(Object.entries(toValue(rules)).map(([key, rule]) => {
-			if (typeof rule === "function" || isObject(rule) && "_validator" in rule) return [key, applyIf(_condition, rule)];
-			return [key, rule];
-		}));
+		let trueRules = mapRulesWithCondition(_condition, rules, true);
+		let falseRules = otherwiseRules ? mapRulesWithCondition(_condition, otherwiseRules, false) : [];
+		return Object.fromEntries([...trueRules, ...falseRules]);
 	});
 }
 
@@ -467,8 +724,23 @@ const alphaSymbolRegex = /^[\w.]+$/;
 /**
 * 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}
+*/
 const alpha = createRule({
 	type: "alpha",
 	validator(value, options) {
@@ -484,7 +756,22 @@ const alphaNumSymbolRegex = /^[a-zA-Z0-9_]*$/;
 /**
 * 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}
 */
 const alphaNum = createRule({
 	type: "alphaNum",
@@ -497,10 +784,30 @@ const alphaNum = createRule({
 });
 
 /**
-* 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);
+*
+* 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)
+*   },
+* })
+* ```
 *
-* @param min - the minimum limit
-* @param max - the maximum limit
+* @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#between Documentation}
 */
 const between = createRule({
 	type: "between",
@@ -523,9 +830,23 @@ const between = createRule({
 });
 
 /**
-* 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 },
+* }
 *
-* Mainly used for typing
+* const state = ref<InferInput<typeof rules>>({});
+* ```
+*
+* @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#boolean Documentation}
 */
 const boolean = createRule({
 	type: "boolean",
@@ -537,7 +858,18 @@ const boolean = createRule({
 });
 
 /**
-* 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}
 */
 const checked = createRule({
 	type: "checked",
@@ -551,7 +883,20 @@ const checked = createRule({
 /**
 * 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}
 */
 const contains = createRule({
 	type: "contains",
@@ -565,9 +910,23 @@ const contains = createRule({
 });
 
 /**
-* 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}
 */
 const date = createRule({
 	type: "date",
@@ -590,8 +949,23 @@ function formatLocaleDate(date$1) {
 /**
 * 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}
 */
 const dateAfter = createRule({
 	type: "dateAfter",
@@ -621,8 +995,23 @@ const dateAfter = createRule({
 /**
 * 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}
 */
 const dateBefore = createRule({
 	type: "dateBefore",
@@ -652,9 +1041,24 @@ const dateBefore = createRule({
 /**
 * 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}
 */
 const dateBetween = createRule({
 	type: "dateBetween",
@@ -672,6 +1076,17 @@ const dateBetween = createRule({
 const decimalRegex = /^[-]?\d*(\.\d+)?$/;
 /**
 * 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}
 */
 const decimal = createRule({
 	type: "decimal",
@@ -685,6 +1100,17 @@ const decimal = createRule({
 const emailRegex = /^(?:[A-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9]{2,}(?:[a-z0-9-]*[a-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])$/i;
 /**
 * 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}
 */
 const email = createRule({
 	type: "email",
@@ -698,7 +1124,18 @@ const email = createRule({
 /**
 * 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}
 */
 const endsWith = createRule({
 	type: "endsWith",
@@ -712,9 +1149,28 @@ const endsWith = createRule({
 });
 
 /**
-* 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
 *
-* @param count - the required length
+* @example
+* ```ts
+* import { exactLength } from '@regle/rules';
+*
+* const exactValue = ref(6);
+*
+* 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}
 */
 const exactLength = createRule({
 	type: "exactLength",
@@ -733,6 +1189,27 @@ const exactLength = createRule({
 
 /**
 * 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}
 */
 const exactValue = createRule({
 	type: "exactValue",
@@ -751,7 +1228,18 @@ const exactValue = createRule({
 
 const hexadecimalRegex = /^[a-fA-F0-9]*$/;
 /**
-* 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}
 */
 const hexadecimal = createRule({
 	type: "hexadecimal",
@@ -765,6 +1253,17 @@ const hexadecimal = createRule({
 const integerRegex = /(^[0-9]*$)|(^-[0-9]+$)/;
 /**
 * 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}
 */
 const integer = createRule({
 	type: "integer",
@@ -783,7 +1282,18 @@ function nibbleValid(nibble) {
 	return numeric$1 >= 0 && numeric$1 <= 255;
 }
 /**
-* 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}
 */
 const ipv4Address = createRule({
 	type: "ipv4Address",
@@ -797,7 +1307,20 @@ const ipv4Address = createRule({
 });
 
 /**
-* 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}
 */
 function literal(literal$1) {
 	return withMessage(withParams((value, literal$2) => {
@@ -807,9 +1330,24 @@ function literal(literal$1) {
 }
 
 /**
-* 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}
 */
 const macAddress = createRule({
 	type: "macAddress",
@@ -826,17 +1364,36 @@ const hexValid = (hex) => hex.toLowerCase().match(/^[0-9a-f]{2}$/);
 /**
 * 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}
 */
 const maxLength = createRule({
 	type: "maxLength",
-	validator: (value, count, options) => {
+	validator: (value, max, options) => {
 		const { allowEqual = true } = options ?? {};
-		if (isFilled(value, false) && isFilled(count)) {
-			if (isNumber(count)) if (allowEqual) return getSize(value) <= count;
-			else return getSize(value) < count;
-			console.warn(`[maxLength] Value or parameter isn't a number, got value: ${value}, parameter: ${count}`);
+		if (isFilled(value, false) && isFilled(max)) {
+			if (isNumber(max)) if (allowEqual) return getSize(value) <= max;
+			else return getSize(value) < max;
+			console.warn(`[maxLength] Value or parameter isn't a number, got value: ${value}, parameter: ${max}`);
 			return false;
 		}
 		return true;
@@ -850,74 +1407,131 @@ const maxLength = createRule({
 /**
 * 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}
 */
 const maxValue = createRule({
 	type: "maxValue",
-	validator: (value, count, options) => {
+	validator: (value, max, options) => {
 		const { allowEqual = true } = options ?? {};
-		if (isFilled(value) && isFilled(count)) {
-			if (!isNaN(toNumber(value)) && !isNaN(toNumber(count))) if (allowEqual) return toNumber(value) <= toNumber(count);
-			else return toNumber(value) < toNumber(count);
-			console.warn(`[maxValue] Value or parameter isn't a number, got value: ${value}, parameter: ${count}`);
+		if (isFilled(value) && isFilled(max)) {
+			if (!isNaN(toNumber(value)) && !isNaN(toNumber(max))) if (allowEqual) return toNumber(value) <= toNumber(max);
+			else return toNumber(value) < toNumber(max);
+			console.warn(`[maxValue] Value or parameter isn't a number, got value: ${value}, parameter: ${max}`);
 			return false;
 		}
 		return true;
 	},
-	message: ({ $params: [count, options] }) => {
+	message: ({ $params: [max, options] }) => {
 		const { allowEqual = true } = options ?? {};
-		if (allowEqual) return `The value must be less than or equal to ${count}`;
-		else return `The value must be less than ${count}`;
+		if (allowEqual) return `The value must be less than or equal to ${max}`;
+		else return `The value must be less than ${max}`;
 	}
 });
 
 /**
 * 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}
 */
 const minLength = createRule({
 	type: "minLength",
-	validator: (value, count, options) => {
+	validator: (value, min, options) => {
 		const { allowEqual = true } = options ?? {};
-		if (isFilled(value, false) && isFilled(count)) {
-			if (isNumber(count)) if (allowEqual) return getSize(value) >= count;
-			else return getSize(value) > count;
-			console.warn(`[minLength] Parameter isn't a number, got parameter: ${count}`);
+		if (isFilled(value, false) && isFilled(min)) {
+			if (isNumber(min)) if (allowEqual) return getSize(value) >= min;
+			else return getSize(value) > min;
+			console.warn(`[minLength] Parameter isn't a number, got parameter: ${min}`);
 			return false;
 		}
 		return true;
 	},
-	message: ({ $value, $params: [count] }) => {
-		if (Array.isArray($value)) return `The list should have at least ${count} items`;
-		return `The value length should be at least ${count}`;
+	message: ({ $value, $params: [min] }) => {
+		if (Array.isArray($value)) return `The list should have at least ${min} items`;
+		return `The value length should be at least ${min}`;
 	}
 });
 
 /**
 * 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}
 */
 const minValue = createRule({
 	type: "minValue",
-	validator: (value, count, options) => {
+	validator: (value, min, options) => {
 		const { allowEqual = true } = options ?? {};
-		if (isFilled(value) && isFilled(count)) {
-			if (!isNaN(toNumber(value)) && !isNaN(toNumber(count))) if (allowEqual) return toNumber(value) >= toNumber(count);
-			else return toNumber(value) > toNumber(count);
-			console.warn(`[minValue] Value or parameter isn't a number, got value: ${value}, parameter: ${count}`);
+		if (isFilled(value) && isFilled(min)) {
+			if (!isNaN(toNumber(value)) && !isNaN(toNumber(min))) if (allowEqual) return toNumber(value) >= toNumber(min);
+			else return toNumber(value) > toNumber(min);
+			console.warn(`[minValue] Value or parameter isn't a number, got value: ${value}, parameter: ${min}`);
 			return false;
 		}
 		return true;
 	},
-	message: ({ $params: [count, options] }) => {
+	message: ({ $params: [min, options] }) => {
 		const { allowEqual = true } = options ?? {};
-		if (allowEqual) return `The value must be greater than or equal to ${count}`;
-		else return `The value must be greater than ${count}`;
+		if (allowEqual) return `The value must be greater than or equal to ${min}`;
+		else return `The value must be greater than ${min}`;
 	}
 });
 
@@ -928,7 +1542,24 @@ function getValidEnumValues(obj) {
 	return Object.values(filtered);
 }
 /**
-* 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}
 */
 function nativeEnum(enumLike) {
 	return withMessage(withParams((value, enumLike$1) => {
@@ -938,9 +1569,23 @@ function nativeEnum(enumLike) {
 }
 
 /**
-* Requires a value to be a native number type
+* Requires a value to be a native number type.
+*
+* Mainly used for typing with `InferInput`.
 *
-* Mainly used for typing
+* @example
+* ```ts
+* import { type InferInput } from '@regle/core';
+* import { number } from '@regle/rules';
+*
+* const rules = {
+*   count: { number },
+* }
+*
+* const state = ref<InferInput<typeof rules>>({});
+* ```
+*
+* @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#number Documentation}
 */
 const number = createRule({
 	type: "number",
@@ -954,6 +1599,17 @@ const number = createRule({
 const numericRegex = /^\d*(\.\d+)?$/;
 /**
 * 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}
 */
 const numeric = createRule({
 	type: "numeric",
@@ -966,6 +1622,21 @@ const numeric = createRule({
 
 /**
 * 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}
 */
 const oneOf = createRule({
 	type: "oneOf",
@@ -978,6 +1649,23 @@ const oneOf = createRule({
 
 /**
 * 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}
 */
 const regex = createRule({
 	type: "regex",
@@ -990,6 +1678,17 @@ const regex = createRule({
 
 /**
 * 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}
 */
 const required = createRule({
 	type: "required",
@@ -1000,9 +1699,27 @@ const required = createRule({
 });
 
 /**
-* 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}
 */
 const requiredIf = createRule({
 	type: "required",
@@ -1017,9 +1734,27 @@ const requiredIf = createRule({
 });
 
 /**
-* 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}
 */
 const requiredUnless = createRule({
 	type: "required",
@@ -1034,7 +1769,28 @@ const requiredUnless = createRule({
 });
 
 /**
-* 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}
 */
 const sameAs = createRule({
 	type: "sameAs",
@@ -1050,7 +1806,20 @@ const sameAs = createRule({
 /**
 * 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}
 */
 const startsWith = createRule({
 	type: "startsWith",
@@ -1064,9 +1833,23 @@ const startsWith = createRule({
 });
 
 /**
-* Requires a value to be a native string type
+* Requires a value to be a native string type.
+*
+* Mainly used for typing with `InferInput`.
 *
-* Mainly used for typing
+* @example
+* ```ts
+* import { type InferInput } from '@regle/core';
+* import { string } from '@regle/rules';
+*
+* const rules = {
+*   firstName: { string },
+* }
+*
+* const state = ref<InferInput<typeof rules>>({});
+* ```
+*
+* @see {@link https://reglejs.dev/core-concepts/rules/built-in-rules#string Documentation}
 */
 const string = createRule({
 	type: "string",
@@ -1081,6 +1864,21 @@ const string = createRule({
 * 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}
 */
 function type() {
 	return (() => true);
@@ -1092,6 +1890,17 @@ function type() {
 const urlRegex = /^(?:(?:(?:https?|ftp):)?\/\/)(?:\S+(?::\S*)?@)?(?:(?!(?:10|127)(?:\.\d{1,3}){3})(?!(?:169\.254|192\.168)(?:\.\d{1,3}){2})(?!172\.(?:1[6-9]|2\d|3[0-1])(?:\.\d{1,3}){2})(?:[1-9]\d?|1\d\d|2[01]\d|22[0-3])(?:\.(?:1?\d{1,2}|2[0-4]\d|25[0-5])){2}(?:\.(?:[1-9]\d?|1\d\d|2[0-4]\d|25[0-4]))|(?:(?:[a-z0-9\u00a1-\uffff][a-z0-9\u00a1-\uffff_-]{0,62})?[a-z0-9\u00a1-\uffff]\.)+(?:[a-z\u00a1-\uffff]{2,}\.?))(?::\d{2,5})?(?:[/?#]\S*)?$/i;
 /**
 * 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}
 */
 const url = createRule({
 	type: "url",