TypeDoc all the thngs

src/http/routing/Route.ts

@@ -12,23 +12,66 @@ import {Middlewares} from "../../service/Middlewares";
 import {Middleware} from "./Middleware";
 import {Config} from "../../service/Config";
 
+/**
+ * Type alias for an item that is a valid response object, or lack thereof.
+ */
 export type ResponseObject = ResponseFactory | string | number | void | any | Promise<ResponseObject>
+
+/**
+ * Type alias for an item that defines a direct route handler.
+ */
 export type RouteHandler = ((request: Request, response: Response) => ResponseObject) | ((request: Request) => ResponseObject) | (() => ResponseObject) | string
+
+/**
+ * Type alias for a function that applies a route handler to the request.
+ * The goal is to transform RouteHandlers to ResolvedRouteHandler.
+ */
 export type ResolvedRouteHandler = (request: Request) => ResponseObject
 
 
 // TODO domains, named routes - support this on groups as well
 
+/**
+ * A class that can be used to build and reference dynamic routes in the application.
+ *
+ * Routes can be defined in nested groups, with prefixes and middleware handlers.
+ *
+ * @example
+ * ```typescript
+ * Route.post('/api/v1/ping', (request: Request) => {
+ *     return 'pong!'
+ * })
+ *
+ * Route.group('/api/v2', () => {
+ *     Route.get('/status', 'controller::api:v2:Status.getStatus').pre('auth:UserOnly')
+ * })
+ * ```
+ */
 export class Route extends AppClass {
+    /** Routes that have been created and registered in the application. */
     private static registeredRoutes: Route[] = []
+
+    /** Groups of routes that have been registered with the application. */
     private static registeredGroups: RouteGroup[] = []
 
+    /**
+     * The current nested group stack. This is used internally when compiling the routes by nested group.
+     * @private
+     */
     private static compiledGroupStack: RouteGroup[] = []
 
+    /** Register a route group handler. */
     public static registerGroup(group: RouteGroup) {
         this.registeredGroups.push(group)
     }
 
+    /**
+     * Load and compile all of the registered routes and their groups, accounting
+     * for nested groups and resolving handlers.
+     *
+     * This function attempts to resolve the route handlers ahead of time to cache
+     * them and also expose any handler resolution errors that might happen at runtime.
+     */
     public static async compile(): Promise<Route[]> {
         let registeredRoutes = this.registeredRoutes
         const registeredGroups = this.registeredGroups
@@ -103,53 +146,87 @@ export class Route extends AppClass {
         return registeredRoutes
     }
 
+    /**
+     * Create a new route on the given endpoint for the given HTTP verb.
+     * @param method
+     * @param definition
+     * @param handler
+     */
     public static endpoint(method: HTTPMethod | HTTPMethod[], definition: string, handler: RouteHandler) {
         const route = new Route(method, handler, definition)
         this.registeredRoutes.push(route)
         return route
     }
 
+    /**
+     * Create a new GET route on the given endpoint.
+     * @param definition
+     * @param handler
+     */
     public static get(definition: string, handler: RouteHandler) {
         return this.endpoint('get', definition, handler)
     }
 
+    /** Create a new POST route on the given endpoint. */
     public static post(definition: string, handler: RouteHandler) {
         return this.endpoint('post', definition, handler)
     }
 
+    /** Create a new PUT route on the given endpoint. */
     public static put(definition: string, handler: RouteHandler) {
         return this.endpoint('put', definition, handler)
     }
 
+    /** Create a new PATCH route on the given endpoint. */
     public static patch(definition: string, handler: RouteHandler) {
         return this.endpoint('patch', definition, handler)
     }
 
+    /** Create a new DELETE route on the given endpoint. */
     public static delete(definition: string, handler: RouteHandler) {
         return this.endpoint('delete', definition, handler)
     }
 
+    /** Create a new route on all HTTP verbs, on the given endpoint. */
     public static any(definition: string, handler: RouteHandler) {
         return this.endpoint(['get', 'put', 'patch', 'post', 'delete'], definition, handler)
     }
 
+    /** Create a new route group with the given prefix. */
     public static group(prefix: string, group: () => void | Promise<void>) {
         const grp = <RouteGroup> Application.getApplication().make(RouteGroup, group, prefix)
         this.registeredGroups.push(grp)
         return grp
     }
 
+    /** Middlewares that should be applied to this route. */
     protected middlewares: Collection<{ stage: 'pre' | 'post', handler: RouteHandler }> = new Collection<{stage: "pre" | "post"; handler: RouteHandler}>()
+
+    /** Pre-compiled route handlers for the pre-middleware for this route. */
     protected _compiledPreflight?: ResolvedRouteHandler[]
+
+    /** Pre-compiled route handlers for the post-middleware for this route. */
     protected _compiledHandler?: ResolvedRouteHandler
+
+    /** Pre-compiled route handler for the main route handler for this route. */
     protected _compiledPostflight?: ResolvedRouteHandler[]
 
     constructor(
+        /** The HTTP method(s) that this route listens on. */
         protected method: HTTPMethod | HTTPMethod[],
+
+        /** The primary handler of this route. */
         protected readonly handler: RouteHandler,
+
+        /** The route path this route listens on. */
         protected route: string
     ) { super() }
 
+    /**
+     * Returns true if this route matches the given HTTP verb and request path.
+     * @param method
+     * @param potential
+     */
     public match(method: HTTPMethod, potential: string): boolean {
         if ( Array.isArray(this.method) && !this.method.includes(method) ) return false
         else if ( !Array.isArray(this.method) && this.method !== method ) return false
@@ -157,6 +234,20 @@ export class Route extends AppClass {
         return !!this.extract(potential)
     }
 
+    /**
+     * Given a request path, try to extract this route's paramters from the path string.
+     *
+     * @example
+     * For route `/foo/:bar/baz` and input `/foo/bob/baz`, extracts:
+     *
+     * ```typescript
+     * {
+     *     bar: 'bob'
+     * }
+     * ```
+     *
+     * @param potential
+     */
     public extract(potential: string): {[key: string]: string} | undefined {
         const routeParts = (this.route.startsWith('/') ? this.route.substr(1) : this.route).split('/')
         const potentialParts = (potential.startsWith('/') ? potential.substr(1) : potential).split('/')
@@ -192,6 +283,9 @@ export class Route extends AppClass {
         return params
     }
 
+    /**
+     * Try to pre-compile and return the preflight handlers for this route.
+     */
     public resolvePreflight(): ResolvedRouteHandler[] {
         if ( !this._compiledPreflight ) {
             this._compiledPreflight = this.resolveMiddlewareHandlersForStage('pre')
@@ -200,6 +294,9 @@ export class Route extends AppClass {
         return this._compiledPreflight
     }
 
+    /**
+     * Try to pre-compile and return the postflight handlers for this route.
+     */
     public resolvePostflight(): ResolvedRouteHandler[] {
         if ( !this._compiledPostflight ) {
             this._compiledPostflight = this.resolveMiddlewareHandlersForStage('post')
@@ -208,6 +305,9 @@ export class Route extends AppClass {
         return this._compiledPostflight
     }
 
+    /**
+     * Try to pre-compile and return the main handler for this route.
+     */
     public resolveHandler(): ResolvedRouteHandler {
         if ( !this._compiledHandler ) {
             this._compiledHandler = this._resolveHandler()
@@ -216,6 +316,7 @@ export class Route extends AppClass {
         return this._compiledHandler
     }
 
+    /** Register the given middleware as a preflight handler for this route. */
     pre(middleware: RouteHandler) {
         this.middlewares.push({
             stage: 'pre',
@@ -225,6 +326,7 @@ export class Route extends AppClass {
         return this
     }
 
+    /** Register the given middleware as a postflight handler for this route. */
     post(middleware: RouteHandler) {
         this.middlewares.push({
             stage: 'post',
@@ -234,20 +336,27 @@ export class Route extends AppClass {
         return this
     }
 
+    /** Prefix the route's path with the given prefix, normalizing `/` characters. */
     private prepend(prefix: string) {
         if ( !prefix.endsWith('/') ) prefix = `${prefix}/`
         if ( this.route.startsWith('/') ) this.route = this.route.substring(1)
         this.route = `${prefix}${this.route}`
     }
 
+    /** Add the given middleware item to the beginning of the preflight handlers. */
     private prependMiddleware(def: { stage: 'pre' | 'post', handler: RouteHandler }) {
         this.middlewares.prepend(def)
     }
 
+    /** Add the given middleware item to the end of the postflight handlers. */
     private appendMiddleware(def: { stage: 'pre' | 'post', handler: RouteHandler }) {
         this.middlewares.push(def)
     }
 
+    /**
+     * Resolve and return the route handler for this route.
+     * @private
+     */
     private _resolveHandler(): ResolvedRouteHandler {
         if ( typeof this.handler !== 'string' ) {
             return (request: Request) => {
@@ -289,6 +398,11 @@ export class Route extends AppClass {
         }
     }
 
+    /**
+     * Resolve and return the route handlers for the given pre- or post-flight stage.
+     * @param stage
+     * @private
+     */
     private resolveMiddlewareHandlersForStage(stage: 'pre' | 'post'): ResolvedRouteHandler[] {
         return this.middlewares.where('stage', '=', stage)
             .map<ResolvedRouteHandler>(def => {
@@ -330,6 +444,7 @@ export class Route extends AppClass {
             .toArray()
     }
 
+    /** Cast the route to an intelligible string. */
     toString() {
         const method = Array.isArray(this.method) ? this.method : [this.method]
         return `${method.join('|')} -> ${this.route}`