@adonisjs/assembler 8.0.0-next.0 → 8.0.0-next.10

package/README.md

@@ -50,17 +50,7 @@ const devServer = new DevServer(appRoot, {
       pattern: 'resources/views/**/*.edge',
       reloadServer: false,
     }
-  ],
-
-  /**
-   * The assets bundler process to start
-   */
-  assets: {
-    enabled: true,
-    name: 'vite',
-    cmd: 'vite',
-    args: []
-  }
+  ]
 })
 
 devServer.onError((error) => {
@@ -87,9 +77,6 @@ await devServer.start()
 ## Test runner
 The `TestRunner` is used to execute the `bin/test.ts` file of your AdonisJS application. Like the `DevServer`, the `TestRunner` allows you to watch for file changes and re-run the tests. The following steps are taken to re-run tests in watch mode.
 
-> [!NOTE]  
-> Read [Using a file watcher](#using-a-file-watcher) section to understand which files are watched by the file watcher.
-
 - If the changed file is a test file, only tests for that file will be re-run.
 - Otherwise, all tests will re-run with respect to the initial filters applied when running the `node ace test` command.
 
@@ -176,17 +163,6 @@ const bundler = new Bundler(appRoot, ts, {
       reloadServer: false,
     }
   ],
-
-  /**
-   * The assets bundler to use to bundle the frontend
-   * assets
-   */
-  assets: {
-    enabled: true,
-    name: 'vite',
-    cmd: 'vite',
-    args: ['build']
-  }
 })
 ```
 
@@ -444,6 +420,113 @@ export const policies = {
 }
 ```
 
+## Index generator
+
+The `IndexGenerator` is a core concept in Assembler that is used to watch the filesystem and create barrel files or types from a source directory.
+
+For example, the core of the framework uses the following config to generate controllers, events, and listeners barrel file.
+
+```ts
+import hooks from '@adonisjs/assembler/hooks'
+
+export default hooks.init((type, parent, indexGenerator) => {
+  indexGenerator.add('controllers', {
+    source: './app/controllers',
+    importAlias: '#controllers',
+    as: 'barrelFile',
+    exportName: 'controllers',
+    removeSuffix: 'controllers',
+    output: './.adonisjs/server/controllers.ts',
+  })
+
+  indexGenerator.add('events', {
+    source: './app/events',
+    importAlias: '#events',
+    as: 'barrelFile',
+    exportName: 'events',
+    output: './.adonisjs/server/events.ts',
+  })
+
+  indexGenerator.add('listeners', {
+    source: './app/listeners',
+    importAlias: '#listeners',
+    as: 'barrelFile',
+    exportName: 'listeners',
+    removeSuffix: 'listener',
+    output: './.adonisjs/server/listeners.ts',
+  })
+})
+```
+
+Once the configurations have been registered with the `IndexGenerator`, it will scan the needed directories and generate the output files. Additionally, the file watchers will re-trigger the index generation when a file is added or removed from the source directory.
+
+### Barrel file generation
+
+Barrel files provide a single entry point by exporting a collection of lazily imported entities, recursively gathered from a source directory. The `IndexGenerator` automates this process by scanning nested directories and generating import mappings that mirror the file structure.
+
+For example, given the following `controllers` directory structure:
+
+```sh
+app/controllers/
+├── auth/
+│   ├── login_controller.ts
+│   └── register_controller.ts
+├── blog/
+│   ├── posts_controller.ts
+│   └── post_comments_controller.ts
+└── users_controller.ts
+```
+
+When processed with the controllers configuration, the `IndexGenerator` produces a barrel file that reflects the directory hierarchy as nested objects, using capitalized file names as property keys.
+
+```ts
+export const controllers = {
+  auth: {
+    Login: () => import('#controllers/auth/login_controller'),
+    Register: () => import('#controllers/auth/register_controller'),
+  },
+  blog: {
+    Posts: () => import('#controllers/blog/posts_controller'),
+    PostComments: () => import('#controllers/blog/post_comments_controller'),
+  },
+  Users: () => import('#controllers/users_controller'),
+}
+```
+
+### Types generation
+
+To generate a types file, register a custom callback that takes an instance of the `VirtualFileSystem` and updates the output string via the `buffer` object. 
+
+The collection is represented as key–value pairs:
+
+- **Key** — the relative path (without extension) from the root of the source directory.
+- **Value** — an object containing the file's `importPath`, `relativePath`, and `absolutePath`.
+
+```ts
+import hooks from '@adonisjs/assembler/hooks'
+
+export default hooks.init((type, parent, indexGenerator) => {
+  indexGenerator.add('inertiaPages', {
+    source: './inertia/pages',
+    as: (vfs, buffer) => {
+      buffer.write(`declare module '@adonisjs/inertia' {`).indent()
+      buffer.write(`export interface Pages {`).indent()
+
+      const files = vfs.asList()
+      Object.keys(files).forEach((filePath) => {
+        buffer.write(
+          `'${filePath}': InferPageProps<typeof import('${file.importPath}').default>`
+        )
+      })
+
+      buffer.dedent().write('}')
+      buffer.dedent().write('}')
+    },
+    output: './.adonisjs/server/inertia_pages.d.ts',
+  })
+})
+```
+
 ## Contributing
 One of the primary goals of AdonisJS is to have a vibrant community of users and contributors who believe in the framework's principles.
 

package/build/chunk-EWPEL2ET.js

@@ -0,0 +1,433 @@
+import {
+  VirtualFileSystem,
+  debug_default,
+  removeExtension,
+  throttle
+} from "./chunk-MVIHDM7A.js";
+
+// src/index_generator/source.ts
+import string from "@poppinss/utils/string";
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, join, relative } from "path/posix";
+import StringBuilder from "@poppinss/utils/string_builder";
+
+// src/file_buffer.ts
+var FileBuffer = class _FileBuffer {
+  /**
+   * Collected lines
+   */
+  #buffer = [];
+  /**
+   * Current indentation size. Each call to indent will increment
+   * it by 2
+   */
+  #identationSize = 0;
+  /**
+   * Cached compiled output. Once this value is set, the `flush`
+   * method will become a noop
+   */
+  #compiledOutput;
+  /**
+   * Creates a new child buffer instance
+   *
+   * @returns A new FileBuffer instance
+   */
+  create() {
+    return new _FileBuffer();
+  }
+  /**
+   * Returns the size of buffer text
+   *
+   * @returns The number of lines in the buffer
+   */
+  get size() {
+    return this.#buffer.length;
+  }
+  /**
+   * Write a new line to the output with current indentation
+   *
+   * @param text - The text to write as a new line
+   * @returns This FileBuffer instance for method chaining
+   */
+  writeLine(text) {
+    if (typeof text === "string") {
+      this.#buffer.push(`${" ".repeat(this.#identationSize)}${text}
+`);
+    } else {
+      this.#buffer.push(text);
+      this.#buffer.push("");
+    }
+    return this;
+  }
+  /**
+   * Write text to the output without adding a new line
+   *
+   * @param text - The text to write without a newline
+   * @returns This FileBuffer instance for method chaining
+   */
+  write(text) {
+    if (typeof text === "string") {
+      this.#buffer.push(`${" ".repeat(this.#identationSize)}${text}`);
+    } else {
+      this.#buffer.push(text);
+    }
+    return this;
+  }
+  /**
+   * Increase indentation by 2 spaces
+   *
+   * @returns This FileBuffer instance for method chaining
+   */
+  indent() {
+    this.#identationSize += 2;
+    return this;
+  }
+  /**
+   * Decrease indentation by 2 spaces (minimum of 0)
+   *
+   * @returns This FileBuffer instance for method chaining
+   */
+  dedent() {
+    this.#identationSize -= 2;
+    if (this.#identationSize < 0) {
+      this.#identationSize = 0;
+    }
+    return this;
+  }
+  toString() {
+    return this.flush();
+  }
+  /**
+   * Return template as a string, joining all buffer lines
+   *
+   * Once called, the output is cached and subsequent calls return the same result.
+   * The flush method becomes a no-op after the first call.
+   *
+   * @returns The complete buffer content as a string
+   */
+  flush() {
+    if (this.#compiledOutput !== void 0) {
+      return this.#compiledOutput;
+    }
+    this.#compiledOutput = this.#buffer.join("\n");
+    return this.#compiledOutput;
+  }
+};
+
+// src/index_generator/source.ts
+var IndexGeneratorSource = class {
+  /**
+   * The application root directory path
+   */
+  #appRoot;
+  /**
+   * The absolute path to the output file
+   */
+  #output;
+  /**
+   * The absolute path to the source directory
+   */
+  #source;
+  /**
+   * The directory containing the output file
+   */
+  #outputDirname;
+  /**
+   * Virtual file system for scanning source files
+   */
+  #vfs;
+  /**
+   * Configuration for this index generator source
+   */
+  #config;
+  /**
+   * CLI logger instance for output messages
+   */
+  #cliLogger;
+  /**
+   * Generate the output content and write it to the output file
+   *
+   * This method creates the file buffer, populates it with the generated
+   * content based on configuration, and writes it to disk.
+   */
+  #generateOutput = throttle(async () => {
+    const buffer = new FileBuffer();
+    if (this.#config.as === "barrelFile") {
+      this.#asBarrelFile(
+        this.#vfs,
+        buffer,
+        this.#config.exportName,
+        this.#config.disableLazyImports
+      );
+    } else {
+      this.#config.as(this.#vfs, buffer, this.#config, {
+        toImportPath: this.#createBarrelFileImportGenerator(
+          this.#source,
+          this.#outputDirname,
+          this.#config
+        )
+      });
+    }
+    await mkdir(dirname(this.#output), { recursive: true });
+    await writeFile(this.#output, buffer.flush());
+  });
+  /**
+   * Unique name for this index generator source
+   */
+  name;
+  /**
+   * Create a new IndexGeneratorSource instance
+   *
+   * @param name - Unique name for this index generator source
+   * @param appRoot - The application root directory path
+   * @param cliLogger - Logger instance for CLI output
+   * @param config - Configuration for this index generator source
+   */
+  constructor(name, appRoot, cliLogger, config) {
+    this.name = name;
+    this.#config = config;
+    this.#appRoot = appRoot;
+    this.#cliLogger = cliLogger;
+    this.#source = join(this.#appRoot, this.#config.source);
+    this.#output = join(this.#appRoot, this.#config.output);
+    this.#outputDirname = dirname(this.#output);
+    this.#vfs = new VirtualFileSystem(this.#source, {
+      glob: this.#config.glob
+    });
+  }
+  /**
+   * Converts a recursive file tree to a string representation
+   *
+   * This method recursively processes a file tree structure and writes
+   * it as JavaScript object notation to the provided buffer.
+   *
+   * @param input - The recursive file tree to convert
+   * @param buffer - The file buffer to write the output to
+   */
+  #treeToString(input, buffer) {
+    Object.keys(input).forEach((key) => {
+      const value = input[key];
+      if (typeof value === "string") {
+        buffer.write(`${key}: ${value},`);
+      } else {
+        buffer.write(`${key}: {`).indent();
+        this.#treeToString(value, buffer);
+        buffer.dedent().write(`},`);
+      }
+    });
+  }
+  /**
+   * Transforms the barrel file index key. Converts basename to PascalCase
+   * and all other paths to camelCase
+   *
+   * @param config - Configuration containing suffix removal options
+   * @returns Function that transforms file paths to appropriate keys
+   */
+  #createBarrelFileKeyGenerator(config) {
+    return function(key) {
+      const paths = key.split("/");
+      let baseName = new StringBuilder(paths.pop());
+      if (config.computeBaseName) {
+        baseName = config.computeBaseName(baseName);
+      } else {
+        baseName = baseName.removeSuffix(config.removeSuffix ?? "").pascalCase();
+      }
+      return [...paths.map((p) => string.camelCase(p)), baseName.toString()].join("/");
+    };
+  }
+  /**
+   * Converts the file path to a lazy import. In case of an alias, the source
+   * path is replaced with the alias, otherwise a relative import is created
+   * from the output dirname.
+   *
+   * @param source - The source directory path
+   * @param outputDirname - The output directory path
+   * @param config - Configuration containing import alias options
+   * @returns Function that converts file paths to import statements
+   */
+  #createBarrelFileImportGenerator(source, outputDirname, config) {
+    return function(filePath) {
+      if (config.importAlias) {
+        debug_default('converting "%s" to import alias, source "%s"', filePath, source);
+        return removeExtension(filePath.replace(source, config.importAlias));
+      }
+      debug_default('converting "%s" to relative import, source "%s"', filePath, outputDirname);
+      return relative(outputDirname, filePath);
+    };
+  }
+  /**
+   * Generate a barrel file export structure
+   *
+   * This method creates a nested object structure that represents all
+   * discovered files as lazy imports, organized by directory structure.
+   *
+   * @param vfs - Virtual file system containing the scanned files
+   * @param buffer - File buffer to write the barrel exports to
+   * @param exportName - Name for the main export object
+   */
+  #asBarrelFile(vfs, buffer, exportName, disableLazyImports) {
+    const useEagerImports = disableLazyImports === true ? true : false;
+    const keyGenerator = this.#createBarrelFileKeyGenerator(this.#config);
+    const importsBuffer = buffer.create();
+    const importGenerator = this.#createBarrelFileImportGenerator(
+      this.#source,
+      this.#outputDirname,
+      this.#config
+    );
+    const tree = vfs.asTree({
+      transformKey: keyGenerator,
+      transformValue: (filePath, key) => {
+        if (useEagerImports) {
+          const importKey = new StringBuilder(key).pascalCase().toString();
+          importsBuffer.write(`import ${importKey} from '${importGenerator(filePath)}'`);
+          return importKey;
+        }
+        return `() => import('${importGenerator(filePath)}')`;
+      }
+    });
+    if (useEagerImports) {
+      buffer.writeLine(importsBuffer);
+    }
+    buffer.write(`export const ${exportName} = {`).indent();
+    this.#treeToString(tree, buffer);
+    buffer.dedent().write(`}`);
+  }
+  /**
+   * Create a log action for tracking file generation progress
+   *
+   * @example
+   * const action = this.#createLogAction()
+   * // ... perform operations
+   * action.displayDuration().succeeded()
+   */
+  #createLogAction() {
+    return this.#cliLogger.action(`create ${this.#config.output}`);
+  }
+  /**
+   * Add a file to the virtual file system and regenerate index if needed
+   *
+   * If the file matches the configured glob patterns, it will be added
+   * to the virtual file system and the index file will be regenerated.
+   *
+   * @param filePath - Absolute path of the file to add
+   */
+  async addFile(filePath) {
+    const added = this.#vfs.add(filePath);
+    if (added) {
+      debug_default('file added, re-generating "%s" index', this.name);
+      const action = this.#createLogAction();
+      await this.#generateOutput();
+      action.displayDuration().succeeded();
+    }
+  }
+  /**
+   * Remove a file from the virtual file system and regenerate index if needed
+   *
+   * If the file was previously tracked, it will be removed from the
+   * virtual file system and the index file will be regenerated.
+   *
+   * @param filePath - Absolute path of the file to remove
+   */
+  async removeFile(filePath) {
+    const removed = this.#vfs.remove(filePath);
+    if (removed) {
+      debug_default('file removed, re-generating "%s" index', this.name);
+      const action = this.#createLogAction();
+      await this.#generateOutput();
+      action.displayDuration().succeeded();
+    }
+  }
+  /**
+   * Generate the index file
+   *
+   * This method scans the source directory, processes files according to
+   * the configuration, and writes the generated index file to disk.
+   */
+  async generate() {
+    const action = this.#createLogAction();
+    await this.#vfs.scan();
+    await this.#generateOutput();
+    action.displayDuration().succeeded();
+  }
+};
+
+// src/index_generator/main.ts
+var IndexGenerator = class {
+  /**
+   * The application root directory path
+   */
+  appRoot;
+  /**
+   * Collection of registered index generator sources
+   */
+  #sources = {};
+  #cliLogger;
+  /**
+   * Create a new IndexGenerator instance
+   *
+   * @param appRoot - The application root directory path
+   * @param cliLogger - Logger instance for CLI output
+   */
+  constructor(appRoot, cliLogger) {
+    this.appRoot = appRoot;
+    this.#cliLogger = cliLogger;
+  }
+  /**
+   * Add a new index generator source
+   *
+   * @param name - Unique name for the source
+   * @param config - Configuration for the index generator source
+   * @returns This IndexGenerator instance for method chaining
+   */
+  add(name, config) {
+    this.#sources[name] = new IndexGeneratorSource(name, this.appRoot, this.#cliLogger, config);
+    return this;
+  }
+  /**
+   * Add a file to all registered index generator sources
+   *
+   * This method propagates the file addition to all registered sources,
+   * allowing them to regenerate their index files if the new file matches
+   * their glob patterns.
+   *
+   * @param filePath - Absolute path of the file to add
+   */
+  async addFile(filePath) {
+    const sources = Object.values(this.#sources);
+    for (let source of sources) {
+      await source.addFile(filePath);
+    }
+  }
+  /**
+   * Remove a file from all registered index generator sources
+   *
+   * This method propagates the file removal to all registered sources,
+   * allowing them to regenerate their index files if the removed file
+   * was previously tracked.
+   *
+   * @param filePath - Absolute path of the file to remove
+   */
+  async removeFile(filePath) {
+    const sources = Object.values(this.#sources);
+    for (let source of sources) {
+      await source.removeFile(filePath);
+    }
+  }
+  /**
+   * Generate all registered index files
+   *
+   * Iterates through all registered sources and generates their
+   * corresponding index files.
+   */
+  async generate() {
+    const sources = Object.values(this.#sources);
+    for (let source of sources) {
+      await source.generate();
+    }
+  }
+};
+
+export {
+  FileBuffer,
+  IndexGenerator
+};