http-schemas

0.13.2 verified Sat Apr 25 auth: no javascript

Strongly-typed HTTP schemas for TypeScript that enforce API contracts at build time and runtime. Version 0.13.2 ships TypeScript types and integrates with the rtti library for schema specification and enforcement. It supports both client-side (createHttpClient) and server-side (Express integration with createRequestHandler and decorateExpressRouter) usage. Key differentiators include static type checking of request/response payloads, runtime validation, and automatic response trimming to prevent information leaks. Release cadence is irregular; the v0.10 API is deprecated but still supported. Alternatives like tRPC and Zod offer similar functionality but with different trade-offs.

Common errors

error TypeError: Cannot read properties of undefined (reading 'reduce') ↓

cause The request body is undefined or not the expected type because the schema validation failed but error handling is missing.

fix

Wrap API calls in try/catch and handle validation errors from http-schemas.

error Error: Schema validation failed: request body is not an array ↓

cause The request body sent to a POST /sum endpoint is not an array of numbers.

fix

Ensure the body matches the schema: client.post('/sum', { body: [1,2] }).

error TS2322: Type 'string' is not assignable to type 'number' ↓

cause The static type checking from http-schemas catches mismatches between schema and usage.

fix

Correct the type of the argument to match the schema definition.

error Error: Cannot find module 'http-schemas/client' ↓

cause Import path is incorrect; http-schemas uses subpath exports.

fix

Use import { createHttpClient } from 'http-schemas/client'.

Warnings

deprecated The v0.10 API is deprecated but still supported. ↓

fix Migrate to the v0.11+ API: use createHttpSchema instead of the old API.

gotcha Response payloads are trimmed of excess properties at runtime to prevent information leaks. ↓

fix Be aware that response objects will have only the properties defined in the schema.

breaking The v0.10 API for server-side code is deprecated; decorateExpressRouter and createRequestHandler are the new way. ↓

fix Update server code to use decorateExpressRouter and createRequestHandler as shown in the README.

gotcha The schema definition uses the `t` object from `rtti`. Incorrect usage can lead to runtime validation failures. ↓

fix Ensure that requestBody and responseBody use valid `t` types (e.g., t.number, t.string, t.array, t.object).

gotcha createHttpClient instances are cheap to create but require a baseURL; missing baseURL will cause runtime errors. ↓

fix Always provide a baseURL option when creating a client, or ensure the schema includes full URLs.

Install

npm install http-schemas

yarn add http-schemas

pnpm add http-schemas

Imports

createHttpSchema

wrong

import httpSchemas from 'http-schemas'

correct

import { createHttpSchema } from 'http-schemas'

createHttpSchema is a named export from the main package.

createHttpClient

wrong

import { createHttpClient } from 'http-schemas'

correct

import { createHttpClient } from 'http-schemas/client'

createHttpClient is exported from the client subpath, not the main entry.

createRequestHandler

wrong

const createRequestHandler = require('http-schemas/server').createRequestHandler

correct

import { createRequestHandler } from 'http-schemas/server'

In CommonJS, use require but ensure it's from the server subpath.

decorateExpressRouter

wrong

import { decorateExpressRouter } from 'http-schemas'

correct

import { decorateExpressRouter } from 'http-schemas/server'

decorateExpressRouter is exported from the server subpath.

t
wrong
```
import { t } from 'rtti'
```
correct
```
import { t } from 'http-schemas'
```
t is re-exported from http-schemas for convenience when defining schemas.

Quickstart

Demonstrates defining an HTTP schema with createHttpSchema and using createHttpClient to make typed requests.

import { createHttpSchema, t } from 'http-schemas';
import { createHttpClient } from 'http-schemas/client';

// Define a shared schema
const apiSchema = createHttpSchema({
  'POST /sum': {
    requestBody: t.array(t.number),
    responseBody: t.number,
  },
  'GET /greet/:name': {
    responseBody: t.string,
  },
});

// Create a client
const client = createHttpClient(apiSchema, { baseURL: 'https://api.example.com' });

// Use the client
async function main() {
  const sum = await client.post('/sum', { body: [1, 2, 3] });
  console.log(sum); // 6
  const greeting = await client.get('/greet/:name', { params: { name: 'World' } });
  console.log(greeting); // Hello, World!
}
main().catch(console.error);