{"id":47613263,"url":"https://github.com/tsoa-next/tsoa-next","last_synced_at":"2026-04-12T03:04:58.343Z","repository":{"id":340864636,"uuid":"1166769258","full_name":"tsoa-next/tsoa-next","owner":"tsoa-next","description":"Build type-safe OpenAPI APIs for Node.js using TypeScript decorators with automatic spec generation and validation","archived":false,"fork":false,"pushed_at":"2026-03-29T01:10:11.000Z","size":8186,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T01:12:39.931Z","etag":null,"topics":["api-framework","backend","code-generation","contract-first","decorators","express","koa","nodejs","openapi","rest-api","schema-validation","swagger","tsoa","tsoa-next","type-safe","typescript"],"latest_commit_sha":null,"homepage":"http://tsoa-next.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"lukeautry/tsoa","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tsoa-next.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-25T15:33:04.000Z","updated_at":"2026-03-28T21:07:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tsoa-next/tsoa-next","commit_stats":null,"previous_names":["vannadii/tsoa","vannadii/tsoa-next","tsoa-next/tsoa-next"],"tags_count":169,"template":false,"template_full_name":null,"purl":"pkg:github/tsoa-next/tsoa-next","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsoa-next%2Ftsoa-next","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsoa-next%2Ftsoa-next/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsoa-next%2Ftsoa-next/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsoa-next%2Ftsoa-next/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsoa-next","download_url":"https://codeload.github.com/tsoa-next/tsoa-next/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsoa-next%2Ftsoa-next/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["api-framework","backend","code-generation","contract-first","decorators","express","koa","nodejs","openapi","rest-api","schema-validation","swagger","tsoa","tsoa-next","type-safe","typescript"],"created_at":"2026-04-01T20:50:47.411Z","updated_at":"2026-04-12T03:04:58.334Z","avatar_url":"https://github.com/tsoa-next.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- This file is generated from README.template.MD by `npm run sync:readmes`. Do not edit directly. --\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://tsoa-next.dev/\" target=\"_blank\" rel=\"noreferrer\"\u003e\n    \u003ch1\u003e\n      \u003cspan style=\"display: inline-flex; align-items: center; gap: 0.35em; white-space: nowrap;\"\u003e\n        \u003cimg src=\"./assets/tsoa-next-logo-590.png\" alt=\"tsoa-next logo\" height=\"40\" style=\"height: 1em; width: auto;\" /\u003e\n        \u003cspan\u003etsoa-next\u003c/span\u003e\n      \u003c/span\u003e\n    \u003c/h1\u003e\n  \u003c/a\u003e\nPronounced so·uh\n\nOpenAPI-compliant REST APIs using TypeScript and Node\n\n[![build status](https://github.com/tsoa-next/tsoa-next/actions/workflows/runTestsOnPush.yml/badge.svg)](https://github.com/tsoa-next/tsoa-next/actions/workflows/runTestsOnPush.yml)\n[![npm version](https://img.shields.io/npm/v/tsoa-next/latest)](https://www.npmjs.com/package/tsoa-next)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=tsoa-next_tsoa-next\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=tsoa-next_tsoa-next)\n\n\u003c/div\u003e\n\n## Project Lineage\n\n`tsoa-next` continues the original [`tsoa`](https://github.com/lukeautry/tsoa) project.\nThe original repository and its contributors established the stable TypeScript-first and OpenAPI-first foundation this work builds on.\nWhere historical release notes or migration references still point upstream, they are kept intentionally for provenance.\n\n## Goal\n\n- TypeScript controllers and models as the single source of truth for your API\n- A valid OpenAPI (formerly Swagger) spec (2.0 or 3.0 if you choose 😍) is generated from your controllers and models, including:\n  - Paths (e.g. GET /users)\n  - Definitions based on TypeScript interfaces (models)\n  - Parameters/model properties marked as required or optional based on TypeScript (e.g. myProperty?: string is optional in the OpenAPI spec)\n  - jsDoc supported for object descriptions (most other metadata can be inferred from TypeScript types)\n- Routes are generated for middleware of choice\n  - Express, Hapi, and Koa currently supported, other middleware can be supported using a simple handlebars template\n  - Validate request payloads\n\n## Philosophy\n\n- Rely on TypeScript type annotations to generate API metadata if possible\n- If regular type annotations aren't an appropriate way to express metadata, use decorators\n- Use jsdoc for pure text metadata (e.g. endpoint descriptions)\n- Minimize boilerplate\n- Models are best represented by interfaces (pure data structures), but can also be represented by classes\n- Runtime validation of tsoa-next should behave as closely as possible to the specifications that the generated OpenAPI 2/3 schema describes. Any differences in validation logic are clarified by logging warnings during the generation of the OpenAPI Specification (OAS) and/or the routes.\n  - Please note that by enabling OpenAPI 3 you minimize the chances of divergent validation logic since OpenAPI 3 has a more expressive schema syntax.\n\n## External Validators\n\n`@Validate(...)` adds opt-in runtime authority for external schemas on supported controller method parameters.\n\n- Supported forms: `@Validate(schema)`, `@Validate('zod', schema)`, `@Validate({ kind: 'zod', schema })`\n- Supported libraries: `zod`, `joi`, `yup`, `superstruct`, `io-ts`\n- `io-ts` installs: add `fp-ts`, and add `io-ts-types` as well if you rely on helpers like `withMessage`\n- Supported parameter decorators: `@Body`, `@BodyProp`, `@Query`, `@Queries`, `@Path`, `@Header`, and `@FormField` / uploaded file params\n- Behavior: TypeScript metadata still drives OpenAPI generation, while the external schema replaces built-in runtime validation for the decorated parameter subtree\n- Compatibility: routes without `@Validate(...)` keep their current behavior\n\nGenerated `RegisterRoutes(...)` functions also accept an optional validation context so applications can provide translation or failure-formatting hooks:\n\n```ts\nRegisterRoutes(app, {\n  validation: {\n    translate: (key, params) =\u003e translateMessage(key, params),\n    errorFormatter: failure =\u003e failure,\n  },\n})\n```\n\n```ts\nimport * as t from 'io-ts'\nimport { withMessage } from 'io-ts-types'\nimport { Body, Controller, Post, Route, Validate } from 'tsoa-next'\n\ninterface PositiveFloatBrand {\n  readonly PositiveFloat: unique symbol\n}\n\nconst PositiveFloat = withMessage(\n  t.brand(t.number, (n): n is t.Branded\u003cnumber, PositiveFloatBrand\u003e =\u003e Number.isFinite(n) \u0026\u0026 n \u003e 0, 'PositiveFloat'),\n  () =\u003e 'validation.wager.amount.mustBePositiveFloat',\n)\n\nconst WagerCodec = t.type({\n  amount: PositiveFloat,\n  outcome: t.Int,\n})\n\ntype Wager = t.TypeOf\u003ctypeof WagerCodec\u003e\n\n@Route('wagers')\nexport class WagersController extends Controller {\n  @Post()\n  public createWager(\n    @Body()\n    @Validate('io-ts', WagerCodec)\n    wager: Wager,\n  ): Wager {\n    return wager\n  }\n}\n```\n\n## Migration Note\n\nThis feature is fully opt-in. If you do not use `@Validate(...)`, existing interface/class models, generated routes, validation behavior, and error responses are unchanged.\n\n## Getting Started\n\n- Requirements:\n  - Node.js 22 or newer\n  - npm 10 or newer\n  - We verify support across the previous LTS, current LTS, and Node vNext in CI\n- [Documentation](https://tsoa-next.dev/)\n- [API Reference](https://tsoa-next.dev/reference/)\n- [Getting started guide](https://tsoa-next.dev/getting-started)\n\n## Package Surface\n\n- Import decorators, runtime helpers, and generated route support from `tsoa-next`\n- Import programmatic generation APIs from `tsoa-next/cli`\n- Use the `tsoa` binary for CLI generation commands\n\n## Examples\n\nCheck out the [guides](https://tsoa-next.dev/)\n\nUse the companion [playground repository](https://github.com/tsoa-next/playground) for runnable example apps and server-focused scenarios.\n\nSee example controllers in [the tests](https://github.com/tsoa-next/tsoa-next/tree/main/tests/fixtures/controllers)\n\nSee example models in [the tests](https://github.com/tsoa-next/tsoa-next/blob/main/tests/fixtures/testModel.ts)\n\n## Help wanted\n\n### Contributing code\n\nTo contribute (via a PR), please first see the [Contributing Guide](https://github.com/tsoa-next/tsoa-next/blob/main/docs/CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsoa-next%2Ftsoa-next","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsoa-next%2Ftsoa-next","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsoa-next%2Ftsoa-next/lists"}