@adonisjs/core 6.19.0 → 7.0.0-next.1

package/build/commands/serve.js

@@ -12,16 +12,34 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { BaseCommand, flags } from '../modules/ace/main.js';
-import { detectAssetsBundler, importAssembler, importTypeScript } from '../src/internal_helpers.js';
+import { BaseCommand, flags } from "../modules/ace/main.js";
+import { importAssembler, importTypeScript } from "../src/utils.js";
 /**
  * Serve command is used to run the AdonisJS HTTP server during development. The
  * command under the hood runs the "bin/server.ts" file and watches for file
  * system changes
+ *
+ * @example
+ * ```
+ * ace serve
+ * ace serve --watch
+ * ace serve --hmr
+ * ace serve --poll
+ * ace serve --no-clear
+ * ```
  */
 export default class Serve extends BaseCommand {
+    /**
+     * The command name
+     */
     static commandName = 'serve';
+    /**
+     * The command description
+     */
     static description = 'Start the development HTTP server along with the file watcher to perform restarts on file change';
+    /**
+     * Help text for the command
+     */
     static help = [
         'Start the development server with file watcher using the following command.',
         '```',
@@ -39,11 +57,16 @@ export default class Serve extends BaseCommand {
         '{{ binaryName }} serve --assets-args="--debug --base=/public"',
         '```',
     ];
+    /**
+     * Command options configuration
+     */
     static options = {
         staysAlive: true,
     };
     /**
      * Log a development dependency is missing
+     *
+     * @param dependency - The name of the missing dependency
      */
     #logMissingDevelopmentDependency(dependency) {
         this.logger.error([
@@ -54,22 +77,6 @@ export default class Serve extends BaseCommand {
             'If you are running your application in production, then use "node bin/server.js" command to start the HTTP server',
         ].join('\n'));
     }
-    /**
-     * Returns the assets bundler config
-     */
-    async #getAssetsBundlerConfig() {
-        const assetsBundler = await detectAssetsBundler(this.app);
-        return assetsBundler
-            ? {
-                enabled: this.assets === false ? false : true,
-                driver: assetsBundler.name,
-                cmd: assetsBundler.devServer.command,
-                args: (assetsBundler.devServer.args || []).concat(this.assetsArgs || []),
-            }
-            : {
-                enabled: false,
-            };
-    }
     /**
      * Runs the HTTP server
      */
@@ -90,18 +97,14 @@ export default class Serve extends BaseCommand {
             clearScreen: this.clear === false ? false : true,
             nodeArgs: this.parsed.nodeArgs,
             scriptArgs: [],
-            assets: await this.#getAssetsBundlerConfig(),
             metaFiles: this.app.rcFile.metaFiles,
-            hooks: {
-                onDevServerStarted: this.app.rcFile.hooks?.onDevServerStarted,
-                onSourceFileChanged: this.app.rcFile.hooks?.onSourceFileChanged,
-            },
+            hooks: this.app.rcFile.hooks,
         });
         /**
          * Share command logger with assembler, so that CLI flags like --no-ansi has
          * similar impact for assembler logs as well.
          */
-        this.devServer.setLogger(this.logger);
+        this.devServer.ui.logger = this.logger;
         /**
          * Exit command when the dev server is closed
          */
@@ -116,20 +119,20 @@ export default class Serve extends BaseCommand {
             this.exitCode = 1;
             this.terminate();
         });
+        const ts = await importTypeScript(this.app);
+        if (!ts) {
+            this.#logMissingDevelopmentDependency('typescript');
+            this.exitCode = 1;
+            return;
+        }
         /**
          * Start the development server
          */
         if (this.watch) {
-            const ts = await importTypeScript(this.app);
-            if (!ts) {
-                this.#logMissingDevelopmentDependency('typescript');
-                this.exitCode = 1;
-                return;
-            }
             await this.devServer.startAndWatch(ts, { poll: this.poll || false });
         }
         else {
-            await this.devServer.start();
+            await this.devServer.start(ts);
         }
     }
 }
@@ -152,15 +155,3 @@ __decorate([
         default: true,
     })
 ], Serve.prototype, "clear", void 0);
-__decorate([
-    flags.boolean({
-        description: 'Start assets bundler dev server',
-        showNegatedVariantInHelp: true,
-        default: true,
-    })
-], Serve.prototype, "assets", void 0);
-__decorate([
-    flags.array({
-        description: 'Define CLI arguments to pass to the assets bundler',
-    })
-], Serve.prototype, "assetsArgs", void 0);

package/build/commands/test.d.ts

@@ -1,32 +1,93 @@
 import type { TestRunner } from '@adonisjs/assembler';
