webext-patterns

Utilities for patterns and globs for WebExtensions

Install

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

Or use npm:

npm install webext-patterns

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

findMatchingPatterns(url, ...patterns)

Accepts a URL and any number of patterns and returns an array of the patterns that match the URL. It returns an empty array if none of the patterns match the URL.

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

• webext-permissions - Get any optional permissions that users have granted you.
• webext-options-sync - Helps you manage and autosave your extension's options.
• webext-storage-cache - Map-like promised cache storage with expiration.
• webext-detect-page - Detects where the current browser extension code is being run.
• Awesome-WebExtensions - A curated list of awesome resources for WebExtensions development.
• More…

License

MIT © Federico Brigante