README.md

Httpie

A modern and light Node.js http client 🐢🚀.

📢 About

The package is inspired by lukeed httpie (The use is relatively similar). This package use new Node.js http client undici under the hood.

🔬 Features

• Automatically parse based on the content-type.
• Automatically decompress based on the content-encoding.
• Includes aliases for common HTTP verbs: get, post, put, patch, and del.
• Able to automatically detect domains and paths to assign the right Agent (use a LRU cache to avoid repetitive computation).
• Allows to use an accurate rate-limiter like p-ratelimit with the limit option.
• Built-in retry mechanism with custom policies.
• Safe error handling with Rust-like Result.

Thanks to undici:

• Support HTTP redirections with the maxRedirections argument.
• Implement high-level API for undici stream and pipeline method.
• High performance (see benchmarks).
• Work well with newest Node.js API AbortController to cancel http request.

Light with seriously maintained dependencies:

🚧 Requirements

• Node.js version 20 or higher

🚀 Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @myunisoft/httpie
# or
$ yarn add @myunisoft/httpie

📚 Usage example

The MyUnisoft httpie client is very similar to lukeed httpie http client.

import * as httpie from "@myunisoft/httpie";

try {
  const { data } = await httpie.get("https://jsonplaceholder.typicode.com/posts");
  console.log(data);
  
  const response = await httpie.post("https://jsonplaceholder.typicode.com/posts", {
    body: {
      title: "foo",
      body: "bar",
      userId: 1
    }
  });

  console.log(response.statusCode);
  console.log(response.statusMessage);
  console.log(response.data);
}
catch (error) {
  console.log(error.message);
  console.log(error.statusCode);
  console.log(error.headers);
  console.log(error.data);
}

Since v2.0.0 you can also use the safe prefix API to get a Promise<Result<T, E>>

import * as httpie from "@myunisoft/httpie";

const response = (await httpie.safePost("https://jsonplaceholder.typicode.com/posts", {
  body: {
    title: "foo",
    body: "bar",
    userId: 1
  }
}))
  .map((response) => response.data)
  .mapErr((error) => new Error("a message here!", { cause: error.data }));
  .unwrap();

👀 For more examples of use please look at the root folder examples.

📜 API

• Request API
• Retry API
• Work and manage Agents

Error handling

Read the error documentation.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Gentilhomme 💻 📖 👀 🛡️ 🐛

PierreDemailly 💻 ⚠️

Yefis 💻 🐛

License

MIT