sqlmorpheus 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -0,0 +1,450 @@
+import "polyfill-symbol-metadata";
+//#region src/lib/typings/DatabaseAccess.d.ts
+interface DatabaseAccess {
+  createBackup?(backupName: string): Promise<any>;
+  runReadStatement(query: string): Promise<unknown>;
+  runWriteStatement(query: string): Promise<any>;
+  runTransaction(query: string): Promise<any>;
+}
+//#endregion
+//#region src/lib/typings/TableClassInterface.d.ts
+type Class<T> = new (...args: never[]) => T;
+/**
+ * This does nothing. It mainly exists in case we want to filter class types in the future
+ */
+type TableClassInterface = {
+  [key: string]: any;
+};
+//#endregion
+//#region src/lib/typings/AllowedMigrations.d.ts
+declare const ALLOWED = "allowed";
+declare const USED = "allowedAndUsed";
+type AllowedMigrationState = typeof ALLOWED | typeof USED;
+interface AllowedMigrations {
+  recreateTable?: Record<string, AllowedMigrationState>;
+  dropTable?: Record<string, AllowedMigrationState>;
+  dropColumn?: Record<string, AllowedMigrationState>;
+  alterPrimaryKey?: Record<string, AllowedMigrationState>;
+  removeForeignKey?: Record<string, AllowedMigrationState>;
+  alterForeignKey?: Record<string, AllowedMigrationState>;
+  dropIndex?: Record<string, AllowedMigrationState>;
+}
+//#endregion
+//#region src/lib/typings/MigrationInstructions.d.ts
+interface RenameData {
+  oldName: string;
+  newName: string;
+}
+interface MigrationInstructions {
+  tableRenaming?: RenameData;
+  recreate: boolean;
+  /**
+   * Stores changes to column. One entry per column.
+   */
+  renamedColumns: RenameData[];
+  allowedMigrations: AllowedMigrations;
+}
+//#endregion
+//#region src/lib/typings/ColumnInfo.d.ts
+interface ColumnInfo {
+  name: string;
+  sqlType: string;
+  maxLength?: number;
+  defaultValue?: string;
+  isPrimaryKey: boolean;
+}
+//#endregion
+//#region src/lib/typings/ForeignKeyInfo.d.ts
+type ForeignKeyActions = "SET NULL" | "SET DEFAULT" | "RESTRICT" | "NO ACTION" | "CASCADE";
+interface ForeignKeyInfo {
+  fromTable: string;
+  fromColumn: string;
+  toTable: string;
+  toColumn: string;
+  onUpdate?: ForeignKeyActions;
+  onDelete?: ForeignKeyActions;
+}
+//#endregion
+//#region src/lib/typings/IndexInfo.d.ts
+interface IndexInfo {
+  name: string;
+  columns: string[];
+  isUnique: boolean;
+}
+/**
+ * Index definition as provided by the user. If no name is provided, a name is generated from the table and column names.
+ */
+interface InputIndexInfo extends Omit<IndexInfo, "name"> {
+  name?: string;
+}
+//#endregion
+//#region src/lib/typings/TableStructure.d.ts
+interface TableStructure {
+  table: string;
+  primaryKey?: string;
+  columns: Record<string, ColumnInfo>;
+  foreignKeys?: ForeignKeyInfo[];
+  indexes?: IndexInfo[];
+}
+//#endregion
+//#region src/lib/Migrations.d.ts
+/**
+ * The Migrations class is responsible for managing manual database schema migrations.
+ */
+declare class Migrations {
+  private fromVersion;
+  private toVersion;
+  private lastUsedVersion;
+  private migrationData;
+  private migrationDataForOldTableNames;
+  private alwaysAllowed;
+  private notAllowedChanges;
+  /**
+   * Resets the migration state to its initial values.
+   * Only used internally.
+   *
+   * @param dbInstructions - The instructions containing database metadata and migration details.
+   * @param fromVersion - The version of the actual database.
+   */
+  reset(dbInstructions: DatabaseInstructions, fromVersion: number): void;
+  /**
+   * Retrieves the migration instructions for the specified table.
+   *
+   * @param tableName - The name of the table for which the entry is to be retrieved or created.
+   * @return The migration instructions corresponding to the given table input.
+   */
+  private getEntryFromTableName;
+  /**
+   * 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.
+   *
+   * @param version - The version to check for relevance.
+   * @return Returns true if the version is relevant, otherwise false.
+   * @throws Error if versions are not properly ordered
+   */
+  private versionIsRelevant;
+  /**
+   * Verifies the renaming tasks specified in {@link DatabaseInstructions.preMigration} that were considered are valid.
+   * Called after all SQL queries have been generated.
+   * Only used internally.
+   *
+   * @param newTables - The table structures extracted from {@link DatabaseInstructions.tables}.
+   * @throws Error if a renaming task is invalid.
+   */
+  verifyRenamingTasks(newTables: Record<string, TableStructure>): Error | void;
+  /**
+   * Making sure all considered calls to {@link allowMigration()} where necessary to prevent input mistakes.
+   * Called after all SQL queries have been generated.
+   * Only used internally.
+   *
+   * @throws Error if unnecessary calls were discovered. All discovered calls are collected and thrown as one Error.
+   */
+  verifyAllowedMigrations(): Error | void;
+  /**
+   * Called by {@link MigrationManager} to check if a specific destructive query is allowed.
+   * Only used internally.
+   *
+   * @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".
+   * For "dropIndex", the index name is used instead.
+   */
+  compareWithAllowedMigration(tableName: string, type: keyof AllowedMigrations, column?: string): void;
+  /**
+   * Retrieves the migration data containing instructions for data migration.
+   * Only used internally.
+   *
+   * @return An object where each key corresponds to the table name,
+   * and the value is the associated migration instructions.
+   */
+  getMigrationData(): Record<string, MigrationInstructions>;
+  /**
+   * Iterates over renamed columns for the specified table and executes a callback for each pair of old and new column names.
+   * Only used internally.
+   *
+   * @param tableName - Name of the table whose renamed columns should be processed.
+   * @param callback - A function to execute for each renamed column, receiving the old and new column names as arguments.
+   */
+  loopRenamedColumns(tableName: string, callback: (oldColumnName: string, newColumnName: string) => void): void;
+  /**
+   * Considers the renaming of a table and returns its (newest) name after the migration or
+   * the original name if no renaming is queued.
+   * Only used internally.
+   *
+   * @see getOldTableName()
+   * @param tableName - The current table name in the database.
+   * @return The newest table name if available, otherwise the current table name.
+   */
+  getNewestTableName(tableName: string): string;
+  /**
+   * Retrieves the current table name in the database.
+   * Only used internally.
+   *
+   * @see getNewestTableName()
+   * @param tableName - The name of the newest table name.
+   * @return The current table name in the database.
+   */
+  getOldTableName(tableName: string): string;
+  /**
+   * Considers the renaming of a column in a table and returns its (newest) name after the migration or
+   * the original name if no renaming is queued.
+   * Only used internally.
+   *
+   * @param tableName - The name of the table containing the column.
+   * @param oldColumnName - The current name of the column in the database.
+   * @return The newest column name if available, otherwise the original column name.
+   */
+  getNewestColumnName(tableName: string, oldColumnName: string): string;
+  /**
+   * Determines if the specified table is marked to be recreated.
+   * Only used internally.
+   *
+   * @param tableName The name of the table to check.
+   * @return Returns true if the table will be recreated, false otherwise.
+   */
+  willBeRecreated(tableName: string): boolean;
+  /**
+   * Marks a table to be recreated and logs the recreation reason for the user.
+   * Only used internally.
+   *
+   * @param tableName - The name of the table to be marked for recreation.
+   * @param reason - The reason why the table is being marked for recreation.
+   */
+  internalRecreate(tableName: string, reason: string): void;
+  /**
+   * SqlMorpheus only allows destructive statements if it was specifically allowed in {@link DatabaseInstructions.preMigration()}.
+   * Use this method to allow a destructive statement for a specific version.
+   * 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 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".
+   * For "dropIndex", provide the index name instead.
+   *
+   * @throws Error if the provided column name is not valid for the specified migration.
+   */
+  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.
+   * Use this method to mark a table to be renamed instead.
+   * 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 version.
+   * @param newTableName - The new table name at the time of the migration version.
+   */
+  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.
+   * Use this method to mark a column to be renamed instead.
+   * 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 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, tableName: string, oldColumn: string, newColumn: string): void;
+  /**
+   * Should not be needed most of the time.
+   * Marks a table to be recreated
+   * (a copy of the table will be created, all data will be moved over, the original table will be dropped and the new table will be renamed to the original name).
+   * 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 tableName - The current table name in the database at the time of the migration version.
+   */
+  recreateTable(version: number, tableName: string): void;
+}
+type PublicMigrations = Pick<Migrations, "recreateTable" | "renameTable" | "renameColumn" | "allowMigration">;
+//#endregion
+//#region src/lib/typings/SqlChanges.d.ts
+interface SqlChanges {
+  up: string;
+  down: string;
+}
+//#endregion
+//#region src/lib/tableInfo/DataTypeOptions.d.ts
+type NativeDataTypeOptions = "boolean" | "number" | "bigint" | "string";
+type AddedDataTypeOptions = "date" | "time" | "dateTime" | "text";
+type DataTypeOptions = NativeDataTypeOptions | AddedDataTypeOptions;
+//#endregion
+//#region src/lib/typings/InputColumnInfo.d.ts
+interface InputColumnInfo extends ColumnInfo {
+  inputType?: DataTypeOptions;
+  inputDefaultValue?: unknown;
+}
+//#endregion
+//#region src/lib/typings/InputTableStructure.d.ts
+interface InputTableStructure extends Omit<TableStructure, "indexes"> {
+  columns: Record<string, InputColumnInfo>;
+  indexes?: InputIndexInfo[];
+}
+//#endregion
+//#region src/lib/tableInfo/TableObjHelper.d.ts
+type AllowedTypes = boolean | number | bigint | string | null | Date;
+//#endregion
+//#region src/lib/tableInfo/TableObj.d.ts
+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" | "index" | "sealType">;
+type TableObjInput = PublicTableObj<DataFormat>;
+/**
+ * Use this class to define tables for DatabaseInstructions
+ * (as an alternative for Class decorators)
+ *
+ */
+declare class TableObj<T extends DataFormat> {
+  readonly IS_TABLE_OBJ = true;
+  readonly tableName: string;
+  tableStructure: InputTableStructure;
+  private constructor();
+  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;
+  }): PublicTableObj<T>;
+  /**
+   * Creates an index on one or more columns of the current table.
+   *
+   * @param columns - The columns that will be part of the index (in order).
+   * @param options - Optional configurations for the index.
+   * If no name is provided, the name is generated from the table and column names.
+   */
+  index(columns: (keyof T)[], options?: {
+    name?: string;
+    unique?: boolean;
+  }): 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>;
+}
+//#endregion
+//#region src/lib/Logger.d.ts
+type LoggerMode = "silent" | "error" | "warn" | "log" | "debug";
+//#endregion
+//#region src/lib/typings/DatabaseInstructions.d.ts
+type TableInput = TableObjInput | Class<TableClassInterface>;
+interface DatabaseInstructions {
+  dialect: "Sqlite" | "MsSql" | "MySql" | "Postgres";
+  tables: TableInput[];
+  version: number;
+  /**
+   * 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 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, 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 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?(dbAccess: DatabaseAccess, fromVersion: number, toVersion: number): SqlChanges;
+}
+//#endregion
+//#region src/lib/tableInfo/decorators/TableClass.d.ts
+/**
+ * Decorator function to configure a database table with its name and primary key.
+ *
+ * @param tableName - The name of the database table used in SQL.
+ * @param primaryKey - The property name representing the primary property of the table.
+ */
+declare function TableClass<T extends TableClassInterface>(tableName: string, primaryKey?: keyof T): (table: Class<T>, context?: any) => void;
+//#endregion
+//#region src/lib/tableInfo/decorators/DataType.d.ts
+/**
+ * Decorator function to assign a specific data type to a column.
+ * Should be used if you want to use a data type that does not exist in JavaScript or
+ * if the default value should be NULL
+ *
+ * @param type - The data type to be assigned.
+ */
+declare function DataType(type: DataTypeOptions): (table: any, context: any) => void;
+//#endregion
+//#region src/lib/tableInfo/decorators/ForeignKey.d.ts
+/**
+ * Decorator function to define a foreign key relationship for a database table.
+ *
+ * @param toTable - The target table class to which the foreign key points.
+ * @param toColumn - The column name in the target table to which the foreign key points.
+ * @param options - Additional options.
+ */
+declare function ForeignKey<TOther extends TableClassInterface>(toTable: Class<TOther>, toColumn: keyof TOther, options?: {
+  onDelete?: ForeignKeyActions;
+  onUpdate?: ForeignKeyActions;
+}): (table: any, context: any) => void;
+//#endregion
+//#region src/lib/tableInfo/decorators/Index.d.ts
+/**
+ * Decorator function to create an index on one or more columns of a table.
+ * This decorator must be used at the head of the class.
+ *
+ * @param columns - The columns that will be part of the index (in order).
+ * @param options - Additional options. If no name is provided, the name is generated from the table and column names.
+ */
+declare function Index<T extends TableClassInterface>(columns: (keyof T)[], options?: {
+  name?: string;
+  unique?: boolean;
+}): (table: Class<T>, context?: any) => void;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Executes a database migration based on the provided database connection and migration instructions.
+ *
+ * @param db - The database access object used to interact with the database.
+ * @param dbInstructions - The migration instructions, including target version, logger mode, and dialect.
+ * @return A promise that resolves when the migration process is successfully completed.
+ */
+export declare function runMigration(db: DatabaseAccess, dbInstructions: DatabaseInstructions): Promise<void>;
+/**
+ * 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.
+ */
+export declare function rollback(dbAccess: DatabaseAccess, toVersion: number, dialect: DatabaseInstructions["dialect"], loggerMode?: DatabaseInstructions["loggerMode"]): Promise<number>;
+//#endregion
+export { DataType, type DatabaseAccess, type DatabaseInstructions, ForeignKey, Index, type PublicMigrations, type SqlChanges, TableClass, TableObj };