@regle/core 1.13.1 → 1.14.0-beta.1

package/dist/regle-core.js

@@ -9,12 +9,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.
+* `isEmpty` also acts as a type guard.
 *
-* @param value - the target value
-* @param [considerEmptyArrayInvalid=true] - will return false if set to `false`. (default: `true`)
+* 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
+*
+* @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'
+* })
+* ```
+*
+* @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;
@@ -153,7 +175,21 @@ function isConstructor(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);
@@ -370,35 +406,57 @@ function defineRuleProcessors(definition, ...params) {
 }
 
 /**
-* Create a typed custom rule that can be used like default rules.
-* It can also be declared in the global options
+* Create a typed custom rule that can be used like built-in rules.
+* The created rule can be declared in global options or used directly.
 *
-* It will automatically detect if the rule is async
+* Features:
+* - Automatically detects if the rule is async
+* - Supports parameters for configurable rules
+* - Full TypeScript type inference
+* - Custom metadata support
 *
+* @param definition - The rule definition object containing:
+*   - `validator`: The validation function
+*   - `message`: Error message (string or function)
+*   - `type`: Optional rule type identifier
+*   - `active`: Optional function to conditionally activate the rule
+*   - `tooltip`: Optional tooltip message
 *
-* @param definition - The rule processors object
-*
-* @returns A rule definition that can be callable depending on params presence
-*
-* @exemple
+* @returns A rule definition that is callable if it accepts parameters
 *
+* @example
 * ```ts
-* // Create a simple rule with no params
-* import {isFilled} from '@regle/rules';
+* import { createRule } from '@regle/core';
+* import { isFilled } from '@regle/rules';
 *
+* // Simple rule without params
 * export const isFoo = createRule({
 *   validator(value: Maybe<string>) {
-*       if (isFilled(value)) {
-*           return value === 'foo';
-*       }
-*       return true
+*     if (isFilled(value)) {
+*       return value === 'foo';
+*     }
+*     return true;
 *   },
 *   message: "The value should be 'foo'"
-* })
+* });
+*
+* // Rule with parameters
+* export const minCustom = createRule({
+*   validator(value: Maybe<number>, min: number) {
+*     if (isFilled(value)) {
+*       return value >= min;
+*     }
+*     return true;
+*   },
+*   message: ({ $params: [min] }) => `Value must be at least ${min}`
+* });
 *
+* // Usage
+* useRegle({ name: '' }, { name: { isFoo } });
+* useRegle({ count: 0 }, { count: { minCustom: minCustom(5) } });
 * ```
 *
-* Docs: {@link https://reglejs.dev/core-concepts/rules/reusable-rules}
+* @see {@link https://reglejs.dev/core-concepts/rules/reusable-rules Documentation}
 */
 function createRule(definition) {
 	if (typeof definition.validator === "function") {
@@ -2984,7 +3042,7 @@ function filterInspectorTree(nodes, filter) {
 	return filtered;
 }
 
-var version$1 = "1.13.1";
+var version$1 = "1.14.0-beta.1";
 
 function createDevtools(app) {
 	setupDevtoolsPlugin({
@@ -3187,23 +3245,37 @@ function createUseRegleComposable(customRules, options, shortcuts) {
 	return useRegle$1;
 }
 /**
-* useRegle serves as the foundation for validation logic.
+* `useRegle` serves as the foundation for validation logic.
+* It transforms your data and validation rules into a powerful, reactive validation system.
 *
-* It accepts the following inputs:
+* @param state - Your form data (plain object, ref, reactive object, or structure with nested refs)
+* @param rules - Validation rules that should align with the structure of your state
+* @param modifiers - Optional configuration to customize regle behavior
+* @returns An object containing `r$` - the reactive validation state
 *
-* @param state - This can be a plain object, a ref, a reactive object, or a structure containing nested refs.
-* @param rules - These should align with the structure of your state.
-* @param modifiers - Customize regle behaviour
-* 
+* @example
 * ```ts
 * import { useRegle } from '@regle/core';
