{"id":23701254,"url":"https://github.com/sinclairnick/spec-dts","last_synced_at":"2025-07-05T19:03:43.459Z","repository":{"id":269357333,"uuid":"907159103","full_name":"sinclairnick/spec-dts","owner":"sinclairnick","description":"OpenAPI type inference without the codegen","archived":false,"fork":false,"pushed_at":"2024-12-23T01:07:09.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-30T09:35:13.247Z","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/sinclairnick.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-12-23T00:55:27.000Z","updated_at":"2024-12-23T01:07:12.000Z","dependencies_parsed_at":"2024-12-23T01:31:31.238Z","dependency_job_id":"49378075-d610-47cc-86db-a16e1cd50144","html_url":"https://github.com/sinclairnick/spec-dts","commit_stats":null,"previous_names":["sinclairnick/spec-dts"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinclairnick%2Fspec-dts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinclairnick%2Fspec-dts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinclairnick%2Fspec-dts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinclairnick%2Fspec-dts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sinclairnick","download_url":"https://codeload.github.com/sinclairnick/spec-dts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239776718,"owners_count":19695158,"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-30T09:35:15.580Z","updated_at":"2025-02-20T04:27:29.282Z","avatar_url":"https://github.com/sinclairnick.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spec-dts\n\nSpec-dts enables inferring the types from an OpenAPI spec without any code generation – just good old TypeScript type inference.\n\n```sh\nnpm i spec-dts\n```\n\n## Features\n\n- [x] Infer OpenAPI types from a JSON spec\n- [x] No code generation\n- [x] Simple API and usage\n\n## Example Usage\n\n```ts\nimport { ParseSpec } from \"spec-dts\";\n\n// Import from file\nimport type { Spec } from \"spec.d.ts\n\n// Or:\ntype Spec = {\n    // JSON spec here\n};\n\ntype Api = ParseSpec\u003cSpec\u003e;\n\ntype GetPostsResult = Api[\"GET /posts\"][\"Output\"]\n```\n\n## Table of Contents\n\n- [Why?](#why)\n- [How?](#how)\n- [API Reference](#api-reference)\n  - [`ParseSpec\u003cT\u003e`](#parsespect)\n  - [`Parse[Part]\u003cT\u003e`](#parsext)\n\n## Why?\n\nWhen consuming APIs that offer an OpenAPI spec, we're forced to use bloated code generators which rarely fit our needs and frequently get in the way, undermining the utility of OpenAPI specs. Spec-dts offers a lightweight, types-only approach for utilising contracts defined in OpenAPI specs.\n\n## How?\n\nBy representing an OpenAPI spec in `.d.ts` form, we can run type inference on it directly, without any code generation.\n\n\u003e Spec-dts is compatible with the [Unclient](https://github.com/sinclairnick/unclient) package.\n\n## API Reference\n\n### `ParseSpec\u003cT\u003e`\n\n\u003e Derive an API definition from an OpenAPI Spec\n\nWe can directly infer the types of a JSON OpenAPI spec using the `ParseSpec\u003cT\u003e` type utility.\n\n```ts\ntype API = ParseSpec\u003c{\n  // OpenAPI JSON\n}\u003e;\n\ntype GetPostsOperation = API[\"GET /posts\"];\n// { Query, Params, Headers, Body, Output }\n```\n\nWe can directly paste in the OpenAPI contents here, considering JSON constitutes a valid TypeScript type.\n\n#### More Scalable Approach\n\nManually pasting the document will suffice for many applications, but if we want to make this more automatic, we can simply fetch our OpenAPI document and save it in a `spec.d.ts` file (or any other name).\n\nA simple unix shell script to do this could look like:\n\n```sh\ncurl -s \"\u003cyour-openapi-url\u003e\" |\\ # Get openapi spec\n \tsed 's/`/\\\\`/g' |\\ # Escape backticks\n  awk '{print \"export type Spec = `\"$0\"`;\"}' \u003e\u003e spec.d.ts # Save to file\n```\n\n### `Parse[Part]\u003cT\u003e`\n\nOn top of parsing the entire spec, we can parse individual parts, like schema, params or operations. These are the internally used types used to parse the spec as a whole.\n\n```ts\nimport {\n  // Schema\n  ParseSchema,\n  ParseSchemaObject,\n  ParseSchemaReference,\n\n  // Primitives\n  ParseObject,\n  ParseArray,\n  ParseString,\n  ParseBoolean,\n  ParseNumber,\n  ParseNull,\n  ParseUnion,\n  ParseIntersection,\n\n  // Parameters\n  ParseParameter,\n  ParseParameters,\n  ParseParameterReference,\n  ParseParameterObject,\n\n  // Body/Response\n  ParseBody,\n  ParseResponse,\n  ParseResponses,\n  ParseBodyOrResponseReference,\n  ParseBodyOrResponseObject,\n\n  // Operations\n  ParseOperation,\n  ParsePath,\n} from \"schema-dts\";\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinclairnick%2Fspec-dts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsinclairnick%2Fspec-dts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinclairnick%2Fspec-dts/lists"}