This package provides a TypeScript implementation of Bash-like brace expansion, allowing you to generate a set of strings based on a pattern with braces. It is a port of the popular NPM packages balanced-match and brace-expansion into platform-agnostic TypeScript.

This package is designed to work in any JavaScript environment, including Deno, Node, Bun, and Cloudflare Workers. It does not have any dependencies, making it lightweight and easy to use. It is particularly useful for generating file paths from glob patterns, and other string interpolations based on a pattern with braces.

deno add jsr:@nick/braces

bunx jsr add @nick/braces

pnpm dlx jsr add @nick/braces

yarn dlx jsr add @nick/braces

npx jsr add @nick/braces

import { braces } from "@nick/braces";

const files = braces("./**/*.{ts,tsx,js,jsx}");
console.log(files);
// [
//   "./**/*.ts",
//   "./**/*.tsx",
//   "./**/*.js",
//   "./**/*.jsx"
// ]

This package's primary export is the braces function, which accepts a string input and returns an array of the fully-expanded brace expressions.

import { braces } from "@nick/braces";

const files = braces("./**/*.{ts,tsx,js,jsx}");
console.log(files);
// [
//   "./**/*.ts",
//   "./**/*.tsx",
//   "./**/*.js",
//   "./**/*.jsx"
// ]

As long as the braces are balanced, this package can handle any level of nested expressions. Just like in Bash, the order of interpolation is left to right.

import { braces } from "@nick/braces";

const files = braces("./**/*.{{{,d.}ts,js}{,x},{m,c}{ts,js}}");
console.log(files);
// [
//   "./**/*.ts",
//   "./**/*.tsx",
//   "./**/*.d.ts",
//   "./**/*.d.tsx",
//   "./**/*.js",
//   "./**/*.jsx",
//   "./**/*.mts",
//   "./**/*.mjs",
//   "./**/*.cts",
//   "./**/*.cjs"
// ]

The braces function also supports the expansion of Bash-style numeric ranges, expressed in the form of n..m, where n and m are both integers.

{start..end}

• Both n and m must be positive or negative integers.
• Ranges are inclusive: both n and m will be in the result set.
• Returns an array of numeric strings (not parsed into JS numbers).

import { braces } from "@nick/braces";

const files = braces("./{1..10}.txt");
console.log(files);
// [
//   "./1.txt",
//   "./2.txt",
//   ...
//   "./10.txt"
// ]

You can also specify a custom step value for the optional third parameter, to control the increment between numbers.

{start..end..step}

• Step value must be a positive integer.
• Step value must be less than or equal to the difference between n and m, otherwise the result will be an empty array.

import { braces } from "@nick/braces";

const files = braces("./untitled-{1..10..2}.txt");
console.log(files);
// [
//   "./untitled-1.txt",
//   "./untitled-3.txt",
//   "./untitled-5.txt",
//   "./untitled-7.txt",
//   "./untitled-9.txt"
// ]

Similarly, you can use character ranges in the form of a..z, where a and z are characters. The range is inclusive, meaning that both a and z are included in the result set.

import { braces } from "@nick/braces";

const files = braces("./{a..e}.txt");
console.log(files);
// [
//   "./a.txt",
//   "./b.txt",
//   "./c.txt",
//   "./d.txt",
//   "./e.txt"
// ]

Similar to numeric ranges, character can also specify a step value using the syntax {start..end..step}. This will generate a sequence with a specified step size.

import { braces } from "@nick/braces";

const files = braces("./{1..10..2}.txt");
console.log(files);
// [
//   "./1.txt",
//   "./3.txt",
//   "./5.txt",
//   "./7.txt",
//   "./9.txt"
// ]

This package was ported into platform-agnostic TypeScript from the NPM packages balanced-match and brace-expansion. The original code was written by Julian Gruber and is licensed under the MIT License.