@whi/essence

Essence

A Javascript implementation for packing/unpacking contextual responses. This could be considered as a tool for the data translation layer.

Overview

The main feature of this tool is packing or unpacking messages.

Features

• Parse JSON encoded Essence package
• Create Essence package
• Create Essence package from value
• Create Essence package from a Javascript error

Install

npm i @whi/essence

Specification

See docs/specification.md

Basic Usage

Unpacking

Handling a success package

const { Translator } = require("@whi/essence");
const Interpreter = new Translator();

let pack = Interpreter.parse({
    "type": "success",
    "payload": data,
});

let payload = pack.value();
// payload == data

Handling an failure package

const { Translator } = require("@whi/essence");
const Interpreter = new Translator();

let pack = Interpreter.parse({
    "type": "failure",
    "payload": {
        "kind": "UserError",
        "error": "MissingInputError",
        "message": "You forgot the resource ID",
    },
});

let payload = pack.value();
// payload instanceof Error

Packing

Creating a success package

const { Translator } = require("@whi/essence");
const Interpreter = new Translator();

let pack = Interpreter.create( true );

JSON.stringify( pack, null, 4 );
// {
//     "type": "success",
//     "payload": true
// }

Creating a failure package

const { Translator } = require("@whi/essence");
const Interpreter = new Translator();

let pack = Interpreter.createFromError( "UserError", new TypeError("You broke it...") );

JSON.stringify( pack, null, 4 );
// {
//     "type": "failure",
//     "payload": {
//         "kind": "UserError",
//         "error": "TypeError",
//         "message": "You broke it",
//         "stack": [
//             "TypeError: You broke it",
//             "    at ...",
//             ...
//         ]
//     }
// }

API Reference

See docs/API.md

Contributing

See CONTRIBUTING.md