@adonisjs/core 6.19.0 → 7.0.0-next.1

package/build/modules/ace/codemods.js

@@ -6,13 +6,32 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import { slash } from '@poppinss/utils';
 import { EventEmitter } from 'node:events';
 import { EnvEditor } from '@adonisjs/env/editor';
+import stringHelpers from "../../src/helpers/string.js";
 /**
- * Codemods to modify AdonisJS source files. The codemod APIs relies on
- * "@adonisjs/assembler" package and it must be installed as a dependency
- * inside user application.
+ * Codemods class for programmatically modifying AdonisJS source files.
+ * This class provides APIs to modify configuration files, register middleware,
+ * generate stubs, and install packages.
+ *
+ * The codemod APIs rely on the "@adonisjs/assembler" package, which must be
+ * installed as a dependency in the user application.
+ *
+ * @example
+ * ```ts
+ * const codemods = new Codemods(app, logger)
+ *
+ * // Generate a controller from a stub
+ * await codemods.makeUsingStub(stubsRoot, 'controller.stub', {
+ *   filename: 'UserController',
+ *   entity: { name: 'User' }
+ * })
+ *
+ * // Install packages
+ * await codemods.installPackages([
+ *   { name: '@adonisjs/lucid', isDevDependency: false }
+ * ])
+ * ```
  */
 export class Codemods extends EventEmitter {
     /**
@@ -79,7 +98,22 @@ export class Codemods extends EventEmitter {
         }
     }
     /**
-     * Define one or more environment variables
+     * Define one or more environment variables in the .env file
+     *
+     * @param environmentVariables - Key-value pairs of environment variables
+     * @param options - Configuration options
+     * @param options.omitFromExample - Keys to exclude from .env.example file
+     *
+     * @example
+     * ```ts
+     * await codemods.defineEnvVariables({
+     *   DB_CONNECTION: 'mysql',
+     *   DB_HOST: 'localhost',
+     *   SECRET_KEY: 'abc123'
+     * }, {
+     *   omitFromExample: ['SECRET_KEY']
+     * })
+     * ```
      */
     async defineEnvVariables(environmentVariables, options) {
         const editor = new EnvEditor(this.#app.appRoot);
@@ -92,8 +126,17 @@ export class Codemods extends EventEmitter {
         this.#cliLogger.action('update .env file').succeeded();
     }
     /**
-     * Returns the TsMorph project instance
-     * See https://ts-morph.com/
+     * Returns the TsMorph project instance for advanced AST manipulations.
+     * See https://ts-morph.com/ for documentation.
+     *
+     * @example
+     * ```ts
+     * const project = await codemods.getTsMorphProject()
+     * if (project) {
+     *   const sourceFile = project.getSourceFile('app/controllers/user_controller.ts')
+     *   // Perform advanced AST operations
+     * }
+     * ```
      */
     async getTsMorphProject() {
         const transformer = await this.#getCodeTransformer();
@@ -220,13 +263,30 @@ export class Codemods extends EventEmitter {
         }
     }
     /**
-     * Generate the stub
+     * Generate a file using a stub template
+     *
+     * @param stubsRoot - Root directory containing stub files
+     * @param stubPath - Path to the specific stub file
+     * @param stubState - Template variables for stub generation
+     *
+     * @example
+     * ```ts
+     * const result = await codemods.makeUsingStub(
+     *   './stubs',
+     *   'controller.stub',
+     *   {
+     *     filename: 'UserController',
+     *     entity: { name: 'User', modelName: 'User' },
+     *     resourceful: true
+     *   }
+     * )
+     * ```
      */
     async makeUsingStub(stubsRoot, stubPath, stubState) {
         const stubs = await this.#app.stubs.create();
         const stub = await stubs.build(stubPath, { source: stubsRoot });
         const output = await stub.generate({ force: this.overwriteExisting, ...stubState });
-        const entityFileName = slash(this.#app.relativePath(output.destination));
+        const entityFileName = stringHelpers.toUnixSlash(this.#app.relativePath(output.destination));
         const result = { ...output, relativeFileName: entityFileName };
         if (output.status === 'skipped') {
             this.#cliLogger.action(`create ${entityFileName}`).skipped(output.skipReason);
@@ -244,7 +304,7 @@ export class Codemods extends EventEmitter {
      * this.installPackages([{ name: '@adonisjs/lucid@next', isDevDependency: false }])
      * ```
      */
-    async installPackages(packages) {
+    async installPackages(packages, packageManager) {
         const transformer = await this.#getCodeTransformer();
         const appPath = this.#app.makePath();
         const colors = this.#cliLogger.getColors();
@@ -254,30 +314,37 @@ export class Codemods extends EventEmitter {
             this.#cliLogger.warning('Cannot install packages. Install "@adonisjs/assembler" or manually install following packages');
             this.#cliLogger.log(`devDependencies: ${devDependencies.join(',')}`);
             this.#cliLogger.log(`dependencies: ${dependencies.join(',')}`);
-            return;
+            return false;
         }
-        const packageManager = await transformer.detectPackageManager(appPath);
-        const spinner = this.#cliLogger.await(`installing dependencies using ${packageManager || 'npm'} `);
+        packageManager = packageManager ?? (await transformer.detectPackageManager(appPath)) ?? 'npm';
+        const spinner = this.#cliLogger.await(`installing dependencies using ${packageManager} `);
         const silentLogs = !this.verboseInstallOutput;
         if (silentLogs) {
             spinner.start();
         }
         try {
-            await transformer.installPackage(dependencies, {
-                cwd: appPath,
-                silent: silentLogs,
-            });
-            await transformer.installPackage(devDependencies, {
-                dev: true,
-                cwd: appPath,
-                silent: silentLogs,
-            });
+            if (dependencies.length) {
+                await transformer.installPackage(dependencies, {
+                    cwd: appPath,
+                    silent: silentLogs,
+                    packageManager,
+                });
+            }
+            if (devDependencies.length) {
+                await transformer.installPackage(devDependencies, {
+                    dev: true,
+                    cwd: appPath,
+                    silent: silentLogs,
+                    packageManager,
+                });
+            }
             if (silentLogs) {
                 spinner.stop();
             }
             this.#cliLogger.success('Packages installed');
             this.#cliLogger.log(devDependencies.map((dependency) => `    ${colors.dim('dev')} ${dependency} `).join('\n'));
             this.#cliLogger.log(dependencies.map((dependency) => `    ${colors.dim('prod')} ${dependency} `).join('\n'));
+            return true;
         }
         catch (error) {
             if (silentLogs) {
@@ -286,6 +353,7 @@ export class Codemods extends EventEmitter {
             }
             this.#cliLogger.fatal(error);
             this.emit('error', error);
+            return false;
         }
     }
     /**

package/build/modules/ace/commands.d.ts

@@ -1,10 +1,24 @@
 import { BaseCommand as AceBaseCommand, ListCommand as AceListCommand } from '@adonisjs/ace';
-import { Kernel } from './kernel.js';
-import type { ApplicationService } from '../../src/types.js';
-import type { CommandOptions, ParsedOutput, UIPrimitives } from '../../types/ace.js';
+import { type Kernel } from './kernel.ts';
+import type { ApplicationService } from '../../src/types.ts';
+import type { CommandOptions, ParsedOutput, UIPrimitives } from '../../types/ace.ts';
 /**
- * The base command to create custom ace commands. The AdonisJS base commands
- * receives the application instance
+ * The base command class for creating custom Ace commands in AdonisJS applications.
+ * This class extends the base Ace command with AdonisJS-specific functionality like
+ * dependency injection and application lifecycle management.
+ *
+ * @example
+ * ```ts
+ * export default class MakeUser extends BaseCommand {
+ *   static commandName = 'make:user'
+ *   static description = 'Create a new user'
+ *
+ *   async run() {
+ *     this.logger.info('Creating user...')
+ *     // Command implementation
+ *   }
+ * }
+ * ```
  */
 export declare class BaseCommand extends AceBaseCommand {
     app: ApplicationService;
@@ -14,7 +28,17 @@ export declare class BaseCommand extends AceBaseCommand {
     get startApp(): boolean | undefined;
     constructor(app: ApplicationService, kernel: Kernel, parsed: ParsedOutput, ui: UIPrimitives, prompt: Kernel['prompt']);
     /**
-     * Creates the codemods module to modify source files
+     * Creates the codemods module to modify source files programmatically.
+     * This method provides access to AST-based code transformations.
+     *
+     * @example
+     * ```ts
+     * const codemods = await this.createCodemods()
+     * await codemods.makeUsingStub(stubsRoot, 'controller.stub', {
+     *   filename: 'UserController',
+     *   entity: { name: 'User' }
+     * })
+     * ```
      */
     createCodemods(): Promise<import("./codemods.js").Codemods>;
     /**
@@ -39,19 +63,29 @@ export declare class BaseCommand extends AceBaseCommand {
      */
     completed?(..._: any[]): any;
     /**
-     * Executes the command
+     * Executes the lifecycle hooks and the run method from the command
      */
     exec(): Promise<any>;
     /**
-     * Terminate the app. A command should prefer calling this method
-     * over the "app.terminate", because this method only triggers
-     * app termination when the current command is in the charge
-     * of the process.
+     * Terminate the application gracefully. This method should be preferred over
+     * calling `app.terminate()` directly as it only triggers termination when
+     * the current command is the main command responsible for the process.
+     *
+     * @example
+     * ```ts
+     * export default class SomeCommand extends BaseCommand {
+     *   async run() {
+     *     // Do some work
+     *     await this.terminate()
+     *   }
+     * }
+     * ```
      */
     terminate(): Promise<void>;
 }
 /**
- * The List command is used to display a list of commands
+ * The List command is used to display a list of available commands.
+ * This command extends the base Ace ListCommand with AdonisJS-specific functionality.
  */
 export declare class ListCommand extends AceListCommand implements BaseCommand {
     app: ApplicationService;
@@ -61,7 +95,8 @@ export declare class ListCommand extends AceListCommand implements BaseCommand {
     get startApp(): boolean | undefined;
     constructor(app: ApplicationService, kernel: Kernel, parsed: ParsedOutput, ui: UIPrimitives, prompt: Kernel['prompt']);
     /**
-     * Creates the codemods module to modify source files
+     * Creates the codemods module to modify source files programmatically.
+     * This method provides access to AST-based code transformations.
      */
     createCodemods(): Promise<import("./codemods.js").Codemods>;
     /**

package/build/modules/ace/commands.js

@@ -8,8 +8,22 @@
  */
 import { BaseCommand as AceBaseCommand, ListCommand as AceListCommand } from '@adonisjs/ace';
 /**
- * The base command to create custom ace commands. The AdonisJS base commands
- * receives the application instance
+ * The base command class for creating custom Ace commands in AdonisJS applications.
+ * This class extends the base Ace command with AdonisJS-specific functionality like
+ * dependency injection and application lifecycle management.
+ *
+ * @example
+ * ```ts
+ * export default class MakeUser extends BaseCommand {
+ *   static commandName = 'make:user'
+ *   static description = 'Create a new user'
+ *
+ *   async run() {
+ *     this.logger.info('Creating user...')
+ *     // Command implementation
+ *   }
+ * }
+ * ```
  */
 export class BaseCommand extends AceBaseCommand {
     app;
@@ -27,7 +41,17 @@ export class BaseCommand extends AceBaseCommand {
         this.kernel = kernel;
     }
     /**
-     * Creates the codemods module to modify source files
+     * Creates the codemods module to modify source files programmatically.
+     * This method provides access to AST-based code transformations.
+     *
+     * @example
+     * ```ts
+     * const codemods = await this.createCodemods()
+     * await codemods.makeUsingStub(stubsRoot, 'controller.stub', {
+     *   filename: 'UserController',
+     *   entity: { name: 'User' }
+     * })
+     * ```
      */
     async createCodemods() {
         const { Codemods } = await import('./codemods.js');
@@ -38,7 +62,7 @@ export class BaseCommand extends AceBaseCommand {
         return codemods;
     }
     /**
-     * Executes the command
+     * Executes the lifecycle hooks and the run method from the command
      */
     async exec() {
         this.hydrate();
@@ -72,10 +96,19 @@ export class BaseCommand extends AceBaseCommand {
         return this.result;
     }
     /**
-     * Terminate the app. A command should prefer calling this method
-     * over the "app.terminate", because this method only triggers
-     * app termination when the current command is in the charge
-     * of the process.
+     * Terminate the application gracefully. This method should be preferred over
+     * calling `app.terminate()` directly as it only triggers termination when
+     * the current command is the main command responsible for the process.
+     *
+     * @example
+     * ```ts
+     * export default class SomeCommand extends BaseCommand {
+     *   async run() {
+     *     // Do some work
+     *     await this.terminate()
+     *   }
+     * }
+     * ```
      */
     async terminate() {
         if (this.kernel.getMainCommand() === this) {
@@ -84,7 +117,8 @@ export class BaseCommand extends AceBaseCommand {
     }
 }
 /**
- * The List command is used to display a list of commands
+ * The List command is used to display a list of available commands.
+ * This command extends the base Ace ListCommand with AdonisJS-specific functionality.
  */
 export class ListCommand extends AceListCommand {
     app;
@@ -102,7 +136,8 @@ export class ListCommand extends AceListCommand {
         this.kernel = kernel;
     }
     /**
-     * Creates the codemods module to modify source files
+     * Creates the codemods module to modify source files programmatically.
+     * This method provides access to AST-based code transformations.
      */
     async createCodemods() {
         const { Codemods } = await import('./codemods.js');

package/build/modules/ace/create_kernel.d.ts

@@ -1,12 +1,23 @@
-import { Kernel } from './main.js';
-import type { ApplicationService } from '../../src/types.js';
+import { Kernel } from './main.ts';
+import type { ApplicationService } from '../../src/types.ts';
 /**
- * We abstract the logic for creating the ace kernel in this
- * file. So that both the "console" environment and rest
- * of the environments can configure and use ace.
+ * Create and configure an Ace command kernel for AdonisJS applications.
+ * This function abstracts the kernel setup logic and can be used in different
+ * environments with appropriate configurations.
  *
- * - In console environment, ace manages the lifecycle of the process
- * - In other environments, ace can be pulled from the container to
- * run commands
+ * - In console environment, Ace manages the lifecycle of the process
+ * - In other environments, Ace can be pulled from the container to run commands
+ *
+ * @param app - The AdonisJS application service instance
+ * @param commandName - Optional specific command name for optimized loading
+ *
+ * @example
+ * ```ts
+ * const app = new Application(new URL('../', import.meta.url))
+ * const kernel = createAceKernel(app)
+ *
+ * // Run a specific command
+ * await kernel.handle(['make:controller', 'UserController'])
+ * ```
  */
 export declare function createAceKernel(app: ApplicationService, commandName?: string): Kernel;

package/build/modules/ace/create_kernel.js

@@ -6,16 +6,27 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import { Kernel } from './main.js';
-import { FsLoader, HelpCommand } from '../../modules/ace/main.js';
+import { Kernel } from "./main.js";
+import { FsLoader, HelpCommand } from "../../modules/ace/main.js";
 /**
- * We abstract the logic for creating the ace kernel in this
- * file. So that both the "console" environment and rest
- * of the environments can configure and use ace.
+ * Create and configure an Ace command kernel for AdonisJS applications.
+ * This function abstracts the kernel setup logic and can be used in different
+ * environments with appropriate configurations.
  *
- * - In console environment, ace manages the lifecycle of the process
- * - In other environments, ace can be pulled from the container to
- * run commands
+ * - In console environment, Ace manages the lifecycle of the process
+ * - In other environments, Ace can be pulled from the container to run commands
+ *
+ * @param app - The AdonisJS application service instance
+ * @param commandName - Optional specific command name for optimized loading
+ *
+ * @example
+ * ```ts
+ * const app = new Application(new URL('../', import.meta.url))
+ * const kernel = createAceKernel(app)
+ *
+ * // Run a specific command
+ * await kernel.handle(['make:controller', 'UserController'])
+ * ```
  */
 export function createAceKernel(app, commandName) {
     const kernel = new Kernel(app);

package/build/modules/ace/kernel.d.ts

@@ -1,11 +1,25 @@
 import { Kernel as AceKernel } from '@adonisjs/ace';
-import { BaseCommand } from './commands.js';
-import type { ApplicationService } from '../../src/types.js';
+import { type BaseCommand } from './commands.ts';
+import type { ApplicationService } from '../../src/types.ts';
 /**
- * The base command to create custom ace commands. The AdonisJS base commands
- * receives the application instance
+ * The Ace command kernel for AdonisJS applications. This kernel extends the base
+ * Ace kernel with AdonisJS-specific functionality like dependency injection and
+ * application lifecycle management.
+ *
+ * @example
+ * ```ts
+ * const app = new Application(new URL('../', import.meta.url))
+ * const kernel = new Kernel(app)
+ *
+ * await kernel.handle(['make:controller', 'UserController'])
+ * ```
  */
 export declare class Kernel extends AceKernel<typeof BaseCommand> {
     app: ApplicationService;
+    /**
+     * Create a new Ace kernel instance
+     *
+     * @param app - The AdonisJS application instance
+     */
     constructor(app: ApplicationService);
 }

package/build/modules/ace/kernel.js

@@ -7,13 +7,27 @@
  * file that was distributed with this source code.
  */
 import { Kernel as AceKernel } from '@adonisjs/ace';
-import { ListCommand } from './commands.js';
+import { ListCommand } from "./commands.js";
 /**
- * The base command to create custom ace commands. The AdonisJS base commands
- * receives the application instance
+ * The Ace command kernel for AdonisJS applications. This kernel extends the base
+ * Ace kernel with AdonisJS-specific functionality like dependency injection and
+ * application lifecycle management.
+ *
+ * @example
+ * ```ts
+ * const app = new Application(new URL('../', import.meta.url))
+ * const kernel = new Kernel(app)
+ *
+ * await kernel.handle(['make:controller', 'UserController'])
+ * ```
  */
 export class Kernel extends AceKernel {
     app;
+    /**
+     * Create a new Ace kernel instance
+     *
+     * @param app - The AdonisJS application instance
+     */
     constructor(app) {
         super(ListCommand, {
             create: async (command, parsedOutput, $kernel) => {

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

@@ -1,3 +1,3 @@
-export { Kernel } from './kernel.js';
-export { BaseCommand, ListCommand } from './commands.js';
-export { args, flags, errors, Parser, FsLoader, ListLoader, cliHelpers, HelpCommand, IndexGenerator, } from '@adonisjs/ace';
+export { Kernel } from './kernel.ts';
+export { BaseCommand, ListCommand } from './commands.ts';
+export { args, flags, errors, Parser, FsLoader, ListLoader, cliHelpers, HelpCommand, IndexGenerator, tracingChannels, } from '@adonisjs/ace';

package/build/modules/ace/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 { Kernel } from './kernel.js';
-export { BaseCommand, ListCommand } from './commands.js';
-export { args, flags, errors, Parser, FsLoader, ListLoader, cliHelpers, HelpCommand, IndexGenerator, } from '@adonisjs/ace';
+export { Kernel } from "./kernel.js";
+export { BaseCommand, ListCommand } from "./commands.js";
+export { args, flags, errors, Parser, FsLoader, ListLoader, cliHelpers, HelpCommand, IndexGenerator, tracingChannels, } from '@adonisjs/ace';

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

@@ -1,8 +1,29 @@
-import { ConsoleDumpConfig } from '@poppinss/dumper/console/types';
-import { HTMLDumpConfig } from '@poppinss/dumper/html/types';
+import { type ConsoleDumpConfig } from '@poppinss/dumper/console/types';
+import { type HTMLDumpConfig } from '@poppinss/dumper/html/types';
 /**
- * Define config for the dumper service exported by
- * the "@adonisjs/core/services/dumper" module
+ * Define configuration for the dumper service exported by the
+ * "@adonisjs/core/services/dumper" module. This function allows
+ * you to customize HTML and console output formatting options.
+ *
+ * @param dumperConfig - Configuration object with HTML and console options
+ * @param dumperConfig.html - HTML output formatting configuration
+ * @param dumperConfig.console - Console output formatting configuration
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   html: {
+ *     showHidden: true,
+ *     depth: 5,
+ *     colors: true
+ *   },
+ *   console: {
+ *     showHidden: false,
+ *     depth: 3,
+ *     collapse: ['Date', 'DateTime']
+ *   }
+ * })
+ * ```
  */
 export declare function defineConfig(dumperConfig: Partial<{
     html: HTMLDumpConfig;

package/build/modules/dumper/define_config.js

@@ -7,8 +7,29 @@
  * file that was distributed with this source code.
  */
 /**
- * Define config for the dumper service exported by
- * the "@adonisjs/core/services/dumper" module
+ * Define configuration for the dumper service exported by the
+ * "@adonisjs/core/services/dumper" module. This function allows
+ * you to customize HTML and console output formatting options.
+ *
+ * @param dumperConfig - Configuration object with HTML and console options
+ * @param dumperConfig.html - HTML output formatting configuration
+ * @param dumperConfig.console - Console output formatting configuration
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   html: {
+ *     showHidden: true,
+ *     depth: 5,
+ *     colors: true
+ *   },
+ *   console: {
+ *     showHidden: false,
+ *     depth: 3,
+ *     collapse: ['Date', 'DateTime']
+ *   }
+ * })
+ * ```
  */
 export function defineConfig(dumperConfig) {
     return dumperConfig;