feat(pluginutils): add createHookFilter()

When trying to port a plugin that uses `createFilter()` to hook filters
it's hard keep the functionality 100% the same, as `createFilter()` does
various pre-processing, like normalising paths and, resolving relative
paths, exluding paths which contain \0, etc.

To make porting easier, provide a `createHookFilter()` which instead of
returning a function, returns a filter object that can be assigned
to "filter.id" or "filter.code", and behaves the same as if createFilter()
was used and the returned function used in a hook.

To make sure that the implementation of `createHookFilter()` matches
`createFilter()`, `createFilter()` now calls `createHookFilter()`
internally and uses the same object to create the test function.

Author: lazka

packages/pluginutils/README.md

@@ -139,6 +139,54 @@ export default function myPlugin(options = {}) {
 }
 ```
 
+### createHookFilter
+
+Constructs a StringFilter object which can be passed to Rollup for module filtering. Provides the same filtering behavior as `createFilter()` but returns a declarative filter object instead of a function. The content of the
+returned object is not guaranteed to be stable between versions.
+
+Parameters: `(include?: <picomatch>, exclude?: <picomatch>, options?: Object)`<br>
+Returns: `StringFilter`
+
+_Note: Please see the TypeScript definition for complete documentation of the return type_
+
+#### `include` and `exclude`
+
+Type: `String | RegExp | Array[...String|RegExp]`<br>
+
+A valid [`picomatch`](https://github.com/micromatch/picomatch#globbing-features) pattern, or array of patterns. If `options.include` is omitted or has zero length, filter will return `true` by default. Otherwise, an ID must match one or more of the `picomatch` patterns, and must not match any of the `options.exclude` patterns.
+
+Note that `picomatch` patterns are very similar to [`minimatch`](https://github.com/isaacs/minimatch#readme) patterns, and in most use cases, they are interchangeable. If you have more specific pattern matching needs, you can view [this comparison table](https://github.com/micromatch/picomatch#library-comparisons) to learn more about where the libraries differ.
+
+#### `options`
+
+##### `resolve`
+
+Type: `String | Boolean | 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. This can be useful if you want to create a filter for virtual module names.
+
+#### Usage
+
+```js
+import { createHookFilter } from '@rollup/pluginutils';
+
+export default function myPlugin(options = {}) {
+  return {
+    transform: {
+      filter: {
+        // assume that the myPlugin accepts options of `options.include` and `options.exclude`
+        id: createHookFilter(options.include, options.exclude, {
+          resolve: '/my/base/dir'
+        })
+      },
+      handler(code) {
+        // implement the transformation...
+      }
+    }
+  };
+}
+```
+
 ### dataToEsm
 
 Transforms objects into tree-shakable ES Module imports.

packages/pluginutils/src/createFilter.ts

@@ -2,7 +2,7 @@ import { resolve, posix, isAbsolute } from 'path';
 
 import pm from 'picomatch';
 
-import type { CreateFilter } from '../types';
+import type { CreateFilter, CreateHookFilter } from '../types';
 
 import ensureArray from './utils/ensureArray';
 import normalizePath from './normalizePath';
@@ -23,53 +23,67 @@ function getMatcherString(id: string, resolutionBase: string | false | null | un
   return posix.join(basePath, normalizePath(id));
 }
 
