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

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

@@ -1,35 +1,92 @@
-import matchit from '@poppinss/matchit';
+/*
+ * @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 { RuntimeException } from '@poppinss/utils';
+import { parseRoutePattern } from '../parser.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 class UrlBuilder {
+    /**
+     * Query string parser
+     */
     #qsParser;
+    /**
+     * The parameters to apply on the route
+     */
     #params = {};
+    /**
+     * Query string to append to the route
+     */
     #qs = {};
+    /**
+     * Should we perform the route lookup or just build the
+     * given pattern as it is.
+     */
     #shouldPerformLookup = true;
+    /**
+     * BaseURL to append to the constructored URL
+     */
     #baseUrl;
+    /**
+     * Encryption class for making signed URLs
+     */
     #encryption;
+    /**
+     * Route finder for finding route pattern
+     */
     #routeFinder;
     constructor(encryption, routeFinder, qsParser) {
         this.#qsParser = qsParser;
         this.#encryption = encryption;
         this.#routeFinder = routeFinder;
     }
+    /**
+     * Raises exception when wildcard values array is missing or
+     * has length of zero.
+     */
     #ensureHasWildCardValues(pattern, values) {
         if (!values || !Array.isArray(values) || !values.length) {
             throw new RuntimeException(`Cannot make URL for "${pattern}" route. Invalid value provided for wildcard param`);
         }
     }
+    /*
+     * Raises exception when value is not defined
+     */
     #ensureHasParamValue(pattern, param, value) {
         if (value === undefined || value === null) {
             throw new RuntimeException(`Cannot make URL for "${pattern}" route. Missing value for "${param}" param`);
         }
     }
