{"id":19119004,"url":"https://github.com/journy-io/http","last_synced_at":"2025-05-05T14:41:01.997Z","repository":{"id":54199235,"uuid":"301972332","full_name":"journy-io/http","owner":"journy-io","description":"💌 HTTP library that powers our Node.js SDK","archived":false,"fork":false,"pushed_at":"2021-10-24T16:34:35.000Z","size":756,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-26T07:51:01.593Z","etag":null,"topics":["http","http-client","library"],"latest_commit_sha":null,"homepage":"https://developers.journy.io","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/journy-io.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}},"created_at":"2020-10-07T08:26:58.000Z","updated_at":"2021-10-24T16:34:38.000Z","dependencies_parsed_at":"2022-08-13T09:00:52.939Z","dependency_job_id":null,"html_url":"https://github.com/journy-io/http","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/journy-io%2Fhttp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/journy-io%2Fhttp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/journy-io%2Fhttp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/journy-io%2Fhttp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/journy-io","download_url":"https://codeload.github.com/journy-io/http/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252516041,"owners_count":21760710,"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","http-client","library"],"created_at":"2024-11-09T05:08:18.245Z","updated_at":"2025-05-05T14:41:01.968Z","avatar_url":"https://github.com/journy-io.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![journy.io](https://raw.githubusercontent.com/journy-io/brand/main/githubbanner.png)](https://journy.io/?utm_source=github\u0026utm_content=readme-http)\n\n# HTTP\n\n[![npm](https://img.shields.io/npm/v/@journyio/http?color=%234d84f5\u0026style=flat-square)](https://www.npmjs.com/package/@journyio/http)\n[![npm downloads](https://img.shields.io/npm/dm/@journyio/http?style=flat-square)](https://www.npmjs.com/package/@journyio/http)\n\nHTTP library that powers our [Node.js SDK](https://github.com/journy-io/js-sdk).\n\n## 💾 Installation\n\nYou can use your package manager (`npm` or `yarn`) to install the HTTP utilities:\n\n```bash\nnpm install --save @journyio/http\n```\nor\n```bash\nyarn add @journyio/http\n```\n\n## 🔌 Getting started\n\n### HttpClientNode\n\nUses Node's `http` / `https` modules\n\n```ts\nimport { HttpClientNode } from \"@journyio/http\";\n\nconst client = new HttpClientNode(/* timeoutInMillis = */ 5000);\n```\n\n### GET request\n\n```ts\nimport { HttpRequest, HttpHeaders } from \"@journyio/http\";\nimport { URL } from \"url\";\n\nconst response = await client.send(\n  new HttpRequest(\n    new URL(`https://api.domain/users?email=${encodeURIComponent(email)}`),\n    \"GET\",\n    new HttpHeaders({ \"x-api-key\": \"my-api-key\" })\n  )\n);\n\nconsole.log(response.getStatusCode());\nconsole.log(response.getBody());\nconsole.log(response.getHeaders());\nconsole.log(response.getHeaders().byName(\"x-ratelimit-remaining\"));\nconsole.log(response.getHeaders().byName(\"X-RateLimit-Remaining\"));\n```\n\n### POST request\n\n```ts\nimport { HttpRequest, HttpHeaders } from \"@journyio/http\";\nimport { URL } from \"url\";\n\nconst response = await client.send(\n  new HttpRequest(\n    new URL(\"https://api.domain/users\"),\n    \"POST\",\n    new HttpHeaders({\n      \"x-api-key\": \"my-api-key\",\n      \"content-type\": \"application/json\",\n    }),\n    JSON.stringify({ email: \"user@acme.com\" })\n  )\n);\n```\n\n`HttpClientNode` doesn't support redirects yet.\n\n## 🤔️ Why another HTTP client?\n\nWhile [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) is great... It's not yet natively available in [Node.js](https://github.com/nodejs/node/issues/19393). It's also missing an important feature: an interface.\n\n```ts\ninterface HttpClient {\n  send(request: HttpRequest): Promise\u003cHttpResponse\u003e;\n}\n```\n\nLet's say you have an API client:\n\n```ts\nclass API {\n  async getUser(id: string): Promise\u003cUser\u003e {\n    const response = await fetch(/* ... */);\n\n    return await response.json();\n  }\n}\n```\n\nIf we want to test this API client, we need to mock HTTP requests. It's really hard to do and often requires [magic](https://github.com/nock/nock).\n\nBy depending on an interface for an HTTP client we can make this a lot easier:\n\n```ts\nclass API {\n  constructor(private readonly httpClient: HttpClient) {}\n\n  async getUser(id: string): Promise\u003cUser\u003e {\n    const response = await this.httpClient.send(\n      new HttpRequest(/* ... */)\n    );\n\n    return JSON.parse(response.getBody());\n  }\n}\n```\n\nIn our test we can use `HttpClientFixed`:\n\n```ts\nclass HttpClientFixed implements HttpClient {\n  private lastRequest: HttpRequest | undefined;\n\n  constructor(private readonly response: HttpResponse) {}\n\n  async send(request: HttpRequest): Promise\u003cHttpResponse\u003e {\n    this.lastRequest = request;\n\n    return this.response;\n  }\n\n  getLastRequest() {\n    return this.lastRequest;\n  }\n}\n```\n\nOur test will look something like this:\n\n```ts\ntest(\"our API client works\", async () =\u003e {\n  const http = new HttpClientFixed(\n    new HttpResponse(\n      200,\n      new HttpHeaders({ \"x-ratelimit-remaining\": \"200\" }),\n      '{\"id\":\"id\",\"name\":\"Hans\"}'\n    )\n  );\n\n  const api = new API(http);\n\n  expect(await api.getUser(\"id\")).toEqual({ id: \"id\", name: \"Hans\" });\n  expect(http.getLastRequest()).toEqual(new HttpRequest(/* ... */));\n})\n```\n\nIn case your client should be able to return different responses depending on the path of the request, you can take a look at the `HttpClientCallback` class. Here you can give a custom callback to the client, which allows for a lot of flexibility.\n\nIn PHP world this concept is known as [PSR-18: HTTP Client](https://www.php-fig.org/psr/psr-18/).\n\nOf course, this makes only sense in TypeScript world. Interfaces are not available in JavaScript.\n\nApart from testing, there are more benefits...\n\nWe can log requests for debugging purposes:\n\n```ts\nclass HttpClientConsoleLogging implements HttpClient {\n  constructor(private readonly client: HttpClient) {}\n\n  async send(request: HttpRequest) {\n    console.log(\"Request...\", request.getMethod(), request.getURL().toString());\n    const response = await this.client.send(request);\n    console.log(\"Response...\", response.getStatusCode(), response.getBody());\n\n    return response;\n  }\n}\n```\n\n```ts\nconst http = new HttpClientConsoleLogging(\n  new HttpClientNode()\n);\n\nconst api = new API(http);\n\n// Request and response will be logged to the console...\nawait api.getUser(\"id\");\n```\n\nMore ideas (not included in this package):\n- Store requests (and responses) of calls that failed\n- Keep track of rate limits\n- Add credentials to requests\n- ...\n\n## 💯 Tests\n\nTo setup [httpbin](https://github.com/postmanlabs/httpbin) locally:\n\n```bash\ndocker-compose up -d\n```\n\nTo run the tests:\n\n```bash\nnpm run test\n```\n\n## ❓ Help\n\nWe welcome your feedback, ideas and suggestions. We really want to make your life easier, so if we’re falling short or should be doing something different, we want to hear about it.\n\nPlease create an issue or contact us via the chat on our website.\n\n## 🔒 Security\n\nIf you discover any security related issues, please email hans at journy io instead of using the issue tracker.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjourny-io%2Fhttp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjourny-io%2Fhttp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjourny-io%2Fhttp/lists"}