@adonisjs/core 6.1.5-3 → 6.1.5-5

package/build/src/helpers/is.js

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

package/build/src/helpers/main.d.ts

@@ -2,4 +2,3 @@ export { default as parseImports } from 'parse-imports';
 export { createId as cuid } from '@paralleldrive/cuid2';
 export { safeEqual, compose, base64, fsImportAll, fsReadAll, slash } from '@poppinss/utils';
 export { parseBindingReference } from './parse_binding_reference.js';
-//# sourceMappingURL=main.d.ts.map

package/build/src/helpers/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 { default as parseImports } from 'parse-imports';
 export { createId as cuid } from '@paralleldrive/cuid2';
 export { safeEqual, compose, base64, fsImportAll, fsReadAll, slash } from '@poppinss/utils';

package/build/src/helpers/parse_binding_reference.d.ts

@@ -1,6 +1,45 @@
 import { LazyImport, Constructor } from '../../types/http.js';
+/**
+ * The "parseBindingReference" method can be used to parse a binding references
+ * similar to route controller binding value or event listener binding value.
+ *
+ * See the following examples to understand how this function works.
+ *
+ * ### Magic strings
+ * ```ts
+ * parseBindingReference('#controllers/home_controller')
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'handle' }
+
+ * parseBindingReference('#controllers/home_controller.index')
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'index' }
+
+ * parseBindingReference('#controllers/home.controller.index')
+ * // returns { moduleNameOrPath: '#controllers/home.controller', method: 'index' }
+ * ```
+ *
+ * ### Class reference
+ * ```ts
+ * class HomeController {}
+ *
+ * parseBindingReference([HomeController])
+ * // returns { moduleNameOrPath: 'HomeController', method: 'handle' }
+
+ * parseBindingReference([HomeController, 'index'])
+ * // returns { moduleNameOrPath: 'HomeController', method: 'index' }
+ * ```
+ *
+ * ### Lazy import reference
+ * ```ts
+ * const HomeController = () => import('#controllers/home_controller')
+ *
+ * parseBindingReference([HomeController])
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'handle' }
+
+ * parseBindingReference([HomeController, 'index'])
+ * // returns { moduleNameOrPath: 'controllers/home_controller', method: 'index' }
+ * ```
+ */
 export declare function parseBindingReference(binding: string | [LazyImport<Constructor<any>> | Constructor<any>, any?]): Promise<{
     moduleNameOrPath: string;
     method: string;
 }>;
-//# sourceMappingURL=parse_binding_reference.d.ts.map

package/build/src/helpers/parse_binding_reference.js

