@adonisjs/assembler 8.0.0-next.5 → 8.0.0-next.7

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

@@ -1,192 +1,336 @@
 import type { Logger } from '@poppinss/cliui';
 import { type Prettify } from '@poppinss/utils/types';
-import { type BundlerHooks, type DevServerHooks, type TestRunnerHooks, type WatcherHooks } from './hooks.ts';
+import { type AllHooks } from './hooks.ts';
+import { type FileBuffer } from '../file_buffer.ts';
+import { type VirtualFileSystem } from '../virtual_file_system.ts';
+/**
+ * Recursive file tree structure for representing nested directory hierarchies
+ */
+export type RecursiveFileTree = {
+    [key: string]: string | RecursiveFileTree;
+};
+/**
+ * Options accepted by the VirtualFileSystem class
+ */
+export type VirtualFileSystemOptions = {
+    glob?: string[];
+};
+/**
+ * Source configuration accepted by the index generator
+ */
+export type IndexGeneratorSourceConfig = ({
+    exportName: string;
+    as: 'barrelFile';
+} | {
+    as: (vfs: VirtualFileSystem, buffer: FileBuffer, config: IndexGeneratorSourceConfig) => void;
+}) & {
+    source: string;
+    output: string;
+    glob?: string[];
+    importAlias?: string;
+    removeSuffix?: string;
+};
 /**
  * Marks a given optional property as required
+ *
+ * @template T - The source type
+ * @template K - The keys from T that should be made required
+ *
+ * @example
+ * type User = { name?: string; email?: string; age: number }
+ * type UserWithName = AsRequired<User, 'name'> // { name: string; email?: string; age: number }
  */
 export type AsRequired<T, K extends keyof T> = Prettify<Omit<T, K> & Required<{
     [O in K]: T[K];
 }>>;
 /**
- * Represents an import statement
+ * Represents an import statement parsed from TypeScript/JavaScript code
+ *
+ * @example
+ * // For: import { User } from './models/user'
+ * const importInfo: Import = {
+ *   specifier: './models/user',
+ *   isConstant: true,
+ *   clause: { type: 'named', value: 'User' }
+ * }
  */
 export type Import = {
+    /** The module specifier being imported from */
     specifier: string;
+    /** Whether the import specifier is a constant string literal */
     isConstant: boolean;
+    /** The import clause details */
     clause: {
+        /** The type of import clause */
         type: 'namespace' | 'default' | 'named';
+        /** The imported identifier name */
         value: string;
+        /** Optional alias for named imports with 'as' keyword */
         alias?: string;
     };
 };
 /**
  * File inspected by the filesystem based upon the provided globs
  * and the current file path
+ *
+ * @example
+ * const inspectedFile: InspectedFile = {
+ *   fileType: 'script',
+ *   reloadServer: true,
+ *   unixRelativePath: 'app/controllers/users_controller.ts',
+ *   unixAbsolutePath: '/project/app/controllers/users_controller.ts'
+ * }
  */
 export type InspectedFile = {
+    /** The category of the file based on its purpose */
     fileType: 'script' | 'meta' | 'test';
+    /** Whether changes to this file should trigger server reload */
     reloadServer: boolean;
+    /** Unix-style relative path from project root */
     unixRelativePath: string;
+    /** Unix-style absolute path to the file */
     unixAbsolutePath: string;
 };
 /**
  * Subset of properties assembler needs from the "adonisrc.ts" file.
+ * Contains configuration for file watching, hooks, and test suites.
+ *
+ * @example
+ * const rcFile: AssemblerRcFile = {
+ *   metaFiles: [
+ *     { pattern: 'config/**', reloadServer: true }
+ *   ],
+ *   hooks: {
+ *     devServerStarted: [() => import('./hooks/server_started')]
+ *   },
+ *   suites: [
+ *     { name: 'unit', files: ['tests/unit/**\/*.spec.ts'] }
+ *   ]
+ * }
  */
 export type AssemblerRcFile = {
     /**
-     * An array of metaFiles glob patterns to watch
+     * An array of metaFiles glob patterns to watch for changes
      */
     metaFiles?: {
+        /** Glob pattern to match files */
         pattern: string;
+        /** Whether to reload server when these files change */
         reloadServer: boolean;
     }[];
     /**
-     * Hooks to execute at different stages.
+     * Hooks to execute at different stages of development and build processes
      */
-    hooks?: Partial<WatcherHooks & DevServerHooks & BundlerHooks & TestRunnerHooks>;
+    hooks?: Partial<AllHooks>;
     /**
-     * An array of suites for which to run tests
+     * An array of test suites configuration
      */
     suites?: {
+        /** Name of the test suite */
         name: string;
+        /** Glob pattern(s) for test files in this suite */
         files: string | string[];
     }[];
 };
 /**
- * Options needed to run a script file
+ * Options needed to run a script file as a child process
+ *
+ * @example
+ * const options: RunScriptOptions = {
+ *   script: 'bin/server.ts',
+ *   scriptArgs: ['--watch'],
+ *   nodeArgs: ['--loader', 'ts-node/esm'],
+ *   stdio: 'inherit',
+ *   env: { NODE_ENV: 'development' },
+ *   reject: true
+ * }
  */
 export type RunScriptOptions = {
-    /**
-     * Script to run
-     */
+    /** Path to the script file to run */
     script: string;
-    /**
-     * Arguments to pass to the script
-     */
+    /** Arguments to pass to the script */
     scriptArgs: string[];
-    /**
-     * Arguments to pass to NodeJS CLI
-     */
+    /** Arguments to pass to the Node.js CLI */
     nodeArgs: string[];
-    /**
-     * Standard input ouput stream options
-     */
+    /** Standard input/output stream options */
     stdio?: 'pipe' | 'inherit';
-    /**
-     * Environment variables to pass to the child process
-     */
+    /** Environment variables to pass to the child process */
     env?: NodeJS.ProcessEnv;
-    /**
-     * Whether or not to reject the promise. Defaults
-     * false
-     */
+    /** Whether to reject the promise on script failure (defaults to false) */
     reject?: boolean;
 };
 /**
- * Options accepted when starting the dev server
+ * Options accepted when starting the development server
+ *
+ * @example
+ * const devOptions: DevServerOptions = {
+ *   hmr: true,
+ *   scriptArgs: [],
+ *   nodeArgs: ['--inspect'],
+ *   clearScreen: true,
+ *   env: { DEBUG: 'adonis:*' },
+ *   hooks: {
+ *     devServerStarted: [() => import('./dev_hooks')]
+ *   }
+ * }
  */
 export type DevServerOptions = {
     /**
-     * If the dev server should use HMR.
-     *
-     * Default:true
+     * Whether the dev server should use Hot Module Replacement (HMR)
+     * @default true
      */
     hmr?: boolean;
     /**
-     * Arguments to pass to the "bin/server.js" file
-     * executed a child process
+     * Arguments to pass to the "bin/server.js" file executed as a child process
      */
     scriptArgs: string[];
     /**
-     * Arguments to pass to Node.js CLI when executing
-     * the "bin/server.js" file
+     * Arguments to pass to Node.js CLI when executing the "bin/server.js" file
      */
     nodeArgs: string[];
     /**
-     * Clear screen after every file change
+     * Whether to clear screen after every file change
      */
     clearScreen?: boolean;
     /**
-     * Environment variables to share with the "bin/server.js"
-     * file.
+     * Environment variables to share with the "bin/server.js" file
      */
     env?: NodeJS.ProcessEnv;
 } & AssemblerRcFile;
 /**
- * Options accepted by the test runner
+ * Options accepted by the test runner for configuring test execution
+ *
+ * @example
+ * const testOptions: TestRunnerOptions = {
+ *   scriptArgs: ['--reporter', 'spec'],
+ *   nodeArgs: ['--max-old-space-size=4096'],
+ *   clearScreen: true,
+ *   reporters: ['spec', 'json'],
+ *   timeout: 30000,
+ *   retries: 2,
+ *   failed: false,
+ *   filters: {
+ *     suites: ['unit', 'integration'],
+ *     tags: ['@slow']
+ *   }
+ * }
  */
 export type TestRunnerOptions = {
     /**
-     * Arguments to pass to the "bin/server.js" file
-     * executed a child process
+     * Arguments to pass to the test script file executed as a child process
      */
     scriptArgs: string[];
     /**
-     * Arguments to pass to Node.js CLI when executing
-     * the "bin/server.js" file
+     * Arguments to pass to Node.js CLI when executing the test script
      */
     nodeArgs: string[];
     /**
-     * Clear screen after every file change
+     * Whether to clear screen after every file change
      */
     clearScreen?: boolean;
     /**
-     * Environment variables to share with the "bin/server.js"
-     * file.
+     * Environment variables to share with the test script
      */
     env?: NodeJS.ProcessEnv;
     /**
-     * Set the tests runner reporter via the CLI flag
+     * Test reporters to use (e.g., 'spec', 'json', 'tap')
      */
     reporters?: string[];
     /**
-     * Set the tests global timeout via the CLI flag
+     * Global timeout for tests in milliseconds
      */
     timeout?: number;
     /**
-     * Define retries via the CLI flag
+     * Number of times to retry failed tests
      */
     retries?: number;
     /**
-     * Run only failed tests
+     * Whether to run only previously failed tests
      */
     failed?: boolean;
     /**
-     * Filter arguments are provided as a key-value
-     * pair, so that we can mutate them (if needed)
+     * Filter options for controlling which tests to run
      */
     filters: Partial<{
+        /** Specific test names to run */
         tests: string[];
+        /** Test suite names to run */
         suites: string[];
+        /** Test group names to run */
         groups: string[];
+        /** Specific test file patterns to run */
         files: string[];
+        /** Test tags to filter by */
         tags: string[];
     }>;
 } & AssemblerRcFile;
 /**
- * Options accepted by the project bundler
+ * Options accepted by the project bundler for production builds
+ * Extends AssemblerRcFile to inherit hooks and meta files configuration
+ *
+ * @example
+ * const bundlerOptions: BundlerOptions = {
+ *   hooks: {
+ *     buildStarting: [() => import('./build_hooks')]
+ *   },
+ *   metaFiles: [
+ *     { pattern: 'public/**', reloadServer: false }
+ *   ]
+ * }
  */
 export type BundlerOptions = AssemblerRcFile;
 /**
- * Keyboard shortcut definition
+ * Keyboard shortcut definition for development server interactions
+ *
+ * @example
+ * const shortcut: KeyboardShortcut = {
+ *   key: 'r',
+ *   description: 'restart server',
+ *   handler: () => server.restart()
+ * }
  */
 export interface KeyboardShortcut {
+    /** The keyboard key that triggers this shortcut */
     key: string;
+    /** Human-readable description of what this shortcut does */
     description: string;
+    /** Function to execute when the shortcut is triggered */
     handler: () => void;
 }
 /**
- * Callbacks for keyboard shortcuts actions
+ * Callbacks for keyboard shortcuts actions in the development server
+ *
+ * @example
+ * const callbacks: KeyboardShortcutsCallbacks = {
+ *   onRestart: () => devServer.restart(),
+ *   onClear: () => process.stdout.write('\u001B[2J\u001B[0;0f'),
+ *   onQuit: () => process.exit(0)
+ * }
  */
 export interface KeyboardShortcutsCallbacks {
+    /** Callback to restart the development server */
     onRestart: () => void;
+    /** Callback to clear the console screen */
     onClear: () => void;
+    /** Callback to quit the development server */
     onQuit: () => void;
 }
 /**
- * Shortcuts manager options
+ * Configuration options for the keyboard shortcuts manager
+ *
+ * @example
+ * const options: ShortcutsManagerOptions = {
+ *   logger: cliui().logger,
+ *   callbacks: {
+ *     onRestart: () => devServer.restart(),
+ *     onClear: () => console.clear(),
+ *     onQuit: () => process.exit()
+ *   }
+ * }
  */
 export interface ShortcutsManagerOptions {
+    /** Logger instance for displaying messages */
     logger: Logger;
+    /** Callback functions for different shortcut actions */
     callbacks: KeyboardShortcutsCallbacks;
 }

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

