@adonisjs/core 6.18.0 → 7.0.0-next.0

package/build/factories/core/ignitor.js

@@ -6,14 +6,30 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import { Ignitor } from '../../src/ignitor/main.js';
-import { drivers } from '../../modules/hash/define_config.js';
-import { defineConfig as defineHttpConfig } from '../../modules/http/main.js';
-import { defineConfig as defineLoggerConfig } from '../../modules/logger.js';
-import { defineConfig as defineHashConfig } from '../../modules/hash/main.js';
-import { defineConfig as defineBodyParserConfig } from '../../modules/bodyparser/main.js';
+import { Ignitor } from "../../src/ignitor/main.js";
+import { drivers } from "../../modules/hash/define_config.js";
+import { defineConfig as defineHttpConfig } from "../../modules/http/main.js";
+import { defineConfig as defineLoggerConfig } from "../../modules/logger.js";
+import { defineConfig as defineHashConfig } from "../../modules/hash/main.js";
+import { defineConfig as defineBodyParserConfig } from "../../modules/bodyparser/main.js";
 /**
- * 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 class IgnitorFactory {
     #preloadActions = [];
@@ -23,7 +39,18 @@ export class IgnitorFactory {
      */
     #loadCoreProviders = false;
     /**
-     * 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) {
         this.#preloadActions.push(action);
@@ -41,7 +68,24 @@ export class IgnitorFactory {
         return coreProviders.concat(providers || []);
     }
     /**
-     * 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) {
         if (params.config) {
@@ -53,15 +97,31 @@ export class IgnitorFactory {
         return 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.#loadCoreProviders = true;
         return 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.merge({
@@ -89,7 +149,18 @@ export class IgnitorFactory {
         return 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, options) {
         return new Ignitor(appRoot, options).tap((app) => {

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

@@ -1,3 +1,3 @@
-export { AceFactory } from './ace.js';
-export { IgnitorFactory } from './ignitor.js';
-export { TestUtilsFactory } from './test_utils.js';
+export { AceFactory } from './ace.ts';
+export { IgnitorFactory } from './ignitor.ts';
+export { TestUtilsFactory } from './test_utils.ts';

package/build/factories/core/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 { AceFactory } from './ace.js';
-export { IgnitorFactory } from './ignitor.js';
-export { TestUtilsFactory } from './test_utils.js';
+export { AceFactory } from "./ace.js";
+export { IgnitorFactory } from "./ignitor.js";
+export { TestUtilsFactory } from "./test_utils.js";

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

@@ -1,10 +1,38 @@
-import { Ignitor } from '../../index.js';
-import type { IgnitorOptions } from '../../src/types.js';
-import { TestUtils } from '../../src/test_utils/main.js';
+import { Ignitor } from '../../index.ts';
+import type { IgnitorOptions } from '../../src/types.ts';
+import { TestUtils } from '../../src/test_utils/main.ts';
 /**
- * Creates an instance of TestUtils class
+ * Factory for creating TestUtils instances used in AdonisJS testing scenarios.
+ * This factory provides convenient methods to set up test utilities either from
+ * an existing Ignitor instance or by creating a new configured one.
+ *
+ * @example
+ * ```ts
+ * // Create from URL for testing
+ * const factory = new TestUtilsFactory()
+ * const testUtils = factory.create(new URL('../', import.meta.url))
+ *
+ * // Use in tests
+ * const app = testUtils.app()
+ * await app.boot()
+ *
+ * // Create HTTP client
+ * const client = testUtils.httpClient()
+ * const response = await client.get('/users')
+ * ```
  */
 export declare class TestUtilsFactory {
+    /**
+     * Create TestUtils from an existing Ignitor instance
+     *
+     * @param ignitor - Existing Ignitor instance configured for testing
+     */
     create(ignitor: Ignitor): TestUtils;
+    /**
+     * Create TestUtils from application root URL with optional configuration
+     *
+     * @param appRoot - Application root directory URL
+     * @param options - Optional Ignitor configuration options
+     */
     create(appRoot: URL, options?: IgnitorOptions): TestUtils;
 }

package/build/factories/core/test_utils.js

