1 | hyper-path [![Build Status](https://travis-ci.org/hypergroup/hyper-path.png)](https://travis-ci.org/hypergroup/hyper-path)
|
2 | ==========
|
3 |
|
4 | Traverse a hyper api
|
5 |
|
6 | Installation
|
7 | ------------
|
8 |
|
9 | ### Node
|
10 |
|
11 | ```sh
|
12 | $ npm install hyper-path
|
13 | ```
|
14 |
|
15 | ### Component
|
16 |
|
17 | ```sh
|
18 | $ component install hypergroup/hyper-path
|
19 | ```
|
20 |
|
21 | Usage
|
22 | -----
|
23 |
|
24 | ```js
|
25 | var client = require('hyper-path');
|
26 |
|
27 | /**
|
28 | * create a agent
|
29 | */
|
30 |
|
31 | function agent(fn) {
|
32 | // make a request to the root of the api here and call
|
33 | // fn(err, body);
|
34 | }
|
35 |
|
36 | agent.get = function(href, fn) {
|
37 | // make a request to the href and call
|
38 | // fn(err, body);
|
39 | }
|
40 |
|
41 | client('.path.to.desired.property', agent)
|
42 | .on(function(err, property) {
|
43 | // property will be set to the value at the end of the passed path, deliminated with '.'
|
44 | // if any of the intermediate properties are undefined a short-circuit will occur and return `undefined`
|
45 | });
|
46 | ```
|
47 |
|
48 | Agents can offer subscriptions and call `fn` anytime the data changes at the `href`. The methods should return an `unsubscribe` function so the request can clean itself up when calling `off`.
|
49 |
|
50 | ```js
|
51 | function agent(fn) {
|
52 | // make a request here
|
53 | return function unsubscribe() {
|
54 | // implement me!
|
55 | }
|
56 | }
|
57 |
|
58 | agent.get = function(href, fn) {
|
59 | // make a request here
|
60 | return function unsubscribe() {
|
61 | // implement me!
|
62 | }
|
63 | }
|
64 |
|
65 | var req = client('.path.to.desired.property', agent)
|
66 | .on(function(err, property) {
|
67 | // this function will be called anytime any intermediate paths change
|
68 | });
|
69 |
|
70 | // stop listening to api changes
|
71 | req.off();
|
72 | ```
|
73 |
|
74 | Clients can also use a scope for requests with the `scope` method.
|
75 |
|
76 | ```js
|
77 | client('local.remote', agent)
|
78 | .scope({local: {href: '/path/to/resource'}})
|
79 | .on(function(err, remote) { });
|
80 | ```
|
81 |
|
82 | The function passed to on will be refreshed anytime the scope is updated.
|
83 |
|
84 | ```js
|
85 | var req = client('local.remote', agent)
|
86 | .on(function(err, remote) { });
|
87 |
|
88 | req.scope({local: {href: '/new/path/to/other/resource'}});
|
89 | ```
|
90 |
|
91 | Tests
|
92 | -----
|
93 |
|
94 | ```sh
|
95 | $ npm install
|
96 | $ npm test
|
97 | ```
|