braces

Bash-like brace expansion, implemented in JavaScript. Safer than other brace expansion libs, with complete support for the Bash 4.3 braces specification, without sacrificing speed.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

Install

Install with npm:

$ npm install --save braces

v3.0.0 Released!!

See the changelog for details.

Why use braces?

Brace patterns make globs more powerful by adding the ability to match specific ranges and sequences of characters.

• Accurate - complete support for the Bash 4.3 Brace Expansion specification (passes all of the Bash braces tests)
• fast and performant - Starts fast, runs fast and scales well as patterns increase in complexity.
• Organized code base - The parser and compiler are easy to maintain and update when edge cases crop up.
• Well-tested - Thousands of test assertions, and passes all of the Bash, minimatch, and brace-expansion unit tests (as of the date this was written).
• Safer - You shouldn't have to worry about users defining aggressive or malicious brace patterns that can break your application. Braces takes measures to prevent malicious regex that can be used for DDoS attacks (see catastrophic backtracking).
• Supports lists - (aka "sets") a/{b,c}/d => ['a/b/d', 'a/c/d']
• Supports sequences - (aka "ranges") {01..03} => ['01', '02', '03']
• Supports steps - (aka "increments") {2..10..2} => ['2', '4', '6', '8', '10']
• Supports escaping - To prevent evaluation of special characters.

Usage

The main export is a function that takes one or more brace patterns and options.

const braces = require('braces');
// braces(patterns[, options]);

console.log(braces(['{01..05}', '{a..e}']));
//=> ['(0[1-5])', '([a-e])']

console.log(braces(['{01..05}', '{a..e}'], { expand: true }));
//=> ['01', '02', '03', '04', '05', 'a', 'b', 'c', 'd', 'e']

Brace Expansion vs. Compilation

By default, brace patterns are compiled into strings that are optimized for creating regular expressions and matching.

Compiled

console.log(braces('a/{x,y,z}/b'));
//=> ['a/(x|y|z)/b']
console.log(braces(['a/{01..20}/b', 'a/{1..5}/b']));
//=> [ 'a/(0[1-9]|1[0-9]|20)/b', 'a/([1-5])/b' ]

Expanded

