📢 About

Httpie is a Node.js HTTP client built on Undici. Its request API follows the small, function-based style of lukeed's httpie, with response parsing, agent selection, rate limiting, and Result-based error handling added around it.

🔬 Features

• Parses JSON and text responses from their content-type; other response bodies remain buffers.
• Decompresses encoded responses before parsing them.
• Provides get, post, put, patch, and del aliases alongside the general request function.
• Provides safeRequest and safe HTTP verb aliases that return a Result.
• Selects an Undici dispatcher from a registered origin or path, with cached URI resolution.
• Accepts a rate-limiter callback through the limit option or an agent registration.

🚧 Requirements

• Node.js version 22 or higher

🚀 Getting Started

Install the package with npm or yarn:

npm install @openally/httpie
# or
yarn add @openally/httpie

📚 Usage example

import {
  get,
  post,
  isHTTPError
} from "@openally/httpie";

interface Post {
  id: number;
  title: string;
  body: string;
  userId: number;
}

try {
  const { data: posts } = await get<Post[]>(
    "https://jsonplaceholder.typicode.com/posts"
  );
  console.log(posts);

  const response = await post<Post>("https://jsonplaceholder.typicode.com/posts", {
    body: {
      title: "foo",
      body: "bar",
      userId: 1
    }
  });

  console.log(response.statusCode, response.data);
}
catch (error: unknown) {
  if (isHTTPError(error)) {
    console.error(error.statusCode, error.data);
  }
  else {
    throw error;
  }
}

The safe methods return a Result instead of throwing:

import { safePost } from "@openally/httpie";

const result = await safePost("https://jsonplaceholder.typicode.com/posts", {
  body: {
    title: "foo",
    body: "bar",
    userId: 1
  }
});

result.match(
  (response) => console.log(response.data),
  (error) => console.error(error.message)
);

[!TIP] More examples available in the root folder examples.

📜 API

• Requests, options, response modes, and safe methods
• Streams and pipelines
• Agent registry and URI resolution

Httpie also re-exports selected Undici APIs. Their behavior follows the Undici documentation.

Error handling

Read Error handling for thrown errors, safe results, and the isHttpieError and isHTTPError guards.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

License

MIT