-const createFilter: CreateFilter = function createFilter(include?, exclude?, options?) {
+const createHookFilter: CreateHookFilter = function createHookFilter(include?, exclude?, options?) {
   const resolutionBase = options && options.resolve;
 
-  const getMatcher = (id: string | RegExp) =>
-    id instanceof RegExp
-      ? id
-      : {
-          test: (what: string) => {
-            // this refactor is a tad overly verbose but makes for easy debugging
-            const pattern = getMatcherString(id, resolutionBase);
-            const fn = pm(pattern, { dot: true });
-            const result = fn(what);
-
-            return result;
-          }
-        };
+  const getMatcher = (id: string | RegExp) => {
+    if (id instanceof RegExp) {
+      return new RegExp(id);
+    }
+    return getMatcherString(id, resolutionBase);
+  };
 
   const includeMatchers = ensureArray(include).map(getMatcher);
   const excludeMatchers = ensureArray(exclude).map(getMatcher);
 
-  if (!includeMatchers.length && !excludeMatchers.length)
-    return (id) => typeof id === 'string' && !id.includes('\0');
+  excludeMatchers.push(/\0/);
+
+  return {
+    include: includeMatchers,
+    exclude: excludeMatchers
+  };
+};
+
+const createFilter: CreateFilter = function createFilter(include?, exclude?, options?) {
+  const { include: includeFilters, exclude: excludeFilters } = createHookFilter(
+    include,
+    exclude,
+    options
+  ) as {
+    include: (string | RegExp)[];
+    exclude: (string | RegExp)[];
+  };
+
+  const getMatcher = (id: string | RegExp) => {
+    if (id instanceof RegExp) {
+      // Ensure the global flag is not set, so that state is not shared across
+      // test() calls
+      return new RegExp(id.source, id.flags.replace('g', ''));
+    }
+    const fn = pm(id, { dot: true });
+    return {
+      test: (what: string) => fn(what)
+    };
+  };
+
+  const includeMatchers = includeFilters.map((id) => getMatcher(id));
+  const excludeMatchers = excludeFilters.map((id) => getMatcher(id));
 
   return function result(id: string | unknown): boolean {
     if (typeof id !== 'string') return false;
-    if (id.includes('\0')) return false;
 
     const pathId = normalizePath(id);
 
     for (let i = 0; i < excludeMatchers.length; ++i) {
-      const matcher = excludeMatchers[i];
-      if (matcher instanceof RegExp) {
-        matcher.lastIndex = 0;
-      }
-      if (matcher.test(pathId)) return false;
+      if (excludeMatchers[i].test(pathId)) return false;
     }
 
     for (let i = 0; i < includeMatchers.length; ++i) {
-      const matcher = includeMatchers[i];
-      if (matcher instanceof RegExp) {
-        matcher.lastIndex = 0;
-      }
-      if (matcher.test(pathId)) return true;
+      if (includeMatchers[i].test(pathId)) return true;
     }
 
     return !includeMatchers.length;
   };
 };
 
-export { createFilter as default };
+export { createFilter, createHookFilter };

packages/pluginutils/src/index.ts

@@ -1,6 +1,6 @@
 import addExtension from './addExtension';
 import attachScopes from './attachScopes';
-import createFilter from './createFilter';
+import { createFilter, createHookFilter } from './createFilter';
 import dataToEsm from './dataToEsm';
 import extractAssignedNames from './extractAssignedNames';
 import makeLegalIdentifier from './makeLegalIdentifier';
@@ -11,6 +11,7 @@ export {
   addExtension,
   attachScopes,
   createFilter,
+  createHookFilter,
   dataToEsm,
   exactRegex,
   extractAssignedNames,
@@ -25,6 +26,7 @@ export default {
   addExtension,
   attachScopes,
   createFilter,
+  createHookFilter,
   dataToEsm,
   exactRegex,
   extractAssignedNames,

packages/pluginutils/test/createFilter.ts

@@ -2,7 +2,7 @@ import { resolve as rawResolve } from 'path';
 
 import test from 'ava';
 
-import { createFilter, normalizePath } from '../';
+import { createFilter, normalizePath, createHookFilter } from '../';
 
 const resolve = (...parts: string[]) => normalizePath(rawResolve(...parts));
 
@@ -199,3 +199,36 @@ test('pass a regular expression to the exclude parameter with g flag', (t) => {
   t.falsy(filter(resolve('zxcvbnmasdfg')));
   t.falsy(filter(resolve('zxcvbnmasdfg')));
 });
+
+interface StringFilterSubset {
+  include: (string | RegExp)[];
+  exclude: (string | RegExp)[];
+}
+
+test('createHookFilter always returns an object with include and exclude arrays', (t) => {
+  const filter = createHookFilter() as StringFilterSubset;
+  t.true(Array.isArray((filter as any).include));
+  t.is((filter as any).include.length, 0);
+  t.true(Array.isArray((filter as any).exclude));
+});
+
+test('createHookFilter populates include and exclude from provided patterns', (t) => {
+  const filter = createHookFilter(['*.js'], ['*.test.js'], {
+    resolve: false
+  }) as StringFilterSubset;
+  t.true(filter.include.some((pattern) => pattern === '*.js'));
+  t.true(filter.exclude.some((pattern) => pattern === '*.test.js'));
+});
+
+test('createHookFilter resolves patterns using resolve base path', (t) => {
+  const filter = createHookFilter(['*.js'], ['*.test.js'], {
+    resolve: '/basedir'
+  }) as StringFilterSubset;
+  t.true(filter.include.some((pattern) => pattern === '/basedir/*.js'));
+  t.true(filter.exclude.some((pattern) => pattern === '/basedir/*.test.js'));
+});
+
+test('createHookFilter passes through RegExp', (t) => {
+  const filter = createHookFilter([/zxcvbnmasdfg/]) as StringFilterSubset;
+  t.true(filter.include.some((pattern) => (pattern as RegExp).source === 'zxcvbnmasdfg'));
+});

packages/pluginutils/types/index.d.ts

@@ -56,6 +56,32 @@ export function createFilter(
   options?: { resolve?: string | false | null }
 ): (id: string | unknown) => boolean;
 
+export type StringFilter<Value = string | RegExp> =
+  | (Value | Value[])
+  | {
+      include?: Value | Value[];
+      exclude?: Value | Value[];
+    };
+
+/**
+ * Constructs a StringFilter object which can be passed to Rollup for module filtering.
+ * Provides the same filtering behavior as `createFilter()` but returns a declarative
+ * filter object instead of a function.
+ *
+ * @param include If omitted or empty, all modules are included by default.
+ * @param exclude ID must not match any of the `exclude` patterns.
+ * @param options Optionally resolves patterns against a directory other than `process.cwd()`.
+ * If a `string` is specified, it will be used as the base directory.
+ * Relative paths are resolved against `process.cwd()` first.
+ * If `false`, patterns will not be resolved (useful for virtual module names).
+ * @returns A StringFilter object compatible with Rollup's filter configuration.
+ */
+export function createHookFilter(
+  include?: FilterPattern,
+  exclude?: FilterPattern,
+  options?: { resolve?: string | false | null }
+): StringFilter;
+
 /**
  * Transforms objects into tree-shakable ES Module imports.
  * @param data An object to transform into an ES module.
@@ -102,6 +128,7 @@ export function suffixRegex(str: string | string[], flags?: string): RegExp;
 export type AddExtension = typeof addExtension;
 export type AttachScopes = typeof attachScopes;
 export type CreateFilter = typeof createFilter;
+export type CreateHookFilter = typeof createHookFilter;
 export type ExactRegex = typeof exactRegex;
 export type ExtractAssignedNames = typeof extractAssignedNames;
 export type MakeLegalIdentifier = typeof makeLegalIdentifier;
@@ -114,6 +141,7 @@ declare const defaultExport: {
   addExtension: AddExtension;
   attachScopes: AttachScopes;
   createFilter: CreateFilter;
+  createHookFilter: CreateHookFilter;
   dataToEsm: DataToEsm;
   exactRegex: ExactRegex;
   extractAssignedNames: ExtractAssignedNames;