beforeMigration option

readme.md

@@ -131,6 +131,46 @@ const store = new Conf({
 
 > Note: The version the migrations use refers to the **project version** by default. If you want to change this behavior, specify the [`projectVersion`](#projectVersion) option.
 
+### beforeMigration
+
+Type: `Function`\
+Default: `undefined`
+
+You can use `beforeMigration` callback for logging purposes, preparing migration data, etc.
+
+`beforeMigration` callback will be called before the migration is executed.
+
+It could be useful when u have multiple configs and you want to log the migration data for each config.
+
+Example:
+
+```js
+const Conf = require('conf');
+
+console.log = someLogger.log;
+
+const mainConfig = new Conf({
+	beforeMigration: (store, currentVersion, nextVersion) => {
+		console.log(`[main-config] migrate from ${currentVersion} -> ${nextVersion}`);
+	},
+	migrations: {
+		'0.4.0': store => {
+			store.set('debugPhase', true);
+		},
+	}
+});
+const secondConfig = new Conf({
+	beforeMigration: (store, currentVersion, nextVersion) => {
+		console.log(`[second-config] migrate from ${currentVersion} -> ${nextVersion}`);
+	},
+	migrations: {
+		'1.0.1': store => {
+			store.set('debugPhase', true);
+		},
+	}
+});
+```
+
 #### configName
 
 Type: `string`\

source/index.ts

@@ -14,11 +14,11 @@ import debounceFn = require('debounce-fn');
 import semver = require('semver');
 import onetime = require('onetime');
 import {JSONSchema} from 'json-schema-typed';
-import {Deserialize, Migrations, OnDidChangeCallback, Options, Serialize, Unsubscribe, Schema, OnDidAnyChangeCallback} from './types';
+import {Deserialize, Migrations, OnDidChangeCallback, Options, Serialize, Unsubscribe, Schema, OnDidAnyChangeCallback, BeforeMigrationCallback} from './types';
 
 const encryptionAlgorithm = 'aes-256-cbc';
 
-const createPlainObject = <T = unknown>(): T => {
+const createPlainObject = <T = Record<string, unknown>>(): T => {
 	return Object.create(null);
 };
 
@@ -141,7 +141,7 @@ class Conf<T extends Record<string, any> = Record<string, unknown>> implements I
 		this.path = path.resolve(options.cwd, `${options.configName ?? 'config'}${fileExtension}`);
 
 		const fileStore = this.store;
-		const store = Object.assign(createPlainObject<T>(), options.defaults, fileStore);
+		const store = Object.assign(createPlainObject(), options.defaults, fileStore);
 		this._validate(store);
 
 		try {
@@ -163,7 +163,7 @@ class Conf<T extends Record<string, any> = Record<string, unknown>> implements I
 				throw new Error('Project version could not be inferred. Please specify the `projectVersion` option.');
 			}
 
-			this._migrate(options.migrations, options.projectVersion);
+			this._migrate(options.migrations, options.projectVersion, options.beforeMigration);
 		}
 	}
 
@@ -499,7 +499,7 @@ class Conf<T extends Record<string, any> = Record<string, unknown>> implements I
 		}
 	}
 
-	private _migrate(migrations: Migrations<T>, versionToMigrate: string): void {
+	private _migrate(migrations: Migrations<T>, versionToMigrate: string, beforeMigration?: BeforeMigrationCallback<T>): void {
 		let previousMigratedVersion = this._get(MIGRATION_KEY, '0.0.0');
 
 		const newerVersions = Object.keys(migrations)
@@ -509,6 +509,10 @@ class Conf<T extends Record<string, any> = Record<string, unknown>> implements I
 
 		for (const version of newerVersions) {
 			try {
+				if (beforeMigration) {
+					beforeMigration(this, previousMigratedVersion, version);
+				}
+
 				const migration = migrations[version];
 				migration(this);
 

source/types.ts

@@ -103,6 +103,16 @@ export interface Options<T extends Record<string, any>> {
 	*/
 	migrations?: Migrations<T>;
 
+	/**
+	You can use `beforeMigration` callback for logging purposes, preparing migration data, etc.
+
+	`beforeMigration` callback will be called before the migration is executed.
+
+	It could be useful when u have multiple configs and you want to log the migration data for each config.
+
+	*/
+	beforeMigration?: BeforeMigrationCallback<T>;
+
 	/**
 	__You most likely don't need this. Please don't use it unless you really have to.__
 
@@ -226,6 +236,7 @@ export interface Options<T extends Record<string, any>> {
 }
 
 export type Migrations<T extends Record<string, any>> = Record<string, (store: Conf<T>) => void>;
+export type BeforeMigrationCallback<T extends Record<string, any>> = (store: Conf<T>, currentVersion: string, previousVersion: string) => void;
 
 export type Schema<T> = {[Property in keyof T]: ValueSchema};
 export type ValueSchema = TypedJSONSchema;

test/index.test-d.ts

@@ -135,6 +135,10 @@ expectError<number>(config.get('unicorn', 1));
 
 // -- Migrations --
 new Conf({
+	beforeMigration: (store, currentVersion, nextVersion) => {
+		console.log(`[main-config] migrate from ${currentVersion} -> ${nextVersion}`);
+		console.log(`[main-config] phase ${(store.get('phase') || 'none') as string}`);
+	},
 	migrations: {
 		'0.0.1': store => {
 			store.set('debug phase', true);

test/index.ts

@@ -1203,3 +1203,22 @@ test('__internal__ keys - should only match specific "__internal__" entry', t =>
 		conf.set('__internal__foo.you-shall', 'not-pass');
 	});
 });
+
+test('beforeMigration - should be called before every migration', t => {
+	const conf = new Conf({
+		cwd: tempy.directory(),
+		projectVersion: '2.0.0',
+		beforeMigration: (store, currentVersion, nextVersion) => {
+			store.set(`beforeMigration ${currentVersion} -> ${nextVersion}`, true);
+		},
+		migrations: {
+			'1.0.0': () => {},
+			'1.0.1': () => {},
+			'2.0.1': () => {}
+		}
+	});
+
+	t.is(conf.get('beforeMigration 0.0.0 -> 1.0.0'), true);
+	t.is(conf.get('beforeMigration 1.0.0 -> 1.0.1'), true);
+	t.false(conf.has('beforeMigration 1.0.1 -> 2.0.1'));
+});