@adonisjs/core 6.19.0 → 7.0.0-next.1

package/build/modules/http/request_validator.js

@@ -7,9 +7,17 @@
  * file that was distributed with this source code.
  */
 /**
- * Request validator is used validate HTTP request data using
- * VineJS validators. You may validate the request body,
- * files, cookies, and headers.
+ * Request validator for validating HTTP request data using VineJS validators.
+ * This class provides a convenient way to validate request body, files, cookies,
+ * headers, and URL parameters in AdonisJS applications.
+ *
+ * @example
+ * ```ts
+ * // Inside a controller method
+ * const data = await request.validateUsing(createUserValidator, {
+ *   messagesProvider: customMessages
+ * })
+ * ```
  */
 export class RequestValidator {
     #ctx;
@@ -35,8 +43,27 @@ export class RequestValidator {
      */
     static messagesProvider;
     /**
-     * The validate method can be used to validate the request
-     * data for the current request using VineJS validators
+     * Validate the current HTTP request data using a VineJS validator.
+     * This method automatically includes request body, files, URL parameters,
+     * headers, and cookies in the validation data.
+     *
+     * @param validator - VineJS validator instance
+     * @param options - Optional validation options including custom error reporters and messages
+     *
+     * @example
+     * ```ts
+     * const createUserValidator = vine.compile(
+     *   vine.object({
+     *     email: vine.string().email(),
+     *     name: vine.string().minLength(3)
+     *   })
+     * )
+     *
+     * const data = await request.validateUsing(createUserValidator, {
+     *   errorReporter: () => vine.errors.SimpleErrorReporter,
+     *   messagesProvider: customMessages
+     * })
+     * ```
      */
     validateUsing(validator, ...[options]) {
         const validatorOptions = options || {};

package/build/modules/transformers/main.d.ts

@@ -0,0 +1 @@
+export * from '@adonisjs/http-transformers';

package/build/modules/transformers/main.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 * from '@adonisjs/http-transformers';

package/build/providers/app_provider.d.ts

@@ -1,64 +1,236 @@
-import type { ApplicationService } from '../src/types.js';
+import { Router } from '../modules/http/main.ts';
+import { type SerializeFn } from '../types/transformers.ts';
+import type { ApplicationService } from '../src/types.ts';
+/**
+ * Extend HTTP request class with the transform method
+ */
+declare module '@adonisjs/core/http' {
+    interface HttpContext {
+        serialize: SerializeFn;
+    }
+}
 /**
  * The Application Service provider registers all the baseline
  * features required to run the framework.
+ *
+ * This provider handles the registration of core services including:
+ * - Application instance
+ * - Logger and logger manager
+ * - Configuration
+ * - Event emitter
+ * - Encryption service
+ * - HTTP server and router
+ * - Body parser middleware
+ * - Dumper for debugging
+ * - Test utilities and ACE kernel
+ *
+ * @example
+ * const provider = new AppServiceProvider(app)
+ * provider.register()
+ * await provider.boot()
+ * await provider.ready()
  */
 export default class AppServiceProvider {
     protected app: ApplicationService;
+    /**
+     * Application service provider constructor
+     *
+     * @param app - The application service instance
+     */
     constructor(app: ApplicationService);
     /**
      * Registers test utils with the container
+     *
+     * Creates a singleton binding for 'testUtils' that lazily imports
+     * and instantiates the TestUtils class when first accessed.
+     *
+     * @example
+     * const testUtils = await app.container.make('testUtils')
+     * testUtils.createHttpContext()
      */
     protected registerTestUtils(): void;
     /**
      * Registers ace with the container
+     *
+     * Creates a singleton binding for 'ace' that lazily creates
+     * the ACE kernel for command-line interface functionality.
+     *
+     * @example
+     * const ace = await app.container.make('ace')
+     * await ace.exec('make:controller', ['UserController'])
      */
     protected registerAce(): void;
     /**
      * Registers the application to the container
+     *
+     * Binds the application instance as both a class binding and an alias.
+     * This allows access to the app instance throughout the container.
+     *
+     * @example
+     * const app = await container.make('app')
+     * const appPath = app.makePath('tmp')
      */
     protected registerApp(): void;
     /**
      * Registers the logger class to resolve the default logger
+     *
+     * Creates a singleton binding for the Logger class that resolves
+     * the default logger instance from the logger manager.
+     *
+     * @example
+     * const logger = await container.make(Logger)
+     * logger.info('Application started')
      */
     protected registerLogger(): void;
     /**
      * Registers the logger manager to the container
+     *
+     * Creates a singleton binding for 'logger' that instantiates
+     * the LoggerManager with configuration from config/logger.ts
+     *
+     * @example
+     * const loggerManager = await container.make('logger')
+     * const fileLogger = loggerManager.use('file')
      */
     protected registerLoggerManager(): void;
     /**
      * Registers the config to the container
+     *
+     * Binds the application's config instance as both a class binding
+     * and an alias, allowing access to configuration values.
+     *
+     * @example
+     * const config = await container.make('config')
+     * const appKey = config.get('app.appKey')
      */
     protected registerConfig(): void;
     /**
      * Registers emitter service to the container
+     *
+     * Creates a singleton binding for the event emitter that handles
+     * application-wide event dispatching and listening.
+     *
+     * @example
+     * const emitter = await container.make('emitter')
+     * emitter.emit('user:created', { userId: 123 })
      */
     protected registerEmitter(): void;
     /**
      * Register the encryption service to the container
+     *
+     * Creates a singleton binding for the encryption service using
+     * the app key from configuration for encryption/decryption operations.
+     *
+     * @example
+     * const encryption = await container.make('encryption')
+     * const encrypted = encryption.encrypt('sensitive data')
      */
     protected registerEncryption(): void;
     /**
      * Registers the HTTP server with the container as a singleton
+     *
+     * Creates a singleton binding for the HTTP server that handles
+     * incoming requests, with dependencies on encryption, emitter,
+     * logger, and HTTP configuration.
+     *
+     * @example
+     * const server = await container.make('server')
+     * server.start()
      */
     protected registerServer(): void;
     /**
      * Registers router with the container as a singleton
+     *
+     * Creates a singleton binding for the router by getting it from
+     * the HTTP server instance. The router handles URL routing.
+     *
+     * @example
+     * const router = await container.make('router')
+     * router.get('/', ({ response }) => response.send('Hello'))
      */
     protected registerRouter(): void;
     /**
      * Self construct bodyparser middleware class, since it needs
      * config that cannot be resolved by the container
+     *
+     * Binds the BodyParserMiddleware with bodyparser configuration
+     * and experimental flags for parsing request bodies.
+     *
+     * @example
+     * const middleware = await container.make(BodyParserMiddleware)
+     * await middleware.handle(ctx, next)
      */
     protected registerBodyParserMiddleware(): void;
     /**
      * Registeres singleton instance of the "Dumper" module configured
      * via the "config/app.ts" file.
+     *
+     * The dumper is used for debugging and variable inspection with
+     * configurable HTML and console output formats.
+     *
+     * @example
+     * const dumper = await container.make('dumper')
+     * dumper.dump({ user: { name: 'John' } })
      */
     protected registerDumper(): void;
+    /**
+     * Generates the types needed by the URL builder and writes
+     * them to the ".adonisjs/server/routes.d.ts" file
+     *
+     * This method scans registered routes and generates TypeScript
+     * types for type-safe URL generation in development.
+     *
+     * @param router - The router instance to generate types from
+     *
+     * @example
+     * await generateRoutesTypes(router)
+     * // Creates .adonisjs/server/routes.d.ts with route types
+     */
+    protected generateRoutesTypes(router: Router): Promise<void>;
+    /**
+     * Generates the routes JSON needed by the client integration
+     *
+     * Exports all registered routes as JSON for client-side
+     * applications that need route information.
+     *
+     * @param router - The router instance to export routes from
+     *
+     * @example
+     * await generateRoutesJSONFile(router)
+     * // Creates .adonisjs/client/routes.json
+     */
+    protected generateRoutesJSONFile(router: Router): Promise<void>;
     /**
      * Registers bindings
+     *
+     * Called during the application bootstrap phase to register
+     * all core service bindings with the IoC container.
+     *
+     * @example
+     * const provider = new AppServiceProvider(app)
+     * provider.register() // Registers all core services
      */
     register(): void;
+    /**
+     * Boot the service provider
+     *
+     * Called after all providers have been registered. Sets up
+     * event emitter for BaseEvent and adds transform macro to HttpContext.
+     *
+     * @example
+     * await provider.boot()
+     * // Now HttpContext has transform method available
+     */
     boot(): Promise<void>;
+    /**
+     * Called when the application is ready
+     *
+     * In non-production environments, generates route types and
+     * JSON files for development tooling when router is committed.
+     *
+     * @example
+     * await provider.ready()
+     * // Route types and JSON generated in development
+     */
+    ready(): Promise<void>;
 }

package/build/providers/app_provider.js

@@ -6,25 +6,58 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import { Config } from '../modules/config.js';
-import { Logger } from '../modules/logger.js';
-import { Application } from '../modules/app.js';
-import { Dumper } from '../modules/dumper/dumper.js';
-import { Encryption } from '../modules/encryption.js';
-import { Router, Server } from '../modules/http/main.js';
-import { BaseEvent, Emitter } from '../modules/events.js';
-import BodyParserMiddleware from '../modules/bodyparser/bodyparser_middleware.js';
+import { dirname } from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { Config } from "../modules/config.js";
+import { Logger } from "../modules/logger.js";
+import { Application } from "../modules/app.js";
+import { Dumper } from "../modules/dumper/dumper.js";
+import { HttpContext } from "../modules/http/main.js";
+import { Encryption } from "../modules/encryption.js";
+import { Router, Server } from "../modules/http/main.js";
+import { BaseEvent, Emitter } from "../modules/events.js";
+import { serialize } from "../modules/transformers/main.js";
+import BodyParserMiddleware from "../modules/bodyparser/bodyparser_middleware.js";
 /**
  * The Application Service provider registers all the baseline
  * features required to run the framework.
+ *
+ * This provider handles the registration of core services including:
+ * - Application instance
+ * - Logger and logger manager
+ * - Configuration
+ * - Event emitter
+ * - Encryption service
+ * - HTTP server and router
+ * - Body parser middleware
+ * - Dumper for debugging
+ * - Test utilities and ACE kernel
+ *
+ * @example
+ * const provider = new AppServiceProvider(app)
+ * provider.register()
+ * await provider.boot()
+ * await provider.ready()
  */
 export default class AppServiceProvider {
     app;
+    /**
+     * Application service provider constructor
+     *
+     * @param app - The application service instance
+     */
     constructor(app) {
         this.app = app;
     }
     /**
      * Registers test utils with the container
+     *
+     * Creates a singleton binding for 'testUtils' that lazily imports
+     * and instantiates the TestUtils class when first accessed.
+     *
+     * @example
+     * const testUtils = await app.container.make('testUtils')
+     * testUtils.createHttpContext()
      */
     registerTestUtils() {
         this.app.container.singleton('testUtils', async () => {
@@ -34,6 +67,13 @@ export default class AppServiceProvider {
     }
     /**
      * Registers ace with the container
+     *
+     * Creates a singleton binding for 'ace' that lazily creates
+     * the ACE kernel for command-line interface functionality.
+     *
+     * @example
+     * const ace = await app.container.make('ace')
+     * await ace.exec('make:controller', ['UserController'])
      */
     registerAce() {
         this.app.container.singleton('ace', async () => {
@@ -43,6 +83,13 @@ export default class AppServiceProvider {
     }
     /**
      * Registers the application to the container
+     *
+     * Binds the application instance as both a class binding and an alias.
+     * This allows access to the app instance throughout the container.
+     *
+     * @example
+     * const app = await container.make('app')
+     * const appPath = app.makePath('tmp')
      */
     registerApp() {
         this.app.container.singleton(Application, () => this.app);
@@ -50,6 +97,13 @@ export default class AppServiceProvider {
     }
     /**
      * Registers the logger class to resolve the default logger
+     *
+     * Creates a singleton binding for the Logger class that resolves
+     * the default logger instance from the logger manager.
+     *
+     * @example
+     * const logger = await container.make(Logger)
+     * logger.info('Application started')
      */
     registerLogger() {
         this.app.container.singleton(Logger, async (resolver) => {
@@ -59,6 +113,13 @@ export default class AppServiceProvider {
     }
     /**
      * Registers the logger manager to the container
+     *
+     * Creates a singleton binding for 'logger' that instantiates
+     * the LoggerManager with configuration from config/logger.ts
+     *
+     * @example
+     * const loggerManager = await container.make('logger')
+     * const fileLogger = loggerManager.use('file')
      */
     registerLoggerManager() {
         this.app.container.singleton('logger', async () => {
@@ -69,6 +130,13 @@ export default class AppServiceProvider {
     }
     /**
      * Registers the config to the container
+     *
+     * Binds the application's config instance as both a class binding
+     * and an alias, allowing access to configuration values.
+     *
+     * @example
+     * const config = await container.make('config')
+     * const appKey = config.get('app.appKey')
      */
     registerConfig() {
         this.app.container.singleton(Config, () => this.app.config);
@@ -76,6 +144,13 @@ export default class AppServiceProvider {
     }
     /**
      * Registers emitter service to the container
+     *
+     * Creates a singleton binding for the event emitter that handles
+     * application-wide event dispatching and listening.
+     *
+     * @example
+     * const emitter = await container.make('emitter')
+     * emitter.emit('user:created', { userId: 123 })
      */
     registerEmitter() {
         this.app.container.singleton(Emitter, async () => {
@@ -85,6 +160,13 @@ export default class AppServiceProvider {
     }
     /**
      * Register the encryption service to the container
+     *
+     * Creates a singleton binding for the encryption service using
+     * the app key from configuration for encryption/decryption operations.
+     *
+     * @example
+     * const encryption = await container.make('encryption')
+     * const encrypted = encryption.encrypt('sensitive data')
      */
     registerEncryption() {
         this.app.container.singleton(Encryption, () => {
@@ -95,6 +177,14 @@ export default class AppServiceProvider {
     }
     /**
      * Registers the HTTP server with the container as a singleton
+     *
+     * Creates a singleton binding for the HTTP server that handles
+     * incoming requests, with dependencies on encryption, emitter,
+     * logger, and HTTP configuration.
+     *
+     * @example
+     * const server = await container.make('server')
+     * server.start()
      */
     registerServer() {
         this.app.container.singleton(Server, async (resolver) => {
@@ -108,6 +198,13 @@ export default class AppServiceProvider {
     }
     /**
      * Registers router with the container as a singleton
+     *
+     * Creates a singleton binding for the router by getting it from
+     * the HTTP server instance. The router handles URL routing.
+     *
+     * @example
+     * const router = await container.make('router')
+     * router.get('/', ({ response }) => response.send('Hello'))
      */
     registerRouter() {
         this.app.container.singleton(Router, async (resolver) => {
@@ -119,6 +216,13 @@ export default class AppServiceProvider {
     /**
      * Self construct bodyparser middleware class, since it needs
      * config that cannot be resolved by the container
+     *
+     * Binds the BodyParserMiddleware with bodyparser configuration
+     * and experimental flags for parsing request bodies.
+     *
+     * @example
+     * const middleware = await container.make(BodyParserMiddleware)
+     * await middleware.handle(ctx, next)
      */
     registerBodyParserMiddleware() {
         this.app.container.bind(BodyParserMiddleware, () => {
@@ -129,6 +233,13 @@ export default class AppServiceProvider {
     /**
      * Registeres singleton instance of the "Dumper" module configured
      * via the "config/app.ts" file.
+     *
+     * The dumper is used for debugging and variable inspection with
+     * configurable HTML and console output formats.
+     *
+     * @example
+     * const dumper = await container.make('dumper')
+     * dumper.dump({ user: { name: 'John' } })
      */
     registerDumper() {
         this.app.container.singleton(Dumper, async () => {
@@ -144,8 +255,61 @@ export default class AppServiceProvider {
         });
         this.app.container.alias('dumper', Dumper);
     }
+    /**
+     * Generates the types needed by the URL builder and writes
+     * them to the ".adonisjs/server/routes.d.ts" file
+     *
+     * This method scans registered routes and generates TypeScript
+     * types for type-safe URL generation in development.
+     *
+     * @param router - The router instance to generate types from
+     *
+     * @example
+     * await generateRoutesTypes(router)
+     * // Creates .adonisjs/server/routes.d.ts with route types
+     */
+    async generateRoutesTypes(router) {
+        const types = router.generateTypes(4);
+        const outputPath = this.app.generatedServerPath('routes.d.ts');
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, [
+            `import '@adonisjs/core/types/http'`,
+            '',
+            `declare module '@adonisjs/core/types/http' {`,
+            '  type ScannedRoutes = {',
+            types,
+            '  }',
+            'export interface RoutesList extends ScannedRoutes {}',
+            '}',
+        ].join('\n'));
+    }
+    /**
+     * Generates the routes JSON needed by the client integration
+     *
+     * Exports all registered routes as JSON for client-side
+     * applications that need route information.
+     *
+     * @param router - The router instance to export routes from
+     *
+     * @example
+     * await generateRoutesJSONFile(router)
+     * // Creates .adonisjs/client/routes.json
+     */
+    async generateRoutesJSONFile(router) {
+        const routes = router.toJSON();
+        const outputPath = this.app.makePath('.adonisjs/client/routes.json');
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, JSON.stringify(routes, null, 2));
+    }
     /**
      * Registers bindings
+     *
+     * Called during the application bootstrap phase to register
+     * all core service bindings with the IoC container.
+     *
+     * @example
+     * const provider = new AppServiceProvider(app)
+     * provider.register() // Registers all core services
      */
     register() {
         this.registerApp();
@@ -161,7 +325,39 @@ export default class AppServiceProvider {
         this.registerRouter();
         this.registerBodyParserMiddleware();
     }
+    /**
+     * Boot the service provider
+     *
+     * Called after all providers have been registered. Sets up
+     * event emitter for BaseEvent and adds transform macro to HttpContext.
+     *
+     * @example
+     * await provider.boot()
+     * // Now HttpContext has transform method available
+     */
     async boot() {
         BaseEvent.useEmitter(await this.app.container.make('emitter'));
+        HttpContext.instanceProperty('serialize', function (...args) {
+            return serialize(...args);
+        });
+    }
+    /**
+     * Called when the application is ready
+     *
+     * In non-production environments, generates route types and
+     * JSON files for development tooling when router is committed.
+     *
+     * @example
+     * await provider.ready()
+     * // Route types and JSON generated in development
+     */
+    async ready() {
+        if (!this.app.inProduction) {
+            const router = await this.app.container.make('router');
+            if (router.commited) {
+                await this.generateRoutesJSONFile(router);
+                await this.generateRoutesTypes(router);
+            }
+        }
     }
 }

package/build/providers/edge_provider.d.ts

@@ -1,6 +1,6 @@
 import { type Edge } from 'edge.js';
-import type { ApplicationService } from '../src/types.js';
-import { type Route } from '../modules/http/main.js';
+import type { ApplicationService } from '../src/types.ts';
+import { type Route } from '../modules/http/main.ts';
 declare module '@adonisjs/core/http' {
     interface HttpContext {
         /**
@@ -20,12 +20,41 @@ declare module '@adonisjs/core/http' {
 /**
  * The Edge service provider configures Edge to work within
  * an AdonisJS application environment
+ *
+ * This provider integrates EdgeJS template engine with AdonisJS by:
+ * - Mounting the views directory
+ * - Configuring template caching for production
+ * - Adding global helpers for route generation
+ * - Creating isolated renderer instances for HTTP contexts
+ * - Adding render macro to BriskRoute for template rendering
+ *
+ * @example
+ * const provider = new EdgeServiceProvider(app)
+ * await provider.boot()
  */
 export default class EdgeServiceProvider {
     protected app: ApplicationService;
+    /**
+     * Edge service provider constructor
+     *
+     * Sets the usingEdgeJS flag to true to indicate EdgeJS is being used.
+     *
+     * @param app - The application service instance
+     */
     constructor(app: ApplicationService);
     /**
      * Bridge AdonisJS and Edge
+     *
+     * Configures EdgeJS integration by:
+     * - Setting up template mounting and caching
+     * - Defining global helpers (route, signedRoute, app, config)
+     * - Adding view getter to HttpContext for isolated rendering
+     * - Adding render macro to BriskRoute
+     * - Registering dumper plugin
+     *
+     * @example
+     * await provider.boot()
+     * // Now edge templates can use {{ route('home') }} helper
      */
     boot(): Promise<void>;
 }