+    /**
+     * Processes the pattern against the params
+     */
     #processPattern(pattern) {
         const uriSegments = [];
         const paramsArray = Array.isArray(this.#params) ? this.#params : null;
         const paramsObject = !Array.isArray(this.#params) ? this.#params : {};
         let paramsIndex = 0;
-        const tokens = matchit.parse(pattern);
+        const tokens = parseRoutePattern(pattern);
         for (const token of tokens) {
+            /**
+             * Expected wildcard param to be at the end always and hence
+             * we must break out from the loop
+             */
             if (token.type === 0) {
                 uriSegments.push(`${token.val}${token.end}`);
             }
@@ -42,6 +99,9 @@ export class UrlBuilder {
             else {
                 const paramName = token.val;
                 const value = paramsArray ? paramsArray[paramsIndex] : paramsObject[paramName];
+                /**
+                 * Type = 1 means param is required
+                 */
                 if (token.type === 1) {
                     this.#ensureHasParamValue(pattern, paramName, value);
                 }
@@ -53,6 +113,9 @@ export class UrlBuilder {
         }
         return `/${uriSegments.join('/')}`;
     }
+    /**
+     * Suffix the query string to the URL
+     */
     #suffixQueryString(url, qs) {
         if (qs) {
             const queryString = this.#qsParser.stringify(qs);
@@ -60,17 +123,30 @@ export class UrlBuilder {
         }
         return url;
     }
+    /**
+     * Prefixes base URL to the uri string
+     */
     #prefixBaseUrl(uri) {
         return this.#baseUrl ? `${this.#baseUrl}${uri}` : uri;
     }
+    /**
+     * Prefix a custom base URL to the final URI
+     */
     prefixUrl(url) {
         this.#baseUrl = url;
         return this;
     }
+    /**
+     * Disable route lookup. Calling this method considers
+     * the "identifier" as the route pattern
+     */
     disableRouteLookup() {
         this.#shouldPerformLookup = false;
         return this;
     }
+    /**
+     * Append query string to the final URI
+     */
     qs(queryString) {
         if (!queryString) {
             return this;
@@ -78,6 +154,9 @@ export class UrlBuilder {
         this.#qs = queryString;
         return this;
     }
+    /**
+     * Specify params to apply to the route pattern
+     */
     params(params) {
         if (!params) {
             return this;
@@ -85,6 +164,11 @@ export class UrlBuilder {
         this.#params = params;
         return 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) {
         let url;
         if (this.#shouldPerformLookup) {
@@ -96,6 +180,11 @@ export class UrlBuilder {
         }
         return this.#suffixQueryString(this.#prefixBaseUrl(url), this.#qs);
     }
+    /**
+     * 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, options) {
         let url;
         if (this.#shouldPerformLookup) {
@@ -105,6 +194,14 @@ export class UrlBuilder {
         else {
             url = this.#processPattern(identifier);
         }
+        /*
+         * Making the signature from the qualified url. We do not prefix the domain when
+         * making signature, since it just makes the signature big.
+         *
+         * There might be a case, when someone wants to generate signature for the same route
+         * on their 2 different domains, but we ignore that case for now and can consider
+         * it later (when someone asks for it)
+         */
         const signature = this.#encryption.verifier.sign(this.#suffixQueryString(url, this.#qs), options?.expiresIn, options?.purpose);
         const qs = Object.assign({}, this.#qs, { signature });
         return this.#suffixQueryString(this.#prefixBaseUrl(url), qs);

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

@@ -5,36 +5,124 @@ import { Route } from './route.js';
 import { RouteGroup } from './group.js';
 import { BriskRoute } from './brisk.js';
 import { RouteResource } from './resource.js';
-import type { Constructor, LazyImport } from '../types/base.js';
 import { LookupStore } from './lookup_store/main.js';
 import { RouteMatchers as Matchers } from './matchers.js';
+import type { Constructor, LazyImport } from '../types/base.js';
 import type { MiddlewareAsClass, ParsedGlobalMiddleware } from '../types/middleware.js';
-import type { RouteFn, MatchedRoute, RouteMatcher, MakeUrlOptions, MakeSignedUrlOptions, GetControllerHandlers } from '../types/route.js';
+import type { RouteFn, MatchedRoute, RouteMatcher, RouteMatchers, MakeUrlOptions, MakeSignedUrlOptions, GetControllerHandlers } from '../types/route.js';
+/**
+ * Router class exposes a unified API to register new routes, group them or
+ * create route resources.
+ *
+ * ```ts
+ * const router = new Router()
+ *
+ * router.get('/', async function () {
+ *   // handle request
+ * })
+ * ```
+ */
 export declare class Router extends LookupStore {
     #private;
+    /**
+     * Collection of routes, including route resource and route
+     * group. To get a flat list of routes, call `router.toJSON()`
+     */
     routes: (Route | RouteResource | RouteGroup | BriskRoute)[];
+    /**
+     * A flag to know if routes for explicit domains have been registered.
+     * The boolean is computed after calling the "commit" method.
+     */
     usingDomains: boolean;
+    /**
+     * Shortcut methods for commonly used route matchers
+     */
     matchers: Matchers;
     constructor(app: Application<any>, encryption: Encryption, qsParser: Qs);
+    /**
+     * Parses the route pattern
+     */
+    parsePattern(pattern: string, matchers?: RouteMatchers): import("../types/route.js").MatchItRouteToken[];
+    /**
+     * Define an array of middleware to use on all the routes.
+     * Calling this method multiple times pushes to the
+     * existing list of middleware
+     */
     use(middleware: LazyImport<MiddlewareAsClass>[]): this;
+    /**
+     * Define a collection of named middleware. The defined collection is
+     * not registered anywhere, but instead converted in a new collection
+     * of functions you can apply on the routes, or router groups.
+     */
     named<NamedMiddleware extends Record<string, LazyImport<MiddlewareAsClass>>>(collection: NamedMiddleware): { [K in keyof NamedMiddleware]: <Args extends import("../types/middleware.js").GetMiddlewareArgs<import("../types/base.js").UnWrapLazyImport<NamedMiddleware[K]>>>(...args: Args) => {
         name: K;
         args: Args[0];
     } & ParsedGlobalMiddleware; };
+    /**
+     * Add route for a given pattern and methods
+     */
     route<T extends Constructor<any>>(pattern: string, methods: string[], handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]): Route<T>;
+    /**
+     * Define a route that handles all common HTTP methods
+     */
     any<T extends Constructor<any>>(pattern: string, handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]): Route<T>;
+    /**
+     * Define `GET` route
+     */
     get<T extends Constructor<any>>(pattern: string, handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]): Route<T>;
+    /**
+     * Define `POST` route
+     */
     post<T extends Constructor<any>>(pattern: string, handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]): Route<T>;
+    /**
+     * Define `PUT` route
+     */
     put<T extends Constructor<any>>(pattern: string, handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]): Route<T>;
+    /**
+     * Define `PATCH` route
+     */
     patch<T extends Constructor<any>>(pattern: string, handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]): Route<T>;
+    /**
+     * Define `DELETE` route
+     */
     delete<T extends Constructor<any>>(pattern: string, handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]): Route<T>;
+    /**
+     * Creates a group of routes. A route group can apply transforms
+     * to routes in bulk
+     */
     group(callback: () => void): RouteGroup;
-    resource(resource: string, controller: string): RouteResource;
-    shallowResource(resource: string, controller: string): RouteResource;
+    /**
+     * Registers a route resource with conventional set of routes
+     */
+    resource(resource: string, controller: string | LazyImport<Constructor<any>> | Constructor<any>): RouteResource;
+    /**
+     * Register a route resource with shallow nested routes.
+     */
+    shallowResource(resource: string, controller: string | LazyImport<Constructor<any>> | Constructor<any>): RouteResource;
+    /**
+     * Returns a brisk route instance for a given URL pattern
+     */
     on(pattern: string): BriskRoute;
+    /**
+     * Define matcher for a given param. The global params are applied
+     * on all the routes (unless overridden at the route level).
+     */
     where(param: string, matcher: RouteMatcher | string | RegExp): this;
+    /**
+     * Commit routes to the store. The router is freezed after the
+     * commit method is called.
+     */
     commit(): void;
+    /**
+     * Find route for a given URL, method and optionally domain
+     */
     match(url: string, method: string, hostname?: string | null): null | MatchedRoute;
+    /**
+     * Make URL to a pre-registered route
+     */
     makeUrl(routeIdentifier: string, params?: any[] | Record<string, any>, options?: MakeUrlOptions): string;
+    /**
+     * Makes a signed URL to a pre-registered route.
+     */
     makeSignedUrl(routeIdentifier: string, params?: any[] | Record<string, any>, options?: MakeSignedUrlOptions): string;
 }

package/build/src/router/main.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 { moduleImporter } from '@adonisjs/fold';
 import { RuntimeException } from '@poppinss/utils';
@@ -10,19 +18,63 @@ import { RouteResource } from './resource.js';
 import { LookupStore } from './lookup_store/main.js';
 import { RouteMatchers as Matchers } from './matchers.js';
 import { defineNamedMiddleware } from '../define_middleware.js';
+import { parseRoutePattern } from './parser.js';
+/**
+ * Router class exposes a unified API to register new routes, group them or
+ * create route resources.
+ *
+ * ```ts
+ * const router = new Router()
+ *
+ * router.get('/', async function () {
+ *   // handle request
+ * })
+ * ```
+ */
 export class Router extends LookupStore {
+    /**
+     * Application is needed to resolve string based controller expressions
+     */
     #app;
+    /**
+     * Store with tokenized routes
+     */
     #store = new RoutesStore();
+    /**
+     * Global matchers to test route params against regular expressions.
+     */
     #globalMatchers = {};
+    /**
+     * Middleware store to be shared with the routes
+     */
     #middleware = [];
+    /**
+     * A boolean to tell the router that a group is in
+     * open state right now
+     */
     #openedGroups = [];
+    /**
+     * Collection of routes, including route resource and route
+     * group. To get a flat list of routes, call `router.toJSON()`
+     */
     routes = [];
+    /**
+     * A flag to know if routes for explicit domains have been registered.
+     * The boolean is computed after calling the "commit" method.
+     */
     usingDomains = false;
+    /**
+     * Shortcut methods for commonly used route matchers
+     */
     matchers = new Matchers();
     constructor(app, encryption, qsParser) {
         super(encryption, qsParser);
         this.#app = app;
     }
+    /**
+     * Push a give router entity to the list of routes or the
+     * recently opened group.
+     */
     #pushToRoutes(entity) {
         const openedGroup = this.#openedGroups[this.#openedGroups.length - 1];
         if (openedGroup) {
@@ -31,13 +83,32 @@ export class Router extends LookupStore {
         }
         this.routes.push(entity);
     }
+    /**
+     * Parses the route pattern
+     */
+    parsePattern(pattern, matchers) {
+        return parseRoutePattern(pattern, matchers);
+    }
+    /**
+     * Define an array of middleware to use on all the routes.
+     * Calling this method multiple times pushes to the
+     * existing list of middleware
+     */
     use(middleware) {
         middleware.forEach((one) => this.#middleware.push(moduleImporter(one, 'handle').toHandleMethod()));
         return this;
     }
+    /**
+     * Define a collection of named middleware. The defined collection is
+     * not registered anywhere, but instead converted in a new collection
+     * of functions you can apply on the routes, or router groups.
+     */
     named(collection) {
         return defineNamedMiddleware(collection);
     }
+    /**
+     * Add route for a given pattern and methods
+     */
     route(pattern, methods, handler) {
         const route = new Route(this.#app, this.#middleware, {
             pattern,
@@ -48,32 +119,74 @@ export class Router extends LookupStore {
         this.#pushToRoutes(route);
         return route;
     }
+    /**
+     * Define a route that handles all common HTTP methods
+     */
     any(pattern, handler) {
         return this.route(pattern, ['HEAD', 'OPTIONS', 'GET', 'POST', 'PUT', 'PATCH', 'DELETE'], handler);
     }
+    /**
+     * Define `GET` route
+     */
     get(pattern, handler) {
         return this.route(pattern, ['GET', 'HEAD'], handler);
     }
+    /**
+     * Define `POST` route
+     */
     post(pattern, handler) {
         return this.route(pattern, ['POST'], handler);
     }
+    /**
+     * Define `PUT` route
+     */
     put(pattern, handler) {
         return this.route(pattern, ['PUT'], handler);
     }
+    /**
+     * Define `PATCH` route
+     */
     patch(pattern, handler) {
         return this.route(pattern, ['PATCH'], handler);
     }
+    /**
+     * Define `DELETE` route
+     */
     delete(pattern, handler) {
         return this.route(pattern, ['DELETE'], handler);
     }
+    /**
+     * Creates a group of routes. A route group can apply transforms
+     * to routes in bulk
+     */
     group(callback) {
+        /*
+         * Create a new group with empty set of routes
+         */
         const group = new RouteGroup([]);
+        /**
+         * Track group
+         */
         this.#pushToRoutes(group);
+        /*
+         * Track the group, so that the upcoming calls inside the callback
+         * can use this group
+         */
         this.#openedGroups.push(group);
+        /*
+         * Execute the callback. Now all registered routes will be
+         * collected seperately from the `routes` array
+         */
         callback();
+        /*
+         * Now the callback is over, get rid of the opened group
+         */
         this.#openedGroups.pop();
         return group;
     }
+    /**
+     * Registers a route resource with conventional set of routes
+     */
     resource(resource, controller) {
         const resourceInstance = new RouteResource(this.#app, this.#middleware, {
             resource,
@@ -84,6 +197,9 @@ export class Router extends LookupStore {
         this.#pushToRoutes(resourceInstance);
         return resourceInstance;
     }
+    /**
+     * Register a route resource with shallow nested routes.
+     */
     shallowResource(resource, controller) {
         const resourceInstance = new RouteResource(this.#app, this.#middleware, {
             resource,
@@ -94,6 +210,9 @@ export class Router extends LookupStore {
         this.#pushToRoutes(resourceInstance);
         return resourceInstance;
     }
+    /**
+     * Returns a brisk route instance for a given URL pattern
+     */
     on(pattern) {
         const briskRoute = new BriskRoute(this.#app, this.#middleware, {
             pattern,
@@ -102,6 +221,10 @@ export class Router extends LookupStore {
         this.#pushToRoutes(briskRoute);
         return briskRoute;
     }
+    /**
+     * Define matcher for a given param. The global params are applied
+     * on all the routes (unless overridden at the route level).
+     */
     where(param, matcher) {
         if (typeof matcher === 'string') {
             this.#globalMatchers[param] = { match: new RegExp(matcher) };
@@ -114,6 +237,10 @@ export class Router extends LookupStore {
         }
         return this;
     }
+    /**
+     * Commit routes to the store. The router is freezed after the
+     * commit method is called.
+     */
     commit() {
         const routeNamesByDomain = new Map();
         toRoutesJSON(this.routes).forEach((route) => {
@@ -121,12 +248,22 @@ export class Router extends LookupStore {
                 routeNamesByDomain.set(route.domain, new Set());
             }
             const routeNames = routeNamesByDomain.get(route.domain);
+            /*
+             * Raise error when route name is already in use. Route names have to be unique
+             * to ensure that only one route is returned during lookup.
+             */
             if (route.name && routeNames.has(route.name)) {
                 throw new RuntimeException(`Route with duplicate name found. A route with name "${route.name}" already exists`);
             }
+            /*
+             * If route has a unique, then track the name for checking duplicates
+             */
             if (route.name) {
                 routeNames.add(route.name);
             }
+            /**
+             * Register the route with the lookup store
+             */
             this.register(route);
             this.#store.add(route);
         });
@@ -136,6 +273,9 @@ export class Router extends LookupStore {
         this.#globalMatchers = {};
         this.#middleware = [];
     }
+    /**
+     * Find route for a given URL, method and optionally domain
+     */
     match(url, method, hostname) {
         const matchingDomain = this.#store.matchDomain(hostname);
         return matchingDomain.length
@@ -145,6 +285,9 @@ export class Router extends LookupStore {
             })
             : this.#store.match(url, method);
     }
+    /**
+     * Make URL to a pre-registered route
+     */
     makeUrl(routeIdentifier, params, options) {
         const normalizedOptions = Object.assign({}, options);
         const builder = normalizedOptions.domain
@@ -156,6 +299,9 @@ export class Router extends LookupStore {
         normalizedOptions.disableRouteLookup && builder.disableRouteLookup();
         return builder.make(routeIdentifier);
     }
+    /**
+     * Makes a signed URL to a pre-registered route.
+     */
     makeSignedUrl(routeIdentifier, params, options) {
         const normalizedOptions = Object.assign({}, options);
         const builder = normalizedOptions.domain

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

@@ -1,13 +1,26 @@
 import Macroable from '@poppinss/macroable';
+/**
+ * Shortcut methods for commonly used route matchers
+ */
 export declare class RouteMatchers extends Macroable {
+    /**
+     * Enforce value to be a number and also casts it to number data
+     * type
+     */
     number(): {
         match: RegExp;
         cast: (value: string) => number;
     };
+    /**
+     * Enforce value to be formatted as uuid
+     */
     uuid(): {
         match: RegExp;
         cast: (value: string) => string;
     };
+    /**
+     * Enforce value to be formatted as slug
+     */
     slug(): {
         match: RegExp;
     };

package/build/src/router/matchers.js

@@ -1,14 +1,35 @@
+/*
+ * @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';
+/**
+ * Shortcut methods for commonly used route matchers
+ */
 export class RouteMatchers extends Macroable {
+    /**
+     * Enforce value to be a number and also casts it to number data
+     * type
+     */
     number() {
         return { match: /^[0-9]+$/, cast: (value) => Number(value) };
     }
+    /**
+     * Enforce value to be formatted as uuid
+     */
     uuid() {
         return {
             match: /^[0-9a-zA-F]{8}-[0-9a-zA-F]{4}-[0-9a-zA-F]{4}-[0-9a-zA-F]{4}-[0-9a-zA-F]{12}$/,
             cast: (value) => value.toLowerCase(),
         };
     }
+    /**
+     * Enforce value to be formatted as slug
+     */
     slug() {
         return { match: /^[^\s-_](?!.*?[-_]{2,})([a-z0-9-\\]{1,})[^\s]*[^-_\s]$/ };
     }

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

@@ -0,0 +1,5 @@
+import { MatchItRouteToken, RouteMatchers } from '../types/route.js';
+/**
+ * Parses the route pattern
+ */
+export declare function parseRoutePattern(pattern: string, matchers?: RouteMatchers): MatchItRouteToken[];

package/build/src/router/parser.js

@@ -0,0 +1,17 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+// @ts-expect-error
+import matchit from '@poppinss/matchit';
+/**
+ * Parses the route pattern
+ */
+export function parseRoutePattern(pattern, matchers) {
+    const tokens = matchit.parse(pattern, matchers);
+    return tokens;
+}