{"id":12219,"library":"typed-rest-client","title":"Typed REST and HTTP Client","description":"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.","status":"active","version":"2.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/Microsoft/typed-rest-client","tags":["javascript","rest","http","client","typescript","node"],"install":[{"cmd":"npm install typed-rest-client","lang":"bash","label":"npm"},{"cmd":"yarn add typed-rest-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add typed-rest-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for query string parsing, notable for a recent vulnerability fix in v2.0.1.","package":"qs","optional":false}],"imports":[{"note":"Named export from a specific subpath. CommonJS `require()` is not supported since v2.0.0.","wrong":"import { RestClient } from 'typed-rest-client';\nconst { RestClient } = require('typed-rest-client');","symbol":"RestClient","correct":"import { RestClient } from 'typed-rest-client/RestClient';"},{"note":"Named export from a specific subpath. CommonJS `require()` is not supported since v2.0.0.","wrong":"import { HttpClient } from 'typed-rest-client';\nconst { HttpClient } = require('typed-rest-client');","symbol":"HttpClient","correct":"import { HttpClient } from 'typed-rest-client/HttpClient';"},{"note":"Type import from the `Interfaces` subpath for configuring requests.","wrong":"import { IRequestOptions } from 'typed-rest-client';\nimport { IRequestOptions } from 'typed-rest-client/RestClient';","symbol":"IRequestOptions","correct":"import { IRequestOptions } from 'typed-rest-client/Interfaces';"}],"quickstart":{"code":"import { RestClient } from 'typed-rest-client/RestClient';\n\ninterface Todo {\n  userId: number;\n  id: number;\n  title: string;\n  completed: boolean;\n}\n\nasync function fetchTodo() {\n  // The user-agent string is required for RestClient initialization\n  const rest = new RestClient('my-app-user-agent');\n  try {\n    const response = await rest.get<Todo>('https://jsonplaceholder.typicode.com/todos/1');\n\n    if (response.statusCode === 200 && response.result) {\n      console.log(`Fetched Todo (ID: ${response.result.id}): ${response.result.title} - Completed: ${response.result.completed}`);\n    } else if (response.statusCode === 404) {\n      // RestClient does not throw for 404 if no error body is returned and result will be null\n      console.log('Todo not found.');\n    } else {\n      console.error(`Request failed with status: ${response.statusCode}`);\n    }\n  } catch (err: any) {\n    // RestClient throws for other 4xx/5xx errors\n    if (err.statusCode) {\n      console.error(`RestClient threw an error for status ${err.statusCode}: ${err.message}`);\n    } else {\n      console.error(`An unexpected network or client error occurred: ${err.message}`);\n    }\n  }\n}\n\nfetchTodo();","lang":"typescript","description":"Demonstrates how to initialize `RestClient` and perform a basic GET request for a JSON resource, including error handling and null checks."},"warnings":[{"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.","message":"Version 2.0.0 and above of `typed-rest-client` requires Node.js version 16 or higher. Older Node.js versions are not supported.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Migrate to `typed-rest-client` version 2.x, ensuring your Node.js environment meets the >=16.0.0 requirement.","message":"Version 1 of `typed-rest-client` is End-of-Life (EOL) and contains known security vulnerabilities. It should not be used in production environments.","severity":"deprecated","affected_versions":"<2.0.0"},{"fix":"Ensure you are using correct subpath imports, e.g., `import { RestClient } from 'typed-rest-client/RestClient';`","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"Attempting to use CommonJS `require()` syntax with `typed-rest-client` v2.x, which is an ESM-only package.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... typed-rest-client/RestClient.js not supported."},{"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.","cause":"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.","error":"RestClient threw an error for status 401: Failed Request: (401)"},{"fix":"Always check if `response.result` is not `null` or `undefined` before accessing its properties: `if (response.statusCode === 200 && response.result) { ... }`.","cause":"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.","error":"TypeError: Cannot read properties of null (reading 'id')"}],"ecosystem":"npm"}