@siren-js/client

Siren.js Client

Node Package Build Workflow standard-readme compliant License Contributing

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:

  • Parse and validate Siren representations
  • Follow a Link (or any URL)
  • Submit an Action
    • Customize Field validation and serialization
  • Resolve a SubEntity
  • Traverse an Entity via the Visitor pattern
  • 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

@dillonredding

Contributing

See our contribution guidelines.

PRs accepted.

If editing the README, please conform to the standard-readme specification.

License

MIT © 2021 Dillon Redding

Generated using TypeDoc