@regle/core 1.13.1 → 1.14.0-beta.1

package/dist/regle-core.d.ts

@@ -51,34 +51,68 @@ interface useRegleFn<TCustomRules extends Partial<ExtendedRulesDeclarations>, TS
   };
 }
 /**
- * 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 - 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
+ * @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
  *
+ * @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}
  */
 declare const useRegle: useRegleFn<Partial<ExtendedRulesDeclarations>, RegleShortcutDefinition<any>, {}, {}>;
 interface inferRulesFn<TCustomRules extends Partial<ExtendedRulesDeclarations>> {
   <TState$1 extends Record<string, any> | MaybeInput<PrimitiveTypes>, TRules$1 extends DeepExact<TRules$1, ReglePartialRuleTree<Unwrap<TState$1 extends Record<string, any> ? TState$1 : {}>, Partial<DefaultValidatorsTree> & TCustomRules>>, TDecl extends RegleRuleDecl<NonNullable<TState$1>, Partial<DefaultValidatorsTree> & TCustomRules>>(state: MaybeRef<TState$1> | DeepReactiveState<TState$1> | undefined, rulesFactory: TState$1 extends MaybeInput<PrimitiveTypes> ? TDecl : TState$1 extends Record<string, any> ? TRules$1 : {}): NonNullable<TState$1> extends PrimitiveTypes ? TDecl : TRules$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}
  */
 declare const inferRules: inferRulesFn<Partial<ExtendedRulesDeclarations>>;
 declare function useRootStorage({
@@ -127,21 +161,34 @@ interface useRulesFn<TCustomRules extends Partial<ExtendedRulesDeclarations>, TS
   };
 }
 /**
- * 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}
  */
 declare const useRules: useRulesFn<Partial<ExtendedRulesDeclarations>, RegleShortcutDefinition<any>>;
 /**
@@ -1290,35 +1337,57 @@ interface SuperCompatibleRegleCollectionStatus extends Omit<SuperCompatibleRegle
 type SuperCompatibleRegleCollectionErrors = $InternalRegleCollectionErrors;
 type SuperCompatibleRegleCollectionIssues = $InternalRegleCollectionIssues;
 /**
- * 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}
  */
 declare function createRule<TValue$1 extends any, TParams$1 extends any[], TReturn extends RegleRuleMetadataDefinition | Promise<RegleRuleMetadataDefinition>, TMetadata$1 extends RegleRuleMetadataDefinition = (TReturn extends Promise<infer M> ? M : TReturn), TAsync$1 extends boolean = (TReturn extends Promise<any> ? true : false)>(definition: RegleRuleInit<TValue$1, TParams$1, TReturn, TMetadata$1, TAsync$1>): InferRegleRule<TValue$1, TParams$1, TAsync$1, TMetadata$1>;
 /**
@@ -1327,16 +1396,43 @@ declare function createRule<TValue$1 extends any, TParams$1 extends any[], TRetu
  */
 declare function unwrapRuleParameters<TParams$1 extends any[]>(params: MaybeRefOrGetter[]): TParams$1;
 /**
- * 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
  *
- * It will return:
+ * @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';
+ *
+ * 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}
  */
 declare function defineRegleConfig<TShortcuts extends RegleShortcutDefinition<TCustomRules>, TCustomRules extends Partial<ExtendedRulesDeclarations>>({
   rules,
@@ -1352,12 +1448,31 @@ declare function defineRegleConfig<TShortcuts extends RegleShortcutDefinition<TC
   useRules: useRulesFn<TCustomRules, TShortcuts>;
 };
 /**
- * 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}
  */
 declare function extendRegleConfig<TRootCustomRules extends Partial<ExtendedRulesDeclarations>, TRootShortcuts extends RegleShortcutDefinition<{}>, TShortcuts extends RegleShortcutDefinition<Merge<TRootCustomRules, TCustomRules>>, TCustomRules extends Partial<ExtendedRulesDeclarations>>(regle: useRegleFn<TRootCustomRules, TRootShortcuts>, {
   rules,
@@ -1429,6 +1544,44 @@ type MergedReglesResult<TRegles extends Record<string, SuperCompatibleRegleRoot>
   errors: EmptyObject;
   issues: EmptyObject;
 };
+/**
+ * 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}
+ */
 declare function mergeRegles<TRegles extends Record<string, SuperCompatibleRegleRoot>, TScoped extends boolean = false>(regles: TRegles, _scoped?: TScoped): TScoped extends false ? MergedRegles<TRegles> : MergedScopedRegles;
 type useCollectScopeFn<TNamedScoped extends boolean = false> = TNamedScoped extends true ? <const TValue$1 extends Record<string, Record<string, any>>>(namespace?: MaybeRefOrGetter<string | string[]>) => {
   r$: MergedRegles<{ [K in keyof TValue$1]: RegleRoot<TValue$1[K]> & SuperCompatibleRegleRoot }>;
@@ -1460,6 +1613,35 @@ type CreateScopedUseRegleOptions<TCustomRegle extends useRegleFn<any, any>, TAsR
    */
   asRecord?: TAsRecord;
 };
+/**
+ * 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}
+ */
 declare function createScopedUseRegle<TCustomRegle extends useRegleFn<any, any> = useRegleFn<Partial<ExtendedRulesDeclarations>>, TAsRecord extends boolean = false, TReturnedRegle extends useRegleFn<any, any, any, any> = (TCustomRegle extends useRegleFn<infer A, infer B> ? useRegleFn<A, B, {
   dispose: () => void;
   register: () => void;
@@ -1479,34 +1661,64 @@ declare const useCollectScope: <TValue$1 extends Record<string, unknown>[] = Rec
     namespace?: vue0.MaybeRefOrGetter<string>;
   }>;
 /**
- * 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}
  */
 declare function createVariant<TForm extends Record<string, any>, TDiscriminant extends keyof JoinDiscriminatedUnions<TForm>, TVariants extends VariantTuple<JoinDiscriminatedUnions<TForm>, TDiscriminant>>(root: MaybeRefOrGetter<TForm> | DeepReactiveState<TForm>, discriminantKey: TDiscriminant, variants: [...TVariants]): Ref<TVariants[number]>;
 /**
- * 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}
  */
 declare function narrowVariant<TRoot extends {
   [x: string]: unknown;
@@ -1518,13 +1730,28 @@ declare function narrowVariant<TRoot extends {
   $value: infer V;
 } ? V : unknown)>(root: TRoot | undefined, discriminantKey: TKey$1, discriminantValue: TValue$1): root is NarrowVariant<TRoot, TKey$1, TValue$1>;
 /**
- * Narrow a nested variant root to a reactive reference
+ * Create a reactive reference to a narrowed variant.
+ * Useful in templates or when you need a stable ref to the narrowed type.
+ *
+ * @param root - The Regle status object (can be a ref)
+ * @param discriminantKey - The key used to discriminate between variants
+ * @param discriminantValue - The specific value to narrow to
+ * @param options - Optional `{ unsafeAssertion: true }` to assert the variant always exists
+ * @returns A ref containing the narrowed variant (or undefined if not matching)
  *
+ * @example
  * ```vue
  * <script setup lang="ts">
- *   const variantR$ = variantToRef(r$, 'type', 'EMAIL');
+ * import { variantToRef } from '@regle/core';
+ *
+ * const emailR$ = variantToRef(r$, 'type', 'EMAIL');
+ *
+ * // In template:
+ * // <input v-if="emailR$" v-model="emailR$.$value.email" />
  * </script>
  * ```
+ *
+ * @see {@link https://reglejs.dev/advanced-usage/variants Documentation}
  */
 declare function variantToRef<TRoot extends RegleStatus<{}, any, any>, const TKey$1 extends keyof TRoot['$fields'], const TValue$1 extends (LazyJoinDiscriminatedUnions<Exclude<TRoot['$fields'][TKey$1], RegleCollectionStatus<any, any, any> | RegleStatus<any, any, any> | NarrowVariantExtracts[keyof NarrowVariantExtracts]>> extends {
   $value: infer V;
@@ -1538,29 +1765,55 @@ declare function variantToRef<TRoot extends RegleStatus<{}, any, any>, const TKe
   $value: infer V;
 } ? V : unknown)>(root: MaybeRef<TRoot>, discriminantKey: TKey$1, discriminantValue: TValue$1): Ref<NarrowVariant<TRoot, TKey$1, TValue$1> | undefined>;
 /**
- * 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}
  */
 declare function defineRules<TRules$1 extends RegleUnknownRulesTree>(rules: TRules$1): TRules$1;
 /**
- * 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}
  */
 declare function refineRules<TRules$1 extends RegleUnknownRulesTree, TRefinement extends ReglePartialRuleTree<InferInput<TRules$1>> & RegleUnknownRulesTree>(rules: TRules$1, refinement: (state: Ref<InferInput<TRules$1>>) => TRefinement): (state: Ref<InferInput<TRules$1>>) => Merge<TRules$1, TRefinement>;
 declare const RegleVuePlugin: Plugin;