bs3m/dist/types/migration.d.ts

TS/JS migrations framework for sqlite3 databases

/** Migration interface definitions. */
import type { Database } from 'better-sqlite3';
/** Base interface for all migrations. */
export interface MigrationBase<T extends string[]> {
    /**
     * List of database keys affected by this migration.
     *
     * Each key must have a matching configuration in the global config.
     */
    dbs: T;
    /** Plain text description of the migration. */
    description: string;
    /** Arbitrary metadata for the migration. */
    metadata?: object;
}
/** Type helper for database connections mapping. */
export type Connections<T extends string[]> = {
    [K in T[number]]: Database;
};
/**
 * Migration interface for connections mode (default). Each database gets its
 * own connection handle.
 */
export interface ConnectionsMigration<T extends string[]> extends MigrationBase<T> {
    /** Migration mode identifier. Optional for the "connections" mode. */
    mode?: 'connections';
    /**
     * Applies the migration changes to the databases. Executed within an implicit
     * transaction for each database.
     *
     * @param connections - Map of database keys to Database instances.
     * @returns True to commit the migration, false or thrown error to abort.
     */
    up: (connections: Connections<T>) => boolean;
    /**
     * Reverts the migration changes from the databases. Executed within an
     * implicit transaction for each database.
     *
     * @param connections - Map of database keys to Database instances.
     * @returns True to commit the rollback, false or thrown error to abort.
     */
    down: (connections: Connections<T>) => boolean;
    /**
     * Optional validation method to verify migration integrity. Called after up()
     * and before down() within the same transaction. Should not leave persistent
     * data behind.
     *
     * @param connections - Map of database keys to Database instances.
     * @returns True if validation passes, false or thrown error to abort.
     */
    test?: (connections: Connections<T>) => boolean;
}
/**
 * Migration interface for attached mode. All databases are attached to a single
 * in-memory database connection, allowing for efficient cross-database
 * operations.
 */
export interface AttachedMigration<T extends string[]> extends MigrationBase<T> {
    /**
     * Migration mode identifier for attached mode. Creates an in-memory database
     * with all specified databases attached using their keys as aliases.
     */
    mode: 'attach';
    /**
     * Applies the migration changes using attached databases.
     *
     * @param db - Single database instance with all databases attached as
     *   aliases.
     * @returns True to commit the migration, false or thrown error to abort.
     */
    up(db: Database): boolean;
    /**
     * Reverts the migration changes using attached databases.
     *
     * @param db - Single database instance with all databases attached as
     *   aliases.
     * @returns True to commit the rollback, false or thrown error to abort.
     */
    down(db: Database): boolean;
    /**
     * Optional validation method for attached mode.
     *
     * @param db - Single database instance with all databases attached as
     *   aliases.
     * @returns True if validation passes, false or thrown error to abort.
     */
    test?(db: Database): boolean;
}
/**
 * Union type for all supported migration types. Can be either connections mode
 * or attached mode.
 */
export type Migration<T extends string[]> = ConnectionsMigration<T> | AttachedMigration<T>;
/**
 * Type helper function for creating strongly-typed migrations. Provides type
 * safety for database keys and removes need to specify generics.
 *
 * @param m - Migration object to type-check and return.
 * @returns The same migration object with enhanced type safety.
 */
export declare function migration<const T extends string[]>(m: Migration<T>): Migration<T>;
//# sourceMappingURL=migration.d.ts.map