Registry / ai-ml / typed-axios-instance

typed-axios-instance

library3.3.1jsnpmunverified

A TypeScript library that adds full type safety to Axios instances by applying route definitions (generated from OpenAPI or Nextlove) as generic parameters. Current stable version is 3.3.1, actively maintained. Key differentiators: no need for generated client code; works directly with existing Axios instances; supports HTTP method discrimination for precise autocomplete on request/response shapes. Requires peer dependencies axios >=1.0.0 and type-fest >=3.0.0. Ships TypeScript types.

ai-ml testing

npm install typed-axios-instance

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TYPED-AXIOS-INSTAN

typed-axios-instance

ai-mljavascriptv3.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

TypedAxios

✓ import type { TypedAxios } from 'typed-axios-instance'

✗ import { TypedAxios } from 'typed-axios-instance' (value import; use type-only)

TypedAxios is a TypeScript type, not a runtime value. Use `import type` to avoid bundling.

RouteDef

✓ import type { RouteDef } from 'typed-axios-instance'

✗ import { RouteDef } from 'typed-axios-instance' (value import)

RouteDef is a type used to define route shapes. Type-only import recommended.

HTTPMethod

✓ import type { HTTPMethod } from 'typed-axios-instance'

Type representing HTTP methods (GET, POST, etc.). Import as type-only.

Shows creating a fully typed Axios instance with typed routes, demonstrating POST and GET methods with response types.

import type { TypedAxios } from 'typed-axios-instance'; import axios from 'axios'; type Routes = [ { route: '/things/create', method: 'POST', jsonBody: { name?: string | undefined }, jsonResponse: { thing: { thing_id: string; name: string; created_at: string | Date } } }, { route: '/things/:thing_id', method: 'GET', jsonResponse: { thing: { thing_id: string; name: string; created_at: string | Date } } } ]; const api: TypedAxios<Routes> = axios.create({ baseURL: process.env.API_URL ?? 'https://example.com' }); const createThing = async (name?: string) => { const { data } = await api.post('/things/create', { name }); return data.thing; };

Debug

Known issues

gotchaTypedAxios is a type, not a class. Trying to use `new TypedAxios()` or `TypedAxios.create()` will fail.

fix

Assign the type to an existing Axios instance via `const api: TypedAxios<Routes> = axios.create(...)`.

affects: >=3.0.0

gotchaRoute definitions must match the actual API. TypeScript will not enforce runtime correctness; incorrect route definitions will cause silent mismatches.

fix

Generate route types from OpenAPI or Nextlove to ensure they reflect the real API.

affects: >=3.0.0

gotchaHTTP method discrimination only works when routes are defined as an array of RouteDef, not as an object map.

fix

Use array syntax `Routes = RouteDef[]` instead of `{ [route:string]: RouteDef }` for per-method autocomplete.

affects: >=3.0.0

deprecatedPeer dependency `type-fest` may be optional but is required for advanced route utilities. If missing, TypeScript compilation may fail.

fix

Install type-fest as a devDependency: `npm install --save-dev type-fest`

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: TypedAxios is not a constructor

Trying to instantiate TypedAxios as a class instead of using it as a type.

fix

Use `const api: TypedAxios<Routes> = axios.create(...)` instead of `new TypedAxios()`.

Cannot find module 'type-fest'

Missing peer dependency type-fest.

fix

Run `npm install --save-dev type-fest` to install the required type utilities.

Type 'Routes' does not satisfy the constraint 'RouteDef[]'

Route definition array does not match the expected RouteDef shape (missing 'route' or 'method').

fix

Ensure each route object has a 'route' (string) and 'method' (HTTP method) property, and optional jsonBody/jsonResponse.

Property 'data' does not exist on type 'AxiosResponse<unknown, any>'

TypeScript cannot infer the response type because the route definition is missing or incorrect.

fix

Verify that the route definition includes a valid `jsonResponse` that matches the actual API response body.

Upgrade

Version history

3.3.1latest on npm

Audit

Dependencies

axiosrequiredRuntime peer dependency: the typed instance wraps an Axios instance

type-festoptionalType-only peer dependency: provides utility types for route definitions

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/seamapi/typed-axios ↗

packagetyped-axios-instance ↗

homepagehttps://github.com/seamapi/typed-axios#readme ↗