sqlmorpheus 0.1.2 → 0.1.4

package/dist/index.d.mts

@@ -98,8 +98,24 @@ interface DatabaseInstructions {
     postMigration?(fromVersion: number, toVersion: number): SqlChanges;
 }
 
+/**
+ * Decorator function to configure a database table with its name and primary key
+ * and to add missing "fromTable" properties to foreign keys.
+ *
+ * @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;
 
+/**
+ * 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.
+ *
+ * @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.
+ */
 declare function ForeignKey<TOther extends BackendTable>(toTable: Class<TOther>, toColumn: keyof TOther, onDelete?: ForeignKeyActions, onUpdate?: ForeignKeyActions): (table: any, context: any) => void;
 
 declare function prepareMigration(db: DatabaseAccess, instructions: DatabaseInstructions, overwriteExisting?: boolean): Promise<void>;
@@ -107,4 +123,4 @@ declare function runPreparedMigrations(db: DatabaseAccess, instructions: Databas
 declare function prepareAndRunMigration(db: DatabaseAccess, instructions: DatabaseInstructions, overwriteExisting?: boolean): Promise<void>;
 declare function rollback(db: DatabaseAccess, instructions: DatabaseInstructions, toVersion: number): Promise<void>;
 
-export { DbTable, ForeignKey, prepareAndRunMigration, prepareMigration, rollback, runPreparedMigrations };
+export { type DatabaseInstructions, DbTable, ForeignKey, prepareAndRunMigration, prepareMigration, rollback, runPreparedMigrations };

package/dist/index.d.ts

@@ -1,9 +1,126 @@
-import { DatabaseAccess } from "./lib/typings/DatabaseAccess";
-import DatabaseInstructions from "./lib/typings/DatabaseInstructions";
-import DbTable from "./lib/tableInfo/decorators/DbTable";
-import ForeignKey from "./lib/tableInfo/decorators/ForeignKey";
-export declare function prepareMigration(db: DatabaseAccess, instructions: DatabaseInstructions, overwriteExisting?: boolean): Promise<void>;
-export declare function runPreparedMigrations(db: DatabaseAccess, instructions: DatabaseInstructions): Promise<void>;
-export declare function prepareAndRunMigration(db: DatabaseAccess, instructions: DatabaseInstructions, overwriteExisting?: boolean): Promise<void>;
-export declare function rollback(db: DatabaseAccess, instructions: DatabaseInstructions, toVersion: number): Promise<void>;
-export { DbTable, ForeignKey };
+interface DatabaseAccess {
+    createBackup?(name: string): Promise<void>;
+    runGetStatement(query: string): Promise<unknown>;
+    runMultipleWriteStatements(query: string): Promise<void>;
+}
+
+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 = {
+    [key: string]: any;
+};
+
+interface AllowedMigrations {
+    recreateTable?: boolean;
+    dropTable?: boolean;
+    dropColumn?: boolean;
+    alterPrimaryKey?: boolean;
+    removeForeignKey?: boolean;
+    alterForeignKey?: boolean;
+    continueWithoutRollback?: boolean;
+}
+
+interface MigrationInstructions {
+    oldTableName?: string;
+    recreate: boolean;
+    /**
+     * Stores changes to column (0: name in the database, last: current name in code)
+     */
+    renamedColumns: string[][];
+    allowedMigrations: Record<number, AllowedMigrations>;
+}
+
+declare class Migrations {
+    private readonly migrationData;
+    private alwaysAllowed;
+    private getEntry;
+    private getTableName;
+    alwaysAllow(...allowedMigrations: (keyof AllowedMigrations)[]): void;
+    allowMigration(version: number, table: string | Class<BackendTable>, ...allowedMigrations: (keyof AllowedMigrations)[]): void;
+    throwIfNotAllowed(version: number, tableName: string, type: keyof AllowedMigrations): void;
+    renameTable(oldTableName: string, newTable: string | Class<BackendTable>): void;
+    renameColumn(table: string | Class<BackendTable>, oldColumn: string, newColumn: string): void;
+    recreateTable(table: Class<BackendTable> | string): void;
+    getMigrationData(): Record<string, MigrationInstructions>;
+    loopRenamedColumns(tableName: string, callback: (oldColumnName: string, newColumnName: string) => void): void;
+    getUpdatedColumnName(tableName: string, oldColumnName: string): string;
+    willBeRecreated(tableName: string): boolean;
+}
+type PublicMigrations = Pick<Migrations, "recreateTable" | "renameTable" | "renameColumn" | "allowMigration" | "alwaysAllow">;
+
+interface SqlChanges {
+    up: string;
+    down: string;
+}
+
+type ForeignKeyActions = "SET NULL" | "SET DEFAULT" | "RESTRICT" | "NO ACTION" | "CASCADE";
+interface ForeignKeyInfo {
+    fromTable: string;
+    fromColumn: string;
+    toTable: string;
+    toColumn: string;
+    onUpdate?: ForeignKeyActions;
+    onDelete?: ForeignKeyActions;
+}
+
+interface TableInfo {
+    primaryKey?: string;
+    foreignKeys?: ForeignKeyInfo[];
+}
+
+type TableObjects = Record<string, {
+    columns: BackendTable;
+    tableInfo?: TableInfo;
+}>;
+
+interface DatabaseInstructions {
+    dialect: "Sqlite" | "MsSql" | "MySql" | "Postgres";
+    tables: Class<BackendTable>[] | TableObjects;
+    version: number;
+    configPath: string;
+    loggerMode?: "silent" | "noLog" | "normal" | "debug";
+    /**
+     * 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.
+     * @return custom SQL that should be executed before migrations are executed.
+     */
+    preMigration?(migrations: PublicMigrations, 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.
+     */
+    postMigration?(fromVersion: number, toVersion: number): SqlChanges;
+}
+
+/**
+ * Decorator function to configure a database table with its name and primary key
+ * and to add missing "fromTable" properties to foreign keys.
+ *
+ * @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;
+
+/**
+ * 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.
+ *
+ * @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.
+ */
+declare function ForeignKey<TOther extends BackendTable>(toTable: Class<TOther>, toColumn: keyof TOther, onDelete?: ForeignKeyActions, onUpdate?: ForeignKeyActions): (table: any, context: any) => void;
+
+declare function prepareMigration(db: DatabaseAccess, instructions: DatabaseInstructions, overwriteExisting?: boolean): Promise<void>;
+declare function runPreparedMigrations(db: DatabaseAccess, instructions: DatabaseInstructions): Promise<void>;
+declare function prepareAndRunMigration(db: DatabaseAccess, instructions: DatabaseInstructions, overwriteExisting?: boolean): Promise<void>;
+declare function rollback(db: DatabaseAccess, instructions: DatabaseInstructions, toVersion: number): Promise<void>;
+
+export { type DatabaseInstructions, DbTable, ForeignKey, prepareAndRunMigration, prepareMigration, rollback, runPreparedMigrations };