Skip to content

feat: Add Standard Schema interface #965

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 20 commits into from
Jun 27, 2025
Merged

feat: Add Standard Schema interface #965

merged 20 commits into from
Jun 27, 2025

Conversation

franky47
Copy link
Member

@franky47 franky47 commented Apr 6, 2025

This adds a new export, createStandardSchemaV1, which (as the name implies), creates a standard-schema compatible object that can be fed to tRPC's inputs, or TanStack Router for search params validation (see #953).

image

Since nuqs parsers always assume they have to deal with deserialisation, and those validation libraries generally assume they work with data already of the right shape (kind of) and verify runtime constraints, we first run the input through the serializer to generate a URL, which we can then parse.

This also introduces a new option on the loaders & the cache: strict mode, which will throw errors rather than applying default values (or returning null) for invalid querystring values.

It also fixes a bug where the loader functions had a signature mismatching the runtime implementation: passing urlKeys is only supported when creating the loader function, which now can accept a different set of runtime options like strict mode. We're renaming the types to make this clearer.

It also deprecates parseServerSide for parsers, as it was an internal artefact of resolving a non-nullable type when specifying a default value. Loaders now have integrated parseServerSide's duties and do provide stronger key/value type-safety (while also supporting other things like strict mode and urlKeys).

Tasks

  • Add tests
  • Add example with tRPC
  • Add docs
  • Add loader strict mode, docs & tests
  • Add cache strict mode, docs & tests
  • Test equality of input/output in the SSv1 validate method ?

@franky47 franky47 added the feature New feature or request label Apr 6, 2025
@franky47 franky47 added this to the 🪵 Backlog milestone Apr 6, 2025
Copy link

vercel bot commented Apr 6, 2025

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

Name Status Preview Comments Updated (UTC)
nuqs ✅ Ready (Inspect) Visit Preview 💬 Add feedback Jun 27, 2025 6:37am

Copy link

pkg-pr-new bot commented Apr 6, 2025

pnpm add https://pkg.pr.new/nuqs@965

commit: 7769705

@franky47 franky47 marked this pull request as draft April 6, 2025 10:29
@franky47 franky47 force-pushed the feat/standard-schema branch from ca05aac to 748d789 Compare April 7, 2025 20:37
@franky47 franky47 force-pushed the feat/standard-schema branch 2 times, most recently from 2cad8bf to 70f9ed7 Compare April 11, 2025 18:37
@franky47 franky47 force-pushed the feat/standard-schema branch from 70f9ed7 to 7162ec8 Compare April 17, 2025 08:01
@franky47 franky47 force-pushed the feat/standard-schema branch from 085449e to ada6de0 Compare April 23, 2025 12:24
@franky47 franky47 force-pushed the feat/standard-schema branch from ada6de0 to 739faf1 Compare June 10, 2025 09:16
Copy link

socket-security bot commented Jun 10, 2025

franky47 added 20 commits June 27, 2025 08:34
This is an internal artifact of needing to resolve a type with or without
a default value to make it non-nullable, and does not provide a strong
key/value type-safety, for which loaders are the preferred way.
TanStack Router handles defaults a bit differently
than nuqs, and would require a Partial output type
for Links not to have to specify every single search
param value for a given route.

Moreover, the output of validateSearch is reflected in
the URL a page load time, which contradicts the "clean URL first"
approach taken by nuqs (it also reflects null values which is not
desirable).
@franky47 franky47 force-pushed the feat/standard-schema branch from 30f4397 to 7769705 Compare June 27, 2025 06:34
@franky47 franky47 enabled auto-merge (squash) June 27, 2025 06:34
@franky47 franky47 merged commit b929682 into next Jun 27, 2025
25 checks passed
@franky47 franky47 deleted the feat/standard-schema branch June 27, 2025 06:37
Copy link

🎉 This PR is included in version 2.5.0-beta.2 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature New feature or request released on @beta
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant