node-siren-writer

A Siren Hypermedia Object Generator for Node

$ npm install siren-writer

Example

var siren = require("siren-writer");

var example = siren.entity("http://api.x.io/orders/42")
    .cls("order")
    .properties({
        orderNumber: 42,
        itemCount: 3,
        status: "pending"
    })
    .embed("http://x.io/rels/order-items", "http://api.x.io/orders/42/items", [ "items", "collection" ])
    .entity(siren.entity("http://api.x.io/customers/pj123")
        .cls("info", "customer")
        .rel("http://x.io/rels/customer")
        .properties({
            customerId: "pj123",
            name: "Peter Joseph"
        }))
    .action(siren.action("add-item", "http://api.x.io/orders/42/items")
        .title("Add Item")
        .method("POST")
        .type("application/x-www-form-urlencoded")
        .field("orderNumber", "hidden", "42")
        .field("productCode", "text")
        .field("quantity", "number"))
    .link("previous", "http://api.x.io/orders/41")
    .link("next", "http://api.x.io/orders/43");

console.log(example.toJSON());

will produce the example from the Siren homepage:

{
  "class": [ "order" ],
  "properties": {
      "orderNumber": 42,
      "itemCount": 3,
      "status": "pending"
  },
  "entities": [
    {
      "class": [ "items", "collection" ],
      "rel": [ "http://x.io/rels/order-items" ],
      "href": "http://api.x.io/orders/42/items"
    },
    {
      "class": [ "info", "customer" ],
      "rel": [ "http://x.io/rels/customer" ],
      "properties": {
        "customerId": "pj123",
        "name": "Peter Joseph"
      },
      "links": [
        { "rel": [ "self" ], "href": "http://api.x.io/customers/pj123" }
      ]
    }
  ],
  "actions": [
    {
      "name": "add-item",
      "title": "Add Item",
      "method": "POST",
      "href": "http://api.x.io/orders/42/items",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        { "name": "orderNumber", "type": "hidden", "value": "42" },
        { "name": "productCode", "type": "text" },
        { "name": "quantity", "type": "number" }
      ]
    }
  ],
  "links": [
    { "rel": [ "self" ], "href": "http://api.x.io/orders/42" },
    { "rel": [ "previous" ], "href": "http://api.x.io/orders/41" },
    { "rel": [ "next" ], "href": "http://api.x.io/orders/43" }
  ]
}

API

Object Creation

siren.entity(href)

Creates a new Entity object. Allows for setting href during initialization.

siren.link(rel, href)

Creates a new Link object. Allows for setting rel and href during initialization.

siren.action(name, href)

Creates a new Action object. Allows for setting name and href during initialization.

siren.field(name, type, value)

Creates a new Field object. Allows for setting all properties (name, type and value) during initialization.

Object Methods

All object types will have a toJSON() method that turns the object into a valid application/vnd.siren+json object that can be JSON-serialized directly.

The vast majority of the other methods available can be put into 1 of 3 categories:

1. Property Modifiers
2. Simple List Builders
3. Complex List Builders

Property Modifiers are a single value, such as an href. Calling the method multiple times on the same object simply overwrites the previous value.

Simple List Builders create an Array of simple values, such as a class or rel. The first call creates the array, subsequent calls append to that same array. For these methods, if an Array is passed as the first argument, that Array is used and other arguments end up being ignored.

siren.entity()
    .rel("a")           // create: adds a single value ("a")
    .rel("b", "c")      // appends: adding "b" and "c"
    .rel([ "d", "e" ]); // appends: adding "d" and "e"

// resulting rel value: [ "a", "b", "c", "d", "e" ]

Complex List Builders also create an Array, however instead of simple values, this list is composed of nested objects. (such as a collection of links or actions within an entity) The arguments used in this function are passed to the constructor for that object type.

siren.entity()
    // both of these methods have the same effect
    .link("self", "/")
    .link(siren.link("self", "/"));

Entity

Property Modifiers:

• href(href): href
• title(title): title

Simple List Builders

• rel(...rel): rel
• class(...class) or cls(...class): class

Complex List Builders

• link(rel, href): links
• action(name, href): actions
• entity(href): entities

Other Methods

• properties(props): Uses extend to set properties
• embed(rel, href, cls): Adds an Embedded Link to entities

Link

Property Modifiers:

• href(href): href

Simple List Builders

• rel(...rel): rel

Action

Property Modifiers:

• name(name): name
• href(href): href
• title(title): title
• type(type): type

Simple List Builders

• class(...class) or cls(...class): class

Complex List Builders

• field(name, type, value): fields

Other Methods

• method(method): Uppercases the input value before setting method

Field

Property Modifiers:

• name(name): name
• value(value): value

Other Methods

• type(type): Checks that the input type is an allowed value before setting.