@hateoas/resolver


Translate HATEOAS HAL links into URLs that can be used by your application trough one method. Handles missing links and translation of templated link options into query string parameters.

It supports following expansions of the URI template spec:
* {}
* {#}
* {.}
* {/}
* {;}
* {?}
* {&}

Valid arguments for expansion are single string or arrays of strings.
When providing an array in combination with an operator, this variable will be exploded by default with the separator associated with the operator i.e.:

``javascript
const links = {
_links: {
example: {
href: 'https://local{/api}{?param}'
}
}
}

resolve(links, 'example', {
api: ['path', 'subpath'],
param: ['p1', 'p2'],
}) >> 'https://local/path/subpath?param=p1¶m=p2'
`

Install

`shell
npm install hateoas
`

Usage

Resolver is written for EcmaScript modules, so after installing you are one step from using it.

`javascript
import { resolve } from 'hateoas';
`

This defined user object will be a base for all of our examples.

`javascript
const user = {
name: 'The Doctor',
_links: {
self: 'https://example.com/characters/1',
companions: {
href: 'https://example.com/characters/1/companions{?page,size}',
templated: true,
},
enemies: [
{
href: 'https://example.com/characters/1/enemies{?race,page,size}',
templated: true,
},
{
href: 'https://example.com/characters/1/enemies{?nameSearch,page,size}',
templated: true,
},
{
href: 'https://example.com/characters/1/enemies?noParams',
templated: false,
},
],
},
};
`

$3

`javascript
resolve(user._links, 'self');
// https://example.com/characters/1
`

$3

When you pass no parameters, the link template will be simply stripped of options. Based on top example.

`javascript
resolve(user._links, 'companions');
// https://example.com/characters/1/companions
`

When you pass parameters, they will be translated into the link template options. Based on top example.

`javascript
resolve(user._links, 'companions', {
page: 3,
size: 5,
});
// https://example.com/characters/1/companions?page=3&size=5
`

#### Missing some parameters?

Beware, all parameters that have no matching link option will get lost. Based on top example.

`javascript
resolve(user._links, 'companions', {
page: 3,
filter: 'Bad Wolf',
});
// https://example.com/characters/1/companions?page=3
`

$3

The resolver will choose the best link for you based on the list of parameters you provide. If you provide none, then the non-templated links are preferred. Based on top example.

`javascript
resolve(user._links, 'enemies');
// Returns the non-templated link
// https://example.com/characters/1/enemies?noParams
`

`javascript
resolve(user._links, 'enemies', {
race: 'timelord',
});
// https://example.com/characters/1/enemies?race=timelord
`

#### Conflicting values

It may happen that you provide parameters that are mutually exclusive by the links definition. In that case, resolver will give you the first link specified. In the top example, we cannot search by name and race at the same time.

`javascript
resolve(user._links, 'enemies', {
race: 'timelord',
nameSearch: 'The Master',
page: 10,
size: 5,
});
// https://example.com/characters/1/enemies?race=timelord&page=10&size=5
`

$3

If your API uses _links or links to provide HAL links, you can simply pass the object to get branch shortcut.

`javascript
resolve(user, 'self');
// https://example.com/characters/1
``