murmuration 1.0.22 → 1.0.29

package/README.md

@@ -4,8 +4,8 @@ Database connections, transactions and migrations.
 
 There are two specific packages that you should make use of instead this one:
 
-* [murmuration-mariadb](https://github.com/djalbat/murmuration-mariadb)
-* [murmuration-postgresql](https://github.com/djalbat/murmuration-postgresql)
+* [Murmuration-MariaDB](https://github.com/djalbat/murmuration-mariadb)
+* [Murmuration-PostGreSQL](https://github.com/djalbat/murmuration-postgresql)
 
 This readme file largely pertains to both, although there are also specific instructions given in readme file for each.
 
@@ -255,6 +255,58 @@ Migrations must obviously never, ever be changed once they have been committed.
 
 If used with care, this migration functionality is wholly effective in the aforementioned use case of a single database instance allied with one or possibly many application instances.
 
+### Custom migrations
+
+As well as migrations based on SQL files it is possible to add custom migrations. These are identified by custom text files that sit next to the SQL files in the migrations directory. They must have the following format:
+
+```
+12-CUSTOM.txt
+```
+
+That is, the file name must start with a contiguous version number followed by a hyphen, but end with `CUSTOM` and have a `.txt` extension. Any other format will be ignored and will also lead to all further migrations being ignored. The contents of these files can be left empty or can contain information pertinent to the custom migration. 
+
+To create a custom migration, extend the CustomMigration class and fill out the `apply()` method as needed. This example requires the CustomMigration class from the Murmuration-PostGreSQL package but the same holds for the Murmuration-MariaDB package:
+
+```
+const { CustomMigration } = require("murmuration-postgresql");
+
+class IdentifierCustomMigration extends CustomMigration {
+  apply(connection, callback) {
+    ...
+    
+    callback(error);
+  }
+
+  static fromFilePath(filePath) {
+    const identifierCustomMigration = new IdentifierCustomMigration(filePath);
+
+    return identifierCustomMigration;
+  }
+}
+```
+Note that the `apply()` method takes `connection` and `callback` arguments. The latter must be called with a boolean `error` argument when the migration completes. Also note the format of the static `fromFilePath()` factory method. The file path of the text file is available via a standard `getFilePath()` method, by the way.
+
+Custom migrations must be collected together into a map, the keys of which are precisely the file names of the custom text files in the migrations SQL directory. For example:
+
+```
+const IdentifierCustomMigration = rquire("./identifierCustomMigration");
+
+const CustomMigrationMap = {
+  "13-CUSTOM.txt" : IdentifierCustomMigration
+};
+```
+
+This map should be passed as an optional third argument to the `migrate()` function as follows:
+
+```
+migrate(configuration, migrationsDirectoryPath, CustomMigrationMap (error) => {
+
+  ...
+});
+```
+
+It is possible to use the same custom migration class for multiple custom migrations with the contents of the custom text files dictating the behaviours of at each invocation.
+
 ## Contact
 
 - james.smith@djalbat.com

package/bin/migrate/customMigration.js

@@ -0,0 +1,42 @@
+"use strict";
+
+const { arrayUtilities } = require("necessary");
+
+const { second } = arrayUtilities;
+
+class CustomMigration {
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+
+  getFilePath() {
+    return this.filePath;
+  }
+
+  getVersion() {
+    const matches = this.filePath.match(/(\d+)-.+$/),
+          secondMatch = second(matches),
+          version = secondMatch;  ///
+
+    return version;
+  }
+  
+  apply(connection, callback) {
+    const log = connection.getLog(),
+          version = this.getVersion();
+
+    log.info(`Applying custom migration version ${version}...`);
+
+    const error = true;
+
+    callback(error);
+  }
+  
+  static fromFilePath(filePath) {
+    const customMigration = new CustomMigration(filePath);
+    
+    return customMigration;
+  }
+}
+
+module.exports = CustomMigration;

package/bin/migrate/migrations.js

@@ -18,33 +18,54 @@ class Migrations {
     return migration;
   }
   
-  static fromMigrationsDirectoryPath(migrationsDirectoryPath) {
-    const entryNames = readDirectory(migrationsDirectoryPath),
-          fileNames = entryNames.reduce((fileNames, entryName) => {
-            const entryNameSQLFileName = /.+\.sql/.test(entryName);
-            
-            if (entryNameSQLFileName) {
-              const sqlFileName = entryName,  ///
-                    fileName = sqlFileName; ///
-              
-              fileNames.push(fileName);
-            }
-            
-            return fileNames;
-          }, []),
-          map = fileNames.reduce((map, fileName) => {
-            const filePath = concatenatePaths(migrationsDirectoryPath, fileName),
-                  migration = Migration.fromFilePath(filePath),
-                  version = migration.getVersion();
-
-            map[version] = migration;
-
-            return map;
-          }, {}),
-          migrations = new Migrations(map);
+  static fromCustomMigrationMapAndMigrationsDirectoryPath(CustomMigrationMap, migrationsDirectoryPath) {
+    const map = {},
+          entryNames = readDirectory(migrationsDirectoryPath),
+          sqlFileNames = sqlFileNamesFromEntryNames(entryNames),
+          customTextFileNames = customTextFileNamesFromEEntryNames(entryNames);
+
+    sqlFileNames.forEach((sqlFileName) => {
+      const filePath = concatenatePaths(migrationsDirectoryPath, sqlFileName),
+            migration = Migration.fromFilePath(filePath),
+            version = migration.getVersion();
+
+      map[version] = migration;
+    });
+
+    customTextFileNames.forEach((customTextFileName) => {
+      const filePath = concatenatePaths(migrationsDirectoryPath, customTextFileName),
+            CustomMigration = CustomMigrationMap[customTextFileName],
+            customMigration = CustomMigration.fromFilePath(filePath),
+            migration = customMigration,  ///
+            version = migration.getVersion();
+
+      map[version] = migration;
+    });
+
+    const migrations = new Migrations(map);
 
     return migrations;
   }
 }
 
 module.exports = Migrations;
+
+function customTextFileNamesFromEEntryNames(entryNames) { return fileNamesFromEntryNames(entryNames, (entryName) => /.+CUSTOM\.txt$/.test(entryName)); }
+
+function sqlFileNamesFromEntryNames(entryNames) { return fileNamesFromEntryNames(entryNames, (entryName) => /.+\.sql$/.test(entryName)); }
+
+function fileNamesFromEntryNames(entryNames, test) {
+  const fileNames = entryNames.reduce((fileNames, entryName) => {
+    const entryNameSQLFileName = test(entryName);
+
+    if (entryNameSQLFileName) {
+      const fileName = entryName;
+
+      fileNames.push(fileName);
+    }
+
+    return fileNames;
+  }, []);
+
+  return fileNames;
+}

package/bin/migrate/operation/applyMigrations.js

@@ -11,8 +11,8 @@ const { first } = arrayUtilities,
       { whilst } = asynchronousUtilities;
 
 function applyMigrationsOperation(next, done, context) {
-  const { configuration, migrationsDirectoryPath } = context,
-        migrations = Migrations.fromMigrationsDirectoryPath(migrationsDirectoryPath),
+  const { configuration, CustomMigrationMap, migrationsDirectoryPath } = context,
+        migrations = Migrations.fromCustomMigrationMapAndMigrationsDirectoryPath(CustomMigrationMap, migrationsDirectoryPath),
         { log } = configuration;
 
   if (log) {

package/bin/migrate.js

@@ -7,7 +7,13 @@ const { asynchronousUtilities } = require("necessary");
 
 const { sequence } = asynchronousUtilities;
 
-function migrate(configuration, migrationsDirectoryPath, callback) {
+function migrate(configuration, migrationsDirectoryPath, CustomMigrationMap, callback) {
+  if (callback === undefined) {
+    callback = CustomMigrationMap; ///
+
+    CustomMigrationMap = {};
+  }
+
   const callbacks = [
           initialiseOperation,
           applyMigrationsOperation
@@ -16,6 +22,7 @@ function migrate(configuration, migrationsDirectoryPath, callback) {
         context = {
           error,
           configuration,
+          CustomMigrationMap,
           migrationsDirectoryPath
         };
 

package/index.js

@@ -3,11 +3,13 @@
 const migrate = require("./bin/migrate"),
       database = require("./bin/database"),
       defaultLog = require("./bin/defaultLog"),
-      transaction = require("./bin/transaction");
+      transaction = require("./bin/transaction"),
+      CustomMigration = require("./bin/migrate/customMigration");
 
 module.exports = {
   migrate,
   database,
   defaultLog,
-  transaction
+  transaction,
+  CustomMigration
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "murmuration",
   "author": "James Smith",
-  "version": "1.0.22",
+  "version": "1.0.29",
   "license": "MIT, Anti-996",
   "homepage": "https://github.com/djalbat/murmuration",
   "description": "Database connections, transactions and migrations.",
@@ -10,7 +10,7 @@
     "url": "https://github.com/djalbat/murmuration"
   },
   "dependencies": {
-    "necessary": "^11.0.2"
+    "necessary": "^11.0.40"
   },
   "devDependencies": {},
   "scripts": {}