@@ -1,5 +1,58 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import parseImports from 'parse-imports';
+/**
+ * The "parseBindingReference" method can be used to parse a binding references
+ * similar to route controller binding value or event listener binding value.
+ *
+ * See the following examples to understand how this function works.
+ *
+ * ### Magic strings
+ * ```ts
+ * parseBindingReference('#controllers/home_controller')
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'handle' }
+
+ * parseBindingReference('#controllers/home_controller.index')
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'index' }
+
+ * parseBindingReference('#controllers/home.controller.index')
+ * // returns { moduleNameOrPath: '#controllers/home.controller', method: 'index' }
+ * ```
+ *
+ * ### Class reference
+ * ```ts
+ * class HomeController {}
+ *
+ * parseBindingReference([HomeController])
+ * // returns { moduleNameOrPath: 'HomeController', method: 'handle' }
+
+ * parseBindingReference([HomeController, 'index'])
+ * // returns { moduleNameOrPath: 'HomeController', method: 'index' }
+ * ```
+ *
+ * ### Lazy import reference
+ * ```ts
+ * const HomeController = () => import('#controllers/home_controller')
+ *
+ * parseBindingReference([HomeController])
+ * // returns { moduleNameOrPath: '#controllers/home_controller', method: 'handle' }
+
+ * parseBindingReference([HomeController, 'index'])
+ * // returns { moduleNameOrPath: 'controllers/home_controller', method: 'index' }
+ * ```
+ */
 export async function parseBindingReference(binding) {
+    /**
+     * The binding reference is a magic string. It might not have method
+     * name attached to it. Therefore we split the string and attempt
+     * to find the method or use the default method name "handle".
+     */
     if (typeof binding === 'string') {
         const tokens = binding.split('.');
         if (tokens.length === 1) {
@@ -8,6 +61,10 @@ export async function parseBindingReference(binding) {
         return { method: tokens.pop(), moduleNameOrPath: tokens.join('.') };
     }
     const [bindingReference, method] = binding;
+    /**
+     * Parsing the binding reference for dynamic imports and using its
+     * import value.
+     */
     const imports = [...(await parseImports(bindingReference.toString()))];
     const importedModule = imports.find(($import) => $import.isDynamicImport && $import.moduleSpecifier.value);
     if (importedModule) {
@@ -16,6 +73,9 @@ export async function parseBindingReference(binding) {
             method: method || 'handle',
         };
     }
+    /**
+     * Otherwise using the name of the binding reference.
+     */
     return {
         moduleNameOrPath: bindingReference.name,
         method: method || 'handle',

package/build/src/helpers/string.d.ts

@@ -1,20 +1,43 @@
 import { EncodeOptions } from 'he';
 import string from '@poppinss/utils/string';
 import StringBuilder from '@poppinss/utils/string_builder';
+/**
+ * Collection of string helpers to transform a string value.
+ */
 declare const stringHelpers: typeof string & {
+    /**
+     * Creates an instance of the string builder
+     */
     create(value: string | StringBuilder): StringBuilder;
     ordinalize: (typeof string)['ordinal'];
+    /**
+     * Convert a string to a sentence
+     */
     toSentence: (typeof string)['sentence'];
+    /**
+     * Generate a random string value of a given length
+     */
     generateRandom: (typeof string)['random'];
+    /**
+     * Pretty print hrtime diff
+     */
     prettyHrTime(time: [number, number], options?: {
         verbose?: boolean | undefined;
         precise?: boolean | undefined;
     }): string;
+    /**
+     * Check if a string is empty.
+     */
     isEmpty(value: string): boolean;
+    /**
+     * Escape HTML entities
+     */
     escapeHTML(value: string, options?: {
         encodeSymbols?: boolean;
     }): string;
+    /**
+     * Encode symbols to html entities
+     */
     encodeSymbols(value: string, options?: EncodeOptions): string;
 };
 export default stringHelpers;
-//# sourceMappingURL=string.d.ts.map

package/build/src/helpers/string.js

@@ -1,7 +1,18 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import he from 'he';
 import prettyHrTime from 'pretty-hrtime';
 import string from '@poppinss/utils/string';
 import StringBuilder from '@poppinss/utils/string_builder';
+/**
+ * Collection of string helpers to transform a string value.
+ */
 const stringHelpers = {
     ...string,
     toSentence: string.sentence,

package/build/src/helpers/types.d.ts

@@ -1,5 +1,10 @@
-/// <reference types="node" resolution-mode="require"/>
+/// <reference types="@types/node" resolution-mode="require"/>
 import is from '@sindresorhus/is';
+/**
+ * @deprecated
+ * Use "is" helpers instead. The types helpers exists
+ * for backward compatibility
+ */
 declare const types: {
     lookup: typeof is;
     isNull: (value: unknown) => value is null;
@@ -14,7 +19,7 @@ declare const types: {
     isRegexp: (value: unknown) => value is RegExp;
     isError: (value: unknown) => value is Error;
     isFunction: (value: unknown) => value is Function;
-    isClass: (value: unknown) => value is import("@sindresorhus/is").Class<unknown, any[]>;
+    isClass: (value: unknown) => value is import("@sindresorhus/is").Class;
     isInteger: (value: unknown) => value is number;
     isFloat(value: number): value is number;
     isDecimal(value: string | number, options?: {
@@ -22,4 +27,3 @@ declare const types: {
     }): boolean;
 };
 export default types;
-//# sourceMappingURL=types.d.ts.map

package/build/src/helpers/types.js

@@ -1,4 +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 is from '@sindresorhus/is';
+/**
+ * @deprecated
+ * Use "is" helpers instead. The types helpers exists
+ * for backward compatibility
+ */
 const types = {
     lookup: is,
     isNull: is.null_,

package/build/src/ignitor/ace.d.ts

@@ -1,9 +1,20 @@
 import { Ignitor } from './main.js';
 import type { ApplicationService } from '../types.js';
+/**
+ * The Ace process is used to start the application in the
+ * console environment.
+ */
 export declare class AceProcess {
     #private;
     constructor(ignitor: Ignitor);
+    /**
+     * Register a callback that runs after booting the AdonisJS app
+     * and just before the provider's ready hook
+     */
     configure(callback: (app: ApplicationService) => Promise<void> | void): this;
+    /**
+     * Handles the command line arguments and executes
+     * the matching ace commands
+     */
     handle(argv: string[]): Promise<void>;
 }
-//# sourceMappingURL=ace.d.ts.map

package/build/src/ignitor/ace.js

@@ -1,19 +1,53 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * The Ace process is used to start the application in the
+ * console environment.
+ */
 export class AceProcess {
+    /**
+     * Ignitor reference
+     */
     #ignitor;
+    /**
+     * The callback that configures the tests runner. This callback
+     * runs at the time of starting the app.
+     */
     #configureCallback = () => { };
     constructor(ignitor) {
         this.#ignitor = ignitor;
     }
+    /**
+     * Register a callback that runs after booting the AdonisJS app
+     * and just before the provider's ready hook
+     */
     configure(callback) {
         this.#configureCallback = callback;
         return this;
     }
+    /**
+     * Handles the command line arguments and executes
+     * the matching ace commands
+     */
     async handle(argv) {
         const app = this.#ignitor.createApp('console');
         await app.init();
         const { createAceKernel } = await import('../../modules/ace/create_kernel.js');
         const kernel = createAceKernel(app);
         app.container.bindValue('ace', kernel);
+        /**
+         * Hook into kernel and start the app when the
+         * command needs the app.
+         *
+         * Since multiple commands can be executed in a single process,
+         * we add a check to only start the app only once.
+         */
         kernel.loading(async (metaData) => {
             if (metaData.options.startApp && !app.isReady) {
                 await app.boot();
@@ -21,8 +55,18 @@ export class AceProcess {
             }
         });
         await this.#configureCallback(app);
+        /**
+         * Handle command line args
+         */
         await kernel.handle(argv);
+        /**
+         * Update the process exit code
+         */
         process.exitCode = kernel.exitCode;
+        /**
+         * Terminate the app when the command does not want to
+         * hold a long running process
+         */
         const mainCommand = kernel.getMainCommand();
         if (!mainCommand || !mainCommand.staysAlive) {
             await app.terminate();

package/build/src/ignitor/http.d.ts

@@ -1,11 +1,17 @@
-/// <reference types="node" resolution-mode="require"/>
-/// <reference types="node" resolution-mode="require"/>
+/// <reference types="@types/node" resolution-mode="require"/>
+/// <reference types="@types/node" resolution-mode="require"/>
 import type { Server as NodeHttpsServer } from 'node:https';
 import { IncomingMessage, ServerResponse, Server as NodeHttpServer } from 'node:http';
 import { Ignitor } from './main.js';
+/**
+ * The HTTP server process is used to start the application in the
+ * web environment.
+ */
 export declare class HttpServerProcess {
     #private;
     constructor(ignitor: Ignitor);
+    /**
+     * Start the HTTP server by wiring up the application
+     */
     start(serverCallback?: (handler: (req: IncomingMessage, res: ServerResponse) => any) => NodeHttpsServer | NodeHttpServer): Promise<void>;
 }
-//# sourceMappingURL=http.d.ts.map

package/build/src/ignitor/http.js

@@ -1,21 +1,50 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { createServer } from 'node:http';
 import debug from '../debug.js';
+/**
+ * The HTTP server process is used to start the application in the
+ * web environment.
+ */
 export class HttpServerProcess {
+    /**
+     * Ignitor reference
+     */
     #ignitor;
     constructor(ignitor) {
         this.#ignitor = ignitor;
     }
+    /**
+     * Calling this method closes the underlying HTTP server
+     */
     #close(nodeHttpServer) {
         return new Promise((resolve) => {
             debug('closing http server process');
             nodeHttpServer.close(() => resolve());
         });
     }
+    /**
+     * Monitors the app and the server to close the HTTP server when
+     * either one of them goes down
+     */
     #monitorAppAndServer(nodeHttpServer, app, logger) {
+        /**
+         * Close the HTTP server when the application begins to
+         * terminate
+         */
         app.terminating(async () => {
             debug('terminating signal received');
             await this.#close(nodeHttpServer);
         });
+        /**
+         * Terminate the app when the HTTP server crashes
+         */
         nodeHttpServer.once('error', (error) => {
             debug('http server crashed with error "%O"', error);
             logger.fatal({ err: error }, error.message);
@@ -23,6 +52,9 @@ export class HttpServerProcess {
             app.terminate();
         });
     }
+    /**
+     * Starts the http server a given host and port
+     */
     #listen(nodeHttpServer) {
         return new Promise((resolve, reject) => {
             const host = process.env.HOST || '0.0.0.0';
@@ -37,25 +69,60 @@ export class HttpServerProcess {
             });
         });
     }
+    /**
+     * Notifies the app and the parent process that the
+     * HTTP server is ready
+     */
     #notifyServerHasStarted(app, logger, emitter, payload) {
+        /**
+         * Notify parent process
+         */
         app.notify({ isAdonisJS: true, environment: 'web', ...payload });
+        /**
+         * Visual notification
+         */
         logger.info('started HTTP server on %s:%s', payload.host, payload.port);
+        /**
+         * Notify app
+         */
         emitter.emit('http:server_ready', payload);
     }
+    /**
+     * Start the HTTP server by wiring up the application
+     */
     async start(serverCallback) {
+        /**
+         * Method to create the HTTP server
+         */
         const createHTTPServer = serverCallback || createServer;
         const app = this.#ignitor.createApp('web');
         await app.init();
         await app.boot();
         await app.start(async () => {
+            /**
+             * Resolve and boot the AdonisJS HTTP server
+             */
             const server = await app.container.make('server');
             await server.boot();
+            /**
+             * Create Node.js HTTP server instance and share it with the
+             * AdonisJS HTTP server
+             */
             const httpServer = createHTTPServer(server.handle.bind(server));
             server.setNodeServer(httpServer);
             const logger = await app.container.make('logger');
             const emitter = await app.container.make('emitter');
+            /**
+             * Start the server by listening on a port of host
+             */
             const payload = await this.#listen(httpServer);
+            /**
+             * Notify
+             */
             this.#notifyServerHasStarted(app, logger, emitter, payload);
+            /**
+             * Monitor app and the server (after the server is listening)
+             */
             this.#monitorAppAndServer(httpServer, app, logger);
         });
     }

package/build/src/ignitor/main.d.ts

@@ -1,18 +1,45 @@
-/// <reference types="node" resolution-mode="require"/>
+/// <reference types="@types/node" resolution-mode="require"/>
 import { AceProcess } from './ace.js';
 import { TestRunnerProcess } from './test.js';
 import { HttpServerProcess } from './http.js';
 import type { AppEnvironments } from '../../types/app.js';
 import type { ApplicationService, IgnitorOptions } from '../types.js';
+/**
+ * Ignitor is used to instantiate an AdonisJS application in different
+ * known environments.
+ */
 export declare class Ignitor {
     #private;
     constructor(appRoot: URL, options: IgnitorOptions);
+    /**
+     * Get access to the application instance created
+     * by either the http server process or the ace
+     * process
+     */
     getApp(): ApplicationService | undefined;
+    /**
+     * Create an instance of AdonisJS application
+     */
     createApp(environment: AppEnvironments): ApplicationService;
+    /**
+     * Tap to access the application class instance.
+     */
     tap(callback: (app: ApplicationService) => void): this;
+    /**
+     * Get instance of the HTTPServerProcess
+     */
     httpServer(): HttpServerProcess;
+    /**
+     * Get an instance of the AceProcess class
+     */
     ace(): AceProcess;
+    /**
+     * Get an instance of the TestRunnerProcess class
+     */
     testRunner(): TestRunnerProcess;
+    /**
+     * Terminates the app by calling the "app.terminate"
+     * method
+     */
     terminate(): Promise<void>;
 }
-//# sourceMappingURL=main.d.ts.map

package/build/src/ignitor/main.js

@@ -1,24 +1,64 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import debug from '../debug.js';
 import { AceProcess } from './ace.js';
 import { TestRunnerProcess } from './test.js';
 import { HttpServerProcess } from './http.js';
 import { setApp } from '../../services/app.js';
 import { Application } from '../../modules/app.js';
+/**
+ * Ignitor is used to instantiate an AdonisJS application in different
+ * known environments.
+ */
 export class Ignitor {
+    /**
+     * Ignitor options
+     */
     #options;
+    /**
+     * Application root URL
+     */
     #appRoot;
+    /**
+     * Reference to the application instance created using
+     * the "createApp" method.
+     *
+     * We store the output of the last call made to "createApp" method
+     * and assume that in one process only one entrypoint will
+     * call this method.
+     */
     #app;
+    /**
+     * Reference to the created application
+     */
     #tapCallbacks = new Set();
     constructor(appRoot, options) {
         this.#appRoot = appRoot;
         this.#options = options;
     }
+    /**
+     * Runs all the tap callbacks
+     */
     #runTapCallbacks(app) {
         this.#tapCallbacks.forEach((tapCallback) => tapCallback(app));
     }
+    /**
+     * Get access to the application instance created
+     * by either the http server process or the ace
+     * process
+     */
     getApp() {
         return this.#app;
     }
+    /**
+     * Create an instance of AdonisJS application
+     */
     createApp(environment) {
         debug('creating application instance');
         this.#app = new Application(this.#appRoot, { environment, importer: this.#options.importer });
@@ -26,19 +66,35 @@ export class Ignitor {
         this.#runTapCallbacks(this.#app);
         return this.#app;
     }
+    /**
+     * Tap to access the application class instance.
+     */
     tap(callback) {
         this.#tapCallbacks.add(callback);
         return this;
     }
+    /**
+     * Get instance of the HTTPServerProcess
+     */
     httpServer() {
         return new HttpServerProcess(this);
     }
+    /**
+     * Get an instance of the AceProcess class
+     */
     ace() {
         return new AceProcess(this);
     }
+    /**
+     * Get an instance of the TestRunnerProcess class
+     */
     testRunner() {
         return new TestRunnerProcess(this);
     }
+    /**
+     * Terminates the app by calling the "app.terminate"
+     * method
+     */
     async terminate() {
         await this.#app?.terminate();
     }

package/build/src/ignitor/test.d.ts

@@ -1,9 +1,18 @@
 import { Ignitor } from './main.js';
 import type { ApplicationService } from '../types.js';
+/**
+ * The Test runner process is used to start the tests runner process
+ */
 export declare class TestRunnerProcess {
     #private;
     constructor(ignitor: Ignitor);
+    /**
+     * Register a callback that runs after booting the AdonisJS app
+     * and just before the provider's ready hook
+     */
     configure(callback: (app: ApplicationService) => Promise<void> | void): this;
+    /**
+     * Runs a callback after starting the app
+     */
     run(callback: (app: ApplicationService) => Promise<void> | void): Promise<void>;
 }
-//# sourceMappingURL=test.d.ts.map