sqlmorpheus 0.2.6 → 1.0.0

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 interface DatabaseAccess {
-    createBackup?(backupName: string): Promise<void>;
-    runGetStatement(query: string): Promise<unknown>;
-    runMultipleWriteStatements(query: string): Promise<void>;
+    createBackup?(backupName: string): Promise<any>;
+    runReadStatement(query: string): Promise<unknown>;
+    runWriteStatement(query: string): Promise<any>;
+    runTransaction(query: string): Promise<any>;
 }
 
 type Class<T> = new (...args: never[]) => T;
@@ -12,14 +13,16 @@ type TableClassInterface = {
     [key: string]: any;
 };
 
+declare const ALLOWED = "allowed";
+declare const USED = "allowedAndUsed";
+type AllowedMigrationState = typeof ALLOWED | typeof USED;
 interface AllowedMigrations {
-    recreateTable?: boolean;
-    dropTable?: boolean;
-    dropColumn?: boolean;
-    alterPrimaryKey?: boolean;
-    removeForeignKey?: boolean;
-    alterForeignKey?: boolean;
-    continueWithoutRollback?: boolean;
+    recreateTable?: Record<string, AllowedMigrationState>;
+    dropTable?: Record<string, AllowedMigrationState>;
+    dropColumn?: Record<string, AllowedMigrationState>;
+    alterPrimaryKey?: Record<string, AllowedMigrationState>;
+    removeForeignKey?: Record<string, AllowedMigrationState>;
+    alterForeignKey?: Record<string, AllowedMigrationState>;
 }
 
 interface RenameData {
@@ -34,7 +37,6 @@ interface MigrationInstructions {
      */
     renamedColumns: RenameData[];
     allowedMigrations: AllowedMigrations;
-    usedMigrations: Record<string, boolean>;
 }
 
 interface ColumnInfo {
@@ -81,14 +83,6 @@ declare class Migrations {
      * @param fromVersion - The version of the actual database.
      */
     reset(dbInstructions: DatabaseInstructions, fromVersion: number): void;
-    /**
-     * Retrieves the migration instructions for the specified table.
-     * @see getEntryFromTableName
-     *
-     * @param table - The {@link TableInput} object from which the table name will be retrieved.
-     * @return The migration instructions corresponding to the given table input.
-     */
-    private getEntry;
     /**
      * Retrieves the migration instructions for the specified table.
      *
@@ -96,13 +90,6 @@ declare class Migrations {
      * @return The migration instructions corresponding to the given table input.
      */
     private getEntryFromTableName;
-    /**
-     * Retrieves the table name from the given table input.
-     *
-     * @param table - The {@link TableInput} object.
-     * @return The name of the table derived from either {@link TableObj} or a class.
-     */
-    private getTableName;
     /**
      * Checks whether a provided version is relevant based on database version ({@link fromVersion}) and target version ({@link toVersion}).
      * Also makes sure that version checks happen in order.
@@ -136,8 +123,9 @@ declare class Migrations {
      * @see allowMigration()
      * @param tableName - The name of the table to check the migration against.
      * @param type - The type of destructive migration being checked.
+     * @param column - The column name for which the migration is allowed. Only needed for "dropColumn", "removeForeignKey" and "alterForeignKey".
      */
-    compareWithAllowedMigration(tableName: string, type: keyof AllowedMigrations): void;
+    compareWithAllowedMigration(tableName: string, type: keyof AllowedMigrations, column?: string): void;
     /**
      * Retrieves the migration data containing instructions for data migration.
      * Only used internally.
@@ -205,10 +193,13 @@ declare class Migrations {
      * This method will be ignored if {@link version} is smaller than the current database version or higher than the target version of {@link DatabaseInstructions}.
      *
      * @param version - The target version for which the specific migration is allowed. Must be provided to make sure this method will only have an effect when specified.
-     * @param table - Either a {@link TableObj} or a class decorated with @TableClass.
-     * @param allowedMigrations - The keys representing the migrations to be allowed. Multiple migrations can be provided
+     * @param tableName - The current table name in the database at the time of the migration version.
+     * @param allowedMigration - The keys representing the migrations to be allowed.
+     * @param column - The column name for which the migration is allowed. Only needed for "dropColumn", "removeForeignKey" and "alterForeignKey".
+     *
+     * @throws Error if the provided column name is not valid for the specified migration.
      */
-    allowMigration(version: number, table: TableInput, ...allowedMigrations: (keyof AllowedMigrations)[]): void;
+    allowMigration(version: number, tableName: string, allowedMigration: keyof AllowedMigrations, column?: string): void;
     /**
      * When you change the name of a table, SqlMorpheus will assume the original table was meant to be dropped
      * and the new table was meant to be added, which would lead to data loss.
@@ -216,10 +207,10 @@ declare class Migrations {
      * This method will be ignored if {@link version} is smaller than the current database version or higher than the target version of {@link DatabaseInstructions}.
      *
      * @param version - The target version for which the table should be renamed. Must be provided to make sure this method will only have an effect when specified.
-     * @param oldTableName - The current name in the database at the time of the migration.
-     * @param newTableName - The new table name or its equivalent input format.
+     * @param oldTableName - The current name in the database at the time of the migration version.
+     * @param newTableName - The new table name at the time of the migration version.
      */
-    renameTable(version: number, oldTableName: string, newTableName: TableInput): void;
+    renameTable(version: number, oldTableName: string, newTableName: string): void;
     /**
      * When you change the name of a column, SqlMorpheus will assume the original column was meant to be removed
      * and the new column was meant to be added, which would lead to data loss.
@@ -227,11 +218,11 @@ declare class Migrations {
      * This method will be ignored if {@link version} is smaller than the current database version or higher than the target version of {@link DatabaseInstructions}.
      *
      * @param version - The target version for which the table should be renamed. Must be provided to make sure this method will only have an effect when specified.
-     * @param table Either a {@link TableObj} or a class decorated with @TableClass containing the column to be renamed.
+     * @param tableName - The current table name in the database at the time of the migration version.
      * @param oldColumn The current name in the database at the time of the migration.
      * @param newColumn The new name to assign to the column.
      */
-    renameColumn(version: number, table: TableInput, oldColumn: string, newColumn: string): void;
+    renameColumn(version: number, tableName: string, oldColumn: string, newColumn: string): void;
     /**
      * Should not be needed most of the time.
      * Marks a table to be recreated
@@ -239,9 +230,9 @@ declare class Migrations {
      * This method will be ignored if {@link version} is smaller than the current database version or higher than the target version of {@link DatabaseInstructions}.
      *
      * @param version - The target version for which the table should be renamed. Must be provided to make sure this method will only have an effect when specified.
-     * @param table Either a {@link TableObj} or a class decorated with @TableClass.
+     * @param tableName - The current table name in the database at the time of the migration version.
      */
-    recreateTable(version: number, table: TableInput): void;
+    recreateTable(version: number, tableName: string): void;
 }
 type PublicMigrations = Pick<Migrations, "recreateTable" | "renameTable" | "renameColumn" | "allowMigration">;
 
@@ -263,12 +254,17 @@ interface InputTableStructure extends TableStructure {
     columns: Record<string, InputColumnInfo>;
 }
 
-type DataFormat = Record<string, unknown>;
-type GetColumns<T> = T extends TableObjBuilderDefinition<infer Item, any> ? Item : never;
-type TableObjBuilderDefinition<T extends DataFormat, TPick extends keyof TableObj<T>> = Pick<TableObj<T>, TPick>;
-type NewTableObjBuilder<T extends DataFormat> = TableObjBuilderDefinition<T, "primaryKey" | "foreignKey" | "dataType" | "maxCharacterLength">;
-type TableObjBuilder<T extends DataFormat> = TableObjBuilderDefinition<T, "foreignKey" | "dataType" | "maxCharacterLength">;
-type TableObjInput = TableObjBuilderDefinition<any, any>;
+type AllowedTypes = boolean | number | bigint | string | null | Date;
+
+interface ColumnOptions {
+    primaryKey?: boolean;
+    dataType?: DataTypeOptions;
+    maxCharacterLength?: number;
+}
+type DataFormat = Record<string, AllowedTypes | [AllowedTypes, ColumnOptions]>;
+type GetColumns<T> = T extends PublicTableObj<infer Item> ? Item : never;
+type PublicTableObj<T extends DataFormat> = Pick<TableObj<T>, "foreignKey" | "sealType">;
+type TableObjInput = PublicTableObj<DataFormat>;
 /**
  * Use this class to define tables for DatabaseInstructions
  * (as an alternative for Class decorators)
@@ -278,44 +274,68 @@ declare class TableObj<T extends DataFormat> {
     readonly IS_TABLE_OBJ = true;
     readonly tableName: string;
     tableStructure: InputTableStructure;
-    static getEmptyColumnEntry(key: string): InputColumnInfo;
-    static getColumnEntry(key: string, value: unknown): InputColumnInfo | null;
     private constructor();
-    primaryKey(key: keyof T): TableObjBuilder<T>;
-    foreignKey<TOther extends TableObjBuilderDefinition<DataFormat, any>>(fromColumn: keyof T, toTable: TOther, toColumn: keyof GetColumns<TOther>, options?: {
+    private applyOptions;
+    /**
+     * Creates a foreign key relationship between the current table and a target table.
+     *
+     * @param fromColumn - The column in the current table that will serve as the foreign key.
+     * @param toTable - The target table object that the foreign key will reference.
+     * @param toColumn - The column in the target table that the foreign key will reference.
+     * @param options - Optional configurations for the foreign key, specifying actions on update or delete.
+     */
+    foreignKey<TOther extends Partial<TableObj<DataFormat>>>(fromColumn: keyof T, toTable: TOther, toColumn: keyof GetColumns<TOther>, options?: {
         onUpdate?: ForeignKeyActions;
         onDelete?: ForeignKeyActions;
-    }): TableObjBuilder<T>;
-    dataType(column: keyof T, type: DataTypeOptions): TableObjBuilder<T>;
-    maxCharacterLength(column: keyof T, max: number): TableObjBuilder<T>;
-    static create<T extends Record<string, unknown>>(tableName: string, columns: T): NewTableObjBuilder<T>;
-    static isTableObj(obj: unknown): obj is TableObj<any>;
+    }): PublicTableObj<T>;
+    /**
+     * An optional helper function to deal with `TS2589: Type instantiation is excessively deep and possibly infinite. when used as method parameter`
+     * Does nothing in runtime
+     */
+    sealType(): TableObjInput;
+    static create<T extends DataFormat>(tableName: string, columns: T): PublicTableObj<T>;
 }
 