-import type { CommandOptions } from '../types/ace.js';
-import { BaseCommand } from '../modules/ace/main.js';
+import type { CommandOptions } from '../types/ace.ts';
+import { BaseCommand } from '../modules/ace/main.ts';
 /**
- * Test command is used to run tests with optional file watcher. Under the
- * hood, we run "bin/test.js" file.
+ * Command to run application tests using the Japa test runner.
+ * Supports filtering tests by suites, files, tags, groups, and individual tests.
+ * Can run in watch mode to automatically re-run tests when files change.
+ *
+ * @example
+ * ```
+ * ace test
+ * ace test unit integration
+ * ace test --watch
+ * ace test --files=user.spec.ts
+ * ace test --tags=slow --groups="User tests"
+ * ace test --reporters=spec,dot
+ * ace test --timeout=5000 --retries=2
+ * ```
  */
 export default class Test extends BaseCommand {
     #private;
+    /**
+     * The command name
+     */
     static commandName: string;
+    /**
+     * The command description
+     */
     static description: string;
+    /**
+     * Command options configuration.
+     * Allows unknown flags to be passed to Japa and keeps the process alive.
+     */
     static options: CommandOptions;
+    /**
+     * The test runner instance from the assembler package
+     */
     testsRunner: TestRunner;
+    /**
+     * Test suite names to run. When provided, only tests from the specified suites will be executed
+     */
     suites?: string[];
+    /**
+     * Filter tests by filename patterns
+     */
     files?: string[];
+    /**
+     * Filter tests by tags
+     */
     tags?: string[];
+    /**
+     * Filter tests by parent group title
+     */
     groups?: string[];
+    /**
+     * Filter tests by test title
+     */
     tests?: string[];
+    /**
+     * Specify one or more test reporters to use for output formatting
+     */
     reporters?: string[];
+    /**
+     * Enable watch mode to automatically re-run tests when files change
+     */
     watch?: boolean;
+    /**
+     * Use polling instead of native filesystem events to detect file changes
+     */
     poll?: boolean;
+    /**
+     * Default timeout in milliseconds for all tests
+     */
     timeout?: number;
+    /**
+     * Default number of retries for failed tests
+     */
     retries?: number;
+    /**
+     * Execute only tests that failed during the last run
+     */
     failed?: boolean;
+    /**
+     * Clear the terminal for new logs after file change in watch mode
+     */
     clear?: boolean;
-    assets?: boolean;
-    assetsArgs?: string[];
     /**
-     * Runs tests
+     * Execute the test command. Sets up the test runner with all configured options
+     * and filters, then runs tests either once or in watch mode. Handles missing
+     * dependencies and properly configures the test environment.
      */
     run(): Promise<void>;
 }

package/build/commands/test.js

