kokua

Kōkua - Hypermedia Representor

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

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