{"id":22382479,"url":"https://github.com/jcoreio/zod-route-schemas","last_synced_at":"2025-03-26T19:41:01.376Z","repository":{"id":227152213,"uuid":"765517750","full_name":"jcoreio/zod-route-schemas","owner":"jcoreio","description":"Utility for parsing URL routes with typesafe parameters","archived":false,"fork":false,"pushed_at":"2025-01-21T06:50:19.000Z","size":187,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-01T01:41:37.804Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jcoreio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-01T04:24:31.000Z","updated_at":"2025-01-21T06:49:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"a8d29299-148e-4491-9fbd-afa97528e00c","html_url":"https://github.com/jcoreio/zod-route-schemas","commit_stats":null,"previous_names":["jcoreio/zod-route-schemas"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fzod-route-schemas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fzod-route-schemas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fzod-route-schemas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fzod-route-schemas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jcoreio","download_url":"https://codeload.github.com/jcoreio/zod-route-schemas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245726837,"owners_count":20662545,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-05T00:13:12.044Z","updated_at":"2025-03-26T19:41:01.354Z","avatar_url":"https://github.com/jcoreio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zod-route-schemas\n\n[![CircleCI](https://circleci.com/gh/jcoreio/zod-route-schemas.svg?style=svg)](https://circleci.com/gh/jcoreio/zod-route-schemas)\n[![Coverage Status](https://codecov.io/gh/jcoreio/zod-route-schemas/branch/master/graph/badge.svg)](https://codecov.io/gh/jcoreio/zod-route-schemas)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n[![npm version](https://badge.fury.io/js/zod-route-schemas.svg)](https://badge.fury.io/js/zod-route-schemas)\n\nUtility for parsing URL routes with typesafe parameters\n\n# Intro\n\nMany routing libraries like `react-router` allow you to define\nroute patterns with parameters like `/users/:userId`, but they\ndon't validate or parse the parameters, like if `userId` must\nbe a number.\n\n`zod-route-schemas` allows you to validate and parse the parameters\naccording to a zod schema:\n\n```ts\nimport z from 'zod'\nimport ZodRoute from 'zod-route-schemas'\n\nconst usersRoute = new ZodRoute(\n  '/users/:userId',\n  z.object({\n    // ZodRoute type magic requires this schema to have a userId property!\n    userId: z\n      .string()\n      .regex(/^\\d+$/)\n      .transform((s) =\u003e parseInt(s)),\n  })\n)\n\nconst params: { userId: number } = usersRoute.parse('/users/23') // type safe!\n```\n\n# API\n\n## Patterns\n\nA pattern should be a valid URL path (this is not strictly enforced at the moment).\nAny path segment (part delimited by `/`) that starts with `:` is a _parameter_. For example the path\n`/org/:orgId/dashboards/:dashboardId` has two parameters, `orgId` and `dashboardId`.\n\nYou can mark a path segment optional (whether it's a parameter or not) with a trailing `?`.\nFor example `/settings/account?/password` matches `/settings/account/password` or `/settings/account`,\nand `/users/:userId` matches `/users` or `/users/dude` with `userId: 'dude'`.\n\n## `class ZodRoute`\n\n```ts\nimport ZodRoute from 'zod-route-schemas'\n```\n\n```ts\nclass ZodRoute\u003c\n  Pattern extends string,\n  Schema extends SchemaForPattern\u003cPattern\u003e,\n  FormatSchema extends InvertSchema\u003cSchema\u003e = InvertSchema\u003cSchema\u003e\n\u003e\n```\n\n### `constructor(pattern, schema, [options])`\n\n`constructor(pattern: Pattern, schema: Schema, options?: { formatSchema?: FormatSchema, partialFormatSchema?: PartialFormatSchema })`\n\nCreates a `ZodRoute`. The `schema` must accept an object as input with all parameters\nfrom `pattern` as `string`-valued properties.\n\n`schema` is used to parse the parameters in `.parse()`/`.safeParse()`.\n\n`formatSchema` is optional, and is used to transform the output parameter values back\nto the raw string values in `.format()`.\nonly accepts an object with `string`, `number`, `boolean`, `null`, or `undefined` values,\nand `String()`ifies them.\n\n`partialFormatSchema` is optional, and is used to transform the output parameter values back\nto the raw string values in `.partialFormat()`.\n\n### `pattern: Pattern`\n\nThe pattern for this route.\n\n### `schema: Schema`\n\nThe schema for parsing this route's parameters in `.parse()`/`.safeParse()`\n\n### `formatSchema: FormatSchema`\n\nThe schema for formatting this route's parameters in `.format()`/`.partialFormat()`.\n\n### `safeParse(path)`\n\n`safeParse(path: string): z.SafeParseReturnType\u003cz.input\u003cSchema\u003e, z.output\u003cSchema\u003e\u003e`\n\nParses the given `path`. If it matches the `pattern`,\nreturns `{ success: true, data: z.output\u003cSchema\u003e }`.\nOtherwise, returns `{ success: false, error: ZodError }`\n\n### `parse(path)`\n\n`parse(path: string): z.output\u003cSchema\u003e`\n\nParses the given `path`, returning the parsed parameters.\nIf `path` doesn't match the `pattern` or `schema`, throws a `ZodError`.\n\n### `format(params)`\n\n`format(params: z.output\u003cSchema\u003e): BindParams\u003cPattern, z.output\u003cSchema\u003e`\n\nCreates a path from the given `params`. If `formatSchema`\ncan't parse the `params`, throws an error. The return type\ncan be computed exactly if the `params` are passed `as const`\nand have only primitive values.\n\n### `partialFormat(params)`\n\n`partialFormat\u003cP extends Partial\u003cz.output\u003cSchema\u003e\u003e\u003e(params: P): BindParams\u003cPattern, P\u003e`\n\nCreates a path or pattern from the given `params`. If a\nparameter is omitted, the corresponding path segment\n(starting with `:`) will be preserved in the returned\npattern.\n\n### `extend(subpattern, subschema, [formatSubschema])`\n\n```\nextend\u003c\n  Subpattern extends string,\n  Subschema extends SchemaForPattern\u003cSubpattern\u003e,\n  FormatSubschema extends InvertSchema\u003cSubschema\u003e = InvertSchema\u003cSubschema\u003e\n\u003e(\n  subpattern: Subpattern,\n  subschema: Subschema,\n  formatSubschema: FormatSubschema = defaultFormatSchema as any\n): ZodRoute\u003c\n  `${Pattern}/${Subpattern}`,\n  z.ZodIntersection\u003cSchema, Subschema\u003e,\n  z.ZodIntersection\u003cFormatSchema, FormatSubschema\u003e\n\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcoreio%2Fzod-route-schemas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjcoreio%2Fzod-route-schemas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcoreio%2Fzod-route-schemas/lists"}