webext-patterns
TypeScript icon, indicating that this package has built-in type declarations

1.4.0 • Public • Published

webext-patterns

Tool to convert the patterns of your WebExtension manifest to regex

This might be incomplete. Please help me test it by adding more pattern and URLs to the tests.

Install

You can download the standalone bundle and include it in your manifest.json.

Or use npm:

npm install webext-patterns
// This module is only offered as a ES Module
import {
	patternToRegex,
	globToRegex,
	excludeDuplicatePatterns
	doesUrlMatchPatterns,
	assertValidPattern,
	isValidPattern,
} from 'webext-patterns';

Usage

patternToRegex('http://*/*');
// Returns /^http:[/][/][^/]+[/].+$/

globToRegex('*.example.com');
// Returns /\.example\.com$/

excludeDuplicatePatterns(['https://*.google.com/*', 'https://google.com/*']);
// Returns ['https://*.google.com/*']

assertValidPattern('https://google.*/*');
// Throws an error because the pattern is invalid

isValidPattern('https://*.google.com/*');
// Returns true

Note Firefox and Chrome handle patterns very slighly differently. webext-patterns defaults to Chrome’s logic, but if it detects a Firefox userAgent it will produce a Firefox-compatible regex.

API

patternToRegex(pattern1, pattern2, etc)

Accepts any number of string arguments and returns a single regex to match all of them.

Match patterns are used in the manifest’s permissions and content scripts’ matches and exclude_matches array.

patternToRegex('http://*/*');
// Returns /^http:[/][/][^/]+[/].+$/

const gmailRegex = patternToRegex('*://mail.google.com/*');
gmailRegex.test('https://mail.google.com/a/b/c'); // -> true
gmailRegex.test('https://photos.google.com/a/b/c'); // -> false

// Also accepts multiple patterns and returns a single regex
const googleRegex = patternToRegex(
	'https://google.com/*',
	'https://google.it/*'
);
googleRegex.test('https://google.it/search'); // -> true
googleRegex.test('https://google.de/search'); // -> false

globToRegex(pattern1, pattern2, etc)

Accepts any number of string arguments and returns a single regex to match all of them.

Globs are used in the manifest’s content scripts’ include_globs and exclude_globs arrays.

globToRegex('*.example.co?');
// Returns /\.example\.co.?$/ in Firefox
// Returns /\.example\.co.$/ everywhere else

const gmailRegex = globToRegex('*://mai?.google.com/*');
gmailRegex.test('https://mail.google.com/a/b/c'); // -> true
gmailRegex.test('https://photos.google.com/a/b/c'); // -> false

// Also accepts multiple globs and returns a single regex
const googleRegex = globToRegex(
	'*google.com*',
	'*google.it*'
);
googleRegex.test('https://google.it/search'); // -> true
googleRegex.test('https://google.de/search'); // -> false

excludeDuplicatePatterns([pattern1, pattern2, etc])

Accepts an array of patterns and returns a filtered array without the patterns that are already covered by others. For example "https://*/*" already covers all "https" URLs, so having "https://google.com/*" in the array won't make any difference and therefore it's dropped.

excludeDuplicatePatterns([
	"https://*/*",
	"https://google.com/*",
	"https://*.example.com/*",
]);
// Returns ["https://*/*"]

doesUrlMatchPatterns(url, ...patterns)

Accepts a URL and any number of patterns and returns true if the URL matches any of the patterns. This is a convenience method that wraps patternToRegex for single use. If you plan on testing multiple URLs to the same pattern, it's better to convert the patterns to a regex once and reuse that.

doesUrlMatchPatterns('https://google.com/', ['https://*.google.com/*', '*://example.com/*']);
// Returns true

assertValidPattern(pattern)

Accepts a pattern and throws an error if it's invalid.

assertValidPattern('https://google.*/*');
// Throws an error because the pattern is invalid

isValidPattern(pattern)

Accepts a pattern and returns true if it's valid.

isValidPattern('https://google.*/*');
// Returns false

Related

Permissions

Others

License

MIT © Federico Brigante

Package Sidebar

Install

npm i webext-patterns

Weekly Downloads

1,405

Version

1.4.0

License

MIT

Unpacked Size

13.4 kB

Total Files

5

Last publish

Collaborators

  • fregante