Proposal: deprecate or discourage the use of @hono/zod-validator, @hono/valibot-validator, etc and instead encourage use of @hono/standard-validator

[KTrain5169]

Hi - sorry for no template, didn't think that the other two necessarily fit for a template.

From what I can tell, most of the validation-library-specific @hono/*-validator middlewares are no longer necessary to be maintained, since almost all use cases can be transferred to @hono/standard-validator instead. (maybe some people rely on throw parsing on the Zod validator instead of non-throw parsing, so that may need to be implemented first, just as a counter-example). So, I propose that those validators be deprecated with a recommendation to use the Standard Validator instead, and the docs on validation also be updated to mention that it is recommended to use the Standard Validator instead of the individual Zod, Valibot or ArkType validators.

The benefits from doing this move (that I could see) are:

• Less maintenance overhead (each validator would need a test suite and someone maintaining it)
• Consolidation (most library-specific middlewares do the same thing)

[stebeus]

It would also be nice to provide the StandardSchemaV1 type for those that are standardizing their JSON error responses with a custom middleware, and a formatter utility to group the validation issues properly. Without these additions, I would still rely on zValidator to use the Zod's flattenError utility.

[KTrain5169]

It would also be nice to provide the StandardSchemaV1 type for those that are standardizing their JSON error responses with a custom middleware,

StandardSchemaV1 is a type interface, the spec is published as @standard-schema/spec if you want to use it yourself.

and a formatter utility to group the validation issues properly. Without these additions, I would still rely on zValidator to use the Zod's flattenError utility.

Curious on your use of it currently, maybe I'll see if that's a usable (as in like it can be separate) utility

[stebeus]

StandardSchemaV1 is a type interface, the spec is published as @standard-schema/spec if you want to use it yourself.

Yes, but wouldn't it be better if it was already included in the @hono/standard-validator package too? After all, Hono is only attractive because it includes the batteries we need.

Curious on your use of it currently, maybe I'll see if that's a usable (as in like it can be separate) utility

These Zod formatters group correlated issues:

{
	"status": 400,
	"message": "Bad Request",
	"cause": {
    // z.flattenError(result.error)
		"formErrors": [],
		"fieldErrors": {
			"username": [
				"Username cannot be longer than 25 characters",
				"Username must only contain alphanumeric characters"
			],
			"password": ["Password must be at least 8 characters long"]
		}
	}
}

Which in the front end, is easier to work with than with the ungrouped issues from the sValidator:

{
	"status": 400,
	"message": "Bad Request",
	"cause": {
		"data": {
			"username": "big_usernameeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
			"password": "1"
		},
		"error": {
			"issues": [
				{
					"message": "Username cannot be longer than 25 characters",
					"path": ["username"]
				},
				{
					"message": "Username must only contain alphanumeric characters",
					"path": ["username"]
				},
				{
					"message": "Password must be at least 8 characters long",
					"path": ["password"]
				}
			]
		},
		"success": false
	}
}

[KTrain5169]

StandardSchemaV1 is a type interface, the spec is published as @standard-schema/spec if you want to use it yourself.

Yes, but wouldn't it be better if it was already included in the @hono/standard-validator package too? After all, Hono is only attractive because it includes the batteries we need.

Not really, the spec is just as easy to copy inline too (in fact SS authors encourage you to do this).

Curious on your use of it currently, maybe I'll see if that's a usable (as in like it can be separate) utility

These Zod formatters group correlated issues:

Seems reasonable enough, the structure of an issue is defined as the following in the spec:

  export interface Issue {
    /** The error message of the issue. */
    readonly message: string;
    /** The path of the issue, if any. */
    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
  }

so a utility function could just sort all related issues together

I'll see if I can hack on this after I finish something

[KTrain5169]

@stebeus Would something like this work? (just copy that code in and see if it would work for your case)

interface SortedIssues {
  [path: PropertyKey]: string[]
}

/**
 * Sort the validation errors by their path.
 * @param issues An array of {@link StandardSchemaV1.Issue validation issues}
 * @returns An object with {@link SortedIssues all issues sorted by path}
 */