+type LoggerMode = "silent" | "error" | "warn" | "log" | "debug";
+
 type TableInput = TableObjInput | Class<TableClassInterface>;
 interface DatabaseInstructions {
     dialect: "Sqlite" | "MsSql" | "MySql" | "Postgres";
     tables: TableInput[];
     version: number;
-    configPath: string;
-    throwIfNotAllowed: boolean;
-    loggerMode?: "silent" | "noLog" | "normal" | "debug";
-    alwaysAllowedMigrations?: AllowedMigrations;
+    /**
+     * Usually SqlMorpheus throws an exception if it needs to execute a destructive database change and is not explicitly confirmed in
+     * (using `allowMigration()` in `preMigration()`).
+     * If true, no exception will be thrown and an error message will be logged to the console instead.
+     */
+    doNotThrowIfNotAllowed?: boolean;
+    /**
+     * Defines how much should be logged to the console.
+     */
+    loggerMode?: LoggerMode;
+    /**
+     * Usually SqlMorpheus throws an exception if it needs to execute a destructive database change and is not explicitly allowed to do so
+     * (using `allowMigration()` in `preMigration()`).
+     * if defined, the confirmation will be skipped for each migration type defined in `alwaysAllowedMigrations`.
+     */
+    alwaysAllowedMigrations?: (keyof AllowedMigrations)[];
     /**
      * Custom migrations that will run before any database changes are applied.
-     * @param migrations The migration object that will be validated after this.
-     * @param fromVersion Version of the current database.
-     * @param toVersion Version of the database after update.
+     * @param migrations - The migration object that will be validated after this.
+     * @param dbAccess - The database access object to interact with the database.
+     * @param fromVersion - Version of the current database.
+     * @param toVersion - Version of the database after update.
      * @return custom SQL that should be executed before migrations are executed.
      */
-    preMigration?(migrations: PublicMigrations, fromVersion: number, toVersion: number): SqlChanges | void;
+    preMigration?(migrations: PublicMigrations, dbAccess: DatabaseAccess, fromVersion: number, toVersion: number): SqlChanges | void;
     /**
      * Custom migrations that will run after database changes have been applied (but before the transaction is finished)
-     * @param fromVersion Version of the current database.
-     * @param toVersion Version of the database after update.
-     * @return custom SQL that should be executed before migrations are executed.
+     * @param dbAccess - The database access object to interact with the database.
+     * @param fromVersion - Version of the current database.
+     * @param toVersion - Version of the database after update.
+     * @return custom SQL that should be executed after migrations were executed.
      */
-    postMigration?(fromVersion: number, toVersion: number): SqlChanges;
+    postMigration?(dbAccess: DatabaseAccess, fromVersion: number, toVersion: number): SqlChanges;
 }
 
 /**
@@ -348,6 +368,13 @@ declare function ForeignKey<TOther extends TableClassInterface>(toTable: Class<T
 }): (table: any, context: any) => void;
 
 declare function runMigration(db: DatabaseAccess, dbInstructions: DatabaseInstructions): Promise<void>;
-declare function rollback(db: DatabaseAccess, dbInstructions: DatabaseInstructions, toVersion: number): Promise<number>;
+/**
+ * Rolls back the database to the provided toVersion
+ * @param dbAccess - Access to the database.
+ * @param toVersion - the version to which the database should be upgraded to.
+ * @param dialect - the dialect that should be used for the database. Usually is the value defined in DatabaseInstructions
+ * @param loggerMode - defines how much should be logged to the console.
+ */
+declare function rollback(dbAccess: DatabaseAccess, toVersion: number, dialect: DatabaseInstructions["dialect"], loggerMode?: DatabaseInstructions["loggerMode"]): Promise<number>;
 
 export { DataType, type DatabaseAccess, type DatabaseInstructions, ForeignKey, type PublicMigrations, type SqlChanges, TableClass, TableObj, rollback, runMigration };