btch-http

library2.0.3jsnpmunverified

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.

http-networking

npm install btch-http

github ↗package ↗

INSTALL

IMPORT

SIG · BTCH-HTTP

btch-http

http-networkingjavascriptv2.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HttpGet

✓ import { HttpGet } from 'btch-http';

✗ const { HttpGet } = require('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

✓ import { HttpClient } from 'btch-http';

✗ const { HttpClient } = require('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

✓ import { HttpError } from 'btch-http';

✗ const { HttpError } = require('btch-http');

Custom error class thrown for all HTTP-related issues including network errors, timeouts, HTTP status codes >= 300, and JSON parse failures.

HttpClientConfig

✓ import type { HttpClientConfig } from 'btch-http';

✗ import { HttpClientConfig } from 'btch-http';

It is best practice to use `import type` for type-only imports to improve compilation and runtime performance in TypeScript.

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();

Debug

Known issues

breakingVersion 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`.

affects: >=2.0.0

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

affects: >=2.0.0

gotchaThe `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.

affects: >=1.0.0

gotchabtch-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`.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

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

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)

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.

Upgrade

Version history

2.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hostinger-bot/btch-http ↗

packagehttps://www.npmjs.com/package/btch-http ↗