feat: Add custom parser testing helpers

Author: franky47

packages/nuqs/package.json

@@ -35,6 +35,7 @@
   "files": [
     "dist/",
     "server.d.ts",
+    "testing.d.ts",
     "adapters/react.d.ts",
     "adapters/next.d.ts",
     "adapters/next/app.d.ts",
@@ -60,6 +61,11 @@
       "import": "./dist/server.js",
       "require": "./esm-only.cjs"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./esm-only.cjs"
+    },
     "./adapters/react": {
       "types": "./dist/adapters/react.d.ts",
       "import": "./dist/adapters/react.js",

packages/nuqs/src/parsers.test.ts

@@ -1,22 +1,49 @@
 import { describe, expect, test } from 'vitest'
 import {
   parseAsArrayOf,
+  parseAsBoolean,
   parseAsFloat,
   parseAsHex,
   parseAsInteger,
-  parseAsIsoDateTime,
   parseAsIsoDate,
+  parseAsIsoDateTime,
+  parseAsNumberLiteral,
   parseAsString,
+  parseAsStringEnum,
+  parseAsStringLiteral,
   parseAsTimestamp
 } from './parsers'
+import { testParseThenSerialize, testSerializeThenParse } from './testing'
 
 describe('parsers', () => {
+  test('parseAsString', () => {
+    expect(parseAsString.parse('')).toBe('')
+    expect(parseAsString.parse('foo')).toBe('foo')
+    testParseThenSerialize(parseAsString, 'foo')
+    testSerializeThenParse(parseAsString, 'foo')
+  })
   test('parseAsInteger', () => {
     expect(parseAsInteger.parse('')).toBeNull()
     expect(parseAsInteger.parse('1')).toBe(1)
     expect(parseAsInteger.parse('3.14')).toBe(3)
     expect(parseAsInteger.parse('3,14')).toBe(3)
     expect(parseAsInteger.serialize(3.14)).toBe('3')
+    testParseThenSerialize(parseAsInteger, '3')
+    testSerializeThenParse(parseAsInteger, 3)
+    expect(() => testParseThenSerialize(parseAsInteger, '3.14')).toThrow()
+    expect(() => testSerializeThenParse(parseAsInteger, 3.14)).toThrow()
+  })
+  test('parseAsHex', () => {
+    expect(parseAsHex.parse('')).toBeNull()
+    expect(parseAsHex.parse('1')).toBe(1)
+    expect(parseAsHex.parse('a')).toBe(0xa)
+    expect(parseAsHex.parse('g')).toBeNull()
+    expect(parseAsHex.serialize(0xa)).toBe('0a')
+    for (let i = 0; i < 256; i++) {
+      const hex = i.toString(16).padStart(2, '0')
+      testParseThenSerialize(parseAsHex, hex)
+      testSerializeThenParse(parseAsHex, i)
+    }
   })
   test('parseAsFloat', () => {
     expect(parseAsFloat.parse('')).toBeNull()
@@ -26,17 +53,31 @@ describe('parsers', () => {
     expect(parseAsFloat.serialize(3.14)).toBe('3.14')
     // https://0.30000000000000004.com/
     expect(parseAsFloat.serialize(0.1 + 0.2)).toBe('0.30000000000000004')
+    testParseThenSerialize(parseAsFloat, '3.14')
+    testSerializeThenParse(parseAsFloat, 3.14)
   })
-  test('parseAsHex', () => {
-    expect(parseAsHex.parse('')).toBeNull()
-    expect(parseAsHex.parse('1')).toBe(1)
-    expect(parseAsHex.parse('a')).toBe(0xa)
-    expect(parseAsHex.parse('g')).toBeNull()
-    expect(parseAsHex.serialize(0xa)).toBe('0a')
+  test('parseAsBoolean', () => {
+    expect(parseAsBoolean.parse('')).toBe(false)
+    // In only triggers on 'true', everything else is false
+    expect(parseAsBoolean.parse('true')).toBe(true)
+    expect(parseAsBoolean.parse('false')).toBe(false)
+    expect(parseAsBoolean.parse('0')).toBe(false)
+    expect(parseAsBoolean.parse('1')).toBe(false)
+    expect(parseAsBoolean.parse('yes')).toBe(false)
+    expect(parseAsBoolean.parse('no')).toBe(false)
+    expect(parseAsBoolean.serialize(true)).toBe('true')
+    expect(parseAsBoolean.serialize(false)).toBe('false')
+    testParseThenSerialize(parseAsBoolean, 'true')
+    testSerializeThenParse(parseAsBoolean, true)
+    testParseThenSerialize(parseAsBoolean, 'false')
+    testSerializeThenParse(parseAsBoolean, false)
   })
+
   test('parseAsTimestamp', () => {
     expect(parseAsTimestamp.parse('')).toBeNull()
     expect(parseAsTimestamp.parse('0')).toStrictEqual(new Date(0))
+    testParseThenSerialize(parseAsTimestamp, '0')
+    testSerializeThenParse(parseAsTimestamp, new Date(1234567890))
   })
   test('parseAsIsoDateTime', () => {
     expect(parseAsIsoDateTime.parse('')).toBeNull()
@@ -48,6 +89,8 @@ describe('parsers', () => {
     expect(parseAsIsoDateTime.parse(moment.slice(0, 16) + 'Z')).toStrictEqual(
       ref
     )
+    testParseThenSerialize(parseAsIsoDateTime, moment)
+    testSerializeThenParse(parseAsIsoDateTime, ref)
   })
   test('parseAsIsoDate', () => {
     expect(parseAsIsoDate.parse('')).toBeNull()
@@ -56,12 +99,61 @@ describe('parsers', () => {
     const ref = new Date(moment)
     expect(parseAsIsoDate.parse(moment)).toStrictEqual(ref)
     expect(parseAsIsoDate.serialize(ref)).toEqual(moment)
+    testParseThenSerialize(parseAsIsoDate, moment)
+    testSerializeThenParse(parseAsIsoDate, ref)
   })
+  test('parseAsStringEnum', () => {
+    enum Test {
+      A = 'a',
+      B = 'b',
+      C = 'c'
+    }
+    const parser = parseAsStringEnum<Test>(Object.values(Test))
+    expect(parser.parse('')).toBeNull()
+    expect(parser.parse('a')).toBe('a')
+    expect(parser.parse('b')).toBe('b')
+    expect(parser.parse('c')).toBe('c')
+    expect(parser.parse('d')).toBeNull()
+    expect(parser.serialize(Test.A)).toBe('a')
+    expect(parser.serialize(Test.B)).toBe('b')
+    expect(parser.serialize(Test.C)).toBe('c')
+    testParseThenSerialize(parser, 'a')
+    testSerializeThenParse(parser, Test.A)
+  })
+  test('parseAsStringLiteral', () => {
+    const parser = parseAsStringLiteral(['a', 'b', 'c'] as const)
+    expect(parser.parse('')).toBeNull()
+    expect(parser.parse('a')).toBe('a')
+    expect(parser.parse('b')).toBe('b')
+    expect(parser.parse('c')).toBe('c')
+    expect(parser.parse('d')).toBeNull()
+    expect(parser.serialize('a')).toBe('a')
+    expect(parser.serialize('b')).toBe('b')
+    expect(parser.serialize('c')).toBe('c')
+    testParseThenSerialize(parser, 'a')
+    testSerializeThenParse(parser, 'a')
+  })
+  test('parseAsNumberLiteral', () => {
+    const parser = parseAsNumberLiteral([1, 2, 3] as const)
+    expect(parser.parse('')).toBeNull()
+    expect(parser.parse('1')).toBe(1)
+    expect(parser.parse('2')).toBe(2)
+    expect(parser.parse('3')).toBe(3)
+    expect(parser.parse('4')).toBeNull()
+    expect(parser.serialize(1)).toBe('1')
+    expect(parser.serialize(2)).toBe('2')
+    expect(parser.serialize(3)).toBe('3')
+    testParseThenSerialize(parser, '1')
+    testSerializeThenParse(parser, 1)
+  })
+
   test('parseAsArrayOf', () => {
     const parser = parseAsArrayOf(parseAsString)
     expect(parser.serialize([])).toBe('')
     // It encodes its separator
     expect(parser.serialize(['a', ',', 'b'])).toBe('a,%2C,b')
+    testParseThenSerialize(parser, 'a,b')
+    testSerializeThenParse(parser, ['a', 'b'])
   })
 
   test('parseServerSide with default (#384)', () => {

packages/nuqs/src/testing.ts

@@ -0,0 +1,75 @@
+import type { ParserBuilder } from './parsers'
+
+/**
+ * Test that a parser is bijective (serialize then parse gives back the same value).
+ *
+ * It will throw if the parser is not bijective (if the parsed value is not equal to the input value).
+ * The parser's `eq` function is used to compare the values.
+ *
+ * Usage:
+ * ```ts
+ * // Expect it to pass (no error thrown)
+ * testSerializeThenParse(myParser, 'foo')
+ * // Expect it to fail
+ * expect(() => testSerializeThenParse(myParser, 'bar')).toThrow()
+ * ```
+ *
+ * @param parser The parser to test
+ * @param input An input value to test against
+ */
+export function testSerializeThenParse<T>(parser: ParserBuilder<T>, input: T) {
+  const serialized = parser.serialize(input)
+  const parsed = parser.parse(serialized)
+  if (parsed === null) {
+    throw new Error(
+      `[nuqs] testSerializeThenParse: parsed value is null (when parsing ${serialized} serialized from ${input})`
+    )
+  }
+  if (!parser.eq(input, parsed)) {
+    throw new Error(
+      `[nuqs] parser is not bijective (in testSerializeThenParse)
+  Expected value:         ${typeof input === 'object' ? JSON.stringify(input) : input}
+  Received parsed value:  ${typeof parsed === 'object' ? JSON.stringify(parsed) : parsed}
+  Serialized as: '${serialized}'
+  `
+    )
+  }
+}
+
+/**
+ * Tests that a parser is bijective (parse then serialize gives back the same query string).
+ *
+ * It will throw if the parser is not bijective (if the serialized value is not equal to the input query).
+ *
+ * Usage:
+ * ```ts
+ * // Expect it to pass (no error thrown)
+ * testParseThenSerialize(myParser, 'foo')
+ * // Expect it to fail
+ * expect(() => testParseThenSerialize(myParser, 'bar')).toThrow()
+ * ```
+ *
+ * @param parser The parser to test
+ * @param input A query string to test against
+ */
+export function testParseThenSerialize<T>(
+  parser: ParserBuilder<T>,
+  input: string
+) {
+  const parsed = parser.parse(input)
+  if (parsed === null) {
+    throw new Error(
+      `[nuqs] testParseThenSerialize: parsed value is null (when parsing ${input})`
+    )
+  }
+  const serialized = parser.serialize(parsed)
+  if (serialized !== input) {
+    throw new Error(
+      `[nuqs] parser is not bijective (in testParseThenSerialize)
+  Expected query: '${input}'
+  Received query: '${serialized}'
+  Parsed value: ${parsed}
+`
+    )
+  }
+}

packages/nuqs/testing.d.ts

@@ -0,0 +1,7 @@
+// This file is needed for projects that have `moduleResolution` set to `node`
+// in their tsconfig.json to be able to `import {} from 'nuqs/testing'`.
+// Other module resolutions strategies will look for the `exports` in `package.json`,
+// but with `node`, TypeScript will look for a .d.ts file with that name at the
+// root of the package.
+
+export * from './dist/testing'

packages/nuqs/tsup.config.ts

@@ -34,7 +34,8 @@ const entrypoints = {
     'adapters/testing': 'src/adapters/testing.ts'
   },
   server: {
-    server: 'src/index.server.ts'
+    server: 'src/index.server.ts',
+    testing: 'src/testing.ts'
   }
 }