api-contract-guard

Ensures backend responses never break frontend contracts

Install

npm install api-contract-guard

Usage

In tests

const { guardResponse } = require('api-contract-guard');

const schema = { id: 'number', name: 'string' };
const res = guardResponse({ id: 123, name: 'Alex' }, schema);

if (!res.valid) {
  console.error('⚠ Contract violation detected', res.errors);
}

Express middleware

const express = require('express');
const { expressGuard } = require('api-contract-guard');

const app = express();
const schema = { id: 'number', name: 'string' };

app.use(expressGuard({
  'GET /users': schema,
  '*': { id: 'number' },  // fallback
}));

app.get('/users', (req, res) => res.json({ id: 1, name: 'Alex' }));

Fastify

const { fastifyGuard } = require('api-contract-guard');

fastify.addHook('preSerialization', fastifyGuard({
  'GET /users': { id: 'number', name: 'string' },
}));

With Zod

If you use Zod, pass your schema directly - api-contract-guard uses schema.safeParse():

const { z } = require('zod');
const { guardResponse } = require('api-contract-guard');

const UserSchema = z.object({ id: z.number(), name: z.string() });
const result = guardResponse(apiResponse, UserSchema);

Schema format

Plain object schema: { key: 'string' | 'number' | 'boolean' | 'object' | 'array' }

License

MIT