range-parser

range-parser is a minimal Node.js utility, part of the jshttp collection, that parses the HTTP Range request header into a normalized list of byte ranges relative to a given resource size. It handles the standard bytes=start-end syntax, suffix ranges, multiple comma-separated ranges, and optional range combining, returning either the parsed ranges or a documented error code for unsatisfiable or malformed input.

Despite being only a few dozen lines, it is one of the most depended-upon packages in the Node ecosystem — used internally by Express, send, and countless static-file servers to implement partial content responses (HTTP 206), byte-serving, and resumable downloads.

What You Get

• A single function that parses Range headers into byte-range objects
• Support for suffix ranges and multiple comma-separated ranges
• Optional combining of overlapping/adjacent ranges via a combine option
• Clear numeric error codes for malformed (-2) and unsatisfiable (-1) ranges
• A dependency-free, battle-tested implementation used across the ecosystem

Common Use Cases

• Implementing HTTP 206 Partial Content responses in a file server
• Enabling resumable or chunked downloads of large assets
• Byte-serving video or audio for seeking in media players
• Validating and normalizing client Range headers before reading a file

Under The Hood

Architecture - The entire library is a single index.js exporting one function, rangeParser(size, str, options). It locates the ’=’ separator to read the range type, splits the remaining string on commas, parses each start/end pair (handling empty start as a suffix range and empty end as through-EOF), filters out invalid or out-of-bounds ranges, and optionally combines overlapping ranges when options.combine is set. Sentinel return values (-1 unsatisfiable, -2 malformed) signal error conditions without throwing.

Tech Stack - Pure JavaScript with zero runtime dependencies, targeting Node.js and distributed via npm. It uses standard string operations and Math utilities only, keeping the footprint tiny.

Code Quality - The code is small, defensive, and thoroughly commented, with a dedicated test/ suite covering suffix ranges, multiple ranges, combining, and error cases. As a jshttp project it follows the group’s conventions and is validated by CI and coverage tooling.

API Design - The API is deliberately minimal: one pure function with an options object for combining. Returning ranges-or-error-code rather than throwing keeps hot-path HTTP handling allocation-light, which is why higher-level frameworks build on it directly.