@adonisjs/http-server 6.8.2-1 → 6.8.2-11

package/build/src/router/brisk.d.ts

@@ -3,17 +3,39 @@ import type { Application } from '@adonisjs/application';
 import { Route } from './route.js';
 import type { ParsedGlobalMiddleware } from '../types/middleware.js';
 import type { MakeUrlOptions, RouteFn, RouteMatchers } from '../types/route.js';
+/**
+ * Brisk routes exposes the API to configure the route handler by chaining
+ * one of the pre-defined methods.
+ *
+ * For example: Instead of defining the redirect logic as a callback, one can
+ * chain the `.redirect` method.
+ *
+ * Brisk routes are always registered under the `GET` HTTP method.
+ */
 export declare class BriskRoute extends Macroable {
     #private;
+    /**
+     * Reference to route instance. Set after `setHandler` is called
+     */
     route: null | Route;
     constructor(app: Application<any>, routerMiddleware: ParsedGlobalMiddleware[], options: {
         pattern: string;
         globalMatchers: RouteMatchers;
     });
+    /**
+     * Set handler for the brisk route
+     */
     setHandler(handler: RouteFn): Route;
+    /**
+     * Redirects to a given route. Params from the original request will
+     * be used when no custom params are defined.
+     */
     redirect(identifier: string, params?: any[] | Record<string, any>, options?: MakeUrlOptions & {
         status: number;
     }): Route;
+    /**
+     * Redirect request to a fixed URL
+     */
     redirectToPath(url: string, options?: {
         status: number;
     }): Route;

package/build/src/router/brisk.js

@@ -1,10 +1,42 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import Macroable from '@poppinss/macroable';
 import { Route } from './route.js';
+/**
+ * Brisk routes exposes the API to configure the route handler by chaining
+ * one of the pre-defined methods.
+ *
+ * For example: Instead of defining the redirect logic as a callback, one can
+ * chain the `.redirect` method.
+ *
+ * Brisk routes are always registered under the `GET` HTTP method.
+ */
 export class BriskRoute extends Macroable {
+    /**
+     * Route pattern
+     */
     #pattern;
+    /**
+     * Matchers inherited from the router
+     */
     #globalMatchers;
+    /**
+     * Reference to the AdonisJS application
+     */
     #app;
+    /**
+     * Middleware registered on the router
+     */
     #routerMiddleware;
+    /**
+     * Reference to route instance. Set after `setHandler` is called
+     */
     route = null;
     constructor(app, routerMiddleware, options) {
         super();
@@ -13,6 +45,9 @@ export class BriskRoute extends Macroable {
         this.#pattern = options.pattern;
         this.#globalMatchers = options.globalMatchers;
     }
+    /**
+     * Set handler for the brisk route
+     */
     setHandler(handler) {
         this.route = new Route(this.#app, this.#routerMiddleware, {
             pattern: this.#pattern,
@@ -22,8 +57,12 @@ export class BriskRoute extends Macroable {
         });
         return this.route;
     }
+    /**
+     * Redirects to a given route. Params from the original request will
+     * be used when no custom params are defined.
+     */
     redirect(identifier, params, options) {
-        return this.setHandler(async (ctx) => {
+        return this.setHandler(async function redirectsToRoute(ctx) {
             const redirector = ctx.response.redirect();
             if (options?.status) {
                 redirector.status(options.status);
@@ -31,8 +70,11 @@ export class BriskRoute extends Macroable {
             return redirector.toRoute(identifier, params || ctx.params, options);
         });
     }
+    /**
+     * Redirect request to a fixed URL
+     */
     redirectToPath(url, options) {
-        return this.setHandler(async (ctx) => {
+        return this.setHandler(async function redirectsToPath(ctx) {
             const redirector = ctx.response.redirect();
             if (options?.status) {
                 redirector.status(options.status);

package/build/src/router/executor.d.ts

@@ -1,4 +1,9 @@
 import type { ContainerResolver } from '@adonisjs/fold';
 import type { StoreRouteNode } from '../types/route.js';
 import type { HttpContext } from '../http_context/main.js';
-export declare function execute(route: StoreRouteNode, resolver: ContainerResolver<any>, ctx: HttpContext): Promise<void>;
+import type { ServerErrorHandler } from '../types/server.js';
+/**
+ * Executor to execute the route middleware pipeline the route
+ * handler
+ */
+export declare function execute(route: StoreRouteNode, resolver: ContainerResolver<any>, ctx: HttpContext, errorResponder: ServerErrorHandler['handle']): Promise<void>;

package/build/src/router/executor.js

@@ -1,7 +1,20 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { useReturnValue } from './factories/use_return_value.js';
-export function execute(route, resolver, ctx) {
+/**
+ * Executor to execute the route middleware pipeline the route
+ * handler
+ */
+export function execute(route, resolver, ctx, errorResponder) {
     return route.middleware
         .runner()
+        .errorHandler((error) => errorResponder(error, ctx))
         .finalHandler(async () => {
         if (typeof route.handler === 'function') {
             return Promise.resolve(route.handler(ctx)).then(useReturnValue(ctx));

package/build/src/router/factories/use_return_value.d.ts

@@ -1,2 +1,6 @@
 import type { HttpContext } from '../../http_context/main.js';
+/**
+ * A factory function that uses the return value of the request
+ * pipeline as the response
+ */
 export declare function useReturnValue(ctx: HttpContext): (value: any) => void;

package/build/src/router/factories/use_return_value.js

@@ -1,8 +1,21 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * A factory function that uses the return value of the request
+ * pipeline as the response
+ */
 export function useReturnValue(ctx) {
     return function (value) {
-        if (value !== undefined &&
-            !ctx.response.hasLazyBody &&
-            value !== ctx.response) {
+        if (value !== undefined && // Return value is explicitly defined
+            !ctx.response.hasLazyBody && // Lazy body is not set
+            value !== ctx.response // Return value is not the instance of response object
+        ) {
             ctx.response.send(value);
         }
     };

package/build/src/router/group.d.ts

@@ -5,14 +5,61 @@ import { Route } from './route.js';
 import { BriskRoute } from './brisk.js';
 import { RouteResource } from './resource.js';
 import { OneOrMore } from '../types/base.js';
+/**
+ * Group class exposes the API to take action on a group of routes.
+ * The group routes must be pre-defined using the constructor.
+ */
 export declare class RouteGroup extends Macroable {
     #private;
     routes: (Route | RouteGroup | RouteResource | BriskRoute)[];
     constructor(routes: (Route | RouteGroup | RouteResource | BriskRoute)[]);
+    /**
+     * Define route param matcher
+     *
+     * ```ts
+     * Route.group(() => {
+     * }).where('id', /^[0-9]+/)
+     * ```
+     */
     where(param: string, matcher: RouteMatcher | string | RegExp): this;
+    /**
+     * Define prefix all the routes in the group.
+     *
+     * ```ts
+     * Route.group(() => {
+     * }).prefix('v1')
+     * ```
+     */
     prefix(prefix: string): this;
+    /**
+     * Define domain for all the routes.
+     *
+     * ```ts
+     * Route.group(() => {
+     * }).domain(':name.adonisjs.com')
+     * ```
+     */
     domain(domain: string): this;
+    /**
+     * Prepend name to the routes name.
+     *
+     * ```ts
+     * Route.group(() => {
+     * }).as('version1')
+     * ```
+     */
     as(name: string): this;
+    /**
+     * Prepend an array of middleware to all routes middleware.
+     *
+     * ```ts
+     * Route.group(() => {
+     * }).use(middleware.auth())
+     * ```
+     */
     use(middleware: OneOrMore<MiddlewareFn | ParsedNamedMiddleware>): this;
+    /**
+     * @alias use
+     */
     middleware(middleware: OneOrMore<MiddlewareFn | ParsedNamedMiddleware>): this;
 }

package/build/src/router/group.js

@@ -1,13 +1,33 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import Macroable from '@poppinss/macroable';
 import { BriskRoute } from './brisk.js';
 import { RouteResource } from './resource.js';
+/**
+ * Group class exposes the API to take action on a group of routes.
+ * The group routes must be pre-defined using the constructor.
+ */
 export class RouteGroup extends Macroable {
     routes;
+    /**
+     * Array of middleware registered on the group.
+     */
     #middleware = [];
     constructor(routes) {
         super();
         this.routes = routes;
     }
+    /**
+     * Shares midldeware stack with the routes. The method is invoked recursively
+     * to only register middleware with the route class and not with the
+     * resource or the child group
+     */
     #shareMiddlewareStackWithRoutes(route) {
         if (route instanceof RouteGroup) {
             route.routes.forEach((child) => this.#shareMiddlewareStackWithRoutes(child));
@@ -23,6 +43,11 @@ export class RouteGroup extends Macroable {
         }
         route.getMiddleware().unshift(this.#middleware);
     }
+    /**
+     * Updates the route name. The method is invoked recursively to only update
+     * the name with the route class and not with the resource or the child
+     * group.
+     */
     #updateRouteName(route, name) {
         if (route instanceof RouteGroup) {
             route.routes.forEach((child) => this.#updateRouteName(child, name));
@@ -38,6 +63,11 @@ export class RouteGroup extends Macroable {
         }
         route.as(name, true);
     }
+    /**
+     * Sets prefix on the route. The method is invoked recursively to only set
+     * the prefix with the route class and not with the resource or the
+     * child group.
+     */
     #setRoutePrefix(route, prefix) {
         if (route instanceof RouteGroup) {
             route.routes.forEach((child) => this.#setRoutePrefix(child, prefix));
@@ -53,6 +83,11 @@ export class RouteGroup extends Macroable {
         }
         route.prefix(prefix);
     }
+    /**
+     * Updates domain on the route. The method is invoked recursively to only update
+     * the domain with the route class and not with the resource or the child
+     * group.
+     */
     #updateRouteDomain(route, domain) {
         if (route instanceof RouteGroup) {
             route.routes.forEach((child) => this.#updateRouteDomain(child, domain));
@@ -68,6 +103,11 @@ export class RouteGroup extends Macroable {
         }
         route.domain(domain, false);
     }
+    /**
+     * Updates matchers on the route. The method is invoked recursively to only update
+     * the matchers with the route class and not with the resource or the child
+     * group.
+     */
     #updateRouteMatchers(route, param, matcher) {
         if (route instanceof RouteGroup) {
             route.routes.forEach((child) => this.#updateRouteMatchers(child, param, matcher));
@@ -83,23 +123,68 @@ export class RouteGroup extends Macroable {
         }
         route.where(param, matcher);
     }
+    /**
+     * Define route param matcher
+     *
+     * ```ts
+     * Route.group(() => {
+     * }).where('id', /^[0-9]+/)
+     * ```
+     */
     where(param, matcher) {
         this.routes.forEach((route) => this.#updateRouteMatchers(route, param, matcher));
         return this;
     }
+    /**
+     * Define prefix all the routes in the group.
+     *
+     * ```ts
+     * Route.group(() => {
+     * }).prefix('v1')
+     * ```
+     */
     prefix(prefix) {
         this.routes.forEach((route) => this.#setRoutePrefix(route, prefix));
         return this;
     }
+    /**
+     * Define domain for all the routes.
+     *
+     * ```ts
+     * Route.group(() => {
+     * }).domain(':name.adonisjs.com')
+     * ```
+     */
     domain(domain) {
         this.routes.forEach((route) => this.#updateRouteDomain(route, domain));
         return this;
     }
+    /**
+     * Prepend name to the routes name.
+     *
+     * ```ts
+     * Route.group(() => {
+     * }).as('version1')
+     * ```
+     */
     as(name) {
         this.routes.forEach((route) => this.#updateRouteName(route, name));
         return this;
     }
+    /**
+     * Prepend an array of middleware to all routes middleware.
+     *
+     * ```ts
+     * Route.group(() => {
+     * }).use(middleware.auth())
+     * ```
+     */
     use(middleware) {
+        /**
+         * Register middleware with children. We share the group middleware
+         * array by reference, therefore have to register it only for the
+         * first time.
+         */
         if (!this.#middleware.length) {
             this.routes.forEach((route) => this.#shareMiddlewareStackWithRoutes(route));
         }
@@ -113,6 +198,9 @@ export class RouteGroup extends Macroable {
         }
         return this;
     }
+    /**
+     * @alias use
+     */
     middleware(middleware) {
         return this.use(middleware);
     }

package/build/src/router/lookup_store/main.d.ts

@@ -2,14 +2,46 @@ import type { Encryption } from '@adonisjs/encryption';
 import type { Qs } from '../../qs.js';
 import { UrlBuilder } from './url_builder.js';
 import type { RouteJSON } from '../../types/route.js';
+/**
+ * Lookup store exposes the API to lookup routes and
+ * make URLs for registered routes.
+ */
 export declare class LookupStore {
     #private;
     constructor(encryption: Encryption, qsParser: Qs);
+    /**
+     * Register route JSON payload
+     */
     register(route: RouteJSON): void;
+    /**
+     * Returns an instance of the URL builder for making
+     * route URIs
+     */
     builder(): UrlBuilder;
+    /**
+     * Returns an instance of the URL builder for a specific
+     * domain.
+     */
     builderForDomain(domain: string): UrlBuilder;
+    /**
+     * Finds a route by its identifier. The identifier can be the
+     * route name, controller.method name or the route pattern
+     * itself.
+     */
     find(routeIdentifier: string, domain?: string): RouteJSON | null;
+    /**
+     * Finds a route by its identifier. The identifier can be the
+     * route name, controller.method name or the route pattern
+     * itself.
+     *
+     * An error is raised when unable to find the route.
+     */
     findOrFail(routeIdentifier: string, domain?: string): RouteJSON;
+    /**
+     * Check if a route exists. The identifier can be the
+     * route name, controller.method name or the route pattern
+     * itself.
+     */
     has(routeIdentifier: string, domain?: string): boolean;
     toJSON(): {
         [domain: string]: RouteJSON[];

package/build/src/router/lookup_store/main.js

@@ -1,32 +1,81 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { UrlBuilder } from './url_builder.js';
 import { RouteFinder } from './route_finder.js';
+/**
+ * Lookup store exposes the API to lookup routes and
+ * make URLs for registered routes.
+ */
 export class LookupStore {
+    /**
+     * List of routes grouped by domain
+     */
     #routes = {};
+    /**
+     * Encryption for making URLs
+     */
     #encryption;
+    /**
+     * Query string parser for making URLs
+     */
     #qsParser;
     constructor(encryption, qsParser) {
         this.#encryption = encryption;
         this.#qsParser = qsParser;
     }
+    /**
+     * Register route JSON payload
+     */
     register(route) {
         this.#routes[route.domain] = this.#routes[route.domain] || [];
         this.#routes[route.domain].push(route);
     }
+    /**
+     * Returns an instance of the URL builder for making
+     * route URIs
+     */
     builder() {
         return this.builderForDomain('root');
     }
+    /**
+     * Returns an instance of the URL builder for a specific
+     * domain.
+     */
     builderForDomain(domain) {
         const routes = this.#routes[domain];
         return new UrlBuilder(this.#encryption, new RouteFinder(routes || []), this.#qsParser);
     }
+    /**
+     * Finds a route by its identifier. The identifier can be the
+     * route name, controller.method name or the route pattern
+     * itself.
+     */
     find(routeIdentifier, domain) {
         const routes = this.#routes[domain || 'root'] || [];
         return new RouteFinder(routes).find(routeIdentifier);
     }
+    /**
+     * Finds a route by its identifier. The identifier can be the
+     * route name, controller.method name or the route pattern
+     * itself.
+     *
+     * An error is raised when unable to find the route.
+     */
     findOrFail(routeIdentifier, domain) {
         const routes = this.#routes[domain || 'root'] || [];
         return new RouteFinder(routes).findOrFail(routeIdentifier);
     }
+    /**
+     * Check if a route exists. The identifier can be the
+     * route name, controller.method name or the route pattern
+     * itself.
+     */
     has(routeIdentifier, domain) {
         const routes = this.#routes[domain || 'root'] || [];
         return new RouteFinder(routes).has(routeIdentifier);

package/build/src/router/lookup_store/route_finder.d.ts

@@ -1,8 +1,21 @@
 import type { RouteJSON } from '../../types/route.js';
+/**
+ * Route finder is used to find a route by its name, route pattern
+ * or the controller.method name.
+ */
 export declare class RouteFinder {
     #private;
     constructor(routes: RouteJSON[]);
+    /**
+     * Find a route by indentifier
+     */
     find(routeIdentifier: string): RouteJSON | null;
+    /**
+     * Find a route by indentifier or fail
+     */
     findOrFail(routeIdentifier: string): RouteJSON;
+    /**
+     * Find if a route exists
+     */
     has(routeIdentifier: string): boolean;
 }

package/build/src/router/lookup_store/route_finder.js

@@ -1,9 +1,24 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import * as errors from '../../exceptions.js';
+/**
+ * Route finder is used to find a route by its name, route pattern
+ * or the controller.method name.
+ */
 export class RouteFinder {
     #routes;
     constructor(routes) {
         this.#routes = routes;
     }
+    /**
+     * Find a route by indentifier
+     */
     find(routeIdentifier) {
         return (this.#routes.find(({ name, pattern, handler }) => {
             if (name === routeIdentifier || pattern === routeIdentifier) {
@@ -15,6 +30,9 @@ export class RouteFinder {
             return handler.reference === routeIdentifier;
         }) || null);
     }
+    /**
+     * Find a route by indentifier or fail
+     */
     findOrFail(routeIdentifier) {
         const route = this.find(routeIdentifier);
         if (!route) {
@@ -22,6 +40,9 @@ export class RouteFinder {
         }
         return route;
     }
+    /**
+     * Find if a route exists
+     */
     has(routeIdentifier) {
         return !!this.find(routeIdentifier);
     }

package/build/src/router/lookup_store/url_builder.d.ts

@@ -1,14 +1,50 @@
 import type { Encryption } from '@adonisjs/encryption';
 import type { Qs } from '../../qs.js';
 import type { RouteFinder } from './route_finder.js';
+/**
+ * URL builder class is used to create URIs for pre-registered
+ * routes.
+ *
+ * ```ts
+ * const builder = new UrlBuilder(encryption, routeFinder)
+ *
+ * builder
+ *  .qs({ sort: 'id' })
+ *  .params([category.id])
+ *  .make('categories.posts.index')
+ * ```
+ */
 export declare class UrlBuilder {
     #private;
     constructor(encryption: Encryption, routeFinder: RouteFinder, qsParser: Qs);
+    /**
+     * Prefix a custom base URL to the final URI
+     */
     prefixUrl(url: string): this;
+    /**
+     * Disable route lookup. Calling this method considers
+     * the "identifier" as the route pattern
+     */
     disableRouteLookup(): this;
+    /**
+     * Append query string to the final URI
+     */
     qs(queryString?: Record<string, any>): this;
+    /**
+     * Specify params to apply to the route pattern
+     */
     params(params?: any[] | Record<string, any>): this;
+    /**
+     * Generate URL for the given route identifier. The identifier can be the
+     * route name, controller.method name or the route pattern
+     * itself.
+     */
     make(identifier: string): string;
+    /**
+     * Generate a signed URL for the given route identifier. The identifier can be the
+     * route name, controller.method name or the route pattern
+     * itself.
+     */
     makeSigned(identifier: string, options?: {
         expiresIn?: string | number;
         purpose?: string;