sqlmorpheus 0.2.1 → 0.2.2

package/README.md

@@ -0,0 +1,3 @@
+ Ever wanted to use a migration tool but couldn't because is uses a different stack than your project and would add unnecessary overhead or would simply not work in your setup at all? SQLMorpheus is an automatic migration library that is as unopinionated as it gets:
+ 
+- It does not use its own database framework

package/dist/index.d.mts

@@ -40,7 +40,8 @@ interface MigrationInstructions {
 interface ColumnInfo {
     name: string;
     type: string;
-    defaultValue: string;
+    maxLength?: number;
+    defaultValue?: string;
     isPrimaryKey: boolean;
 }
 
@@ -57,10 +58,13 @@ 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 fromVersion;
     private toVersion;
@@ -69,24 +73,174 @@ declare class Migrations {
     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;
+    /**
+     * 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">;
@@ -100,16 +254,21 @@ type NativeDataTypeOptions = "boolean" | "number" | "bigint" | "string";
 type AddedDataTypeOptions = "date" | "time" | "dateTime";
 type DataTypeOptions = NativeDataTypeOptions | AddedDataTypeOptions;
 
-interface TableInfo {
-    primaryKey?: string;
-    foreignKeys?: ForeignKeyInfo[];
-    dataTypes?: Record<string, DataTypeOptions>;
+interface InputColumnInfo extends ColumnInfo {
+    inputType?: DataTypeOptions;
+    inputDefaultValue?: unknown;
+}
+
+interface InputTableStructure extends TableStructure {
+    columns: Record<string, InputColumnInfo>;
 }
 
 type DataFormat = Record<string, unknown>;
-type GetColumns<T> = T extends TableObjBuilder<infer Item, any> ? Item : never;
-type TableObjBuilder<T extends DataFormat, TPick extends keyof TableObj<T>> = Pick<TableObj<T>, TPick>;
-type TableObjInput = TableObjBuilder<any, any>;
+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)
@@ -118,17 +277,19 @@ type TableObjInput = TableObjBuilder<any, any>;
 declare class TableObj<T extends DataFormat> {
     readonly IS_TABLE_OBJ = true;
     readonly tableName: string;
-    readonly columns: T;
-    tableInfo: TableInfo;
+    tableStructure: InputTableStructure;
+    static getEmptyColumnEntry(key: string): InputColumnInfo;
+    static getColumnEntry(key: string, value: unknown): InputColumnInfo | null;
     private constructor();
-    primaryKey(key: keyof T): TableObjBuilder<T, "foreignKey" | "dataType">;
-    foreignKey<TOther extends TableObjBuilder<DataFormat, any>>(fromColumn: keyof T, toTable: TOther, toColumn: keyof GetColumns<TOther>, options?: {
+    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, "foreignKey" | "dataType">;
-    dataType(column: keyof T, type: DataTypeOptions): TableObjBuilder<T, "foreignKey" | "dataType">;
-    static create<T extends Record<string, unknown>>(tableName: string, columns: T): TableObjBuilder<T, "primaryKey" | "foreignKey" | "dataType">;
-    static isDbTable(obj: unknown): obj is TableObj<any>;
+    }): 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>;

package/dist/index.d.ts

@@ -40,7 +40,8 @@ interface MigrationInstructions {
 interface ColumnInfo {
     name: string;
     type: string;
-    defaultValue: string;
+    maxLength?: number;
+    defaultValue?: string;
     isPrimaryKey: boolean;
 }
 
@@ -57,10 +58,13 @@ 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 fromVersion;
     private toVersion;
@@ -69,24 +73,174 @@ declare class Migrations {
     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;
+    /**
+     * 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">;
@@ -100,16 +254,21 @@ type NativeDataTypeOptions = "boolean" | "number" | "bigint" | "string";
 type AddedDataTypeOptions = "date" | "time" | "dateTime";
 type DataTypeOptions = NativeDataTypeOptions | AddedDataTypeOptions;
 
-interface TableInfo {
-    primaryKey?: string;
-    foreignKeys?: ForeignKeyInfo[];
-    dataTypes?: Record<string, DataTypeOptions>;
+interface InputColumnInfo extends ColumnInfo {
+    inputType?: DataTypeOptions;
+    inputDefaultValue?: unknown;
+}
+
+interface InputTableStructure extends TableStructure {
+    columns: Record<string, InputColumnInfo>;
 }
 
 type DataFormat = Record<string, unknown>;
-type GetColumns<T> = T extends TableObjBuilder<infer Item, any> ? Item : never;
-type TableObjBuilder<T extends DataFormat, TPick extends keyof TableObj<T>> = Pick<TableObj<T>, TPick>;
-type TableObjInput = TableObjBuilder<any, any>;
+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)
@@ -118,17 +277,19 @@ type TableObjInput = TableObjBuilder<any, any>;
 declare class TableObj<T extends DataFormat> {
     readonly IS_TABLE_OBJ = true;
     readonly tableName: string;
-    readonly columns: T;
-    tableInfo: TableInfo;
+    tableStructure: InputTableStructure;
+    static getEmptyColumnEntry(key: string): InputColumnInfo;
+    static getColumnEntry(key: string, value: unknown): InputColumnInfo | null;
     private constructor();
-    primaryKey(key: keyof T): TableObjBuilder<T, "foreignKey" | "dataType">;
-    foreignKey<TOther extends TableObjBuilder<DataFormat, any>>(fromColumn: keyof T, toTable: TOther, toColumn: keyof GetColumns<TOther>, options?: {
+    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, "foreignKey" | "dataType">;
-    dataType(column: keyof T, type: DataTypeOptions): TableObjBuilder<T, "foreignKey" | "dataType">;
-    static create<T extends Record<string, unknown>>(tableName: string, columns: T): TableObjBuilder<T, "primaryKey" | "foreignKey" | "dataType">;
-    static isDbTable(obj: unknown): obj is TableObj<any>;
+    }): 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>;