Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .git-blame-ignore-revs
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Formatted with oxfmt when the repository moved off Biome.
4328ceb8fd62291c3dfcf11b2a8a78645b280132
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,6 @@ jobs:
- run: pnpm add --global @antelopejs/core
- run: pnpm prepack
- run: pnpm lint
- run: pnpm format:check
- run: pnpm knip
- run: pnpm test
8 changes: 4 additions & 4 deletions .github/workflows/stale.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
name: 'Close stale issues'
name: "Close stale issues"

on:
schedule:
- cron: '30 * * * *'
- cron: "30 * * * *"
workflow_dispatch:

permissions:
Expand All @@ -17,8 +17,8 @@ jobs:
- uses: actions/stale@v9
with:
exempt-issue-labels: pending
stale-issue-message: 'This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days.'
close-issue-message: 'This issue was closed because it has been stalled for 30 days with no activity.'
stale-issue-message: "This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days."
close-issue-message: "This issue was closed because it has been stalled for 30 days with no activity."
days-before-stale: 60
days-before-close: 30
operations-per-run: 200
Expand Down
18 changes: 9 additions & 9 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
| --------------------- | --------------------------------------------------------------------------------------- |
| English only | All code must be in English: variable names, function names, comments |
| PNPM only | Always use pnpm, never npm or yarn |
| NO COMMENTS | Code must be self-documenting through clear naming. TSDoc is allowed for public APIs |
| NO COMMENTS | Code must be self-documenting through clear naming. TSDoc is allowed for public APIs |
| NO switch/case | Use objects, maps, or arrays instead |
| NO inline types | Define proper interfaces/types, never use anonymous types like `{a: string, b: number}` |
| Functions ≤ 40 lines | Split into subfunctions if longer |
Expand All @@ -35,23 +35,23 @@ Never use `switch/case` or `if param === 'XXX'` chains. Instead:
// BAD
function getStatus(code: string) {
switch (code) {
case 'A':
return 'Active';
case 'I':
return 'Inactive';
case "A":
return "Active";
case "I":
return "Inactive";
default:
return 'Unknown';
return "Unknown";
}
}

// GOOD
const STATUS_MAP: Record<string, string> = {
A: 'Active',
I: 'Inactive',
A: "Active",
I: "Inactive",
};

function getStatus(code: string) {
return STATUS_MAP[code] ?? 'Unknown';
return STATUS_MAP[code] ?? "Unknown";
}
```

Expand Down
3 changes: 0 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
# Changelog


## v0.0.13

[compare changes](https://github.com/AntelopeJS/interface-api/compare/v0.0.12...v0.0.13)
Expand Down Expand Up @@ -145,7 +144,6 @@

## v0.0.2


### 🚀 Enhancements

- Add API interface implementation ([981bb27](https://github.com/AntelopeJS/interface-api/commit/981bb27))
Expand All @@ -172,4 +170,3 @@
- Antony Rizzitelli <upd4ting@gmail.com>
- Glastis ([@Glastis](http://github.com/Glastis))
- Fabrice Cst <fabrice@altab.be>

56 changes: 0 additions & 56 deletions biome.json

This file was deleted.

51 changes: 39 additions & 12 deletions docs/2.controllers.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,13 @@ The function ensures that computed properties and injected parameters are proper
Controllers contain methods decorated with HTTP method decorators that define route handlers.

```typescript
import { Controller, Get, Post, Delete, HTTPResult } from "@antelopejs/interface-api";
import {
Controller,
Get,
Post,
Delete,
HTTPResult,
} from "@antelopejs/interface-api";

