HTTP Link Header Parser & Formatter

Common errors

• TypeError: http_link_header_1.LinkHeader is not a constructor

  cause Attempting to use ES module import syntax for a CommonJS module in a TypeScript or ES module environment, where the default export is not correctly resolved.
  fix Change your import statement to `const LinkHeader = require('http-link-header');` or configure your TypeScript/bundler setup to handle CommonJS modules.

• TypeError: LinkHeader.parse is not a function

  cause Similar to the constructor error, this occurs when the `LinkHeader` object obtained via `import` is not the expected class or lacks the static `parse` method due to incorrect CommonJS/ESM interop.
  fix Ensure you are using `const LinkHeader = require('http-link-header');` to get the correct CommonJS module export that exposes the `parse` static method.

• Error: Invalid or relative URI passed to further processing logic

  cause The library does not resolve relative URIs in Link headers, leading to downstream errors if subsequent code expects absolute URLs.
  fix After parsing, manually resolve relative URIs against a known base URL (e.g., the URL of the document that returned the Link header) using `new URL(relativeUri, baseUrl).href`.

Warnings

• gotcha This library explicitly deviates from RFC 8288 by not automatically resolving relative URI-References. Parsed URIs remain relative and must be resolved by the user's application if absolute URIs are required.
  Fix: Implement custom URI resolution logic using a base URI after parsing the Link header. For example, `new URL(link.refs[0].uri, baseUrl).toString()`.
• gotcha The `http-link-header` package is a CommonJS module and does not provide native ES Module (`import`) exports. Using `import` statements directly in modern Node.js or browser environments may lead to unexpected behavior or require bundler configuration.
  Fix: Use `const LinkHeader = require('http-link-header');` for CommonJS environments. In ES module contexts, consider using a bundler (e.g., Webpack, Rollup) or evaluate alternatives that offer native ESM support.
• deprecated The `http-link-header` package appears to be unmaintained, with its last release in 2018. While functional for its stated purpose, users should be aware of the lack of ongoing bug fixes, security updates, or feature development. Consider newer alternatives for active projects.
  Fix: Evaluate if this library meets your long-term needs. For new projects or critical applications, consider alternatives like `@hugoalh/http-header-link` (which supports ESM/TypeScript) or be prepared to fork and maintain the package yourself.

Install

• npm install http-link-header npm
• yarn add http-link-header yarn
• pnpm add http-link-header pnpm

Imports

• LinkHeader (main class)
  wrong:

  import LinkHeader from 'http-link-header';
  import { LinkHeader } from 'http-link-header';

  correct:

  const LinkHeader = require('http-link-header');

  This package is a CommonJS module. Direct ES module `import` statements may not work as expected in modern environments without specific bundler configuration.
• LinkHeader.parse (static method)
  wrong:

  import { parse } from 'http-link-header';

  correct:

  const LinkHeader = require('http-link-header');
  const link = LinkHeader.parse(headerString);

  The `parse` method is a static method of the `LinkHeader` class, not a direct named export from the package.
• Link (instance)
  wrong:

  import { Link } from 'http-link-header';
  import Link from 'http-link-header';

  correct:

  const LinkHeader = require('http-link-header');
  const link = new LinkHeader();

  To create a new, empty `Link` object for accumulating or building headers, instantiate the `LinkHeader` class. The instance methods like `set` and `setUnique` operate on this object.

Quickstart

Demonstrates parsing a complex HTTP Link header string (including extended attributes), accessing individual references, filtering by relation type, adding new unique references, and stringifying the Link object back to a header format.

const LinkHeader = require('http-link-header');

// Example HTTP Link header string with multiple relations and extended attributes
const headerString = '<https://example.com/next>; rel="next", ' +
                     '<https://example.com/prev>; rel="prev"; title="Previous Page", ' +
                     '<https://example.com/image.png>; rel="preload"; as="image"; type="image/png", ' +
                     '</extended-attr-example>; rel=start; title*=UTF-8\'en\'%E2%91%A0%E2%93%AB%E2%85%93%E3%8F%A8%E2%99%B3%F0%9D%84%9E%CE%BB';

// Parse the header string
const link = LinkHeader.parse(headerString);

console.log('Parsed Link Header:', JSON.stringify(link, null, 2));
console.log('First reference URI:', link.refs[0].uri);
console.log('All "prev" references:', link.rel('prev'));
console.log('Extended title value:', link.get('rel', 'start')[0]['title*'].value);

// Add a new unique reference
link.setUnique({
  uri: 'https://example.com/canonical',
  rel: 'canonical'
});
console.log('\nAfter adding canonical:', JSON.stringify(link.refs, null, 2));

// Stringify back to header format
const formattedHeader = link.toString();
console.log('\nFormatted Header:', formattedHeader);

// Check for a specific relation
console.log('\nHas "preload" relation?', link.has('rel', 'preload'));