{"id":15527345,"url":"https://github.com/r2don/nest-http-interface","last_synced_at":"2025-04-23T12:25:55.442Z","repository":{"id":154038821,"uuid":"624835783","full_name":"r2don/nest-http-interface","owner":"r2don","description":"HTTP client for Nest framework, inspired by HTTP interface in Spring 6","archived":false,"fork":false,"pushed_at":"2023-10-22T02:52:23.000Z","size":579,"stargazers_count":17,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T23:32:10.283Z","etag":null,"topics":["http-client","http-interface","http-request","nestjs"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@r2don/nest-http-interface","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/r2don.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":"2023-04-07T11:26:14.000Z","updated_at":"2024-07-29T14:03:08.000Z","dependencies_parsed_at":"2023-07-02T21:30:36.959Z","dependency_job_id":"f86515e6-6a87-4fc8-8bb5-c9dc524d4974","html_url":"https://github.com/r2don/nest-http-interface","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r2don%2Fnest-http-interface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r2don%2Fnest-http-interface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r2don%2Fnest-http-interface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r2don%2Fnest-http-interface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r2don","download_url":"https://codeload.github.com/r2don/nest-http-interface/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250432436,"owners_count":21429670,"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":["http-client","http-interface","http-request","nestjs"],"created_at":"2024-10-02T11:05:40.217Z","updated_at":"2025-04-23T12:25:55.387Z","avatar_url":"https://github.com/r2don.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://nestjs.com\"\u003e\u003cimg src=\"https://nestjs.com/img/logo_text.svg\" alt=\"Nest Logo\" width=\"320\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# nest-http-interface\n\n[![npm version](https://badge.fury.io/js/@r2don%2Fnest-http-interface.svg)](https://badge.fury.io/js/@r2don%2Fnest-http-interface)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=r2don_nest-http-interface\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=r2don_nest-http-interface)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=r2don_nest-http-interface\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=r2don_nest-http-interface)\n\nThis library is inspired by the HTTP interface in Spring 6 and provides a similar API for Nest.js.\n\n## Features\n\n- Provides a simplified and declarative way of creating HTTP services.\n- Supports both REST and GraphQL requests.\n- Provides a concise syntax for handling query parameters, path variables, request headers, request bodies, and forms.\n- Offers integration with [class-transformer](https://github.com/typestack/class-transformer) to facilitate data\n  transformation.\n- Support both promise and observable.\n- Circuit breaker support\n\n## Requirements\n\n- Node.js \n    - 18 or later if `HttpClient` is not specified (default: `fetch`)\n    - if custom `HttpClient` is provided, you can use lower version of Node.js\n- Nest.js 8 or later\n\n## Installation\n\n```bash\n$ npm install @r2don/nest-http-interface\n```\n\nIf you have not installed `class-transformer`, you need to install it:\n\n```bash\n$ npm install class-transformer\n```\n\n## Usage\n\nFirst, the module we created must be imported into `AppModule.ts`:\n\n```ts\nimport { Module } from '@nestjs/common';\nimport { HttpInterfaceModule } from '@r2don/nest-http-interface';\n\n@Module({\n  imports: [HttpInterfaceModule.forRoot()],\n})\nexport class AppModule {}\n```\n\nThen, you need to create the desired HTTP service and specify several decorators:\n\n```ts\nimport {\n  HttpInterface,\n  GetExchange,\n  ResponseBody,\n  imitation,\n  PathVariable,\n} from '@r2don/nest-http-interface';\n\n@HttpInterface('https://example.com/api') // base url\nclass UserHttpService {\n  @GetExchange('/users/{id}') // path\n  @ResponseBody(UserResponse) // response dto\n  async request(@PathVariable('id') id: number): Promise\u003cUserResponse\u003e {\n    return imitation(id); // this is a mock function to prevent the type error\n  }\n}\n```\n\nAfter adding the service to the providers in the module, you can use it and make HTTP requests when calling\nthe `request` method:\n\n```ts\n@Injectable()\nclass UserService {\n  constructor(private readonly client: UserHttpService) {}\n\n  async getUser(id: number): Promise\u003cUserResponse\u003e {\n    return this.client.request(id);\n  }\n}\n```\n\n## Decorators\n\n- `@HttpInterface()`: Marks the class as an HTTP service.\n\n- `@{HTTP Method}Exchange(path: string, options?: HttpClientOptions)`: Marks the method as an HTTP request method, with `path` being the request's\n  path or full URL.\n\n- `@GraphQLExchange(query: string, url = '/graphql', options?: HttpClientOptions)`: Marks the method as a GraphQL request method, with `query` being\n  the GraphQL query and `url` being the GraphQL endpoint.\n\n- `@ResponseBody(dto: ClassConstructor, options?: ClassTransformOptions)`: Specifies the response DTO using a class\n  constructor and options from the `class-transformer` library.\n\n- `@PathVariable(name?: string)`: Specifies the path variable, requiring the name of the variable.\n\n- `@RequestParam(key?: string, defaultValue?: string)`: Specifies the query string parameter, requiring the key of the\n  parameter. If `key` is not specified, the parameter must be an object. See examples below:\n\n  - Example with key: `request(@RequestParam('foo') query: string): string`\n  - Example without key: `request(@RequestParam() query: { foo: string }): string`\n\n- `@RequestHeader(key?: string, option?: { defaultValue?: string; transform?: (value: string) =\u003e string })`: Specifies\n  the request header, requiring the key of the header optionally.\n\n- `@Bearer()`: Specifies the bearer token using the `Authorization` header.\n\n- `@Cookie(key: string)`: Specifies the cookie using the `Cookie` header, requiring the key of the cookie.\n\n- `@RequestBody(key?: string, defalutValue?: unkown)`: Specifies the request body using `application/json` as the\n  content type, requiring the key of the body optionally.\n\n- `@RequestForm(key?: string, defaultValue?: string)`: Specifies the request form\n  using `application/x-www-form-urlencoded` as the content type, requiring the key of the body optionally.\n\n- `@CircuitBreaker(options?: CircuitBreaker.Options)`: Marks the method as a circuit breaker, with `options` being the\n  options of the circuit breaker. You can use global options by setting the `circuitBreakerOption` property in the module.\n  `options` is from [opossum](https://www.npmjs.com/package/opossum) library.\n\n- `@ObservableResponse()`: Marks the method as an observable method. If this decorator is not specified, the method will return\n  a promise.\n\n## Auto generate `@ResponseBody()` from return type of exchange method\n\nBecause of limitation of `reflect-metadata`, `@ResponseBody()` is required to specify the response DTO.\n\nBut this library provides a way to auto generate `@ResponseBody()` and infers response DTO from return type of exchange method.\n\nIt uses `CLI Plugin` like `@nestjs/swagger` and `@nestjs/graphql`.\n\nTo enable the plugin, open nest-cli.json\n\n```json\n{\n  \"compilerOptions\": {\n    \"plugins\": [\"@r2don/nest-http-interface\"]\n  }\n}\n```\n\nYou can use the options property to customize the behavior of the plugin.\n\n```json\n{\n  \"compilerOptions\": {\n    \"plugins\": [\n      {\n        \"name\": \"@r2don/nest-http-interface\",\n        \"options\": {\n          \"interfaceFilenameSuffix\": [\".http.service.ts\"]\n        }\n      }\n    ]\n  }\n}\n```\n\nHere is the list of options:\n\n| option                  | default         | description               |\n| ----------------------- | --------------- | ------------------------- |\n| interfaceFilenameSuffix | ['.service.ts'] | HTTP service files suffix |\n\n`@ResponseBody()` will be added whenever `nest start` or `nest build` is executed.\n\n## Example\n\nThere are some examples in the [example](./example) directory.\nPlease refer to the [README.md](./example/README.md).\n\n## License\n\nThis library is licensed under the MIT license.\n\n## Testing\n\nTo run tests, execute:\n\n```bash\n$ pnpm test\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr2don%2Fnest-http-interface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr2don%2Fnest-http-interface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr2don%2Fnest-http-interface/lists"}