sqlmorpheus 0.2.0 → 0.2.2

package/dist/index.d.ts

@@ -8,7 +8,7 @@ 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 BackendTable = {
+type TableClassInterface = {
     [key: string]: any;
 };
 
@@ -31,7 +31,6 @@ interface MigrationInstructions {
     recreate: boolean;
     /**
      * Stores changes to column. One entry per column.
-     * Each entry is an array (0: name in the database, last: current name in code)
      */
     renamedColumns: RenameData[];
     allowedMigrations: AllowedMigrations;
@@ -41,7 +40,8 @@ interface MigrationInstructions {
 interface ColumnInfo {
     name: string;
     type: string;
-    defaultValue: string;
+    maxLength?: number;
+    defaultValue?: string;
     isPrimaryKey: boolean;
 }
 
@@ -58,34 +58,190 @@ interface ForeignKeyInfo {
 interface TableStructure {
     table: string;
     primaryKey?: string;
-    columns: ColumnInfo[];
+    columns: Record<string, ColumnInfo>;
     foreignKeys?: ForeignKeyInfo[];
 }
 
+/**
+ * The Migrations class is responsible for managing manual database schema migrations.
+ */
 declare class Migrations {
-    private toVersion;
-    private alwaysAllowed;
     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.
+     * @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.
+     *
+     * @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;
+    /**
+     * 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.
+     *
+     * @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.
+     */
     compareWithAllowedMigration(tableName: string, type: keyof AllowedMigrations): void;
-    allowMigration(version: number, table: string | Class<BackendTable>, ...allowedMigrations: (keyof AllowedMigrations)[]): void;
-    renameTable(version: number, oldTableName: string, newTableName: string | Class<BackendTable>): void;
-    renameColumn(version: number, table: string | Class<BackendTable>, oldColumn: string, newColumn: string): void;
-    recreateTableImp(table: Class<BackendTable> | string): void;
-    recreateTable(version: number, table: Class<BackendTable> | 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 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
+     */
+    allowMigration(version: number, table: TableInput, ...allowedMigrations: (keyof AllowedMigrations)[]): 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.
+     * @param newTableName - The new table name or its equivalent input format.
+     */
+    renameTable(version: number, oldTableName: string, newTableName: TableInput): 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 table Either a {@link TableObj} or a class decorated with @TableClass containing the column to be renamed.
+     * @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;
+    /**
+     * 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 table Either a {@link TableObj} or a class decorated with @TableClass.
+     */
+    recreateTable(version: number, table: TableInput): void;
 }
 type PublicMigrations = Pick<Migrations, "recreateTable" | "renameTable" | "renameColumn" | "allowMigration">;
 
@@ -94,19 +250,52 @@ interface SqlChanges {
     down: string;
 }
 
-interface TableInfo {
-    primaryKey?: string;
-    foreignKeys?: ForeignKeyInfo[];
+type NativeDataTypeOptions = "boolean" | "number" | "bigint" | "string";
+type AddedDataTypeOptions = "date" | "time" | "dateTime";
+type DataTypeOptions = NativeDataTypeOptions | AddedDataTypeOptions;
+
+interface InputColumnInfo extends ColumnInfo {
+    inputType?: DataTypeOptions;
+    inputDefaultValue?: unknown;
+}
+
+interface InputTableStructure extends TableStructure {
+    columns: Record<string, InputColumnInfo>;
 }
 
-type TableObjects = Record<string, {
-    columns: BackendTable;
-    tableInfo?: TableInfo;
-}>;
+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>;
+/**
+ * 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;
+    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?: {
+        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>;
+}
 
+type TableInput = TableObjInput | Class<TableClassInterface>;
 interface DatabaseInstructions {
     dialect: "Sqlite" | "MsSql" | "MySql" | "Postgres";
-    tables: Class<BackendTable>[] | TableObjects;
+    tables: TableInput[];
     version: number;
     configPath: string;
     throwIfNotAllowed: boolean;
@@ -130,24 +319,33 @@ interface DatabaseInstructions {
 }
 
 /**
- * Decorator function to configure a database table with its name and primary key
- * and to add missing "fromTable" properties to foreign keys.
+ * 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 DbTable<T extends BackendTable>(tableName: string, primaryKey?: keyof T): (table: Class<T>, context?: any) => void;
+declare function TableClass<T extends TableClassInterface>(tableName: string, primaryKey?: keyof T): (table: Class<T>, context?: any) => void;
 
 /**
- * Decorator function to define a foreign key constraint for a database table. It defines a relationship
- * between a column on the current table and a column on another table.
+ * 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;
+
+/**
+ * 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 [onDelete] - Optional. The action to perform when a row in the target table is deleted.
- * @param [onUpdate] - Optional. The action to perform when a related row in the target table is updated.
+ * @param options - Additional options.
  */
-declare function ForeignKey<TOther extends BackendTable>(toTable: Class<TOther>, toColumn: keyof TOther, onDelete?: ForeignKeyActions, onUpdate?: ForeignKeyActions): (table: any, context: any) => void;
+declare function ForeignKey<TOther extends TableClassInterface>(toTable: Class<TOther>, toColumn: keyof TOther, options?: {
+    onDelete?: ForeignKeyActions;
+    onUpdate?: ForeignKeyActions;
+}): (table: any, context: any) => void;
 
 declare function prepareMigration(db: DatabaseAccess, dbInstructions: DatabaseInstructions, overwriteExisting?: boolean): Promise<void>;
 declare function runPreparedMigrations(db: DatabaseAccess, dbInstructions: DatabaseInstructions): Promise<void>;
@@ -155,4 +353,4 @@ declare function prepareAndRunMigration(db: DatabaseAccess, instructions: Databa
 declare function runMigrationWithoutHistory(db: DatabaseAccess, dbInstructions: DatabaseInstructions): Promise<void>;
 declare function rollback(db: DatabaseAccess, dbInstructions: DatabaseInstructions, toVersion: number): Promise<void>;
 
-export { type DatabaseAccess, type DatabaseInstructions, DbTable, ForeignKey, type PublicMigrations, type SqlChanges, prepareAndRunMigration, prepareMigration, rollback, runMigrationWithoutHistory, runPreparedMigrations };
+export { DataType, type DatabaseAccess, type DatabaseInstructions, ForeignKey, type PublicMigrations, type SqlChanges, TableClass, TableObj, prepareAndRunMigration, prepareMigration, rollback, runMigrationWithoutHistory, runPreparedMigrations };