@@ -3,67 +3,280 @@ import { type AsyncOrSync, type LazyImport } from '@poppinss/utils/types';
 import { type Bundler } from '../bundler.ts';
 import { type DevServer } from '../dev_server.ts';
 import { type TestRunner } from '../test_runner.ts';
+import { type RoutesListItem } from './code_scanners.ts';
+import { type IndexGenerator } from '../index_generator/main.ts';
+import { type RoutesScanner } from '../code_scanners/routes_scanner/main.ts';
 /**
- * Hooks executed by the file watcher.
+ * Defines a hook that can be either a lazy import or an object with a run method.
+ * This type provides flexibility in how hooks are defined and imported, supporting
+ * both dynamic imports for code splitting and direct object definitions.
+ *
+ * @template Fn - The function signature that the hook must conform to
+ *
+ * @example
+ * // Using lazy import
+ * const hook: DefineHook<(server: DevServer) => void> = () => import('./my-hook')
+ *
+ * // Using direct object
+ * const hook: DefineHook<(server: DevServer) => void> = {
+ *   run: (server) => console.log('Hook executed')
+ * }
+ */
+type DefineHook<Fn extends (...args: any) => any> = LazyImport<Fn> | {
+    run: Fn;
+};
+/**
+ * Common hooks executed by the dev-server, test runner and the bundler.
+ * These hooks are shared across all assembler operations and provide
+ * lifecycle management for initialization tasks.
+ *
+ * @example
+ * const commonHooks: CommonHooks = {
+ *   init: [
+ *     () => import('./hooks/create_barrel_files')
+ *   ]
+ * }
+ */
+export type CommonHooks = {
+    /**
+     * The hook is executed as the first step when assembler starts the
+     * dev-server, runs tests or creates a build. Use this hook to perform
+     * initialization tasks that are common across all operations.
+     *
+     * @param parent - The parent instance (DevServer, TestRunner, or Bundler)
+     */
+    init: DefineHook<(parent: DevServer | TestRunner | Bundler, indexGenerator: IndexGenerator) => AsyncOrSync<void>>[];
+};
+/**
+ * Hooks executed by the dev server around the router.
+ * These hooks provide lifecycle management for route scanning and processing.
+ *
+ * @example
+ * const routerHooks: RouterHooks = {
+ *   routesCommitted: [
+ *     () => import('./hooks/on_routes_committed')
+ *   ],
+ *   routesScanning: [
+ *     () => import('./hooks/before_routes_scan')
+ *   ],
+ *   routesScanned: [
+ *     () => import('./hooks/after_routes_scan')
+ *   ]
+ * }
+ */
+export type RouterHooks = {
+    /**
+     * The hook is executed when routes are committed by the dev server child
+     * process. Use this hook to react to route changes and perform related tasks.
+     *
+     * @param parent - The DevServer instance
+     * @param routes - Record of routes grouped by domain or method
+     */
+    routesCommitted: DefineHook<(parent: DevServer, routes: Record<string, RoutesListItem[]>) => AsyncOrSync<void>>[];
+    /**
+     * The hook is executed when dev server begins the routes scanning process.
+     * Use this hook to prepare for route scanning or modify scanner configuration.
+     *
+     * @param parent - The DevServer instance
+     * @param routesScanner - The RoutesScanner instance being used
+     */
+    routesScanning: DefineHook<(parent: DevServer, routesScanner: RoutesScanner) => AsyncOrSync<void>>[];
+    /**
+     * The hook is executed when routes scanning process has finished.
+     * Use this hook to process the scanned routes or clean up resources.
+     *
+     * @param parent - The DevServer instance
+     * @param routesScanner - The RoutesScanner instance that was used
+     */
+    routesScanned: DefineHook<(parent: DevServer, routesScanner: RoutesScanner) => AsyncOrSync<void>>[];
+};
+/**
+ * Hooks executed by the file watcher during development and testing.
  *
  * - In HMR mode, assembler will rely on hot-hook to notify about the filesystem changes.
  * - Otherwise, the inbuilt watcher of the DevServer or the TestsRunner will notify.
+ *
+ * @example
+ * const watcherHooks: WatcherHooks = {
+ *   fileChanged: [
+ *     () => import('./hooks/on_file_changed')
+ *   ],
+ *   fileAdded: [
+ *     () => import('./hooks/on_file_added')
+ *   ],
+ *   fileRemoved: [
+ *     () => import('./hooks/on_file_removed')
+ *   ]
+ * }
  */
 export type WatcherHooks = {
     /**
-     * The hook is executed after a file has been changed in the watch mode.
+     * The hook is executed after a file has been changed in watch mode.
+     * Provides information about the change source and reload behavior.
+     * Use this hook to react to file changes and trigger custom actions.
+     *
+     * @param filePath - The relative path to the changed file
+     * @param info - Information about the file change
+     * @param info.source - Source of the file change notification
+     * @param info.hotReloaded - Whether the file was hot reloaded without server restart
+     * @param info.fullReload - Whether a full server reload is required
+     * @param parent - The parent DevServer or TestRunner instance
      */
-    fileChanged: LazyImport<(filePath: string, info: {
+    fileChanged: DefineHook<(relativePath: string, absolutePath: string, info: {
+        /** Source of the file change notification */
         source: 'hot-hook' | 'watcher';
+        /** Whether the file was hot reloaded without server restart */
         hotReloaded: boolean;
+        /** Whether a full server reload is required */
         fullReload: boolean;
-    }, server: DevServer | TestRunner) => AsyncOrSync<void>>[];
+    }, parent: DevServer | TestRunner) => AsyncOrSync<void>>[];
     /**
-     * The hook is executed after a file has been added.
+     * The hook is executed after a file has been added to the filesystem.
+     * Use this hook to react to new files being added to the project.
+     *
+     * @param filePath - The absolute path to the added file
+     * @param server - The DevServer or TestRunner instance
      */
-    fileAdded: LazyImport<(filePath: string, server: DevServer | TestRunner) => AsyncOrSync<void>>[];
+    fileAdded: DefineHook<(relativePath: string, absolutePath: string, server: DevServer | TestRunner) => AsyncOrSync<void>>[];
     /**
-     * The hook is executed after a file has been removed.
+     * The hook is executed after a file has been removed from the filesystem.
+     * Use this hook to clean up resources or update caches when files are deleted.
+     *
+     * @param filePath - The absolute path to the removed file
+     * @param server - The DevServer or TestRunner instance
      */
-    fileRemoved: LazyImport<(filePath: string, server: DevServer | TestRunner) => AsyncOrSync<void>>[];
+    fileRemoved: DefineHook<(relativePath: string, absolutePath: string, server: DevServer | TestRunner) => AsyncOrSync<void>>[];
 };
 /**
- * Hooks executed when running the dev server.
+ * Hooks executed when running the development server.
+ *
+ * @example
+ * const devServerHooks: DevServerHooks = {
+ *   devServerStarting: [
+ *     () => import('./hooks/before_dev_server_start')
+ *   ],
+ *   devServerStarted: [
+ *     () => import('./hooks/after_dev_server_start')
+ *   ]
+ * }
  */
 export type DevServerHooks = {
     /**
-     * The hook is executed before the child process for the dev server
-     * is started.
+     * The hook is executed before the child process for the dev server is started.
+     * Use this hook to perform setup tasks or modify server configuration.
+     *
+     * @param server - The DevServer instance that is about to start
      */
-    devServerStarting: LazyImport<(server: DevServer) => AsyncOrSync<void>>[];
+    devServerStarting: DefineHook<(server: DevServer) => AsyncOrSync<void>>[];
     /**
      * The hook is executed after the child process has been started.
+     * Use this hook to display additional information or perform post-startup tasks.
+     *
+     * @param server - The DevServer instance that has started
+     * @param info - Server information containing port and host
+     * @param info.port - The port number the server is running on
+     * @param info.host - The host address the server is bound to
+     * @param uiInstructions - UI instructions for displaying server information
      */
-    devServerStarted: LazyImport<(server: DevServer, uiInstructions: Instructions) => AsyncOrSync<void>>[];
+    devServerStarted: DefineHook<(server: DevServer, info: {
+        port: number;
+        host: string;
+    }, uiInstructions: Instructions) => AsyncOrSync<void>>[];
 };
 /**
  * Hooks executed when the production build is created.
+ *
+ * @example
+ * const bundlerHooks: BundlerHooks = {
+ *   buildStarting: [
+ *     () => import('./hooks/before_build')
+ *   ],
+ *   buildFinished: [
+ *     () => import('./hooks/after_build')
+ *   ]
+ * }
  */
 export type BundlerHooks = {
     /**
-     * The hook is executed before we begin creating the production build
+     * The hook is executed before we begin creating the production build.
+     * Use this hook to perform pre-build tasks like asset optimization.
+     *
+     * @param server - The Bundler instance that will create the build
      */
-    buildStarting: LazyImport<(server: Bundler) => AsyncOrSync<void>>[];
+    buildStarting: DefineHook<(server: Bundler) => AsyncOrSync<void>>[];
     /**
-     * The hook is executed after the production build has been created
+     * The hook is executed after the production build has been created.
+     * Use this hook to perform post-build tasks or display build statistics.
+     *
+     * @param server - The Bundler instance that created the build
+     * @param uiInstructions - UI instructions for displaying build information
      */
-    buildFinished: LazyImport<(server: Bundler, uiInstructions: Instructions) => AsyncOrSync<void>>[];
+    buildFinished: DefineHook<(server: Bundler, uiInstructions: Instructions) => AsyncOrSync<void>>[];
 };
 /**
- * Hooks executed when running the tests
+ * Hooks executed when running the test suite.
+ *
+ * @example
+ * const testRunnerHooks: TestRunnerHooks = {
+ *   testsStarting: [
+ *     () => import('./hooks/before_tests')
+ *   ],
+ *   testsFinished: [
+ *     () => import('./hooks/after_tests')
+ *   ]
+ * }
  */
 export type TestRunnerHooks = {
     /**
-     * The hook is executed before we begin executing the tests
+     * The hook is executed before we begin executing the tests.
+     * Use this hook to set up test databases or perform pre-test setup.
+     *
+     * @param server - The TestRunner instance that will execute the tests
      */
-    testsStarting: LazyImport<(server: TestRunner) => AsyncOrSync<void>>[];
+    testsStarting: DefineHook<(server: TestRunner) => AsyncOrSync<void>>[];
     /**
-     * The hook is executed after the tests have been executed
+     * The hook is executed after the tests have been executed.
+     * Use this hook to clean up resources or generate test reports.
+     *
+     * @param server - The TestRunner instance that executed the tests
      */
-    testsFinished: LazyImport<(server: TestRunner) => AsyncOrSync<void>>[];
+    testsFinished: DefineHook<(server: TestRunner) => AsyncOrSync<void>>[];
 };
