node-parse-numeric-range

parse-numeric-range is a tiny, dependency-free JavaScript utility that converts numeric range expressions typed by a human — strings like “1-10,20-30” or “5..8,12” — into a flat, expanded array of integers. It supports comma-separated lists, ascending and descending ranges, negative numbers, and several interchangeable range separators including the hyphen, double and triple dots, and Unicode ellipsis-style characters (‥, ⋯, …).

The library ships as a single ~35-line module with both a CommonJS (module.exports) and ESM (exports.default) export plus a bundled TypeScript declaration file, making it a drop-in dependency for any Node.js or browser project that needs to turn a user- or author-supplied range string into something a program can iterate over.

What You Get

• A single default-exported parse(expression: string): number[] function with zero runtime dependencies
• Support for comma-separated lists mixing plain numbers and ranges in one expression, e.g. "4,6,8-10,12"
• Ascending and descending range expansion determined automatically by which endpoint is larger, e.g. 5-1 expands to [5,4,3,2,1]
• Multiple accepted range separators: hyphen (-), double dot (..), triple dot (...), and the Unicode ‥, ⋯, … characters
• Bundled TypeScript type declarations (index.d.ts) so no separate @types package is needed

Common Use Cases

• Parsing a CLI flag such as --lines 10-20,45 into concrete line numbers to act on
• Turning a print-dialog-style page range like "1-3,7" into an array for pagination logic
• Resolving a markdown/MDX code-fence line-highlight annotation such as {4-8,12} into the exact lines to highlight
• Expanding user-entered ID or row-selection ranges in an admin UI (e.g. "100-120,150") into a list to bulk-act on

Under The Hood

Architecture The entire library is one exported function, parsePart, in index.js: it splits the input on commas, trims each token, and tests it first against a plain-integer regex and then against a range regex capturing a left bound, a separator, and a right bound, expanding matched ranges with a simple incrementing loop. There is no internal layering, no configuration surface, and no state beyond the accumulator array — the whole contract of the library is this one pure function, so “what breaks if the core abstraction changes” is simply whatever calls parse() directly.

Tech Stack Plain, dependency-free JavaScript targeting both CommonJS and ES module consumers via a dual module.exports/exports.default assignment, with a hand-written index.d.ts providing TypeScript types. There is no build step, bundler, or transpiler in the published package; development tooling is limited to mocha, chai, and the esm loader for running tests, wired into a legacy Travis CI config.

Code Quality The test suite in test/test.js is thorough for the library’s scope, covering plain numbers, ascending and descending ranges, all supported separators (including the Unicode variants), negative bounds, whitespace tolerance, and the empty-string case — roughly eighteen assertions via chai’s expect().to.eql(). There is no linter or formatter configuration in the repo, no type-checked source (types are declared separately from the implementation), and error handling is implicit: malformed input is silently ignored rather than raising, since only strings matching the two known regex shapes contribute to the output.

What Makes It Unique The library’s specific value is its handling of range-separator variety and directionality in one small surface: it treats -, .., ..., and three Unicode ellipsis-style characters as meaningfully different (inclusive vs. exclusive of the right endpoint) while also auto-detecting descending ranges without a separate flag. This is a narrow, already-well-trodden parsing problem — the approach is a straightforward regex-driven expansion rather than a novel algorithm, but it is a clean, dependency-free solution that several markdown/code-highlighting ecosystems have adopted as their canonical range parser.