feat: postal code validation

[ysknsid25]

Japanese often implement postal code checks. But all are self-implemented.

Even Zod does not provide it as standard.

Therefore, we thought that the addition of postal code validation could be a factor that would give valibot an advantage in Japan.

In addition, although this time we have prepared for Japan and the U.S., it is possible to extend it by adding the country code to CountryCode and the regular expression pattern corresponding to the country code to getPostalCodePattern.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
valibot	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 22, 2025 2:15am

[Copilot]

Pull Request Overview

A PR that introduces postal code validation to improve support for Japanese and U.S. postal codes in the library. Key changes include the implementation of the postalCode validation action, corresponding tests for type inference and validation behavior, and an update to the API menu documentation.

Reviewed Changes

Copilot reviewed 5 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
library/src/actions/postalCode/postalCode.test-d.ts	Added type tests for the postalCode action.
library/src/actions/postalCode/postalCode.test.ts	Added tests validating postal code formats for JP and US.
library/src/actions/postalCode/postalCode.ts	Implemented the postalCode validation action.
library/src/actions/postalCode/index.ts	Export updated to include new postalCode module.
website/src/routes/api/menu.md	Updated API documentation with a postalCode route.

Files not reviewed (3)

• website/src/routes/api/(actions)/postalCode/index.mdx: Language not supported
• website/src/routes/api/(schemas)/string/index.mdx: Language not supported
• website/src/routes/guides/(main-concepts)/pipelines/index.mdx: Language not supported

[Copilot]

Pull Request Overview

This PR adds postal code validation to support Japanese and US postal code formats, enhancing the library’s validation capabilities.

• Implements postal code validation logic in the core action function.
• Provides extensive unit and type tests for the postal code functionality.
• Updates the API documentation menu to include the postalCode endpoint.

Reviewed Changes

Copilot reviewed 5 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
library/src/actions/postalCode/postalCode.ts	Implements postal code validation logic including regex lookup.
library/src/actions/postalCode/postalCode.test.ts	Adds unit tests for the postal code action using vitest.
library/src/actions/postalCode/postalCode.test-d.ts	Provides type tests to ensure correct type inference.
library/src/actions/postalCode/index.ts	Exports the postalCode module.
website/src/routes/api/menu.md	Updates the API menu to include the postalCode endpoint.

Files not reviewed (3)

• website/src/routes/api/(actions)/postalCode/index.mdx: Language not supported
• website/src/routes/api/(schemas)/string/index.mdx: Language not supported
• website/src/routes/guides/(main-concepts)/pipelines/index.mdx: Language not supported

Comments suppressed due to low confidence (1)

library/src/actions/postalCode/postalCode.ts:104

• [nitpick] The generic type parameter 'CountryCode' shadows the imported 'CountryCode' type. Consider renaming it (e.g., to 'TCode') for improved clarity.

export function postalCode<TInput extends string, CountryCode>(

[fabian-hiller]

Thanks for creating this PR! I am not sure if we should add a postalCode action because it is country specific and hard to get right, and supporting every country will likely lead to a larger bundle size. I will wait to see if more developers show interest in this PR before reviewing your code. In the meantime, a good workaround is to use our regex action.

[ysknsid25]

@fabian-hiller

Nice to meet you!

I agree with you, the reason why I implemented only JP and US was because I thought it would be difficult to cover all countries and if there is a demand for each country, I would be happy to have it expanded 👍

[fabian-hiller]

This is also the reason why we don't provide a phone action yet. While postalCode is probably a bit easier to implement, it might still be hard to support every country without making a mistake. Therefore, it might make sense to implement such a validation function as an independent library that can be used together with our check action.

I don't want to make a decision right now. I leave this PR open to get more feedback from others in the long run.

[ysknsid25]

I agree. It might be interesting if the method is extended with plug-ins, etc.