Search Param Validation — React Deep Dive

raw URLSearchParams → typed, validated, defaulted

A URL search string like ?page=2&sort=desc is raw text — URLSearchParams hands you {{page:"2", sort:"desc"}}: everything is a string, nothing is checked, nothing has a default. TanStack Router’s validateSearch replaces that with a schema (Zod / Valibot / ArkType). The router runs a pipeline — parse → coerce → validate → default — and the component reads route.useSearch() to get a real {'{ page: number, sort: "asc"|"desc", filter?: string }'}. Invalid URLs are rejected (or recovered with fallbacks), never silently passed through.

stage	what happens	example
`parse`	URL search string → object of raw strings	`?page=2` → `{'{ page:"2" }'}`
`coerce`	declared type converts the string	`z.number()`: `"2"` → `2`
`validate`	constraints checked; reject on failure	`.min(1)`, `z.enum([...])`
`default`	missing key → schema default	no `page` → `1`
`type`	validator return type flows to consumers	`route.useSearch()` is fully typed

1 · the schema validator you write (edit me)

searchSchema is the single source of truth (this stands in for z.object({'{...}'})). validateSearch() is the engine: it walks each field, coerces numbers, checks enum/min constraints, and fills defaults for missing keys — returning {'{ data, errors }'}, exactly like a Zod parse result.

// Schema — the single source of truth (stands in for z.object({...})).
// In real TanStack Router: validateSearch: zodValidator(searchSchema)
var searchSchema = {
  page:   { type: 'number', default: 1, min: 1, coerce: true },
  sort:   { type: 'enum', values: ['asc', 'desc'], default: 'asc' },
  filter: { type: 'string', optional: true }
};

// validateSearch: (rawInput, schema) -> { data, errors }
//   pipeline: parse -> coerce -> validate constraints -> apply defaults.
//   Mirrors Zod's .parse(): returns the typed data, or a list of issues.
function validateSearch(rawInput, schema) {
  var result = { data: null, errors: [] };
  var data = {};

  Object.keys(schema).forEach(function (key) {
    var field = schema[key];
    var raw = rawInput[key];

    // parse: missing or empty
    if (raw === undefined || raw === null || raw === '') {
      if (field.optional) return;                                  // omit optional
      if (field.default !== undefined) { data[key] = field.default; return; }
      result.errors.push(key + ': required');
      return;
    }

    // coerce: URL gives strings; z.number() coerces
    if (field.type === 'number' && field.coerce) {
      raw = Number(raw);
      if (isNaN(raw)) { result.errors.push(key + ': must be a number'); return; }
    }

    // validate: constraints
    if (field.type === 'number') {
      if (field.min !== undefined && raw < field.min) {
        result.errors.push(key + ': must be >= ' + field.min); return;
      }
    }
    if (field.type === 'enum') {
      if (field.values.indexOf(raw) < 0) {
        result.errors.push(key + ': must be one of ' + field.values.join(', ')); return;
      }
    }

    data[key] = raw;
  });

  result.data = result.errors.length === 0 ? data : null;
  return result;
}

// serializeUrl: the reverse of parse (data -> ?query string).
function serializeUrl(data) {
  var parts = Object.keys(data).map(function (k) {
    return encodeURIComponent(k) + '=' + encodeURIComponent(data[k]);
  });
  return parts.length ? ('?' + parts.join('&')) : '(no params)';
}

