JarCastingHalfred
A "parser" for the JSON-flavour of HAL, the Hypertext Application Language (that is application/hal+json). If you feed it an object that has _links and _embedded properties, as described in the HAL spec, it will make all links and embedded resource available via convenient methods. If requested, Halfred can also validate a HAL object.
For more information on HAL, see
This module works in Node.js and in the browser. It has no dependencies, the size of the browser build is 8 KB / 4 KB (non-minified/minified)
Installation
Node.js
npm:
npm install halfred --save
Browser
- If you are using npm and Browserify: Just
npm install halfred --saveandrequire('halfred'), then browserify your module as usual. - If you are using Bower:
bower install halfred --save - Otherwise you can grab a download from the latest release:
- halfred.min.js: Minified build with UMD. This build can be used with an AMD loader like RequireJS or with a script tag (in which case it will register
halfredin the global scope). If in doubt, use this build. - halfred.js: Non-minified build with UMD. Same as above, just larger :-)
- halfred.external.min.js: Minified require/external build. Created with browserify's
--requireparameter and intended to be used (required) from other browserified modules, which were created with--external halfred. This build could be used if you use browserify but do not want to bundle Halfred with your own browserify build but keep it as a separate file. - halfred.external.js: Non-minified require/external build. Same as before, just bigger.
- halfred.min.js: Minified build with UMD. This build can be used with an AMD loader like RequireJS or with a script tag (in which case it will register
Usage
var halfred = require('halfred');
var resource = halfred.parse(object);
Resource API
halfred.parse(object) returns a Resource object. Here's what you can do with it:
allLinkArrays(): Returns an object which has an array for each link that was present in the source object. See below why each link is represented as an array.allLinks(): Alias forallLinkArrayslinkArray(key): Returns the array of links for the givenkey, ornullif there are no links for thiskey.link(key): Returns the first element of the array of links for the givenkeyornullif there are no links for thiskey.allEmbeddedResourceArrays(): Returns an object which has an array for each embedded resource that was present in the source object. See below why each embedded resource is represented as an array. Each element of any of this arrays is in turn aResourceobject.allEmbeddedArrays(): Alias forallEmbeddedResourceArrays()allEmbeddedResources(): Alias forallEmbeddedResourceArrays()embeddedResourceArray(key): Returns the array of embedded resources for the givenkey, ornullif there are no embedded resources for thiskey. Each element of this arrays is in turn aResourceobject.embeddedArray(key): Alias forembeddedResourceArray().embeddedResource(key): Returns the first element of the array of embedded resources for the givenkeyornullif there are no embedded resources for thiskey. The returend object is aResourceobject.embedded(key): Alias forembeddedResource(key)original(): Returns the unmodified, original object that was parsed to this resource. This is rather uninteresting for the source object you give to theparsemethod (because you probably still have a reference to the source object) but it is a convenient way to get the part of the source object that corresponds to an embedded resource.hasCuries(): Returnstrueif the resource has any CURIEs (Compact URIs).curieArray(): Returns the array of CURIEs. Each object in the array is a link object, which means it can be templated etc. See below for the link object API.curie(name): Returns the curie with the given name, if any. The returned object is a link object, which means it can be templated etc. See below for link object API.reverseResolveCurie(fullUrl): Returns the compact URI for the given full URL, if any.validationIssues(): Returns all validation issues. Validation issues are only gathered if validation has been turned on by callinghalfred.enableValidation()before callinghalfred.parse.validation(): Alias forvalidationIssues()
In addition to the methods mentioned here, resource has all properties of the source object. This is also true for embedded Resource objects. The non-HAL properties (that is, any property except _links and _embedded) are copied over to the Resource object. This is always a shallow copy, so modifying the a non-HAL property in the Resource object might also alter the source object and vice versa.
The Resource object also has the properties _links and _embedded but they might differ from the _links/_embedded properties in the source object (Halfred applies some normalization to them). These are not intended to be accessed by clients directly, instead, use the provided methods to work with links and embedded resources.
Extending Resource objects
The Resource class is exported on the halfred object, and therefore can be extended by attaching new methods to the prototype:
var halfred = require('halfred');
halfred.Resource.prototype.followLink = function followLink(key, callback) {
var link = this.link(key);
if (link) {
return $.get(link.href, callback);
}
}
var resource = halfred.parse(object);
resource.followLink('self', function(data) {
console.log('response data', data);
});
Links And Embedded Resources
The resource methods allLinkArrays() and linkArray(key) an array for each link, instead of a single object. This might seem counterintuitive. The HAL spec allows a link to be either a single link object or an array of link objects, so halfred normalizes all that are not arrays to be single element arrays. If you are sure that there is only one link for a given key, you can use link(key) to directly get the first element from that array.
The same is true for embedded resources.
Once you have the link object, you can access the properties href, templated and so on (refer to the spec for details) on it. The templated property defaults to false, if it wasn't set in the object given to parse, all other properties described in the spec default to null.
Enable/Disable Validation
In some situations, it might be desirable to validate the resource you want to parse and check, if it is valid according to the HAL spec. By default, Halfred does not do validation checks. If you want to have validation checks you can enable them by calling halfred.enableValidation(). Then after parsing a source object, call validationIssues() on the Resource object returned by parse to get an array of all validation issues.
You can disable validation checks again by calling halfred.disableValidation(). You can also call halfred.enableValidation(true) or halfred.enableValidation(false) to enable/disable validation.
Inject a Logger
You can use halfred.injectLogger(logger) to inject any object that exposes the same API as console does, that is, it needs to provide the methods log, warn, etc. Actually, currently only logger.warn is used to print a deprecation warning as mandated by the Hal spec, section 5.4. If no logger is injected, the global console object will be used. If this object does not exist, a no-op logger will be used and deprecation warnings will not be logged.
Contributing
Code of Conduct
See Code of Conduct.
Release Notes
See CHANGELOG.
License
MIT
