npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

hal

v1.2.0

Published

Hypertext Application Language

Downloads

8,457

Readme

JS HAL Travis CI Status

HAL is a hypermedia-aware serialization format, which can be represented using JSON and XML format.

It's obviously particularly useful for RESTful API delivering real Hypermedia contents (cf HATEOAS).

Usage

In your browser

<script src="/path/to/hal.js"></script>
<script>
var resource = new hal.Resource({name: "Harry"}, '/harry');
resource.link('hello', '/harry/hello');
console.log(resource.toJSON());
</script>

Compatibility

Don't know, didn't test. It may not even work on the browser, who knows ?

OK, more seriously you'll require:

  • JSON.stringify
  • Array.prototype.forEach
  • Array.prototype.reduce
  • Object.prototype.hasOwnProperty

In Node.JS

npm install hal
var hal = require('hal');

var resource = new hal.Resource({name: "Harry"}, '/harry');
resource.link('hello', '/harry/hello');
console.log(resource.toJSON());

API

Resource (object, uri)

This class designs a HAL resource:

  • object are the base fields of this resource
  • Note that you can define _links and _embedded properties, this is at your own risks
  • If you set href property and uri is undefined, it will be used instead of uri and deleted
  • uri is the link to this property (as <link rel="self">)

Link (rel, href) or Link (rel, attributes)

This class designs a HAL link:

  • rel is mandatory
  • href or attributes.href is mandatory

Resource#link (link) or Resource#link (rel, href) or Resource#link (rel, attributes)

Adds a new link to resource.

Resource#embed (rel, resource[s] [, pluralize])

Embeds other resource(s) to current resource.

Resource#toXML ()

Returns XML representation.

Note: embedded resources rel will be naively singularized by removing last 's'. See Resource#toJSON for more information.

Resource#toJSON ()

Returns JSON representation.

Note: rel will be naively pluralized by appending a 's' if there is not. This is due to differences between JSON and XML representation on embedded relationship and rel attribute.

Why this crappy singular/plural management ?

I base myself on the examples provided here. The two representations are equivalent, and you can see how plural and singular is used:

{
  "_links": {
   "self": { "href": "/orders" }
  },
  "_embedded": {
   "orders": [{
       "_links": {
         "self": { "href": "/orders/1" }
       }
     },{
       "_links": {
         "self": { "href": "/orders/2" }
       }
    }]
  }
}
<resource href="/orders">
  <resource rel="order" href="/orders/1">
  </resource>
  <resource rel="order" href="/orders/2">
  </resource>
</resource>

If this ugly action is the result of a misunderstanding, please let me know as I'd be glad to remove it!

Example

// A resource
var ordersCollection = new hal.Resource({
  currentlyProcessing: 14,
  shippedToday: 20
}, "/orders");

// Links
ordersCollection.link("next", "/orders?page=2");
ordersCollection.link("find", {href: "/orders{?id}", templated: true});

// Another resource
var order123 = new hal.Resource({
  total: 30.00,
  currency: "USD",
  status: "shipped"
}, "/orders/123");
// Alternative ways to link
order123.link(new hal.Link("basket", "/baskets/98712"));
order123.link(new hal.Link("customer", {href: "/customers/7809"}));

// Yet another resource
var order124 = new hal.Resource({
  total: 20.00,
  currency: "USD",
  status: "processing"
}, "/orders/124");
order124.link("basket", "/baskets/97213");
order124.link("customer", "/customers/12369");

// Embed the resources
ordersCollection.embed("orders", [order123, order124]);

Calling ordersCollection.toJSON(' '):

{
  "currentlyProcessing": 14,
  "shippedToday": 20,
  "_links": {
    "self": {
      "href": "/orders"
    },
    "next": {
      "href": "/orders?page=2"
    },
    "find": {
      "href": "/orders{?id}",
      "templated": "true"
    }
  },
  "_embedded": {
    "orders": [
      {
        "total": 30,
        "currency": "USD",
        "status": "shipped",
        "_links": {
          "self": {
            "href": "/orders/123"
          },
          "basket": {
            "href": "/baskets/98712"
          },
          "customer": {
            "href": "/customers/7809"
          }
        }
      },
      {
        "total": 20,
        "currency": "USD",
        "status": "processing",
        "_links": {
          "self": {
            "href": "/orders/124"
          },
          "basket": {
            "href": "/baskets/97213"
          },
          "customer": {
            "href": "/customers/12369"
          }
        }
      }
    ]
  }
}

Calling ordersCollection.toXML(' '):

<resource href="/orders">
  <link rel="next" href="/orders?page=2" />
  <link rel="find" href="/orders{?id}" templated="true" />
  <currentlyProcessing>14</currentlyProcessing>
  <shippedToday>20</shippedToday>
  <resource rel="order" href="/orders/123">
      <link rel="basket" href="/baskets/98712" />
      <link rel="customer" href="/customers/7809" />
      <total>30</total>
      <currency>USD</currency>
      <status>shipped</status>
  </resource>
  <resource rel="order" href="/orders/124">
      <link rel="basket" href="/baskets/97213" />
      <link rel="customer" href="/customers/12369" />
      <total>20</total>
      <currency>USD</currency>
      <status>processing</status>
  </resource>
</resource>

Yes, JSON seems a lot more verbose, but it's because of the spaces. In production you won't add indentation and then JSON is 517 bytes long, versus 625 bytes of XML.

Not yet, XML, not yet.