class UsersController extends Controller("/users") {
@Get()
Expand Down Expand Up @@ -154,7 +160,13 @@ Postfix handlers run after the main handler completes. They are useful for respo
> **Warning:** If a postfix handler returns a value, all subsequent postfix handlers are skipped.

```typescript
import { Controller, Get, Postfix, Result, HTTPResult } from "@antelopejs/interface-api";
import {
Controller,
Get,
Postfix,
Result,
HTTPResult,
} from "@antelopejs/interface-api";

class UsersController extends Controller("/users") {
@Get(":id")
Expand All @@ -174,7 +186,13 @@ class UsersController extends Controller("/users") {
Monitor handlers run after request processing completes, regardless of success or failure. Their return value is ignored. Use them for logging, metrics, or other observation tasks.

```typescript
import { Controller, Get, Monitor, Context, RequestContext } from "@antelopejs/interface-api";
import {
Controller,
Get,
Monitor,
Context,
RequestContext,
} from "@antelopejs/interface-api";

class UsersController extends Controller("/users") {
@Get(":id")
Expand All @@ -196,7 +214,11 @@ class UsersController extends Controller("/users") {
WebSocket handlers manage persistent connections using the `@WebsocketHandler` decorator.

```typescript
import { Controller, WebsocketHandler, Connection } from "@antelopejs/interface-api";
import {
Controller,
WebsocketHandler,
Connection,
} from "@antelopejs/interface-api";

class ChatController extends Controller("/chat") {
@WebsocketHandler()
Expand All @@ -217,7 +239,12 @@ class ChatController extends Controller("/chat") {
Handlers can be assigned priorities to control execution order. This is especially useful when multiple prefix or postfix handlers match the same route.

```typescript
import { Controller, Prefix, HandlerPriority, HTTPResult } from "@antelopejs/interface-api";
import {
Controller,
Prefix,
HandlerPriority,
HTTPResult,
} from "@antelopejs/interface-api";

class SecuredController extends Controller("/api") {
@Prefix("get", "*", HandlerPriority.HIGHEST)
Expand All @@ -240,13 +267,13 @@ class SecuredController extends Controller("/api") {

The available priority levels are:

| Priority | Value | Description |
| --------------------------- | ----- | ---------------- |
| `HandlerPriority.HIGHEST` | 0 | Executes first |
| `HandlerPriority.HIGH` | 1 | High priority |
| `HandlerPriority.NORMAL` | 2 | Default priority |
| `HandlerPriority.LOW` | 3 | Low priority |
| `HandlerPriority.LOWEST` | 4 | Executes last |
| Priority | Value | Description |
| ------------------------- | ----- | ---------------- |
| `HandlerPriority.HIGHEST` | 0 | Executes first |
| `HandlerPriority.HIGH` | 1 | High priority |
| `HandlerPriority.NORMAL` | 2 | Default priority |
| `HandlerPriority.LOW` | 3 | Low priority |
| `HandlerPriority.LOWEST` | 4 | Executes last |

## The `Listen` function

Expand Down
30 changes: 18 additions & 12 deletions docs/3.http-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ import { HTTPResult } from "@antelopejs/interface-api";
// From a plain body
const result = HTTPResult.withHeaders(
{ message: "Success" },
{ "X-Request-Id": "abc-123" }
{ "X-Request-Id": "abc-123" },
);

// From an existing HTTPResult
Expand All @@ -112,7 +112,13 @@ const withExtra = HTTPResult.withHeaders(original, {
For long-running processes or server-sent events, use the `getWriteStream` method.

```typescript
import { Controller, Get, Context, WriteStream, RequestContext } from "@antelopejs/interface-api";
import {
Controller,
Get,
Context,
WriteStream,
RequestContext,
} from "@antelopejs/interface-api";
import { PassThrough } from "node:stream";

class StreamController extends Controller("/stream") {
Expand Down Expand Up @@ -140,16 +146,16 @@ The `getWriteStream` method accepts an optional content type (defaults to `text/

The `RequestContext` interface provides access to all request-related information.

| Property | Type | Description |
| ----------------- | ---------------------------- | -------------------------------------------- |
| `rawRequest` | `IncomingMessage` | The raw Node.js HTTP request object |
| `rawResponse` | `ServerResponse` | The raw Node.js HTTP response object |
| `url` | `URL` | The parsed request URL |
| `routeParameters` | `Record<string, string>` | Parameters extracted from URL path segments |
| `body` | `unknown` | The request body data |
| `response` | `HTTPResult` | The response object sent to the client |
| `error` | `unknown` | Error thrown during processing, if any |
| `connection` | `unknown` | WebSocket connection, if applicable |
| Property | Type | Description |
| ----------------- | ------------------------ | ------------------------------------------- |
| `rawRequest` | `IncomingMessage` | The raw Node.js HTTP request object |
| `rawResponse` | `ServerResponse` | The raw Node.js HTTP response object |
| `url` | `URL` | The parsed request URL |
| `routeParameters` | `Record<string, string>` | Parameters extracted from URL path segments |
| `body` | `unknown` | The request body data |
| `response` | `HTTPResult` | The response object sent to the client |
| `error` | `unknown` | Error thrown during processing, if any |
| `connection` | `unknown` | WebSocket connection, if applicable |

## Read request bodies

Expand Down
Loading