Siren.js Client
Siren API client library for JavaScript
This library handles much of the boilerplate, protocol-level details around interacting with a Siren API. Here are the things it can do:
- [x] Parse and validate Siren representations
- [x] Follow a
Link
(or any URL) - [x] Submit an
Action
- [x] Customize
Field
validation and serialization
- [x] Customize
- [x] Resolve a
SubEntity
- [x] Traverse an
Entity
via the Visitor pattern - [x] Crawl a Siren API
Table of Contents
Install
npm install @siren-js/client
Usage
import { follow, parse, resolve, submit } from '@siren-js/client';
// follow API entry point
let response = await follow('https://api.example.com/entry-point');
// parse the response as Siren
let entity = await parse(response);
// find the first 'item' sub-entity
const itemSubEntity = entity.entities.find((subEntity) => subEntity.rel.includes('item'));
if (itemSubEntity != null) {
// resolve the sub-entity to a full entity
entity = await resolve(itemSubEntity);
}
// find the first 'next' link
const nextLink = entity.links.find((link) => link.rel.includes('next'));
if (nextLink != null) {
// follow the 'next' link, if present, and parse as a Siren entity
entity = await follow(nextLink).then(parse);
}
// find the 'edit' action
const editAction = entity.getAction('edit');
if (editAction != null) {
// find the 'quantity' field in the 'edit' action
const quantityField = editAction.getField('quantity');
if (quantityField != null) {
// set the 'quantity' field value
quantityField.value = 69;
}
// submit the action and parse the response as Siren
response = await submit(editAction).then(parse);
}
Development
# setup Node.js
$ nvm use
# test with Jest
$ npm test
# run tests in watch mode
$ npm run test:watch
# run tests with coverage
$ npm run test:cov
# compile TypeScript code
$ npm run compile
# lint with ESLint
$ npm run lint
# automatically fix lint issues where possible
$ npm run lint:fix
# format files with Prettier
$ npm run format
# check files for proper formatting
$ npm run format:check
# build the library (compile, lint, format check)
$ npm run build:lib
# generate docs with TypeDoc
$ npm run build:docs
API
See our docs.
Maintainer
Contributing
See our contribution guidelines.
PRs accepted.
If editing the README, please conform to the standard-readme specification.
License
MIT © 2021 Dillon Redding