-import { required } from '@regle/rules';
-
-const { r$ } = useRegle({ email: '' }, {
-email: { required }
-})
+* import { required, email, minLength } from '@regle/rules';
+*
+* const { r$ } = useRegle(
+*   { name: '', email: '' },
+*   {
+*     name: { required, minLength: minLength(2) },
+*     email: { required, email }
+*   }
+* );
+*
+* // Access validation state
+* r$.$valid        // Whether all validations pass
+* r$.$value        // The current form values
+* r$.name.$errors  // Errors for the name field
+*
+* // Trigger validation
+* const result = await r$.$validate();
 * ```
-* Docs: {@link https://reglejs.dev/core-concepts/}  
+*
+* @see {@link https://reglejs.dev/core-concepts/ Documentation}
 */
 const useRegle = createUseRegleComposable();
 
@@ -3214,11 +3286,31 @@ function createInferRuleHelper() {
 	return inferRules$1;
 }
 /**
-* Rule type helper to provide autocomplete and typecheck to your form rules or part of your form rules
-* It will just return the rules without any processing.
+* Type helper to provide autocomplete and type-checking for your form rules.
+* It returns the rules without any processing - useful with computed rules.
 *
 * @param state - The state reference
 * @param rules - Your rule tree
+* @returns The rules object (passthrough)
+*
+* @example
+* ```ts
+* import { inferRules, useRegle } from '@regle/core';
+* import { required, minLength } from '@regle/rules';
+*
+* const state = ref({ name: '' });
+*
+* // inferRules preserves TypeScript autocompletion
+* const rules = computed(() => {
+*   return inferRules(state, {
+*     name: { required, minLength: minLength(2) }
+*   })
+* });
+*
+* const { r$ } = useRegle(state, rules);
+* ```
+*
+* @see {@link https://reglejs.dev/core-concepts/#dynamic-rules-object Documentation}
 */
 const inferRules = createInferRuleHelper();
 
@@ -3255,21 +3347,34 @@ function createUseRulesComposable(customRules, options, shortcuts) {
 	return useRules$1;
 }
 /**
-* useRules is a clone of useRegle, without the need to provide a state.
+* `useRules` is a variant of `useRegle` that doesn't require you to provide initial state.
+* It creates an empty state based on your rules structure and implements the Standard Schema spec.
 *
-* It accepts the following inputs:
+* This is useful when you want to define validation rules first and infer the state type from them.
 *
-* @param rules - Your rules object
-* @param modifiers - Customize regle behaviour
-* 
+* @param rules - Your validation rules object
+* @param modifiers - Optional configuration to customize regle behavior
+* @returns The reactive validation state (implements StandardSchemaV1)
+*
+* @example
 * ```ts
-* import { useRules } from '@regle/core';
-import { required } from '@regle/rules';
-
-const { r$ } = useRules({
-email: { required }
-})
+* import { useRules, type InferInput } from '@regle/core';
+* import { required, string, email } from '@regle/rules';
+*
+* const r$ = useRules({
+*   name: { required, string },
+*   email: { required, email }
+* });
+*
+* // State is automatically created and typed
+* r$.$value.name // string | null
+* r$.$value.email // string | null
+*
+* // Can be used with Standard Schema compatible libraries
+* const result = await r$['~standard'].validate({ name: '', email: '' });
 * ```
+*
+* @see {@link https://reglejs.dev/common-usage/standard-schema#userules Documentation}
 */
 const useRules = createUseRulesComposable();
 
@@ -3303,16 +3408,43 @@ function applyMarkStatic(value) {
 }
 
 /**
-* Define a global regle configuration, where you can:
+* Define a global Regle configuration to customize the validation behavior across your application.
+*
+* Features:
 * - Customize built-in rules messages
-* - Add your custom rules
-* - Define global modifiers
-* - Define shortcuts
+* - Add your custom rules with full type inference
+* - Define global modifiers (lazy, rewardEarly, etc.)
+* - Define shortcuts for common validation patterns
+*
+* @param options - Configuration options
+* @param options.rules - Factory function returning custom rules
+* @param options.modifiers - Global behavior modifiers
+* @param options.shortcuts - Reusable validation shortcuts
+* @returns Object containing typed `useRegle`, `inferRules`, and `useRules` functions
+*
+* @example
+* ```ts
+* import { defineRegleConfig } from '@regle/core';
+* import { required, withMessage } from '@regle/rules';
 *
