README.md

Siren.js Client

Siren API client library for JavaScript

Siren is a very powerful hypermedia format that enables a server and its clients to be decoupled from one another. There is a lot of boilerplate, protocol-level details around interacting with a Siren API, which is where Siren.js client comes in. This library allows you to do the following:

• Parse and validate Siren representations
• Follow a Link (or any URL)
• Submit an Action
  • Customize Field serialization
  • Toggle and customize Field validation
• Traverse an Entity via the Visitor pattern
• Crawl a Siren API

Table of Contents

• Background
• Install
• Usage
• Development
• API
• Maintainer
• Contributing
• License

Background

Install

npm install @siren-js/client

Usage

import { follow, parse } 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 'next' link
const nextLink = entity.links.find((link) => link.rel.includes('next'));
if (nextLink != null) {
  // follow the 'next' link, if present
  response = await follow(nextLink);
  // alternatively, parse the response content as JSON...
  const json = await response.json();
  // ...and run that result through the parse function
  entity = await parse(json);
}

// find the 'edit' action
const editAction = entity.getAction('edit');
if (editAction != null) {
  // find the 'quantity' field, if 'edit' action is present
  const quantityField = editAction.getField('quantity');
  if (quantityField != null) {
    // update 'quantity' field, if present
    quantityField.value = 69;
  }
  // submit the action
  response = await submit(editAction);
  // a third option is to extract the response content as text...
  const text = await response.text();
  // ...and run it through the parse function
  entity = await parse(response);
}

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