feat: http routes documentation

Author: holtwick

zerva-http/package.json

@@ -62,18 +62,18 @@
     "bytes": "3.1.2",
     "compressible": "^2.0.18",
     "cors": "^2.8.5",
-    "express": "^4.19.2",
+    "express": "^4.20.0",
     "helmet": "^7.1.0",
     "mime": "^4.0.4",
     "negotiator": "^0.6.3",
     "on-headers": "^1.0.2",
     "vary": "^1.1.2",
-    "zeed": "^0.24.16"
+    "zeed": "^0.24.17"
   },
   "devDependencies": {
     "@zerva/bin": "workspace:*",
     "tsup": "^8.2.4",
-    "typescript": "^5.5.4",
+    "typescript": "^5.6.2",
     "vitest": "^2.0.5"
   }
 }

zerva-http/src/accepts.ts

@@ -6,8 +6,8 @@
  * MIT Licensed
  */
 
-import Negotiator from 'negotiator'
 import mime from 'mime'
+import Negotiator from 'negotiator'
 
 function Accepts(this: any, req: any) {
   if (!(this instanceof Accepts)) {

zerva-http/src/compression.ts

@@ -7,14 +7,14 @@
  * MIT Licensed
  */
 
-import zlib from 'node:zlib'
-import type { IncomingMessage } from 'node:http'
-import type { Readable } from 'node:stream'
 import { Buffer } from 'node:buffer'
+import zlib from 'node:zlib'
 import bytes from 'bytes'
 import compressible from 'compressible'
 import onHeaders from 'on-headers'
 import vary from 'vary'
+import type { IncomingMessage } from 'node:http'
+import type { Readable } from 'node:stream'
 import accepts from './accepts'
 
 const cacheControlNoTransformRegExp = /(?:^|,)\s*?no-transform\s*?(?:,|$)/

zerva-http/src/http.ts

@@ -3,20 +3,20 @@
 import fs from 'node:fs'
 import httpModule from 'node:http'
 import httpsModule from 'node:https'
-import type { AddressInfo } from 'node:net'
 import process from 'node:process'
 import { emit, on, register } from '@zerva/core'
 import corsDefault from 'cors'
 import express from 'express'
-import type { HelmetOptions } from 'helmet'
 import helmetDefault from 'helmet'
+import { isLocalHost, isString, LoggerFromConfig, LogLevelInfo, promisify, valueToBoolean } from 'zeed'
+import type { HelmetOptions } from 'helmet'
+import type { AddressInfo } from 'node:net'
 import type { LogConfig } from 'zeed'
-import { LogLevelInfo, LoggerFromConfig, isLocalHost, isString, promisify, valueToBoolean } from 'zeed'
 import { compressionMiddleware } from './compression'
 import type { Express, NextFunction, Request, Response, Server, zervaHttpGetHandler, zervaHttpHandlerModes, zervaHttpInterface, zervaHttpPaths } from './types'
 
-export * from './types'
 export * from './status'
+export * from './types'
 
 const moduleName = 'http'
 
@@ -179,14 +179,25 @@ export function useHttp(config?: {
     log.error('client request error', err)
   })
 
+  interface ZervaHttpRouteDescription {
+    path: string
+    method: string
+    description: string
+  }
+
+  const routes: ZervaHttpRouteDescription[] = []
+
   function smartRequestHandler(
     mode: zervaHttpHandlerModes,
     path: zervaHttpPaths,
     handlers: zervaHttpGetHandler[],
-  ): void {
+  ) {
     if (isString(path) && !path.startsWith('/'))
       path = `/${path}`
 
+    const route: ZervaHttpRouteDescription = { path: String(path), method: mode, description: '' }
+    routes.push(route)
+
     log(`register ${mode.toUpperCase()} ${path}`)
 
     let suffix: string | undefined
@@ -243,6 +254,12 @@ export function useHttp(config?: {
         }
       })
     }
+
+    return {
+      description(description: string) {
+        route.description = description
+      },
+    }
   }
 
   function addStatic(path: zervaHttpPaths, fsPath: string): void {
@@ -286,6 +303,7 @@ export function useHttp(config?: {
       addStatic,
       static: addStatic,
       STATIC: addStatic,
+      routes,
     } as any)
   })
 
@@ -315,6 +333,7 @@ export function useHttp(config?: {
       addStatic,
       static: addStatic,
       STATIC: addStatic,
+      routes,
     } as any)
     server.listen({ host, port }, () => {
       const { port, family, address } = server.address() as AddressInfo

zerva-http/src/index.ts

@@ -1,3 +1,3 @@
-export * from './types'
 export * from './http'
 export * from './status'
+export * from './types'

zerva-http/src/status.ts

@@ -1,5 +1,5 @@
-import type { LoggerInterface } from 'zeed'
 import { Logger } from 'zeed'
+import type { LoggerInterface } from 'zeed'
 
 const log: LoggerInterface = Logger('status')
 

zerva-http/src/types.ts

@@ -1,5 +1,5 @@
-import type { Server } from 'node:http'
 import type { Express, NextFunction, Request, RequestHandler, Response } from 'express'
+import type { Server } from 'node:http'
 
 export type { Server }
 export type { Express, NextFunction, Request, RequestHandler, Response }