@web3-storage/parse-link-header/README.md

Parses a link header and returns paging information for each contained link.

# parse-link-header

Parses a link header and returns paging information for each contained link.

Note: This is a fork of [github.com/thlorenz/parse-link-header](https://github.com/thlorenz/parse-link-header) with zero dependencies, no Node.js globals and ESM.

## Install

    npm install @web3-storage/parse-link-header

## Usage

```js
import { parseLinkHeader } from '@web3-storage/parse-link-header'

const linkHeader =
  '<https://api.github.com/user/9287/repos?page=3&per_page=100>; rel="next", ' +
  '<https://api.github.com/user/9287/repos?page=1&per_page=100>; rel="prev"; pet="cat", ' +
  '<https://api.github.com/user/9287/repos?page=5&per_page=100>; rel="last"'

const parsed = parseLinkHeader(linkHeader)
console.log(parsed)
```

```js
{ next:
   { page: '3',
     per_page: '100',
     rel: 'next',
     url: 'https://api.github.com/user/9287/repos?page=3&per_page=100' },
  prev:
   { page: '1',
     per_page: '100',
     rel: 'prev',
     pet: 'cat',
     url: 'https://api.github.com/user/9287/repos?page=1&per_page=100' },
  last:
   { page: '5',
     per_page: '100',
     rel: 'last',
     url: 'https://api.github.com/user/9287/repos?page=5&per_page=100' } }
```

## API

`parseLinkHeader(linkHeader: String, options?: Object): Object`

Parses the given link header containing [web links](http://tools.ietf.org/html/rfc5988) and returns an object keyed by
the `rel` property that contains information about each link.

The following options are available to avoid redundantly parsing of extremely long (invalid) input:

* `maxHeaderLength: number` - Sets the number of characters the input should be limited to - longer inputs will not be handled. Defaults to `2000`.
* `throwOnMaxHeaderLengthExceeded: boolean` - Defines behavior for when the `PARSE_LINK_HEADER_MAXLEN` parameter is exceeded. if `true`, an error will be thrown; if it's `false`/`null`/`undefined`, the function fails silently by returning `null`. Defaults to `false`.

### Formatting a link header

The purpose of this module is to parse the link header information. To format an object generated by this module back to the link header string, use the [format-link-header](https://github.com/jonathansamines/format-link-header) module.