@antelopejs/interface-api-util

Request validation and rate limiting helpers for handlers written against @antelopejs/interface-api. Every failure becomes an HTTPResult error response.

Part of AntelopeJS. Used by AntelopeJS DMS, the open-source back office for your PostgreSQL, MongoDB or RethinkDB database.

What it offers

• assert(condition, code, message) throws an HTTPResult when the condition is falsy and narrows its type when it holds.
• assertValidation(body, validator) runs a synchronous validator, such as a Zod parse, and turns a thrown error into an error response, 400 by default.
• @RateLimit(limit, windowMs) caps calls to a handler per client in a fixed window and answers 429 beyond it.

Implementations

The helpers run in your module. They need the API interface served by a module:

| Module | Notes | | ------------------------------------------------------ | --------------------------------------------------------------------------- | | @antelopejs/api | Implements @antelopejs/interface-api and @antelopejs/interface-api-util |

Install

Add the package to the module that declares routes:

pnpm add @antelopejs/interface-api-util

Then add an implementation of the API interface to the project:

ajs project modules add @antelopejs/api

Quick start

import {
  Controller,
  Get,
  HTTPResult,
  Parameter,
} from "@antelopejs/interface-api";
import { RateLimit, assert } from "@antelopejs/interface-api-util";

const BOOKS = new Map([["1", { title: "The Glass Meridian" }]]);

export class BookController extends Controller("/books") {
  @Get(":id")
  @RateLimit(100, 60_000)
  async getBook(@Parameter("id") id: string) {
    const book = BOOKS.get(id);
    assert(book, 404, "Book not found");
    return new HTTPResult(200, book);
  }
}

Place @RateLimit directly below the route decorator. Placed above it, @RateLimit throws when the class is defined.

Documentation

• Assertions, validation and rate limiting

Compatibility

The module declares these peer dependencies:

| Package | Supported | Tested with | | ---------------------------- | ---------------- | ----------- | | @antelopejs/interface-api | >=0.3.0 <1.0.0 | 0.2.0 | | @antelopejs/interface-core | >=0.2.4 <1.0.0 | 0.4.0 |

Contributing

Read CONTRIBUTING.md before you open a pull request. The local checks are:

pnpm install
pnpm lint
pnpm test

License

Apache-2.0