@adonisjs/core 6.1.5-2 → 6.1.5-20

package/build/factories/stubs.d.ts

@@ -2,9 +2,19 @@ import type { ApplicationService } from '../src/types.js';
 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
+ */
 export declare class StubsFactory {
     #private;
+    /**
+     * Merge custom factory parameters
+     */
     merge(params: Partial<FactoryParameters>): this;
+    /**
+     * Prepares a stub
+     */
     prepare(stubPath: string, data: Record<string, any>): Promise<{
         contents: any;
         destination: any;

package/build/factories/stubs.js

@@ -1,18 +1,40 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { AppFactory } from '@adonisjs/application/factories';
 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
+ */
 export class StubsFactory {
     #parameters = {};
+    /**
+     * Returns an instance of application
+     */
     #getApp() {
         return this.#parameters.app || new AppFactory().create(new URL('./', import.meta.url), () => { });
     }
+    /**
+     * Merge custom factory parameters
+     */
     merge(params) {
         this.#parameters = Object.assign(this.#parameters, params);
         return this;
     }
+    /**
+     * Prepares a stub
+     */
     async prepare(stubPath, data) {
         const app = this.#getApp();
         await app.init();
-        const stub = await app.stubs.build(stubPath, {
+        const stubs = await app.stubs.create();
+        const stub = await stubs.build(stubPath, {
             source: stubsRoot,
         });
         return stub.prepare(data);

package/build/index.d.ts

@@ -1,5 +1,5 @@
-/// <reference types="node" resolution-mode="require"/>
-export { stubsRoot } from './stubs/index.js';
+/// <reference types="@types/node" resolution-mode="require"/>
+export { stubsRoot } from './stubs/main.js';
 export { inject } from './modules/container.js';
 export { Ignitor } from './src/ignitor/main.js';
 export declare const errors: {
@@ -140,4 +140,8 @@ export declare const errors: {
     E_INSECURE_APP_KEY: new (args?: any, options?: ErrorOptions | undefined) => import("@poppinss/utils").Exception;
     E_MISSING_APP_KEY: new (args?: any, options?: ErrorOptions | undefined) => import("@poppinss/utils").Exception;
 };
+/**
+ * Pretty prints an error with colorful output using
+ * Youch terminal
+ */
 export declare function prettyPrintError(error: any): Promise<void>;

package/build/index.js

@@ -1,9 +1,17 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { errors as aceErrors } from '@adonisjs/ace';
 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/index.js';
+export { stubsRoot } from './stubs/main.js';
 export { inject } from './modules/container.js';
 export { Ignitor } from './src/ignitor/main.js';
 export const errors = {
@@ -13,7 +21,12 @@ export const errors = {
     ...aceErrors,
     ...envErrors,
 };
+/**
+ * Pretty prints an error with colorful output using
+ * Youch terminal
+ */
 export async function prettyPrintError(error) {
+    // @ts-expect-error
     const { default: youchTerminal } = await import('youch-terminal');
     const { default: Youch } = await import('youch');
     const youch = new Youch(error, {});

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

@@ -0,0 +1,54 @@
+import type { Logger } from '@poppinss/cliui';
+import type { CodeTransformer } from '@adonisjs/assembler/code_transformer';
+import type { AddMiddlewareEntry, EnvValidationDefinition } from '@adonisjs/assembler/types';
+import type { Application } from '../app.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.
+ */
+export declare class Codemods {
+    #private;
+    constructor(app: Application<any>, cliLogger: Logger);
+    /**
+     * Define one or more environment variables
+     */
+    defineEnvVariables(environmentVariables: Record<string, number | string | boolean>): Promise<void>;
+    /**
+     * Define validations for the environment variables
+     */
+    defineEnvValidations(validations: EnvValidationDefinition): Promise<void>;
+    /**
+     * Define validations for the environment variables
+     */
+    registerMiddleware(stack: 'server' | 'router' | 'named', middleware: AddMiddlewareEntry[]): Promise<void>;
+    /**
+     * Update RCFile
+     */
+    updateRcFile(...params: Parameters<CodeTransformer['updateRcFile']>): Promise<void>;
+    /**
+     * Generats the stub
+     */
+    makeUsingStub(stubsRoot: string, stubPath: string, stubState: Record<string, any>): Promise<{
+        relativeFileName: string;
+        contents: any;
+        destination: any;
+        attributes: any;
+        status: "created";
+        skipReason: null;
+    } | {
+        relativeFileName: string;
+        contents: any;
+        destination: any;
+        attributes: any;
+        status: "force_created";
+        skipReason: null;
+    } | {
+        relativeFileName: string;
+        contents: any;
+        destination: any;
+        attributes: any;
+        status: "skipped";
+        skipReason: string;
+    }>;
+}

package/build/modules/ace/codemods.js

@@ -0,0 +1,133 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * 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 { EnvEditor } from '@adonisjs/env/editor';
+/**
+ * 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.
+ */
+export class Codemods {
+    /**
+     * Flag to know if assembler is installed as a
+     * peer dependency or not.
+     */
+    #isAssemblerInstalled;
+    /**
+     * Reference to lazily imported assembler code transformer
+     */
+    #codeTransformer;
+    /**
+     * Reference to AdonisJS application
+     */
+    #app;
+    /**
+     * Reference to CLI logger to write logs
+     */
+    #cliLogger;
+    constructor(app, cliLogger) {
+        this.#app = app;
+        this.#cliLogger = cliLogger;
+    }
+    /**
+     * Lazily imports assembler
+     */
+    async #importAssembler() {
+        if (this.#isAssemblerInstalled === undefined) {
+            this.#codeTransformer = await import('@adonisjs/assembler/code_transformer');
+            this.#isAssemblerInstalled = !!this.#codeTransformer;
+        }
+    }
+    /**
+     * Define one or more environment variables
+     */
+    async defineEnvVariables(environmentVariables) {
+        const editor = new EnvEditor(this.#app.appRoot);
+        await editor.load();
+        Object.keys(environmentVariables).forEach((key) => {
+            const value = environmentVariables[key];
+            editor.add(key, value);
+        });
+        await editor.save();
+        this.#cliLogger.action('update .env file').succeeded();
+    }
+    /**
+     * Define validations for the environment variables
+     */
+    async defineEnvValidations(validations) {
+        await this.#importAssembler();
+        if (!this.#codeTransformer) {
+            this.#cliLogger.warning('Cannot update "start/env.ts" file. Install "@adonisjs/assembler" to modify source files');
+            return;
+        }
+        const transformer = new this.#codeTransformer.CodeTransformer(this.#app.appRoot);
+        const action = this.#cliLogger.action('update start/env.ts file');
+        try {
+            await transformer.defineEnvValidations(validations);
+            action.succeeded();
+        }
+        catch (error) {
+            action.failed(error.message);
+        }
+    }
+    /**
+     * Define validations for the environment variables
+     */
+    async registerMiddleware(stack, middleware) {
+        await this.#importAssembler();
+        if (!this.#codeTransformer) {
+            this.#cliLogger.warning('Cannot update "start/kernel.ts" file. Install "@adonisjs/assembler" to modify source files');
+            return;
+        }
+        const transformer = new this.#codeTransformer.CodeTransformer(this.#app.appRoot);
+        const action = this.#cliLogger.action('update start/kernel.ts file');
+        try {
+            await transformer.addMiddlewareToStack(stack, middleware);
+            action.succeeded();
+        }
+        catch (error) {
+            action.failed(error.message);
+        }
+    }
+    /**
+     * Update RCFile
+     */
+    async updateRcFile(...params) {
+        await this.#importAssembler();
+        if (!this.#codeTransformer) {
+            this.#cliLogger.warning('Cannot update "adonisrc.ts" file. Install "@adonisjs/assembler" to modify source files');
+            return;
+        }
+        const transformer = new this.#codeTransformer.CodeTransformer(this.#app.appRoot);
+        const action = this.#cliLogger.action('update adonisrc.ts file');
+        try {
+            await transformer.updateRcFile(...params);
+            action.succeeded();
+        }
+        catch (error) {
+            action.failed(error.message);
+        }
+    }
+    /**
+     * Generats the stub
+     */
+    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(stubState);
+        const entityFileName = slash(this.#app.relativePath(output.destination));
+        const result = { ...output, relativeFileName: entityFileName };
+        if (output.status === 'skipped') {
+            this.#cliLogger.action(`create ${entityFileName}`).skipped(output.skipReason);
+            return result;
+        }
+        this.#cliLogger.action(`create ${entityFileName}`).succeeded();
+        return result;
+    }
+}

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

@@ -2,6 +2,10 @@ import { BaseCommand as AceBaseCommand, ListCommand as AceListCommand } from '@a
 import { Kernel } from './kernel.js';
 import type { ApplicationService } from '../../src/types.js';
 import type { CommandOptions, ParsedOutput, UIPrimitives } from '../../types/ace.js';
+/**
+ * The base command to create custom ace commands. The AdonisJS base commands
+ * receives the application instance
+ */
 export declare class BaseCommand extends AceBaseCommand {
     app: ApplicationService;
     kernel: Kernel;
@@ -9,12 +13,46 @@ export declare class BaseCommand extends AceBaseCommand {
     get staysAlive(): boolean | undefined;
     get startApp(): boolean | undefined;
     constructor(app: ApplicationService, kernel: Kernel, parsed: ParsedOutput, ui: UIPrimitives, prompt: Kernel['prompt']);
+    /**
+     * Creates the codemods module to modify source files
+     */
+    createCodemods(): Promise<import("./codemods.js").Codemods>;
+    /**
+     * The prepare template method is used to prepare the
+     * state for the command. This is the first method
+     * executed on a given command instance.
+     */
     prepare?(..._: any[]): any;
+    /**
+     * The interact template method is used to display the prompts
+     * to the user. The method is called after the prepare
+     * method.
+     */
     interact?(..._: any[]): any;
+    /**
+     * The completed method is the method invoked after the command
+     * finishes or results in an error.
+     *
+     * You can access the command error using the `this.error` property.
+     * Returning `true` from completed method supresses the error
+     * reporting to the kernel layer.
+     */
     completed?(..._: any[]): any;
+    /**
+     * Executes 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(): Promise<void>;
 }
+/**
+ * The List command is used to display a list of commands
+ */
 export declare class ListCommand extends AceListCommand implements BaseCommand {
     app: ApplicationService;
     kernel: Kernel;
@@ -22,5 +60,15 @@ export declare class ListCommand extends AceListCommand implements BaseCommand {
     get staysAlive(): boolean | undefined;
     get startApp(): boolean | undefined;
     constructor(app: ApplicationService, kernel: Kernel, parsed: ParsedOutput, ui: UIPrimitives, prompt: Kernel['prompt']);
+    /**
+     * Creates the codemods module to modify source files
+     */
+    createCodemods(): Promise<import("./codemods.js").Codemods>;
+    /**
+     * 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(): Promise<void>;
 }

package/build/modules/ace/commands.js

@@ -1,4 +1,16 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 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
+ */
 export class BaseCommand extends AceBaseCommand {
     app;
     kernel;
@@ -14,12 +26,28 @@ export class BaseCommand extends AceBaseCommand {
         this.app = app;
         this.kernel = kernel;
     }
+    /**
+     * Creates the codemods module to modify source files
+     */
+    async createCodemods() {
+        const { Codemods } = await import('./codemods.js');
+        return new Codemods(this.app, this.logger);
+    }
+    /**
+     * Executes the command
+     */
     async exec() {
         this.hydrate();
         try {
+            /**
+             * Executing the template methods
+             */
             this.prepare && (await this.app.container.call(this, 'prepare'));
             this.interact && (await this.app.container.call(this, 'interact'));
             const result = await this.app.container.call(this, 'run');
+            /**
+             * Set exit code
+             */
             this.result = this.result === undefined ? result : this.result;
             this.exitCode = this.exitCode ?? 0;
         }
@@ -27,6 +55,10 @@ export class BaseCommand extends AceBaseCommand {
             this.error = error;
             this.exitCode = this.exitCode ?? 1;
         }
+        /**
+         * Run the completed method (if exists) and check if has handled
+         * the error
+         */
         let errorHandled = this.completed
             ? await this.app.container.call(this, 'completed')
             : false;
@@ -35,12 +67,21 @@ 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.
+     */
     async terminate() {
         if (this.kernel.getMainCommand() === this) {
             await this.app.terminate();
         }
     }
 }
+/**
+ * The List command is used to display a list of commands
+ */
 export class ListCommand extends AceListCommand {
     app;
     kernel;
@@ -56,6 +97,19 @@ export class ListCommand extends AceListCommand {
         this.app = app;
         this.kernel = kernel;
     }
+    /**
+     * Creates the codemods module to modify source files
+     */
+    async createCodemods() {
+        const { Codemods } = await import('./codemods.js');
+        return new Codemods(this.app, this.logger);
+    }
+    /**
+     * 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.
+     */
     async terminate() {
         if (this.kernel.getMainCommand() === this) {
             await this.app.terminate();

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

@@ -1,3 +1,12 @@
 import { Kernel } from './main.js';
 import type { ApplicationService } from '../../src/types.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.
+ *
+ * - In console environment, ace manages the lifecycle of the process
+ * - In other environments, ace can be pulled from the container to
+ * run commands
+ */
 export declare function createAceKernel(app: ApplicationService): Kernel;

package/build/modules/ace/create_kernel.js

@@ -1,11 +1,36 @@
+/*
+ * @adonisjs/ace
+ *
+ * (c) AdonisJS
+ *
+ * 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';
+/**
+ * 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.
+ *
+ * - In console environment, ace manages the lifecycle of the process
+ * - In other environments, ace can be pulled from the container to
+ * run commands
+ */
 export function createAceKernel(app) {
     const kernel = new Kernel(app);
     kernel.addLoader(new FsLoader(app.commandsPath()));
+    kernel.info.set('binary', 'node ace');
+    /**
+     * Lazy import commands mentioned in the "commands" array
+     * of rcFile
+     */
     app.rcFile.commands.forEach((commandModule) => {
-        kernel.addLoader(() => app.import(commandModule));
+        kernel.addLoader(() => typeof commandModule === 'function' ? commandModule() : app.import(commandModule));
     });
+    /**
+     * Custom global flags
+     */
     kernel.defineFlag('ansi', {
         type: 'boolean',
         showNegatedVariantInHelp: true,
@@ -15,6 +40,9 @@ export function createAceKernel(app) {
         type: 'boolean',
         description: HelpCommand.description,
     });
+    /**
+     * Flag listener to turn colors on/off
+     */
     kernel.on('ansi', (_, $kernel, parsed) => {
         if (parsed.flags.ansi === false) {
             $kernel.ui.switchMode('silent');
@@ -23,6 +51,9 @@ export function createAceKernel(app) {
             $kernel.ui.switchMode('normal');
         }
     });
+    /**
+     * Flag listener to display the help
+     */
     kernel.on('help', async (command, $kernel, parsed) => {
         parsed.args.unshift(command.commandName);
         const help = new HelpCommand($kernel, parsed, kernel.ui, kernel.prompt);

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

@@ -1,6 +1,10 @@
 import { Kernel as AceKernel } from '@adonisjs/ace';
 import { BaseCommand } from './commands.js';
 import type { ApplicationService } from '../../src/types.js';
+/**
+ * The base command to create custom ace commands. The AdonisJS base commands
+ * receives the application instance
+ */
 export declare class Kernel extends AceKernel<typeof BaseCommand> {
     app: ApplicationService;
     constructor(app: ApplicationService);

package/build/modules/ace/kernel.js

@@ -1,5 +1,17 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { Kernel as AceKernel } from '@adonisjs/ace';
 import { ListCommand } from './commands.js';
+/**
+ * The base command to create custom ace commands. The AdonisJS base commands
+ * receives the application instance
+ */
 export class Kernel extends AceKernel {
     app;
     constructor(app) {

package/build/modules/ace/main.js

@@ -1,3 +1,11 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * 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';

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

@@ -1,4 +1,12 @@
-/// <reference types="node" resolution-mode="require"/>
+/// <reference types="@types/node" resolution-mode="require"/>
+/**
+ * Ace shell is used to run the ace commands inside a TypeScript project
+ * without pre-compiling TypeScript source files.
+ *
+ * Under the hood a child process is used to execute the "bin/console.ts" file. This
+ * is required because we have to use "ts-node/esm" loader in order to run TypeScript
+ * files.
+ */
 export declare function aceShell(cwd: URL): {
     handle(argv: string[]): Promise<void>;
 };

package/build/modules/ace/shell.js

@@ -1,8 +1,29 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 const DEFAULT_NODE_ARGS = [
+    // Use ts-node/esm loader. The project must install it
     '--loader=ts-node/esm',
+    // Disable annonying warnings
     '--no-warnings',
+    // Enable expiremental meta resolve for cases where someone uses magic import string
     '--experimental-import-meta-resolve',
+    // Enable source maps, since TSNode source maps are broken
+    '--enable-source-maps',
 ];
+/**
+ * Ace shell is used to run the ace commands inside a TypeScript project
+ * without pre-compiling TypeScript source files.
+ *
+ * Under the hood a child process is used to execute the "bin/console.ts" file. This
+ * is required because we have to use "ts-node/esm" loader in order to run TypeScript
+ * files.
+ */
 export function aceShell(cwd) {
     return {
         async handle(argv) {

package/build/modules/app.js

@@ -1 +1,9 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 export * from '@adonisjs/application';

package/build/modules/bodyparser/bodyparser_middleware.d.ts

@@ -1,2 +1,6 @@
 import { BodyParserMiddleware } from '@adonisjs/bodyparser/bodyparser_middleware';
+/**
+ * Default export allows lazy importing middleware with
+ * destructuring the named exports
+ */
 export default BodyParserMiddleware;

package/build/modules/bodyparser/bodyparser_middleware.js

@@ -1,2 +1,14 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { BodyParserMiddleware } from '@adonisjs/bodyparser/bodyparser_middleware';
+/**
+ * Default export allows lazy importing middleware with
+ * destructuring the named exports
+ */
 export default BodyParserMiddleware;

package/build/modules/bodyparser/main.js

@@ -1 +1,9 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 export * from '@adonisjs/bodyparser';