feat: rules first typing: InferInput type and refineRules helper (#112)

* working poc

* temp nor working refine

* handle variants, defineRules, refineRules

* chore: release v1.2.0-beta.1

* chore: test

* reworked some rules

* handle variants in refineRules, added tests

* finished unit tests

* infer state docs

Author: victorgarciaesgi

docs/.vitepress/config.ts

@@ -92,13 +92,17 @@ const AdvancedUsage: (DefaultTheme.NavItemWithLink | DefaultTheme.NavItemChildre
 
 const Typescript: (DefaultTheme.NavItemWithLink | DefaultTheme.NavItemChildren)[] = [
   {
-    text: 'Typing props',
+    text: 'Typing component props',
     link: '/typescript/typing-props',
   },
   {
-    text: 'Typing rules',
+    text: 'Rules definitions',
     link: '/typescript/typing-rules',
   },
+  {
+    text: 'Infer state from rules',
+    link: '/typescript/infer-state-from-rules',
+  },
 ];
 
 const Integrations: (DefaultTheme.NavItemWithLink | DefaultTheme.NavItemChildren)[] = [

docs/src/core-concepts/index.md

@@ -104,6 +104,13 @@ Regle provide a list of default rules that you can use from `@regle/rules`.
 
 You can find the [list of built-in rules here](/core-concepts/rules/built-in-rules)
 
+
+:::tip
+
+If you prefer to have a rules-first way of typing your state (like schema libraries), you can check [how to do it here](/typescript/infer-state-from-rules)
+
+:::
+
 <br/>
 
 

docs/src/core-concepts/rules/built-in-rules.md

@@ -107,6 +107,23 @@ const { r$ } = useRegle({ count: 0 }, {
 })
 ```
 
+## `boolean`
+
+Requires a value to be a native boolean type. Mainly used for typing.
+
+```ts twoslash
+import {useRegle, type InferInput} from '@regle/core';
+import {ref} from 'vue';
+// ---cut---
+import { boolean } from '@regle/rules';
+
+const rules = {
+  checkbox: { boolean },
+}
+
+const state = ref<InferInput<typeof rules>>({});
+```
+
 ## `checked`
 
 Requires a boolean value to be `true`. This is useful for checkbox inputs.
@@ -140,6 +157,24 @@ const { r$ } = useRegle({ bestLib: '' }, {
 })
 ```
 
+## `date`
+
+Requires a value to be a native Date constructor. Mainly used for typing.
+
+```ts twoslash
+import {useRegle, type InferInput} from '@regle/core';
+import {ref} from 'vue';
+
+// ---cut---
+import { date } from '@regle/rules';
+
+const rules = {
+  birthday: { date },
+}
+
+const state = ref<InferInput<typeof rules>>({});
+```
+
 
 ## `dateAfter`
 _**Params**_
@@ -516,6 +551,24 @@ const { r$ } = useRegle({ type: '' }, {
 })
 ```
 
+## `number`
+
+Requires a value to be a native number type. Mainly used for typing.
+
+```ts twoslash
+import {useRegle, type InferInput} from '@regle/core';
+import {ref} from 'vue';
+
+// ---cut---
+import { number } from '@regle/rules';
+
+const rules = {
+  count: { number },
+}
+
+const state = ref<InferInput<typeof rules>>({});
+```
+
 ## `numeric`
 
 Allows only numeric values (including numeric strings).
@@ -672,6 +725,41 @@ const { r$ } = useRegle({ bestLib: '' }, {
 })
 ```
 
+## `string`
+
+Requires a value to be a native string type. Mainly used for typing
+
+```ts twoslash
+import {useRegle, type InferInput} from '@regle/core';
+import {ref} from 'vue';
+// ---cut---
+import { string } from '@regle/rules';
+
+const rules = {
+  firstName: { string },
+}
+
+const state = ref<InferInput<typeof rules>>({});
+```
+
+## `type`
+
+Define the input type of a rule. No runtime validation.   
+Override any input type set by other rules.
+
+```ts twoslash
+import {useRegle, type InferInput} from '@regle/core';
+import {ref} from 'vue';
+// ---cut---
+import { type } from '@regle/rules';
+
+const rules = {
+  firstName: { type: type<string>() },
+}
+
+const state = ref<InferInput<typeof rules>>({});
+```
+
 
 ## `url`
 

docs/src/typescript/infer-state-from-rules.md

@@ -0,0 +1,76 @@
+---
+title: Infer state from rules
+description: Write your validations in the Zod way
+---
+
+# Infer state from rules
+
+Regle is state first, that means that you write your rules depending on the state structure, that's the model based way that Vuelidate introduced.
+
+With Schema libraries like Zod or Valibot, it's the contrary: the state type depends on the schema output.
+
+This mental model may differ to some people, the good new is Regle allow to work both ways!
+
+## `InferInput`
+
+`InferInput` is an utility type that can produce a object state from any rules object.
+
+It will try to extract the possible state type that a rule may have, prioritizing rules that have a strict input type.
+
+Some rules may have `unknown` type because it could apply to any value. To cover this, there is now type-helpers rules to help you type your state from the rules: `type`, `string`, `number`, `boolean`, `date`.
+
+:::info
+Some types like `numeric` will feel weird as it's typed `string | number`, it's normal as the rule can also validate numeric strings. You can enforce the type by applying `number` rule to it.
+:::
+
+```ts twoslash
+import {ref} from 'vue';
+// ---cut---
+import { defineRules, type InferInput} from '@regle/core';
+import { required, string, numeric, type } from '@regle/rules';
+
+/* defineRules is not required, but it helps you catch errors in structure */
+const rules = defineRules({
+  firstName: { required, string },
+  count: { numeric },
+  enforceType: { required, type: type<'FOO' | 'BAR'>()}
+})
+
+type State = InferInput<typeof rules>;
+//     ^?
+
+```
+
+<br/>
+<br/>
+<br/>
+
+## `refineRules`
+
+Regle is state first because in real world forms, rules can depend a state values.   
+This make it a problem for dynamic rules as it would make a cyclic type error when trying to use the state inside the rules.
+
+To cover this case and inspired by Zod's `refine`, Regle provides a `refineRules` helper to write dynamic rules that depend on the state, while making it possible to access a typed state.
+
+
+Anything returned by the rule refine function will override what's defined in the default rules.
+
+```ts twoslash
+import {ref} from 'vue';
+// ---cut---
+import { refineRules, type InferInput} from '@regle/core';
+import { required, string, sameAs } from '@regle/rules';
+
+const rules = refineRules({
+  password: { required, string },
+}, 
+ (state) => ({
+   confirmPassword: { required, sameAs: sameAs(() => state.value.password) }
+ })
+)
+
+type State = InferInput<typeof rules>;
+//     ^?
+```
+
+

package.json

@@ -1,6 +1,6 @@
 {
   "name": "regle",
-  "version": "1.1.4",
+  "version": "1.2.0-beta.1",
   "private": true,
   "description": "Headless model-based form validation library for Vue.js",
   "scripts": {

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@regle/core",
-  "version": "1.1.4",
+  "version": "1.2.0-beta.1",
   "description": "Headless form validation library for Vue 3",
   "scripts": {
     "typecheck": "tsc --noEmit",

packages/core/src/core/createVariant.ts

@@ -1,6 +1,7 @@
 import {
   computed,
   isRef,
+  nextTick,
   ref,
   toRef,
   toValue,
@@ -15,6 +16,7 @@ import type {
   DeepReactiveState,
   JoinDiscriminatedUnions,
   LazyJoinDiscriminatedUnions,
+  MaybeInput,
   RegleCollectionStatus,
   RegleFieldStatus,
   RegleStatus,
@@ -105,7 +107,10 @@ export function narrowVariant<
   root: TRoot,
   discriminantKey: TKey,
   discriminantValue: TValue
-): root is Extract<TRoot, { [K in TKey]: RegleFieldStatus<TValue, any, any> }> {
+): root is Extract<
+  TRoot,
+  { [K in TKey]: RegleFieldStatus<TValue, any, any> | RegleFieldStatus<MaybeInput<TValue>, any, any> }
+> {
   return (
     isObject(root[discriminantKey]) &&
     '$value' in root[discriminantKey] &&
@@ -141,14 +146,16 @@ export function variantToRef<
 
   watch(
     fromRoot,
-    () => {
+    async () => {
+      // avoid premature load of wrong rules resulting in a false positive
+      await nextTick();
       if (narrowVariant(fromRoot.value, discriminantKey, discriminantValue)) {
         returnedRef.value = fromRoot.value;
       } else {
         returnedRef.value = undefined;
       }
     },
-    { immediate: true }
+    { immediate: true, flush: 'pre' }
   );
 
   return returnedRef as any;

packages/core/src/core/defaultValidators.ts

@@ -1,4 +1,4 @@
-import type { EnumLike, Maybe, RegleRuleDefinition, RegleRuleWithParamsDefinition } from '../types';
+import type { EnumLike, Maybe, MaybeInput, RegleRuleDefinition, RegleRuleWithParamsDefinition } from '../types';
 
 export interface CommonComparisonOptions {
   /**
@@ -20,8 +20,10 @@ export type DefaultValidators = {
   alpha: RegleRuleWithParamsDefinition<string, [options?: CommonAlphaOptions | undefined]>;
   alphaNum: RegleRuleWithParamsDefinition<string | number, [options?: CommonAlphaOptions | undefined]>;
   between: RegleRuleWithParamsDefinition<number, [min: Maybe<number>, max: Maybe<number>]>;
+  boolean: RegleRuleDefinition<unknown, [], false, boolean, any, unknown>;
   checked: RegleRuleDefinition<boolean, [], false, boolean, boolean>;
   contains: RegleRuleWithParamsDefinition<string, [part: Maybe<string>], false, boolean>;
+  date: RegleRuleDefinition<unknown, [], false, boolean, MaybeInput<Date>, unknown>;
   dateAfter: RegleRuleWithParamsDefinition<
     string | Date,
     [after: Maybe<string | Date>, options?: CommonComparisonOptions],
@@ -86,11 +88,14 @@ export type DefaultValidators = {
   >;
   minValue: RegleRuleWithParamsDefinition<number, [count: number, options?: CommonComparisonOptions], false, boolean>;
   nativeEnum: RegleRuleDefinition<string | number, [enumLike: EnumLike], false, boolean, string | number>;
+  number: RegleRuleDefinition<unknown, [], false, boolean, any, unknown>;
   numeric: RegleRuleDefinition<string | number, [], false, boolean, string | number>;
   oneOf: RegleRuleDefinition<string | number, [options: (string | number)[]], false, boolean, string | number>;
   regex: RegleRuleWithParamsDefinition<string, [regexp: RegExp], false, boolean>;
   required: RegleRuleDefinition<unknown, []>;
   sameAs: RegleRuleWithParamsDefinition<unknown, [target: unknown, otherName?: string], false, boolean>;
+  string: RegleRuleDefinition<unknown, [], false, boolean, any, unknown>;
+  type: RegleRuleDefinition<unknown, [], false, boolean, unknown, unknown>;
   startsWith: RegleRuleWithParamsDefinition<string, [part: Maybe<string>], false, boolean>;
   url: RegleRuleDefinition<string, [], false, boolean, string>;
 };

packages/core/src/core/index.ts

@@ -5,3 +5,4 @@ export type { DefaultValidators, CommonComparisonOptions, CommonAlphaOptions } f
 export { mergeRegles, type MergedRegles } from './mergeRegles';
 export { createScopedUseRegle, useCollectScope, useScopedRegle } from './createScopedUseRegle';
 export { createVariant, narrowVariant, variantToRef } from './createVariant';
+export { defineRules, refineRules } from './refineRules';

packages/core/src/core/refineRules.ts

@@ -0,0 +1,42 @@
+import type { Merge } from 'type-fest';
+import { merge } from '../../../shared';
+import type { InferInput, ReglePartialRuleTree, RegleUnknownRulesTree } from '../types';
+import type { Ref } from 'vue';
+
+/**
+ * Helper method to wrap an raw rules object
+ *
+ * Similar to:
+ *
+ * ```ts
+ * const rules = {...} satisfies RegleUnknownRulesTree
+ * ```
+ */
+export function defineRules<TRules extends RegleUnknownRulesTree>(rules: TRules): TRules {
+  return rules;
+}
+
+/**
+ * Refine a raw rules object to set rules that depends on the state values.
+ *
+ * @example
+ *
+ * ```ts
+ * const rules = refineRules({
+ *    password: { required, type: type<string>() },
+ * }, (state) => {
+ *    return {
+ *        confirmPassword: { required, sameAs: sameAs(() => state.value.password)}
+ *    }
+ * })
+ * ```
+ */
+export function refineRules<
+  TRules extends RegleUnknownRulesTree,
+  TRefinement extends ReglePartialRuleTree<InferInput<TRules>> & RegleUnknownRulesTree,
+>(
+  rules: TRules,
+  refinement: (state: Ref<InferInput<TRules>>) => TRefinement
+): (state: Ref<InferInput<TRules>>) => Merge<TRules, TRefinement> {
+  return (state) => merge({ ...rules }, refinement(state)) as any;
+}