Parser System Overview

export type SingleParser<T> = {
  type?: 'single'
  
  /**
   * Convert a query string value into a state value.
   *
   * If the string value does not represent a valid state value,
   * the parser should return `null`. Throwing an error is also supported.
   */
  parse: (value: string) => T | null

  /**
   * Render the state value into a query string value.
   */
  serialize?: (value: T) => string

  /**
   * Check if two state values are equal.
   *
   * This is used when using the `clearOnDefault` value, to compare the default
   * value with the set value.
   *
   * It makes sense to provide this function when the state value is an object
   * or an array, as the default referential equality check will not work.
   */
  eq?: (a: T, b: T) => boolean
}

export type MultiParser<T> = {
  type: 'multi'
  parse: (value: ReadonlyArray<string>) => T | null
  serialize?: (value: T) => Array<string>
  eq?: (a: T, b: T) => boolean
}

export type SingleParserBuilder<T> = Required<SingleParser<T>> &
  Options & {
    /**
     * Set history type, shallow routing and scroll restoration options
     * at the hook declaration level.
     */
    withOptions<This>(this: This, options: Options): This

    /**
     * Specifying a default value makes the hook state non-nullable when the
     * query is missing from the URL: the default value is returned instead
     * of `null`.
     */
    withDefault(
      this: SingleParserBuilder<T>,
      defaultValue: NonNullable<T>
    ): Omit<SingleParserBuilder<T>, 'parseServerSide'> & {
      readonly defaultValue: NonNullable<T>
      parseServerSide(value: string | string[] | undefined): NonNullable<T>
    }

    /**
     * Use the parser in Server Components
     * @deprecated prefer using loaders instead
     */
    parseServerSide(value: string | string[] | undefined): T | null
  }

export type MultiParserBuilder<T> = Required<MultiParser<T>> &
  Options & {
    withOptions<This>(this: This, options: Options): This
    withDefault(
      this: MultiParserBuilder<T>,
      defaultValue: NonNullable<T>
    ): Omit<MultiParserBuilder<T>, 'parseServerSide'> & {
      readonly defaultValue: NonNullable<T>
      parseServerSide(value: string | string[] | undefined): NonNullable<T>
    }
    parseServerSide(value: string | string[] | undefined): T | null
  }

import { type inferParserType } from 'nuqs'

const intNullable = parseAsInteger
const intNonNull = parseAsInteger.withDefault(0)

type A = inferParserType<typeof intNullable> // number | null
type B = inferParserType<typeof intNonNull>  // number

// Works with parser objects too
const parsers = {
  a: parseAsInteger,
  b: parseAsBoolean.withDefault(false)
}

type State = inferParserType<typeof parsers>
// { a: number | null, b: boolean }

export type inferParserType<Input> =
  Input extends GenericParserBuilder<any>
    ? inferSingleParserType<Input>
    : Input extends Record<string, GenericParserBuilder<any>>
      ? inferParserRecordType<Input>
      : never

// ✅ Good
const parseAsInteger = createParser({
  parse: v => {
    const int = parseInt(v)
    return int == int ? int : null // NaN check
  },
  serialize: v => '' + Math.round(v)
})

// ❌ Bad - throws errors
const parseAsInteger = createParser({
  parse: v => {
    if (!/^\d+$/.test(v)) {
      throw new Error('Invalid integer')
    }
    return parseInt(v)
  },
  serialize: String
})

// ❌ Bad - loses precision
const parseAsFloat = createParser({
  parse: parseFloat,
  serialize: v => v.toFixed(2) // Rounds!
})

// ✅ Good - preserves precision
const parseAsFloat = createParser({
  parse: v => {
    const float = parseFloat(v)
    return float == float ? float : null
  },
  serialize: String // No rounding
})

const parseAsJson = createParser({
  parse: query => {
    try {
      return JSON.parse(query)
    } catch {
      return null
    }
  },
  serialize: value => JSON.stringify(value),
  eq(a, b) {
    // Check referential equality first for performance
    return a === b || JSON.stringify(a) === JSON.stringify(b)
  }
})