Lightweight Node.js HTTP Client

2.0.3 · active · verified Tue Apr 21

btch-http is a lightweight and type-safe HTTP client for Node.js, built directly on the Node.js `https` module, ensuring zero external dependencies. The current stable version is 2.0.3, with recent minor updates following a major version 2.0.0 release. It differentiates itself by offering full TypeScript support out-of-the-box, smart error handling that consolidates network, timeout, and HTTP status code (>=300) errors into a custom `HttpError` class, and comprehensive timeout support. It provides both a quick one-liner `HttpGet` function for simple GET requests with URL encoding and a full-featured `HttpClient` class for more complex interactions involving configurable base URLs, versions, default headers, and POST requests with JSON bodies or custom headers. It requires Node.js >=20.18.1.

Common errors

```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use CommonJS `require()` syntax to import `btch-http` in an environment configured for ES modules.

fix Use ES module import syntax: `import { SymbolName } from 'btch-http';`
```
TypeError: btch_http_1.HttpClient is not a constructor
```
cause Incorrect import of `HttpClient` or attempting to use it in a CommonJS context when the package is ESM-only.

fix Ensure you are using `import { HttpClient } from 'btch-http';` and your project is configured for ES modules, with a compatible Node.js version.
```
Failed to download TikTok data: Network Error (or similar message within try/catch)
```
cause A network connectivity issue, DNS resolution failure, or the target server refused the connection.

fix Verify your internet connection, ensure the target `baseUrl` is correct and accessible, and check firewall settings. The `HttpError` will contain details about the underlying network issue.

Warnings

breaking Version 2.0.0 of `btch-http` switched to being an ESM-only package. CommonJS `require()` statements are no longer supported.
Fix: Migrate your project to use ES modules (`import`/`export`) or use dynamic `import()` for `btch-http`.
breaking With version 2.0.0, the package's engine requirement was updated to Node.js `>=20.18.1`. Running on older Node.js versions will result in errors.
Fix: Upgrade your Node.js environment to version 20.18.1 or newer.
gotcha The `HttpGet` function automatically appends the second URL argument as a query parameter (e.g., `?url=...`) to the endpoint. This implicit behavior might be unexpected if not explicitly known.
Fix: Be aware of this automatic URL encoding when using `HttpGet`. For more explicit control over query parameters, consider using the `HttpClient` class and its `get` method.
gotcha btch-http's error handling is strict: it throws an `HttpError` for any HTTP status code >= 300, as well as network errors, timeouts, or JSON parsing failures. This might differ from other HTTP clients that only throw for 5xx status codes.
Fix: Always wrap your `btch-http` calls in `try...catch` blocks and use `instanceof HttpError` to specifically handle API-related errors, allowing you to inspect `error.status`, `error.message`, and `error.response`.

Install

npm install btch-http npm
yarn add btch-http yarn
pnpm add btch-http pnpm

Imports

HttpGet
wrong:
```
const { HttpGet } = require('btch-http');
```
correct:
```
import { HttpGet } from 'btch-http';
```
The package is ESM-only since v2.0.0 and requires Node.js >=20.18.1. This function provides a quick GET with automatic URL parameter appending.
HttpClient
wrong:
```
const { HttpClient } = require('btch-http');
```
correct:
```
import { HttpClient } from 'btch-http';
```
The primary class for creating a reusable HTTP client with configurable base URLs, headers, and methods. ESM-only since v2.0.0.
HttpError
wrong:
```
const { HttpError } = require('btch-http');
```
correct:
```
import { HttpError } from 'btch-http';
```
Custom error class thrown for all HTTP-related issues including network errors, timeouts, HTTP status codes >= 300, and JSON parse failures.
HttpClientConfig
wrong:
```
import { HttpClientConfig } from 'btch-http';
```
correct:
```
import type { HttpClientConfig } from 'btch-http';
```
It is best practice to use `import type` for type-only imports to improve compilation and runtime performance in TypeScript.

Quickstart

Demonstrates a quick, one-liner GET request using `HttpGet` to retrieve data from a TikTok video downloader API.

import { HttpGet } from 'btch-http';

const tiktokVideoUrl = 'https://www.tiktok.com/@omagadsus/video/7025456384175017243';

async function downloadTikTokData() {
  try {
    // The `HttpGet` function automatically appends `?url=...` for the second argument.
    const data = await HttpGet(
      'ttdl',
      tiktokVideoUrl,
      '1.0.0', // Client version
      30000,   // Timeout in milliseconds
      'https://backend1.tioo.eu.org' // Base URL for the endpoint
    );
    console.log('Download URL:', data.video);
    console.log('Raw data:', data);
  } catch (error) {
    if (error instanceof Error) {
      console.error('Failed to download TikTok data:', error.message);
    } else {
      console.error('An unknown error occurred:', error);
    }
  }
}

downloadTikTokData();

view raw JSON →