{"id":36502263,"url":"https://github.com/typified-web/request","last_synced_at":"2026-01-12T02:24:01.988Z","repository":{"id":57168668,"uuid":"413248245","full_name":"typified-web/request","owner":"typified-web","description":"Add types to your http client with almost zero runtime cost.","archived":false,"fork":false,"pushed_at":"2021-10-17T13:11:18.000Z","size":163,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-05T13:51:33.263Z","etag":null,"topics":["http","request","typescript"],"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/typified-web.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-10-04T02:15:15.000Z","updated_at":"2021-10-17T13:11:20.000Z","dependencies_parsed_at":"2022-09-12T21:22:54.857Z","dependency_job_id":null,"html_url":"https://github.com/typified-web/request","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/typified-web/request","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typified-web%2Frequest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typified-web%2Frequest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typified-web%2Frequest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typified-web%2Frequest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/typified-web","download_url":"https://codeload.github.com/typified-web/request/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typified-web%2Frequest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28332245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"online","status_checked_at":"2026-01-12T02:00:08.677Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["http","request","typescript"],"created_at":"2026-01-12T02:23:57.587Z","updated_at":"2026-01-12T02:24:01.979Z","avatar_url":"https://github.com/typified-web.png","language":"TypeScript","readme":"# @typified-web/request\n\nA tiny request library to provide compile-time type-safe with your API specification.\n\n## Features\n\n- Types for each API calls with simple declarations for API,\n\n  which means:\n\n  - Code completion by API declarations with supported editor (like VSCode).\n\n  - Type validation at compile-time (design-time).\n\n- Natural API to request resources.\n\n- Tiny footprint for runtime of browser and NodeJS (about **4kb** uncompressed).\n\n## Getting Started\n\nInstallation via npm:\n\n```shell\nnpm i @typified-web/request\n```\n\nDeclare your API. E.g. the `GET /greet/:name` end point:\n\n```typescript\ntype YourAPI = {\n  '/greet/:name': {\n    get: {\n      input: {\n        route: {\n          name: string;\n        };\n      };\n      output: {\n        body: {\n          resCode: string;\n          result: {\n            name: string;\n          };\n        };\n      };\n    };\n  };\n};\n```\n\nThen create your API request client:\n\n```typescript\nimport { createRequest } from '@typified-web/request';\n\n// the decorated reuqest function.\nexport default createRequest\u003cYourAPI\u003e();\n```\n\n\u003e If you're using NodeJS, install `node-fetch` to provide the `fetch` implementation, like:\n\u003e\n\u003e ```typescript\n\u003e import fetch from 'node-fetch';\n\u003e\n\u003e export default createRequest\u003cYourAPI\u003e({\n\u003e   fetch: (path, opt) =\u003e {\n\u003e     return fetch(`${host}${path}`, opt);\n\u003e   },\n\u003e });\n\u003e ```\n\nThen, you can use it anywhere you like via `import` and get auto completion and validation for each request:\n\n```typescript\nimport request from './the/newly/created/request';\n\n// send a request.\nrequest.endpoint('/greet/:name').get({ route: { name: 'Jack' } });\n```\n\nCode-completion and type validation works like a charm.\n\n## API\n\nThe API includes two parts: the API declaration for design-time and the decorated request client for runtime.\n\n### API declaration\n\nThe API definition is like the Open API specification, but in a more simpler form of typescript declarations.\n\n```typescript\nexport type APISpec = {\n  // URL or path of the API endpoint.\n  [path: string]: {\n    // HTTP Methods.\n    [M in Method]?: {\n      // Request Specification.\n      input?: {\n        // Path parameters\n        route?: PathParameter;\n        // Path parameters\n        query?: PathParameter;\n        // Headers\n        headers?: Record\u003cstring, string\u003e;\n        // Request body.\n        body?: Json;\n      };\n      // Response Specification.\n      output: {\n        headers?: Record\u003cstring, string\u003e;\n        body?: Json;\n      };\n    };\n  };\n};\n```\n\nThe declaration is just for design-time only and will be swiped in runtime. That's why we call it almost **zero-overhead**.\n\n\u003e **Too large for a single API declaration?**\n\u003e\n\u003e You can split your API declaration into several types and use intersection type to join them together.\n\u003e\n\u003e e.g.\n\u003e\n\u003e ```typescript\n\u003e // first part of API declaration.\n\u003e type YourAPI_1 = {\n\u003e   '/greet/:name': {\n\u003e     get: {\n\u003e       input: {\n\u003e         route: {\n\u003e           name: string;\n\u003e         };\n\u003e       };\n\u003e       output: {\n\u003e         body: {\n\u003e           resCode: string;\n\u003e           result: {\n\u003e             name: string;\n\u003e           };\n\u003e         };\n\u003e       };\n\u003e     };\n\u003e   };\n\u003e };\n\u003e\n\u003e // second part of API declaration.\n\u003e type YourAPI_2 = {\n\u003e   '/say-hello/:name': {\n\u003e     get: {\n\u003e       input: {\n\u003e         route: {\n\u003e           name: string;\n\u003e         };\n\u003e       };\n\u003e       output: {\n\u003e         body: {\n\u003e           resCode: string;\n\u003e           result: {\n\u003e             name: string;\n\u003e           };\n\u003e         };\n\u003e       };\n\u003e     };\n\u003e   };\n\u003e };\n\u003e\n\u003e // join them with type intersection.\n\u003e export type API = YourAPI_1 \u0026 YourAPI_2;\n\u003e ```\n\n### The request client\n\nTo create a request client, you can specify your customized fetch implemenation for easy extention:\n\n```typescript\nimport fetch from 'node-fetch';\n\nconst request = createRequest\u003cYourAPI\u003e({\n  fetch: (path, opt) =\u003e {\n    return fetch(`${host}${path}`, opt);\n  },\n});\n```\n\nThe request client itself is complicatedly typed as it uses generics massively.\n\nHowever, the usage is quite simple.\n\n```typescript\nrequest.endpoint('PATH').method({ params });\n```\n\nThe path is the resource key defined in your API specification and method is the supported method(`get`/`post`/`put`/`patch`/`delete`) for your endpoint declaration. The parameters will be inferred for you.\n\n## Limitations\n\nIt just add type declarations to the JSON-like API, which means the input and output are mostly JSON. Anything outside the JSON-like API is not considered well.\n\nHelp is welcomed!\n\n## License\n\nMIT.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypified-web%2Frequest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypified-web%2Frequest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypified-web%2Frequest/lists"}