Add transform option for custom file transformations

sindresorhus · sindresorhus · commit b5d18fc0fced · 2025-09-11T19:13:41.000+07:00
Fixes #5
diff --git a/api.d.ts b/api.d.ts
@@ -4,13 +4,16 @@ export type FileChange = {
 	newContent: string;
 };
 
+export type ReplaceInFilesOptions = {
+	find?: Array<string | RegExp>;
+	replacement?: string; // Required when `find` exists
+	ignoreCase?: boolean;
+	glob?: boolean;
+	dryRun?: boolean;
+	transform?: (content: string, filePath: string) => string;
+};
+
 export default function replaceInFiles(
-	path: string | string[],
-	options: {
-		find: Array<string | RegExp>;
-		replacement: string;
-		ignoreCase?: boolean;
-		glob?: boolean;
-		dryRun?: boolean;
-	},
+	paths: string | readonly string[],
+	options?: ReplaceInFilesOptions,
 ): Promise<void | FileChange[]>;
diff --git a/api.js b/api.js
@@ -1,73 +1,133 @@
 import process from 'node:process';
 import path from 'node:path';
-import {promises as fsPromises} from 'node:fs';
+import {promises as fs} from 'node:fs';
 import normalizePath_ from 'normalize-path';
 import writeFileAtomic from 'write-file-atomic';
 import escapeStringRegexp from 'escape-string-regexp';
 import {globby} from 'globby';
 
 const normalizePath = process.platform === 'win32' ? normalizePath_ : x => x;
 