Enable brace expansion by setting the expand option to true, or by using braces.expand() (returns an array similar to what you'd expect from Bash, or echo {1..5}, or minimatch):

console.log(braces('a/{x,y,z}/b', { expand: true }));
//=> ['a/x/b', 'a/y/b', 'a/z/b']

console.log(braces.expand('{01..10}'));
//=> ['01','02','03','04','05','06','07','08','09','10']

Lists

Expand lists (like Bash "sets"):

console.log(braces('a/{foo,bar,baz}/*.js'));
//=> ['a/(foo|bar|baz)/*.js']

console.log(braces.expand('a/{foo,bar,baz}/*.js'));
//=> ['a/foo/*.js', 'a/bar/*.js', 'a/baz/*.js']

Sequences

Expand ranges of characters (like Bash "sequences"):

console.log(braces.expand('{1..3}')); // ['1', '2', '3']
console.log(braces.expand('a/{1..3}/b')); // ['a/1/b', 'a/2/b', 'a/3/b']
console.log(braces('{a..c}', { expand: true })); // ['a', 'b', 'c']
console.log(braces('foo/{a..c}', { expand: true })); // ['foo/a', 'foo/b', 'foo/c']

// supports zero-padded ranges
console.log(braces('a/{01..03}/b')); //=> ['a/(0[1-3])/b']
console.log(braces('a/{001..300}/b')); //=> ['a/(0{2}[1-9]|0[1-9][0-9]|[12][0-9]{2}|300)/b']

See fill-range for all available range-expansion options.

Steppped ranges

Steps, or increments, may be used with ranges:

console.log(braces.expand('{2..10..2}'));
//=> ['2', '4', '6', '8', '10']

console.log(braces('{2..10..2}'));
//=> ['(2|4|6|8|10)']

When the .optimize method is used, or options.optimize is set to true, sequences are passed to to-regex-range for expansion.

Nesting

Brace patterns may be nested. The results of each expanded string are not sorted, and left to right order is preserved.

"Expanded" braces

console.log(braces.expand('a{b,c,/{x,y}}/e'));
//=> ['ab/e', 'ac/e', 'a/x/e', 'a/y/e']

console.log(braces.expand('a/{x,{1..5},y}/c'));
//=> ['a/x/c', 'a/1/c', 'a/2/c', 'a/3/c', 'a/4/c', 'a/5/c', 'a/y/c']

"Optimized" braces

console.log(braces('a{b,c,/{x,y}}/e'));
//=> ['a(b|c|/(x|y))/e']

console.log(braces('a/{x,{1..5},y}/c'));
//=> ['a/(x|([1-5])|y)/c']

Escaping

Escaping braces

A brace pattern will not be expanded or evaluted if either the opening or closing brace is escaped:

console.log(braces.expand('a\\{d,c,b}e'));
//=> ['a{d,c,b}e']

console.log(braces.expand('a{d,c,b\\}e'));
//=> ['a{d,c,b}e']

Escaping commas

Commas inside braces may also be escaped:

console.log(braces.expand('a{b\\,c}d'));
//=> ['a{b,c}d']

console.log(braces.expand('a{d\\,c,b}e'));
//=> ['ad,ce', 'abe']

Single items

Following bash conventions, a brace pattern is also not expanded when it contains a single character:

console.log(braces.expand('a{b}c'));
//=> ['a{b}c']

Options

options.maxLength

Type: Number

Default: 10,000

Description: Limit the length of the input string. Useful when the input string is generated or your application allows users to pass a string, et cetera.

console.log(braces('a/{b,c}/d', { maxLength: 3 })); //=> throws an error

options.expand

Type: Boolean

Default: undefined

Description: Generate an "expanded" brace pattern (alternatively you can use the braces.expand() method, which does the same thing).

console.log(braces('a/{b,c}/d', { expand: true }));
//=> [ 'a/b/d', 'a/c/d' ]

options.nodupes

Type: Boolean

Default: undefined

Description: Remove duplicates from the returned array.

options.rangeLimit

Type: Number

Default: 1000

Description: To prevent malicious patterns from being passed by users, an error is thrown when braces.expand() is used or options.expand is true and the generated range will exceed the rangeLimit.

You can customize options.rangeLimit or set it to Inifinity to disable this altogether.

Examples

// pattern exceeds the "rangeLimit", so it's optimized automatically
console.log(braces.expand('{1..1000}'));
//=> ['([1-9]|[1-9][0-9]{1,2}|1000)']

// pattern does not exceed "rangeLimit", so it's NOT optimized
console.log(braces.expand('{1..100}'));
//=> ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15', '16', '17', '18', '19', '20', '21', '22', '23', '24', '25', '26', '27', '28', '29', '30', '31', '32', '33', '34', '35', '36', '37', '38', '39', '40', '41', '42', '43', '44', '45', '46', '47', '48', '49', '50', '51', '52', '53', '54', '55', '56', '57', '58', '59', '60', '61', '62', '63', '64', '65', '66', '67', '68', '69', '70', '71', '72', '73', '74', '75', '76', '77', '78', '79', '80', '81', '82', '83', '84', '85', '86', '87', '88', '89', '90', '91', '92', '93', '94', '95', '96', '97', '98', '99', '100']

options.transform

Type: Function

Default: undefined

Description: Customize range expansion.

Example: Transforming non-numeric values

const alpha = braces.expand('x/{a..e}/y', {
  transform(value, index) {
    // When non-numeric values are passed, "value" is a character code.
    return 'foo/' + String.fromCharCode(value) + '-' + index;
  },
});
console.log(alpha);
//=> [ 'x/foo/a-0/y', 'x/foo/b-1/y', 'x/foo/c-2/y', 'x/foo/d-3/y', 'x/foo/e-4/y' ]

Example: Transforming numeric values

const numeric = braces.expand('{1..5}', {
  transform(value) {
    // when numeric values are passed, "value" is a number
    return 'foo/' + value * 2;
  },
});
console.log(numeric);
//=> [ 'foo/2', 'foo/4', 'foo/6', 'foo/8', 'foo/10' ]

options.quantifiers

Type: Boolean

Default: undefined

Description: In regular expressions, quanitifiers can be used to specify how many times a token can be repeated. For example, a{1,3} will match the letter a one to three times.

Unfortunately, regex quantifiers happen to share the same syntax as Bash lists

The quantifiers option tells braces to detect when regex quantifiers are defined in the given pattern, and not to try to expand them as lists.

Examples

const braces = require('braces');
console.log(braces('a/b{1,3}/{x,y,z}'));
//=> [ 'a/b(1|3)/(x|y|z)' ]
console.log(braces('a/b{1,3}/{x,y,z}', { quantifiers: true }));
//=> [ 'a/b{1,3}/(x|y|z)' ]
console.log(braces('a/b{1,3}/{x,y,z}', { quantifiers: true, expand: true }));
//=> [ 'a/b{1,3}/x', 'a/b{1,3}/y', 'a/b{1,3}/z' ]

options.keepEscaping

Type: Boolean

Default: undefined

Description: Do not strip backslashes that were used for escaping from the result.

What is "brace expansion"?

Brace expansion is a type of param