@adonisjs/assembler 6.1.3-6 → 6.1.3-8

package/build/index.d.ts

@@ -1,4 +1,3 @@
 export { Bundler } from './src/bundler.js';
 export { DevServer } from './src/dev_server.js';
 export { TestRunner } from './src/test_runner.js';
-//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -1,3 +1,11 @@
+/*
+ * @adonisjs/assembler
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 export { Bundler } from './src/bundler.js';
 export { DevServer } from './src/dev_server.js';
 export { TestRunner } from './src/test_runner.js';

package/build/src/assets_dev_server.d.ts

@@ -1,11 +1,32 @@
 /// <reference types="node" resolution-mode="require"/>
 import { type Logger } from '@poppinss/cliui';
 import type { AssetsBundlerOptions } from './types.js';
+/**
+ * Exposes the API to start the development server for processing assets during
+ * development.
+ *
+ * - Here we are running the assets dev server in a child process.
+ * - Piping the output from the child process and reformatting it before writing it to
+ *   process streams.
+ *
+ * AssetsDevServer is agnostic and can run any assets dev server. Be it Vite or Encore or
+ * even Webpack directly.
+ */
 export declare class AssetsDevServer {
     #private;
     constructor(cwd: URL, options?: AssetsBundlerOptions);
+    /**
+     * Set a custom CLI UI logger
+     */
     setLogger(logger: Logger): this;
+    /**
+     * Starts the assets bundler server. The assets bundler server process is
+     * considered as the secondary process and therefore we do not perform
+     * any cleanup if it dies.
+     */
     start(): void;
+    /**
+     * Stop the dev server
+     */
     stop(): void;
 }
-//# sourceMappingURL=assets_dev_server.d.ts.map

package/build/src/assets_dev_server.js

@@ -1,11 +1,36 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { cliui } from '@poppinss/cliui';
 import { run } from './helpers.js';
+/**
+ * Instance of CLIUI
+ */
 const ui = cliui();
+/**
+ * Exposes the API to start the development server for processing assets during
+ * development.
+ *
+ * - Here we are running the assets dev server in a child process.
+ * - Piping the output from the child process and reformatting it before writing it to
+ *   process streams.
+ *
+ * AssetsDevServer is agnostic and can run any assets dev server. Be it Vite or Encore or
+ * even Webpack directly.
+ */
 export class AssetsDevServer {
     #cwd;
     #logger = ui.logger;
     #options;
     #devServer;
+    /**
+     * Getting reference to colors library from logger
+     */
     get #colors() {
         return this.#logger.getColors();
     }
@@ -13,14 +38,24 @@ export class AssetsDevServer {
         this.#cwd = cwd;
         this.#options = options;
     }
+    /**
+     * Logs messages from vite dev server stdout and stderr
+     */
     #logViteDevServerMessage(data) {
         const dataString = data.toString();
         const lines = dataString.split('\n');
+        /**
+         * Logging VITE ready in message with proper
+         * spaces and newlines
+         */
         if (dataString.includes('ready in')) {
             console.log('');
             console.log(dataString.trim());
             return;
         }
+        /**
+         * Put a wrapper around vite network address log
+         */
         if (dataString.includes('Local') && dataString.includes('Network')) {
             const sticker = ui.sticker().useColors(this.#colors).useRenderer(this.#logger.getRenderer());
             lines.forEach((line) => {
@@ -31,12 +66,18 @@ export class AssetsDevServer {
             sticker.render();
             return;
         }
+        /**
+         * Log rest of the lines
+         */
         lines.forEach((line) => {
             if (line.trim()) {
                 console.log(line);
             }
         });
     }
+    /**
+     * Logs messages from assets dev server stdout and stderr
+     */
     #logAssetsDevServerMessage(data) {
         const dataString = data.toString();
         const lines = dataString.split('\n');
@@ -46,20 +87,39 @@ export class AssetsDevServer {
             }
         });
     }
+    /**
+     * Set a custom CLI UI logger
+     */
     setLogger(logger) {
         this.#logger = logger;
         return this;
     }
