@adonisjs/core 6.19.0 → 7.0.0-next.0

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

@@ -4,7 +4,16 @@ import { Secret } from '@poppinss/utils';
  * shareable tokens while storing the token hash within the database.
  *
  * This class is used by the Auth and the Persona packages to manage
- * tokens
+ * tokens for authentication and authorization purposes.
+ *
+ * @example
+ * class UserToken extends VerificationToken {
+ *   constructor(user: User, secret: Secret<string>) {
+ *     super()
+ *     this.tokenableId = user.id
+ *     this.computeValue(secret)
+ *   }
+ * }
  */
 export declare abstract class VerificationToken {
     /**
@@ -13,6 +22,8 @@ export declare abstract class VerificationToken {
      *
      * Returns null when unable to decode the token because of
      * invalid format or encoding.
+     *
+     * @param value - The token string to decode
      */
     static decode(value: string): null | {
         identifier: string;
@@ -21,6 +32,10 @@ export declare abstract class VerificationToken {
     /**
      * Creates a transient token that can be shared with the persistence
      * layer.
+     *
+     * @param userId - The user ID for whom the token is being created
+     * @param size - The size of the random token seed
+     * @param expiresIn - Token expiration time (string like '2h' or number in seconds)
      */
     static createTransientToken(userId: string | number | BigInt, size: number, expiresIn: string | number): {
         secret: Secret<string>;
@@ -30,6 +45,8 @@ export declare abstract class VerificationToken {
     };
     /**
      * Creates a secret opaque token and its hash.
+     *
+     * @param size - The length of the random token to generate
      */
     static seed(size: number): {
         secret: Secret<string>;
@@ -64,6 +81,8 @@ export declare abstract class VerificationToken {
     /**
      * Compute the value property using the given secret. You can
      * get secret via the static "createTransientToken" method.
+     *
+     * @param secret - The secret value to compute the public token value from
      */
     protected computeValue(secret: Secret<string>): void;
     /**
@@ -74,6 +93,8 @@ export declare abstract class VerificationToken {
     isExpired(): boolean;
     /**
      * Verifies the value of a token against the pre-defined hash
+     *
+     * @param secret - The secret to verify against the stored hash
      */
     verify(secret: Secret<string>): boolean;
 }

package/build/src/helpers/verification_token.js

@@ -8,13 +8,23 @@
  */
 import { createHash } from 'node:crypto';
 import string from '@poppinss/utils/string';
-import { base64, safeEqual, Secret } from '@poppinss/utils';
+import { safeEqual, Secret } from '@poppinss/utils';
+import base64 from '@poppinss/utils/base64';
 /**
  * Verification token class can be used to create tokens publicly
  * shareable tokens while storing the token hash within the database.
  *
  * This class is used by the Auth and the Persona packages to manage
- * tokens
+ * tokens for authentication and authorization purposes.
+ *
+ * @example
+ * class UserToken extends VerificationToken {
+ *   constructor(user: User, secret: Secret<string>) {
+ *     super()
+ *     this.tokenableId = user.id
+ *     this.computeValue(secret)
+ *   }
+ * }
  */
 export class VerificationToken {
     /**
@@ -23,6 +33,8 @@ export class VerificationToken {
      *
      * Returns null when unable to decode the token because of
      * invalid format or encoding.
+     *
+     * @param value - The token string to decode
      */
     static decode(value) {
         /**
@@ -54,6 +66,10 @@ export class VerificationToken {
     /**
      * Creates a transient token that can be shared with the persistence
      * layer.
+     *
+     * @param userId - The user ID for whom the token is being created
+     * @param size - The size of the random token seed
+     * @param expiresIn - Token expiration time (string like '2h' or number in seconds)
      */
     static createTransientToken(userId, size, expiresIn) {
         const expiresAt = new Date();
@@ -66,6 +82,8 @@ export class VerificationToken {
     }
     /**
      * Creates a secret opaque token and its hash.
+     *
+     * @param size - The length of the random token to generate
      */
     static seed(size) {
         const seed = string.random(size);
@@ -76,6 +94,8 @@ export class VerificationToken {
     /**
      * Compute the value property using the given secret. You can
      * get secret via the static "createTransientToken" method.
+     *
+     * @param secret - The secret value to compute the public token value from
      */
     computeValue(secret) {
         this.value = new Secret(`${base64.urlEncode(String(this.identifier))}.${base64.urlEncode(secret.release())}`);
@@ -90,6 +110,8 @@ export class VerificationToken {
     }
     /**
      * Verifies the value of a token against the pre-defined hash
+     *
+     * @param secret - The secret to verify against the stored hash
      */
     verify(secret) {
         const newHash = createHash('sha256').update(secret.release()).digest('hex');

package/build/src/ignitor/ace.d.ts

@@ -1,20 +1,40 @@
-import { Ignitor } from './main.js';
-import type { ApplicationService } from '../types.js';
+import { type Ignitor } from './main.ts';
+import type { ApplicationService } from '../types.ts';
 /**
  * The Ace process is used to start the application in the
- * console environment.
+ * console environment. It manages the Ace kernel lifecycle
+ * and command execution.
+ *
+ * @example
+ * const ignitor = new Ignitor()
+ * const aceProcess = new AceProcess(ignitor)
+ *
+ * await aceProcess
+ *   .configure((app) => {
+ *     // Configure ace kernel
+ *   })
+ *   .handle(['make:controller', 'UserController'])
  */
 export declare class AceProcess {
     #private;
+    /**
+     * Creates a new Ace process instance
+     *
+     * @param ignitor - The ignitor instance used to create and manage the app
+     */
     constructor(ignitor: Ignitor);
     /**
      * Register a callback that can be used to configure the ace
      * kernel before the handle method is called
+     *
+     * @param callback - Configuration callback function
      */
     configure(callback: (app: ApplicationService) => Promise<void> | void): this;
     /**
      * Handles the command line arguments and executes
      * the matching ace commands
+     *
+     * @param argv - Command line arguments array
      */
     handle(argv: string[]): Promise<void>;
 }

package/build/src/ignitor/ace.js

@@ -8,7 +8,18 @@
  */
 /**
  * The Ace process is used to start the application in the
- * console environment.
+ * console environment. It manages the Ace kernel lifecycle
+ * and command execution.
+ *
+ * @example
+ * const ignitor = new Ignitor()
+ * const aceProcess = new AceProcess(ignitor)
+ *
+ * await aceProcess
+ *   .configure((app) => {
+ *     // Configure ace kernel
+ *   })
+ *   .handle(['make:controller', 'UserController'])
  */
 export class AceProcess {
     /**
@@ -20,12 +31,19 @@ export class AceProcess {
      * handle method is called
      */
     #configureCallback = () => { };
+    /**
+     * Creates a new Ace process instance
+     *
+     * @param ignitor - The ignitor instance used to create and manage the app
+     */
     constructor(ignitor) {
         this.#ignitor = ignitor;
     }
     /**
      * Register a callback that can be used to configure the ace
      * kernel before the handle method is called
+     *
+     * @param callback - Configuration callback function
      */
     configure(callback) {
         this.#configureCallback = callback;
@@ -34,6 +52,8 @@ export class AceProcess {
     /**
      * Handles the command line arguments and executes
      * the matching ace commands
+     *
+     * @param argv - Command line arguments array
      */
     async handle(argv) {
         const app = this.#ignitor.createApp('console');

package/build/src/ignitor/http.d.ts

@@ -1,15 +1,28 @@
 import type { Server as NodeHttpsServer } from 'node:https';
-import { IncomingMessage, ServerResponse, Server as NodeHttpServer } from 'node:http';
-import { Ignitor } from './main.js';
+import { type IncomingMessage, type ServerResponse, type Server as NodeHttpServer } from 'node:http';
+import { type Ignitor } from './main.ts';
 /**
  * The HTTP server process is used to start the application in the
- * web environment.
+ * web environment. It creates and manages the Node.js HTTP server
+ * instance, handling lifecycle events and monitoring.
+ *
+ * @example
+ * const ignitor = new Ignitor()
+ * const httpProcess = new HttpServerProcess(ignitor)
+ * await httpProcess.start()
  */
 export declare class HttpServerProcess {
     #private;
+    /**
+     * Creates a new HTTP server process instance
+     *
+     * @param ignitor - The ignitor instance used to create and manage the app
+     */
     constructor(ignitor: Ignitor);
     /**
      * Start the HTTP server by wiring up the application
+     *
+     * @param serverCallback - Optional callback to create custom HTTP server instance
      */
     start(serverCallback?: (handler: (req: IncomingMessage, res: ServerResponse) => any) => NodeHttpsServer | NodeHttpServer): Promise<void>;
 }

package/build/src/ignitor/http.js

@@ -6,17 +6,28 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import { createServer } from 'node:http';
-import debug from '../debug.js';
+import { createServer, } from 'node:http';
+import debug from "../debug.js";
 /**
  * The HTTP server process is used to start the application in the
- * web environment.
+ * web environment. It creates and manages the Node.js HTTP server
+ * instance, handling lifecycle events and monitoring.
+ *
+ * @example
+ * const ignitor = new Ignitor()
+ * const httpProcess = new HttpServerProcess(ignitor)
+ * await httpProcess.start()
  */
 export class HttpServerProcess {
     /**
      * Ignitor reference
      */
     #ignitor;
+    /**
+     * Creates a new HTTP server process instance
+     *
+     * @param ignitor - The ignitor instance used to create and manage the app
+     */
     constructor(ignitor) {
         this.#ignitor = ignitor;
     }
@@ -89,6 +100,8 @@ export class HttpServerProcess {
     }
     /**
      * Start the HTTP server by wiring up the application
+     *
+     * @param serverCallback - Optional callback to create custom HTTP server instance
      */
     async start(serverCallback) {
         const startTime = process.hrtime();

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

@@ -1,14 +1,33 @@
-import { AceProcess } from './ace.js';
-import { TestRunnerProcess } from './test.js';
-import { HttpServerProcess } from './http.js';
-import type { AppEnvironments } from '../../types/app.js';
-import type { ApplicationService, IgnitorOptions } from '../types.js';
+import { AceProcess } from './ace.ts';
+import { TestRunnerProcess } from './test.ts';
+import { HttpServerProcess } from './http.ts';
+import type { AppEnvironments } from '../../types/app.ts';
+import type { ApplicationService, IgnitorOptions } from '../types.ts';
 /**
  * Ignitor is used to instantiate an AdonisJS application in different
- * known environments.
+ * known environments. It serves as the main entry point for creating
+ * and managing application processes.
+ *
+ * @example
+ * const ignitor = new Ignitor(new URL(import.meta.url))
+ *
+ * // For HTTP server
+ * await ignitor.httpServer().start()
+ *
+ * // For CLI commands
+ * await ignitor.ace().handle(process.argv.slice(2))
+ *
+ * // For tests
+ * await ignitor.testRunner().run(() => {})
  */
 export declare class Ignitor {
     #private;
+    /**
+     * Creates a new Ignitor instance
+     *
+     * @param appRoot - The root URL of the application
+     * @param options - Configuration options for the ignitor
+     */
     constructor(appRoot: URL, options?: IgnitorOptions);
     /**
      * Get access to the application instance created
@@ -18,10 +37,14 @@ export declare class Ignitor {
     getApp(): ApplicationService | undefined;
     /**
      * Create an instance of AdonisJS application
+     *
+     * @param environment - The environment in which to create the app (web, console, test, repl)
      */
     createApp(environment: AppEnvironments): ApplicationService;
     /**
      * Tap to access the application class instance.
+     *
+     * @param callback - Callback function to execute when app is created
      */
     tap(callback: (app: ApplicationService) => void): this;
     /**

package/build/src/ignitor/main.js

@@ -6,15 +6,28 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import debug from '../debug.js';
-import { AceProcess } from './ace.js';
-import { TestRunnerProcess } from './test.js';
-import { HttpServerProcess } from './http.js';
-import { setApp } from '../../services/app.js';
-import { Application } from '../../modules/app.js';
+import debug from "../debug.js";
+import { AceProcess } from "./ace.js";
+import { TestRunnerProcess } from "./test.js";
+import { HttpServerProcess } from "./http.js";
+import { setApp } from "../../services/app.js";
+import { Application } from "../../modules/app.js";
 /**
  * Ignitor is used to instantiate an AdonisJS application in different
- * known environments.
+ * known environments. It serves as the main entry point for creating
+ * and managing application processes.
+ *
+ * @example
+ * const ignitor = new Ignitor(new URL(import.meta.url))
+ *
+ * // For HTTP server
+ * await ignitor.httpServer().start()
+ *
+ * // For CLI commands
+ * await ignitor.ace().handle(process.argv.slice(2))
+ *
+ * // For tests
+ * await ignitor.testRunner().run(() => {})
  */
 export class Ignitor {
     /**
@@ -38,6 +51,12 @@ export class Ignitor {
      * Reference to the created application
      */
     #tapCallbacks = new Set();
+    /**
+     * Creates a new Ignitor instance
+     *
+     * @param appRoot - The root URL of the application
+     * @param options - Configuration options for the ignitor
+     */
     constructor(appRoot, options = {}) {
         this.#appRoot = appRoot;
         this.#options = options;
@@ -58,6 +77,8 @@ export class Ignitor {
     }
     /**
      * Create an instance of AdonisJS application
+     *
+     * @param environment - The environment in which to create the app (web, console, test, repl)
      */
     createApp(environment) {
         debug('creating application instance');
@@ -68,6 +89,8 @@ export class Ignitor {
     }
     /**
      * Tap to access the application class instance.
+     *
+     * @param callback - Callback function to execute when app is created
      */
     tap(callback) {
         this.#tapCallbacks.add(callback);

package/build/src/ignitor/test.d.ts

@@ -1,18 +1,41 @@
-import { Ignitor } from './main.js';
-import type { ApplicationService } from '../types.js';
+import { type Ignitor } from './main.ts';
+import type { ApplicationService } from '../types.ts';
 /**
- * The Test runner process is used to start the tests runner process
+ * The Test runner process is used to start the tests runner process.
+ * It provides lifecycle hooks for configuring the test environment
+ * and running tests within the AdonisJS application context.
+ *
+ * @example
+ * const ignitor = new Ignitor()
+ * const testProcess = new TestRunnerProcess(ignitor)
+ *
+ * await testProcess
+ *   .configure((app) => {
+ *     // Configure test environment
+ *   })
+ *   .run(async (app) => {
+ *     // Run your tests
+ *   })
  */
 export declare class TestRunnerProcess {
     #private;
+    /**
+     * Creates a new test runner process instance
+     *
+     * @param ignitor - The ignitor instance used to create and manage the app
+     */
     constructor(ignitor: Ignitor);
     /**
      * Register a callback that runs after booting the AdonisJS app
      * and just before the provider's ready hook
+     *
+     * @param callback - Configuration callback function
      */
     configure(callback: (app: ApplicationService) => Promise<void> | void): this;
     /**
      * Runs a callback after starting the app
+     *
+     * @param callback - Test execution callback function
      */
     run(callback: (app: ApplicationService) => Promise<void> | void): Promise<void>;
 }

package/build/src/ignitor/test.js

@@ -7,7 +7,21 @@
  * file that was distributed with this source code.
  */
 /**
- * The Test runner process is used to start the tests runner process
+ * The Test runner process is used to start the tests runner process.
+ * It provides lifecycle hooks for configuring the test environment
+ * and running tests within the AdonisJS application context.
+ *
+ * @example
+ * const ignitor = new Ignitor()
+ * const testProcess = new TestRunnerProcess(ignitor)
+ *
+ * await testProcess
+ *   .configure((app) => {
+ *     // Configure test environment
+ *   })
+ *   .run(async (app) => {
+ *     // Run your tests
+ *   })
  */
 export class TestRunnerProcess {
     /**
@@ -19,12 +33,19 @@ export class TestRunnerProcess {
      * runs at the time of starting the app.
      */
     #configureCallback = () => { };
+    /**
+     * Creates a new test runner process instance
+     *
+     * @param ignitor - The ignitor instance used to create and manage the app
+     */
     constructor(ignitor) {
         this.#ignitor = ignitor;
     }
     /**
      * Register a callback that runs after booting the AdonisJS app
      * and just before the provider's ready hook
+     *
+     * @param callback - Configuration callback function
      */
     configure(callback) {
         this.#configureCallback = callback;
@@ -32,6 +53,8 @@ export class TestRunnerProcess {
     }
     /**
      * Runs a callback after starting the app
+     *
+     * @param callback - Test execution callback function
      */
     async run(callback) {
         const app = this.#ignitor.createApp('test');

package/build/src/test_utils/http.d.ts

@@ -1,16 +1,32 @@
-import type { TestUtils } from './main.js';
+import type { TestUtils } from './main.ts';
 import type { Server as NodeHttpsServer } from 'node:https';
-import { IncomingMessage, ServerResponse, Server as NodeHttpServer } from 'node:http';
+import { type IncomingMessage, type ServerResponse, type Server as NodeHttpServer } from 'node:http';
 /**
  * Http server utils are used to start the AdonisJS HTTP server
- * during testing
+ * during testing. It provides methods to start and stop the server
+ * for integration testing.
+ *
+ * @example
+ * const testUtils = new TestUtils(app)
+ * const httpUtils = testUtils.httpServer()
+ *
+ * const closeServer = await httpUtils.start()
+ * // Make HTTP requests to test endpoints
+ * await closeServer() // Clean up
  */
 export declare class HttpServerUtils {
     #private;
+    /**
+     * Creates a new HttpServerUtils instance
+     *
+     * @param utils - The test utils instance
+     */
     constructor(utils: TestUtils);
     /**
      * Testing hook to start the HTTP server to listen for new request.
      * The return value is a function to close the HTTP server.
+     *
+     * @param serverCallback - Optional callback to create custom HTTP server instance
      */
     start(serverCallback?: (handler: (req: IncomingMessage, res: ServerResponse) => any) => NodeHttpsServer | NodeHttpServer): Promise<() => Promise<void>>;
 }

package/build/src/test_utils/http.js

@@ -6,19 +6,38 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import debug from '../debug.js';
-import { createServer } from 'node:http';
+import debug from "../debug.js";
+import { createServer, } from 'node:http';
 /**
  * Http server utils are used to start the AdonisJS HTTP server
- * during testing
+ * during testing. It provides methods to start and stop the server
+ * for integration testing.
+ *
+ * @example
+ * const testUtils = new TestUtils(app)
+ * const httpUtils = testUtils.httpServer()
+ *
+ * const closeServer = await httpUtils.start()
+ * // Make HTTP requests to test endpoints
+ * await closeServer() // Clean up
  */
 export class HttpServerUtils {
+    /**
+     * Reference to the test utils instance
+     */
     #utils;
+    /**
+     * Creates a new HttpServerUtils instance
+     *
+     * @param utils - The test utils instance
+     */
     constructor(utils) {
         this.#utils = utils;
     }
     /**
      * Starts the http server a given host and port
+     *
+     * @param nodeHttpServer - The Node.js HTTP server instance
      */
     #listen(nodeHttpServer) {
         return new Promise((resolve, reject) => {
@@ -37,6 +56,8 @@ export class HttpServerUtils {
     /**
      * Testing hook to start the HTTP server to listen for new request.
      * The return value is a function to close the HTTP server.
+     *
+     * @param serverCallback - Optional callback to create custom HTTP server instance
      */
     async start(serverCallback) {
         const createHTTPServer = serverCallback || createServer;

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

@@ -1,11 +1,19 @@
 import Macroable from '@poppinss/macroable';
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { HttpServerUtils } from './http.js';
-import type { ApplicationService } from '../types.js';
-import { CookieClient, type HttpContext } from '../../modules/http/main.js';
+import { HttpServerUtils } from './http.ts';
+import type { ApplicationService } from '../types.ts';
+import { CookieClient, type HttpContext } from '../../modules/http/main.ts';
 /**
  * Test utils has a collection of helper methods to make testing
- * experience great for AdonisJS applications
+ * experience great for AdonisJS applications. It provides utilities
+ * for HTTP testing, context creation, and cookie handling.
+ *
+ * @example
+ * const testUtils = new TestUtils(app)
+ * await testUtils.boot()
+ *
+ * const ctx = await testUtils.createHttpContext()
+ * const httpUtils = testUtils.httpServer()
  */
 export declare class TestUtils extends Macroable {
     #private;
@@ -14,7 +22,15 @@ export declare class TestUtils extends Macroable {
      * Check if utils have been booted
      */
     get isBooted(): boolean;
+    /**
+     * Cookie client instance for handling cookies in tests
+     */
     cookies: CookieClient;
+    /**
+     * Creates a new TestUtils instance
+     *
+     * @param app - The application service instance
+     */
     constructor(app: ApplicationService);
     /**
      * Boot test utils. It requires the app to be booted
@@ -28,6 +44,8 @@ export declare class TestUtils extends Macroable {
     httpServer(): HttpServerUtils;
     /**
      * Create an instance of HTTP context for testing
+     *
+     * @param options - Options for creating HTTP context with custom req/res objects
      */
     createHttpContext(options?: {
         req?: IncomingMessage;