@@ -12,21 +12,46 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { BaseCommand, flags, args } from '../modules/ace/main.js';
-import { detectAssetsBundler, importAssembler, importTypeScript } from '../src/internal_helpers.js';
+import { BaseCommand, flags, args } from "../modules/ace/main.js";
+import { importAssembler, importTypeScript } from "../src/utils.js";
 /**
- * Test command is used to run tests with optional file watcher. Under the
- * hood, we run "bin/test.js" file.
+ * Command to run application tests using the Japa test runner.
+ * Supports filtering tests by suites, files, tags, groups, and individual tests.
+ * Can run in watch mode to automatically re-run tests when files change.
+ *
+ * @example
+ * ```
+ * ace test
+ * ace test unit integration
+ * ace test --watch
+ * ace test --files=user.spec.ts
+ * ace test --tags=slow --groups="User tests"
+ * ace test --reporters=spec,dot
+ * ace test --timeout=5000 --retries=2
+ * ```
  */
 export default class Test extends BaseCommand {
+    /**
+     * The command name
+     */
     static commandName = 'test';
+    /**
+     * The command description
+     */
     static description = 'Run tests along with the file watcher to re-run tests on file change';
+    /**
+     * Command options configuration.
+     * Allows unknown flags to be passed to Japa and keeps the process alive.
+     */
     static options = {
         allowUnknownFlags: true,
         staysAlive: true,
     };
     /**
-     * Log a development dependency is missing
+     * Log an error message when a required development dependency is missing.
+     * Provides helpful instructions for resolving the issue.
+     *
+     * @param dependency - The name of the missing dependency package
      */
     #logMissingDevelopmentDependency(dependency) {
         this.logger.error([
@@ -38,7 +63,10 @@ export default class Test extends BaseCommand {
         ].join('\n'));
     }
     /**
-     * Collection of unknown flags to pass to Japa
+     * Collect unknown flags and format them to pass to the Japa test runner.
+     * Handles boolean flags, arrays, and single values appropriately.
+     *
+     * @returns Array of formatted command-line arguments for Japa
      */
     #getPassthroughFlags() {
         return this.parsed.unknownFlags
@@ -61,23 +89,9 @@ export default class Test extends BaseCommand {
             .flat(2);
     }
     /**
-     * Returns the assets bundler config
-     */
-    async #getAssetsBundlerConfig() {
-        const assetsBundler = await detectAssetsBundler(this.app);
-        return assetsBundler
-            ? {
-                enabled: this.assets === false ? false : true,
-                driver: assetsBundler.name,
-                cmd: assetsBundler.devServer.command,
-                args: (assetsBundler.devServer.args || []).concat(this.assetsArgs || []),
-            }
-            : {
-                enabled: false,
-            };
-    }
-    /**
-     * Runs tests
+     * Execute the test command. Sets up the test runner with all configured options
+     * and filters, then runs tests either once or in watch mode. Handles missing
+     * dependencies and properly configures the test environment.
      */
     async run() {
         process.env.NODE_ENV = 'test';
@@ -91,7 +105,6 @@ export default class Test extends BaseCommand {
             clearScreen: this.clear === false ? false : true,
             nodeArgs: this.parsed.nodeArgs,
             scriptArgs: this.#getPassthroughFlags(),
-            assets: await this.#getAssetsBundlerConfig(),
             filters: {
                 suites: this.suites,
                 files: this.files,
@@ -112,13 +125,14 @@ export default class Test extends BaseCommand {
             env: {
                 NODE_ENV: 'test',
             },
+            hooks: this.app.rcFile.hooks,
             metaFiles: this.app.rcFile.metaFiles,
         });
         /**
          * Share command logger with assembler, so that CLI flags like --no-ansi has
          * similar impact for assembler logs as well.
          */
-        this.testsRunner.setLogger(this.logger);
+        this.testsRunner.ui.logger = this.logger;
         /**
          * Exit command when the test runner is closed
          */
@@ -193,15 +207,3 @@ __decorate([
         default: true,
     })
 ], Test.prototype, "clear", void 0);
-__decorate([
-    flags.boolean({
-        description: 'Start assets bundler dev server.',
-        showNegatedVariantInHelp: true,
-        default: true,
-    })
-], Test.prototype, "assets", void 0);
-__decorate([
-    flags.array({
-        description: 'Define CLI arguments to pass to the assets bundler',
-    })
-], Test.prototype, "assetsArgs", void 0);

package/build/factories/core/ace.d.ts

@@ -1,10 +1,37 @@
-import { Ignitor } from '../../src/ignitor/main.js';
-import type { IgnitorOptions } from '../../src/types.js';
-import type { Kernel } from '../../modules/ace/kernel.js';
+import { Ignitor } from '../../src/ignitor/main.ts';
+import type { IgnitorOptions } from '../../src/types.ts';
+import type { Kernel } from '../../modules/ace/kernel.ts';
 /**
- * Creates an instance of Ace kernel
+ * Factory for creating and configuring Ace command kernel instances.
+ * This factory provides a convenient way to create Ace kernels either from
+ * an existing Ignitor instance or by creating a new one from scratch.
+ *
+ * @example
+ * ```ts
+ * // Create from URL
+ * const aceFactory = new AceFactory()
+ * const kernel = await aceFactory.make(new URL('../', import.meta.url))
+ *
+ * // Create from existing ignitor
+ * const ignitor = new Ignitor(appRoot)
+ * const kernel = await aceFactory.make(ignitor)
+ *
+ * // Run commands
+ * await kernel.handle(['make:controller', 'UserController'])
+ * ```
  */
 export declare class AceFactory {
+    /**
+     * Create an Ace kernel from an existing Ignitor instance
+     *
+     * @param ignitor - Existing Ignitor instance
+     */
     make(ignitor: Ignitor): Promise<Kernel>;
+    /**
+     * Create an Ace kernel from application root URL
+     *
+     * @param appRoot - Application root directory URL
+     * @param options - Optional Ignitor configuration options
+     */
     make(appRoot: URL, options?: IgnitorOptions): Promise<Kernel>;
 }

package/build/factories/core/ace.js

