Runtime-enforced API contract system for Node.js
npm install heicatbash
Install both packages
npm install heicat-core heicat-cli
Or install individually
npm install heicat-core
npm install -D heicat-cli
`
$3
Initialize contracts in your project:
`bash
npx heicat init
`
Add middleware to your Express app:
`typescript
import { contractMiddleware } from "heicat-core";
app.use(
contractMiddleware({
contractsPath: "./contracts",
mode: "dev"
})
);
`
That's it! Your API now has runtime contract enforcement.
What It Does
- Validates requests before they reach your handlers
- Validates responses before they're sent to clients
- Validates errors to ensure consistent error shapes
- Logs violations with clear, actionable messages
- Works in dev, strict, and CI modes
Example Violation
`
❌ POST /users: Response missing field: email
`
CLI Commands
`bash
Initialize contracts in your project
heicat init [--contracts-path ]
Validate contract files (syntax + schema)
heicat validate [--contracts-path ]
Show contract status and statistics
heicat status [--contracts-path ]
Watch contracts and validate in real-time
heicat watch [--contracts-path ] [--port ]
Test contracts against running server
heicat test [--contracts-path ]
`
Contract Format
Contracts are simple JSON files:
`json
{
"method": "POST",
"path": "/users",
"request": {
"body": {
"email": { "type": "string", "required": true },
"password": { "type": "string", "minLength": 8 }
}
},
"response": {
"200": {
"id": "string",
"email": "string"
}
},
"errors": {
"400": { "message": "string" }
}
}
`
Modes
- dev: Logs warnings, doesn't block responses
- strict: Blocks invalid responses (implemented)
- ci: Fails process on violations (implemented)
Why This Works
TypeScript validates at compile time. This validates at runtime.
- Catches silent API drift
- Enforces backend behavior consistency
- Makes contracts the source of truth
- Requires almost zero adoption effort
Project Structure
`
your-project/
├─ contracts/
│ ├─ users.contract.json
│ ├─ auth.contract.json
├─ src/
│ ├─ routes/
└─ package.json
`
Testing
$3
#### 1. Validate Contract Syntax
`bash
Validate all contract files
heicat validate
Validate specific contracts directory
heicat validate --contracts-path ./my-contracts
`
#### 2. Test Against Running Server
`bash
Start your server first
npm start
Test all contracts against localhost:3000
heicat test http://localhost:3000
Test specific contracts
heicat test http://localhost:3000 --contracts-path ./contracts
`
#### 3. Watch Mode with Live GUI
`bash
Start watch mode with GUI dashboard
heicat watch
Opens http://localhost:3333 with live violations dashboard
`
$3
#### Testing the Middleware
1. Start the example app:
`bash
cd examples/express-app
npm install
npm start
`
2. Test valid request:
`bash
curl -X POST http://localhost:3000/users \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","password":"password123","name":"Test User"}'
`
3. Test invalid request (missing required field):
`bash
curl -X POST http://localhost:3000/users \
-H "Content-Type: application/json" \
-d '{"password":"password123"}'
Should return 400 with validation error
`
4. Test login:
`bash
curl -X POST http://localhost:3000/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","password":"password123"}'
`
$3
#### Running Tests
`bash
Test all packages
npm test
Test specific package
cd packages/core
npm test
cd packages/cli
npm test
`
#### Writing Tests
Tests use Jest and are located in __tests__/ directories or *.test.ts files.
Example test structure:
`
packages/core/
src/
__tests__/
validation-engine.test.ts
middleware.test.ts
`
$3
#### End-to-End Testing
1. Start the example server
2. Run contract tests:
`bash
contract-studio test http://localhost:3000
`
#### CI/CD Testing
Add to your CI pipeline:
`yaml
- name: Validate Contracts
run: npx heicat validate
- name: Test Contracts
run: |
npm start &
sleep 5
npx heicat test http://localhost:3000
`
Local Developer GUI
Start the interactive dashboard for real-time contract monitoring:
`bash
npx heicat watch --port 3333
`
Features:
- Dark Mode: Modern ShadCN-inspired dark theme
- Real-time Monitoring: Auto-updates every 3 seconds
- Violation Dashboard: Live statistics and detailed violation logs
- Contract Status: Shows loaded contracts and monitoring status
- Responsive Design: Works on desktop and mobile devices
Dashboard Includes:
- Statistics Cards: Total violations, errors, and warnings with icons
- Status Indicator: Live monitoring status with animated pulse
- Violation Details: Formatted error messages with severity badges
- Clear Function: Reset violation logs for fresh monitoring
- Auto-scroll: Smooth scrolling for long violation lists
Design System:
- ShadCN-inspired components with proper dark mode colors
- Inter font for modern typography
- Consistent spacing and border radius
- Subtle shadows and hover effects
- Accessible focus states and keyboard navigation
Runs locally at http://localhost:3333 with no authentication required.
Development
$3
This is a monorepo managed with NPM workspaces.
`bash
Install all dependencies
npm install
Build all packages
npm run build
Build individual packages
npm run build:core
npm run build:cli
Run tests
npm test
Clean build artifacts
npm run clean
`
$3
`bash
Bump version and publish all packages
npm run release
Or publish individually
cd packages/core && npm publish
cd packages/cli && npm publish
`
$3
`bash
Run the example Express app
cd examples/express-app
npm install
npm start
Start GUI dashboard
npm run watch
`
Project Structure
`
heicat/
├── packages/
│ ├── core/ # Runtime middleware package
│ └── cli/ # CLI tools package
├── examples/
│ └── express-app/ # Example implementation
├── package.json # Monorepo root
└── README.md
``