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

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

@@ -1,25 +1,54 @@
 import Macroable from '@poppinss/macroable';
 import type { Application } from '@adonisjs/application';
 import { Route } from './route.js';
+import type { Constructor, LazyImport } from '../types/base.js';
 import type { ParsedGlobalMiddleware } from '../types/middleware.js';
 import type { ResourceActionNames, RouteMatcher, RouteMatchers } from '../types/route.js';
+/**
+ * Route resource exposes the API to register multiple routes for a resource.
+ */
 export declare class RouteResource extends Macroable {
     #private;
+    /**
+     * A collection of routes instances that belongs to this resource
+     */
     routes: Route[];
     constructor(app: Application<any>, routerMiddleware: ParsedGlobalMiddleware[], options: {
         resource: string;
-        controller: string;
+        controller: string | LazyImport<Constructor<any>> | Constructor<any>;
         globalMatchers: RouteMatchers;
         shallow: boolean;
     });
+    /**
+     * Register only given routes and remove others
+     */
     only(names: ResourceActionNames[]): this;
+    /**
+     * Register all routes, except the one's defined
+     */
     except(names: ResourceActionNames[]): this;
+    /**
+     * Register api only routes. The `create` and `edit` routes, which
+     * are meant to show forms will not be registered
+     */
     apiOnly(): this;
+    /**
+     * Define matcher for params inside the resource
+     */
     where(key: string, matcher: RouteMatcher | string | RegExp): this;
+    /**
+     * Tap into multiple routes to configure them by their name
+     */
     tap(callback: (route: Route) => void): this;
     tap(actions: ResourceActionNames | ResourceActionNames[], callback: (route: Route) => void): this;
+    /**
+     * Set the param name for a given resource
+     */
     params(resources: {
         [resource: string]: string;
     }): this;
+    /**
+     * Prepend name to all the routes
+     */
     as(name: string, normalizeName?: boolean): this;
 }

package/build/src/router/resource.js

@@ -1,16 +1,59 @@
+/*
+ * @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 string from '@poppinss/utils/string';
 import Macroable from '@poppinss/macroable';
 import { RuntimeException } from '@poppinss/utils';
 import { Route } from './route.js';
+/**
+ * Route resource exposes the API to register multiple routes for a resource.
+ */
 export class RouteResource extends Macroable {
+    /**
+     * Resource identifier. Nested resources are separated
+     * with a dot notation
+     */
     #resource;
+    /**
+     * The controller to handle resource routing requests
+     */
     #controller;
+    /**
+     * Is it a shallow resource? Shallow resources URLs do not have parent
+     * resource name and id once they can be identified with the id.
+     */
     #shallow = false;
+    /**
+     * Matchers inherited from the router
+     */
     #globalMatchers;
+    /**
+     * Reference to the AdonisJS application
+     */
     #app;
+    /**
+     * Middleware registered on the router
+     */
     #routerMiddleware;
+    /**
+     * Parameter names for the resources. Defaults to `id` for
+     * a singular resource and `resource_id` for nested
+     * resources.
+     */
     #params = {};
+    /**
+     * Base name for the routes. We suffix action names
+     * on top of the base name
+     */
     #routesBaseName;
+    /**
+     * A collection of routes instances that belongs to this resource
+     */
     routes = [];
     constructor(app, routerMiddleware, options) {
         super();
@@ -24,33 +67,60 @@ export class RouteResource extends Macroable {
         this.#routesBaseName = this.#getRoutesBaseName();
         this.#buildRoutes();
     }
+    /**
+     * Normalizes the resource name to dropping leading and trailing
+     * slashes.
+     */
     #normalizeResourceName(resource) {
         return resource.replace(/^\//, '').replace(/\/$/, '');
     }
+    /**
+     * Ensure resource name is not an empty string
+     */
     #validateResourceName(resource) {
         if (!resource || resource === '/') {
             throw new RuntimeException(`Invalid resource name "${resource}"`);
         }
     }
+    /**
+     * Converting segments of a resource to snake case to
+     * make the route name.
+     */
     #getRoutesBaseName() {
         return this.#resource
             .split('.')
             .map((token) => string.snakeCase(token))
             .join('.');
     }
