@adonisjs/core 6.19.0 → 7.0.0-next.1

package/build/src/assembler_hooks/index_entities.d.ts

@@ -0,0 +1,37 @@
+import { type IndexEntitiesConfig } from '../types.ts';
+/**
+ * Configures the IndexGenerator to create barrel files for "controllers", "events",
+ * and "listeners". This function is used as an assembler hook to automatically generate
+ * index files that export all modules from specified directories.
+ *
+ * @param {IndexEntitiesConfig} entities - Configuration object for entities indexing
+ *
+ * @example
+ * // Basic usage with default configuration
+ * indexEntities({})
+ *
+ * @example
+ * // Custom configuration for specific entities
+ * indexEntities({
+ *   events: {
+ *     enabled: true,
+ *     source: 'app/custom-events',
+ *     importAlias: '#custom-events'
+ *   },
+ *   controllers: {
+ *     enabled: false
+ *   }
+ * })
+ *
+ * @example
+ * // Using custom glob patterns
+ * indexEntities({
+ *   listeners: {
+ *     source: 'app/handlers',
+ *     glob: '**\/*_handler.ts'
+ *   }
+ * })
+ */
+export declare function indexEntities(entities?: IndexEntitiesConfig): {
+    run(_: import("@adonisjs/assembler").DevServer | import("@adonisjs/assembler").TestRunner | import("@adonisjs/assembler").Bundler, indexGenerator: import("@adonisjs/assembler/index_generator").IndexGenerator): void;
+};

package/build/src/assembler_hooks/index_entities.js

@@ -0,0 +1,106 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import stringHelpers from "../helpers/string.js";
+import { outputTransformerDataObjects } from "../utils.js";
+/**
+ * Configures the IndexGenerator to create barrel files for "controllers", "events",
+ * and "listeners". This function is used as an assembler hook to automatically generate
+ * index files that export all modules from specified directories.
+ *
+ * @param {IndexEntitiesConfig} entities - Configuration object for entities indexing
+ *
+ * @example
+ * // Basic usage with default configuration
+ * indexEntities({})
+ *
+ * @example
+ * // Custom configuration for specific entities
+ * indexEntities({
+ *   events: {
+ *     enabled: true,
+ *     source: 'app/custom-events',
+ *     importAlias: '#custom-events'
+ *   },
+ *   controllers: {
+ *     enabled: false
+ *   }
+ * })
+ *
+ * @example
+ * // Using custom glob patterns
+ * indexEntities({
+ *   listeners: {
+ *     source: 'app/handlers',
+ *     glob: '**\/*_handler.ts'
+ *   }
+ * })
+ */
+export function indexEntities(entities = {}) {
+    const events = Object.assign({ enabled: true, source: 'app/events', importAlias: '#events' }, entities.events);
+    const listeners = Object.assign({ enabled: true, source: 'app/listeners', importAlias: '#listeners' }, entities.listeners);
+    const controllers = Object.assign({ enabled: true, source: 'app/controllers', importAlias: '#controllers' }, entities.controllers);
+    const transformers = Object.assign({ enabled: false, source: 'app/transformers', importAlias: '#transformers' }, entities.transformers);
+    return {
+        run(_, indexGenerator) {
+            if (events.enabled) {
+                indexGenerator.add('events', {
+                    source: events.source,
+                    glob: events.glob,
+                    as: 'barrelFile',
+                    exportName: 'events',
+                    importAlias: events.importAlias,
+                    output: '.adonisjs/server/events.ts',
+                });
+            }
+            if (listeners.enabled) {
+                indexGenerator.add('listeners', {
+                    source: listeners.source,
+                    glob: listeners.glob,
+                    as: 'barrelFile',
+                    exportName: 'listeners',
+                    importAlias: listeners.importAlias,
+                    output: '.adonisjs/server/listeners.ts',
+                });
+            }
+            if (controllers.enabled) {
+                indexGenerator.add('controllers', {
+                    source: controllers.source,
+                    glob: controllers.glob,
+                    as: 'barrelFile',
+                    exportName: 'controllers',
+                    importAlias: controllers.importAlias,
+                    removeSuffix: 'controller',
+                    output: '.adonisjs/server/controllers.ts',
+                });
+            }
+            if (transformers.enabled) {
+                indexGenerator.add('transformers', {
+                    source: transformers.source,
+                    glob: transformers.glob,
+                    as(vfs, buffer, __, helpers) {
+                        const transformersList = vfs.asTree({
+                            transformKey(key) {
+                                const segments = key.split('/');
+                                const baseName = segments.pop();
+                                return [
+                                    ...segments.map((segment) => stringHelpers.pascalCase(segment)),
+                                    stringHelpers.create(baseName).removeSuffix('transformer').pascalCase(),
+                                ].join('/');
+                            },
+                            transformValue: helpers.toImportPath,
+                        });
+                        outputTransformerDataObjects(transformersList, buffer);
+                    },
+                    importAlias: transformers.importAlias,
+                    output: '.adonisjs/client/data.d.ts',
+                });
+            }
+        },
+    };
+}

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

