@adonisjs/http-server 7.0.0-0 → 7.0.0-1

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

@@ -0,0 +1,52 @@
+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;
+    }): string;
+}

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

@@ -0,0 +1,209 @@
+/*
+ * @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 = 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}`);
+            }
+            else if (token.type === 2) {
+                const values = paramsArray ? paramsArray.slice(paramsIndex) : paramsObject['*'];
+                this.#ensureHasWildCardValues(pattern, values);
+                uriSegments.push(`${values.join('/')}${token.end}`);
+                break;
+            }
+            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);
+                }
+                paramsIndex++;
+                if (value !== undefined && value !== null) {
+                    uriSegments.push(`${value}${token.end}`);
+                }
+            }
+        }
+        return `/${uriSegments.join('/')}`;
+    }
+    /**
+     * Suffix the query string to the URL
+     */
+    #suffixQueryString(url, qs) {
+        if (qs) {
+            const queryString = this.#qsParser.stringify(qs);
+            url = queryString ? `${url}?${queryString}` : url;
+        }
+        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;
+        }
+        this.#qs = queryString;
+        return this;
+    }
+    /**
+     * Specify params to apply to the route pattern
+     */
+    params(params) {
+        if (!params) {
+            return this;
+        }
+        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) {
+            const route = this.#routeFinder.findOrFail(identifier);
+            url = this.#processPattern(route.pattern);
+        }
+        else {
+            url = this.#processPattern(identifier);
+        }
+        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) {
+            const route = this.#routeFinder.findOrFail(identifier);
+            url = this.#processPattern(route.pattern);
+        }
+        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

@@ -0,0 +1,128 @@
+import type { Encryption } from '@adonisjs/encryption';
+import type { Application } from '@adonisjs/application';
+import type { Qs } from '../qs.js';
+import { Route } from './route.js';
+import { RouteGroup } from './group.js';
+import { BriskRoute } from './brisk.js';
+import { RouteResource } from './resource.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, 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;
+    /**
+     * 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

@@ -0,0 +1,316 @@
+/*
+ * @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';
+import { Route } from './route.js';
+import { RouteGroup } from './group.js';
+import { BriskRoute } from './brisk.js';
+import { RoutesStore } from './store.js';
+import { toRoutesJSON } from '../helpers.js';
+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) {
+            openedGroup.routes.push(entity);
+            return;
+        }
+        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,
+            methods,
+            handler,
+            globalMatchers: this.#globalMatchers,
+        });
+        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,
+            controller,
+            shallow: false,
+            globalMatchers: this.#globalMatchers,
+        });
+        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,
+            controller,
+            shallow: true,
+            globalMatchers: this.#globalMatchers,
+        });
+        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,
+            globalMatchers: this.#globalMatchers,
+        });
+        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) };
+        }
+        else if (is.regExp(matcher)) {
+            this.#globalMatchers[param] = { match: matcher };
+        }
+        else {
+            this.#globalMatchers[param] = matcher;
+        }
+        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) => {
+            if (!routeNamesByDomain.has(route.domain)) {
+                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);
+        });
+        routeNamesByDomain.clear();
+        this.usingDomains = this.#store.usingDomains;
+        this.routes = [];
+        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
+            ? this.#store.match(url, method, {
+                tokens: matchingDomain,
+                hostname: hostname,
+            })
+            : 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
+            ? this.builderForDomain(normalizedOptions.domain)
+            : this.builder();
+        builder.params(params);
+        builder.qs(normalizedOptions.qs);
+        normalizedOptions.prefixUrl && builder.prefixUrl(normalizedOptions.prefixUrl);
+        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
+            ? this.builderForDomain(normalizedOptions.domain)
+            : this.builder();
+        builder.params(params);
+        builder.qs(normalizedOptions.qs);
+        normalizedOptions.prefixUrl && builder.prefixUrl(normalizedOptions.prefixUrl);
+        normalizedOptions.disableRouteLookup && builder.disableRouteLookup();
+        return builder.makeSigned(routeIdentifier, normalizedOptions);
+    }
+}