@adonisjs/core 6.19.0 → 7.0.0-next.1

package/build/modules/dumper/dumper.d.ts

@@ -1,6 +1,6 @@
 import type { HTMLDumpConfig } from '@poppinss/dumper/html/types';
 import type { ConsoleDumpConfig } from '@poppinss/dumper/console/types';
-import type { Application } from '../app.js';
+import type { Application } from '../app.ts';
 /**
  * Dumper exposes the API to dump or die/dump values in your
  * AdonisJS application. An singleton instance of the Dumper
@@ -30,20 +30,64 @@ export declare class Dumper {
     #private;
     constructor(app: Application<any>);
     /**
-     * Configure the HTML formatter output
+     * Configure the HTML formatter output options
+     *
+     * @param config - Configuration options for HTML dump formatting
+     *
+     * @example
+     * ```ts
+     * dumper.configureHtmlOutput({
+     *   showHidden: true,
+     *   depth: 5,
+     *   colors: false
+     * })
+     * ```
      */
     configureHtmlOutput(config: HTMLDumpConfig): this;
     /**
-     * Configure the ANSI formatter output
+     * Configure the ANSI formatter output options for console display
+     *
+     * @param config - Configuration options for ANSI console formatting
+     *
+     * @example
+     * ```ts
+     * dumper.configureAnsiOutput({
+     *   showHidden: true,
+     *   depth: 3,
+     *   collapse: ['Date', 'DateTime']
+     * })
+     * ```
      */
     configureAnsiOutput(config: ConsoleDumpConfig): this;
     /**
-     * Returns the style and the script elements for the
-     * HTML document
+     * Returns the style and script elements that need to be injected into
+     * the HTML document head for proper dump visualization
+     *
+     * @param cspNonce - Optional Content Security Policy nonce for inline scripts
+     *
+     * @example
+     * ```ts
+     * const headElements = dumper.getHeadElements('abc123')
+     * // Insert into your HTML head section
+     * ```
      */
     getHeadElements(cspNonce?: string): string;
     /**
-     * Dump value to HTML ouput
+     * Dump a value to formatted HTML output
+     *
+     * @param value - The value to dump and inspect
+     * @param options - Options for HTML output formatting
+     * @param options.cspNonce - Optional Content Security Policy nonce
+     * @param options.title - Optional title to display in the dump header
+     * @param options.source - Optional source file information for editor links
+     *
+     * @example
+     * ```ts
+     * const htmlOutput = dumper.dumpToHtml(user, {
+     *   title: 'User Object',
+     *   source: { location: '/app/controllers/user.ts', line: 42 }
+     * })
+     * ```
      */
     dumpToHtml(value: unknown, options?: {
         cspNonce?: string;
@@ -54,7 +98,21 @@ export declare class Dumper {
         };
     }): string;
     /**
-     * Dump value to ANSI output
+     * Dump a value to formatted ANSI output for console display
+     *
+     * @param value - The value to dump and inspect
+     * @param options - Options for ANSI output formatting
+     * @param options.title - Optional title to display in the dump header
+     * @param options.source - Optional source file information for editor links
+     *
+     * @example
+     * ```ts
+     * const ansiOutput = dumper.dumpToAnsi(user, {
+     *   title: 'User Debug',
+     *   source: { location: '/app/controllers/user.ts', line: 42 }
+     * })
+     * console.log(ansiOutput)
+     * ```
      */
     dumpToAnsi(value: unknown, options?: {
         title?: string;
@@ -64,12 +122,24 @@ export declare class Dumper {
         };
     }): string;
     /**
-     * Dump values and die. The formatter will be picked
-     * based upon where your app is running.
+     * Dump values and die. This method dumps the provided value and then
+     * terminates the application. The output format is automatically chosen
+     * based on the execution context.
+     *
+     * - During an HTTP request, HTML output will be sent to the browser
+     * - Otherwise the value will be logged to the console in ANSI format
+     *
+     * @param value - The value to dump before terminating
+     * @param traceSourceIndex - Stack trace index for source location (default: 1)
+     *
+     * @example
+     * ```ts
+     * // This will dump the user object and terminate the application
+     * dumper.dd(user)
      *
-     * - During an HTTP request, the HTML output will be
-     *   sent to the server.
-     * - Otherwise the value will be logged in the console
+     * // This will never execute
+     * console.log('This line will not run')
+     * ```
      */
     dd(value: unknown, traceSourceIndex?: number): void;
 }

package/build/modules/dumper/dumper.js

@@ -9,7 +9,7 @@
 import useColors from '@poppinss/colors';
 import { dump as consoleDump } from '@poppinss/dumper/console';
 import { createScript, createStyleSheet, dump } from '@poppinss/dumper/html';
