Registry / http-networking / typed-rest-client

typed-rest-client

library2.3.0jsnpmunverified

typed-rest-client is a lightweight REST and HTTP client library designed for Node.js, with a strong emphasis on TypeScript support, including generics and async/await capabilities. The current stable version is 2.3.0, building on a release history that includes a significant v2.0.0 update in late 2023 that raised the minimum Node.js requirement to version 16.0.0. The library provides built-in TypeScript typings, eliminating the need for separate type installations. It differentiates itself by offering both a low-level HttpClient, which returns response objects for all HTTP statuses (including 4xx/5xx), and a higher-level RestClient, which automatically deserializes JSON and throws errors for non-success status codes. Key features include support for Basic, Bearer, and NTLM authentication, proxy configurations, client/server certificates, and automatic handling of HTTP redirects. It maintains a regular, but not rapid, release cadence, focusing on stability and functionality for enterprise Node.js applications.

http-networking serialization auth-security

npm install typed-rest-client

github ↗package ↗

INSTALL

IMPORT

SIG · TYPED-REST-CLIENT

typed-rest-client

http-networkingjavascriptv2.3.0

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.

RestClient

✓ import { RestClient } from 'typed-rest-client/RestClient';

✗ import { RestClient } from 'typed-rest-client'; const { RestClient } = require('typed-rest-client');

Named export from a specific subpath. CommonJS `require()` is not supported since v2.0.0.

HttpClient

✓ import { HttpClient } from 'typed-rest-client/HttpClient';

✗ import { HttpClient } from 'typed-rest-client'; const { HttpClient } = require('typed-rest-client');

Named export from a specific subpath. CommonJS `require()` is not supported since v2.0.0.

IRequestOptions

✓ import { IRequestOptions } from 'typed-rest-client/Interfaces';

✗ import { IRequestOptions } from 'typed-rest-client'; import { IRequestOptions } from 'typed-rest-client/RestClient';

Type import from the `Interfaces` subpath for configuring requests.

Demonstrates how to initialize `RestClient` and perform a basic GET request for a JSON resource, including error handling and null checks.

import { RestClient } from 'typed-rest-client/RestClient'; interface Todo { userId: number; id: number; title: string; completed: boolean; } async function fetchTodo() { // The user-agent string is required for RestClient initialization const rest = new RestClient('my-app-user-agent'); try { const response = await rest.get<Todo>('https://jsonplaceholder.typicode.com/todos/1'); if (response.statusCode === 200 && response.result) { console.log(`Fetched Todo (ID: ${response.result.id}): ${response.result.title} - Completed: ${response.result.completed}`); } else if (response.statusCode === 404) { // RestClient does not throw for 404 if no error body is returned and result will be null console.log('Todo not found.'); } else { console.error(`Request failed with status: ${response.statusCode}`); } } catch (err: any) { // RestClient throws for other 4xx/5xx errors if (err.statusCode) { console.error(`RestClient threw an error for status ${err.statusCode}: ${err.message}`); } else { console.error(`An unexpected network or client error occurred: ${err.message}`); } } } fetchTodo();

Debug

Known issues

breakingVersion 2.0.0 and above of `typed-rest-client` requires Node.js version 16 or higher. Older Node.js versions are not supported.

fix

Upgrade your Node.js environment to version 16.0.0 or higher. If unable to upgrade, you must stick with `typed-rest-client` v1, which is End-of-Life and contains security vulnerabilities.

affects: >=2.0.0

gotchaThe `HttpClient` and `RestClient` classes handle errors differently. `HttpClient` will return a response object for all HTTP status codes (e.g., 404, 500) and will not throw. `RestClient`, being higher-level, will automatically deserialize JSON and will throw an error for any 4xx or 5xx status codes (except often 404 with an empty body, where `result` will be `null`), making it crucial to use `try...catch` blocks.

fix

Always wrap `RestClient` calls in `try...catch` blocks to handle non-success HTTP responses. For `HttpClient`, inspect the `response.statusCode` property and `response.result` (or `response.message`) for details.

affects: >=1.0.0

deprecatedVersion 1 of `typed-rest-client` is End-of-Life (EOL) and contains known security vulnerabilities. It should not be used in production environments.

fix

Migrate to `typed-rest-client` version 2.x, ensuring your Node.js environment meets the >=16.0.0 requirement.

affects: <2.0.0

gotchaThis package uses explicit subpath imports for its main classes (e.g., `/RestClient`, `/HttpClient`, `/Interfaces`). Attempting to import directly from the root package will result in module resolution errors.

fix

Ensure you are using correct subpath imports, e.g., `import { RestClient } from 'typed-rest-client/RestClient';`

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module ... typed-rest-client/RestClient.js not supported.

Attempting to use CommonJS `require()` syntax with `typed-rest-client` v2.x, which is an ESM-only package.

fix

Switch to ES module `import` syntax: `import { RestClient } from 'typed-rest-client/RestClient';`. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or using `.mjs` file extension).

RestClient threw an error for status 401: Failed Request: (401)

The `RestClient` received a 4xx or 5xx HTTP status code from the server (e.g., Unauthorized, Internal Server Error), causing it to throw an error.

fix

Implement proper error handling with `try...catch` blocks around `RestClient` calls to gracefully manage non-success HTTP responses. Inspect `err.statusCode` for the exact HTTP status and `err.message` for details.

TypeError: Cannot read properties of null (reading 'id')

The `RestClient`'s `get` or `post` method returned `null` for `response.result` (e.g., on a 404 Not Found without an error body), and the code attempted to access properties on `response.result` without a null check.

fix

Always check if `response.result` is not `null` or `undefined` before accessing its properties: `if (response.statusCode === 200 && response.result) { ... }`.

Upgrade

Version history

2.3.0latest on npm

Audit

Dependencies

qsrequiredUsed for query string parsing, notable for a recent vulnerability fix in v2.0.1.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Microsoft/typed-rest-client ↗

packagehttps://www.npmjs.com/package/typed-rest-client ↗