HTTP

HTTP library that powers our Node.js SDK.

💾 Installation

You can use your package manager (npm or yarn) to install the HTTP utilities:

npm install --save @journyio/http

or

yarn add @journyio/http

🔌 Getting started

HttpClientNode

Example of GET request:

import { HttpClientNode, HttpRequest, HttpHeaders } from "@journyio/http";
import { URL } from "url";

const client = new HttpClientNode(/* timeoutInMillis = */ 5000);

const response = await client.send(
  new HttpRequest(
    new URL(`https://api.domain/users?email=${encodeURIComponent(email)}`),
    "GET",
    new HttpHeaders({ "x-api-key": "my-api-key" })
  )
);

console.log(response.getStatusCode());
console.log(response.getBody());
console.log(response.getHeaders());
console.log(response.getHeaders().byName("x-ratelimit-remaining"));
console.log(response.getHeaders().byName("X-RateLimit-Remaining"));

Example of POST request:

const response = await client.send(
  new HttpRequest(
    new URL("https://api.domain/users"),
    "POST",
    new HttpHeaders({
      "x-api-key": "my-api-key",
      "content-type": "application/json",
    }),
    JSON.stringify({ email: "[email protected]" })
  )
);

HttpClientNode doesn't support redirects yet.

🤔️ Why another HTTP client?

While fetch is great... It's not yet natively available in Node.js. It's also missing an important feature: an interface.

interface HttpClient {
  send(request: HttpRequest): Promise<HttpResponse>;
}

Let's say you have an API client:

class API {
  async getUser(id: string): Promise<User> {
    const response = await fetch(/* ... */);

    return await response.json();
  }
}

If we want to test this API client, we need to mock HTTP requests. It's really hard to do and often requires magic.

By depending on an interface for an HTTP client we can make this a lot easier:

class API {
  constructor(private readonly httpClient: HttpClient) {}

  async getUser(id: string): Promise<User> {
    const response = await this.httpClient.send(
      new HttpRequest(/* ... */)
    );

    return JSON.parse(response.getBody());
  }
}

In our test we can use HttpClientFixed:

class HttpClientFixed implements HttpClient {
  private lastRequest: HttpRequest | undefined;

  constructor(private readonly response: HttpResponse) {}

  async send(request: HttpRequest): Promise<HttpResponse> {
    this.lastRequest = request;

    return this.response;
  }

  getLastRequest() {
    return this.lastRequest;
  }
}

Our test will look something like this:

test("our API client works", async () => {
  const http = new HttpClientFixed(
    new HttpResponse(
      200,
      new HttpHeaders({ "x-ratelimit-remaining": "200" }),
      '{"id":"id","name":"Hans"}'
    )
  );

  const api = new API(http);

  expect(await api.getUser("id")).toEqual({ id: "id", name: "Hans" });
  expect(http.getLastRequest()).toEqual(new HttpRequest(/* ... */));
})

In 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.

In PHP world this concept is known as PSR-18: HTTP Client.

Of course, this makes only sense in TypeScript world. Interfaces are not available in JavaScript.

Apart from testing, there are more benefits...

We can log requests for debugging purposes:

class HttpClientConsoleLogging implements HttpClient {
  constructor(private readonly client: HttpClient) {}

  async send(request: HttpRequest) {
    console.log("Request...", request.getMethod(), request.getURL().toString());
    const response = await this.client.send(request);
    console.log("Response...", response.getStatusCode(), response.getBody());

    return response;
  }
}

const http = new HttpClientConsoleLogging(
  new HttpClientNode()
);

const api = new API(http);

// Request and response will be logged to the console...
await api.getUser("id");

More ideas (not included in this package):

• Store requests (and responses) of calls that failed
• Keep track of rate limits
• Add credentials to requests
• ...

💯 Tests

To run the tests:

npm run test

❓ Help

We 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.

Please create an issue or contact us via the chat on our website.

🔒 Security

If you discover any security related issues, please email hans at journy io instead of using the issue tracker.