{"id":14986484,"url":"https://github.com/jcwillox/typebox-x","last_synced_at":"2025-07-31T22:04:47.085Z","repository":{"id":249210503,"uuid":"828528332","full_name":"jcwillox/typebox-x","owner":"jcwillox","description":"Tools for working with TypeBox","archived":false,"fork":false,"pushed_at":"2025-04-03T19:04:41.000Z","size":135,"stargazers_count":4,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-03T20:22:22.480Z","etag":null,"topics":["nestjs","openapi","typebox","typescript","validation"],"latest_commit_sha":null,"homepage":"https://npmjs.com/@jcwillox/typebox-x","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/jcwillox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-07-14T12:30:20.000Z","updated_at":"2025-04-03T14:52:32.000Z","dependencies_parsed_at":"2024-10-24T22:59:48.948Z","dependency_job_id":"d2b05e5c-c13d-458a-b0bc-712840180d32","html_url":"https://github.com/jcwillox/typebox-x","commit_stats":{"total_commits":57,"total_committers":2,"mean_commits":28.5,"dds":"0.14035087719298245","last_synced_commit":"cf2bac5d0471496dcb45f20ef696d93351c98fc4"},"previous_names":["jcwillox/typebox-x"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcwillox%2Ftypebox-x","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcwillox%2Ftypebox-x/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcwillox%2Ftypebox-x/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcwillox%2Ftypebox-x/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jcwillox","download_url":"https://codeload.github.com/jcwillox/typebox-x/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248482932,"owners_count":21111402,"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":["nestjs","openapi","typebox","typescript","validation"],"created_at":"2024-09-24T14:12:56.696Z","updated_at":"2025-04-11T21:31:19.935Z","avatar_url":"https://github.com/jcwillox.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TypeBox Extensions\n\n[![License](https://img.shields.io/github/license/jcwillox/typebox-x?style=flat-square)](https://github.com/jcwillox/typebox-x/blob/main/LICENSE)\n[![Version](https://img.shields.io/npm/v/@jcwillox/typebox-x?style=flat-square)](https://www.npmjs.com/package/@jcwillox/typebox-x)\n[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@jcwillox/typebox-x?style=flat-square)](https://bundlephobia.com/package/@jcwillox/typebox-x)\n[![Publish Size](https://flat.badgen.net/packagephobia/publish/@jcwillox/typebox-x)](https://packagephobia.com/result?p=@jcwillox/typebox-x)\n[![Code style](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)\n\nTypeBox extensions (typebox-x) is a utility library based around the [sinclairzx81/typebox](https://github.com/sinclairzx81/typebox) schema builder and validation library.\n\n**Features**\n\n- Validate and coerce environment variables (like [t3-env](https://env.t3.gg/docs/introduction)).\n- Additional kinds and shorthands, e.g. `t.UUID`.\n- Built in configuration for common formats, e.g. `date`, `email`, `uri`.\n- Built in support for [NestJS](https://nestjs.com)\n\n## Install\n\n```bash\npnpm add @jcwillox/typebox-x @sinclair/typebox\n```\n\n## Load envs\n\nFirst import the `createEnv` function, then pass it a typebox schema.\n\nThe `createEnv` function uses the clean, convert, default and decode function from typebox to parse you environment variables.\n\nThis means that it will strip extra keys, set default values, attempt to convert values to the destination type, e.g. `\"true\" -\u003e true`, and then decode/check the value.\n\n```ts\nimport { createEnv } from \"@jcwillox/typebox-x\";\n\nconst env = createEnv(\n  t.Object({\n    APP_ENV: t.Optional(t.String()),\n    NODE_ENV: t.String({ default: \"development\" }),\n    BOOL_FLAG: t.Boolean(),\n  }),\n);\n\nconsole.log(env.BOOL_FLAG === true); // -\u003e true\n```\n\n## Variants\n\n**Nullable**\n\n- Wraps schema in a union with null.\n  ```ts\n  t.Nullable(t.String());\n  // t.Union([t.String(), t.Null()]);\n  ```\n\n**Nullish**\n\n- Wraps schema in an optional union with null.\n  ```ts\n  t.Nullish(t.String());\n  // t.Optional(t.Union([t.String(), t.Null()]));\n  ```\n\n**UUID**\n\n- Shorthand for string of format `uuid`.\n  ```ts\n  t.UUID();\n  // t.String({ format: \"uuid\" })\n  ```\n\n**DateString**\n\n- Uses `Transform` to convert a string to a `Date` object when decoding and from a `Date` object to a string when encoding.\n  ```ts\n  t.DateString();\n  ```\n\n**RecordString**\n\n- A replacement for `t.Record` that uses `t.String` as the key type, and adds the `additionalProperties` property, for backwards compatibility with OpenAPI 3.0.\n  ```ts\n  t.RecordString(t.Object({ one: t.String() }));\n  // Record\u003cstring, {a: string}\u003e\n  ```\n  Equivalent to:\n  ```ts\n  t.Record(t.String(), schema, {\n    additionalProperties: schema,\n  });\n  ```\n\n**StringEnum**\n\n- Creates a union of strings with a `enum` schema representation\n  ```ts\n  t.StringEnum([\"one\", \"two\"]);\n  ```\n\n**LiteralEnum**\n\n- Drop-in replacement for `t.Literal` that adds the `type` and `enum` properties, for backwards compatibility with OpenAPI 3.0.\n- You should override `Literal` with this function, for OpenAPI 3.0 compatibility.\n  ```ts\n  t.LiteralEnum(\"one\");\n  ```\n\n## Formats\n\nSimply import `@jcwillox/typebox-x/formats` before you perform any validations, usually you'll want to do this in you entrypoint. If a format is already defined with the same name, it will not be overwritten.\n\n```ts\nimport \"@jcwillox/typebox-x/formats\";\n```\n\n## NestJS\n\nUse the typebox prefixed method decorators and provide the corresponding schemas.\n\n```ts\nimport { Controller } from \"@nestjs/common\";\nimport { t } from \"@jcwillox/typebox-x\";\nimport { TypeboxGet } from \"@jcwillox/typebox-x/nestjs\";\n// or if you prefer we also export non-prefixed methods\n// import { Get } from \"@jcwillox/typebox-x/nestjs\";\n\n@Controller()\nexport class AppController {\n  @TypeboxGet(\":my_id\", {\n    query: t.Object({\n      limit: t.Optional(t.Integer({ default: 10 })),\n    }),\n    params: {\n      my_id: t.UUID(),\n    },\n    response: t.Object({\n      message: t.String(),\n    }),\n  })\n  getHello() {\n    return { message: \"Hello World!\" };\n  }\n}\n```\n\nYou'll likely want to define your schemas outside the `@TypeboxGet` decorator, so you can also infer types from them,\nusing `Static\u003ctypeof schema\u003e`.\n\n```ts\nimport { Controller, Param, Query } from \"@nestjs/common\";\nimport { t } from \"@jcwillox/typebox-x\";\nimport { TypeboxGet } from \"@jcwillox/typebox-x/nestjs\";\nimport { Static } from \"@sinclair/typebox\";\n\ntype Query = Static\u003ctypeof QuerySchema\u003e;\nconst QuerySchema = t.Object({\n  limit: t.Optional(t.Integer({ default: 10 })),\n});\n\ntype Response = Static\u003ctypeof ResponseSchema\u003e;\nconst ResponseSchema = t.Object({\n  message: t.String(),\n});\n\n@Controller()\nexport class AppController {\n  @TypeboxGet(\":my_id\", {\n    query: QuerySchema,\n    params: { my_id: t.UUID() },\n    response: ResponseSchema,\n  })\n  getHello(@Param(\"my_id\") myId: string, @Query() query: Query): Response {\n    return { message: \"Hello World!\" };\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcwillox%2Ftypebox-x","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjcwillox%2Ftypebox-x","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcwillox%2Ftypebox-x/lists"}