-* It will return:
+* export const { useRegle, inferRules, useRules } = defineRegleConfig({
+*   rules: () => ({
+*     // Override default required message
+*     required: withMessage(required, 'This field cannot be empty'),
+*     // Add custom rule
+*     myCustomRule: createRule({
+*       validator: (value) => value === 'valid',
+*       message: 'Invalid value'
+*     })
+*   }),
+*   modifiers: {
+*     lazy: true,
+*     rewardEarly: true
+*   }
+* });
+* ```
 *
-* - a `useRegle` composable that can typecheck your custom rules
-* - an `inferRules` helper that can typecheck your custom rules
+* @see {@link https://reglejs.dev/advanced-usage/global-config Documentation}
 */
 function defineRegleConfig({ rules, modifiers, shortcuts }) {
 	const useRegle$1 = createUseRegleComposable(rules, modifiers, shortcuts);
@@ -3334,12 +3466,31 @@ function defineRegleConfig({ rules, modifiers, shortcuts }) {
 	};
 }
 /**
-* Extend an already created custom `useRegle` (as the first parameter)
+* Extend an already created custom `useRegle` configuration with additional rules, modifiers, or shortcuts.
 *
-* It will return:
+* @param regle - The existing useRegle function to extend
+* @param options - Additional configuration to merge
+* @param options.rules - Additional custom rules
+* @param options.modifiers - Additional modifiers to merge
+* @param options.shortcuts - Additional shortcuts to merge
+* @returns Object containing the extended `useRegle` and `inferRules` functions
 *
-* - a `useRegle` composable that can typecheck your custom rules
-* - an `inferRules` helper that can typecheck your custom rules
+* @example
+* ```ts
+* import { extendRegleConfig } from '@regle/core';
+* import { baseUseRegle } from './base-config';
+*
+* export const { useRegle, inferRules } = extendRegleConfig(baseUseRegle, {
+*   rules: () => ({
+*     additionalRule: myNewRule
+*   }),
+*   modifiers: {
+*     rewardEarly: true
+*   }
+* });
+* ```
+*
+* @see {@link https://reglejs.dev/advanced-usage/global-config Documentation}
 */
 function extendRegleConfig(regle, { rules, modifiers, shortcuts }) {
 	const rootConfig = regle.__config ?? {};
@@ -3361,6 +3512,44 @@ function extendRegleConfig(regle, { rules, modifiers, shortcuts }) {
 	};
 }
 
+/**
+* Merge multiple Regle instances into a single validation state.
+* Useful for combining multiple forms or validation scopes.
+*
+* @param regles - An object containing named Regle instances to merge
+* @param _scoped - Internal flag for scoped validation (default: false)
+* @returns A merged validation state with all instances' properties combined
+*
+* @example
+* ```ts
+* import { useRegle, mergeRegles } from '@regle/core';
+* import { required } from '@regle/rules';
+*
+* // Create separate validation instances
+* const { r$: personalInfo } = useRegle(
+*   { name: '', email: '' },
+*   { name: { required }, email: { required } }
+* );
+*
+* const { r$: address } = useRegle(
+*   { street: '', city: '' },
+*   { street: { required }, city: { required } }
+* );
+*
+* // Merge them together
+* const merged$ = mergeRegles({
+*   personalInfo,
+*   address
+* });
+*
+* // Access combined state
+* merged$.$valid           // true when ALL forms are valid
+* merged$.$errors          // { personalInfo: {...}, address: {...} }
+* await merged$.$validate() // Validates all forms
+* ```
+*
+* @see {@link https://reglejs.dev/advanced-usage/merge-regles Documentation}
+*/
 function mergeRegles(regles, _scoped) {
 	const scoped = _scoped == null ? false : _scoped;
 	const $value = computed({
@@ -3628,6 +3817,35 @@ function createUseScopedRegleComposable(instances, customUseRegle) {
 	return { useScopedRegle: useScopedRegle$1 };
 }
 
+/**
+* Create a scoped validation system for collecting and validating multiple form instances.
+* Useful for dynamic forms, multi-step wizards, or component-based form architectures.
+*
+* @param options - Configuration options
+* @param options.customUseRegle - Custom useRegle instance with your global config
+* @param options.customStore - External ref to store collected instances
+* @param options.asRecord - If true, collect instances in a Record (requires `id` param in useScopedRegle)
+* @returns Object containing `useScopedRegle` and `useCollectScope` functions
+*
+* @example
+* ```ts
+* // scoped-config.ts
+* import { createScopedUseRegle } from '@regle/core';
+*
+* export const { useScopedRegle, useCollectScope } = createScopedUseRegle();
+*
+* // ChildComponent.vue
+* const { r$ } = useScopedRegle(state, rules, {
+*   namespace: 'myForm'
+* });
+*
+* // ParentComponent.vue
+* const { r$: collectedR$ } = useCollectScope('myForm');
+* await collectedR$.$validate(); // Validates all child forms
+* ```
+*
+* @see {@link https://reglejs.dev/advanced-usage/scoped-validation Documentation}
+*/
 function createScopedUseRegle(options) {
 	const instances = (options?.customStore ? () => {
 		if (options.customStore) {
@@ -3648,24 +3866,42 @@ function createScopedUseRegle(options) {
 const { useCollectScope, useScopedRegle } = createScopedUseRegle();
 
 /**
-* Declare variations of state that depends on one value
+* Create variant-based validation rules that depend on a discriminant field value.
+* Useful for union types where different fields are required based on a type discriminant.
+*
+* Note: Autocomplete may not fully work due to TypeScript limitations.
 *
-* Autocomplete may not work here because of https://github.com/microsoft/TypeScript/issues/49547
+* @param root - The reactive state object
+* @param discriminantKey - The key used to discriminate between variants
+* @param variants - Array of variant rule definitions using `literal` for type matching
+* @returns A computed ref containing the currently active variant rules
 *
+* @example
 * ```ts
