typed-rest-client review
typed-rest-client 3.1.0 is a Node HTTP client with two layers. RestClient joins URLs, sends and parses JSON, and returns generic result objects; HttpClient exposes status codes, headers, streams, and raw bodies. Authentication handlers cover Basic, Bearer, personal access tokens, and legacy NTLM, while transport options cover proxies, certificates, redirects, retries, and keep-alive agents. Version 3.0 replaced legacy parsed URLs with WHATWG URL objects, and 3.1.0 updated dependencies and overrides to address vulnerabilities while raising the engine floor to Node 20.
typed-rest-client 3.1.0 installed 27 packages in 1.5 seconds with 0 audit findings, but our browser build failed and its engine now requires Node 20. Keep it for Microsoft-oriented Node automation that needs PAT, proxy, and certificate handlers; use fetch or undici for a new ordinary HTTP client.
We installed it
| Install | ✓ · 1.5s | 27 packages on disk · 7 MB |
| Import | ✓ | ESM import works · require() works · CommonJS package |
| Browser | n/a | could not be bundled for the browser (Node-only code, most likely) |
| Types | — | no TypeScript types found |
| Known vulns | 0 | 0 critical · 0 high · 0 moderate · 0 low (npm audit) |
Answers from our run
Does typed-rest-client install cleanly?
Yes. In a fresh container with an empty cache, npm install typed-rest-client finished in 2 seconds, leaving 27 packages and 7 MB on disk. npm audit reported no known vulnerabilities.
Can typed-rest-client run in a browser?
Not directly: esbuild could not bundle it for the browser in our run, which normally means it depends on Node built-ins. Use it on the server, or find a browser-targeted alternative.
Does typed-rest-client work with both ESM and CommonJS?
Yes. Both import 'typed-rest-client' and require('typed-rest-client') worked in Node 22 in our run. The package is published as CommonJS.
Does typed-rest-client include TypeScript types?
No type declarations were found in our install, so TypeScript users need their own declarations.
typed-rest-client or undici: which should you use?
undici: Use it for current Node fetch, pooling, streaming, and AbortSignal support without legacy authentication handlers. typed-rest-client 3.1.0 installed 27 packages in 1.5 seconds with 0 audit findings, but our browser build failed and its engine now requires Node 20.
When should you not use typed-rest-client?
The service only makes ordinary JSON calls on current Node. Native fetch or undici avoids 27 installed packages and legacy auth code.
Use it if
- A Node 20 automation service needs built-in Azure DevOps personal access token handling.
- Corporate proxy bypass rules, client certificates, or a custom CA are part of the deployment.
- Code needs both convenient JSON methods and low-level IncomingMessage access under one CommonJS package.
- An existing integration already relies on RestClient's unusual 404 result and other 4xx or 5xx rejection rules.
- The service only makes ordinary JSON calls on current Node. Native fetch or undici avoids 27 installed packages and legacy auth code.
- Browser, worker, or edge execution is required. Our esbuild browser build failed, matching the package's Node http, fs, Buffer, and stream dependencies.
- Node 18 support must remain. Version 3.1.0 declares Node >=20.0.0.
- Runtime response validation is expected from TypeScript generics. RestClient parses JSON and treats it as T without checking the object shape.
- NTLM is the sole attraction. The handler is deprecated in source, lacks proxy-agent support, and depends on DES and MD4 implementations.
Setup reality
We installed typed-rest-client 3.1.0 in a fresh Node 22 Bookworm sandbox in 1.5 seconds. It left 27 packages and 7 MB on disk, and npm audit found 0 known vulnerabilities. The package has 5 direct dependencies, 0 peer dependencies, 240 KB unpacked, an MIT license, and a Node >=20.0.0 engine. Our scanner found no TypeScript types. CommonJS require() and ESM import both worked under Node 22.23.2.
Pick RestClient or HttpClient before designing error handling. RestClient resolves a 404 with result set to null and rejects other 4xx or 5xx statuses. HttpClient returns the response for any HTTP status and throws for transport failures. The generic T describes JSON to the compiler but performs no runtime validation, so check untrusted responses with a schema.
Bearer and PAT handlers avoid sending Authorization to another origin unless cross-origin authentication is enabled. Proxy configuration can come from options or HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. Certificate files are read synchronously when the client is constructed. ignoreSslError disables verification and should not substitute for a correct CA bundle. NODE_DEBUG=http can print sensitive request details.
Retries are disabled by default and cover selected network failures plus 502, 503, and 504 only for OPTIONS, GET, DELETE, and HEAD. Writes do not retry. Redirects are followed by default, while HTTPS-to-HTTP downgrade needs an explicit option. keepAlive clients require dispose() during shutdown. Our browser build failed, so keep all 27 installed packages on the server side.
Patterns
Fetch a JSON resource get-json
const restm = require('typed-rest-client/RestClient');
const client = new restm.RestClient('inventory-service', 'https://api.example.com');
const response = await client.get('/users/42');
if (response.result) console.log(response.result.name);A 404 yields result: null, while the generic type in TypeScript does not validate the decoded JSON object.
POST a JSON object create-json
const response = await client.create('/users', {name: 'Ada'});
console.log(response.statusCode, response.result?.id);create() uses POST; update() uses PATCH and replace() uses PUT with the same JSON-oriented result handling.
Encode repeated query values send-query-params
const response = await client.get('/users', {
queryParameters: {
params: {page: 2, role: ['admin', 'editor']},
options: {arrayFormat: 'repeat'},
},
additionalHeaders: {'x-request-id': requestId},
});Version 3.1.0 uses qs 6.15.3 for query serialization, so arrayFormat controls the URL representation.
Attach a bearer credential use-bearer-token
const handlers = require('typed-rest-client/Handlers');
const restm = require('typed-rest-client/RestClient');
const auth = new handlers.BearerCredentialHandler(process.env.API_TOKEN);
const client = new restm.RestClient('deploy-tool', baseUrl, [auth]);Authorization is withheld after a cross-origin redirect unless the client explicitly enables cross-origin authentication.
Authenticate to Azure DevOps with a PAT use-pat
const auth = new handlers.PersonalAccessTokenCredentialHandler(
process.env.AZURE_DEVOPS_PAT
);
const client = new restm.RestClient('build-tool', organizationUrl, [auth]);The handler builds a Basic credential from PAT:<token>; keep the token in server-side environment storage.
Treat every HTTP status as data read-raw-response
const httpm = require('typed-rest-client/HttpClient');
const client = new httpm.HttpClient('health-checker');
const response = await client.get('https://api.example.com/health');
const body = await response.readBody();
console.log(response.message.statusCode, body);HttpClient returns 404 and 500 responses without rejecting, so inspect statusCode before parsing or trusting the body.
Read a rejected REST status handle-rest-error
try {
await client.update('/users/42', {name: 'Grace'});
} catch (error) {
console.error(error.statusCode, error.message, error.result);
}RestClient's 404 path resolves with null; this catch receives other 4xx and 5xx failures plus transport errors.
Retry selected read failures retry-idempotent-read
const client = new httpm.HttpClient('catalog-reader', [], {
allowRetries: true,
maxRetries: 3,
socketTimeout: 10_000,
});
await client.get('https://api.example.com/catalog');Retries apply to 4 read-oriented methods and selected network errors or 502, 503, and 504 responses; POST and PATCH are excluded.
Use an authenticated proxy configure-proxy
const client = new httpm.HttpClient('corp-tool', [], {
proxy: {
proxyUrl: 'http://proxy.company.example:8080',
proxyUsername: process.env.PROXY_USER,
proxyPassword: process.env.PROXY_PASSWORD,
proxyBypassHosts: ['^localhost$', '\\.company\\.internal$'],
},
});Bypass entries are regular expressions; HTTP_PROXY, HTTPS_PROXY, and NO_PROXY are also read from the environment.
Load client and CA certificates configure-mtls
const client = new httpm.HttpClient('mtls-client', [], {
cert: {
caFile: '/etc/my-app/ca.pem',
certFile: '/etc/my-app/client.pem',
keyFile: '/etc/my-app/client-key.pem',
passphrase: process.env.CLIENT_KEY_PASSPHRASE,
},
});Certificate files are read synchronously during construction; ignoreSslError disables verification instead of repairing trust.
Send a file stream upload-stream
const {createReadStream} = require('node:fs');
const stream = createReadStream('/tmp/artifact.zip');
const response = await client.uploadStream(
'PUT', '/artifacts/latest', stream,
{additionalHeaders: {'content-type': 'application/zip'}}
);RestClient expects JSON in the reply; use HttpClient when the response itself must remain a stream.
Close keep-alive agents dispose-keepalive
const client = new httpm.HttpClient('batch-worker', [], {
keepAlive: true,
maxSockets: 20,
});
try {
await client.get(url);
} finally {
client.dispose();
}Version 3.1.0 keeps agents open when keepAlive is enabled, so dispose() belongs in worker shutdown.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| undici | npm | Use it for current Node fetch, pooling, streaming, and AbortSignal support without legacy authentication handlers. |
| got | npm | Use it for an ESM-first Node client with hooks, pagination, retry controls, and detailed errors. |
| axios | npm | Use it when the same request API must work in browsers and Node and interceptors matter. |
More web backend guides
urllib3 · requests · ws · anyio · httpx · undici · the whole shelf →
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.