@nodezor/api-contract-guard

Real-time type-safe API contract and payload shape validation guard.

The Problem

Frontend and backend applications often drift out of sync during rapid iteration, causing breaking changes, missing properties, or invalid payload types on production endpoints. Standard integration tests rarely catch real-time API shape mismatches before end users encounter runtime type errors in client applications.

Features

• 🛡️ Payload Contract Verification: Validates object structures, arrays, primitives, and URLs.
• ⚡ Zero External Dependencies: Lightweight and fast using native JavaScript primitives.
• 📊 Diagnostic Table Reporting: Prints structured console tables for mismatched or missing fields.
• 🔒 TypeScript Inference: Auto-infers the shape of validated API response payloads.

Installation

# pnpm
pnpm add @nodezor/api-contract-guard

# npm
npm install @nodezor/api-contract-guard

# yarn
yarn add @nodezor/api-contract-guard

Quick Start / Usage Example

import { validatePayload } from '@nodezor/api-contract-guard';

const userResponseSchema = {
  id: { type: 'string', required: true },
  age: { type: 'number', required: true },
  active: { type: 'boolean', required: true },
  roles: { type: 'array', required: true },
  profileUrl: { type: 'url', required: true },
} as const;

async function fetchUser(userId: string) {
  const res = await fetch(`/api/users/${userId}`);
  const rawData = await res.json();

  // Validates payload shape at runtime and returns typed object
  const user = validatePayload(userResponseSchema, rawData);
  console.log(user.id, user.roles);
}

API Reference

validatePayload<S extends ContractSchema>(schema: S, payload: Record<string, unknown>, options?: ContractGuardOptions): InferContract<S>

Validates an API payload against a contract schema definition.

| Parameter | Type | Description | | :--- | :--- | :--- | | schema | ContractSchema | Schema defining field rules (type, required, fallback, validator) | | payload | Record<string, unknown> | Raw input payload to validate | | options | ContractGuardOptions | Options (exitOnFailure, reporter) |

Supported Types (ContractType)

• 'string', 'number', 'boolean', 'url', 'array', 'object'

License

MIT © PRX2112