Merge pull request #155 from jacksteamdev/add-action.transform

Add transform and when functions to actions

Author: crutchcorn

index.d.ts

@@ -181,6 +181,19 @@ export interface ActionConfig<TData extends object = object> {
    * @default true
    */
   abortOnFail?: boolean;
+  /**
+   * Skip an action if this function returns a string,
+   * which is the reason it should be skipped.
+   *
+   * May also return a Promise which resolves to a string.
+   *
+   * The action will continue if action.skip()
+   * returns or resolves to anything other than a string,
+   * and the return value will be ignored.
+   *
+   * @default () => true
+   */
+  skip?: (data: TData) => void | string | Promise<void | string>;
 }
 
 /**
@@ -211,6 +224,10 @@ export interface AddActionConfig<TData extends object = object>
    * @default false
    */
   skipIfExists?: boolean;
+  /**
+   * Transform the template result before writing the file.
+   */
+  transform?: (templateResult: string, data: TData) => string;
 }
 
 /**
@@ -258,12 +275,19 @@ export interface AddManyActionConfig<TData extends object = object>
    * @default true
    */
   verbose?: boolean;
+  /**
+   * Transform the template result before writing the file.
+   */
+  transform?: (templateResult: string, data: TData) => string;
 }
 
 /**
- * The `modify` action will use a `pattern` property to find/replace text in the
- * file located at the `path` specified. More details on modify can be found in
- * the example folder.
+ * The `modify` action will use a `pattern` property and/or a `transform` function 
+ * to find/replace or transform text in the file located at the `path` specified.
+ * 
+ * `pattern` and `transform` can be used together or individually.
+ * 
+ * More details on modify can be found in the example folder.
  */
 export interface ModifyActionConfig<TData extends object = object>
   extends ActionConfig<TData> {
@@ -280,16 +304,20 @@ export interface ModifyActionConfig<TData extends object = object>
    * Used to match text that should be replaced.
    * @default end-of-file
    */
-  pattern: string | RegExp;
+  pattern?: string | RegExp;
   /**
    * Handlebars template that should replace what was matched by the `pattern`.
    * Capture groups are available as `$1`, `$2`, etc.
    */
-  template: string;
+  template?: string;
   /**
    * Path a file containing the `template`.
    */
-  templateFile: string;
+  templateFile?: string;
+  /**
+   * Transform the file contents immediately before writing to disk.
+   */
+  transform?: (fileContents: string, data: TData) => string;
 }
 
 /**

src/actions/_common-action-add-file.js

@@ -2,6 +2,7 @@ import path from 'path';
 import del from 'del';
 import {
 	getRenderedTemplate,
+	getTransformedTemplate,
 	makeDestPath,
 	throwStringifiedError,
 	getRelativeToBasePath
@@ -38,7 +39,14 @@ export default async function addFile(data, cfg, plop) {
 				await fspp.writeFileRaw(fileDestPath, rawTemplate);
 			} else {
 				const renderedTemplate = await getRenderedTemplate(data, cfg, plop);
-				await fspp.writeFile(fileDestPath, renderedTemplate);
+
+				const transformedTemplate = await getTransformedTemplate(
+					renderedTemplate,
+					data,
+					cfg
+				);
+
+				await fspp.writeFile(fileDestPath, transformedTemplate);
 			}
 
 			// keep the executable flags

src/actions/_common-action-interface-check.js

@@ -16,5 +16,17 @@ export default function(action, {checkPath=true, checkAbortOnFail=true} = {}) {
 		return `Invalid value for abortOnFail (${abortOnFail} is not a Boolean)`;
 	}
 
+	if ('transform' in action && typeof action.transform !== 'function') {
+		return `Invalid value for transform (${typeof action.transform} is not a function)`;
+	}
+
+	if (action.type === 'modify' && !('pattern' in action) && !('transform' in action)) {
+		return 'Invalid modify action (modify must have a pattern or transform function)';
+	}
+
+	if ('skip' in action && typeof action.skip !== 'function') {
+		return `Invalid value for skip (${typeof action.skip} is not a function)`;
+	}
+
 	return true;
 }

src/actions/_common-action-utils.js

@@ -49,3 +49,21 @@ export const throwStringifiedError = err => {
 		throw err.message || JSON.stringify(err);
 	}
 };
+
+export async function getTransformedTemplate(template, data, cfg) {
+	// transform() was already typechecked at runtime in interface check
+	if ('transform' in cfg) {
+		const result = await cfg.transform(template, data);
+
+		if (typeof result !== 'string')
+			throw new TypeError(
+				`Invalid return value for transform (${JSON.stringify(
+					result
+				)} is not a string)`
+			);
+
+		return result;
+	} else {
+		return template;
+	}
+}

src/actions/modify.js

@@ -4,7 +4,8 @@ import {
 	makeDestPath,
 	throwStringifiedError,
 	getRelativeToBasePath,
-	getRenderedTemplatePath
+	getRenderedTemplatePath,
+	getTransformedTemplate
 } from './_common-action-utils';
 
 import actionInterfaceTest from './_common-action-interface-check';
@@ -26,7 +27,8 @@ export default async function (data, cfg, plop) {
 			cfg.templateFile = getRenderedTemplatePath(data, cfg, plop);
 			const replacement = await getRenderedTemplate(data, cfg, plop);
 			fileData = fileData.replace(cfg.pattern, replacement);
-			await fspp.writeFile(fileDestPath, fileData);
+			const transformed = await getTransformedTemplate(fileData, data, cfg);
+			await fspp.writeFile(fileDestPath, transformed);
 		}
 		return getRelativeToBasePath(fileDestPath, plop);
 	} catch (err) {

src/generator-runner.js

@@ -114,6 +114,14 @@ export default function (plopfileApi, flags) {
 		// data can also be a function that returns a data object
 		if (typeof cfgData === 'function') { cfgData = await cfgData(); }
 
+		// check if action should run
+		if (typeof cfg.skip === 'function') {
+			const reasonToSkip = await cfg.skip(data);
+			if (typeof reasonToSkip === 'string') {
+				return reasonToSkip;
+			}
+		}
+
 		// track keys that can be applied to the main data scope
 		const cfgDataKeys = Object.keys(cfgData).filter(k => typeof data[k] === 'undefined');
 		// copy config data into main data scope so it's available for templates
@@ -135,16 +143,19 @@ export default function (plopfileApi, flags) {
 				}
 			)
 			// cleanup main data scope so config data doesn't leak
-			.finally(() => cfgDataKeys.forEach(k => {delete data[k];}));
+			.finally(() =>
+				cfgDataKeys.forEach(k => {
+					delete data[k];
+				})
+			);
 	};
 
 	// request the list of custom actions from the plopfile
 	function getCustomActionTypes() {
-		return plopfileApi.getActionTypeList()
-			.reduce(function (types, name) {
-				types[name] = plopfileApi.getActionType(name);
-				return types;
-			}, {});
+		return plopfileApi.getActionTypeList().reduce(function(types, name) {
+			types[name] = plopfileApi.getActionType(name);
+			return types;
+		}, {});
 	}
 
 	return {