@megaorm/cli/dist/handlers/GeneratorHandler.d.ts

This package allows you to communicate with MegaORM via commands directly from the command line interface (CLI).

import { MegaBuilder } from '@megaorm/builder';
/**
 * Custom error class for handling errors related to the generator operations.
 *
 * This error is thrown when there are issues with generator entries,
 * such as invalid paths or batch numbers, ensuring that the errors can be
 * distinguished from other types of errors in the application.
 */
export declare class GeneratorHandlerError extends Error {
}
/**
 * The `GeneratorHandler` class is responsible for managing operations related to database
 * generators. It provides functionality to add, remove, execute, and roll back generator files
 * that create or drop tables, ensuring consistent and reliable execution of generation tasks.
 *
 * This class encapsulates the logic required for handling file-based database generation,
 * ensuring consistent operations across tables and generator files.
 *
 */
export declare class GeneratorHandler {
    /**
     * Rows inserted into the generators table.
     */
    private rows;
    /**
     * The database builder instance used for executing queries.
     */
    private builder;
    /**
     * The absolute path to the assets directory.
     */
    private assets;
    /**
     * Creates a new handler instance with the specified database builder.
     *
     * @param builder The database builder instance used for constructing queries.
     * @throws `GeneratorHandlerError` if the provided builder is not a valid instance of `MegaBuilder`.
     */
    constructor(builder: MegaBuilder);
    /**
     * Collects the absolute paths of generator files from the specified directory.
     *
     * @param path The directory path from which to collect generator files.
     * @param map A boolean indicating whether to include mapped files (e.g., `.js.map`) in the resulting paths.
     * @returns A promise that resolves with an array of absolute paths to valid generator files.
     * @throws GeneratorHandlerError if there is an issue collecting the files or if an invalid generator file is encountered.
     */
    private collectPaths;
    /**
   * Collects exported generator instances from the specified file paths.
   *
   * This method attempts to require each file listed in the provided array of
   * paths. It expects each file to export either a default instance of `MegaGenerator`
   * or a named generator instance. If any of the files do not conform to these
   * expectations, an error will be thrown.
   *
   * ### Behavior
   * - If no paths are provided or if no valid generators are found, a
   *   `GeneratorHandlerError` is thrown with a relevant message.
   * - For each path, the method tries to:
   *   - Import the module using `require`.
   *   - Check if the imported module is a valid `MegaGenerator` instance.
   *   - If the module exports a named generator, it will check for the first
   *     property and validate it as a `MegaGenerator`.
  
   *
   * @param paths An array absolute paths to your generator files.
   * @returns An array of `MegaGenerator` instances collected from the specified file paths.
   * @throws `GeneratorHandlerError` if no generators are found or if an invalid generator is encountered in any of the specified paths.
   */
    private collectGenerators;
    /**
     * Loads data from the `generators` table or creates the table if it does not exist.
     *
     * This method attempts to retrieve all rows from the `generators` table, storing
     * them in the `this.rows` property. If the `generators` table does not exist,
     * it catches the resulting error and initializes a new `Generator` instance to
     * create the table. This method is useful for ensuring that the necessary
     * table structure is available before performing further actions.
     *
     * @returns Promise resolves once the table data is loaded into `this.rows` or the table is created.
     */
    private load;
    /**
     * Creates tables based on the provided generator files and records their creation in the database.
     *
     * This method sequentially invokes the `create` method on each generator instance in the `paths` array.
     * The method also maintains a record of successfully created tables in the `created` array.
     * If any table fails to be created, the remaining tables in the sequence are not created.
     *
     * @param paths An array of paths to generator files that define the tables to be created.
     * @param batch A batch number i use to group the created tables togother for future rollback.
     * @returns A promise that resolves with a message indicating the number of tables created successfully.
     * @throws `GeneratorHandlerError` If any generator does not contain a valid `create` method or if an
     * error occurs during table creation or batch recording.
     */
    private createTables;
    /**
     * Drops tables based on the provided generator files and records their removal from the database.
     *
     * This method sequentially invokes the `drop` method on each generator instance in the `paths` array.
     * Successfully dropped tables are recorded in the `dropped` array. If any table fails to be
     * dropped, the remaining tables in the sequence are not dropped.
     *
     * @param paths An array of paths to generator files that define the tables to be dropped.
     * @returns A promise that resolves with a message indicating the number of tables dropped successfully.
     * @throws `GeneratorHandlerError` If any generator does not contain a valid `drop` method or if an
     * error occurs during table removal or record deletion.
     */
    private dropTables;
    /**
     * Prepares the handler to create new tables by:
     * - Finding paths to all generator files
     * - Filtering out files that have already been run, so only unexecuted generators left
     * - Assigning a new batch number for tracking
     *
     * @param path The main folder where generator files are located.
     * @returns A promise that resolves with the new batch number and paths to pending generators.
     * @throws `GeneratorHandlerError` If there are no new generators to run or if loading data or paths fails.
     */
    private beReadyToGenerate;
    /**
     * Prepares the handler to drop tables by:
     * - Retrieving the highest batch number
     * - Collecting paths of all generators in that batch
     *
     * @note Paths are reversed to ensure tables are dropped in the correct order.
     * @returns A promise that resolves with paths to the generator files in the latest batch.
     * @throws `GeneratorHandlerError` If there are no files to rollback or if loading data fails.
     */
    private beReadyToRollback;
    /**
     * Executes the `create` method for each unexecuted generator to create tables.
     *
     * @param path The main folder where generator files are located.
     * @returns A promise that resolves with a success message if tables are created successfully.
     * @throws `GeneratorHandlerError` If any error occurs during preparation or table creation.
     */
    generate(path: string): Promise<string>;
    /**
     * Executes the `drop` method for each generator associated with the highest batch number.
     *
     * This method ensures that only the tables created in the most recent batch are dropped,
     * preserving any tables created in earlier batches. This allows for targeted rollback of
     * the last set of generator executions without affecting previously created tables.
     *
     * @returns A promise that resolves with a success message if tables are dropped successfully.
     * @throws `GeneratorHandlerError` If any error occurs during preparation or table dropping.
     */
    rollback(): Promise<string>;
    /**
     * Creates a new generator file in the specified path.
     *
     * This method generates a new file for the specified table name in the given directory path.
     * You can choose to create a TypeScript file or a JavaScript file based on the provided boolean flag.
     *
     * @param name The snake_case table name for which the generator is created.
     * @param path The directory path where the generator file will be created.
     * @param ts A boolean indicating whether to create a TypeScript file (`true`) or a JavaScript file (`false`).
     * @returns A promise that resolves with a success message indicating the path of the created generator file.
     * @throws `GeneratorHandlerError` If the table name is invalid, the path is empty, or if any errors occur during file operations.
     * @note The table name must be a snake_case table name, e.g., users, category_product.
     */
    add(name: string, path: string, ts?: boolean): Promise<string>;
    /**
     * Removes the generator associated with the given table name from the specified folder path.
     *
     * This method first drops all tables in the database using the `reset` method, then removes
     * the generator file for the specified table, and finally updates the numbering of each remaining
     * generator file in the folder.
     *
     * @param name The snake_case table name whose associated generator is to be removed.
     * @param path The directory path where the generator files are located.
     * @returns A promise that resolves with a success message indicating how many generator files were removed.
     * @throws `GeneratorHandlerError` If the table name is invalid, the path is empty.
     * @note The table name must be a snake_case table name, e.g., users, category_product.
     */
    remove(name: string, path: string): Promise<string>;
    /**
     * Resets the database by dropping all tables associated with the generator files
     * in the specified directory.
     *
     * @param path The directory path where the generator files are located.
     * @returns A promise that resolves with a success message indicating how many tables were dropped.
     * @throws `GeneratorHandlerError` If there are no tables to reset.
     * @note This method will continue dropping tables even if some errors occur (e.g., if a table does not exist).
     */
    reset(path: string): Promise<string>;
}