Readme and options updated.

Author: ciscoheat

CHANGELOG.md

@@ -5,24 +5,25 @@ Headlines: Added, Changed, Deprecated, Removed, Fixed, Security
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.8.0] - 2023-04-21
+## [0.8.0] - 2023-04-22
 
 ### Changed
 
-- Client-side validators now works in realtime, based on "reward early, validate late"; If no error, validate on `focusout`. If error exists, validate on `input`.
+- Client-side validators now works in realtime, based on "reward early, validate late": If no field error, validate on `blur`. If field error exists, validate on `input`.
 
 ### Removed
 
 - The rarely used `update` function is removed. Use `form` instead, which now has an option for not tainting the affected fields.
 
 ### Fixed
 
-- `tainted` wasn't updated correctly for array data.
+- `tainted` wasn't updated properly for array data.
 - `dataType: 'json'` now handles large (+1Mb) payloads.
 
 ### Added
 
 - Added `validate` to `superForm`, which can be used to validate any field, at any time.
+- Client-side validation can be customized with the `validationMethod: 'auto' | 'oninput' | 'onblur' | 'submit-only'` option.
 - The option `{ taint: boolean | 'untaint' | 'untaint-all' }` has been added to `form.set` and `form.update`.
 - The `resetForm` option can now take an `async () => boolean` function to determine whether the form should be resetted or not.
 

README.md

@@ -21,13 +21,13 @@
 
 <br/>
 