export function sortErrors(issues: ReadonlyArray<StandardSchemaV1.Issue>): SortedIssues {
  const sortedIssues: SortedIssues = {}
  issues.forEach((i) => {
    const issuePath = i.path![0]
    const index = typeof issuePath === 'object' ? issuePath.key : issuePath
    if (!sortedIssues[index]) sortedIssues[index] = []
    sortedIssues[index].push(i.message)
  })
  return sortedIssues
}

(you'll also need to install the @standard-schema/spec package or copy the spec from their website to satisfy TypeScript, shouldn't need it once it lands)

If so, I'll submit a PR tomorrow or later this week.

[stebeus]

Your utility worked, @KTrain5169. But I had to add the formErrors property to your function to handle the invalid credentials error in my sign-in schema. I also added tests to help your PR get accepted. Nevertheless, this could be a better default response for the sValidator middleware depending on how other devs work with those.

// utils.ts
import type { StandardSchemaV1 } from '@standard-schema/spec';

/**
 * Sorts validation errors by their paths.
 * @param issues An array of {@link StandardSchemaV1.Issue validation issues}.
 * @returns An object with sorted form and field errors.
 */
export const sortErrors = (issues: readonly StandardSchemaV1.Issue[]) => {
	const formErrors: string[] = [];
	const fieldErrors: Record<PropertyKey, string[]> = {};

	const hasKey = (key: PropertyKey) => key != null;

	for (const { path = [], message } of issues) {
		const [issuePath] = path;
		const key = typeof issuePath === 'object' ? issuePath.key : issuePath;

		if (hasKey(key) && fieldErrors[key] == null) fieldErrors[key] = [];

		const errors = hasKey(key) ? fieldErrors[key] : formErrors;
		errors.push(message);
	}

	return { formErrors, fieldErrors };
}

// utils.test.ts
import * as v from 'valibot';
import { describe, expect, it } from 'vitest';
import * as z from 'zod';

import { sortErrors } from './utils.ts';

describe('sortErrors', () => {
	const alphanumericRegex = /^[\p{L}\p{N}_]+$/u;

	it('sorts Zod validation errors by path', () => {
		// Arrange
		const userSchema = z.strictObject({
			username: z
				.string()
				.max(10, 'Username cannot be longer than 10 characters')
				.regex(alphanumericRegex, 'Username must contain only alphanumeric characters'),
			password: z.string().trim().min(4, 'Password must be at least 4 characters long'),
		});

		const { error: { issues = [] } = {} } = z.safeParse(userSchema, {
			username: 'Super John Doe',
			password: '123',
			role: 'admin',
		});

		// Act
		const sortedErrors = sortErrors(issues);

		// Assert
		expect(sortedErrors).toStrictEqual({
			formErrors: ['Unrecognized key: "role"'],
			fieldErrors: {
				username: [
					'Username cannot be longer than 10 characters',
					'Username must contain only alphanumeric characters',
				],
				password: ['Password must be at least 4 characters long'],
			},
		});
	});

	it('sorts Valibot validation errors by path', async () => {
		// Arrange
		const userSchema = v.strictObject({
			username: v.pipe(
				v.string(),
				v.maxLength(10, 'Username cannot be longer than 10 characters'),
				v.regex(alphanumericRegex, 'Username must contain only alphanumeric characters'),
			),
			password: v.pipe(
				v.string(),
				v.trim(),
				v.minLength(4, 'Password must be at least 4 characters long'),
			),
		});

		const { issues = [] } = await userSchema['~standard'].validate({
			username: 'Super John Doe',
			password: '123',
			role: 'admin',
		});

		// Act
		const sortedErrors = sortErrors(issues);

		// Assert
		expect(sortedErrors).toStrictEqual({
			formErrors: [],
			fieldErrors: {
				username: [
					'Username cannot be longer than 10 characters',
					'Username must contain only alphanumeric characters',
				],
				password: ['Password must be at least 4 characters long'],
				role: ['Invalid key: Expected never but received "role"'],
			},
		});
	});
});

[KTrain5169]

Your utility worked, @KTrain5169. But I had to add the formErrors property to your function to handle the invalid credentials error in my sign-in schema. I also added tests to help your PR get accepted. Nevertheless, this could be a better default response for the sValidator middleware depending on how other devs work with those.

Thanks. I'm not sure if this is necessarily a better default for absolutely everyone, but it may be best for 99% of use cases. If a new version of the middleware releases and someone complains about it, I'll just set it as a boolean toggle option.

Also thanks for the test case!