@@ -1,5 +1,6 @@
-import type { UIPrimitives } from '../../types/ace.js';
-import { type Router } from '../../modules/http/main.js';
+import type { UIPrimitives } from '../../types/ace.ts';
+import { type Router } from '../../modules/http/main.ts';
+import type { MiddlewareHandlerInfo, RouteHandlerInfo } from '../../types/http.ts';
 /**
  * Shape of the serialized route specific to the formatter
  */
@@ -7,25 +8,36 @@ type SerializedRoute = {
     name: string;
     pattern: string;
     methods: string[];
-    middleware: string[];
-    handler: {
-        type: 'closure';
-        name: string;
-        args?: string;
-    } | {
-        type: 'controller';
-        moduleNameOrPath: string;
-        method: string;
-    };
+    middleware: MiddlewareHandlerInfo[];
+    handler: RouteHandlerInfo;
 };
 /**
  * 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
+ *
+ * @example
+ * const formatter = new RoutesListFormatter(router, ui, {
+ *   displayHeadRoutes: false,
+ *   maxPrettyPrintWidth: 120
+ * }, {
+ *   match: 'api',
+ *   middleware: ['auth']
+ * })
+ *
+ * const ansiOutput = await formatter.formatAsAnsiList()
  */
 export declare class RoutesListFormatter {
     #private;
+    /**
+     * Creates a new instance of the routes list formatter
+     *
+     * @param router - Router instance containing routes to format
+     * @param ui - UI primitives for colors and table formatting
+     * @param options - Display options for route formatting
+     * @param filters - Filters to apply when displaying routes
+     */
     constructor(router: Router, ui: UIPrimitives, options: {
         displayHeadRoutes?: boolean;
         maxPrettyPrintWidth?: number;

package/build/src/cli_formatters/routes_list.js

@@ -7,17 +7,37 @@
  * 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';
+import { cliHelpers } from "../../modules/ace/main.js";
+import { middlewareInfo, routeInfo } from '@adonisjs/http-server/helpers';
 /**
  * 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
+ *
+ * @example
+ * const formatter = new RoutesListFormatter(router, ui, {
+ *   displayHeadRoutes: false,
+ *   maxPrettyPrintWidth: 120
+ * }, {
+ *   match: 'api',
+ *   middleware: ['auth']
+ * })
+ *
+ * const ansiOutput = await formatter.formatAsAnsiList()
  */
 export class RoutesListFormatter {
+    /**
+     * Router instance containing all registered routes
+     */
     #router;
+    /**
+     * Colors utility for ANSI formatting
+     */
     #colors;
+    /**
+     * Table utility for creating formatted tables
+     */
     #table;
     /**
      * Options for printing routes
@@ -27,6 +47,14 @@ export class RoutesListFormatter {
      * Filters to apply when finding routes
      */
     #filters;
+    /**
+     * Creates a new instance of the routes list formatter
+     *
+     * @param router - Router instance containing routes to format
+     * @param ui - UI primitives for colors and table formatting
+     * @param options - Display options for route formatting
+     * @param filters - Filters to apply when displaying routes
+     */
     constructor(router, ui, options, filters) {
         this.#router = router;
         this.#colors = ui.colors;
@@ -49,7 +77,7 @@ export class RoutesListFormatter {
                 if (name === '*') {
                     return route.middleware.length > 0;
                 }
-                return route.middleware.includes(name);
+                return route.middleware.find((middleware) => middleware.name === name);
             });
         }
         /**
@@ -61,7 +89,7 @@ export class RoutesListFormatter {
                 if (name === '*') {
                     return route.middleware.length === 0;
                 }
-                return !route.middleware.includes(name);
+                return !route.middleware.find((middleware) => middleware.name === name);
             });
         }
         /**
@@ -95,43 +123,6 @@ export class RoutesListFormatter {
          */
         return false;
     }
-    /**
-     * Serialize route middleware to an array of names
-     */
-    #serializeMiddleware(middleware) {
-        return [...middleware.all()].reduce((result, one) => {
-            if (typeof one === 'function') {
-                result.push(one.name || 'closure');
-                return result;
-            }
-            if ('name' in one && one.name) {
-                result.push(one.name);
-            }
-            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',
-            args: 'listArgs' in handler ? String(handler.listArgs) : undefined,
-        };
-    }
     /**
      * Serializes routes JSON to an object that can be used for pretty printing
      */
@@ -140,12 +131,15 @@ export class RoutesListFormatter {
         if (!this.#options.displayHeadRoutes) {
             methods = methods.filter((method) => method !== 'HEAD');
         }
+        const middlewareList = await Promise.all([...route.middleware.all()].map((middleware) => {
+            return middlewareInfo(middleware);
+        }));
         return {
             name: route.name || '',
             pattern: route.pattern,
             methods: methods,
-            handler: await this.#serializeHandler(route.handler),
-            middleware: this.#serializeMiddleware(route.middleware),
+            handler: await routeInfo(route),
+            middleware: middlewareList.filter((info) => info.type !== 'global'),
         };
     }
     /**
@@ -201,12 +195,15 @@ export class RoutesListFormatter {
      */
     #formatMiddleware(route, mode = 'normal') {
         if (mode === 'compact' && route.middleware.length > 3) {
-            const firstMiddleware = route.middleware[0];
-            const secondMiddleware = route.middleware[1];
+            const firstMiddleware = route.middleware[0].name;
+            const secondMiddleware = route.middleware[1].name;
             const diff = route.middleware.length - 2;
             return this.#colors.dim(`${firstMiddleware}, ${secondMiddleware}, and ${diff} more`);
         }
-        return this.#colors.dim(`${route.middleware.filter((one) => one).join(', ')}`);
+        return this.#colors.dim(`${route.middleware
+            .map((one) => one.name)
+            .filter((one) => one)
+            .join(', ')}`);
     }
     /**
      * Formatting the domain headling to be in green color with

package/build/src/config_provider.d.ts

@@ -1,9 +1,54 @@
-import { ApplicationService, ConfigProvider } from './types.js';
+import { type ApplicationService, type ConfigProvider } from './types.ts';
 /**
- * Helper to create config provider and resolve config from
- * them
+ * Helper utilities to create and resolve config providers. Config providers
+ * are used to defer configuration resolution until the application is booted,
+ * allowing access to environment variables and other application services.
+ *
+ * @example
+ * // Creating a database config provider
+ * const databaseConfig = configProvider.create(async (app) => ({
+ *   connection: app.env.get('DB_CONNECTION', 'sqlite'),
+ *   host: app.env.get('DB_HOST', 'localhost'),
+ *   port: app.env.get('DB_PORT', 5432)
+ * }))
+ *
+ * @example
+ * // Resolving a config provider
+ * const config = await configProvider.resolve(app, databaseConfig)
+ * if (config) {
+ *   console.log(`Database connection: ${config.connection}`)
+ * }
  */
 export declare const configProvider: {
+    /**
+     * Creates a new config provider that will resolve configuration
+     * when the application is booted.
+     *
+     * @param resolver - Function that receives the application service and returns the configuration
+     *
+     * @example
+     * const mailConfig = configProvider.create(async (app) => ({
+     *   driver: app.env.get('MAIL_DRIVER', 'smtp'),
+     *   host: app.env.get('SMTP_HOST'),
+     *   port: app.env.get('SMTP_PORT', 587)
+     * }))
+     */
     create<T>(resolver: ConfigProvider<T>["resolver"]): ConfigProvider<T>;
+    /**
+     * Resolves a config provider if the provided value is a valid config provider,
+     * otherwise returns null.
+     *
+     * @param app - The application service instance
+     * @param provider - The potential config provider to resolve
+     *
+     * @example
+     * const resolved = await configProvider.resolve(app, someProvider)
+     * if (resolved) {
+     *   // Use the resolved configuration
+     *   console.log('Config resolved:', resolved)
+     * } else {
+     *   console.log('Not a valid config provider')
+     * }
+     */
     resolve<T>(app: ApplicationService, provider: unknown): Promise<T | null>;
 };

package/build/src/config_provider.js

@@ -7,16 +7,61 @@
  * file that was distributed with this source code.
  */
 /**
- * Helper to create config provider and resolve config from
- * them
+ * Helper utilities to create and resolve config providers. Config providers
+ * are used to defer configuration resolution until the application is booted,
+ * allowing access to environment variables and other application services.
+ *
+ * @example
+ * // Creating a database config provider
+ * const databaseConfig = configProvider.create(async (app) => ({
+ *   connection: app.env.get('DB_CONNECTION', 'sqlite'),
+ *   host: app.env.get('DB_HOST', 'localhost'),
+ *   port: app.env.get('DB_PORT', 5432)
+ * }))
+ *
+ * @example
+ * // Resolving a config provider
+ * const config = await configProvider.resolve(app, databaseConfig)
+ * if (config) {
+ *   console.log(`Database connection: ${config.connection}`)
+ * }
  */
 export const configProvider = {
+    /**
+     * Creates a new config provider that will resolve configuration
+     * when the application is booted.
+     *
+     * @param resolver - Function that receives the application service and returns the configuration
+     *
+     * @example
+     * const mailConfig = configProvider.create(async (app) => ({
+     *   driver: app.env.get('MAIL_DRIVER', 'smtp'),
+     *   host: app.env.get('SMTP_HOST'),
+     *   port: app.env.get('SMTP_PORT', 587)
+     * }))
+     */
     create(resolver) {
         return {
             type: 'provider',
             resolver,
         };
     },
+    /**
+     * Resolves a config provider if the provided value is a valid config provider,
+     * otherwise returns null.
+     *
+     * @param app - The application service instance
+     * @param provider - The potential config provider to resolve
+     *
+     * @example
+     * const resolved = await configProvider.resolve(app, someProvider)
+     * if (resolved) {
+     *   // Use the resolved configuration
+     *   console.log('Config resolved:', resolved)
+     * } else {
+     *   console.log('Not a valid config provider')
+     * }
+     */
     async resolve(app, provider) {
         if (provider && typeof provider === 'object' && 'type' in provider) {
             return provider.resolver(app);

package/build/src/debug.d.ts

@@ -1,2 +1,17 @@
+/**
+ * Debug utility for AdonisJS core. This uses Node.js built-in debuglog
+ * utility to provide debugging information when the NODE_DEBUG environment
+ * variable includes 'adonisjs:core'.
+ *
+ * @example
+ * // Enable debugging by setting environment variable
+ * // NODE_DEBUG=adonisjs:core node app.js
+ *
+ * @example
+ * // Usage in code
+ * import debug from '@adonisjs/core/debug'
+ * debug('Application started')
+ * debug('Processing request: %s', req.url)
+ */
 declare const _default: import("util").DebugLogger;
 export default _default;

package/build/src/debug.js

@@ -7,4 +7,19 @@
  * file that was distributed with this source code.
  */
 import { debuglog } from 'node:util';
+/**
+ * Debug utility for AdonisJS core. This uses Node.js built-in debuglog
+ * utility to provide debugging information when the NODE_DEBUG environment
+ * variable includes 'adonisjs:core'.
+ *
+ * @example
+ * // Enable debugging by setting environment variable
+ * // NODE_DEBUG=adonisjs:core node app.js
+ *
+ * @example
+ * // Usage in code
+ * import debug from '@adonisjs/core/debug'
+ * debug('Application started')
+ * debug('Processing request: %s', req.url)
+ */
 export default debuglog('adonisjs:core');

package/build/src/exceptions.d.ts

@@ -1 +1,41 @@
-export { Exception, createError, RuntimeException, InvalidArgumentsException, } from '@poppinss/utils';
+/**
+ * Core exception classes and utilities for AdonisJS. This module re-exports
+ * commonly used exception classes from @poppinss/utils for creating and
+ * handling errors in AdonisJS applications.
+ *
+ * @example
+ * // Creating a custom exception
+ * import { Exception } from '@adonisjs/core/exceptions'
+ *
+ * class ValidationException extends Exception {
+ *   static status = 422
+ *   static code = 'E_VALIDATION_FAILURE'
+ * }
+ *
+ * @example
+ * // Using createError to create custom error classes
+ * import { createError } from '@adonisjs/core/exceptions'
+ *
+ * const UserNotFound = createError('User not found', 'E_USER_NOT_FOUND', 404)
+ * throw new UserNotFound()
+ */
+export { 
+/**
+ * Base exception class for creating custom exceptions with status codes,
+ * error codes, and additional context.
+ */
+Exception, 
+/**
+ * Utility function to create custom error classes with predefined
+ * message, code, and status.
+ */
+createError, 
+/**
+ * Runtime exception class for errors that occur during application runtime.
+ */
+RuntimeException, 
+/**
+ * Exception class for invalid argument errors, typically used in function
+ * parameter validation.
+ */
+InvalidArgumentsException, } from '@poppinss/utils/exception';

package/build/src/exceptions.js

@@ -6,4 +6,44 @@
  * 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';
+/**
+ * Core exception classes and utilities for AdonisJS. This module re-exports
+ * commonly used exception classes from @poppinss/utils for creating and
+ * handling errors in AdonisJS applications.
+ *
+ * @example
+ * // Creating a custom exception
+ * import { Exception } from '@adonisjs/core/exceptions'
+ *
+ * class ValidationException extends Exception {
+ *   static status = 422
+ *   static code = 'E_VALIDATION_FAILURE'
+ * }
+ *
+ * @example
+ * // Using createError to create custom error classes
+ * import { createError } from '@adonisjs/core/exceptions'
+ *
+ * const UserNotFound = createError('User not found', 'E_USER_NOT_FOUND', 404)
+ * throw new UserNotFound()
+ */
+export { 
+/**
+ * Base exception class for creating custom exceptions with status codes,
+ * error codes, and additional context.
+ */
+Exception, 
+/**
+ * Utility function to create custom error classes with predefined
+ * message, code, and status.
+ */
+createError, 
+/**
+ * Runtime exception class for errors that occur during application runtime.
+ */
+RuntimeException, 
+/**
+ * Exception class for invalid argument errors, typically used in function
+ * parameter validation.
+ */
+InvalidArgumentsException, } from '@poppinss/utils/exception';

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

@@ -1 +1,47 @@
-export { assertExists, assertNotNull, assertIsDefined, assertUnreachable, } from '@poppinss/utils/assert';
+/**
+ * Assertion utilities for type-safe programming in AdonisJS. These functions
+ * provide runtime type assertions that help with TypeScript type narrowing
+ * and catching potential null/undefined issues early.
+ *
+ * @example
+ * // Type-safe null checking
+ * import { assertExists } from '@adonisjs/core/helpers'
+ *
+ * function processUser(user: User | null) {
+ *   assertExists(user) // TypeScript now knows user is not null
+ *   console.log(user.name) // Safe to access properties
+ * }
+ *
+ * @example
+ * // Exhaustiveness checking in switch statements
+ * import { assertUnreachable } from '@adonisjs/core/helpers'
+ *
+ * function handleStatus(status: 'pending' | 'completed') {
+ *   switch (status) {
+ *     case 'pending': return 'Processing...'
+ *     case 'completed': return 'Done!'
+ *     default: return assertUnreachable(status)
+ *   }
+ * }
+ */
+export { 
+/**
+ * Assert that a value exists (is not null or undefined).
+ * Throws an error if the value is null or undefined.
+ */
+assertExists, 
+/**
+ * Assert that a value is not null.
+ * Throws an error if the value is null.
+ */
+assertNotNull, 
+/**
+ * Assert that a value is defined (is not undefined).
+ * Throws an error if the value is undefined.
+ */
+assertIsDefined, 
+/**
+ * Assert that code should never reach this point.
+ * Useful for exhaustiveness checking in switch statements.
+ */
+assertUnreachable, } from '@poppinss/utils/assert';