+/**
+ * Combined type representing all available hooks across the assembler ecosystem.
+ * This intersection type merges all hook categories into a single type for
+ * comprehensive hook management and type safety.
+ *
+ * @example
+ * ```js
+ * const allHooks: AllHooks = {
+ *   init: [() => import('./hooks/init')],
+ *   fileChanged: [() => import('./hooks/file_changed')],
+ *   devServerStarted: [() => import('./hooks/dev_server_started')],
+ *   buildFinished: [() => import('./hooks/build_finished')],
+ *   testsFinished: [() => import('./hooks/tests_finished')],
+ *   routesCommitted: [() => import('./hooks/routes_committed')]
+ * }
+ * ```
+ */
+export type AllHooks = CommonHooks & WatcherHooks & DevServerHooks & BundlerHooks & TestRunnerHooks & RouterHooks;
+/**
+ * Utility type that extracts the parameter types for a specific hook.
+ * This type helps maintain type safety when working with hook callbacks
+ * by providing the exact parameter signature for any given hook name.
+ *
+ * @template Hook - The name of the hook to extract parameters for
+ *
+ * @example
+ * ```js
+ * // Get parameters for the fileChanged hook
+ * type FileChangedParams = HookParams<'fileChanged'>
+ * // Result: [string, string, {...}, DevServer | TestRunner]
+ *
+ * // Get parameters for the devServerStarted hook
+ * type DevServerStartedParams = HookParams<'devServerStarted')
+ * // Result: [DevServer, {port: number, host: string}, Instructions]
+ * ```
+ */
+export type HookParams<Hook extends keyof AllHooks> = AllHooks[Hook][number] extends DefineHook<infer A> ? Parameters<A> : never;
+export {};