@@ -6,11 +6,28 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import { Ignitor } from '../../index.js';
-import { IgnitorFactory } from './ignitor.js';
-import { TestUtils } from '../../src/test_utils/main.js';
+import { Ignitor } from "../../index.js";
+import { IgnitorFactory } from "./ignitor.js";
+import { TestUtils } from "../../src/test_utils/main.js";
 /**
- * Creates an instance of TestUtils class
+ * Factory for creating TestUtils instances used in AdonisJS testing scenarios.
+ * This factory provides convenient methods to set up test utilities either from
+ * an existing Ignitor instance or by creating a new configured one.
+ *
+ * @example
+ * ```ts
+ * // Create from URL for testing
+ * const factory = new TestUtilsFactory()
+ * const testUtils = factory.create(new URL('../', import.meta.url))
+ *
+ * // Use in tests
+ * const app = testUtils.app()
+ * await app.boot()
+ *
+ * // Create HTTP client
+ * const client = testUtils.httpClient()
+ * const response = await client.get('/users')
+ * ```
  */
 export class TestUtilsFactory {
     create(ignitorOrAppRoot, options) {

package/build/factories/stubs.d.ts

@@ -1,19 +1,68 @@
-import type { ApplicationService } from '../src/types.js';
+import type { ApplicationService } from '../src/types.ts';
 type FactoryParameters = {
     app: ApplicationService;
 };
 /**
- * Prepares stubs from "@adonisjs/core" package. We do not publish this class as it
- * is for internal testing only using the "stubsRoot" of the core package
+ * Factory for preparing and processing stub templates from the "@adonisjs/core" package.
+ * This factory is designed for internal testing and development purposes, utilizing
+ * the core package's stub root directory.
+ *
+ * Note: This class is not published as it's intended for internal testing only.
+ *
+ * @example
+ * ```ts
+ * const stubsFactory = new StubsFactory()
+ *
+ * // Prepare a controller stub
+ * const preparedStub = await stubsFactory.prepare('controller.stub', {
+ *   filename: 'UserController',
+ *   entity: { name: 'User' },
+ *   resourceful: true
+ * })
+ *
+ * console.log(preparedStub.contents)
+ * ```
  */
 export declare class StubsFactory {
     #private;
     /**
-     * Merge custom factory parameters
+     * Merge custom factory parameters to override defaults.
+     * This allows you to provide a custom application instance.
+     *
+     * @param params - Parameters to merge
+     * @param params.app - Custom application service instance
+     *
+     * @example
+     * ```ts
+     * const customApp = new AppFactory().create(appRoot)
+     * const stubsFactory = new StubsFactory().merge({ app: customApp })
+     * ```
      */
     merge(params: Partial<FactoryParameters>): this;
     /**
-     * Prepares a stub
+     * Prepare a stub template with the provided data and return the processed content.
+     * This method initializes the application, loads the stub, and processes it with
+     * the given template variables.
+     *
+     * @param stubPath - Path to the stub file relative to the stubs root
+     * @param data - Template data to populate the stub placeholders
+     *
+     * @example
+     * ```ts
+     * const stubsFactory = new StubsFactory()
+     * const preparedStub = await stubsFactory.prepare('controller.stub', {
+     *   filename: 'UserController',
+     *   entity: {
+     *     name: 'User',
+     *     modelName: 'User',
+     *     pluralName: 'users'
+     *   },
+     *   resourceful: true
+     * })
+     *
+     * // Access the processed stub content
+     * console.log(preparedStub.contents)
+     * ```
      */
     prepare(stubPath: string, data: Record<string, any>): Promise<{
         contents: string;

package/build/factories/stubs.js

@@ -7,28 +7,77 @@
  * file that was distributed with this source code.
  */
 import { AppFactory } from '@adonisjs/application/factories';
-import { stubsRoot } from '../index.js';
+import { stubsRoot } from "../index.js";
 /**
- * Prepares stubs from "@adonisjs/core" package. We do not publish this class as it
- * is for internal testing only using the "stubsRoot" of the core package
+ * Factory for preparing and processing stub templates from the "@adonisjs/core" package.
+ * This factory is designed for internal testing and development purposes, utilizing
+ * the core package's stub root directory.
+ *
+ * Note: This class is not published as it's intended for internal testing only.
+ *
+ * @example
+ * ```ts
+ * const stubsFactory = new StubsFactory()
+ *
+ * // Prepare a controller stub
+ * const preparedStub = await stubsFactory.prepare('controller.stub', {
+ *   filename: 'UserController',
+ *   entity: { name: 'User' },
+ *   resourceful: true
+ * })
+ *
+ * console.log(preparedStub.contents)
+ * ```
  */
 export class StubsFactory {
     #parameters = {};
     /**
-     * Returns an instance of application
+     * Returns an instance of application, either from parameters or creates a default one
      */
     #getApp() {
         return this.#parameters.app || new AppFactory().create(new URL('./', import.meta.url));
     }
     /**
-     * Merge custom factory parameters
+     * Merge custom factory parameters to override defaults.
+     * This allows you to provide a custom application instance.
+     *
+     * @param params - Parameters to merge
+     * @param params.app - Custom application service instance
+     *
+     * @example
+     * ```ts
+     * const customApp = new AppFactory().create(appRoot)
+     * const stubsFactory = new StubsFactory().merge({ app: customApp })
+     * ```
      */
     merge(params) {
         this.#parameters = Object.assign(this.#parameters, params);
         return this;
     }
     /**
-     * Prepares a stub
+     * Prepare a stub template with the provided data and return the processed content.
+     * This method initializes the application, loads the stub, and processes it with
+     * the given template variables.
+     *
+     * @param stubPath - Path to the stub file relative to the stubs root
+     * @param data - Template data to populate the stub placeholders
+     *
+     * @example
+     * ```ts
+     * const stubsFactory = new StubsFactory()
+     * const preparedStub = await stubsFactory.prepare('controller.stub', {
+     *   filename: 'UserController',
+     *   entity: {
+     *     name: 'User',
+     *     modelName: 'User',
+     *     pluralName: 'users'
+     *   },
+     *   resourceful: true
+     * })
+     *
+     * // Access the processed stub content
+     * console.log(preparedStub.contents)
+     * ```
      */
     async prepare(stubPath, data) {
         const app = this.#getApp();

package/build/index.d.ts

@@ -3,10 +3,11 @@ import { errors as envErrors } from '@adonisjs/env';
 import { errors as appErrors } from '@adonisjs/application';
 import { errors as encryptionErrors } from '@adonisjs/encryption';
 import { errors as httpServerErrors } from '@adonisjs/http-server';
-export { stubsRoot } from './stubs/main.js';
-export { inject } from './modules/container.js';
-export { Ignitor } from './src/ignitor/main.js';
-export { configProvider } from './src/config_provider.js';
+export { stubsRoot } from './stubs/main.ts';
+export { inject } from './modules/container.ts';
+export { Ignitor } from './src/ignitor/main.ts';
+export { configProvider } from './src/config_provider.ts';
+export { indexEntities } from './src/assembler_hooks/index_entities.ts';
 /**
  * Aggregated errors from all modules.
  */

package/build/index.js

@@ -11,10 +11,11 @@ import { errors as envErrors } from '@adonisjs/env';
 import { errors as appErrors } from '@adonisjs/application';
 import { errors as encryptionErrors } from '@adonisjs/encryption';
 import { errors as httpServerErrors } from '@adonisjs/http-server';
-export { stubsRoot } from './stubs/main.js';
-export { inject } from './modules/container.js';
-export { Ignitor } from './src/ignitor/main.js';
-export { configProvider } from './src/config_provider.js';
+export { stubsRoot } from "./stubs/main.js";
+export { inject } from "./modules/container.js";
+export { Ignitor } from "./src/ignitor/main.js";
+export { configProvider } from "./src/config_provider.js";
+export { indexEntities } from "./src/assembler_hooks/index_entities.js";
 /**
  * Aggregated errors from all modules.
  */
@@ -34,9 +35,12 @@ export async function prettyPrintError(error) {
         console.error(error);
         return;
     }
-    // @ts-expect-error
-    const { default: youchTerminal } = await import('youch-terminal');
-    const { default: Youch } = await import('youch');
-    const youch = new Youch(error, {});
-    console.error(youchTerminal(await youch.toJSON(), { displayShortPath: true }));
+    try {
+        const { Youch } = await import('youch');
+        const youch = new Youch();
+        console.error(await youch.toANSI(error));
+    }
+    catch {
+        console.error(error);
+    }
 }

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

@@ -1,12 +1,31 @@
 import { EventEmitter } from 'node:events';
 import type { UIPrimitives } from '@adonisjs/ace/types';
 import type { CodeTransformer } from '@adonisjs/assembler/code_transformer';
-import type { MiddlewareNode, EnvValidationNode, BouncerPolicyNode } from '@adonisjs/assembler/types';
-import type { Application } from '../app.js';
+import type { MiddlewareNode, EnvValidationNode, BouncerPolicyNode, SupportedPackageManager } from '@adonisjs/assembler/types';
+import type { Application } from '../app.ts';
 /**
- * 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 declare class Codemods extends EventEmitter {
     #private;
@@ -21,16 +40,40 @@ export declare class Codemods extends EventEmitter {
     verboseInstallOutput: boolean;
     constructor(app: Application<any>, cliLogger: UIPrimitives['logger']);
     /**
-     * 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']
+     * })
+     * ```
      */
     defineEnvVariables<T extends Record<string, number | string | boolean>>(environmentVariables: T, options?: {
         omitFromExample?: Array<keyof T>;
     }): Promise<void>;
     /**
-     * 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
+     * }
+     * ```
      */
-    getTsMorphProject(): Promise<InstanceType<typeof import('@adonisjs/assembler/code_transformer').CodeTransformer>['project'] | undefined>;
+    getTsMorphProject(): Promise<CodeTransformer['project'] | undefined>;
     /**
      * Define validations for the environment variables
      */
@@ -58,7 +101,24 @@ export declare class Codemods extends EventEmitter {
      */
     registerJapaPlugin(...params: Parameters<CodeTransformer['addJapaPlugin']>): Promise<void>;
     /**
-     * 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
+     *   }
+     * )
+     * ```
      */
     makeUsingStub(stubsRoot: string, stubPath: string, stubState: Record<string, any>): Promise<{
         relativeFileName: string;
@@ -94,7 +154,7 @@ export declare class Codemods extends EventEmitter {
     installPackages(packages: {
         name: string;
         isDevDependency: boolean;
-    }[]): Promise<void>;
+    }[], packageManager?: SupportedPackageManager | 'pnpm@6' | 'deno'): Promise<boolean>;
     /**
      * List the packages one should install before using the packages
      */