Added signature to set a form-level error with setError.

Author: ciscoheat

CHANGELOG.md

@@ -5,6 +5,12 @@ 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).
 
+## [Unreleased]
+
+### Added
+
+- Added signature to more conveniently set a form-level error with `setError`.
+
 ## [1.1.3] - 2023-06-29
 
 ### Fixed

src/errors.test.ts

@@ -22,7 +22,7 @@ describe('Errors', async () => {
     expect(output.data.name).toBeNull();
 
     const err = {
-      _errors: ['Form-level error'],
+      _errors: ['Form-level error', 'Second form-level error'],
       scopeId: ['This is an error'],
       enumber: ['This should be ok', 'Still ok'],
       arr: { _errors: ['Array-level error'], 3: ['Array item error'] },
@@ -37,7 +37,8 @@ describe('Errors', async () => {
     setError(output, 'enumber', 'Still ok');
     setError(output, 'arr._errors', 'Array-level error');
     setError(output, '', 'Form-level error that should not be displayed.');
-    setError(output, '', 'Form-level error', { overwrite: true });
+    setError(output, 'Form-level error', { overwrite: true });
+    setError(output, 'Second form-level error');
 
     assert(!output.valid);
     expect(output.errors).toStrictEqual(err);

src/lib/superValidate.ts

@@ -1,4 +1,4 @@
-import { fail, json, type RequestEvent } from '@sveltejs/kit';
+import { ActionFailure, fail, json, type RequestEvent } from '@sveltejs/kit';
 import { parse, stringify } from 'devalue';
 import {
   SuperFormError,
@@ -55,19 +55,64 @@ export function message<T extends ZodValidation<AnyZodObject>, M>(
 
 export const setMessage = message;
 
+type SetErrorOptions = {
+  overwrite?: boolean;
+  status?: NumericRange<400, 599>;
+};
+
+/**
+ * Sets a form-level error.
+ * form.valid is automatically set to false.
+ *
+ * @param {SuperValidated<T, unknown>} form A validation object, usually returned from superValidate.
+ * @param {string | string[]} error Error message(s).
+ * @param {SetErrorOptions} options Option to overwrite previous errors and set a different status than 400. The status must be in the range 400-599.
+ * @returns fail(status, { form })
+ */
+export function setError<T extends ZodValidation<AnyZodObject>>(
+  form: SuperValidated<T, unknown>,
+  error: string | string[],
+  options?: SetErrorOptions
+): ActionFailure<{ form: SuperValidated<T, unknown> }>;
+
 /**
- * Sets an error for a form field, with an optional HTTP status code.
- * form.valid is automatically set to false. A status lower than 400 cannot be sent.
+ * Sets an error for a form field or array field.
+ * form.valid is automatically set to false.
+ *
+ * @param {SuperValidated<T, unknown>} form A validation object, usually returned from superValidate.
+ * @param {'' | StringPathLeaves<z.infer<UnwrapEffects<T>>, '_errors'>} path Path to the form field. Use an empty string to set a form-level error. Array-level errors can be set by appending "._errors" to the field.
+ * @param {string | string[]} error Error message(s).
+ * @param {SetErrorOptions} options Option to overwrite previous errors and set a different status than 400. The status must be in the range 400-599.
+ * @returns fail(status, { form })
  */
 export function setError<T extends ZodValidation<AnyZodObject>>(
   form: SuperValidated<T, unknown>,
   path: '' | StringPathLeaves<z.infer<UnwrapEffects<T>>, '_errors'>,
   error: string | string[],
-  options: { overwrite?: boolean; status?: NumericRange<400, 599> } = {
-    overwrite: false,
-    status: 400
+  options?: SetErrorOptions
+): ActionFailure<{ form: SuperValidated<T, unknown> }>;
+
+export function setError<T extends ZodValidation<AnyZodObject>>(
+  form: SuperValidated<T, unknown>,
+  path:
+    | string
+    | string[]
+    | (string & StringPathLeaves<z.infer<UnwrapEffects<T>>, '_errors'>),
+  error?: string | string[] | SetErrorOptions,
+  options?: SetErrorOptions
+): ActionFailure<{ form: SuperValidated<T, unknown> }> {
+  // Unify signatures
+  if (
+    error == undefined ||
+    (typeof error !== 'string' && !Array.isArray(error))
+  ) {
+    options = error;
+    error = path;
+    path = '';
   }
-) {
+
+  if (options === undefined) options = {};
+
   const errArr = Array.isArray(error) ? error : [error];
 
   if (!form.errors) form.errors = {};