@isaacs/balanced-match 4.0.1

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 pkg:npm/%40isaacs/balanced-match@4.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40isaacs/balanced-match@4.0.1

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:447f96b48e26161d05ef3c9b7f82339564dfc4b6ff48f73a4ceb34eb3d22683b","contract":["balanced extracts the first matching pair of balanced delimiters and returns start, end, pre, body, and post substrings","balanced matches balanced nested delimiter pairs by identifying the outermost balanced match","balanced matches the first closed delimiter pair when multiple sequential delimiter pairs are present","balanced supports RegExp delimiters for matching dynamic and formatted delimiters","range returns character index bounds of the first balanced delimiter match","balanced returns undefined when delimiters do not match or remain unclosed"],"goal":"verify pkg:npm/%40isaacs/balanced-match@4.0.1","kind":"HOW","packages":["pkg:npm/%40isaacs/balanced-match@4.0.1"],"schemaVersion":1},"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/balanced-match@4.0.1"],"schemaVersion":1,"verifierAdapter":"node-typescript@1"}

import { balanced, range } from '@isaacs/balanced-match';

/**
 * Extract the first balanced pair of delimiters from a string.
 *
 * @param {string | RegExp} open - Opening delimiter pattern
 * @param {string | RegExp} close - Closing delimiter pattern
 * @param {string} str - Source string to search
 * @returns {object | false | undefined} Matched substring details or undefined
 */
export function extractBalanced(open, close, str) {
  return balanced(open, close, str);
}

/**
 * Get index bounds of the first balanced delimiter pair.
 *
 * @param {string} open - Opening delimiter
 * @param {string} close - Closing delimiter
 * @param {string} str - Source string to search
 * @returns {[number, number] | undefined} Start and end indices
 */
export function extractRange(open, close, str) {
  return range(open, close, str);
}

{
  "name": "sample-balanced-match",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-balanced-match",
      "version": "1.0.0",
      "dependencies": {
        "@isaacs/balanced-match": "4.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"
      }
    }
  }
}

{
  "name": "sample-balanced-match",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "@isaacs/balanced-match": "4.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40isaacs/balanced-match@4.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40isaacs/balanced-match@4.0.1"
  ]
}

import assert from 'node:assert/strict';
import { balanced, range } from '@isaacs/balanced-match';
import { extractBalanced, extractRange } from '../index.mjs';

// 1. Basic balanced matching
{
  const result = balanced('{', '}', 'hello {world} test');
  assert.deepEqual(result, {
    start: 6,
    end: 12,
    pre: 'hello ',
    body: 'world',
    post: ' test',
  });
  assert.deepEqual(extractBalanced('{', '}', 'hello {world} test'), result);
}

// 2. Nested delimiters
{
  const result = balanced('{', '}', 'pre{in{nested}value}post');
  assert.deepEqual(result, {
    start: 3,
    end: 19,
    pre: 'pre',
    body: 'in{nested}value',
    post: 'post',
  });
  assert.deepEqual(extractBalanced('{', '}', 'pre{in{nested}value}post'), result);
}

// 3. Multiple sequential pairs
{
  const result = balanced('{', '}', 'pre{first}mid{second}post');
  assert.deepEqual(result, {
    start: 3,
    end: 9,
    pre: 'pre',
    body: 'first',
    post: 'mid{second}post',
  });
  assert.deepEqual(extractBalanced('{', '}', 'pre{first}mid{second}post'), result);
}

// 4. RegExp delimiters
{
  const result = balanced(/<\w+>/, /<\/\w+>/, 'before<b>bold text</b>after');
  assert.deepEqual(result, {
    start: 6,
    end: 18,
    pre: 'before',
    body: 'bold text',
    post: 'after',
  });
  assert.deepEqual(extractBalanced(/<\w+>/, /<\/\w+>/, 'before<b>bold text</b>after'), result);
}

// 5. range helper function
{
  const indices = range('{', '}', 'before {target} after');
  assert.deepEqual(indices, [7, 14]);
  assert.deepEqual(extractRange('{', '}', 'before {target} after'), [7, 14]);
}

// 6. No match returns undefined
{
  const noMatch = balanced('{', '}', 'no braces here');
  assert.equal(noMatch, undefined);
  assert.equal(extractBalanced('{', '}', 'no braces here'), undefined);

  const unmatched = balanced('{', '}', 'unclosed {brace');
  assert.equal(unmatched, undefined);
  assert.equal(extractBalanced('{', '}', 'unclosed {brace'), undefined);
}

console.log('Contract passed');