-Superforms is a SvelteKit library that helps you with **server-side validation** and **client-side display** of forms.
+Making SvelteKit **validation** and **display** of forms easier than ever!
 
 # Feature list
 
 - Merging `PageData` and `ActionData` consistently - Forget about which one to use and how, just focus on your data.
 - Server-side data validation using [Zod](https://zod.dev), with output that can be used directly on the client.
-- [Auto-centering and auto-focusing](https://superforms.vercel.app/concepts/error-handling) on invalid form fields.
+- [Auto-centering and auto-focusing](https://superforms.vercel.app/concepts/error-handling#usage-client) on invalid form fields.
 - [Tainted form detection](https://superforms.vercel.app/concepts/tainted), prevents the user from losing data if navigating away from an unsaved form.
 - No JS required as default, but full support for [progressive enhancement](https://superforms.vercel.app/concepts/enhance).
 - Automatically coerces the string data from `FormData` into correct types.
@@ -61,4 +61,4 @@ You can also watch this excellent introduction video to see what's possible: htt
 
 # Feedback wanted!
 
-Ideas, feedback, bug reports, PR:s, etc, are very welcome as a Github [issue](https://github.com/ciscoheat/sveltekit-superforms/issues) or [discussion](https://github.com/ciscoheat/sveltekit-superforms/discussions)!
+Ideas, general feedback, bug reports, PR:s, etc, are very welcome as a Github [issue](https://github.com/ciscoheat/sveltekit-superforms/issues), [discussion](https://github.com/ciscoheat/sveltekit-superforms/discussions), or on the [Discord server](https://discord.gg/AptebvVuhB)!

src/lib/client/index.ts

@@ -126,6 +126,7 @@ export type FormOptions<T extends ZodValidation<AnyZodObject>, M> = Partial<{
     | ZodEffects<ZodEffects<ZodEffects<T>>>
     | ZodEffects<ZodEffects<ZodEffects<ZodEffects<T>>>>
     | ZodEffects<ZodEffects<ZodEffects<ZodEffects<ZodEffects<T>>>>>;
+  validationMethod: 'auto' | 'oninput' | 'onblur' | 'submit-only';
   defaultValidator: 'keep' | 'clear';
   clearOnSubmit: 'errors' | 'message' | 'errors-and-message' | 'none';
   delayMs: number;
@@ -182,7 +183,8 @@ const defaultFormOptions = {
   timeoutMs: 8000,
   multipleSubmits: 'prevent',
   validation: undefined,
-  SPA: undefined
+  SPA: undefined,
+  validateMethod: 'auto'
 };
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -202,9 +204,12 @@ type SuperFormEventList<T extends AnyZodObject, M> = {
   >[];
 };
 
+type TaintOption = boolean | 'untaint' | 'untaint-all';
+
 type ValidateOptions<V> = Partial<{
   value: V;
-  update: boolean;
+  update: boolean | 'errors' | 'value';
+  taint: TaintOption;
   errors: string | string[];
 }>;
 
@@ -224,12 +229,12 @@ export type SuperForm<T extends ZodValidation<AnyZodObject>, M = any> = {
     set(
       this: void,
       value: z.infer<T>,
-      options?: { taint?: boolean | 'untaint' | 'untaint-all' }
+      options?: { taint?: TaintOption }
     ): void;
     update(
       this: void,
       updater: Updater<z.infer<T>>,
-      options?: { taint?: boolean | 'untaint' | 'untaint-all' }
+      options?: { taint?: TaintOption }
     ): void;
   };
   formId: Writable<string | undefined>;
@@ -414,28 +419,23 @@ export function superForm<
   let taintedFormState: typeof initialForm.data = clone(initialForm.data);
 
   const _formData = writable(storeForm.data);
-  // TODO: Is get(Submitting) really needed?
   const Form = {
     subscribe: _formData.subscribe,
     set: (
       value: Parameters<typeof _formData.set>[0],
-      options: { taint?: boolean | 'untaint' | 'untaint-all' } = {}
+      options: { taint?: TaintOption } = {}
     ) => {
-      //if (!get(Submitting)) {
       checkTainted(value, taintedFormState, options.taint ?? true);
-      //}
       taintedFormState = clone(value);
       return _formData.set(value);
     },
     update: (
       updater: Parameters<typeof _formData.update>[0],
-      options: { taint?: boolean | 'untaint' | 'untaint-all' } = {}
+      options: { taint?: TaintOption } = {}
     ) => {
       return _formData.update((value) => {
         const output = updater(value);
-        //if (!get(Submitting)) {
         checkTainted(output, taintedFormState, options.taint ?? true);
-        //}
         taintedFormState = clone(value);
         return output;
       });
@@ -447,7 +447,7 @@ export function superForm<
   function checkTainted(
     newObj: unknown,
     compareAgainst: unknown,
-    options: boolean | 'untaint' | 'untaint-all'
+    options: TaintOption
   ) {
     if (options === false) {
       return;
@@ -764,7 +764,7 @@ export function superForm<
         (Array.isArray(path) ? path : [path]) as string[],
         options.validators,
         options.defaultValidator,
-        get(Form),
+        Form,
         Errors,
         opts
       );
@@ -837,14 +837,17 @@ async function validateField<T extends AnyZodObject, M>(
   path: string[],
   validators: FormOptions<T, M>['validators'],
   defaultValidator: FormOptions<T, M>['defaultValidator'],
-  data: z.infer<T>,
+  data: SuperForm<T, M>['form'],
   errors: SuperForm<T, M>['errors'],
   options: ValidateOptions<unknown> = {}
 ): Promise<string[] | undefined> {
+  if (options.update === undefined) options.update = true;
+  if (options.taint === undefined) options.taint = false;
+
   function setError(errorMsgs: null | undefined | string | string[]) {
     if (typeof errorMsgs === 'string') errorMsgs = [errorMsgs];
 
-    if (options.update !== false) {
+    if (options.update === true || options.update == 'errors') {
       errors.update((errors) => {
         const error = traversePath(
           errors,
@@ -879,19 +882,29 @@ async function validateField<T extends AnyZodObject, M>(
   }
 
   let value = options.value;
+  const currentData = get(data);
 
-  if (value === undefined) {
+  if (!('value' in options)) {
     const dataToValidate = traversePath(
-      data,
-      path as FieldPath<typeof data>
+      currentData,
+      path as FieldPath<typeof currentData>
     );
 
     if (!dataToValidate) {
       throw new SuperFormError('Validation data not found: ' + path);
     }
 
     value = dataToValidate.value;
+  } else if (options.update === true || options.update === 'value') {
+    data.update(
+      ($data) => {
+        setPaths($data, [path], value);
+        return $data;
+      },
+      { taint: options.taint }
+    );
   }
+
   //console.log('🚀 ~ file: index.ts:871 ~ validate:', path, value);
 
   if (typeof validators !== 'object') {
@@ -998,8 +1011,22 @@ function formEnhance<T extends AnyZodObject, M>(
   // Add blur event, to check tainted
   let lastBlur: string[][] = [];
   function checkBlur() {
+    if (
+      options.validationMethod == 'oninput' ||
+      options.validationMethod == 'submit-only'
+    ) {
+      return;
+    }
+
     const newChanges = get(lastChanges);
-    if (equal(newChanges, lastBlur)) return;
+
+    if (
+      options.validationMethod != 'onblur' &&
+      equal(newChanges, lastBlur)
+    ) {
+      return;
+    }
+
     lastBlur = newChanges;
 
     for (const change of newChanges) {
@@ -1008,7 +1035,7 @@ function formEnhance<T extends AnyZodObject, M>(
         change,
         options.validators,
         options.defaultValidator,
-        get(data),
+        data,
         errors
       );
     }
@@ -1017,30 +1044,43 @@ function formEnhance<T extends AnyZodObject, M>(
 
   // Add input event, to check tainted
   function checkInput() {
+    if (
+      options.validationMethod == 'onblur' ||
+      options.validationMethod == 'submit-only'
+    ) {
+      return;
+    }
+
     const errorContent = get(errors);
     const taintedContent = get(tainted);
 
     for (const change of get(lastChanges)) {
-      const isTainted =
-        taintedContent &&
-        pathExists(taintedContent, change, (value) => value === true);
+      let shouldValidate = options.validationMethod === 'oninput';
 
-      const errorNode = errorContent
-        ? pathExists(errorContent, change)
-        : undefined;
+      if (!shouldValidate) {
+        const isTainted =
+          taintedContent &&
+          pathExists(taintedContent, change, (value) => value === true);
 
-      // Need a special check here, since if the error has never existed,
-      // there won't be a key for the error. But if it existed and was cleared,
-      // the key exists with the value undefined.
-      const hasError = errorNode && errorNode.key in errorNode.parent;
+        const errorNode = errorContent
+          ? pathExists(errorContent, change)
+          : undefined;
+
+        // Need a special check here, since if the error has never existed,
+        // there won't be a key for the error. But if it existed and was cleared,
+        // the key exists with the value undefined.
+        const hasError = errorNode && errorNode.key in errorNode.parent;
+
+        shouldValidate = !!isTainted && !!hasError;
+      }
 
-      if (isTainted && hasError) {
+      if (shouldValidate) {
         //console.log('🚀 ~ file: index.ts:920 ~ INPUT with error:', change);
         validateField(
           change,
           options.validators,
           options.defaultValidator,
-          get(data),
+          data,
           errors
         );
       }

src/routes/nested-validation/TagForm.svelte

@@ -13,6 +13,8 @@
 
   export let output: (string[] | undefined)[] = [];
 
+  $: testMode = $page.url.searchParams.has('test');
+
   const superFormValidator: FormOptions<
     typeof schema,
     unknown
@@ -54,30 +56,61 @@
 
   // validate tests
   onMount(async () => {
-    if (!$page.url.searchParams.has('test')) return;
+    if (!testMode) return;
+
+    await validate(['tags', 0, 'name'], {
+      value: 'p',
+      update: 'errors',
+      errors: 'Custom error'
+    });
 
-    validate(['tags', 0, 'name'], { value: 'p', errors: 'Custom error' });
     output = [...output, await validate('name')];
 
     output = [
       ...output,
-      await validate(['tags', 0, 'id'], {
-        update: false,
-        value: 1
+      await validate(['tags', 2, 'id'], {
+        value: 2
       })
     ];
 
     output = [
       ...output,
       (await validate(['tags', 0, 'id'], {
-        update: false,
+        update: 'errors',
         value: 7
-      })) ?? ['OK']
+      })) ?? ['Update errors OK']
     ];
+
+    const errors = await validate(['tags', 1, 'id']);
+    if (
+      errors?.length == 1 &&
+      errors[0] == 'Number must be greater than or equal to 3'
+    ) {
+      output = [...output, ['Error check OK']];
+    } else {
+      output = [...output, ['FAIL']];
+    }
+
+    const errors2 = await validate(['tags', 1, 'id'], {
+      value: 0,
+      update: false
+    });
+    if (
+      errors2?.length == 1 &&
+      errors2[0] == 'Number must be greater than or equal to 3'
+    ) {
+      output = [...output, ['Error check 2 OK']];
+    } else {
+      output = [...output, ['FAIL']];
+    }
   });
 </script>
 
 <form method="POST" use:enhance>
+  {#if testMode}
+    <SuperDebug data={$tainted} />
+  {/if}
+
   {#if $message}<h4>{$message}</h4>{/if}
   <input type="hidden" name="id" value={validator} />
   <small>{validator} validation</small>