@stackline/parse-link-header

Compatibility-first HTTP Link header parser for Node.js and browsers.

Documentation | npm | Issues | Repository

Current package version: 1.0.3

Why this package?

Parse HTTP Link headers into the relation-keyed pagination object used by parse-link-header@2.0.0. This independent maintained continuation keeps the CommonJS API while adding native ESM, first-party TypeScript declarations, browser-safe loading, runtime options, and parser hardening.

Compatibility

Item	Value
Package	`@stackline/parse-link-header@1.0.3`
Node.js runtime	`>=12`
CommonJS / primary entry	`./index.js`
ES module entry	`./index.mjs`
Type declarations	`./index.d.ts`

The maintained package preserves the established contract:

callable CommonJS default export;
default and named ESM exports;
null for empty or silently rejected over-limit input;
a plain object keyed by each rel token;
query values, URL, relation, and extension parameters on each link;
arrays for repeated query keys;
expansion of space-separated relations;
last-link-wins behavior when a relation is repeated;
index and index.js deep imports;
the default length bound and historical environment controls.

Intentional hardening discards parser-controlled __proto__, prototype, and constructor keys. Quoted parameters correctly retain semicolons, commas, and escaped quotes. Malformed links remain ignored rather than crashing the whole header.

See COMPATIBILITY_CONTRACT.md and MIGRATION.md for the complete boundary.

Installation

Install

npm install @stackline/parse-link-header

Keep existing source imports unchanged with an npm alias:

Usage

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

const parseLinkHeader = require('parse-link-header')

import parseLinkHeader from '@stackline/parse-link-header'

const links = parseLinkHeader(
  '<https://api.example.test/items?page=2>; rel="next", ' +
  '<https://api.example.test/items?page=8>; rel="last"'
)

console.log(links.next.page) // "2"
console.log(links.next.url)  // complete next-page URL

The named ESM export is also available:

import { parseLinkHeader } from '@stackline/parse-link-header'

Features and Integrations

Runtime limits

Parsing is bounded to 2,000 characters by default, preserving the mitigation introduced upstream for CVE-2021-23490. An over-limit value returns null unless throwing is enabled.

parseLinkHeader(header, {
  maxHeaderLength: 8192,
  throwOnMaxHeaderLengthExceeded: true
})

The historical environment variables remain supported:

PARSE_LINK_HEADER_MAXLEN
PARSE_LINK_HEADER_THROW_ON_MAXLEN_EXCEEDED

Per-call options take precedence and are suitable for browser applications where process.env is unavailable.

Project documents

Security

Review inputs and the package-specific compatibility limits before processing untrusted data. Report suspected vulnerabilities as described in the security policy.

Local Development

git clone https://github.com/alexandroit/stackline-parse-link-header.git
cd stackline-parse-link-header
npm ci
npm run verify

Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.

Consumer Smoke Test

Run the repository's existing consumer/package check after installing development dependencies:

npm run test:smoke

Release Checklist

Run npm run verify and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.

License

License and attribution

MIT. The original copyright notice for Thorsten Lorenz is preserved in LICENSE. This project is independent and is not affiliated with or endorsed by the original author.

Credits and original authors

Stackline Maintainers.
Thorsten Lorenz.
Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.