Registry / http-networking / range-parser

range-parser

JSON →
library1.2.1jsnpmunverified

range-parser is a foundational utility within the Node.js ecosystem, specifically designed for parsing the HTTP `Range` header field. This header is crucial for implementing partial content responses (HTTP 206 Partial Content), enabling clients to request specific byte ranges of a resource, which is essential for video streaming, resumable downloads, and efficient data retrieval. Currently at stable version 1.2.1, it provides a straightforward API to transform a `Range` header string into a structured array of byte range objects, each with `start` and `end` properties. A key characteristic is its error handling mechanism, which returns negative integer codes (e.g., -1 for unsatisfiable ranges, -2 for malformed headers) instead of throwing exceptions, requiring developers to explicitly check the return type. It offers a `combine` option to automatically merge overlapping or adjacent ranges for simplified processing. As part of the `jshttp` organization, the package is mature and highly stable, receiving updates primarily for maintenance and minor enhancements rather than frequent new feature releases, making it a reliable choice for server-side range parsing.

http-networkingweb-framework
npm install range-parser
github ↗package ↗
INSTALL
IMPORT
SIG · RANGE-PARSER
R
range-parser
http-networkingjavascriptv1.2.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

parseRange
✓ const parseRange = require('range-parser');
✗ import { parseRange } from 'range-parser';
The package exports a single function as its default export. For CommonJS, `require()` directly returns the function.
parseRange
✓ import parseRange from 'range-parser';
✗ import { parseRange } from 'range-parser';
For ESM, the module is a default export. Named imports (`{ parseRange }`) will not work.
RangeParserTypes
✓ import type { Range, Ranges, Options } from 'range-parser';
✗ import { Range, Ranges, Options } from 'range-parser';
While the package itself is pure JavaScript, community-contributed TypeScript types (`@types/range-parser`) provide type definitions for `Range` objects, the `Ranges` array type, and `Options` interface. These should be imported as types.

This quickstart demonstrates how to use `range-parser` to parse HTTP `Range` headers, including basic valid range parsing, using the `combine` option, and handling common error conditions like unsatisfiable and malformed headers through its negative integer return values.

const parseRange = require('range-parser'); // Example 1: Basic parsing of a valid range const fileSize1 = 1000; const header1 = 'bytes=0-99,200-299'; const ranges1 = parseRange(fileSize1, header1); if (Array.isArray(ranges1)) { console.log(`Parsed ranges for header '${header1}':`, ranges1); console.log(`Type: ${ranges1.type}`); // Typically 'bytes' ranges1.forEach(r => console.log(` Start: ${r.start}, End: ${r.end}`)); } else { console.error(`Error parsing header '${header1}':`, ranges1 === -1 ? 'Unsatisfiable Range' : 'Malformed Header'); } // Example 2: Parsing with the 'combine' option to merge overlapping/adjacent ranges const fileSize2 = 100; const header2 = 'bytes=50-55,0-10,5-10,56-60'; const ranges2 = parseRange(fileSize2, header2, { combine: true }); if (Array.isArray(ranges2)) { console.log(`\nParsed (combined) ranges for header '${header2}':`, ranges2); ranges2.forEach(r => console.log(` Start: ${r.start}, End: ${r.end}`)); } else { console.error(`Error parsing header '${header2}' with combine:`, ranges2); } // Example 3: Handling an unsatisfiable range (requesting beyond file size) const fileSize3 = 50; const header3 = 'bytes=100-150'; const ranges3 = parseRange(fileSize3, header3); if (!Array.isArray(ranges3)) { console.error(`\nError for header '${header3}':`, ranges3 === -1 ? 'Unsatisfiable Range' : 'Malformed Header'); } // Example 4: Handling a malformed header string const fileSize4 = 100; const header4 = 'invalid-range-string'; const ranges4 = parseRange(fileSize4, header4); if (!Array.isArray(ranges4)) { console.error(`\nError for header '${header4}':`, ranges4 === -1 ? 'Unsatisfiable Range' : 'Malformed Header'); }
Debug
Known issues
gotchaThe `parseRange` function returns negative integers (-1 or -2) to signal parsing errors or unsatisfiable ranges, rather than throwing exceptions or returning an empty array. Developers must explicitly check if the return value is an array before attempting to access its properties or iterate over it.
fix
Always check `if (Array.isArray(result))` before processing the parsed ranges. If it's not an array, handle the negative integer error code appropriately (e.g., return HTTP 416 Range Not Satisfiable for -1).
affects: >=1.0.0
gotchaThe `combine` option, which merges overlapping and adjacent ranges, defaults to `false`. If your application logic requires consolidated ranges (e.g., to simplify handling or reduce the number of content parts), you must explicitly set this option to `true`.
fix
Pass `{ combine: true }` as the third argument to `parseRange(size, header, { combine: true })` if you intend to merge ranges.
affects: >=1.0.0
gotchaThe package does not ship with official TypeScript type definitions. While community types (`@types/range-parser`) are available, their accuracy and maintenance depend on external contributors. This can sometimes lead to minor inconsistencies with the latest package versions or unexpected type issues.
fix
Install `@types/range-parser` for TypeScript support (`npm install --save-dev @types/range-parser`). Be prepared to cast types or use `// @ts-ignore` for minor discrepancies if they arise, or contribute to the types definition.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'type')
Attempting to access `ranges.type` or `ranges.forEach` when `parseRange` returned a negative number (-1 or -2) indicating an error, meaning `ranges` is not an array.
fix
Wrap calls to access `ranges` properties or methods with a check: `if (Array.isArray(ranges)) { /* ... process ranges */ } else { /* ... handle error code */ }`.
TypeError: range.forEach is not a function
Similar to the above, this occurs when `parseRange` returns a negative number for an error, and the code attempts to call `forEach` directly on this number, which is not a function.
fix
Ensure the return value from `parseRange` is an array before calling array methods like `forEach`. For example: `if (Array.isArray(ranges)) { ranges.forEach(...) }`.
HTTP 416 Range Not Satisfiable
While not a JavaScript error, this HTTP status code often results from passing an 'unsatisfiable range' to `range-parser`, which then returns `-1`. If not handled, the server might send incorrect data or a generic error.
fix
If `parseRange` returns `-1`, your HTTP server implementation should respond with a `416 Range Not Satisfiable` status code and include a `Content-Range` header indicating the full size of the resource (e.g., `Content-Range: bytes */{fileSize}`).
Upgrade
Version history
1.2.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/jshttp/range-parser ↗
packagehttps://www.npmjs.com/package/range-parser ↗
range-parser — npm install range-parser · libregistry