@isaacs/brace-expansion 5.0.1: expand

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify @isaacs/brace-expansion.expand in pkg:npm/%40isaacs/brace-expansion@5.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40isaacs/brace-expansion@5.0.1
Demonstrate these symbols/APIs:
  - @isaacs/brace-expansion.expand

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:593fd5fb8caf6298f563949569318db71ec5ca01d4ef4438514638224683c793","contract":["expand expands comma-separated alternatives within curly braces into string combinations","expand generates sequential ranges for numeric and alphabetic patterns including step increments","expand resolves nested brace expressions and computes Cartesian products for adjacent brace groups","expand preserves escaped braces and handles literal strings without braces","expand returns an empty array for empty string input and enforces the max expansion limit option"],"goal":"verify @isaacs/brace-expansion.expand in pkg:npm/%40isaacs/brace-expansion@5.0.1","kind":"HOW","packages":["pkg:npm/%40isaacs/brace-expansion@5.0.1"],"schemaVersion":1,"symbols":["@isaacs/brace-expansion.expand"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40isaacs/brace-expansion@5.0.1"],"schemaVersion":1,"symbols":["@isaacs/brace-expansion.expand"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-brace-expansion-expand",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-brace-expansion-expand",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@isaacs/brace-expansion": "5.0.1"
      }
    },
    "node_modules/@isaacs/balanced-match": {
      "version": "4.0.1",
      "resolved": "https://registry.npmjs.org/@isaacs/balanced-match/-/balanced-match-4.0.1.tgz",
      "integrity": "sha512-yzMTt9lEb8Gv7zRioUilSglI0c0smZ9k5D65677DLWLtWJaXIS3CqcGyUFByYKlnUj6TkjLVs54fBl6+TiGQDQ==",
      "license": "MIT",
      "engines": {
        "node": "20 || >=22"
      }
    },
    "node_modules/@isaacs/brace-expansion": {
      "version": "5.0.1",
      "resolved": "https://registry.npmjs.org/@isaacs/brace-expansion/-/brace-expansion-5.0.1.tgz",
      "integrity": "sha512-WMz71T1JS624nWj2n2fnYAuPovhv7EUhk69R6i9dsVyzxt5eM3bjwvgk9L+APE1TRscGysAVMANkB0jh0LQZrQ==",
      "license": "MIT",
      "dependencies": {
        "@isaacs/balanced-match": "^4.0.1"
      },
      "engines": {
        "node": "20 || >=22"
      }
    }
  }
}

{
  "name": "sample-brace-expansion-expand",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of @isaacs/brace-expansion.expand",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "@isaacs/brace-expansion": "5.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @isaacs/brace-expansion.expand in pkg:npm/%40isaacs/brace-expansion@5.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40isaacs/brace-expansion@5.0.1"
  ],
  "symbols": [
    "@isaacs/brace-expansion.expand"
  ]
}

const { expand } = require('@isaacs/brace-expansion');

/**
 * Expand a brace pattern into an array of string combinations.
 *
 * @param {string} pattern - Brace pattern to expand
 * @param {object} [options] - Expansion options (e.g. max limit)
 * @returns {string[]} Array of expanded strings
 */
function expandPattern(pattern, options) {
  return expand(pattern, options);
}

/**
 * Expand multiple brace patterns and concatenate results into a single array.
 *
 * @param {string[]} patterns - Array of brace patterns
 * @param {object} [options] - Expansion options
 * @returns {string[]} Combined array of expanded strings
 */
function expandPatterns(patterns, options) {
  if (!Array.isArray(patterns)) {
    return [];
  }
  return patterns.flatMap((p) => expand(p, options));
}

module.exports = {
  expand,
  expandPattern,
  expandPatterns
};

import assert from 'node:assert';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  expand,
  expandPattern,
  expandPatterns
} = require('../src/index.js');

// 1. Verify export functions
assert.strictEqual(typeof expand, 'function', 'expand must be a function');
assert.strictEqual(typeof expandPattern, 'function', 'expandPattern helper must be a function');
assert.strictEqual(typeof expandPatterns, 'function', 'expandPatterns helper must be a function');

// 2. expand expands comma-separated alternatives within curly braces into string combinations
assert.deepStrictEqual(
  expand('item.{tar.gz,zip,rar}'),
  ['item.tar.gz', 'item.zip', 'item.rar'],
  'expand should expand comma-separated alternatives'
);
assert.deepStrictEqual(
  expandPattern('prefix_{a,b,c}_suffix'),
  ['prefix_a_suffix', 'prefix_b_suffix', 'prefix_c_suffix'],
  'expandPattern should expand comma-separated options'
);

// 3. expand generates sequential ranges for numeric and alphabetic patterns including step increments
assert.deepStrictEqual(
  expand('{1..4}'),
  ['1', '2', '3', '4'],
  'expand should expand ascending numeric range'
);
assert.deepStrictEqual(
  expand('{4..1}'),
  ['4', '3', '2', '1'],
  'expand should expand descending numeric range'
);
assert.deepStrictEqual(
  expand('{0..8..2}'),
  ['0', '2', '4', '6', '8'],
  'expand should expand stepped numeric range'
);
assert.deepStrictEqual(
  expand('{01..03}'),
  ['01', '02', '03'],
  'expand should expand zero-padded numeric range'
);
assert.deepStrictEqual(
  expand('{a..d}'),
  ['a', 'b', 'c', 'd'],
  'expand should expand ascending alphabetic range'
);
assert.deepStrictEqual(
  expand('{d..a}'),
  ['d', 'c', 'b', 'a'],
  'expand should expand descending alphabetic range'
);
assert.deepStrictEqual(
  expand('{a..e..2}'),
  ['a', 'c', 'e'],
  'expand should expand stepped alphabetic range'
);

// 4. expand resolves nested brace expressions and computes Cartesian products for adjacent brace groups
assert.deepStrictEqual(
  expand('a{b,c{1,2}}d'),
  ['abd', 'ac1d', 'ac2d'],
  'expand should resolve nested brace expressions'
);
assert.deepStrictEqual(
  expand('{a,b}{1,2}'),
  ['a1', 'a2', 'b1', 'b2'],
  'expand should compute Cartesian products of adjacent groups'
);
assert.deepStrictEqual(
  expandPatterns(['{x,y}', '{1,2}']),
  ['x', 'y', '1', '2'],
  'expandPatterns should flatMap expansions of multiple patterns'
);

// 5. expand preserves escaped braces and handles literal strings without braces
assert.deepStrictEqual(
  expand('a\\{b,c\\}d'),
  ['a{b,c}d'],
  'expand should preserve escaped braces'
);
assert.deepStrictEqual(
  expand('plain-string'),
  ['plain-string'],
  'expand should return literal string without braces in an array'
);

// 6. expand returns an empty array for empty string input and enforces the max expansion limit option
assert.deepStrictEqual(
  expand(''),
  [],
  'expand should return empty array for empty string'
);
assert.deepStrictEqual(
  expandPattern(''),
  [],
  'expandPattern should return empty array for empty string'
);
assert.deepStrictEqual(
  expand('{1..100}', { max: 4 }),
  ['1', '2', '3', '4'],
  'expand should respect max option'
);
assert.deepStrictEqual(
  expandPattern('{a,b,c,d,e}', { max: 2 }),
  ['a', 'b'],
  'expandPattern should respect max option'
);

console.log('Contract tests passed.');