@whatsaaaa/form-builder-schema 0.5.0 → 0.6.0

package/README.md

@@ -129,7 +129,7 @@ const { build } = createSchemaBuilder({
 })
 ```
 
-The built-in `email` and `url` types use the `email` and `url` rules, so keep `formatRules` (or replace those types), or `createSchemaBuilder` throws a `TypeError`.
+The built-in `email` and `url` types use the `email` and `url` rules, so keep `formatRules` (or replace those types), or `createSchemaBuilder` throws a `TypeError`. `includeDefaultRules: false` leaves out the built-in form rules too; add them back with `formRules: defaultFormRules`.
 
 ### Listing rules
 
@@ -140,6 +140,43 @@ const { rulesForKind } = createSchemaBuilder()
 rulesForKind('file').map(([name, def]) => def.meta?.label) // ['Minimum size', …]
 ```
 
+## Form rules
+
+A form rule checks a field against other fields, such as a repeated password or a date range. Form rules go in `formRules`, next to `fields`, and each one names the `field` its error shows on:
+
+```json
+{
+  "version": "1",
+  "fields": [
+    { "name": "password", "type": "password", "required": true },
+    { "name": "password2", "type": "password", "required": true },
+    { "name": "start", "type": "date" },
+    { "name": "end", "type": "date" }
+  ],
+  "formRules": [
+    { "rule": "sameAs", "field": "password2", "other": "password", "message": "Passwords differ" },
+    {
+      "rule": "compare",
+      "field": "end",
+      "op": "gt",
+      "other": "start",
+      "message": "After the start"
+    }
+  ]
+}
+```
+
+| Rule            | Params                                     | Kinds                         | Passes when       |
+| --------------- | ------------------------------------------ | ----------------------------- | ----------------- |
+| `sameAs`        | `other`                                    | string, number, boolean, date | `field === other` |
+| `differentFrom` | `other`                                    | string, number, boolean, date | `field !== other` |
+| `compare`       | `op` (`lt`, `lte`, `gt` or `gte`), `other` | number, date                  | `field op other`  |
+
+- **Paths** name fields by their value: `'password2'`, `'address.zip'` for a field in a group, and `'lines.*.qty'` for a field in the items of an array. A rule on a path with `*` runs once per item, and its error shows on that item's field. A path it reads with `*` means the same item, so `{ "field": "lines.*.qty", "op": "lte", "other": "lines.*.stock" }` compares each line with itself.
+- **A form rule runs last**, after every field's own rules, and only when the fields it reads have no issues. So a password that is too short never also shows "Passwords differ". It never runs on an empty value either: make the fields required when they must be filled.
+- **`message` is required.** It goes through `resolveMessage` like every other message, with the rule's field in `ctx.field`.
+- The fields a rule reads must have the same kind: `compare` on a number and a date is `kind_mismatch`. A date with `output: 'date'` is compared by its time, so compare it with another date that has `output: 'date'`.
+
 ## Checking definitions
 
 `validate(json)` never throws. It returns every problem in the definition, in document order:
