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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parseRange
✓ import { parseRange } from 'header-range-parser';
✗ import parseRange from 'header-range-parser';
The `parseRange` function is the primary API for parsing range headers and is a named export, not a default export.
ERROR_UNSATISFIABLE_RESULT
✓ import { ERROR_UNSATISFIABLE_RESULT } from 'header-range-parser';
✗ import ERROR_UNSATISFIABLE_RESULT from 'header-range-parser';
All error constants (e.g., `ERROR_UNSATISFIABLE_RESULT`, `ERROR_STRING_IS_NOT_HEADER`) are named exports. CommonJS `require` syntax is also supported in CJS projects.
Ranges
✓ import type { Ranges, Result } from 'header-range-parser';
✗ import { Ranges, Result } from 'header-range-parser';
Dedicated TypeScript types like `Ranges` and `Result` are provided for type-safe usage. For optimal bundling and clarity in TypeScript, prefer `import type` when only importing type declarations.
This example demonstrates parsing various `Range` header formats, including valid, partial, unsatisfiable, and invalid inputs. It also shows how to use the `combine` option and handle different error outcomes returned by `parseRange`.
import { parseRange, ERROR_UNSATISFIABLE_RESULT, ERROR_STRING_IS_NOT_HEADER, ERROR_INVALID_ARGUMENT } from 'header-range-parser';
import type { Ranges } from 'header-range-parser';
// Simulate a total resource size and various range headers
const totalSize = 1000;
const rangeHeaderValid = 'bytes=0-499, 500-999';
const rangeHeaderPartial = 'bytes=500-'; // Request from 500 to end
const rangeHeaderUnsatisfiable = 'bytes=1500-2000'; // Ranges beyond totalSize
const rangeHeaderInvalid = 'bytes=abc-def'; // Malformed header
const rangeHeaderCombined = 'bytes=50-55,0-10,5-10,56-60'; // Overlapping/adjacent ranges
console.log('--- Parsing Valid Range Header ---');
const subRangesValid: Ranges | number = parseRange(totalSize, rangeHeaderValid);
if (Array.isArray(subRangesValid)) {
console.log(`Parsed type: ${subRangesValid.type}`);
subRangesValid.forEach((range, index) => {
console.log(` Range ${index}: start=${range.start}, end=${range.end}`);
});
} else {
console.error('Error parsing valid range:', subRangesValid);
}
console.log('\n--- Parsing Partial Range Header (500- end of file) ---');
const subRangesPartial: Ranges | number = parseRange(totalSize, rangeHeaderPartial);
if (Array.isArray(subRangesPartial)) {
console.log(`Parsed type: ${subRangesPartial.type}`);
subRangesPartial.forEach((range, index) => {
console.log(` Range ${index}: start=${range.start}, end=${range.end}`);
});
} else {
console.error('Error parsing partial range:', subRangesPartial);
}
console.log('\n--- Parsing Unsatisfiable Range Header ---');
let subRangesUnsatisfiable: Ranges | number = parseRange(totalSize, rangeHeaderUnsatisfiable);
if (subRangesUnsatisfiable === ERROR_UNSATISFIABLE_RESULT) {
console.log(`Result: Range is unsatisfiable (error code: ${subRangesUnsatisfiable})`);
} else if (Array.isArray(subRangesUnsatisfiable)) {
console.log(`Unexpected success for unsatisfiable range. Parsed type: ${subRangesUnsatisfiable.type}`);
}
console.log('\n--- Parsing Invalid Range Header (with throwError: false) ---');
// Using throwError: false to get error codes instead of throwing exceptions
const subRangesInvalid: Ranges | number = parseRange(totalSize, rangeHeaderInvalid, { throwError: false });
if (subRangesInvalid === ERROR_STRING_IS_NOT_HEADER || subRangesInvalid === ERROR_INVALID_ARGUMENT) {
console.log(`Result: Invalid header string (error code: ${subRangesInvalid})`);
} else if (Array.isArray(subRangesInvalid)) {
console.log(`Unexpected success for invalid range. Parsed type: ${subRangesInvalid.type}`);
}
console.log('\n--- Combining Overlapping and Adjacent Ranges ---');
const subRangesCombined: Ranges | number = parseRange(totalSize, rangeHeaderCombined, { combine: true });
if (Array.isArray(subRangesCombined)) {
console.log(`Parsed type: ${subRangesCombined.type}`);
subRangesCombined.forEach((range, index) => {
console.log(` Combined Range ${index}: start=${range.start}, end=${range.end}`);
});
} else {
console.error('Error combining ranges:', subRangesCombined);
}
Errors
Common errors & fixes
RangeError: Invalid range header: bytes=-100
The `throwError` option is implicitly or explicitly set to `true` (which is the default behavior), and an invalid or malformed `Range` header string was provided to `parseRange`.
fixTo prevent exceptions, set `throwError: false` in the options object passed to `parseRange`. This will make the function return numeric error codes or error objects instead of throwing. Alternatively, ensure the input `header` string is a valid HTTP `Range` header before parsing.
TypeError: Cannot read properties of undefined (reading 'type')
`parseRange` returned a negative number (e.g., `-1`, `-2`, `-3`) or an error object, indicating a parsing failure, but the subsequent code attempted to access properties (like `type`) as if a successful `Ranges` array was returned.
fixBefore accessing properties of the result, explicitly check if the return value of `parseRange` is an array of ranges (e.g., `if (Array.isArray(subRanges)) { ... }`) or one of the documented negative error codes. ERR_REQUIRE_ESM: require() of ES Module ... header-range-parser.js from ... not supported.
Attempting to use `require()` CommonJS syntax to import `header-range-parser` in an ECMAScript Module (ESM) project context.
fixIf your project is configured as an ESM module (e.g., `"type": "module"` in `package.json`), you must use ESM `import` statements: `import { parseRange } from 'header-range-parser';`. Audit
Dependencies
No dependency data recorded yet.