-*  // ⚠️ Use getter syntax for your rules () => {} or a computed one
-*    const {r$} = useRegle(state, () => {
-*      const variant = createVariant(state, 'type', [
-*        {type: { literal: literal('EMAIL')}, email: { required, email }},
-*        {type: { literal: literal('GITHUB')}, username: { required }},
-*        {type: { required }},
-*      ]);
-*
-*      return {
-*        ...variant.value,
-*      };
-*    })
+* import { useRegle, createVariant } from '@regle/core';
+* import { required, email, literal } from '@regle/rules';
+*
+* const state = ref({
+*   type: 'EMAIL' as 'EMAIL' | 'GITHUB',
+*   email: '',
+*   username: ''
+* });
+*
+* // ⚠️ Use getter syntax for your rules
+* const { r$ } = useRegle(state, () => {
+*   const variant = createVariant(state, 'type', [
+*     { type: { literal: literal('EMAIL') }, email: { required, email } },
+*     { type: { literal: literal('GITHUB') }, username: { required } },
+*     { type: { required } }, // Default case
+*   ]);
+*
+*   return {
+*     ...variant.value,
+*   };
+* });
 * ```
+*
+* @see {@link https://reglejs.dev/advanced-usage/variants Documentation}
 */
 function createVariant(root, discriminantKey, variants) {
 	const watchableRoot = computed(() => toValue(root)[discriminantKey]);
@@ -3685,13 +3921,25 @@ function createVariant(root, discriminantKey, variants) {
 	});
 }
 /**
-* Narrow a nested variant field to a discriminated value
+* Type guard to narrow a variant field to a specific discriminated value.
+* Enables type-safe access to variant-specific fields.
+*
+* @param root - The Regle status object
+* @param discriminantKey - The key used to discriminate between variants
+* @param discriminantValue - The specific value to narrow to
+* @returns `true` if the discriminant matches, with TypeScript narrowing the type
 *
+* @example
 * ```ts
+* import { narrowVariant } from '@regle/core';
+*
 * if (narrowVariant(r$, 'type', 'EMAIL')) {
-*    r$.email.$value = 'foo';
+*   // TypeScript knows r$.email exists here
+*   r$.email.$value = 'user@example.com';
 * }
 * ```
+*
+* @see {@link https://reglejs.dev/advanced-usage/variants Documentation}
 */
 function narrowVariant(root, discriminantKey, discriminantValue) {
 	return !!root && isObject(root[discriminantKey]) && "$value" in root[discriminantKey] && root[discriminantKey]?.$value === discriminantValue;
@@ -3711,31 +3959,57 @@ function variantToRef(root, discriminantKey, discriminantValue, _options) {
 }
 
 /**
-* Helper method to wrap an raw rules object
+* Helper method to wrap a raw rules object with type inference.
+* Provides autocomplete and type-checking without processing.
 *
-* Similar to:
+* @param rules - The rules object to wrap
+* @returns The same rules object (passthrough)
 *
+* @example
 * ```ts
-* const rules = {...} satisfies RegleUnknownRulesTree
+* import { defineRules } from '@regle/core';
+* import { required, string } from '@regle/rules';
+*
+* // defineRules helps catch structure errors
+* const rules = defineRules({
+*   firstName: { required, string },
+*   lastName: { required, string }
+* });
 * ```
+*
+* @see {@link https://reglejs.dev/common-usage/standard-schema Documentation}
 */
 function defineRules(rules) {
 	return rules;
 }
 /**
-* Refine a raw rules object to set rules that depends on the state values.
+* Refine a rules object to add rules that depend on the state values.
+* Inspired by Zod's `refine`, this allows writing dynamic rules while maintaining type safety.
 *
-* @example
+* @param rules - The base rules object
+* @param refinement - A function that receives the typed state and returns additional rules
+* @returns A function that, given the state ref, returns the merged rules
 *
+* @example
 * ```ts
+* import { refineRules, type InferInput } from '@regle/core';
+* import { required, string, sameAs } from '@regle/rules';
+*
 * const rules = refineRules({
-*    password: { required, type: type<string>() },
-* }, (state) => {
-*    return {
-*        confirmPassword: { required, sameAs: sameAs(() => state.value.password)}
-*    }
-* })
+*   password: { required, string },
+* }, (state) => ({
+*   // state is typed based on the base rules
+*   confirmPassword: {
+*     required,
+*     sameAs: sameAs(() => state.value.password)
+*   }
+* }));
+*
+* type State = InferInput<typeof rules>;
+* // { password: string; confirmPassword: string }
 * ```
+*
+* @see {@link https://reglejs.dev/common-usage/standard-schema#refinerules Documentation}
 */
 function refineRules(rules, refinement) {
 	return (state) => merge({ ...rules }, refinement(state));