@regle/schemas 1.13.1 → 1.14.0

package/dist/regle-schemas.d.ts

@@ -150,62 +150,134 @@ interface useRegleSchemaFn<TShortcuts extends RegleShortcutDefinition<any> = nev
   <TSchema extends StandardSchemaV1, TState extends StandardSchemaV1.InferInput<TSchema> | undefined>(...params: [state: MaybeRef<DeepPartial<NoInferLegacy<TState>>> | DeepReactiveState<DeepPartial<NoInferLegacy<TState>>>, rulesFactory: MaybeRef<TSchema>, ...(HaveAnyRequiredProps<useRegleSchemaFnOptions<TAdditionalOptions>> extends true ? [options: useRegleSchemaFnOptions<TAdditionalOptions>] : [options?: useRegleSchemaFnOptions<TAdditionalOptions>])]): NonNullable<TState> extends PrimitiveTypes ? RegleSingleFieldSchema<NonNullable<TState>, TSchema, TShortcuts, TAdditionalReturnProperties> : RegleSchema<UnwrapNestedRefs<NonNullable<TState>>, TSchema, TShortcuts, TAdditionalReturnProperties>;
 }
 /**
- * useRegle serves as the foundation for validation logic.
+ * `useRegleSchema` enables validation using Standard Schema compatible libraries
+ * like Zod, Valibot, or ArkType.
  *
- * 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 schema - 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 schema - A Standard Schema compliant schema (Zod, Valibot, ArkType, etc.)
+ * @param modifiers - Optional configuration to customize regle behavior
+ * @returns An object containing `r$` - the reactive validation state
  *
+ * @example
  * ```ts
  * import { useRegleSchema } from '@regle/schemas';
  * import * as v from 'valibot';
  *
- * const { r$ } = useRegleSchema({ name: '' }, v.object({
- *   name: v.pipe(v.string(), v.minLength(3))
- * }))
+ * // With Valibot
+ * const { r$ } = useRegleSchema(
+ *   { name: '', email: '' },
+ *   v.object({
+ *     name: v.pipe(v.string(), v.minLength(3)),
+ *     email: v.pipe(v.string(), v.email())
+ *   })
+ * );
+ *
+ * // With Zod
+ * import { z } from 'zod';
+ *
+ * const { r$ } = useRegleSchema(
+ *   { name: '' },
+ *   z.object({
+ *     name: z.string().min(3)
+ *   })
+ * );
+ *
+ * // Access validation state
+ * r$.$valid        // Whether all validations pass
+ * r$.$value        // The current form values
+ * r$.name.$errors  // Errors for the name field
  * ```
- * Docs: {@link https://reglejs.dev/integrations/schemas-libraries}
+ *
+ * @see {@link https://reglejs.dev/integrations/schemas-libraries Documentation}
  */
 declare const useRegleSchema: useRegleSchemaFn<RegleShortcutDefinition<any>, {}, {}>;
 /**
+ * Force a schema validation to re-run when specified dependencies change.
+ * Useful when your schema depends on reactive values that aren't automatically tracked.
+ *
+ * @param schema - The Standard Schema to wrap
+ * @param _depsArray - Array of reactive dependencies (their values will trigger re-validation)
+ * @returns The same schema (passthrough)
  *
- * Force dependency on any RPC schema
+ * @example
  * ```ts
- * const foo = ref('');
+ * import { withDeps, useRegleSchema } from '@regle/schemas';
+ * import * as v from 'valibot';
+ *
+ * const compareValue = ref('');
  *
  * const schema = computed(() => v.object({
- *    name: withDeps(
- *       v.pipe(v.string(), v.check((value) => value === foo.value)),
- *       [foo.value]
- *    )
- * }))
+ *   name: withDeps(
+ *     v.pipe(
+ *       v.string(),
+ *       v.check((value) => value === compareValue.value)
+ *     ),
+ *     [compareValue.value] // Re-validate when this changes
+ *   )
+ * }));
  *
- * useRegleSchema({name: ''}, schema)
+ * const { r$ } = useRegleSchema({ name: '' }, schema);
  * ```
+ *
+ * @see {@link https://reglejs.dev/integrations/schemas-libraries Documentation}
  */
 declare function withDeps<TSchema extends StandardSchemaV1, TParams extends unknown[] = []>(schema: TSchema, _depsArray: [...TParams]): TSchema;
 interface inferSchemaFn {
   <TSchema extends StandardSchemaV1, TState extends StandardSchemaV1.InferInput<TSchema> | undefined>(state: MaybeRef<DeepPartial<TState>> | DeepReactiveState<DeepPartial<TState>>, rulesFactory: MaybeRef<TSchema>): NoInferLegacy<TSchema>;
 }
 /**
- * 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 schema.
+ * Returns the schema without any processing - useful with computed schemas.
  *
  * @param state - The state reference
- * @param schema - Your schema
+ * @param schema - Your Standard Schema (Zod, Valibot, ArkType, etc.)
+ * @returns The schema (passthrough)
+ *
+ * @example
+ * ```ts
+ * import { inferSchema, useRegleSchema } from '@regle/schemas';
+ * import { z } from 'zod';
+ *
+ * const state = ref({ name: '' });
+ *
+ * // inferSchema preserves TypeScript autocompletion
+ * const schema = computed(() => {
+ *   return inferSchema(state, z.object({
+ *     name: z.string().min(2)
+ *   }));
+ * });
+ *
+ * const { r$ } = useRegleSchema(state, schema);
+ * ```
+ *
+ * @see {@link https://reglejs.dev/integrations/schemas-libraries Documentation}
  */
 declare const inferSchema: inferSchemaFn;
 /**
- * Define a global regle configuration, where you can:
- * - Define global modifiers
- * - Define shortcuts
+ * Define a global configuration for `useRegleSchema`.
+ *
+ * Features:
+ * - Define global modifiers (lazy, rewardEarly, etc.)
+ * - Define shortcuts for common validation patterns
+ *
+ * @param options - Configuration options
+ * @param options.modifiers - Global behavior modifiers
+ * @param options.shortcuts - Reusable validation shortcuts
+ * @returns Object containing typed `useRegleSchema` and `inferSchema` functions
+ *
+ * @example
+ * ```ts
+ * import { defineRegleSchemaConfig } from '@regle/schemas';
  *
- * It will return:
+ * export const { useRegleSchema, inferSchema } = defineRegleSchemaConfig({
+ *   modifiers: {
+ *     lazy: true,
+ *     rewardEarly: true
+ *   }
+ * });
+ * ```
  *
- * - a `useRegleSchema` composable that can typecheck your custom rules
- * - an `inferSchema` helper that can typecheck your custom rules
+ * @see {@link https://reglejs.dev/integrations/schemas-libraries Documentation}
  */
 declare function defineRegleSchemaConfig<TShortcuts extends RegleShortcutDefinition>({
   modifiers,
@@ -226,6 +298,29 @@ type CreateScopedUseRegleSchemaOptions<TCustomRegle extends useRegleSchemaFn<any
 declare const useCollectSchemaScope: <TValue$1 extends Record<string, unknown>[] = Record<string, unknown>[]>(namespace?: vue0.MaybeRefOrGetter<string | string[]>) => {
     r$: _regle_core0.MergedScopedRegles<TValue$1>;
   }, useScopedRegleSchema: useRegleSchemaFn<_regle_core0.RegleShortcutDefinition<any>, {}, {}>;
+/**
+ * Create a scoped validation system for schema-based validation.
+ * Similar to `createScopedUseRegle` but for use with Standard Schema libraries.
+ *
+ * @param options - Configuration options
+ * @param options.customUseRegle - Custom useRegleSchema 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)
+ * @returns Object containing `useScopedRegle` and `useCollectScope` functions
+ *
+ * @example
+ * ```ts
+ * import { createScopedUseRegleSchema, defineRegleSchemaConfig } from '@regle/schemas';
+ *
+ * const { useRegleSchema } = defineRegleSchemaConfig({...});
+ *
+ * export const { useScopedRegle, useCollectScope } = createScopedUseRegleSchema({
+ *   customUseRegle: useRegleSchema
+ * });
+ * ```
+ *
+ * @see {@link https://reglejs.dev/advanced-usage/scoped-validation Documentation}
+ */
 declare const createScopedUseRegleSchema: <TCustomRegle extends useRegleSchemaFn = useRegleSchemaFn, TAsRecord extends boolean = false, TReturnedRegle extends useRegleSchemaFn<any, any, any> = (TCustomRegle extends useRegleSchemaFn<infer S> ? useRegleSchemaFn<S, {
   dispose: () => void;
   register: () => void;

package/dist/regle-schemas.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;
@@ -290,41 +312,77 @@ function createUseRegleSchemaComposable(options, shortcuts) {
 	return useRegleSchema$1;
 }
 /**
-* useRegle serves as the foundation for validation logic.
-*
-* It accepts the following inputs:
+* `useRegleSchema` enables validation using Standard Schema compatible libraries
+* like Zod, Valibot, or ArkType.
 *
-* @param state - This can be a plain object, a ref, a reactive object, or a structure containing nested refs.
-* @param schema - 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 schema - A Standard Schema compliant schema (Zod, Valibot, ArkType, etc.)
+* @param modifiers - Optional configuration to customize regle behavior
+* @returns An object containing `r$` - the reactive validation state
 *
+* @example
 * ```ts
 * import { useRegleSchema } from '@regle/schemas';
 * import * as v from 'valibot';
 *
-* const { r$ } = useRegleSchema({ name: '' }, v.object({
-*   name: v.pipe(v.string(), v.minLength(3))
-* }))
+* // With Valibot
+* const { r$ } = useRegleSchema(
+*   { name: '', email: '' },
+*   v.object({
+*     name: v.pipe(v.string(), v.minLength(3)),
+*     email: v.pipe(v.string(), v.email())
+*   })
+* );
+*
+* // With Zod
+* import { z } from 'zod';
+*
+* const { r$ } = useRegleSchema(
+*   { name: '' },
+*   z.object({
+*     name: z.string().min(3)
+*   })
+* );
+*
+* // Access validation state
+* r$.$valid        // Whether all validations pass
+* r$.$value        // The current form values
+* r$.name.$errors  // Errors for the name field
 * ```
-* Docs: {@link https://reglejs.dev/integrations/schemas-libraries}
+*
+* @see {@link https://reglejs.dev/integrations/schemas-libraries Documentation}
 */
 const useRegleSchema = createUseRegleSchemaComposable();
 
 /**
+* Force a schema validation to re-run when specified dependencies change.
+* Useful when your schema depends on reactive values that aren't automatically tracked.
+*
+* @param schema - The Standard Schema to wrap
+* @param _depsArray - Array of reactive dependencies (their values will trigger re-validation)
+* @returns The same schema (passthrough)
 *
-* Force dependency on any RPC schema
+* @example
 * ```ts
-* const foo = ref('');
+* import { withDeps, useRegleSchema } from '@regle/schemas';
+* import * as v from 'valibot';
+*
+* const compareValue = ref('');
 *
 * const schema = computed(() => v.object({
-*    name: withDeps(
-*       v.pipe(v.string(), v.check((value) => value === foo.value)),
-*       [foo.value]
-*    )
-* }))
+*   name: withDeps(
+*     v.pipe(
+*       v.string(),
+*       v.check((value) => value === compareValue.value)
+*     ),
+*     [compareValue.value] // Re-validate when this changes
+*   )
+* }));
 *
-* useRegleSchema({name: ''}, schema)
+* const { r$ } = useRegleSchema({ name: '' }, schema);
 * ```
+*
+* @see {@link https://reglejs.dev/integrations/schemas-libraries Documentation}
 */
 function withDeps(schema, _depsArray) {
 	return schema;
@@ -337,23 +395,59 @@ function createInferSchemaHelper() {
 	return inferSchema$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 schema.
+* Returns the schema without any processing - useful with computed schemas.
 *
 * @param state - The state reference
-* @param schema - Your schema
+* @param schema - Your Standard Schema (Zod, Valibot, ArkType, etc.)
+* @returns The schema (passthrough)
+*
+* @example
+* ```ts
+* import { inferSchema, useRegleSchema } from '@regle/schemas';
+* import { z } from 'zod';
+*
+* const state = ref({ name: '' });
+*
+* // inferSchema preserves TypeScript autocompletion
+* const schema = computed(() => {
+*   return inferSchema(state, z.object({
+*     name: z.string().min(2)
+*   }));
+* });
+*
+* const { r$ } = useRegleSchema(state, schema);
+* ```
+*
+* @see {@link https://reglejs.dev/integrations/schemas-libraries Documentation}
 */
 const inferSchema = createInferSchemaHelper();
 
 /**
-* Define a global regle configuration, where you can:
-* - Define global modifiers
-* - Define shortcuts
+* Define a global configuration for `useRegleSchema`.
+*
+* Features:
+* - Define global modifiers (lazy, rewardEarly, etc.)
+* - Define shortcuts for common validation patterns
 *
-* It will return:
+* @param options - Configuration options
+* @param options.modifiers - Global behavior modifiers
+* @param options.shortcuts - Reusable validation shortcuts
+* @returns Object containing typed `useRegleSchema` and `inferSchema` functions
+*
+* @example
+* ```ts
+* import { defineRegleSchemaConfig } from '@regle/schemas';
+*
+* export const { useRegleSchema, inferSchema } = defineRegleSchemaConfig({
+*   modifiers: {
+*     lazy: true,
+*     rewardEarly: true
+*   }
+* });
+* ```
 *
-* - a `useRegleSchema` composable that can typecheck your custom rules
-* - an `inferSchema` helper that can typecheck your custom rules
+* @see {@link https://reglejs.dev/integrations/schemas-libraries Documentation}
 */
 function defineRegleSchemaConfig({ modifiers, shortcuts }) {
 	return {
@@ -363,6 +457,29 @@ function defineRegleSchemaConfig({ modifiers, shortcuts }) {
 }
 
 const { useCollectScope: useCollectSchemaScope, useScopedRegle: useScopedRegleSchema } = createScopedUseRegle({ customUseRegle: useRegleSchema });
+/**
+* Create a scoped validation system for schema-based validation.
+* Similar to `createScopedUseRegle` but for use with Standard Schema libraries.
+*
+* @param options - Configuration options
+* @param options.customUseRegle - Custom useRegleSchema 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)
+* @returns Object containing `useScopedRegle` and `useCollectScope` functions
+*
+* @example
+* ```ts
+* import { createScopedUseRegleSchema, defineRegleSchemaConfig } from '@regle/schemas';
+*
+* const { useRegleSchema } = defineRegleSchemaConfig({...});
+*
+* export const { useScopedRegle, useCollectScope } = createScopedUseRegleSchema({
+*   customUseRegle: useRegleSchema
+* });
+* ```
+*
+* @see {@link https://reglejs.dev/advanced-usage/scoped-validation Documentation}
+*/
 const createScopedUseRegleSchema = (options) => {
 	const { customStore, customUseRegle = useRegleSchema, asRecord = false } = options ?? {};
 	return createScopedUseRegle({

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@regle/schemas",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "description": "Schemas adapter for Regle",
   "dependencies": {
     "@standard-schema/spec": "1.0.0",
     "type-fest": "5.2.0",
-    "@regle/core": "1.13.1",
-    "@regle/rules": "1.13.1"
+    "@regle/rules": "1.14.0",
+    "@regle/core": "1.14.0"
   },
   "peerDependencies": {
     "valibot": "^1.0.0",