restyped

library1.1.0jsnpmunverified

RESTyped is a TypeScript specification and lightweight library for end-to-end typing of REST APIs. Current stable version is 1.1.0. It enables sharing request and response types between server and client via a single interface definition, ensuring type safety across HTTP boundaries. Unlike alternatives like tRPC or GraphQL codegen, RESTyped is unopinionated, works with any existing REST API, and adds no runtime overhead for most implementations. It supports common HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) and allows typing params, query, body, and response per route. Requires TypeScript 2.4+. The library itself is just type definitions; integrations exist for Axios and Express (the latter as WIP).

devops

npm install restyped

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RESTYPED

restyped

devopsjavascriptv1.1.0

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.

FoodDeliveryAPI

✓ import type { FoodDeliveryAPI } from 'food-delivery-api'

✗ import { FoodDeliveryAPI } from 'food-delivery-api'

Use import type to avoid emitting runtime code; RESTyped APIs are pure types.

RouteShape

✓ import { RouteShape } from 'restyped'

✗ const { RouteShape } = require('restyped')

RESTyped exports RouteShape as a named interface; it's only for TypeScript, not runtime.

default export

✓ import restyped from 'restyped'

✗ import * as restyped from 'restyped'

There is no default export; RESTyped only exports named types. This pattern is incorrect and leads to 'undefined'.

Demonstrates defining a typed REST API interface with GET and POST endpoints, then using TypedAxiosInstance from restyped-axios for type-safe HTTP calls.

// Define your API shape in a .d.ts file // my-api.d.ts export interface MyAPI { '/users': { GET: { query: { limit?: number } response: { id: number; name: string }[] } POST: { body: { name: string } response: { id: number } } } } // Use with restyped-axios import axios from 'axios'; import { TypedAxiosInstance } from 'restyped-axios'; import type { MyAPI } from './my-api'; const api: TypedAxiosInstance<MyAPI> = axios.create({ baseURL: 'https://api.example.com' }); // Type-safe GET request api.get('/users', { params: { limit: 10 } }) .then(res => { // res.data is inferred as { id: number; name: string }[] console.log(res.data[0].name); }); // Type-safe POST request api.post('/users', { name: 'Alice' }) .then(res => { // res.data is inferred as { id: number } console.log(res.data.id); });

Debug

Known issues

gotchaRoute paths must exactly match the keys in your interface; any mismatch (e.g., trailing slash) will break type inference.

fix

Ensure route paths in the interface and HTTP calls are identical (e.g., '/users' not '/users/').

affects: >=0.0.0

deprecatedThe 'params' field is only available for routes with dynamic segments; using it on a static route may cause TypeScript errors.

fix

Only define 'params' when the route has placeholders like ':id'. For static routes, omit 'params' entirely.

affects: >=1.0.0

gotchaRESTyped is a type-only library; it does not validate runtime data. If your server sends unexpected shapes, TypeScript won't catch it.

fix

Use runtime validation (e.g., zod, io-ts) alongside RESTyped for runtime safety.

affects: >=0.0.0

breakingIn v1.0.0, the 'RouteShape' helper was introduced, replacing the previous manual interface approach. Old 'ApiDefinition' exports are removed.

fix

Use 'RouteShape' from 'restyped' to define routes, or update your API definitions to match the new specification (interface per route).

affects: <1.0.0

Errors

Common errors & fixes

Type '{}' is not assignable to type 'MyAPI["/users"]["GET"]["response"]'.

The HTTP response does not match the defined response type in the API interface.

fix

Verify the server response matches the type in your interface, or adjust the interface to match the actual response.

Module '"restyped"' has no exported member 'RouteShape'.

Using an older version of restyped (<1.0.0) that does not export RouteShape.

fix

Upgrade to restyped@1.1.0: npm install restyped@latest

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/rawrmaan/restyped ↗

packagerestyped ↗

homepagehttps://github.com/rawrmaan/restyped#readme ↗