feat: Add custom parsers testing helpers

[franky47]

This PR introduces a new export, with two functions to help testing custom parsers.

Parsers must be bijective, which means:

• On a valid input query string, running the parser then the serializer should output the same query string as the input
• On a valid state, running the serializer then the parser should return an identical value.

For that second point, identical value means that the eq equality function of the parser should return true when fed the input and output.

Usage

Eg, in Vitest:

import {
  isParserBijective,
  testParseThenSerialize,
  testSerializeThenParse
} from 'nuqs/testing'

it('is bijective', () => {
  // Passing tests return true
  expect(isParserBijective(parseAsInteger, '42', 42)).toBe(true)
  // Failing test throws an error
  expect(() => isParserBijective(parseAsInteger, '42', 47)).toThrowError()

  // You can also test either side separately:
  expect(testParseThenSerialize(parseAsInteger, '42')).toBe(true)
  expect(testSerializeThenParse(parseAsInteger, 42)).toBe(true)
  // Those will also throw an error if the test fails,
  // which makes it easier to isolate which side failed:
  expect(() => testParseThenSerialize(parseAsInteger, 'not a number')).toThrowError()
  expect(() => testSerializeThenParse(parseAsInteger, NaN)).toThrowError()
})

Bug fix

Also contains a bug fix for date parsers which were missing a suitable equality function.

Tasks

• Add docs

[vercel]

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	Feb 16, 2025 9:47pm

[pkg-pr-new]

Open in Stackblitz

npm i https://pkg.pr.new/nuqs@853

commit: 64f6635

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

Files not reviewed (1)

• packages/nuqs/package.json: Language not supported

Comments suppressed due to low confidence (3)

packages/nuqs/src/testing.ts:25

• [nitpick] The error message could be more clear and helpful. Consider rephrasing to: '[nuqs] testSerializeThenParse: The parsed value is null when parsing the serialized value ${serialized} from the input ${input}.'

[nuqs] testSerializeThenParse: parsed value is null (when parsing ${serialized} serialized from ${input})

packages/nuqs/src/testing.ts:62

• [nitpick] The error message could be more clear and helpful. Consider rephrasing to: '[nuqs] testParseThenSerialize: The parsed value is null when parsing the input ${input}.'

[nuqs] testParseThenSerialize: parsed value is null (when parsing ${input})

packages/nuqs/src/testing.ts:14

• There is a typo in the usage example. 'testSerializeThanParse' should be 'testSerializeThenParse'.

expect(() => testSerializeThanParse(myParser, 'bar')).toThrow()

[github-actions]

🎉 This PR is included in version 2.4.0-beta.5 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 2.4.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