@adonisjs/core 6.1.5-0 → 6.1.5-10

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

@@ -2,25 +2,148 @@ 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';
+/**
+ * Wrapper around the stub generation logic.
+ * Allow commands to easily generate files from given stubs
+ */
+declare class StubGenerator {
+    #private;
+    constructor(command: BaseCommand, flags: Record<string, any>);
+    generate(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;
+    }>;
+}
+/**
+ * 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;
+    stubGenerator: StubGenerator;
     static options: CommandOptions;
     get staysAlive(): boolean | undefined;
     get startApp(): boolean | undefined;
     constructor(app: ApplicationService, kernel: Kernel, parsed: ParsedOutput, ui: UIPrimitives, prompt: Kernel['prompt']);
+    /**
+     * 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;
+    /**
+     * Make a new file using the given stub
+     */
+    makeUsingStub(stubPath: string, stubState: Record<string, any>, stubsRoot: string): 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;
+    }>;
+    /**
+     * 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;
+    stubGenerator: StubGenerator;
     static options: CommandOptions;
     get staysAlive(): boolean | undefined;
     get startApp(): boolean | undefined;
     constructor(app: ApplicationService, kernel: Kernel, parsed: ParsedOutput, ui: UIPrimitives, prompt: Kernel['prompt']);
+    /**
+     * Make a new file using the given stub
+     */
+    makeUsingStub(stubPath: string, stubState: Record<string, any>, stubsRoot: string): 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;
+    }>;
+    /**
+     * 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>;
 }
+export {};

package/build/modules/ace/commands.js

@@ -1,7 +1,45 @@
+/*
+ * @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 { BaseCommand as AceBaseCommand, ListCommand as AceListCommand } from '@adonisjs/ace';
+/**
+ * Wrapper around the stub generation logic.
+ * Allow commands to easily generate files from given stubs
+ */
+class StubGenerator {
+    #command;
+    #flags;
+    constructor(command, flags) {
+        this.#command = command;
+        this.#flags = flags;
+    }
+    async generate(stubsRoot, stubPath, stubState) {
+        const stub = await this.#command.app.stubs.build(stubPath, { source: stubsRoot });
+        const output = await stub.generate(Object.assign({ flags: this.#flags }, stubState));
+        const entityFileName = slash(this.#command.app.relativePath(output.destination));
+        const result = { ...output, relativeFileName: entityFileName };
+        if (output.status === 'skipped') {
+            this.#command.logger.action(`create ${entityFileName}`).skipped(output.skipReason);
+            return result;
+        }
+        this.#command.logger.action(`create ${entityFileName}`).succeeded();
+        return result;
+    }
+}
+/**
+ * The base command to create custom ace commands. The AdonisJS base commands
+ * receives the application instance
+ */
 export class BaseCommand extends AceBaseCommand {
     app;
     kernel;
+    stubGenerator = new StubGenerator(this, this.parsed?.flags || {});
     static options = {};
     get staysAlive() {
         return this.constructor.options.staysAlive;
@@ -14,12 +52,27 @@ export class BaseCommand extends AceBaseCommand {
         this.app = app;
         this.kernel = kernel;
     }
+    /**
+     * Make a new file using the given stub
+     */
+    async makeUsingStub(stubPath, stubState, stubsRoot) {
+        return this.stubGenerator.generate(stubsRoot, stubPath, stubState);
+    }
+    /**
+     * 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 +80,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,15 +92,25 @@ 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;
+    stubGenerator = new StubGenerator(this, this.parsed?.flags || {});
     static options = {};
     get staysAlive() {
         return this.constructor.options.staysAlive;
@@ -56,6 +123,18 @@ export class ListCommand extends AceListCommand {
         this.app = app;
         this.kernel = kernel;
     }
+    /**
+     * Make a new file using the given stub
+     */
+    async makeUsingStub(stubPath, stubState, stubsRoot) {
+        return this.stubGenerator.generate(stubsRoot, stubPath, stubState);
+    }
+    /**
+     * 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));
     });
+    /**
+     * 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.d.ts

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

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, HelpCommand, IndexGenerator, } from '@adonisjs/ace';
+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';

package/build/modules/config.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/config';

package/build/modules/container.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/fold';

package/build/modules/encryption.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/encryption';

package/build/modules/env.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/env';

package/build/modules/events.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/events';

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

@@ -1,5 +1,8 @@
 import type { HashDriversList } from '../../src/types.js';
 import type { ManagerDriverFactory } from '../../types/hash.js';
+/**
+ * Define config for the hash service.
+ */
 export declare function defineConfig<KnownHashers extends Record<string, {
     [K in keyof HashDriversList]: {
         driver: K;

package/build/modules/hash/define_config.js

@@ -1,12 +1,32 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { InvalidArgumentsException } from '@poppinss/utils';
 import driversCollection from './drivers_collection.js';
+/**
+ * Define config for the hash service.
+ */
 export function defineConfig(config) {
+    /**
+     * Hashers list should always be provided
+     */
     if (!config.list) {
         throw new InvalidArgumentsException('Missing "list" property in hash config');
     }
+    /**
+     * The default hasher should be mentioned in the list
+     */
     if (config.default && !config.list[config.default]) {
         throw new InvalidArgumentsException(`Missing "list.${String(config.default)}" in hash config. It is referenced by the "default" property`);
     }
+    /**
+     * Converting list config to a collection that hash manager can use
+     */
     const managerHashers = Object.keys(config.list).reduce((result, disk) => {
         const hasherConfig = config.list[disk];
         result[disk] = () => driversCollection.create(hasherConfig.driver, hasherConfig);

package/build/modules/hash/drivers_collection.d.ts

@@ -1,9 +1,21 @@
-import { Argon, Bcrypt, Scrypt } from './main.js';
 import type { HashDriversList } from '../../src/types.js';
+/**
+ * A global collection of Hash drivers
+ */
 declare class HashDriversCollection {
+    /**
+     * List of registered drivers
+     */
     list: Partial<HashDriversList>;
+    /**
+     * Extend drivers collection and add a custom
+     * driver to it.
+     */
     extend<Name extends keyof HashDriversList>(driverName: Name, factoryCallback: HashDriversList[Name]): this;
-    create<Name extends keyof HashDriversList>(name: Name, config: Parameters<HashDriversList[Name]>[0]): Bcrypt | Argon | Scrypt;
+    /**
+     * Creates the driver instance with config
+     */
+    create<Name extends keyof HashDriversList>(name: Name, config: Parameters<HashDriversList[Name]>[0]): import("@adonisjs/hash").Bcrypt | import("@adonisjs/hash").Argon | import("@adonisjs/hash").Scrypt;
 }
-declare const hashDriversCollection: HashDriversCollection;
-export default hashDriversCollection;
+declare const _default: HashDriversCollection;
+export default _default;

package/build/modules/hash/drivers_collection.js

@@ -1,15 +1,39 @@
-import { Argon, Bcrypt, Scrypt } from './main.js';
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * This class exists in the core, because it maintains a list of
+ * globally available drivers applicable to the hash manager
+ * instance registered with the container.
+ *
+ * In other words, these drivers are not needed by the hash module
+ * regular usage and specific to AdonisJS container flow.
+ */
 import { RuntimeException } from '@poppinss/utils';
+/**
+ * A global collection of Hash drivers
+ */
 class HashDriversCollection {
-    list = {
-        bcrypt: (config) => new Bcrypt(config),
-        argon2: (config) => new Argon(config),
-        scrypt: (config) => new Scrypt(config),
-    };
+    /**
+     * List of registered drivers
+     */
+    list = {};
+    /**
+     * Extend drivers collection and add a custom
+     * driver to it.
+     */
     extend(driverName, factoryCallback) {
         this.list[driverName] = factoryCallback;
         return this;
     }
+    /**
+     * Creates the driver instance with config
+     */
     create(name, config) {
         const driverFactory = this.list[name];
         if (!driverFactory) {
@@ -18,5 +42,4 @@ class HashDriversCollection {
         return driverFactory(config);
     }
 }
-const hashDriversCollection = new HashDriversCollection();
-export default hashDriversCollection;
+export default new HashDriversCollection();

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

@@ -1,2 +1,3 @@
 export * from '@adonisjs/hash';
 export { defineConfig } from './define_config.js';
+export { default as driversList } from './drivers_collection.js';