function SearchValidationDemo() {
  var _React$useState = React.useState({ page: '2', sort: 'desc', filter: 'react' }),
      input = _React$useState[0], setInput = _React$useState[1];

  function setField(key, value) {
    var next = {}; next[key] = value;
    setInput(Object.assign({}, input, next));
  }

  var result = validateSearch(input, searchSchema);
  var keys = Object.keys(searchSchema);

  return (
    <div>
      <h3 className="text-[#e6edf3] text-sm font-bold mb-2">Schema definition (the single source of truth)</h3>
      <div style={{ overflowX: 'auto', minWidth: 0 }}>
        <table>
          <tr><th>param</th><th>type</th><th>constraints</th><th>default</th></tr>
          {keys.map(function (k) {
            var f = searchSchema[k];
            var cons = [];
            if (f.type === 'enum') cons.push('one of [' + f.values.join(', ') + ']');
            if (f.min !== undefined) cons.push('>= ' + f.min);
            if (f.coerce) cons.push('coerce');
            if (f.optional) cons.push('optional');
            return (
              <tr data-testid="schema-row" key={k}>
                <td><code>{k}</code></td>
                <td className="text-[#8b949e]">{f.type}</td>
                <td className="text-[#8b949e]">{cons.join(' · ') || '—'}</td>
                <td className="text-[#8b949e]">{f.default !== undefined ? JSON.stringify(f.default) : '—'}</td>
              </tr>
            );
          })}
        </table>
      </div>

      <h3 className="text-[#e6edf3] text-sm font-bold mb-2 mt-4">URL search params (edit me)</h3>
      <div className="grid grid-cols-1 md:grid-cols-3 gap-3 mb-3">
        <div>
          <label className="block text-xs text-[#8b949e] mb-1">page (number)</label>
          <input
            data-testid="input-page"
            value={input.page}
            onChange={function (e) { setField('page', e.target.value); }}
            className="w-full px-2 py-2 bg-[#0d1117] border border-[#30363d] rounded text-[#e6edf3] text-sm font-mono"
          />
        </div>
        <div>
          <label className="block text-xs text-[#8b949e] mb-1">sort (enum)</label>
          <input
            data-testid="input-sort"
            value={input.sort}
            onChange={function (e) { setField('sort', e.target.value); }}
            className="w-full px-2 py-2 bg-[#0d1117] border border-[#30363d] rounded text-[#e6edf3] text-sm font-mono"
          />
        </div>
        <div>
          <label className="block text-xs text-[#8b949e] mb-1">filter (optional string)</label>
          <input
            data-testid="input-filter"
            value={input.filter}
            onChange={function (e) { setField('filter', e.target.value); }}
            className="w-full px-2 py-2 bg-[#0d1117] border border-[#30363d] rounded text-[#e6edf3] text-sm font-mono"
          />
        </div>
      </div>

      <div
        data-testid="verdict"
        data-valid={result.data ? 'true' : 'false'}
        className={'p-3 rounded border ' + (result.data ? 'bg-[rgba(46,204,113,.08)] border-[#2ecc71]' : 'bg-[rgba(231,76,60,.08)] border-[#e74c3c]')}
      >
        {result.data ? (
          <div>
            <div className="text-[#2ecc71] font-bold mb-1">✓ Valid — coerced, validated, defaults applied</div>
            <div className="text-[#e6edf3] text-sm">
              page: <span data-testid="data-page" className="text-[#61dafb] font-bold">{String(result.data.page)}</span>
              {' · '}sort: <span className="text-[#61dafb] font-bold">{String(result.data.sort)}</span>
              {' · '}filter: <span className="text-[#61dafb] font-bold">{result.data.filter !== undefined ? String(result.data.filter) : '(omitted)'}</span>
            </div>
            <div className="text-[#8b949e] text-xs mt-2">
              URL: <code data-testid="url-preview">{serializeUrl(result.data)}</code>
            </div>
          </div>
        ) : (
          <div>
            <div className="text-[#e74c3c] font-bold mb-1">✗ Validation error(s):</div>
            <ul data-testid="errors" className="list-disc ml-5 text-[#e74c3c] text-sm">
              {result.errors.map(function (er, i) { return <li key={i}>{er}</li>; })}
            </ul>
          </div>
        )}
      </div>

      <h3 className="text-[#e6edf3] text-sm font-bold mb-2 mt-4">Pipeline: parse → coerce → validate → default</h3>
      <pre className="src">
{'?page=2&sort=desc&filter=react\n' +
 '   │  parse    (URLSearchParams → { page:"2", sort:"desc", filter:"react" })\n' +
 '   ▼\n' +
 '   │  coerce   (Number("2") → 2)\n' +
 '   ▼\n' +
 '   │  validate (2 >= min(1) ✓ · "desc" ∈ [asc,desc] ✓)\n' +
 '   ▼\n' +
 '   │  default  (missing keys → schema defaults)\n' +
 '   ▼\n' +
 '{ page: 2 (number), sort: "desc" (enum), filter: "react" (string) }'}
      </pre>
    </div>
  );
}

createRoot(document.getElementById('root')).render(<SearchValidationDemo/>);

2 · Babel compiles JSX → element tree

<SearchValidationDemo/> becomes React.createElement(SearchValidationDemo). The schema + validator run as plain JS on every keystroke; React only re-renders the verdict when the parsed input changes.

// (hit "compile & render" to see Babel's output)

3 · live search-param validator (proven)

Edit page / sort / filter above and watch the verdict flip. Try page=invalid (number error), sort=unknown (enum error), or clear a field (default applied). The gold-check drives all four cases automatically.

schema params: — · gold: valid(2) → number error → enum error → defaults(1)

intent → schema pattern

intent	pattern	why
required number param	`z.number().int().min(1)`	rejects non-numbers and out-of-range; no silent `"2"`
default when missing	`.default(1)`	applied only when the key is absent (parse-level)
recover when invalid	`fallback(z.number(), 1)` / `.catch(1)`	keeps the route alive instead of throwing to errorComponent
constrain to a set	`z.enum(['asc','desc'])`	type narrows to the union; unknown value → error
optional param	`.optional()`	omitted key → `undefined` (not an error)
read in a component	`route.useSearch()`	typed by the schema’s output; never raw strings
handle invalid URL	`errorComponent: ({{ error }}) => ...`	shown when validation throws; reset via `router.navigate`