Link Header Parser

0.1.2 · active · verified Sun Apr 19

This package, `linkheader-parser` (version 0.1.2), offers a minimalist utility for parsing HTTP `Link` headers as defined in RFC 5988. Given its very early stage versioning, it is likely in an experimental or pre-1.0 development phase, meaning the API might not yet be stable and releases are infrequent. Its core function is to extract structured information (like URI, relation types, and parameters) from a standard `Link` header string. As a focused parser, its key differentiator is its lightweight implementation and direct adherence to the RFC, without additional features like URI resolution. Users should be aware that such an early version implies potential for breaking changes in minor releases and limited support compared to more mature alternatives. It is a simple, no-dependency parser for web linking metadata.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'next')
```
cause The link header string passed to the parser was invalid or contained no 'next' relation.

fix Ensure the input `Link` header string is correctly formatted according to RFC 5988 and contains the expected 'next' relation. Add checks for `undefined` before accessing properties, e.g., `parsedLinks?.next`.
```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use ESM `import` syntax in a CommonJS (CJS) Node.js environment without proper configuration (`"type": "module"` in `package.json` or a transpiler).

fix For CJS projects, try `const { parse } = require('linkheader-parser');`. Alternatively, configure your project as an ESM module by adding `"type": "module"` to your `package.json` or use a bundler like Webpack or Rollup.

Warnings

breaking As a package in the 0.x.x version range, any minor version update (e.g., from 0.1.2 to 0.2.0) may introduce breaking changes to the API without adhering to semantic versioning guarantees.
Fix: Pin the exact version in `package.json` (`"linkheader-parser": "0.1.2"`) and review release notes thoroughly before updating to new minor or patch versions.
gotcha This parser, like many others, may not automatically resolve relative URIs within the Link header. It typically provides the URI string as found in the header, leaving resolution to the consuming application.
Fix: If relative URIs are expected, implement client-side logic to resolve them against a base URI after parsing the link header.
gotcha Malformed or extremely long Link headers can lead to unexpected parsing errors or performance issues. Some parsers have safeguards (like max length limits) but this library's specific handling is undocumented.
Fix: Sanitize or truncate untrusted input Link headers before passing them to the parser. Implement robust error handling around parsing calls.
gotcha The specification allows for multiple parameters with the same name (e.g., `rel="next prev"`). The parser's output structure for such cases (e.g., an array or a single string) requires inspection.
Fix: Test parsing of Link headers with multiple `rel` values or other duplicate parameters to understand the exact output format and adjust consuming code accordingly.

Install

npm install linkheader-parser npm
yarn add linkheader-parser yarn
pnpm add linkheader-parser pnpm

Imports

parse
wrong:
```
const parse = require('linkheader-parser');
```
correct:
```
import { parse } from 'linkheader-parser';
```
Assuming a named 'parse' export. CommonJS `require` might work, but modern usage prefers ESM imports. For this pre-1.0 package, ESM support is an assumption; verify if bundling for older environments.
Link
```
import type { Link } from 'linkheader-parser';
```
The library likely exports a type definition for the parsed Link object structure, though its exact name and export method (named or interface) would need verification from source.

Quickstart

Demonstrates how to parse a complex RFC 5988 Link header string and access the extracted link information.

import { parse } from 'linkheader-parser';

const linkHeaderString = '<https://example.com/api/page/2>; rel="next", ' +
                         '<https://example.com/api/page/1>; rel="prev", ' +
                         '<https://example.com/api/page/last>; rel="last"; title="Last Page"; type="text/html"; param_with_dashes="value-here"';

try {
  const parsedLinks = parse(linkHeaderString);
  console.log('Parsed "next" link:', parsedLinks.next);
  console.log('Parsed "last" link URI:', parsedLinks.last?.uri);
  console.log('All parsed links:', JSON.stringify(parsedLinks, null, 2));
} catch (error) {
  console.error('Error parsing link header:', error.message);
}

// Expected output structure (example, actual depends on library implementation):
// {
//   next: { uri: 'https://example.com/api/page/2', rel: 'next' },
//   prev: { uri: 'https://example.com/api/page/1', rel: 'prev' },
//   last: { uri: 'https://example.com/api/page/last', rel: 'last', title: 'Last Page', type: 'text/html', 'param_with_dashes': 'value-here' }
// }

view raw JSON →