-import { E_DUMP_DIE_EXCEPTION } from './errors.js';
+import { E_DUMP_DIE_EXCEPTION } from "./errors.js";
 const colors = useColors.ansi();
 const DUMP_TITLE_STYLES = `
 .adonisjs-dump-header {
@@ -107,22 +107,52 @@ export class Dumper {
         };
     }
     /**
-     * Configure the HTML formatter output
+     * Configure the HTML formatter output options
+     *
+     * @param config - Configuration options for HTML dump formatting
+     *
+     * @example
+     * ```ts
+     * dumper.configureHtmlOutput({
+     *   showHidden: true,
+     *   depth: 5,
+     *   colors: false
+     * })
+     * ```
      */
     configureHtmlOutput(config) {
         this.#htmlConfig = config;
         return this;
     }
     /**
-     * Configure the ANSI formatter output
+     * Configure the ANSI formatter output options for console display
+     *
+     * @param config - Configuration options for ANSI console formatting
+     *
+     * @example
+     * ```ts
+     * dumper.configureAnsiOutput({
+     *   showHidden: true,
+     *   depth: 3,
+     *   collapse: ['Date', 'DateTime']
+     * })
+     * ```
      */
     configureAnsiOutput(config) {
         this.#consoleConfig = config;
         return this;
     }
     /**
-     * Returns the style and the script elements for the
-     * HTML document
+     * Returns the style and script elements that need to be injected into
+     * the HTML document head for proper dump visualization
+     *
+     * @param cspNonce - Optional Content Security Policy nonce for inline scripts
+     *
+     * @example
+     * ```ts
+     * const headElements = dumper.getHeadElements('abc123')
+     * // Insert into your HTML head section
+     * ```
      */
     getHeadElements(cspNonce) {
         return (`<style id="dumper-styles">` +
@@ -134,7 +164,21 @@ export class Dumper {
             '</script>');
     }
     /**
-     * Dump value to HTML ouput
+     * Dump a value to formatted HTML output
+     *
+     * @param value - The value to dump and inspect
+     * @param options - Options for HTML output formatting
+     * @param options.cspNonce - Optional Content Security Policy nonce
+     * @param options.title - Optional title to display in the dump header
+     * @param options.source - Optional source file information for editor links
+     *
+     * @example
+     * ```ts
+     * const htmlOutput = dumper.dumpToHtml(user, {
+     *   title: 'User Object',
+     *   source: { location: '/app/controllers/user.ts', line: 42 }
+     * })
+     * ```
      */
     dumpToHtml(value, options = {}) {
         const link = this.#getEditorLink(options.source) ?? null;
@@ -146,7 +190,21 @@ export class Dumper {
             dump(value, { cspNonce: options.cspNonce, ...this.#htmlConfig }));
     }
     /**
-     * Dump value to ANSI output
+     * Dump a value to formatted ANSI output for console display
+     *
+     * @param value - The value to dump and inspect
+     * @param options - Options for ANSI output formatting
+     * @param options.title - Optional title to display in the dump header
+     * @param options.source - Optional source file information for editor links
+     *
+     * @example
+     * ```ts
+     * const ansiOutput = dumper.dumpToAnsi(user, {
+     *   title: 'User Debug',
+     *   source: { location: '/app/controllers/user.ts', line: 42 }
+     * })
+     * console.log(ansiOutput)
+     * ```
      */
     dumpToAnsi(value, options = {}) {
         const columns = process.stdout.columns;
@@ -171,12 +229,24 @@ export class Dumper {
         return `${heading}\n${consoleDump(value, this.#consoleConfig)}`;
     }
     /**
-     * Dump values and die. The formatter will be picked
-     * based upon where your app is running.
+     * Dump values and die. This method dumps the provided value and then
+     * terminates the application. The output format is automatically chosen
+     * based on the execution context.
+     *
+     * - During an HTTP request, HTML output will be sent to the browser
+     * - Otherwise the value will be logged to the console in ANSI format
+     *
+     * @param value - The value to dump before terminating
+     * @param traceSourceIndex - Stack trace index for source location (default: 1)
+     *
+     * @example
+     * ```ts
+     * // This will dump the user object and terminate the application
+     * dumper.dd(user)
      *
-     * - During an HTTP request, the HTML output will be
-     *   sent to the server.
-     * - Otherwise the value will be logged in the console
+     * // This will never execute
+     * console.log('This line will not run')
+     * ```
      */
     dd(value, traceSourceIndex = 1) {
         const error = new E_DUMP_DIE_EXCEPTION(value, this);

package/build/modules/dumper/errors.d.ts

@@ -1,12 +1,21 @@
 import { inspect } from 'node:util';
-import type { Kernel } from '@adonisjs/core/ace';
 import { Exception } from '@poppinss/utils/exception';
-import type { HttpContext } from '@adonisjs/core/http';
-import type { Dumper } from './dumper.js';
+import type { Dumper } from './dumper.ts';
+import type { Kernel } from '../ace/kernel.ts';
+import type { HttpContext } from '../http/main.ts';
 /**
- * DumpDie exception is raised by the "dd" function. It will
- * result in dumping the value in response to an HTTP
- * request or printing the value to the console
+ * DumpDie exception raised by the "dd" (dump and die) function.
+ * This special exception terminates execution while dumping the provided
+ * value as HTML (during HTTP requests) or ANSI (in console/CLI).
+ *
+ * @example
+ * ```ts
+ * // This will dump the user object and terminate
+ * dumper.dd(user)
+ *
+ * // In HTTP context: sends HTML dump to browser
+ * // In CLI context: prints ANSI dump to console
+ * ```
  */
 declare class DumpDieException extends Exception {
     #private;
@@ -17,8 +26,10 @@ declare class DumpDieException extends Exception {
     value: unknown;
     constructor(value: unknown, dumper: Dumper);
     /**
-     * Set the index for the trace source. This is helpful when
-     * you build nested helpers on top of Die/Dump
+     * Set the stack trace index for determining the source location.
+     * This is useful when building nested helpers on top of dump/die functionality.
+     *
+     * @param index - Stack trace index (0 = current function, 1 = caller, etc.)
      */
     setTraceSourceIndex(index: number): this;
     /**
@@ -27,11 +38,21 @@ declare class DumpDieException extends Exception {
      */
     report(): void;
     /**
-     * Handler called by the AdonisJS HTTP exception handler
+     * HTTP exception handler that renders the dump as HTML output.
+     * This method is called automatically by AdonisJS when a DumpDieException
+     * is thrown during an HTTP request.
+     *
+     * @param error - The DumpDieException instance
+     * @param ctx - HTTP context for the current request
      */
     handle(error: DumpDieException, ctx: HttpContext): Promise<void>;
     /**
-     * Handler called by the AdonisJS Ace kernel
+     * Ace command exception handler that renders the dump as ANSI output.
+     * This method is called automatically by the Ace kernel when a DumpDieException
+     * is thrown during command execution.
+     *
+     * @param error - The DumpDieException instance
+     * @param kernel - Ace kernel instance
      */
     render(error: DumpDieException, kernel: Kernel): Promise<void>;
     /**

package/build/modules/dumper/errors.js

@@ -10,9 +10,18 @@ import { inspect } from 'node:util';
 import { parse } from 'error-stack-parser-es';
 import { Exception } from '@poppinss/utils/exception';
 /**
- * DumpDie exception is raised by the "dd" function. It will
- * result in dumping the value in response to an HTTP
- * request or printing the value to the console
+ * DumpDie exception raised by the "dd" (dump and die) function.
+ * This special exception terminates execution while dumping the provided
+ * value as HTML (during HTTP requests) or ANSI (in console/CLI).
+ *
+ * @example
+ * ```ts
+ * // This will dump the user object and terminate
+ * dumper.dd(user)
+ *
+ * // In HTTP context: sends HTML dump to browser
+ * // In CLI context: prints ANSI dump to console
+ * ```
  */
 class DumpDieException extends Exception {
     static status = 500;
@@ -45,8 +54,10 @@ class DumpDieException extends Exception {
         };
     }
     /**
-     * Set the index for the trace source. This is helpful when
-     * you build nested helpers on top of Die/Dump
+     * Set the stack trace index for determining the source location.
+     * This is useful when building nested helpers on top of dump/die functionality.
+     *
+     * @param index - Stack trace index (0 = current function, 1 = caller, etc.)
      */
     setTraceSourceIndex(index) {
         this.#traceSourceIndex = index;
@@ -58,7 +69,12 @@ class DumpDieException extends Exception {
      */
     report() { }
     /**
-     * Handler called by the AdonisJS HTTP exception handler
+     * HTTP exception handler that renders the dump as HTML output.
+     * This method is called automatically by AdonisJS when a DumpDieException
+     * is thrown during an HTTP request.
+     *
+     * @param error - The DumpDieException instance
+     * @param ctx - HTTP context for the current request
      */
     async handle(error, ctx) {
         const source = this.#getErrorSource();
@@ -81,7 +97,12 @@ class DumpDieException extends Exception {
             '</html>');
     }
     /**
-     * Handler called by the AdonisJS Ace kernel
+     * Ace command exception handler that renders the dump as ANSI output.
+     * This method is called automatically by the Ace kernel when a DumpDieException
+     * is thrown during command execution.
+     *
+     * @param error - The DumpDieException instance
+     * @param kernel - Ace kernel instance
      */
     async render(error, kernel) {
         const source = this.#getErrorSource();

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

@@ -1,3 +1,3 @@
-export * as errors from './errors.js';
-export { Dumper } from './dumper.js';
-export { defineConfig } from './define_config.js';
+export * as errors from './errors.ts';
+export { Dumper } from './dumper.ts';
+export { defineConfig } from './define_config.ts';

package/build/modules/dumper/main.js

@@ -6,6 +6,6 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-export * as errors from './errors.js';
-export { Dumper } from './dumper.js';
-export { defineConfig } from './define_config.js';
+export * as errors from "./errors.js";
+export { Dumper } from "./dumper.js";
+export { defineConfig } from "./define_config.js";

package/build/modules/dumper/plugins/edge.d.ts

@@ -1,5 +1,5 @@
 import { type Edge } from 'edge.js';
-import { type Dumper } from '../dumper.js';
+import { type Dumper } from '../dumper.ts';
 /**
  * Returns an edge plugin that integrates with a given
  * dumper instance

package/build/modules/hash/define_config.d.ts

@@ -1,8 +1,8 @@
-import type { Argon } from './drivers/argon.js';
-import type { Scrypt } from './drivers/scrypt.js';
-import type { Bcrypt } from './drivers/bcrypt.js';
-import type { ConfigProvider } from '../../src/types.js';
-import type { ArgonConfig, BcryptConfig, ScryptConfig, ManagerDriverFactory } from '../../types/hash.js';
+import type { Argon } from './drivers/argon.ts';
+import type { Scrypt } from './drivers/scrypt.ts';
+import type { Bcrypt } from './drivers/bcrypt.ts';
+import type { ConfigProvider } from '../../src/types.ts';
+import type { ArgonConfig, BcryptConfig, ScryptConfig, ManagerDriverFactory } from '../../types/hash.ts';
 /**
  * Resolved config from the config provider will be
  * the config accepted by the hash manager
@@ -14,18 +14,63 @@ type ResolvedConfig<KnownHashers extends Record<string, ManagerDriverFactory | C
     };
 };
 /**
- * Define config for the hash service.
+ * Define config for the hash service. This function creates a configuration
+ * provider that lazily imports and resolves hash drivers when needed.
+ *
+ * @param config - Configuration object containing default hasher and list of hashers
+ * @param config.default - Optional default hasher name (must exist in the list)
+ * @param config.list - Record of hasher configurations or config providers
+ *
+ * @example
+ * ```ts
+ * const hashConfig = defineConfig({
+ *   default: 'scrypt',
+ *   list: {
+ *     scrypt: drivers.scrypt({
+ *       cost: 16384,
+ *       blockSize: 8,
+ *       parallelization: 1,
+ *       saltSize: 16,
+ *       keyLength: 64,
+ *     }),
+ *     bcrypt: drivers.bcrypt({
+ *       rounds: 10,
+ *     })
+ *   }
+ * })
+ * ```
  */
 export declare function defineConfig<KnownHashers extends Record<string, ManagerDriverFactory | ConfigProvider<ManagerDriverFactory>>>(config: {
     default?: keyof KnownHashers;
     list: KnownHashers;
 }): ConfigProvider<ResolvedConfig<KnownHashers>>;
 /**
- * Helpers to configure drivers inside the config file. The
- * drivers will be imported and constructed lazily.
+ * Helpers to configure drivers inside the config file. These functions create
+ * configuration providers that lazily import and instantiate hash drivers.
  *
  * - Import happens when you first use the hash module
  * - Construction of drivers happens when you first use a driver
+ *
+ * @example
+ * ```ts
+ * const hashConfig = defineConfig({
+ *   default: 'bcrypt',
+ *   list: {
+ *     bcrypt: drivers.bcrypt({ rounds: 12 }),
+ *     argon2: drivers.argon2({
+ *       variant: 'id',
+ *       memory: 65536,
+ *       time: 3,
+ *       parallelism: 4
+ *     }),
+ *     scrypt: drivers.scrypt({
+ *       cost: 16384,
+ *       blockSize: 8,
+ *       parallelization: 1
+ *     })
+ *   }
+ * })
+ * ```
  */
 export declare const drivers: {
     argon2: (config: ArgonConfig) => ConfigProvider<() => Argon>;

package/build/modules/hash/define_config.js

@@ -6,11 +6,35 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import { InvalidArgumentsException } from '@poppinss/utils';
-import debug from '../../src/debug.js';
-import { configProvider } from '../../src/config_provider.js';
+import { InvalidArgumentsException } from '@poppinss/utils/exception';
+import debug from "../../src/debug.js";
+import { configProvider } from "../../src/config_provider.js";
 /**
- * Define config for the hash service.
+ * Define config for the hash service. This function creates a configuration
+ * provider that lazily imports and resolves hash drivers when needed.
+ *
+ * @param config - Configuration object containing default hasher and list of hashers
+ * @param config.default - Optional default hasher name (must exist in the list)
+ * @param config.list - Record of hasher configurations or config providers
+ *
+ * @example
+ * ```ts
+ * const hashConfig = defineConfig({
+ *   default: 'scrypt',
+ *   list: {
+ *     scrypt: drivers.scrypt({
+ *       cost: 16384,
+ *       blockSize: 8,
+ *       parallelization: 1,
+ *       saltSize: 16,
+ *       keyLength: 64,
+ *     }),
+ *     bcrypt: drivers.bcrypt({
+ *       rounds: 10,
+ *     })
+ *   }
+ * })
+ * ```
  */
 export function defineConfig(config) {
     /**
@@ -49,11 +73,32 @@ export function defineConfig(config) {
     });
 }
 /**
- * Helpers to configure drivers inside the config file. The
- * drivers will be imported and constructed lazily.
+ * Helpers to configure drivers inside the config file. These functions create
+ * configuration providers that lazily import and instantiate hash drivers.
  *
  * - Import happens when you first use the hash module
  * - Construction of drivers happens when you first use a driver
+ *
+ * @example
+ * ```ts
+ * const hashConfig = defineConfig({
+ *   default: 'bcrypt',
+ *   list: {
+ *     bcrypt: drivers.bcrypt({ rounds: 12 }),
+ *     argon2: drivers.argon2({
+ *       variant: 'id',
+ *       memory: 65536,
+ *       time: 3,
+ *       parallelism: 4
+ *     }),
+ *     scrypt: drivers.scrypt({
+ *       cost: 16384,
+ *       blockSize: 8,
+ *       parallelization: 1
+ *     })
+ *   }
+ * })
+ * ```
  */
 export const drivers = {
     argon2: (config) => {

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

@@ -1,2 +1,2 @@
 export * from '@adonisjs/hash';
-export { defineConfig, drivers } from './define_config.js';
+export { defineConfig, drivers } from './define_config.ts';

package/build/modules/hash/main.js

@@ -7,4 +7,4 @@
  * file that was distributed with this source code.
  */
 export * from '@adonisjs/hash';
-export { defineConfig, drivers } from './define_config.js';
+export { defineConfig, drivers } from "./define_config.js";

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

@@ -4,4 +4,4 @@
  */
 import '@adonisjs/bodyparser';
 export * from '@adonisjs/http-server';
-export { RequestValidator } from './request_validator.js';
+export { RequestValidator } from './request_validator.ts';

package/build/modules/http/main.js

@@ -12,4 +12,4 @@
  */
 import '@adonisjs/bodyparser';
 export * from '@adonisjs/http-server';
-export { RequestValidator } from './request_validator.js';
+export { RequestValidator } from "./request_validator.js";

package/build/modules/http/request_validator.d.ts

@@ -1,13 +1,21 @@
 import type { VineValidator } from '@vinejs/vine';
 import type { Infer, SchemaTypes, ErrorReporterContract, MessagesProviderContact } from '@vinejs/vine/types';
-import type { HttpContext } from './main.js';
-import type { FeatureFlags } from '../app.js';
-import type { ExperimentalFlagsList } from '../../types/app.js';
-import type { RequestValidationOptions } from '../../types/http.js';
+import type { HttpContext } from './main.ts';
+import type { FeatureFlags } from '../app.ts';
+import type { ExperimentalFlagsList } from '../../types/app.ts';
+import type { RequestValidationOptions } from '../../types/http.ts';
 /**
- * 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 declare class RequestValidator {
     #private;
@@ -29,8 +37,27 @@ export declare class RequestValidator {
      */
     static messagesProvider?: (_: HttpContext) => MessagesProviderContact;
     /**
-     * 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<Schema extends SchemaTypes, MetaData extends undefined | Record<string, any>>(validator: VineValidator<Schema, MetaData>, ...[options]: [undefined] extends MetaData ? [options?: RequestValidationOptions<MetaData> | undefined] : [options: RequestValidationOptions<MetaData>]): Promise<Infer<Schema>>;
 }