feat: filtering paths is delegated to createFilter from @rollup/pluginutils

BREAKING CHANGE: the plugin itself is not responsible for filtering
paths

Author: recursive-beast

README.md

@@ -46,24 +46,49 @@ export default {
 ## API
 
 ```typescript
-function externalAssets(pattern: string | RegExp | (string | RegExp)[]);
+function externalAssets(
+	include?: string | RegExp | (string | RegExp)[],
+	exclude?: string | RegExp | (string | RegExp)[],
+	options?: { resolve?: string | false | null },
+);
 ```
 
-### pattern
+### include / exclude
 
 `string | RegExp | (string | RegExp)[]`
 
-A picomatch pattern, or array of patterns, which correspond to assets the plugin should operate on.
+A valid [picomatch][9] pattern, or array of patterns.
+If `include` is omitted or has zero length, all imports will be considered as assets.
+Otherwise, an import path must match one or more of the `include` patterns,
+and must not match any of the `exclude` patterns.
+
+**Note**: patterns that include windows paths are normalized to be valid picomatch patterns.
 
 ```javascript
+import path from "path";
+
 // Operate on images located in the ./assets directory.
 externalAssets("assets/**/*.jpg");
 
 // Operate on images located in the ./assets directory.
 // and all stylesheet files.
 externalAssets(["assets/**/*.{jpg,png}", /\.(css|scss)$/]);
+
+// Operate on all assets except text files.
+externalAssets("assets/**/*", "**/*.txt");
+
+// Operate on all assets except text files.
+// `__dirname` is the pattern's base dir instead of `process.cwd()`.
+externalAssets(path.resolve(__dirname, "assets/**/*"), "**/*.txt");
 ```
 
+### options
+
+- `resolve` `{string | false | null}`: Optionally resolves the patterns against a directory other than `process.cwd()`.
+If a `string` is specified, then the value will be used as the base directory.
+Relative paths will be resolved against `process.cwd()` first.
+If `false`, then the patterns will not be resolved against any directory.
+
 ## Contributing
 
 ### Prerequisites
@@ -127,3 +152,4 @@ Please follow the [conventional commits][5] specification, because [semantic-rel
 [6]: https://github.com/semantic-release/semantic-release
 [7]: https://github.com/concordancejs/concordance/issues/68
 [8]: https://jestjs.io/
+[9]: https://github.com/micromatch/picomatch#globbing-features

src/index.ts

@@ -8,15 +8,33 @@ import { getIdDeduplicator, getOutputId, getRelativeImportPath } from "./helpers
 const PLUGIN_NAME = "external-assets";
 const PREFIX = `\0${PLUGIN_NAME}:`;
 
+interface Options {
+	/**
+	 * Optionally resolves the patterns against a directory other than `process.cwd()`.
+	 * If a `string` is specified, then the value will be used as the base directory.
+	 * Relative paths will be resolved against `process.cwd()` first.
+	 * If `false`, then the patterns will not be resolved against any directory.
+	 */
+	resolve?: string | false | null;
+}
+
 /**
  * Make assets external but include them in the output.
- * @param pattern - A picomatch pattern, or array of patterns,
- * which correspond to assets the plugin should operate on.
+ * @param include A valid picomatch pattern, or array of patterns.
+ * If `include` is omitted or has zero length, all imports will be processed.
+ *
+ * **Note**: patterns that include windows paths are normalized to be valid picomatch patterns.
+ * @param exclude If an asset matches one of the `exclude` patterns, its import will not be processed.
+ *
+ * **Note**: patterns that include windows paths are normalized to be valid picomatch patterns.
+ * @param options The options object.
  */
-export default function externalAssets(pattern: FilterPattern): Plugin {
-	if (!pattern) throw new Error("please specify a pattern for targeted assets");
-
-	const idFilter = createFilter(pattern);
+export default function externalAssets(
+	include?: FilterPattern,
+	exclude?: FilterPattern,
+	options?: Options,
+): Plugin {
+	const idFilter = createFilter(include, exclude, options);
 	const deduplicateId = getIdDeduplicator();
 
 	return {
@@ -35,11 +53,7 @@ export default function externalAssets(pattern: FilterPattern): Plugin {
 		},
 
 		async load(id) {
-			if (
-				id.startsWith("\0") // Virtual module.
-				|| id.includes("?") // Id reserved by some other plugin.
-				|| !idFilter(id) // Filtered out id.
-			) return null;
+			if (!idFilter(id)) return null;
 
 			// For two or more assets with the same content, only one asset is going to be emitted.
 			// `this.emitFile` deduplicates in the same way.

tests/general.test.ts

@@ -1,8 +1 @@
-import externalAssets from "../src/index";
-
-test("pattern is required", () => {
-	// @ts-ignore
-	expect(() => externalAssets()).toThrow(Error);
-});
-
 test.todo("produces correct sourcemaps");