http-link-header

What is http-link-header?

The http-link-header npm package is used to parse and construct HTTP Link headers. It provides a convenient way to handle the Link header, which is used in HTTP responses to provide metadata about the requested resource, such as pagination links, relationships, and more.

What are http-link-header's main functionalities?

Parsing Link Headers

This feature allows you to parse a Link header string into an object. The parsed object contains references (refs) that you can easily access and manipulate.

const LinkHeader = require('http-link-header');
const linkHeader = LinkHeader.parse('<https://api.example.com/users?page=2>; rel="next", <https://api.example.com/users?page=5>; rel="last"');
console.log(linkHeader.refs);

Constructing Link Headers

This feature allows you to construct a Link header string from an object. You can add multiple links with different relations and then convert the object back to a string format suitable for HTTP headers.

const LinkHeader = require('http-link-header');
const linkHeader = new LinkHeader();
linkHeader.set({
  uri: 'https://api.example.com/users?page=2',
  rel: 'next'
});
linkHeader.set({
  uri: 'https://api.example.com/users?page=5',
  rel: 'last'
});
console.log(linkHeader.toString());

Finding Links by Relation

This feature allows you to find a specific link by its relation type (rel). This is useful for quickly accessing specific links like 'next', 'prev', 'first', or 'last' in paginated responses.

const LinkHeader = require('http-link-header');
const linkHeader = LinkHeader.parse('<https://api.example.com/users?page=2>; rel="next", <https://api.example.com/users?page=5>; rel="last"');
const nextLink = linkHeader.get('rel', 'next');
console.log(nextLink);

Other packages similar to http-link-header

parse-link-header

The parse-link-header package is another library for parsing HTTP Link headers. It provides similar functionality to http-link-header but focuses solely on parsing and does not offer construction capabilities. It is simpler and may be preferred if you only need to parse Link headers.

http-headers

The http-headers package is a more general library for parsing and constructing HTTP headers, including but not limited to Link headers. It offers a broader range of functionality compared to http-link-header, making it suitable for more complex HTTP header manipulations.

README

HTTP Link Header

Parse & format HTTP link headers according to RFC 8288

Install via npm

$ npm install --save http-link-header

Usage

var LinkHeader = require( 'http-link-header' )

Parsing a HTTP link header

var link = LinkHeader.parse(
  '<example.com>; rel="example"; title="Example Website", ' +
  '<example-01.com>; rel="alternate"; title="Alternate Example Domain"'
)

> Link {
  refs: [
    { uri: 'example.com', rel: 'example', title: 'Example Website' },
    { uri: 'example-01.com', rel: 'alternate', title: 'Alternate Example Domain' },
  ]
}

Checking whether it has a reference with a given attribute & value

link.has( 'rel', 'alternate' )
> true

Retrieving a reference with a given attribute & value

link.get( 'rel', 'alternate' )
> [
  { uri: 'example-01.com', rel: 'alternate', title: 'Alternate Example Domain' }
]

// Shorthand for `rel` attributes
link.rel( 'alternate' )
> [
  { uri: 'example-01.com', rel: 'alternate', title: 'Alternate Example Domain' }
]

Setting references

link.set({ rel: 'next', uri: 'http://example.com/next' })
> Link {
  refs: [
    { uri: 'example.com', rel: 'example', title: 'Example Website' },
    { uri: 'example-01.com', rel: 'alternate', title: 'Alternate Example Domain' },
    { rel: 'next', uri: 'http://example.com/next' }
  ]
}

Parsing multiple headers

var link = new LinkHeader()

link.parse( '<example.com>; rel="example"; title="Example Website"' )
> Link {
  refs: [
    { uri: 'example.com', rel: 'example', title: 'Example Website' },
  ]
}

link.parse( '<example-01.com>; rel="alternate"; title="Alternate Example Domain"' )
> Link {
  refs: [
    { uri: 'example.com', rel: 'example', title: 'Example Website' },
    { uri: 'example-01.com', rel: 'alternate', title: 'Alternate Example Domain' },
  ]
}

link.parse( '<example-02.com>; rel="alternate"; title="Second Alternate Example Domain"' )
> Link {
  refs: [
    { uri: 'example.com', rel: 'example', title: 'Example Website' },
    { uri: 'example-01.com', rel: 'alternate', title: 'Alternate Example Domain' },
    { uri: 'example-02.com', rel: 'alternate', title: 'Second Alternate Example Domain' },
  ]
}

Handling extended attributes

link.parse( '</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' )

> Link {
  refs: [
    { uri: '/extended-attr-example', rel: 'start', 'title*': { language: 'en', encoding: null, value: '①⓫⅓㏨♳𝄞λ' } }
  ]
}

Stringifying to HTTP header format

link.toString()
> '<example.com>; rel=example; title="Example Website", <example-01.com>; rel=alternate; title="Alternate Example Domain"'

Speed

$ npm run benchmark

# http-link-header .parse() ⨉ 1000000
ok ~1.29 s (1 s + 289696759 ns)

# http-link-header #toString() ⨉ 1000000
ok ~554 ms (0 s + 553782657 ns)

Changelog

v1.0.1

• Fix link.has() always returning true