Hypermedia Representor implemented with Hyper+json
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
test
.eslintignore
.eslintrc.yml
.gitignore
.snyk
.travis.yml
LICENSE
README-PLUGINDEV.md
README.md
benchmark.js
codecov.yml
package.json

README.md

Kōkua - Hypermedia Representor

Kōkua (Hawaiian) - help, aid, assistance

NPM Version Build Test Coverage

Kōkua is an implementation of the Representor pattern, written in modern Javascript/Node. It allows developers to represent hypermedia messages in a flexible media type, purpose-designed for the task: Hyper and automatically outputs messages in a variety of popular Hypermedia formats such as:

  1. HAL (application/hal+json)
  2. Siren (application/vnd.siren+json)
  3. Collection+JSON (application/vnd.collection+json)
  4. UBER (application/vnd.uber+json)
  5. JSON API (application/vnd.api+json)
  6. etc.

Usage

Convert a Hyper document to other formats

  const kokua = require("kokua");
  let halDoc = kokua(hyperDoc, kokua.mt('hal'));

where the first argument to a kokua() call is a JSON document formatted as a Hyper document, and the second argument is the name of a supported media-type that we want the message to be translated to.

Convert a document in another format to Hyper

  const kokua = require("kokua");
  let uberDoc = kokua.parse(halDoc, kokua.mt('hal'));

where the first argument to a kokua.parse() call is a JSON document formatted in a media type, supported by Kokua, and the second argument is the name of a supported media-type that we want the message to be translated from.

Please see the official specification for Hyper media type, for more details about the format.

Advanced Example

  const hyperDoc = const hyper = {
    "h:head": {"curies": {"ea": "http://example.com/docs/rels/"}},
    "h:ref": {"self": "/orders", "next": "/orders?page=2"},
    "currentlyProcessing": 14, "shippedToday": 20,
    "ea:order": [
      {
        "h:ref": {
          "self": "/orders/123",
          "ea:basket": "/baskets/98712",
          "ea:customer": "/customers/7809"
        },
        "total": 30, "currency": "USD", "status": "shipped"
      },
      {
        "h:ref": {
          "self": "/orders/123",
          "ea:basket": "/baskets/98712",
          "ea:customer": "/customers/124234"
        },
        "total": 123, "currency": "USD", "status": "pending"
      }
    ]
  };

  const kokua = require("kokua");
  let halDoc = kokua(hyperDoc, kokua.mt('hal'));
  let sirenDoc = kokua(hyperDoc, kokua.mt('siren'));

Implementation Status

  1. Hyper to HAL: 100%
    • Reverse: 0%
  2. Hyper to Siren: 100%
    • Reverse: 100%
  3. Hyper to UBER: 0%
    • Reverse: 0%
  4. Hyper to Collection+JSON: 0%
    • Reverse: 0%
  5. Hyper to JSONAPI: 0%
    • Reverse: 0%

Quick-n-dirty benchmark

> node benchmark.js
Time to convert HAL 10,000 times:  2.572 ms
Time to convert Siren 10,000 times:  1.42 ms

Plugin Development

If you are interested in developing a new plugin to implement translation to a hypermedia format that is not yet implemented, please refer to README-PLUGINDEV