@adonisjs/core 6.1.5-2 → 6.1.5-21

package/build/src/cli_formatters/routes_list.d.ts

@@ -1,5 +1,8 @@
-import { type Router } from '../../modules/http.js';
 import type { UIPrimitives } from '../../types/ace.js';
+import { type Router } from '../../modules/http/main.js';
+/**
+ * Shape of the serialized route specific to the formatter
+ */
 type SerializedRoute = {
     name: string;
     pattern: string;
@@ -14,6 +17,12 @@ type SerializedRoute = {
         method: string;
     };
 };
+/**
+ * Routes list formatter is used to format the routes to JSON or an ANSI string
+ * with pretty output.
+ *
+ * The decisions of colors, padding, alignment are all handled by the lists formatter
+ */
 export declare class RoutesListFormatter {
     #private;
     constructor(router: Router, ui: UIPrimitives, options: {
@@ -24,14 +33,28 @@ export declare class RoutesListFormatter {
         middleware?: string[];
         ignoreMiddleware?: string[];
     });
+    /**
+     * Formats routes as an array of objects. Routes are grouped by
+     * domain.
+     */
     formatAsJSON(): Promise<{
         domain: string;
         routes: SerializedRoute[];
     }[]>;
+    /**
+     * Format routes to ansi list of tables. Each domain has its own table
+     * with heading and rows. Each row has colums with colors and spacing
+     * around them.
+     */
     formatAsAnsiList(): Promise<{
         heading: string;
         rows: string[];
     }[]>;
+    /**
+     * Format routes to ansi tables. Each domain has its own table
+     * with heading and rows. Each row has colums with colors and spacing
+     * around them.
+     */
     formatAsAnsiTable(): Promise<{
         heading: string;
         table: ReturnType<UIPrimitives['table']>;

package/build/src/cli_formatters/routes_list.js

@@ -1,11 +1,31 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import stringWidth from 'string-width';
 import { cliHelpers } from '../../modules/ace/main.js';
 import { parseBindingReference } from '../../src/helpers/main.js';
+/**
+ * Routes list formatter is used to format the routes to JSON or an ANSI string
+ * with pretty output.
+ *
+ * The decisions of colors, padding, alignment are all handled by the lists formatter
+ */
 export class RoutesListFormatter {
     #router;
     #colors;
     #table;
+    /**
+     * Options for printing routes
+     */
     #options;
+    /**
+     * Filters to apply when finding routes
+     */
     #filters;
     constructor(router, ui, options, filters) {
         this.#router = router;
@@ -15,8 +35,15 @@ export class RoutesListFormatter {
         this.#options = options;
         this.#router.commit();
     }
+    /**
+     * Test if a route clears the applied filters
+     */
     #isAllowedByFilters(route) {
         let allowRoute = true;
+        /**
+         * Check if the route is allowed by applying the middleware
+         * filter
+         */
         if (this.#filters.middleware) {
             allowRoute = this.#filters.middleware.every((name) => {
                 if (name === '*') {
@@ -25,6 +52,10 @@ export class RoutesListFormatter {
                 return route.middleware.includes(name);
             });
         }
+        /**
+         * Check if the route has any or the ignored middleware. If yes, do not
+         * display the route
+         */
         if (allowRoute && this.#filters.ignoreMiddleware) {
             allowRoute = this.#filters.ignoreMiddleware.every((name) => {
                 if (name === '*') {
@@ -33,22 +64,40 @@ export class RoutesListFormatter {
                 return !route.middleware.includes(name);
             });
         }
+        /**
+         * No more filters to be applied
+         */
         if (!this.#filters.match) {
             return allowRoute;
         }
+        /**
+         * Check if the route name has the match keyword
+         */
         if (route.name.includes(this.#filters.match)) {
             return true;
         }
+        /**
+         * Check if the route pattern has the match keyword
+         */
         if (route.pattern.includes(this.#filters.match)) {
             return true;
         }
+        /**
+         * Check if the route handler has the match keyword
+         */
         if (route.handler.type === 'controller'
             ? route.handler.moduleNameOrPath.includes(this.#filters.match)
             : route.handler.name.includes(this.#filters.match)) {
             return true;
         }
+        /**
+         * Disallow route
+         */
         return false;
     }
+    /**
+     * Serialize route middleware to an array of names
+     */
     #serializeMiddleware(middleware) {
         return [...middleware.all()].reduce((result, one) => {
             if (typeof one === 'function') {
@@ -61,18 +110,30 @@ export class RoutesListFormatter {
             return result;
         }, []);
     }
+    /**
+     * Serialize route handler reference to display object
+     */
     async #serializeHandler(handler) {
+        /**
+         * Value is a controller reference
+         */
         if ('reference' in handler) {
             return {
                 type: 'controller',
                 ...(await parseBindingReference(handler.reference)),
             };
         }
+        /**
+         * Value is an inline closure
+         */
         return {
             type: 'closure',
             name: handler.name || 'closure',
         };
     }
+    /**
+     * Serializes routes JSON to an object that can be used for pretty printing
+     */
     async #serializeRoute(route) {
         let methods = route.methods;
         if (!this.#options.displayHeadRoutes) {
@@ -86,9 +147,15 @@ export class RoutesListFormatter {
             middleware: this.#serializeMiddleware(route.middleware),
         };
     }
+    /**
+     * Formats the route method for the ansi list and table
+     */
     #formatRouteMethod(method) {
         return this.#colors.dim(method);
     }
+    /**
+     * Formats route pattern for the ansi list and table
+     */
     #formatRoutePattern(route) {
         const pattern = this.#router
             .parsePattern(route.pattern)
@@ -107,14 +174,23 @@ export class RoutesListFormatter {
             .join('/');
         return `${pattern === '/' ? pattern : `/${pattern}`}${route.name ? ` ${this.#colors.dim(`(${route.name})`)}` : ''} `;
     }
+    /**
+     * Formats controller name for the ansi list and table
+     */
     #formatControllerName(route) {
         return route.handler.type === 'controller' ? ` ${route.handler.moduleNameOrPath}.` : '';
     }
+    /**
+     * Formats action name for the ansi list and table
+     */
     #formatAction(route) {
         return route.handler.type === 'controller'
             ? `${this.#colors.cyan(route.handler.method)}`
             : ` ${this.#colors.cyan(route.handler.name)}`;
     }
+    /**
+     * Formats route middleware for the ansi list and table
+     */
     #formatMiddleware(route, mode = 'normal') {
         if (mode === 'compact' && route.middleware.length > 3) {
             const firstMiddleware = route.middleware[0];
@@ -124,6 +200,10 @@ export class RoutesListFormatter {
         }
         return this.#colors.dim(`${route.middleware.filter((one) => one).join(', ')}`);
     }
+    /**
+     * Formatting the domain headling to be in green color with
+     * dots around it
+     */
     #formatDomainHeadline(domain) {
         if (domain !== 'root') {
             return cliHelpers.justify([`${this.#colors.dim('..')} ${this.#colors.green(domain)} `], {
@@ -133,19 +213,31 @@ export class RoutesListFormatter {
         }
         return '';
     }
+    /**
+     * Justify the ansi list
+     */
     #justifyListTables(tables) {
         return tables.map((table) => {
+            /**
+             * Formatting methods
+             */
             const methods = table.rows.map((columns) => columns[0]);
             const largestMethodsLength = Math.max(...methods.map((method) => stringWidth(method)));
             const formattedMethods = cliHelpers.justify(methods, {
                 maxWidth: largestMethodsLength,
             });
+            /**
+             * Formatting patterns
+             */
             const patterns = table.rows.map((columns) => columns[1]);
             const largestPatternLength = Math.max(...patterns.map((pattern) => stringWidth(pattern)));
             const formattedPatterns = cliHelpers.justify(patterns, {
                 maxWidth: largestPatternLength,
                 paddingChar: this.#colors.dim('.'),
             });
+            /**
+             * Formatting middleware to be right aligned
+             */
             const middleware = table.rows.map((columns) => columns[3]);
             const largestMiddlewareLength = Math.max(...middleware.map((one) => stringWidth(one)));
             const formattedMiddleware = cliHelpers.justify(middleware, {
@@ -153,6 +245,10 @@ export class RoutesListFormatter {
                 align: 'right',
                 paddingChar: ' ',
             });
+            /**
+             * Formatting controllers to be right aligned and take all the remaining
+             * space after printing route method, pattern and middleware.
+             */
             const controllers = table.rows.map((columns) => columns[2]);
             const largestControllerLength = (this.#options.maxPrettyPrintWidth || cliHelpers.TERMINAL_SIZE) -
                 (largestPatternLength + largestMethodsLength + largestMiddlewareLength);
@@ -172,6 +268,10 @@ export class RoutesListFormatter {
             };
         });
     }
+    /**
+     * Formats routes as an array of objects. Routes are grouped by
+     * domain.
+     */
     async formatAsJSON() {
         const routes = this.#router.toJSON();
         const domains = Object.keys(routes);
@@ -185,6 +285,11 @@ export class RoutesListFormatter {
         }
         return routesJSON;
     }
+    /**
+     * Format routes to ansi list of tables. Each domain has its own table
+     * with heading and rows. Each row has colums with colors and spacing
+     * around them.
+     */
     async formatAsAnsiList() {
         const routes = this.#router.toJSON();
         const domains = Object.keys(routes);
@@ -201,6 +306,10 @@ export class RoutesListFormatter {
                     ],
                 ],
             };
+            /**
+             * Computing table rows. Each route+method will have its
+             * own row
+             */
             for (let route of routes[domain]) {
                 const serializedRoute = await this.#serializeRoute(route);
                 if (this.#isAllowedByFilters(serializedRoute)) {
@@ -218,6 +327,11 @@ export class RoutesListFormatter {
         }
         return this.#justifyListTables(tables);
     }
+    /**
+     * Format routes to ansi tables. Each domain has its own table
+     * with heading and rows. Each row has colums with colors and spacing
+     * around them.
+     */
     async formatAsAnsiTable() {
         const routes = this.#router.toJSON();
         const domains = Object.keys(routes);
@@ -235,6 +349,10 @@ export class RoutesListFormatter {
                     { content: this.#colors.dim('MIDDLEWARE'), hAlign: 'right' },
                 ]),
             };
+            /**
+             * Computing table rows. Each route+method will have its
+             * own row
+             */
             for (let route of routes[domain]) {
                 const serializedRoute = await this.#serializeRoute(route);
                 if (this.#isAllowedByFilters(serializedRoute)) {

package/build/src/debug.d.ts

@@ -1,3 +1,3 @@
-/// <reference types="node" resolution-mode="require"/>
+/// <reference types="@types/node" resolution-mode="require"/>
 declare const _default: import("util").DebugLogger;
 export default _default;

package/build/src/debug.js

@@ -1,2 +1,10 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { debuglog } from 'node:util';
 export default debuglog('adonisjs:core');

package/build/src/exceptions.d.ts

@@ -0,0 +1 @@
+export { Exception, createError, RuntimeException, InvalidArgumentsException, } from '@poppinss/utils';

package/build/src/exceptions.js

@@ -0,0 +1,9 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+export { Exception, createError, RuntimeException, InvalidArgumentsException, } from '@poppinss/utils';

package/build/src/helpers/is.js

@@ -1,2 +1,10 @@
+/*
+ * @adonisjs/core
+ *
+ * (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';
 export default is;

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

@@ -1,4 +1,4 @@
 export { default as parseImports } from 'parse-imports';
 export { createId as cuid } from '@paralleldrive/cuid2';
-export { safeEqual, compose, base64, fsImportAll, fsReadAll, slash } from '@poppinss/utils';
+export { slash, base64, compose, fsReadAll, safeEqual, fsImportAll, MessageBuilder, } from '@poppinss/utils';
 export { parseBindingReference } from './parse_binding_reference.js';

package/build/src/helpers/main.js

@@ -1,4 +1,12 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 export { default as parseImports } from 'parse-imports';
 export { createId as cuid } from '@paralleldrive/cuid2';
-export { safeEqual, compose, base64, fsImportAll, fsReadAll, slash } from '@poppinss/utils';
+export { slash, base64, compose, fsReadAll, safeEqual, fsImportAll, MessageBuilder, } from '@poppinss/utils';
 export { parseBindingReference } from './parse_binding_reference.js';

package/build/src/helpers/parse_binding_reference.d.ts

@@ -1,4 +1,44 @@
 import { LazyImport, Constructor } from '../../types/http.js';
+/**
+ * The "parseBindingReference" method can be used to parse a binding references
+ * similar to route controller binding value or event listener binding value.
+ *
+ * See the following examples to understand how this function works.
+ *
+ * ### Magic strings
+ * ```ts
+ * parseBindingReference('#controllers/home_controller')
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'handle' }
+
+ * parseBindingReference('#controllers/home_controller.index')
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'index' }
+
+ * parseBindingReference('#controllers/home.controller.index')
+ * // returns { moduleNameOrPath: '#controllers/home.controller', method: 'index' }
+ * ```
+ *
+ * ### Class reference
+ * ```ts
+ * class HomeController {}
+ *
+ * parseBindingReference([HomeController])
+ * // returns { moduleNameOrPath: 'HomeController', method: 'handle' }
+
+ * parseBindingReference([HomeController, 'index'])
+ * // returns { moduleNameOrPath: 'HomeController', method: 'index' }
+ * ```
+ *
+ * ### Lazy import reference
+ * ```ts
+ * const HomeController = () => import('#controllers/home_controller')
+ *
+ * parseBindingReference([HomeController])
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'handle' }
+
+ * parseBindingReference([HomeController, 'index'])
+ * // returns { moduleNameOrPath: 'controllers/home_controller', method: 'index' }
+ * ```
+ */
 export declare function parseBindingReference(binding: string | [LazyImport<Constructor<any>> | Constructor<any>, any?]): Promise<{
     moduleNameOrPath: string;
     method: string;

package/build/src/helpers/parse_binding_reference.js

@@ -1,5 +1,58 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import parseImports from 'parse-imports';
+/**
+ * The "parseBindingReference" method can be used to parse a binding references
+ * similar to route controller binding value or event listener binding value.
+ *
+ * See the following examples to understand how this function works.
+ *
+ * ### Magic strings
+ * ```ts
+ * parseBindingReference('#controllers/home_controller')
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'handle' }
+
+ * parseBindingReference('#controllers/home_controller.index')
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'index' }
+
+ * parseBindingReference('#controllers/home.controller.index')
+ * // returns { moduleNameOrPath: '#controllers/home.controller', method: 'index' }
+ * ```
+ *
+ * ### Class reference
+ * ```ts
+ * class HomeController {}
+ *
+ * parseBindingReference([HomeController])
+ * // returns { moduleNameOrPath: 'HomeController', method: 'handle' }
+
+ * parseBindingReference([HomeController, 'index'])
+ * // returns { moduleNameOrPath: 'HomeController', method: 'index' }
+ * ```
+ *
+ * ### Lazy import reference
+ * ```ts
+ * const HomeController = () => import('#controllers/home_controller')
+ *
+ * parseBindingReference([HomeController])
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'handle' }
+
+ * parseBindingReference([HomeController, 'index'])
+ * // returns { moduleNameOrPath: 'controllers/home_controller', method: 'index' }
+ * ```
+ */
 export async function parseBindingReference(binding) {
+    /**
+     * The binding reference is a magic string. It might not have method
+     * name attached to it. Therefore we split the string and attempt
+     * to find the method or use the default method name "handle".
+     */
     if (typeof binding === 'string') {
         const tokens = binding.split('.');
         if (tokens.length === 1) {
@@ -8,6 +61,10 @@ export async function parseBindingReference(binding) {
         return { method: tokens.pop(), moduleNameOrPath: tokens.join('.') };
     }
     const [bindingReference, method] = binding;
+    /**
+     * Parsing the binding reference for dynamic imports and using its
+     * import value.
+     */
     const imports = [...(await parseImports(bindingReference.toString()))];
     const importedModule = imports.find(($import) => $import.isDynamicImport && $import.moduleSpecifier.value);
     if (importedModule) {
@@ -16,6 +73,9 @@ export async function parseBindingReference(binding) {
             method: method || 'handle',
         };
     }
+    /**
+     * Otherwise using the name of the binding reference.
+     */
     return {
         moduleNameOrPath: bindingReference.name,
         method: method || 'handle',

package/build/src/helpers/string.d.ts

@@ -1,17 +1,43 @@
 import { EncodeOptions } from 'he';
 import string from '@poppinss/utils/string';
+import StringBuilder from '@poppinss/utils/string_builder';
+/**
+ * Collection of string helpers to transform a string value.
+ */
 declare const stringHelpers: typeof string & {
+    /**
+     * Creates an instance of the string builder
+     */
+    create(value: string | StringBuilder): StringBuilder;
     ordinalize: (typeof string)['ordinal'];
+    /**
+     * Convert a string to a sentence
+     */
     toSentence: (typeof string)['sentence'];
+    /**
+     * Generate a random string value of a given length
+     */
     generateRandom: (typeof string)['random'];
+    /**
+     * Pretty print hrtime diff
+     */
     prettyHrTime(time: [number, number], options?: {
         verbose?: boolean | undefined;
         precise?: boolean | undefined;
     }): string;
+    /**
+     * Check if a string is empty.
+     */
     isEmpty(value: string): boolean;
+    /**
+     * Escape HTML entities
+     */
     escapeHTML(value: string, options?: {
         encodeSymbols?: boolean;
     }): string;
+    /**
+     * Encode symbols to html entities
+     */
     encodeSymbols(value: string, options?: EncodeOptions): string;
 };
 export default stringHelpers;

package/build/src/helpers/string.js

@@ -1,11 +1,26 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import he from 'he';
 import prettyHrTime from 'pretty-hrtime';
 import string from '@poppinss/utils/string';
+import StringBuilder from '@poppinss/utils/string_builder';
+/**
+ * Collection of string helpers to transform a string value.
+ */
 const stringHelpers = {
     ...string,
     toSentence: string.sentence,
     ordinalize: string.ordinal,
     generateRandom: string.random,
+    create(value) {
+        return new StringBuilder(value);
+    },
     prettyHrTime(time, options) {
         return prettyHrTime(time, options);
     },