@@ -151,16 +188,17 @@ if (!result.success) {
 }
 ```
 
-`build(json)` runs the same checks and throws one `DefinitionError` with all of them. Issue codes are `invalid_shape`, `unsupported_version`, `unknown_key`, `unknown_type`, `missing_name`, `invalid_name`, `duplicate_name`, `invalid_props`, `invalid_default`, `unknown_rule`, `unknown_param`, `invalid_params` and `kind_mismatch`. An issue in a nested field has its full path, such as `['fields', 2, 'fields', 0, 'rules', 1]`.
+`build(json)` runs the same checks and throws one `DefinitionError` with all of them. Issue codes are `invalid_shape`, `unsupported_version`, `unknown_key`, `unknown_type`, `missing_name`, `invalid_name`, `duplicate_name`, `invalid_props`, `invalid_default`, `unknown_rule`, `unknown_param`, `invalid_params`, `kind_mismatch` and `unknown_field`. An issue in a nested field has its full path, such as `['fields', 2, 'fields', 0, 'rules', 1]`.
 
 - **Names** are one key of the value, so a name with `.`, `[` or `]` is `invalid_name`.
 - **Defaults** must pass the field's own schema, rules included, or they are `invalid_default`. An empty default, like `''`, counts as none.
+- **Form rules** report on `['formRules', 0]` and below. A `field` path that names no field with a value is `unknown_field` on `['formRules', 0, 'field']`, and a path the rule reads gets it on `['formRules', 0]`. When a field the rule reads has issues of its own, the rule adds none.
 
 Keys on a field must be reserved keys (`RESERVED_FIELD_KEYS`) or props of its type. Put renderer settings under `ui`, which is never checked.
 
 ## Extending
 
-`createSchemaBuilder({ kinds, fieldTypes, rules })` merges your entries over the defaults by key. The merged registries are returned as `kinds`, `fieldTypes` and `rules`.
+`createSchemaBuilder({ kinds, fieldTypes, rules, formRules })` merges your entries over the defaults by key. The merged registries are returned as `kinds`, `fieldTypes`, `rules` and `formRules`.
 
 ```ts
 const tags = defineFieldType({
@@ -198,6 +236,22 @@ const { build } = createSchemaBuilder({ fieldTypes: { tags }, rules: { even } })
   const schema = myType.schema?.(field, createBuildContext({ path: ['fields', 0] }))
   ```
 
+- A **form rule** lists the paths it reads besides `field`, and checks their values with a plain function. The builder checks that the fields exist and have one of `kinds`, and runs `check` only when none of them has an issue or is empty:
+
+  ```ts
+  const sameZip = defineFormRule({
+    params: v.object({ others: v.array(v.string()) }),
+    reads: (params) => params.others,
+    kinds: ['string'],
+    check: (values) => new Set(values).size === 1, // the value of `field`, then the others
+    meta: { label: 'Same ZIP', category: 'comparison' },
+  })
+
+  const { build } = createSchemaBuilder({ formRules: { sameZip } })
+  ```
+
+  `sameKind: true` requires every field it reads to have the same kind. `rule`, `field` and `message` are reserved (`RESERVED_FORM_RULE_KEYS`), so params can't use them.
+
 - Mistakes in the registry, such as an unknown kind or a reserved props key, throw a `TypeError` from `createSchemaBuilder`.
 
 ## Initial input and walking fields

package/dist/index.d.ts

@@ -12,6 +12,8 @@ type ValueKind = 'string' | 'number' | 'boolean' | 'date' | 'array' | 'file' | '
 interface JsonForm {
   version: '1';
   fields: readonly JsonField[];
+  /** Rules that check a field against other fields. They run after every field's own rules. */
+  formRules?: readonly JsonFormRule[];
 }
 interface JsonField {
   name?: string;
@@ -34,10 +36,17 @@ interface JsonRule {
   message?: string;
   [param: string]: unknown;
 }
+interface JsonFormRule {
+  rule: string;
+  /** Where the error shows, as a dot path: `'password2'`, `'address.zip'` or `'lines.*.qty'`. */
+  field: string;
+  message: string;
+  [param: string]: unknown;
+}
 /** Where something is in a definition, e.g. `['fields', 0, 'rules', 1]`. */
 type DefinitionPath = readonly (string | number)[];
 /** Public API: adding a code is a minor change, renaming one is breaking. */
-type DefinitionIssueCode = 'invalid_shape' | 'unsupported_version' | 'unknown_key' | 'unknown_type' | 'missing_name' | 'invalid_name' | 'duplicate_name' | 'invalid_props' | 'invalid_default' | 'unknown_rule' | 'unknown_param' | 'invalid_params' | 'kind_mismatch';
+type DefinitionIssueCode = 'invalid_shape' | 'unsupported_version' | 'unknown_key' | 'unknown_type' | 'missing_name' | 'invalid_name' | 'duplicate_name' | 'invalid_props' | 'invalid_default' | 'unknown_rule' | 'unknown_param' | 'invalid_params' | 'kind_mismatch' | 'unknown_field';
 interface DefinitionIssue {
   code: DefinitionIssueCode;
   path: DefinitionPath;
@@ -150,6 +159,29 @@ interface RuleDef<TParams extends AnyObjectSchema = AnyObjectSchema> {
   /** Method syntax keeps `create` bivariant, so specific rules fit in a `Record<string, RuleDef>`. */
   create(params: v.InferOutput<TParams>, message?: string): AnyAction;
 }
+/**
+ * A rule that checks a field against other fields, e.g. that two passwords match. It goes in the
+ * definition's `formRules`, and its error shows on the field named by `field`.
+ */
+interface FormRuleDef<TParams extends AnyObjectSchema = AnyObjectSchema> {
+  /** Its params, next to `rule`, `field` and `message` in the definition. Unknown ones fail. */
+  params?: TParams;
+  /**
+   * The paths the rule reads besides `field`, e.g. `[params.other]`, so the builder can check
+   * that those fields exist. Method syntax keeps it bivariant, like `check()`.
+   */
+  reads(params: v.InferOutput<TParams>): readonly string[];
+  /** The kinds the fields it reads may have. Any kind when omitted. */
+  kinds?: readonly ValueKind[];
+  /** True when every field it reads must have the same kind, e.g. to compare them. */
+  sameKind?: boolean;
+  /**
+   * True when the values pass. `values` holds the value of `field`, then the values of the paths
+   * from `reads()`, in that order. It only runs when all of them are valid and none is empty.
+   */
+  check(values: readonly unknown[], params: v.InferOutput<TParams>): boolean;
+  meta?: RuleMeta;
+}
 interface MessageContext {
   field: JsonField;
   rule?: string;
@@ -161,6 +193,8 @@ interface SchemaBuilderOptions {
   kinds?: Record<string, KindDef>;
   fieldTypes?: Record<string, FieldTypeDef>;
   rules?: Record<string, RuleDef>;
+  formRules?: Record<string, FormRuleDef>;
+  /** With false, only your own rules and form rules are registered. Defaults to true. */
   includeDefaultRules?: boolean;
   messages?: {
     required?: string;
@@ -178,6 +212,7 @@ export declare function createSchemaBuilder(options?: SchemaBuilderOptions): {
   kinds: Readonly<Record<string, KindDef>>;
   fieldTypes: Readonly<Record<string, FieldTypeDef<AnyObjectSchema>>>;
   rules: Readonly<Record<string, RuleDef<AnyObjectSchema>>>;
+  formRules: Readonly<Record<string, FormRuleDef<AnyObjectSchema>>>;
 };
 /**
  * Formisch's `initialInput` for a definition: each field's `default`, nested the way the value
@@ -598,6 +633,7 @@ export declare const defaultRules: {
     readonly value: import("valibot").SchemaWithPipe<readonly [import("valibot").NumberSchema<undefined>, import("valibot").IntegerAction<number, undefined>, import("valibot").MinValueAction<number, 0, undefined>]>;
   }, undefined>>;
 };
+export declare const defineFormRule: <T extends AnyObjectSchema>(def: FormRuleDef<T>) => FormRuleDef<T>;
 export declare const defineRule: <T extends AnyObjectSchema>(def: RuleDef<T>) => RuleDef<T>;
 /** Size and type of a File or Blob. */
 export declare const fileRules: {
@@ -650,6 +686,19 @@ export declare const formatRules: {
     readonly types: v.SchemaWithPipe<readonly [v.ArraySchema<v.PicklistSchema<readonly ["md4", "md5", "sha1", "sha256", "sha384", "sha512", "ripemd128", "ripemd160", "tiger128", "tiger160", "tiger192", "crc32", "crc32b", "adler32"], undefined>, undefined>, v.MinLengthAction<("md4" | "md5" | "sha1" | "sha256" | "sha384" | "sha512" | "ripemd128" | "ripemd160" | "tiger128" | "tiger160" | "tiger192" | "crc32" | "crc32b" | "adler32")[], 1, "Pick at least one hash type">]>;
   }, undefined>>;
 };
+/** Every built-in form rule. */
+export declare const defaultFormRules: {
+  sameAs: FormRuleDef<v.ObjectSchema<{
+    readonly other: v.StringSchema<undefined>;
+  }, undefined>>;
+  differentFrom: FormRuleDef<v.ObjectSchema<{
+    readonly other: v.StringSchema<undefined>;
+  }, undefined>>;
+  compare: FormRuleDef<v.ObjectSchema<{
+    readonly op: v.PicklistSchema<["lt", "lte", "gt", "gte"], undefined>;
+    readonly other: v.StringSchema<undefined>;
+  }, undefined>>;
+};
 /** Characters of a string, or items of an array */
 export declare const lengthRules: {
   length: RuleDef<v.ObjectSchema<{
@@ -744,5 +793,9 @@ export declare const RESERVED_FIELD_KEYS: readonly ["name", "type", "label", "de
  * Rule keys this package owns. A rule's params can't use them.
  */
 export declare const RESERVED_RULE_KEYS: readonly ["rule", "message"];
-export type { AnyAction, AnyObjectSchema, AnySchema, BuildContext, DefinitionIssue, DefinitionIssueCode, DefinitionPath, FieldTypeDef, FieldWithProps, JsonField, JsonForm, JsonRule, KindDef, KindOf, MessageContext, RuleCategory, RuleDef, RuleMeta, RuleStage, SchemaBuilderOptions, ValidateResult, ValueKind, WalkedField };
+/**
+ * Form rule keys this package owns. A form rule's params can't use them.
+ */
+export declare const RESERVED_FORM_RULE_KEYS: readonly ["rule", "field", "message"];
+export type { AnyAction, AnyObjectSchema, AnySchema, BuildContext, DefinitionIssue, DefinitionIssueCode, DefinitionPath, FieldTypeDef, FieldWithProps, FormRuleDef, JsonField, JsonForm, JsonFormRule, JsonRule, KindDef, KindOf, MessageContext, RuleCategory, RuleDef, RuleMeta, RuleStage, SchemaBuilderOptions, ValidateResult, ValueKind, WalkedField };
 //# sourceMappingURL=index.d.ts.map