sqlmorpheus 0.1.4 → 0.1.5

package/dist/index.d.mts

@@ -121,6 +121,7 @@ declare function ForeignKey<TOther extends BackendTable>(toTable: Class<TOther>,
 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 runMigrationWithoutHistory(db: DatabaseAccess, instructions: DatabaseInstructions): Promise<void>;
 declare function rollback(db: DatabaseAccess, instructions: DatabaseInstructions, toVersion: number): Promise<void>;
 
-export { type DatabaseInstructions, DbTable, ForeignKey, prepareAndRunMigration, prepareMigration, rollback, runPreparedMigrations };
+export { type DatabaseInstructions, DbTable, ForeignKey, prepareAndRunMigration, prepareMigration, rollback, runMigrationWithoutHistory, runPreparedMigrations };

package/dist/index.d.ts

@@ -121,6 +121,7 @@ declare function ForeignKey<TOther extends BackendTable>(toTable: Class<TOther>,
 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 runMigrationWithoutHistory(db: DatabaseAccess, instructions: DatabaseInstructions): Promise<void>;
 declare function rollback(db: DatabaseAccess, instructions: DatabaseInstructions, toVersion: number): Promise<void>;
 
-export { type DatabaseInstructions, DbTable, ForeignKey, prepareAndRunMigration, prepareMigration, rollback, runPreparedMigrations };
+export { type DatabaseInstructions, DbTable, ForeignKey, prepareAndRunMigration, prepareMigration, rollback, runMigrationWithoutHistory, runPreparedMigrations };

package/dist/index.js

@@ -25,6 +25,7 @@ __export(index_exports, {
   prepareAndRunMigration: () => prepareAndRunMigration,
   prepareMigration: () => prepareMigration,
   rollback: () => rollback,
+  runMigrationWithoutHistory: () => runMigrationWithoutHistory,
   runPreparedMigrations: () => runPreparedMigrations
 });
 module.exports = __toCommonJS(index_exports);
@@ -253,6 +254,12 @@ var MigrationHistoryManager = class {
     (0, import_node_fs.mkdirSync)(this.configPath, { recursive: true });
     (0, import_node_fs.mkdirSync)(this.migrationsPath, { recursive: true });
   }
+  /**
+   * Retrieves the last recorded history version from the configuration path.
+   * If the version is not already cached in memory, this method reads it from a file on disk.
+   *
+   * @return The last version number, or 0 if the version file does not exist or cannot be parsed.
+   */
   getLastHistoryVersion() {
     if (this.lastVersion)
       return this.lastVersion;
@@ -260,9 +267,21 @@ var MigrationHistoryManager = class {
     this.lastVersion = (0, import_node_fs.existsSync)(path) ? parseInt((0, import_fs.readFileSync)(`${this.configPath}/last_version.txt`, { encoding: "utf-8" })) ?? 0 : 0;
     return this.lastVersion;
   }
+  /**
+   * Updates the "last history version" information by writing the given version to a file.
+   *
+   * @param version - The version number to set as the last history version.
+   */
   setLastHistoryVersion(version) {
     (0, import_node_fs.writeFileSync)(`${this.configPath}/last_version.txt`, version.toString(), { encoding: "utf-8" });
   }
+  /**
+   * Creates migration history files for upgrading and downgrading database schemas.
+   *
+   * @param toVersion - The target version number for the migration.
+   * @param changes - An object containing the SQL changes for upgrading (`changes.up`) and downgrading (`changes.down`).
+   * @param overwriteExisting - A flag that determines if existing migration files should be overwritten. Defaults to `false`.
+   */
   createMigrationHistory(toVersion, changes, overwriteExisting) {
     const fromVersion = this.getLastHistoryVersion();
     const upPath = `${this.migrationsPath}/${FILENAME_UP_PREFIX}${toVersion}.sql`;
@@ -279,9 +298,22 @@ ${changes.up}`, { encoding: "utf-8" });
 -- To:   Version ${fromVersion}
 ${changes.down}`, { encoding: "utf-8" });
   }
+  /**
+   * Retrieves the SQL migration script for upgrading to the specified version.
+   * If no version is provided, it retrieves the migration script for the latest version in the history.
+   *
+   * @param toVersion - The version of the migration script to retrieve. If not specified, the latest version is used.
+   * @return The content of the SQL migration script as a string.
+   */
   getUpMigration(toVersion) {
     return (0, import_fs.readFileSync)(`${this.migrationsPath}/${FILENAME_UP_PREFIX}${toVersion ?? this.getLastHistoryVersion()}.sql`, { encoding: "utf-8" });
   }
+  /**
+   * Retrieves the SQL migration script for downgrading to the specified version.
+   *
+   * @param version - The version number of the migration to retrieve.
+   * @return The SQL script for the down migration.
+   */
   getDownMigration(version) {
     return (0, import_fs.readFileSync)(`${this.migrationsPath}/${FILENAME_DOWN_PREFIX}${version}.sql`, { encoding: "utf-8" });
   }
@@ -581,6 +613,17 @@ var MigrationManager = class {
     this.tableStructureGenerator = new TableStructureGenerator(dbInstructions, this.dialect);
     this.migrationHistoryManager = new MigrationHistoryManager(this.dbInstructions.configPath);
   }
+  /**
+   * Generates the SQL changes required to migrate a database from its current version
+   * to the target version defined in the database instructions. Handles the creation
+   * and deletion of tables, migration of foreign keys and columns, renaming of columns,
+   * and recreating tables, along with executing any pre- and post-migration custom logic.
+   *
+   * @return A promise that resolves to an object containing the SQL
+   * changes for the migration (`up` and `down` changes) or null if no migration is required.
+   * Throws an error in scenarios such as attempting to migrate to a lower version
+   * or an invalid starting version.
+   */
   async getMigrateSql() {
     if (this.dbInstructions.version <= 0)
       throw new Error("Cannot migrate to version 0 or lower");
@@ -649,12 +692,28 @@ ${foreignKeyOnQuery}`;
 ${foreignKeyOnQuery}`;
     return changes;
   }
+  /**
+   * Prepares the migration by generating the SQL changes and creating a migration history entry.
+   * If no changes are needed, the method exits early.
+   *
+   * @param overwriteExisting - Optional flag indicating if overwriting existing changes is allowed.
+   * @return - A promise that resolves once the migration preparation is complete.
+   */
   async prepareMigration(overwriteExisting) {
     const changes = await this.getMigrateSql();
     if (!changes)
       return;
     this.migrationHistoryManager.createMigrationHistory(this.dbInstructions.version, changes, overwriteExisting);
   }
+  /**
+   * Generates SQL change statements for creating and dropping tables based on the current table structure
+   * and existing table configurations in the database. The `up` changes include SQL statements for creating
+   * new tables, while the `down` changes include SQL statements for dropping the corresponding tables or
+   * recreating them if necessary.
+   *
+   * @return {Promise<SqlChanges>} A promise that resolves to an object containing `up` and `down` SQL
+   * change statements for migrating the database schema.
+   */
   async createAndDropTables() {
     let changes = {
       up: "\n\n-- Create tables\n",
@@ -681,6 +740,16 @@ ${foreignKeyOnQuery}`;
     }
     return changes;
   }
+  /**
+   * Generates an SQL string to create a table with the specified schema.
+   *
+   * @param tableName - The name of the table to be created.
+   * @param columns - An array of objects defining the columns of the table, including their names, types
+   * default values, and whether they are primary keys.
+   * @param foreignKeys - An optional array of objects defining the foreign key constraints for the table,
+   * including the source column, target table, target column, action on update, and action on delete.
+   * @return The complete SQL string to create the table with the specified structure and constraints.
+   */
   createTableSql(tableName, columns, foreignKeys) {
     const queryLines = [];
     for (const columnInfo of columns) {
@@ -693,9 +762,20 @@ ${foreignKeyOnQuery}`;
     }
     return this.dialect.createTable(tableName, queryLines);
   }
+  /**
+   * Checks if the specified table does not exist in the list of existing tables.
+   *
+   * @param tableName - The name of the table to check.
+   * @return Returns true if the table does not exist, otherwise false.
+   */
   tableDoesNotExists(tableName) {
     return this.existingTables.indexOf(tableName) == -1;
   }
+  /**
+   * Recreates database tables that have been flagged to be recreated in migration data.
+   * This method generated the necessary SQL code for backing up the current table data, dropping and recreating
+   * the tables, and reinserting the preserved data into the recreated tables.
+   */
   async recreateTables() {
     const changes = {
       up: "\n\n-- Recreate tables\n",
@@ -724,6 +804,9 @@ ${foreignKeyOnQuery}`;
     }
     return changes;
   }
+  /**
+   * Migrates foreign key constraints for all defined tables.
+   */
   async migrateForeignKeys() {
     if (!this.dialect.canAlterForeignKeys)
       return { up: "", down: "" };
@@ -847,12 +930,22 @@ ${foreignKeyOnQuery}`;
     }
     return changes;
   }
+  /**
+   * Retrieves the name of the primary key column from a list of column information.
+   *
+   * @param columnInfoList - An array of ColumnInfo objects containing details about each column.
+   * @return The name of the primary key column if found; otherwise, undefined.
+   */
   getPrimaryKeyColumn(columnInfoList) {
     for (const columnInfo of columnInfoList) {
       if (columnInfo.isPrimaryKey)
         return columnInfo.name;
     }
   }
+  /**
+   * Handles the renaming of columns in database tables by generating SQL changes for both applying and reverting the renames.
+   * Skips tables that are marked for recreation.
+   */
   renameColumns() {
     const changes = {
       up: "\n\n-- Rename columns\n",
@@ -932,6 +1025,13 @@ async function prepareAndRunMigration(db, instructions, overwriteExisting) {
   await prepareMigration(db, instructions, overwriteExisting);
   await runPreparedMigrations(db, instructions);
 }
+async function runMigrationWithoutHistory(db, instructions) {
+  Logger.setMode(instructions.loggerMode);
+  const mm = new MigrationManager(db, instructions);
+  const changes = await mm.getMigrateSql();
+  if (changes)
+    await db.runMultipleWriteStatements(changes.up);
+}
 async function rollback(db, instructions, toVersion) {
   Logger.setMode(instructions.loggerMode);
   const migrationHistoryManager = new MigrationHistoryManager(instructions.configPath);
@@ -952,5 +1052,6 @@ async function rollback(db, instructions, toVersion) {
   prepareAndRunMigration,
   prepareMigration,
   rollback,
+  runMigrationWithoutHistory,
   runPreparedMigrations
 });

package/dist/index.mjs

@@ -222,6 +222,12 @@ var MigrationHistoryManager = class {
     mkdirSync(this.configPath, { recursive: true });
     mkdirSync(this.migrationsPath, { recursive: true });
   }
+  /**
+   * Retrieves the last recorded history version from the configuration path.
+   * If the version is not already cached in memory, this method reads it from a file on disk.
+   *
+   * @return The last version number, or 0 if the version file does not exist or cannot be parsed.
+   */
   getLastHistoryVersion() {
     if (this.lastVersion)
       return this.lastVersion;
@@ -229,9 +235,21 @@ var MigrationHistoryManager = class {
     this.lastVersion = existsSync(path) ? parseInt(readFileSync(`${this.configPath}/last_version.txt`, { encoding: "utf-8" })) ?? 0 : 0;
     return this.lastVersion;
   }
+  /**
+   * Updates the "last history version" information by writing the given version to a file.
+   *
+   * @param version - The version number to set as the last history version.
+   */
   setLastHistoryVersion(version) {
     writeFileSync(`${this.configPath}/last_version.txt`, version.toString(), { encoding: "utf-8" });
   }
+  /**
+   * Creates migration history files for upgrading and downgrading database schemas.
+   *
+   * @param toVersion - The target version number for the migration.
+   * @param changes - An object containing the SQL changes for upgrading (`changes.up`) and downgrading (`changes.down`).
+   * @param overwriteExisting - A flag that determines if existing migration files should be overwritten. Defaults to `false`.
+   */
   createMigrationHistory(toVersion, changes, overwriteExisting) {
     const fromVersion = this.getLastHistoryVersion();
     const upPath = `${this.migrationsPath}/${FILENAME_UP_PREFIX}${toVersion}.sql`;
@@ -248,9 +266,22 @@ ${changes.up}`, { encoding: "utf-8" });
 -- To:   Version ${fromVersion}
 ${changes.down}`, { encoding: "utf-8" });
   }
+  /**
+   * Retrieves the SQL migration script for upgrading to the specified version.
+   * If no version is provided, it retrieves the migration script for the latest version in the history.
+   *
+   * @param toVersion - The version of the migration script to retrieve. If not specified, the latest version is used.
+   * @return The content of the SQL migration script as a string.
+   */
   getUpMigration(toVersion) {
     return readFileSync(`${this.migrationsPath}/${FILENAME_UP_PREFIX}${toVersion ?? this.getLastHistoryVersion()}.sql`, { encoding: "utf-8" });
   }
+  /**
+   * Retrieves the SQL migration script for downgrading to the specified version.
+   *
+   * @param version - The version number of the migration to retrieve.
+   * @return The SQL script for the down migration.
+   */
   getDownMigration(version) {
     return readFileSync(`${this.migrationsPath}/${FILENAME_DOWN_PREFIX}${version}.sql`, { encoding: "utf-8" });
   }
@@ -550,6 +581,17 @@ var MigrationManager = class {
     this.tableStructureGenerator = new TableStructureGenerator(dbInstructions, this.dialect);
     this.migrationHistoryManager = new MigrationHistoryManager(this.dbInstructions.configPath);
   }
+  /**
+   * Generates the SQL changes required to migrate a database from its current version
+   * to the target version defined in the database instructions. Handles the creation
+   * and deletion of tables, migration of foreign keys and columns, renaming of columns,
+   * and recreating tables, along with executing any pre- and post-migration custom logic.
+   *
+   * @return A promise that resolves to an object containing the SQL
+   * changes for the migration (`up` and `down` changes) or null if no migration is required.
+   * Throws an error in scenarios such as attempting to migrate to a lower version
+   * or an invalid starting version.
+   */
   async getMigrateSql() {
     if (this.dbInstructions.version <= 0)
       throw new Error("Cannot migrate to version 0 or lower");
@@ -618,12 +660,28 @@ ${foreignKeyOnQuery}`;
 ${foreignKeyOnQuery}`;
     return changes;
   }
+  /**
+   * Prepares the migration by generating the SQL changes and creating a migration history entry.
+   * If no changes are needed, the method exits early.
+   *
+   * @param overwriteExisting - Optional flag indicating if overwriting existing changes is allowed.
+   * @return - A promise that resolves once the migration preparation is complete.
+   */
   async prepareMigration(overwriteExisting) {
     const changes = await this.getMigrateSql();
     if (!changes)
       return;
     this.migrationHistoryManager.createMigrationHistory(this.dbInstructions.version, changes, overwriteExisting);
   }
+  /**
+   * Generates SQL change statements for creating and dropping tables based on the current table structure
+   * and existing table configurations in the database. The `up` changes include SQL statements for creating
+   * new tables, while the `down` changes include SQL statements for dropping the corresponding tables or
+   * recreating them if necessary.
+   *
+   * @return {Promise<SqlChanges>} A promise that resolves to an object containing `up` and `down` SQL
+   * change statements for migrating the database schema.
+   */
   async createAndDropTables() {
     let changes = {
       up: "\n\n-- Create tables\n",
@@ -650,6 +708,16 @@ ${foreignKeyOnQuery}`;
     }
     return changes;
   }
+  /**
+   * Generates an SQL string to create a table with the specified schema.
+   *
+   * @param tableName - The name of the table to be created.
+   * @param columns - An array of objects defining the columns of the table, including their names, types
+   * default values, and whether they are primary keys.
+   * @param foreignKeys - An optional array of objects defining the foreign key constraints for the table,
+   * including the source column, target table, target column, action on update, and action on delete.
+   * @return The complete SQL string to create the table with the specified structure and constraints.
+   */
   createTableSql(tableName, columns, foreignKeys) {
     const queryLines = [];
     for (const columnInfo of columns) {
@@ -662,9 +730,20 @@ ${foreignKeyOnQuery}`;
     }
     return this.dialect.createTable(tableName, queryLines);
   }
+  /**
+   * Checks if the specified table does not exist in the list of existing tables.
+   *
+   * @param tableName - The name of the table to check.
+   * @return Returns true if the table does not exist, otherwise false.
+   */
   tableDoesNotExists(tableName) {
     return this.existingTables.indexOf(tableName) == -1;
   }
+  /**
+   * Recreates database tables that have been flagged to be recreated in migration data.
+   * This method generated the necessary SQL code for backing up the current table data, dropping and recreating
+   * the tables, and reinserting the preserved data into the recreated tables.
+   */
   async recreateTables() {
     const changes = {
       up: "\n\n-- Recreate tables\n",
@@ -693,6 +772,9 @@ ${foreignKeyOnQuery}`;
     }
     return changes;
   }
+  /**
+   * Migrates foreign key constraints for all defined tables.
+   */
   async migrateForeignKeys() {
     if (!this.dialect.canAlterForeignKeys)
       return { up: "", down: "" };
@@ -816,12 +898,22 @@ ${foreignKeyOnQuery}`;
     }
     return changes;
   }
+  /**
+   * Retrieves the name of the primary key column from a list of column information.
+   *
+   * @param columnInfoList - An array of ColumnInfo objects containing details about each column.
+   * @return The name of the primary key column if found; otherwise, undefined.
+   */
   getPrimaryKeyColumn(columnInfoList) {
     for (const columnInfo of columnInfoList) {
       if (columnInfo.isPrimaryKey)
         return columnInfo.name;
     }
   }
+  /**
+   * Handles the renaming of columns in database tables by generating SQL changes for both applying and reverting the renames.
+   * Skips tables that are marked for recreation.
+   */
   renameColumns() {
     const changes = {
       up: "\n\n-- Rename columns\n",
@@ -901,6 +993,13 @@ async function prepareAndRunMigration(db, instructions, overwriteExisting) {
   await prepareMigration(db, instructions, overwriteExisting);
   await runPreparedMigrations(db, instructions);
 }
+async function runMigrationWithoutHistory(db, instructions) {
+  Logger.setMode(instructions.loggerMode);
+  const mm = new MigrationManager(db, instructions);
+  const changes = await mm.getMigrateSql();
+  if (changes)
+    await db.runMultipleWriteStatements(changes.up);
+}
 async function rollback(db, instructions, toVersion) {
   Logger.setMode(instructions.loggerMode);
   const migrationHistoryManager = new MigrationHistoryManager(instructions.configPath);
@@ -920,5 +1019,6 @@ export {
   prepareAndRunMigration,
   prepareMigration,
   rollback,
+  runMigrationWithoutHistory,
   runPreparedMigrations
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlmorpheus",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "author": "JodliDev",
   "keywords": [],
   "license": "MIT",