HTTP Range Header Parser

1.0.0 verified Thu Apr 23 auth: no javascript

The `http-range` package provides a Node.js-specific parser and creator for HTTP/1.1 `Content-Range` and `Range` header fields. It offers dedicated classes `ContentRange` and `Range` for handling these headers, allowing developers to parse incoming header strings into structured objects and construct valid header strings from component parts. Additionally, it exposes a `RangeSpec` class for granular control over individual range specifications. The package is currently at version 1.0.0, indicating a stable and mature API. Its primary focus is on strict adherence to RFC2616 specifications for range headers, differentiating it by offering distinct classes for both Content-Range and Range headers rather than a single generic utility function. Release cadence is not explicitly defined but the project appears to be stable with a specific and limited scope.

Common errors

error Error: Invalid arguments for [ClassName] constructor ↓

cause Attempting to create an instance of `ContentRange`, `Range`, or `RangeSpec` with malformed or missing required arguments, such as passing a non-numeric value for `length` in `ContentRange`.

fix

Ensure all arguments passed to ContentRange, Range, or RangeSpec constructors conform to their expected types and formats (e.g., length must be a number or '*'). Consult the API documentation for each class's constructor signature.

error Error: Invalid [HeaderType] string ↓

cause The input string provided to the `parse()` method (e.g., `new ContentRange().parse(input)`) does not conform to the HTTP/1.1 `Content-Range` or `Range` header specification.

fix

Validate the input string against RFC2616 for Content-Range (e.g., bytes 0-49/50) or Range (e.g., bytes=0-49,100-199) before attempting to parse, or wrap the parse call in a try...catch block to handle parsing errors.

Warnings

gotcha Invalid input to `ContentRange`, `Range`, or `RangeSpec` constructors or `parse` methods will throw synchronous errors. The library does not return null or a Promise for errors; it directly throws exceptions. ↓

fix Wrap calls to constructors and `parse` methods (e.g., `new ContentRange().parse(input)`) in `try...catch` blocks to handle malformed header strings or invalid arguments gracefully.

Install

npm install http-range

yarn add http-range

pnpm add http-range

Imports

ContentRange
wrong
```
const ContentRange = require('http-range');
```
correct
```
import { ContentRange } from 'http-range';
```
The package primarily uses CommonJS `require()` syntax as shown in its README. For modern Node.js applications using ES modules, named imports are the correct approach. The `ContentRange` class is exported as a named property of the module.
Range
wrong
```
const Range = require('http-range');
```
correct
```
import { Range } from 'http-range';
```
Similar to `ContentRange`, the `Range` class is a named export. Ensure to use named imports when working with ES modules.
RangeSpec
wrong
```
import RangeSpec from 'http-range';
```
correct
```
import { RangeSpec } from 'http-range';
```
The `RangeSpec` class, which represents individual byte range specifications, is also exported as a named member of the module.

Quickstart

Demonstrates parsing and creating HTTP `Content-Range` and `Range` headers using the `ContentRange` and `Range` classes, including handling multiple range specifications and direct `RangeSpec` usage.

const { ContentRange, Range } = require('http-range');

// Example 1: Parsing and creating 'Content-Range' header
const contentRangeInput = 'bytes 0-49/50';
const parsedContentRange = new ContentRange().parse(contentRangeInput);
console.log(`Parsed Content-Range: ${JSON.stringify(parsedContentRange.range)} / ${parsedContentRange.length}`);
const newContentRange = new ContentRange('bytes', '0-49', 50);
console.log(`Created Content-Range: ${newContentRange.toString()}`);

// Example 2: Parsing and creating 'Range' header with multiple specs
const rangeInput = 'bytes=0-49,50-99,-30';
const parsedRange = new Range().parse(rangeInput);
console.log(`\nParsed Range (unit): ${parsedRange.unit}`);
parsedRange.ranges.forEach((r, i) => console.log(` - Range Spec ${i + 1}: low=${r.low ?? 'undefined'}, high=${r.high ?? 'undefined'}`));
const newRange = new Range('bytes', '0-49');
console.log(`Created Range: ${newRange.toString()}`);

// Example 3: Using RangeSpec directly (less common, for single range definition)
const rangeSpecInput = '100-200';
const parsedRangeSpec = new ContentRange().range.parse(rangeSpecInput); // Using ContentRange's prototype to parse
console.log(`\nParsed RangeSpec: low=${parsedRangeSpec.low}, high=${parsedRangeSpec.high}`);