a cache for slack profile pictures and emojis
dunkirk.sh
1/**
2 * Type-safe route system that generates Swagger documentation from route definitions
3 * This ensures the Swagger docs stay in sync with the actual API implementation
4 */
5
6// Base types for HTTP methods
7export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
8
9// Parameter types
10export interface RouteParam {
11 name: string;
12 type: "string" | "number" | "boolean";
13 required: boolean;
14 description: string;
15 example?: unknown;
16}
17
18// Response types
19export interface ApiResponse {
20 status: number;
21 description: string;
22 schema?: Record<string, unknown>; // JSON Schema or example object
23}
24
25// Route metadata for Swagger generation
26export interface RouteMetadata {
27 summary: string;
28 description?: string;
29 tags?: string[];
30 parameters?: {
31 path?: RouteParam[];
32 query?: RouteParam[];
33 body?: Record<string, unknown>; // JSON Schema for request body
34 };
35 responses: Record<number, ApiResponse>;
36 requiresAuth?: boolean;
37}
38
39// Handler function type
40export type RouteHandler = (request: Request) => Promise<Response> | Response;
41
42// Enhanced route definition that includes metadata
43export interface TypedRoute {
44 handler: RouteHandler;
45 metadata: RouteMetadata;
46}
47
48// Method-specific route definitions (matching Bun's pattern)
49export interface RouteDefinition {
50 GET?: TypedRoute;
51 POST?: TypedRoute;
52 PUT?: TypedRoute;
53 DELETE?: TypedRoute;
54 PATCH?: TypedRoute;
55}
56
57// Type helper to create routes with metadata
58export function createRoute(
59 handler: RouteHandler,
60 metadata: RouteMetadata,
61): TypedRoute {
62 return { handler, metadata };
63}
64
65// Type helper for path parameters
66export function pathParam(
67 name: string,
68 type: RouteParam["type"] = "string",
69 description: string,
70 example?: unknown,
71): RouteParam {
72 return { name, type, required: true, description, example };
73}
74
75// Type helper for query parameters
76export function queryParam(
77 name: string,
78 type: RouteParam["type"] = "string",
79 description: string,
80 required = false,
81 example?: unknown,
82): RouteParam {
83 return { name, type, required, description, example };
84}
85
86// Type helper for API responses
87export function apiResponse(
88 status: number,
89 description: string,
90 schema?: Record<string, unknown>,
91): [number, ApiResponse] {
92 return [status, { status, description, schema }];
93}