HTTP pagination utility

@stackline/parse-link-header

Turn a response Link header into familiar next, prev, and last objects. Keep the established API while browser builds lose their Node polyfills.

npm install @stackline/parse-link-header

v1.0.0 zero runtime dependencies Node.js 12-24 TypeScript 3.9+

Executable behavior

Link header workbench

Maximum characters Throw when over limit Import style

HTTP Link header

Relation map

3 relations0 charactersplain object

Header parsed 2,000-character limit browser-safe configuration

Compatibility boundary

The relation-keyed shape stays put.

Each relation token points to a plain object containing its URL, relation, query values, and extension parameters. Space-separated relations expand; repeated relations keep the later link.

{
  next: {
    page: "2",
    per_page: "50",
    rel: "next",
    url: "https://api.example.test/items?page=2&per_page=50"
  }
}

Parser-controlled __proto__, prototype, and constructor keys are ignored. Quoted delimiters remain inside their parameter value.

Read the complete compatibility contract

Public surface

One parser, two module systems

Surface	Usage	Status
CommonJS	`const parse = require('@stackline/parse-link-header')`	Historical
ESM default	`import parse from '@stackline/parse-link-header'`	Additive
ESM named	`import { parseLinkHeader } from '@stackline/parse-link-header'`	Additive
Per-call options	`parse(header, { maxHeaderLength: 8192 })`	Additive

Release evidence

Compatibility is executable.

The release gate exercises valid, malformed, adversarial, browser, compiler, and installed-package paths.

1,000: differential Link headers against the frozen 2.0.0 baseline
1M: character linear-parser regression when the caller raises the bound
3 modes: CommonJS, native ESM, and browser bundle execution
0: runtime dependencies in the published package

Drop-in adoption

Keep existing imports.

An npm alias changes the implementation without changing require('parse-link-header') or existing default imports.

npm install parse-link-header@npm:@stackline/parse-link-header

Open the migration guide

Inspect the release