https://github.com/jcoreio/zod-route-schemas
Utility for parsing URL routes with typesafe parameters
https://github.com/jcoreio/zod-route-schemas
Last synced: about 1 year ago
JSON representation
Utility for parsing URL routes with typesafe parameters
- Host: GitHub
- URL: https://github.com/jcoreio/zod-route-schemas
- Owner: jcoreio
- License: mit
- Created: 2024-03-01T04:24:31.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2025-01-21T06:50:19.000Z (over 1 year ago)
- Last Synced: 2025-02-01T01:41:37.804Z (over 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 183 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# zod-route-schemas
[](https://circleci.com/gh/jcoreio/zod-route-schemas)
[](https://codecov.io/gh/jcoreio/zod-route-schemas)
[](https://github.com/semantic-release/semantic-release)
[](http://commitizen.github.io/cz-cli/)
[](https://badge.fury.io/js/zod-route-schemas)
Utility for parsing URL routes with typesafe parameters
# Intro
Many routing libraries like `react-router` allow you to define
route patterns with parameters like `/users/:userId`, but they
don't validate or parse the parameters, like if `userId` must
be a number.
`zod-route-schemas` allows you to validate and parse the parameters
according to a zod schema:
```ts
import z from 'zod'
import ZodRoute from 'zod-route-schemas'
const usersRoute = new ZodRoute(
'/users/:userId',
z.object({
// ZodRoute type magic requires this schema to have a userId property!
userId: z
.string()
.regex(/^\d+$/)
.transform((s) => parseInt(s)),
})
)
const params: { userId: number } = usersRoute.parse('/users/23') // type safe!
```
# API
## Patterns
A pattern should be a valid URL path (this is not strictly enforced at the moment).
Any path segment (part delimited by `/`) that starts with `:` is a _parameter_. For example the path
`/org/:orgId/dashboards/:dashboardId` has two parameters, `orgId` and `dashboardId`.
You can mark a path segment optional (whether it's a parameter or not) with a trailing `?`.
For example `/settings/account?/password` matches `/settings/account/password` or `/settings/account`,
and `/users/:userId` matches `/users` or `/users/dude` with `userId: 'dude'`.
## `class ZodRoute`
```ts
import ZodRoute from 'zod-route-schemas'
```
```ts
class ZodRoute<
Pattern extends string,
Schema extends SchemaForPattern,
FormatSchema extends InvertSchema = InvertSchema
>
```
### `constructor(pattern, schema, [options])`
`constructor(pattern: Pattern, schema: Schema, options?: { formatSchema?: FormatSchema, partialFormatSchema?: PartialFormatSchema })`
Creates a `ZodRoute`. The `schema` must accept an object as input with all parameters
from `pattern` as `string`-valued properties.
`schema` is used to parse the parameters in `.parse()`/`.safeParse()`.
`formatSchema` is optional, and is used to transform the output parameter values back
to the raw string values in `.format()`.
only accepts an object with `string`, `number`, `boolean`, `null`, or `undefined` values,
and `String()`ifies them.
`partialFormatSchema` is optional, and is used to transform the output parameter values back
to the raw string values in `.partialFormat()`.
### `pattern: Pattern`
The pattern for this route.
### `schema: Schema`
The schema for parsing this route's parameters in `.parse()`/`.safeParse()`
### `formatSchema: FormatSchema`
The schema for formatting this route's parameters in `.format()`/`.partialFormat()`.
### `safeParse(path)`
`safeParse(path: string): z.SafeParseReturnType, z.output>`
Parses the given `path`. If it matches the `pattern`,
returns `{ success: true, data: z.output }`.
Otherwise, returns `{ success: false, error: ZodError }`
### `parse(path)`
`parse(path: string): z.output`
Parses the given `path`, returning the parsed parameters.
If `path` doesn't match the `pattern` or `schema`, throws a `ZodError`.
### `format(params)`
`format(params: z.output): BindParams`
Creates a path from the given `params`. If `formatSchema`
can't parse the `params`, throws an error. The return type
can be computed exactly if the `params` are passed `as const`
and have only primitive values.
### `partialFormat(params)`
`partialFormat
>>(params: P): BindParams`
Creates a path or pattern from the given `params`. If a
parameter is omitted, the corresponding path segment
(starting with `:`) will be preserved in the returned
pattern.
### `extend(subpattern, subschema, [formatSubschema])`
```
extend<
Subpattern extends string,
Subschema extends SchemaForPattern,
FormatSubschema extends InvertSchema = InvertSchema
>(
subpattern: Subpattern,
subschema: Subschema,
formatSubschema: FormatSubschema = defaultFormatSchema as any
): ZodRoute<
`${Pattern}/${Subpattern}`,
z.ZodIntersection,
z.ZodIntersection
>
```