Brace Expansion

Brace expansion as known from sh/bash shells, implemented in JavaScript. This library enables developers to expand brace patterns into arrays of strings, supporting comma-separated lists, numeric sequences, alphabetic sequences, and nested expansions with full compatibility with shell brace expansion behavior.

Package Information

• Package Name: brace-expansion
• Package Type: npm
• Language: JavaScript (ES modules)
• Installation: npm install brace-expansion

Core Imports

import expand from 'brace-expansion';

This package is ES module only and does not support CommonJS require().

Basic Usage

import expand from 'brace-expansion';

// Comma-separated lists
expand('file-{a,b,c}.jpg');
// => ['file-a.jpg', 'file-b.jpg', 'file-c.jpg']

// Empty options
expand('-v{,,}');
// => ['-v', '-v', '-v']

// Numeric sequences
expand('file{0..2}.jpg');
// => ['file0.jpg', 'file1.jpg', 'file2.jpg']

// Alphabetic sequences
expand('file-{a..c}.jpg');
// => ['file-a.jpg', 'file-b.jpg', 'file-c.jpg']

// Reverse sequences
expand('file{2..0}.jpg');
// => ['file2.jpg', 'file1.jpg', 'file0.jpg']

// Sequences with increments
expand('file{0..4..2}.jpg');
// => ['file0.jpg', 'file2.jpg', 'file4.jpg']

// Alphabetic sequences with increments
expand('file-{a..e..2}.jpg');
// => ['file-a.jpg', 'file-c.jpg', 'file-e.jpg']

// Zero-padded sequences
expand('file{00..10..5}.jpg');
// => ['file00.jpg', 'file05.jpg', 'file10.jpg']

// Nested expansions
expand('{{A..C},{a..c}}');
// => ['A', 'B', 'C', 'a', 'b', 'c']

// Complex nested patterns
expand('ppp{,config,oe{,conf}}');
// => ['ppp', 'pppconfig', 'pppoe', 'pppoeconf']

Capabilities

Brace Expansion Function

Expands brace patterns into arrays of all possible string combinations.

/**
 * Expand brace patterns into arrays of strings
 * @param {string} str - Input string containing brace patterns to expand
 * @returns {string[]} Array of all possible and valid expansions
 */
function expand(str)

Parameters:

• str (string): Input string containing brace patterns. Can include comma-separated lists ({a,b,c}), numeric sequences ({1..5}), alphabetic sequences ({a..e}), sequences with increments ({0..10..2}), and nested patterns.

Returns:

• string[]: Array of all possible and valid expansions. If no valid expansions are found, returns an array containing the original string [str]. Empty or null input returns an empty array [].

Supported Expansion Patterns:

1. Comma-separated lists: {a,b,c} expands to individual options

   • Example: {red,green,blue} → ['red', 'green', 'blue']
   • Supports empty options: {a,,c} → ['a', '', 'c']

2. Numeric sequences: {start..end} or {start..end..increment}

   • Example: {1..5} → ['1', '2', '3', '4', '5']
   • With increment: {0..10..2} → ['0', '2', '4', '6', '8', '10']
   • Supports negative numbers: {3..-2} → ['3', '2', '1', '0', '-1', '-2']
   • Reverse sequences: {5..1} → ['5', '4', '3', '2', '1']

3. Alphabetic sequences: {start..end} or {start..end..increment}

   • Example: {a..e} → ['a', 'b', 'c', 'd', 'e']
   • With increment: {a..z..2} → ['a', 'c', 'e', 'g', ...]
   • Case sensitive: {A..C} → ['A', 'B', 'C']

4. Zero-padded sequences: Leading zeros are preserved

   • Example: {01..05} → ['01', '02', '03', '04', '05']
   • Mixed padding: {007..010} → ['007', '008', '009', '010']

5. Nested expansions: Multiple levels of brace nesting supported

   • Example: {a,{b,c},d} → ['a', 'b', 'c', 'd']
   • Complex nesting: {{A..C},{a..c}} → ['A', 'B', 'C', 'a', 'b', 'c']

6. Combined patterns: Mixing text with multiple brace expansions

   • Example: file{1..2}.{jpg,png} → ['file1.jpg', 'file1.png', 'file2.jpg', 'file2.png']

Special Cases:

• Brace sets preceded by $ are not expanded for compatibility reasons (e.g., ${var}, prefix${a,b} → ['prefix${a,b}'])
• Escaped braces \\{ and \\} are treated as literal characters
• Invalid patterns return the original string wrapped in an array
• Empty braces {} at the start are escaped and preserved: {}file → ['{}file']

Error Handling:

• No exceptions are thrown
• Invalid brace patterns are treated as literal strings
• Malformed sequences return the original input wrapped in array
• Function always returns an array, never undefined or null

Usage Examples:

// URL generation
expand('http://server{1..3}.example.com/api/v{1,2}');
// => ['http://server1.example.com/api/v1', 'http://server1.example.com/api/v2', 
//     'http://server2.example.com/api/v1', 'http://server2.example.com/api/v2',
//     'http://server3.example.com/api/v1', 'http://server3.example.com/api/v2']

// File patterns
expand('backup-{2023..2025}-{jan,feb,mar}.{tar,zip}');
// Generates all combinations: backup-2023-jan.tar, backup-2023-jan.zip, etc.

// Command variations
expand('mkdir /usr/local/src/bash/{old,new,dist,bugs}');
// => ['mkdir /usr/local/src/bash/old', 'mkdir /usr/local/src/bash/new', 
//     'mkdir /usr/local/src/bash/dist', 'mkdir /usr/local/src/bash/bugs']

// Invalid patterns (return original)
expand('invalid{pattern');
// => ['invalid{pattern']

// Variable-like patterns (not expanded)
expand('${a,b}${c,d}');
// => ['${a,b}${c,d}']

expand('${1..3}');
// => ['${1..3}']

// Mixed patterns with variables
expand('{a,b}${c,d}${e,f}');
// => ['a${c,d}${e,f}', 'b${c,d}${e,f}']

expand('');
// => []