-// TODO(sindresorhus): I will extract this to a separate module at some point when it's more mature.
-// `find` is expected to be `Array<string | RegExp>`
-// The `ignoreCase` option overrides the `i` flag for regexes in `find`
-export default async function replaceInFiler(filePaths, {find, replacement, ignoreCase, glob, dryRun} = {}) {
-	filePaths = [filePaths].flat();
+const toArray = value => {
+	if (value === undefined) {
+		return [];
+	}
+
+	return Array.isArray(value) ? value : [value];
+};
 
-	if (filePaths.length === 0) {
-		return;
+const normalizeRegex = (pattern, forceIgnoreCase) => {
+	if (!(pattern instanceof RegExp)) {
+		throw new TypeError('Expected a RegExp');
 	}
 
-	if (find.length === 0) {
-		throw new Error('Expected at least one `find` pattern');
+	const flags = new Set(pattern.flags);
+	flags.add('g');
+
+	// Override case handling
+	if (forceIgnoreCase) {
+		flags.add('i');
+	} else if (forceIgnoreCase === false) {
+		flags.delete('i');
 	}
 
-	if (replacement === undefined) {
-		throw new Error('The `replacement` option is required');
+	return new RegExp(pattern.source, [...flags].join(''));
+};
+
+/**
+ * Replace matching strings and regexes in files.
+ * - If `find` is provided, `replacement` must be a string.
+ * - If `transform` is provided, it runs after all find/replace operations.
+ * - When `dryRun` is true, returns a list of proposed changes.
+ */
+export default async function replaceInFiles(
+	inputPaths,
+	{
+		find,
+		replacement,
+		ignoreCase = false,
+		glob = true,
+		dryRun = false,
+		transform,
+	} = {},
+) {
+	const filePathPatterns = toArray(inputPaths);
+
+	if (transform !== undefined && typeof transform !== 'function') {
+		throw new TypeError('The `transform` option must be a function');
 	}
 
-	// Replace the replacement string with the string unescaped (only one backslash) if it's escaped
-	replacement = replacement
-		.replaceAll('\\n', '\n')
-		.replaceAll('\\r', '\r')
-		.replaceAll('\\t', '\t');
+	const hasFind = Array.isArray(find) && find.length > 0;
+	const hasTransform = typeof transform === 'function';
+
+	if (!hasFind && !hasTransform) {
+		throw new Error('Expected at least one `find` pattern or a `transform` function');
+	}
 
-	// TODO: Drop the `normalizePath` call when `convertPathToPattern` from `fast-glob` is added to globby.
-	filePaths = glob ? await globby(filePaths.map(filePath => normalizePath(filePath))) : [...new Set(filePaths.map(filePath => normalizePath(path.resolve(filePath))))];
+	if (hasFind && typeof replacement !== 'string') {
+		throw new TypeError('Expected `replacement` to be a string when `find` is provided');
+	}
 
-	find = find.map(element => {
-		const iFlag = ignoreCase ? 'i' : '';
+	// Resolve file paths
+	let filePaths;
+	if (glob) {
+		const patterns = filePathPatterns.map(p => normalizePath(p));
+		filePaths = await globby(patterns, {dot: true, absolute: true, expandDirectories: false});
+	} else {
+		filePaths = filePathPatterns.map(p => path.resolve(String(p)));
+	}
 
-		if (typeof element === 'string') {
-			return new RegExp(escapeStringRegexp(element), `g${iFlag}`);
-		}
+	// De-duplicate
+	filePaths = [...new Set(filePaths)];
 
-		return new RegExp(element.source, `${element.flags.replace('i', '')}${iFlag}`);
-	});
+	// Replace escape sequences in replacement if we have find patterns
+	if (hasFind && typeof replacement === 'string') {
+		replacement = replacement
+			.replaceAll('\\n', '\n')
+			.replaceAll('\\r', '\r')
+			.replaceAll('\\t', '\t');
+	}
+
+	// Prepare replacers
+	const replacers = hasFind
+		? toArray(find).map(pattern => {
+			if (typeof pattern === 'string') {
+				const flags = ignoreCase ? 'gi' : 'g';
+				return new RegExp(escapeStringRegexp(pattern), flags);
+			}
+
+			return normalizeRegex(pattern, ignoreCase);
+		})
+		: [];
 
 	const changes = [];
 
 	await Promise.all(filePaths.map(async filePath => {
-		const string = await fsPromises.readFile(filePath, 'utf8');
+		const originalContent = await fs.readFile(filePath, 'utf8');
+
+		let nextContent = originalContent;
 
-		let newString = string;
-		for (const pattern of find) {
-			newString = newString.replace(pattern, replacement);
+		for (const rx of replacers) {
+			nextContent = nextContent.replace(rx, replacement);
 		}
 
-		if (newString === string) {
+		if (hasTransform) {
+			nextContent = transform(nextContent, filePath);
+			if (typeof nextContent !== 'string') {
+				throw new TypeError('`transform` must return a string');
+			}
+		}
+
+		if (nextContent === originalContent) {
 			return;
 		}
 
 		if (dryRun) {
-			changes.push({
-				filePath,
-				originalContent: string,
-				newContent: newString,
-			});
-		} else {
-			await writeFileAtomic(filePath, newString);
+			changes.push({filePath, originalContent, newContent: nextContent});
+			return;
 		}
+
+		await writeFileAtomic(filePath, nextContent);
 	}));
 
 	if (dryRun) {
diff --git a/cli.js b/cli.js
@@ -11,7 +11,7 @@ const cli = meow(`
 	Options
 	  --regex           Regex pattern to find  (Can be set multiple times)
 	  --string          String to find  (Can be set multiple times)
-	  --replacement     Replacement string  (Required)
+	  --replacement     Replacement string  (Required when using --regex/--string)
 	  --ignore-case     Search case-insensitively
 	  --no-glob         Disable globbing
 	  --dry-run         Show what would be replaced without making changes
@@ -39,7 +39,6 @@ const cli = meow(`
 		},
 		replacement: {
 			type: 'string',
-			isRequired: true,
 		},
 		ignoreCase: {
 			type: 'boolean',
@@ -61,11 +60,31 @@ if (cli.input.length === 0) {
 	process.exit(1);
 }
 
-if (!cli.flags.regex && !cli.flags.string) {
+const toArray = v => v === undefined ? [] : (Array.isArray(v) ? v : [v]);
+
+const findPatterns = [
+	...toArray(cli.flags.string),
+	...toArray(cli.flags.regex).map(rx => new RegExp(rx, 'g')),
+];
+
+if (findPatterns.length === 0) {
 	console.error('Specify at least `--regex` or `--string`');
 	process.exit(1);
 }
 
+if (findPatterns.length > 0 && typeof cli.flags.replacement !== 'string') {
+	console.error('The `--replacement` option is required when using `--string` or `--regex`');
+	process.exit(1);
+}
+
+const result = await replaceInFiles(cli.input, {
+	find: findPatterns,
+	replacement: cli.flags.replacement,
+	ignoreCase: cli.flags.ignoreCase,
+	glob: cli.flags.glob,
+	dryRun: cli.flags.dryRun,
+});
+
 function displayDryRunResults(changes) {
 	if (changes.length === 0) {
 		console.log('No matches found.');
@@ -113,17 +132,6 @@ function highlightDifferences(text, otherText, color) {
 	return text.slice(0, start) + styleText(color, text.slice(start, end)) + text.slice(end);
 }
 
-const result = await replaceInFiles(cli.input, {
-	find: [
-		...cli.flags.string,
-		...cli.flags.regex.map(regexString => new RegExp(regexString, 'g')),
-	],
-	replacement: cli.flags.replacement,
-	ignoreCase: cli.flags.ignoreCase,
-	glob: cli.flags.glob,
-	dryRun: cli.flags.dryRun,
-});
-
 if (cli.flags.dryRun) {
 	displayDryRunResults(result);
 }
diff --git a/readme.md b/readme.md
@@ -39,3 +39,36 @@ $ replace-in-files --help
 Real-world use-case: [Bumping version number in a file when publishing to npm](https://github.com/sindresorhus/modern-normalize/commit/c1d65e3f7daba2b695ccf837d2aef19d586d1ca6)
 
 The regex should be [JavaScript flavor](https://www.regular-expressions.info/javascript.html).
+
+## Programmatic API
+
+You can also use this package programmatically:
+
+```js
+import replaceInFiles from 'replace-in-files-cli';
+
+// Find and replace
+await replaceInFiles('*.js', {
+	find: ['old', /version \d+/],
+	replacement: 'new'
+});
+
+// Transform entire file content
+await replaceInFiles('*.js', {
+	transform: (content, filePath) => `/* Banner */\n${content}`
+});
+
+// Combine find/replace with transform (transform runs after find/replace)
+await replaceInFiles('*.js', {
+	find: ['old'],
+	replacement: 'new', 
+	transform: (content, filePath) => `/* ${filePath} */\n${content}`
+});
+```
+
+### Transform Option
+
+The `transform` option provides full control over file content:
+- **Standalone**: Use alone for prepend, append, or complex transformations
+- **Combined**: Use with `find`/`replacement` - transform runs after find/replace operations
+- **Parameters**: Receives `(content, filePath)` for context-aware transformations
diff --git a/test.js b/test.js