+    /**
+     * Create a new route for the given pattern, methods and controller action
+     */
     #createRoute(pattern, methods, action) {
         const route = new Route(this.#app, this.#routerMiddleware, {
             pattern,
             methods,
-            handler: `${this.#controller}.${action}`,
+            handler: typeof this.#controller === 'string'
+                ? `${this.#controller}.${action}`
+                : [this.#controller, action],
             globalMatchers: this.#globalMatchers,
         });
         route.as(`${this.#routesBaseName}.${action}`);
         this.routes.push(route);
     }
+    /**
+     * Returns the `resource_id` name for a given resource. The
+     * resource name is converted to singular form and
+     * transformed to snake case.
+     *
+     * photos becomes photo_id
+     * users becomes user_id
+     */
     #getResourceId(resource) {
         return `${string.snakeCase(string.singular(resource))}_id`;
     }
+    /**
+     * Build routes for the given resource
+     */
     #buildRoutes() {
         const resources = this.#resource.split('.');
         const mainResource = resources.pop();
@@ -70,6 +140,9 @@ export class RouteResource extends Macroable {
         this.#createRoute(`${this.#shallow ? mainResource : baseURI}/:id`, ['PUT', 'PATCH'], 'update');
         this.#createRoute(`${this.#shallow ? mainResource : baseURI}/:id`, ['DELETE'], 'destroy');
     }
+    /**
+     * Filter the routes based on their partial names
+     */
     #filter(names, inverse) {
         const actions = Array.isArray(names) ? names : [names];
         return this.routes.filter((route) => {
@@ -77,17 +150,30 @@ export class RouteResource extends Macroable {
             return inverse ? !match : match;
         });
     }
+    /**
+     * Register only given routes and remove others
+     */
     only(names) {
         this.#filter(names, true).forEach((route) => route.markAsDeleted());
         return this;
     }
+    /**
+     * Register all routes, except the one's defined
+     */
     except(names) {
         this.#filter(names, false).forEach((route) => route.markAsDeleted());
         return this;
     }
+    /**
+     * Register api only routes. The `create` and `edit` routes, which
+     * are meant to show forms will not be registered
+     */
     apiOnly() {
         return this.except(['create', 'edit']);
     }
