https://github.com/falkz/zod-search-params
Type-safe URL search parameters using Zod schemas
https://github.com/falkz/zod-search-params
query-params-parsing url-search-params zod zod-validation
Last synced: 5 months ago
JSON representation
Type-safe URL search parameters using Zod schemas
- Host: GitHub
- URL: https://github.com/falkz/zod-search-params
- Owner: FalkZ
- License: mit
- Created: 2025-06-18T10:54:48.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-06-18T19:26:46.000Z (12 months ago)
- Last Synced: 2025-06-18T20:28:31.263Z (12 months ago)
- Topics: query-params-parsing, url-search-params, zod, zod-validation
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@falkz/zod-search-params
- Size: 30.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @falkz/zod-search-params
Type-safe URL search parameters using Zod schemas.
## Installation
```bash
npm install @falkz/zod-search-params zod
```
## Quick Start
```typescript
import { z } from "zod/v4";
import { searchParamsObject, toSearchParams } from "@falkz/zod-search-params";
const schema = searchParamsObject({
query: z.string(),
page: z.number(),
limit: z.number().optional(),
active: z.boolean(),
});
// Parse
const params = schema.parse("?query=hello&page=1&active=true");
// { query: 'hello', page: 1, limit: undefined, active: true }
// Serialize
const urlParams = toSearchParams({ query: "world", page: 2, active: false });
// URLSearchParams { 'query' => 'world', 'page' => '2' }
```
## API
### Creating a Schema
`searchParamsObject()` behaves the same way as `z.object()`. This means as long as you use [supported values](#supported) you can create the schema in the same way as you are used to from zod.
```typescript
import { z } from "zod/v4";
import { searchParamsObject } from "@falkz/zod-search-params";
const schema = searchParamsObject({
name: z.string(),
age: z.number(),
active: z.boolean().optional(),
});
type InferredType = z.infer;
const typedObject = schema.parse("name=john&age=25&active=true");
// or
const typedObject = schema.parse(new URLSearchParams("name=john&age=25"));
// or
const typedObject = schema.parse(window.location.search);
```
### Supported Values
These are all the values the `searchParamsObject` accepts:
- [`z.string()`, `z.number()`, `z.bigint()`, `z.boolean()`](https://zod.dev/api#primitives)
- [`z.literal()`](https://zod.dev/api#literals)
- [`z.email()`, `z.url()`, `z.uuid()`, etc.](https://zod.dev/api#string-formats)
- [`z.enum()`](https://zod.dev/api#enums)
- [`z.templateLiteral()`](https://zod.dev/api#template-literals)
- [`.optional()` modifier](https://zod.dev/api#optionals)
If the value is not supported, typescript will let you know that you passed in a value that does not work.
### Serializing to URLSearchParams
`toSearchParams` converts an object to URLSearchParams. When parsed again by `searchParamsObject` the same object will be recreated.
```typescript
import { toSearchParams } from "@falkz/zod-search-params";
// create new params:
const params = toSearchParams({
query: "hello",
page: 1,
active: true,
disabled: false,
empty: undefined,
});
// or update existing params:
const updatedParams = toSearchParams(
{
query: "hello",
page: 1,
active: true,
disabled: false,
empty: undefined,
},
window.location.search,
);
```