@@ -6,11 +6,27 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import { IgnitorFactory } from './ignitor.js';
-import { Ignitor } from '../../src/ignitor/main.js';
-import { createAceKernel } from '../../modules/ace/create_kernel.js';
+import { IgnitorFactory } from "./ignitor.js";
+import { Ignitor } from "../../src/ignitor/main.js";
+import { createAceKernel } from "../../modules/ace/create_kernel.js";
 /**
- * Creates an instance of Ace kernel
+ * Factory for creating and configuring Ace command kernel instances.
+ * This factory provides a convenient way to create Ace kernels either from
+ * an existing Ignitor instance or by creating a new one from scratch.
+ *
+ * @example
+ * ```ts
+ * // Create from URL
+ * const aceFactory = new AceFactory()
+ * const kernel = await aceFactory.make(new URL('../', import.meta.url))
+ *
+ * // Create from existing ignitor
+ * const ignitor = new Ignitor(appRoot)
+ * const kernel = await aceFactory.make(ignitor)
+ *
+ * // Run commands
+ * await kernel.handle(['make:controller', 'UserController'])
+ * ```
  */
 export class AceFactory {
     async make(ignitorOrAppRoot, options) {

package/build/factories/core/ignitor.d.ts

@@ -1,33 +1,104 @@
-import { Ignitor } from '../../src/ignitor/main.js';
-import type { ApplicationService, IgnitorOptions } from '../../src/types.js';
+import { Ignitor } from '../../src/ignitor/main.ts';
+import type { ApplicationService, IgnitorOptions } from '../../src/types.ts';
 type FactoryParameters = {
     rcFileContents: Record<string, any>;
     config: Record<string, any>;
 };
 /**
- * Ignitor factory creates an instance of the AdonisJS ignitor
+ * Factory for creating and configuring AdonisJS Ignitor instances.
+ * This factory provides a fluent API to set up applications with core providers,
+ * configurations, and preload actions for testing and development scenarios.
+ *
+ * @example
+ * ```ts
+ * const ignitor = new IgnitorFactory()
+ *   .withCoreProviders()
+ *   .withCoreConfig()
+ *   .preload((app) => {
+ *     // Custom initialization logic
+ *   })
+ *   .create(new URL('../', import.meta.url))
+ *
+ * const app = ignitor.createApp('web')
+ * await app.boot()
+ * ```
  */
 export declare class IgnitorFactory {
     #private;
     /**
-     * Define preload actions to run.
+     * Define preload actions to run during application initialization.
+     * These actions are executed after the application is booted.
+     *
+     * @param action - Function to execute during preload phase
+     *
+     * @example
+     * ```ts
+     * factory.preload((app) => {
+     *   // Register custom bindings
+     *   app.container.bind('customService', () => new CustomService())
+     * })
+     * ```
      */
     preload(action: (app: ApplicationService) => void | Promise<void>): this;
     /**
-     * Merge custom factory parameters
+     * Merge custom factory parameters with existing ones.
+     * This allows you to customize RC file contents and application configuration.
+     *
+     * @param params - Parameters to merge
+     * @param params.config - Application configuration to merge
+     * @param params.rcFileContents - RC file contents to merge
+     *
+     * @example
+     * ```ts
+     * factory.merge({
+     *   config: {
+     *     database: { connection: 'mysql' }
+     *   },
+     *   rcFileContents: {
+     *     commands: ['./commands/CustomCommand']
+     *   }
+     * })
+     * ```
      */
     merge(params: Partial<FactoryParameters>): this;
     /**
-     * Load core provider when booting the app
+     * Include core AdonisJS providers when booting the application.
+     * This adds essential providers like app, hash, and REPL providers.
+     *
+     * @example
+     * ```ts
+     * const ignitor = new IgnitorFactory()
+     *   .withCoreProviders()
+     *   .create(appRoot)
+     * ```
      */
     withCoreProviders(): this;
     /**
-     * Merge default config for the core features. A shallow merge
-     * is performed.
+     * Merge default configuration for core AdonisJS features.
+     * This includes configurations for HTTP, hash, logger, and bodyparser.
+     * A shallow merge is performed with existing config.
+     *
+     * @example
+     * ```ts
+     * const ignitor = new IgnitorFactory()
+     *   .withCoreConfig()
+     *   .create(appRoot)
+     * ```
      */
     withCoreConfig(): this;
     /**
-     * Create ignitor instance
+     * Create a configured Ignitor instance with all specified parameters.
+     *
+     * @param appRoot - Application root directory URL
+     * @param options - Optional Ignitor configuration options
+     *
+     * @example
+     * ```ts
+     * const ignitor = new IgnitorFactory()
+     *   .withCoreConfig()
+     *   .withCoreProviders()
+     *   .create(new URL('../', import.meta.url))
+     * ```
      */
     create(appRoot: URL, options?: IgnitorOptions): Ignitor;
 }