+    /**
+     * Starts the assets bundler server. The assets bundler server process is
+     * considered as the secondary process and therefore we do not perform
+     * any cleanup if it dies.
+     */
     start() {
         if (!this.#options?.serve) {
             return;
         }
         this.#logger.info(`starting "${this.#options.driver}" dev server...`);
+        /**
+         * Create child process
+         */
         this.#devServer = run(this.#cwd, {
             script: this.#options.cmd,
+            /**
+             * We do not inherit the stdio for vite and encore, because in
+             * inherit mode they own the stdin and interrupts the
+             * `Ctrl + C` command.
+             */
             stdio: 'pipe',
             scriptArgs: this.#options.args,
         });
+        /**
+         * Log child process messages
+         */
         this.#devServer.stdout?.on('data', (data) => {
             if (this.#options.driver === 'vite') {
                 this.#logViteDevServerMessage(data);
@@ -85,6 +145,9 @@ export class AssetsDevServer {
             this.#logger.fatal(error);
         });
     }
+    /**
+     * Stop the dev server
+     */
     stop() {
         if (this.#devServer) {
             this.#devServer.removeAllListeners();

package/build/src/bundler.d.ts

@@ -2,10 +2,18 @@
 import type tsStatic from 'typescript';
 import { type Logger } from '@poppinss/cliui';
 import type { BundlerOptions } from './types.js';
+/**
+ * The bundler class exposes the API to build an AdonisJS project.
+ */
 export declare class Bundler {
     #private;
     constructor(cwd: URL, ts: typeof tsStatic, options: BundlerOptions);
+    /**
+     * Set a custom CLI UI logger
+     */
     setLogger(logger: Logger): this;
+    /**
+     * Bundles the application to be run in production
+     */
     bundle(stopOnError?: boolean, client?: 'npm' | 'yarn' | 'pnpm'): Promise<boolean>;
 }
-//# sourceMappingURL=bundler.d.ts.map

package/build/src/bundler.js

@@ -1,3 +1,11 @@
+/*
+ * @adonisjs/assembler
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import slash from 'slash';
 import copyfiles from 'cpy';
 import fs from 'node:fs/promises';
@@ -5,13 +13,22 @@ import { fileURLToPath } from 'node:url';
 import { join, relative } from 'node:path';
 import { cliui } from '@poppinss/cliui';
 import { run, parseConfig } from './helpers.js';
+/**
+ * Instance of CLIUI
+ */
 const ui = cliui();
+/**
+ * The bundler class exposes the API to build an AdonisJS project.
+ */
 export class Bundler {
     #cwd;
     #cwdPath;
     #ts;
     #logger = ui.logger;
     #options;
+    /**
+     * Getting reference to colors library from logger
+     */
     get #colors() {
         return this.#logger.getColors();
     }
@@ -24,9 +41,15 @@ export class Bundler {
     #getRelativeName(filePath) {
         return slash(relative(this.#cwdPath, filePath));
     }
+    /**
+     * Cleans up the build directory
+     */
     async #cleanupBuildDirectory(outDir) {
         await fs.rm(outDir, { recursive: true, force: true, maxRetries: 5 });
     }
+    /**
+     * Runs assets bundler command to build assets.
+     */
     async #buildAssets() {
         const assetsBundler = this.#options.assets;
         if (!assetsBundler?.serve) {
@@ -45,6 +68,9 @@ export class Bundler {
             return false;
         }
     }
+    /**
+     * Runs tsc command to build the source.
+     */
     async #runTsc(outDir) {
         try {
             await run(this.#cwd, {
@@ -58,9 +84,12 @@ export class Bundler {
             return false;
         }
     }
+    /**
+     * Copy files to destination directory
+     */
     async #copyFiles(files, outDir) {
         try {
-            await copyfiles(files, outDir, { cwd: this.#cwdPath });
+            await copyfiles(files, outDir, { parents: true, cwd: this.#cwdPath });
         }
         catch (error) {
             if (!error.message.includes("the file doesn't exist")) {
@@ -68,12 +97,18 @@ export class Bundler {
             }
         }
     }
+    /**
+     * Copy meta files to the output directory
+     */
     async #copyMetaFiles(outDir, additionalFilesToCopy) {
         const metaFiles = (this.#options.metaFiles || [])
             .map((file) => file.pattern)
             .concat(additionalFilesToCopy);
         await this.#copyFiles(metaFiles, outDir);
     }
+    /**
+     * Copies .adonisrc.json file to the destination
+     */
     async #copyAdonisRcFile(outDir) {
         const existingContents = JSON.parse(await fs.readFile(join(this.#cwdPath, '.adonisrc.json'), 'utf-8'));
         const compiledContents = Object.assign({}, existingContents, {
@@ -83,6 +118,9 @@ export class Bundler {
         await fs.mkdir(outDir, { recursive: true });
         await fs.writeFile(join(outDir, '.adonisrc.json'), JSON.stringify(compiledContents, null, 2) + '\n');
     }
+    /**
+     * Returns the lock file name for a given packages client
+     */
     #getClientLockFile(client) {
         switch (client) {
             case 'npm':
@@ -93,6 +131,9 @@ export class Bundler {
                 return 'pnpm-lock.yaml';
         }
     }
+    /**
+     * Returns the installation command for a given packages client
+     */
     #getClientInstallCommand(client) {
         switch (client) {
             case 'npm':
@@ -103,24 +144,46 @@ export class Bundler {
                 return 'pnpm i --prod';
         }
     }
+    /**
+     * Set a custom CLI UI logger
+     */
     setLogger(logger) {
         this.#logger = logger;
         return this;
     }
+    /**
+     * Bundles the application to be run in production
+     */
     async bundle(stopOnError = true, client = 'npm') {
+        /**
+         * Step 1: Parse config file to get the build output directory
+         */
         const config = parseConfig(this.#cwd, this.#ts);
         if (!config) {
             return false;
         }
+        /**
+         * Step 2: Cleanup existing build directory (if any)
+         */
         const outDir = config.options.outDir || fileURLToPath(new URL('build/', this.#cwd));
         this.#logger.info('cleaning up output directory', { suffix: this.#getRelativeName(outDir) });
         await this.#cleanupBuildDirectory(outDir);
+        /**
+         * Step 3: Build frontend assets
+         */
         if (!(await this.#buildAssets())) {
             return false;
         }
+        /**
+         * Step 4: Build typescript source code
+         */
         this.#logger.info('compiling typescript source', { suffix: 'tsc' });
         const buildCompleted = await this.#runTsc(outDir);
         await this.#copyFiles(['ace.js'], outDir);
+        /**
+         * Remove incomplete build directory when tsc build
+         * failed and stopOnError is set to true.
+         */
         if (!buildCompleted && stopOnError) {
             await this.#cleanupBuildDirectory(outDir);
             const instructions = ui
@@ -132,13 +195,22 @@ export class Bundler {
             this.#logger.logError(instructions.prepare());
             return false;
         }
+        /**
+         * Step 5: Copy meta files to the build directory
+         */
         const pkgFiles = ['package.json', this.#getClientLockFile(client)];
         this.#logger.info('copying meta files to the output directory');
         await this.#copyMetaFiles(outDir, pkgFiles);
+        /**
+         * Step 6: Copy .adonisrc.json file to the build directory
+         */
         this.#logger.info('copying .adonisrc.json file to the output directory');
         await this.#copyAdonisRcFile(outDir);
         this.#logger.success('build completed');
         this.#logger.log('');
+        /**
+         * Next steps
+         */
         ui.instructions()
             .useRenderer(this.#logger.getRenderer())
             .heading('Run the following commands to start the server in production')

package/build/src/dev_server.d.ts

@@ -2,15 +2,42 @@
 import type tsStatic from 'typescript';
 import { type Logger } from '@poppinss/cliui';
 import type { DevServerOptions } from './types.js';
+/**
+ * Exposes the API to start the development. Optionally, the watch API can be
+ * used to watch for file changes and restart the development server.
+ *
+ * The Dev server performs the following actions
+ *
+ * - Assigns a random PORT, when PORT inside .env file is in use
+ * - Uses tsconfig.json file to collect a list of files to watch.
+ * - Uses metaFiles from .adonisrc.json file to collect a list of files to watch.
+ * - Restart HTTP server on every file change.
+ */
 export declare class DevServer {
     #private;
     constructor(cwd: URL, options: DevServerOptions);
+    /**
+     * Set a custom CLI UI logger
+     */
     setLogger(logger: Logger): this;
+    /**
+     * Add listener to get notified when dev server is
+     * closed
+     */
     onClose(callback: (exitCode: number) => any): this;
+    /**
+     * Add listener to get notified when dev server exists
+     * with an error
+     */
     onError(callback: (error: any) => any): this;
+    /**
+     * Start the development server
+     */
     start(): Promise<void>;
+    /**
+     * Start the development server in watch mode
+     */
     startAndWatch(ts: typeof tsStatic, options?: {
         poll: boolean;
     }): Promise<void>;
 }
-//# sourceMappingURL=dev_server.d.ts.map

package/build/src/dev_server.js

@@ -1,8 +1,30 @@
+/*
+ * @adonisjs/assembler
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import picomatch from 'picomatch';
 import { cliui } from '@poppinss/cliui';
 import { AssetsDevServer } from './assets_dev_server.js';
 import { getPort, isDotEnvFile, isRcFile, runNode, watch } from './helpers.js';
+/**
+ * Instance of CLIUI
+ */
 const ui = cliui();
+/**
+ * Exposes the API to start the development. Optionally, the watch API can be
+ * used to watch for file changes and restart the development server.
+ *
+ * The Dev server performs the following actions
+ *
+ * - Assigns a random PORT, when PORT inside .env file is in use
+ * - Uses tsconfig.json file to collect a list of files to watch.
+ * - Uses metaFiles from .adonisrc.json file to collect a list of files to watch.
+ * - Restart HTTP server on every file change.
+ */
 export class DevServer {
     #cwd;
     #logger = ui.logger;
@@ -16,6 +38,9 @@ export class DevServer {
     #httpServer;
     #watcher;
     #assetsServer;
+    /**
+     * Getting reference to colors library from logger
+     */
     get #colors() {
         return this.#logger.getColors();
     }
@@ -29,6 +54,9 @@ export class DevServer {
             .filter(({ reloadServer }) => reloadServer !== true)
             .map(({ pattern }) => pattern));
     }
+    /**
+     * Inspect if child process message is from AdonisJS HTTP server
+     */
     #isAdonisJSReadyMessage(message) {
         return (message !== null &&
             typeof message === 'object' &&
@@ -36,11 +64,17 @@ export class DevServer {
             'environment' in message &&
             message.environment === 'web');
     }
+    /**
+     * Conditionally clear the terminal screen
+     */
     #clearScreen() {
         if (this.#options.clearScreen) {
             process.stdout.write('\u001Bc');
         }
     }
+    /**
+     * Starts the HTTP server
+     */
     #startHTTPServer(port, mode) {
         this.#httpServer = runNode(this.#cwd, {
             script: this.#scriptFile,
@@ -68,18 +102,22 @@ export class DevServer {
             }
         })
             .catch((error) => {
-            this.#logger.warning('unable to connect to underlying HTTP server process');
-            this.#logger.fatal(error);
             this.#onError?.(error);
             this.#watcher?.close();
             this.#assetsServer?.stop();
         });
     }
+    /**
+     * Starts the assets server
+     */
     #startAssetsServer() {
         this.#assetsServer = new AssetsDevServer(this.#cwd, this.#options.assets);
         this.#assetsServer.setLogger(this.#logger);
         this.#assetsServer.start();
     }
+    /**
+     * Restarts the HTTP server
+     */
     #restartHTTPServer(port) {
         if (this.#httpServer) {
             this.#httpServer.removeAllListeners();
@@ -87,6 +125,9 @@ export class DevServer {
         }
         this.#startHTTPServer(port, 'blocking');
     }
+    /**
+     * Handles a non TypeScript file change
+     */
     #handleFileChange(action, port, relativePath) {
         if (isDotEnvFile(relativePath) || isRcFile(relativePath)) {
             this.#clearScreen();
@@ -105,30 +146,50 @@ export class DevServer {
             this.#logger.log(`${this.#colors.green(action)} ${relativePath}`);
         }
     }
+    /**
+     * Handles TypeScript source file change
+     */
     #handleSourceFileChange(action, port, relativePath) {
         this.#clearScreen();
         this.#logger.log(`${this.#colors.green(action)} ${relativePath}`);
         this.#restartHTTPServer(port);
     }
+    /**
+     * Set a custom CLI UI logger
+     */
     setLogger(logger) {
         this.#logger = logger;
         this.#assetsServer?.setLogger(logger);
         return this;
     }
+    /**
+     * Add listener to get notified when dev server is
+     * closed
+     */
     onClose(callback) {
         this.#onClose = callback;
         return this;
     }
+    /**
+     * Add listener to get notified when dev server exists
+     * with an error
+     */
     onError(callback) {
         this.#onError = callback;
         return this;
     }
+    /**
+     * Start the development server
+     */
     async start() {
         this.#clearScreen();
         this.#logger.info('starting HTTP server...');
         this.#startHTTPServer(String(await getPort(this.#cwd)), 'nonblocking');
         this.#startAssetsServer();
     }
+    /**
+     * Start the development server in watch mode
+     */
     async startAndWatch(ts, options) {
         const port = String(await getPort(this.#cwd));
         this.#isWatching = true;
@@ -136,24 +197,43 @@ export class DevServer {
         this.#logger.info('starting HTTP server...');
         this.#startHTTPServer(port, 'blocking');
         this.#startAssetsServer();
+        /**
+         * Create watcher using tsconfig.json file
+         */
         const output = watch(this.#cwd, ts, options || {});
         if (!output) {
             this.#onClose?.(1);
             return;
         }
+        /**
+         * Storing reference to watcher, so that we can close it
+         * when HTTP server exists with error
+         */
         this.#watcher = output.chokidar;
+        /**
+         * Notify the watcher is ready
+         */
         output.watcher.on('watcher:ready', () => {
             this.#logger.info('watching file system for changes...');
         });
+        /**
+         * Cleanup when watcher dies
+         */
         output.chokidar.on('error', (error) => {
             this.#logger.warning('file system watcher failure');
             this.#logger.fatal(error);
             this.#onError?.(error);
             output.chokidar.close();
         });
+        /**
+         * Changes in TypeScript source file
+         */
         output.watcher.on('source:add', ({ relativePath }) => this.#handleSourceFileChange('add', port, relativePath));
         output.watcher.on('source:change', ({ relativePath }) => this.#handleSourceFileChange('update', port, relativePath));
         output.watcher.on('source:unlink', ({ relativePath }) => this.#handleSourceFileChange('delete', port, relativePath));
+        /**
+         * Changes in non-TypeScript source files
+         */
         output.watcher.on('add', ({ relativePath }) => this.#handleFileChange('add', port, relativePath));
         output.watcher.on('change', ({ relativePath }) => this.#handleFileChange('update', port, relativePath));
         output.watcher.on('unlink', ({ relativePath }) => this.#handleFileChange('delete', port, relativePath));

package/build/src/helpers.d.ts

@@ -2,14 +2,44 @@
 import type tsStatic from 'typescript';
 import { Watcher } from '@poppinss/chokidar-ts';
 import type { RunOptions, WatchOptions } from './types.js';
+/**
+ * Parses tsconfig.json and prints errors using typescript compiler
+ * host
+ */
 export declare function parseConfig(cwd: string | URL, ts: typeof tsStatic): tsStatic.ParsedCommandLine | undefined;
+/**
+ * Runs a Node.js script as a child process and inherits the stdio streams
+ */
 export declare function runNode(cwd: string | URL, options: RunOptions): import("execa").ExecaChildProcess<string>;
+/**
+ * Runs a script as a child process and inherits the stdio streams
+ */
 export declare function run(cwd: string | URL, options: Omit<RunOptions, 'nodeArgs'>): import("execa").ExecaChildProcess<string>;
+/**
+ * Watches the file system using tsconfig file
+ */
 export declare function watch(cwd: string | URL, ts: typeof tsStatic, options: WatchOptions): {
     watcher: Watcher;
     chokidar: import("chokidar").FSWatcher;
 } | undefined;
+/**
+ * Check if file is an .env file
+ */
 export declare function isDotEnvFile(filePath: string): boolean;
+/**
+ * Check if file is .adonisrc.json file
+ */
 export declare function isRcFile(filePath: string): boolean;
+/**
+ * Returns the port to use after inspect the dot-env files inside
+ * a given directory.
+ *
+ * A random port is used when the specified port is in use. Following
+ * is the logic for finding a specified port.
+ *
+ * - The "process.env.PORT" value is used if exists.
+ * - The dot-env files are loaded using the "EnvLoader" and the PORT
+ *   value is by iterating over all the loaded files. The iteration
+ *   stops after first find.
+ */
 export declare function getPort(cwd: URL): Promise<number>;
-//# sourceMappingURL=helpers.d.ts.map