# siren-nav

> A library for navigating Siren APIs

Latest version **2.0.2** (published 2022-06-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install siren-nav
pnpm add siren-nav
yarn add siren-nav
bun add siren-nav
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.2 |
| Published | 2022-06-29 |
| First published | 2017-01-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 506.3 KB |
| Known vulnerabilities | 0 (+25 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Michael M. Tiller |
| Maintainers | mtiller |
| Keywords | siren, http |

## Links

- npm: https://www.npmjs.com/package/siren-nav
- Repository: https://github.com/xogeny/siren-nav
- npm.io page: https://npm.io/package/siren-nav

## Dependencies (7)

- [flat](https://npm.io/package/flat.md) ^5.0.0
- [rxjs](https://npm.io/package/rxjs.md) ^6.5.2
- [axios](https://npm.io/package/axios.md) ^0.16.0
- [debug](https://npm.io/package/debug.md) ^3.1.0
- [urijs](https://npm.io/package/urijs.md) ^1.19.1
- [siren-types](https://npm.io/package/siren-types.md) 1.0.0-rc10
- [isomorphic-ws](https://npm.io/package/isomorphic-ws.md) ^5.0.0

## Recent versions

- 2.0.2 (latest) — 2022-06-29
- 2.0.0-rc.2 — 2020-01-21
- 2.0.0-rc.1 — 2020-01-16
- 2.0.0-alpha.9 — 2020-01-16
- 2.0.0-beta.1 — 2019-05-29
- 2.0.0-alpha.8 — 2019-05-24
- 2.0.0-alpha.7 — 2019-05-24
- 2.0.0-alpha.6 — 2019-05-24
- 2.0.0-alpha.5 — 2019-05-14
- 2.0.0-alpha.3 — 2019-05-13
- 2.0.0-alpha.2 — 2019-05-13
- 2.0.0-alpha.1 — 2019-05-13
- 2.0.0-rc1 — 2019-05-13
- 1.2.0-rc2 — 2018-05-23
- 1.2.0-rc1 — 2018-05-23
- … 25 more at https://npm.io/package/siren-nav/versions

## README

# Overview

This package contains utilities for navigating and interacting with Siren based
APIs.  The central idea in this approach is that it should be possible to chain 
together complex sequences of interactions.  What complicates things is the fact 
that the events described do not take place in response to the commands themselves.
Instead, all processing is deferred as long as possible (i.e., until an actual 
result is required).  Fundamentally, there is something inherentily monadic in all
this although that wasn't a direct goal (just a useful pattern).

This is all achieved by the fact that lots of "promises" are being tracked
behind the scenes to describe the results of each processing step.  Further 
complicating things is the fact that some requests that "trigger" the processing 
are not necessarily the end of the chain.

To understand what is going on, consider the following code:

```
nav
    .follow("task")
    .performHyperAction("submit", {
        properties: {
            source: this.state.currentSource,
        }
    })
    .followLocation()
    .follow("result")
    .getSiren();
```

We start with a `SirenNav` instance, `nav`.  This has presumably already been created.
It manages the current "state" of the navigation internally.  That state mainly consists
of knowing what the URL of the current resoure is.  But it **DOES NOT** update the state
after the chain calls like `follow`.  Instead, what it does is record the process by 
which the current state (whatever that happens to be) can be transformed into the 
next step *without actually doing it*.  These chains of state transformations are stored 
up until an actual request is to be made.  In this example, that is the `performHyperAction`
call.  This necessarily must perform a (`POST`) request and returns a `NavResponse` object.
Again, note that this is not itself a promise of anything, but intead a "holder" of a 
promise to the result.  The actual request could have been requested (via the `get` or 
`getSiren` methods).  But in this case, the `followLocation` method initiates a new request that returns
a fresh `SirenNav` instance.  In other words, the chaining continues by turning a 
`SirenNav` instance into a `NavResponse` instance and back again into a `SirenNav` 
instance.

---
_Source: https://npm.io/package/siren-nav · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._