+    /**
+     * Define matcher for params inside the resource
+     */
     where(key, matcher) {
         this.routes.forEach((route) => {
             route.where(key, matcher);
@@ -102,6 +188,9 @@ export class RouteResource extends Macroable {
         this.#filter(actions, false).forEach((route) => callback(route));
         return this;
     }
+    /**
+     * Set the param name for a given resource
+     */
     params(resources) {
         Object.keys(resources).forEach((resource) => {
             const param = resources[resource];
@@ -113,6 +202,9 @@ export class RouteResource extends Macroable {
         });
         return this;
     }
+    /**
+     * Prepend name to all the routes
+     */
     as(name, normalizeName = true) {
         name = normalizeName ? string.snakeCase(name) : name;
         this.routes.forEach((route) => {

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

@@ -3,6 +3,10 @@ import type { Application } from '@adonisjs/application';
 import type { Constructor, LazyImport, OneOrMore } from '../types/base.js';
 import type { MiddlewareFn, ParsedNamedMiddleware, ParsedGlobalMiddleware } from '../types/middleware.js';
 import type { GetControllerHandlers, RouteFn, RouteJSON, RouteMatcher, RouteMatchers, StoreRouteMiddleware } from '../types/route.js';
+/**
+ * The route class exposes the APIs for constructing a route using the
+ * fluent API.
+ */
 export declare class Route<Controller extends Constructor<any> = any> extends Macroable {
     #private;
     constructor(app: Application<any>, routerMiddleware: ParsedGlobalMiddleware[], options: {
@@ -11,17 +15,78 @@ export declare class Route<Controller extends Constructor<any> = any> extends Ma
         handler: RouteFn | string | [LazyImport<Controller> | Controller, GetControllerHandlers<Controller>?];
         globalMatchers: RouteMatchers;
     });
+    /**
+     * Define matcher for a given param. If a matcher exists, then we do not
+     * override that, since the routes inside a group will set matchers
+     * before the group, so they should have priority over the group
+     * matchers.
+     *
+     * ```ts
+     * Route.group(() => {
+     *   Route.get('/:id', 'handler').where('id', /^[0-9]$/)
+     * }).where('id', /[^a-z$]/)
+     * ```
+     *
+     * The `/^[0-9]$/` will win over the matcher defined by the group
+     */
     where(param: string, matcher: RouteMatcher | string | RegExp): this;
+    /**
+     * Define prefix for the route. Calling this method multiple times
+     * applies multiple prefixes in the reverse order.
+     */
     prefix(prefix: string): this;
+    /**
+     * Define a custom domain for the route. We do not overwrite the domain
+     * unless `overwrite` flag is set to true.
+     */
     domain(domain: string, overwrite?: boolean): this;
+    /**
+     * Define one or more middleware to be executed before the route
+     * handler.
+     *
+     * Named middleware can be referenced using the name registered with
+     * the router middleware store.
+     */
     use(middleware: OneOrMore<MiddlewareFn | ParsedNamedMiddleware>): this;
+    /**
+     * @alias use
+     */
     middleware(middleware: OneOrMore<MiddlewareFn | ParsedNamedMiddleware>): this;
+    /**
+     * Give a unique name to the route. Assinging a new unique removes the
+     * existing name of the route.
+     *
+     * Setting prepends to true prefixes the name to the existing name.
+     */
     as(name: string, prepend?: boolean): this;
+    /**
+     * Check if the route was marked to be deleted
+     */
     isDeleted(): boolean;
+    /**
+     * Mark route as deleted. Deleted routes are not registered
+     * with the route store
+     */
     markAsDeleted(): void;
+    /**
+     * Get the route name
+     */
     getName(): string | undefined;
+    /**
+     * Get the route pattern
+     */
     getPattern(): string;
+    /**
+     * Set the route pattern
+     */
     setPattern(pattern: string): this;
+    /**
+     * Returns the stack of middleware registered on the route.
+     * The value is shared by reference.
+     */
     getMiddleware(): StoreRouteMiddleware[][];
+    /**
+     * Returns JSON representation of the route
+     */
     toJSON(): RouteJSON;
 }

package/build/src/router/route.js

@@ -1,3 +1,11 @@
+/*
+ * @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 is from '@sindresorhus/is';
 import Macroable from '@poppinss/macroable';
 import Middleware from '@poppinss/middleware';
@@ -5,18 +13,66 @@ import { RuntimeException } from '@poppinss/utils';
 import { moduleCaller, moduleExpression, moduleImporter } from '@adonisjs/fold';
 import { execute } from './executor.js';
 import { dropSlash } from '../helpers.js';
+import debug from '../debug.js';
+/**
+ * The route class exposes the APIs for constructing a route using the
+ * fluent API.
+ */
 export class Route extends Macroable {
+    /**
+     * Route pattern
+     */
     #pattern;
+    /**
+     * HTTP Methods for the route
+     */
     #methods;
+    /**
+     * A unique name for the route
+     */
     #name;
+    /**
+     * A boolean to prevent route from getting registered within
+     * the store.
+     *
+     * This flag must be set before "Router.commit" method
+     */
     #isDeleted = false;
+    /**
+     * Route handler
+     */
     #handler;
+    /**
+     * Matchers inherited from the router
+     */
     #globalMatchers;
+    /**
+     * Reference to the AdonisJS application
+     */
     #app;
+    /**
+     * Middleware registered on the router
+     */
     #routerMiddleware;
+    /**
+     * By default the route is part of the `root` domain. Root domain is used
+     * when no domain is defined
+     */
     #routeDomain = 'root';
+    /**
+     * An object of matchers to be forwarded to the store. The matchers
+     * list is populated by calling `where` method
+     */
     #matchers = {};
+    /**
+     * Custom prefixes defined on the route or the route parent
+     * groups
+     */
     #prefixes = [];
+    /**
+     * Middleware defined directly on the route or the route parent
+     * routes. We mantain an array for each layer of the stack
+     */
     #middleware = [];
     constructor(app, routerMiddleware, options) {
         super();
@@ -27,6 +83,10 @@ export class Route extends Macroable {
         this.#handler = this.#resolveRouteHandle(options.handler);
         this.#globalMatchers = options.globalMatchers;
     }
+    /**
+     * Resolves the route handler string expression to a
+     * handler method object
+     */
     #resolveRouteHandle(handler) {
         if (typeof handler === 'string') {
             return {
@@ -34,13 +94,23 @@ export class Route extends Macroable {
                 ...moduleExpression(handler, this.#app.appRoot).toHandleMethod(),
             };
         }
+        /**
+         * Using a lazily imported controller
+         */
         if (Array.isArray(handler)) {
+            /**
+             * The first item of the tuple is a class constructor
+             */
             if (is.class_(handler[0])) {
                 return {
                     reference: handler,
                     ...moduleCaller(handler[0], (handler[1] || 'handle')).toHandleMethod(),
                 };
             }
+            /**
+             * The first item of the tuple is a function that lazily
+             * loads the controller
+             */
             return {
                 reference: handler,
                 ...moduleImporter(handler[0], (handler[1] || 'handle')).toHandleMethod(),
@@ -48,9 +118,17 @@ export class Route extends Macroable {
         }
         return handler;
     }
+    /**
+     * Returns an object of param matchers by merging global and local
+     * matchers. The local copy is given preference over the global
+     * one's
+     */
     #getMatchers() {
         return { ...this.#globalMatchers, ...this.#matchers };
     }
+    /**
+     * Returns a normalized pattern string by prefixing the `prefix` (if defined).
+     */
     #computePattern() {
         const pattern = dropSlash(this.#pattern);
         const prefix = this.#prefixes
@@ -60,6 +138,20 @@ export class Route extends Macroable {
             .join('');
         return prefix ? `${prefix}${pattern === '/' ? '' : pattern}` : pattern;
     }
+    /**
+     * Define matcher for a given param. If a matcher exists, then we do not
+     * override that, since the routes inside a group will set matchers
+     * before the group, so they should have priority over the group
+     * matchers.
+     *
+     * ```ts
+     * Route.group(() => {
+     *   Route.get('/:id', 'handler').where('id', /^[0-9]$/)
+     * }).where('id', /[^a-z$]/)
+     * ```
+     *
+     * The `/^[0-9]$/` will win over the matcher defined by the group
+     */
     where(param, matcher) {
         if (this.#matchers[param]) {
             return this;
@@ -75,23 +167,47 @@ export class Route extends Macroable {
         }
         return this;
     }
+    /**
+     * Define prefix for the route. Calling this method multiple times
+     * applies multiple prefixes in the reverse order.
+     */
     prefix(prefix) {
         this.#prefixes.push(prefix);
         return this;
     }
+    /**
+     * Define a custom domain for the route. We do not overwrite the domain
+     * unless `overwrite` flag is set to true.
+     */
     domain(domain, overwrite = false) {
         if (this.#routeDomain === 'root' || overwrite) {
             this.#routeDomain = domain;
         }
         return this;
     }
+    /**
+     * Define one or more middleware to be executed before the route
+     * handler.
+     *
+     * Named middleware can be referenced using the name registered with
+     * the router middleware store.
+     */
     use(middleware) {
         this.#middleware.push(Array.isArray(middleware) ? middleware : [middleware]);
         return this;
     }
+    /**
+     * @alias use
+     */
     middleware(middleware) {
         return this.use(middleware);
     }
+    /**
+     * Give a unique name to the route. Assinging a new unique removes the
+     * existing name of the route.
+     *
+     * Setting prepends to true prefixes the name to the existing name.
+     */
     as(name, prepend = false) {
         if (prepend) {
             if (!this.#name) {
@@ -103,31 +219,64 @@ export class Route extends Macroable {
         this.#name = name;
         return this;
     }
+    /**
+     * Check if the route was marked to be deleted
+     */
     isDeleted() {
         return this.#isDeleted;
     }
+    /**
+     * Mark route as deleted. Deleted routes are not registered
+     * with the route store
+     */
     markAsDeleted() {
         this.#isDeleted = true;
     }
+    /**
+     * Get the route name
+     */
     getName() {
         return this.#name;
     }
+    /**
+     * Get the route pattern
+     */
     getPattern() {
         return this.#pattern;
     }
+    /**
+     * Set the route pattern
+     */
     setPattern(pattern) {
         this.#pattern = pattern;
         return this;
     }
+    /**
+     * Returns the stack of middleware registered on the route.
+     * The value is shared by reference.
+     */
     getMiddleware() {
         return this.#middleware;
     }
+    /**
+     * Returns the middleware instance for persistence inside the
+     * store
+     */
     #getMiddlewareForStore() {
         const middleware = new Middleware();
-        this.#routerMiddleware.forEach((one) => middleware.add(one));
-        this.#middleware.flat().forEach((one) => middleware.add(one));
+        this.#routerMiddleware.forEach((one) => {
+            debug('adding global middleware to route %s, %O', this.#pattern, one);
+            middleware.add(one);
+        });
+        this.#middleware.flat().forEach((one) => {
+            debug('adding named middleware to route %s, %O', this.#pattern, one);
+            middleware.add(one);
+        });
         return middleware;
     }
+    /**
+     * Returns JSON representation of the route
+     */
     toJSON() {
         return {
             domain: this.#routeDomain,

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

@@ -1,12 +1,66 @@
 import type { RouteJSON, MatchedRoute, StoreRoutesTree, MatchItRouteToken } from '../types/route.js';
+/**
+ * Store class is used to store a list of routes, along side with their tokens
+ * to match the URLs.
+ *
+ * ```ts
+ * const store = new Store()
+ *
+ * store.add({
+ *  pattern: 'posts/:id',
+ *  handler: function onRoute () {},
+ *  middleware: [],
+ *  matchers: {
+ *    id: '^[0-9]$+'
+ *  },
+ *  meta: {},
+ *  methods: ['GET']
+ * })
+ *
+ * store.match('posts/1', 'GET')
+ * ```
+ */
 export declare class RoutesStore {
     #private;
+    /**
+     * A flag to know if routes for explicit domains
+     * have been registered
+     */
     usingDomains: boolean;
+    /**
+     * Tree of registered routes and their matchit tokens
+     */
     tree: StoreRoutesTree;
+    /**
+     * Add a route to the store
+     *
+     * ```ts
+     * store.add({
+     *   pattern: 'post/:id',
+     *   methods: ['GET'],
+     *   matchers: {},
+     *   meta: {},
+     *   handler: function handler () {
+     *   }
+     * })
+     * ```
+     */
     add(route: RouteJSON): this;
+    /**
+     * Matches the url, method and optionally domain to pull the matching
+     * route. `null` is returned when unable to match the URL against
+     * registered routes.
+     *
+     * The domain parameter has to be a registered pattern and not the fully
+     * qualified runtime domain. You must call `matchDomain` first to fetch
+     * the pattern for qualified domain
+     */
     match(url: string, method: string, domain?: {
         tokens: MatchItRouteToken[];
         hostname: string;
     }): null | MatchedRoute;
+    /**
+     * Match hostname against registered domains.
+     */
     matchDomain(hostname?: string | null): MatchItRouteToken[];
 }