range-parser

HTTP Range header field parser.

Compliant with RFC 9110, 14.2 Range

Deserialization

Parses a string as HTTP Range header field and yield JavaScript Object.

The field naming conventions follow RFC 9110, 14.2. Range.

1import { parseRange } from "https://deno.land/x/range_parser@$VERSION/parse.ts";
2import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
3
4const actual = parseRange("bytes=0-100, 200-, -300, test");
5
6assertEquals(actual, {
7  rangeUnit: "bytes",
8  rangeSet: [
9    { firstPos: 0, lastPos: 100 },
10    { firstPos: 200, lastPos: undefined },
11    { suffixLength: 300 },
12    "test",
13  ],
14});

rangeSet is a list of one or more <int-range>, <suffix-range> and <other-range> according to the definition of <range-spec>.

It has the following data structure:

1interface IntRange {
2  firstPos: number;
3  lastPos: number | undefined;
4}
5interface SuffixRange {
6  suffixLength: number;
7}
8type OtherRange = string;

Parsing specification

The parser strictly adheres to the ABNF syntax. It also checks semantics.

Specifically, the parser guarantees the following:

• The <int-range> or <suffix-range> number is a non-negative integer
• <range-unit> and <other-range> are syntactically valid strings
• <int-range>, <first-pos> is equal to or greater than <last-pos>.

Syntax error

Throws SyntaxError if it detects invalid syntax.

1import { parseRange } from "https://deno.land/x/range_parser@$VERSION/parse.ts";
2import { assertThrows } from "https://deno.land/std/testing/asserts.ts";
3
4assertThrows(() => parseRange("<invalid:input>"));

Semantic error

The following cases are semantic error:

• <int-range>, <last-pos> less than <first-pos>.

see RFC 9110, 14.1.1. Range Specifiers

In this case, it throws a RangeError.

1import { parseRange } from "https://deno.land/x/range_parser@$VERSION/parse.ts";
2import { assertThrows } from "https://deno.land/std/testing/asserts.ts";
3
4assertThrows(() => parseRange("bytes=1-0"));

Serialization

Serializes Range into string.

1import { stringifyRange } from "https://deno.land/x/range_parser@$VERSION/stringify.ts";
2import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
3
4assertEquals(
5  stringifyRange({
6    rangeUnit: "bytes",
7    rangeSet: [{ firstPos: 0, lastPos: 100 }, { suffixLength: 200 }],
8  }),
9  "bytes=0-100, -200",
10);

Throwing error

Throws TypeError if Range contains errors.

For error definitions, see the Parsing specification.

1import { stringifyRange } from "https://deno.land/x/range_parser@$VERSION/stringify.ts";
2import { assertThrows } from "https://deno.land/std/testing/asserts.ts";
3
4assertThrows(() =>
5  stringifyRange({
6    rangeUnit: "bytes",
7    rangeSet: [{ firstPos: NaN, lastPos: undefined }],
8  })
9);

Utility

We provide some utilities.

isIntRange

Whether the RangeSpec is IntRange or not.

1import {
2  type IntRange,
3  isIntRange,
4  type OtherRange,
5  type SuffixRange,
6} from "https://deno.land/x/range_parser@$VERSION/mod.ts";
7import { assert } from "https://deno.land/std/testing/asserts.ts";
8
9declare const intRange: IntRange;
10declare const suffixRange: SuffixRange;
11declare const otherRange: OtherRange;
12
13assert(isIntRange(intRange));
14assert(!isIntRange(suffixRange));
15assert(!isIntRange(otherRange));

isSuffixRange

Whether the RangeSpec is SuffixRange or not.

1import {
2  type IntRange,
3  isSuffixRange,
4  type OtherRange,
5  type SuffixRange,
6} from "https://deno.land/x/range_parser@$VERSION/mod.ts";
7import { assert } from "https://deno.land/std/testing/asserts.ts";
8
9declare const intRange: IntRange;
10declare const suffixRange: SuffixRange;
11declare const otherRange: OtherRange;
12
13assert(isSuffixRange(suffixRange));
14assert(!isSuffixRange(intRange));
15assert(!isSuffixRange(otherRange));

isOtherRange

Whether the RangeSpec is OtherRange or not.

1import {
2  type IntRange,
3  isOtherRange,
4  type OtherRange,
5  type SuffixRange,
6} from "https://deno.land/x/range_parser@$VERSION/mod.ts";
7import { assert } from "https://deno.land/std/testing/asserts.ts";
8
9declare const intRange: IntRange;
10declare const suffixRange: SuffixRange;
11declare const otherRange: OtherRange;
12
13assert(isOtherRange(otherRange));
14assert(!isOtherRange(intRange));
15assert(!isOtherRange(suffixRange));

isRangeFormat

Whether the input is HTTP Range header field format or not.

1import { isRangeFormat } from "https://deno.land/x/range_parser@$VERSION/mod.ts";
2import { assert } from "https://deno.land/std/testing/asserts.ts";
3
4assert(isRangeFormat("bytes=0-100, 200-, -500"));
5assert(!isRangeFormat("<invalid>"));

License

Copyright © 2023-present httpland.

Released under the MIT license