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 5988

Install via npm

$ npm install --save http-link-header

Usage

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

Parse 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' },
  ]
}

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

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

Retrieve 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' }
]

Set 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' }
  ]
}

Parse multiple headers

var links = new LinkHeader()

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

links.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' },
  ]
}

links.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' },
  ]
}

Stringify 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 .......................................... 204,355 op/s
  toString ....................................... 485,465 op/s