sharp-pointer v0.1.0
sharp-pointer
A complete implementation of JSON Pointer (RFC 6901) for nodejs and modern browsers.
Install
npm install sharp-pointer
Use/Import
var ptr = require('sharp-pointer')
Module API
Classes:
JsonPointer
: class – a convenience class for working with JSON pointers.JsonReference
: class – a convenience class for working with JSON references.
Functions:
.create(pointer)
.has(target,pointer)
.get(target,pointer)
.set(target,pointer,value,force)
.flatten(target,fragmentId)
.list(target,fragmentId)
.map(target,fragmentId)
All example code assumes data has this structure:
var data = {
legumes: [{
name: 'pinto beans',
unit: 'lbs',
instock: 4
}, {
name: 'lima beans',
unit: 'lbs',
instock: 21
}, {
name: 'black eyed peas',
unit: 'lbs',
instock: 13
}, {
name: 'plit peas',
unit: 'lbs',
instock: 8
}]
}
.create(pointer)
Creates an instance of the JsonPointer
class.
arguments:
pointer
: string, required – a JSON pointer in JSON string representation or URI fragment identifier representation
returns:
- a new
JsonPointer
instance
example:
var pointer = ptr.create('/legumes/0');
// fragmentId: #/legumes/0
.has(target,pointer)
Determins whether the specified target
has a value at the pointer
's path.
arguments:
target
: object, required – the target objectpointer
: string, required – a JSON pointer in JSON string representation or URI fragment identifier representation
returns:
- the dereferenced value or undefined if nonexistent
.get(target,pointer)
Gets a value from the specified target
object at the pointer
's path
arguments:
target
: object, required – the target objectpointer
: string, required – a JSON pointer in JSON string representation or URI fragment identifier representation
returns:
- the dereferenced value or undefined if nonexistent
example:
var value = ptr.get(data, '/legumes/1');
// fragmentId: #/legumes/1
.set(target, pointer, value, force)
Sets the value
at the specified pointer
on the target
. The default behavior is to do nothing if pointer
is nonexistent.
arguments:
target
: object, required – the target objectpointer
: string, required – a JSON pointer in JSON string representation or URI fragment identifier representationvalue
: any – the value to be set at the specifiedpointer
's pathforce
: boolean, optional – indicates whether nonexistent paths are created during the call
returns:
- The prior value at the pointer's path — therefore, undefined means the pointer's path was nonexistent.
example:
var prior = ptr.set(data, '#/legumes/1/instock', 50);
example force:
var data = {};
ptr.set(data, '#/peter/piper', 'man', true);
ptr.set(data, '#/peter/pan', 'boy', true);
ptr.set(data, '#/peter/pickle', 'dunno', true);
console.log(JSON.stringify(data, null, ' '));
{
"peter": {
"piper": "man",
"pan": "boy",
"pickle": "dunno"
}
}
.list(target, fragmentId)
Lists all of the pointers available on the specified target
.
See a discussion about cycles in the object graph later in this document if you have interest in how such is dealt with.
arguments:
target
: object, required – the target objectfragmentId
: boolean, optional – indicates whether fragment identifiers should be listed instead of pointers
returns:
- an array of
pointer-value
pairs
example:
var list = ptr.list(data);
[ ...
{
"pointer": "/legumes/2/unit",
"value": "ea"
},
{
"pointer": "/legumes/2/instock",
"value": 9340
},
{
"pointer": "/legumes/3/name",
"value": "plit peas"
},
{
"pointer": "/legumes/3/unit",
"value": "lbs"
},
{
"pointer": "/legumes/3/instock",
"value": 8
}
]
fragmentId
example:
var list = ptr.list(data, true);
[ ...
{
"fragmentId": "#/legumes/2/unit",
"value": "ea"
},
{
"fragmentId": "#/legumes/2/instock",
"value": 9340
},
{
"fragmentId": "#/legumes/3/name",
"value": "plit peas"
},
{
"fragmentId": "#/legumes/3/unit",
"value": "lbs"
},
{
"fragmentId": "#/legumes/3/instock",
"value": 8
}
]
.flatten(target, fragmentId)
Flattens an object graph (the target
) into a single-level object of pointer-value
pairs.
arguments:
target
: object, required – the target objectfragmentId
: boolean, optional – indicates whether fragment identifiers should be listed instead of pointers
returns:
- a flattened object of
property-value
pairs as properties.
example:
var obj = ptr.flatten(data, true);
{ ...
"#/legumes/1/name": "lima beans",
"#/legumes/1/unit": "lbs",
"#/legumes/1/instock": 21,
"#/legumes/2/name": "black eyed peas",
"#/legumes/2/unit": "ea",
"#/legumes/2/instock": 9340,
"#/legumes/3/name": "plit peas",
"#/legumes/3/unit": "lbs",
"#/legumes/3/instock": 8
}
.map(target, fragmentId)
Flattens an object graph (the target
) into a Map object.
arguments:
target
: object, required – the target objectfragmentId
: boolean, optional – indicates whether fragment identifiers should be listed instead of pointers
returns:
- a Map object containing key-value pairs where keys are pointers.
example:
var map = ptr.map(data, true);
for (let it of map) {
console.log(JSON.stringify(it, null, ' '));
}
...
["#/legumes/0/name", "pinto beans"]
["#/legumes/0/unit", "lbs"]
["#/legumes/0/instock", 4 ]
["#/legumes/1/name", "lima beans"]
["#/legumes/1/unit", "lbs"]
["#/legumes/1/instock", 21 ]
["#/legumes/2/name", "black eyed peas"]
["#/legumes/2/unit", "ea"]
["#/legumes/2/instock", 9340 ]
["#/legumes/3/name", "plit peas"]
["#/legumes/3/unit", "lbs"]
["#/legumes/3/instock", 8 ]
.decode(pointer)
Decodes the specified pointer
.
arguments:
pointer
: string, required – a JSON pointer in JSON string representation or URI fragment identifier representation.
returns:
- An array of path segments used as indexers to descend from a root/
target
object to a referenced value.
example:
var path = ptr.decode('#/legumes/1/instock');
[ "legumes", "1", "instock" ]
.decodePointer(pointer)
Decodes the specified pointer
.
arguments:
pointer
: string, required – a JSON pointer in JSON string representation.
returns:
- An array of path segments used as indexers to descend from a root/
target
object to a referenced value.
example:
var path = ptr.decodePointer('/people/wilbur dongleworth/age');
[ "people", "wilbur dongleworth", "age" ]
.encodePointer(path)
Encodes the specified path
as a JSON pointer in JSON string representation.
arguments:
path
: Array, required – an array of path segments
returns:
- A JSON pointer in JSON string representation.
example:
var path = ptr.encodePointer(['people', 'wilbur dongleworth', 'age']);
"/people/wilbur dongleworth/age"
.decodeUriFragmentIdentifier(pointer)
Decodes the specified pointer
.
arguments:
pointer
: string, required – a JSON pointer in URI fragment identifier representation.
returns:
- An array of path segments used as indexers to descend from a root/
target
object to a referenced value.
example:
var path = ptr.decodePointer('#/people/wilbur%20dongleworth/age');
[ "people", "wilbur dongleworth", "age" ]
.encodeUriFragmentIdentifier(path)
Encodes the specified path
as a JSON pointer in URI fragment identifier representation.
arguments:
path
: Array, required - an array of path segments
returns:
- A JSON pointer in URI fragment identifier representation.
example:
var path = ptr.encodePointer(['people', 'wilbur dongleworth', 'age']);
"#/people/wilbur%20dongleworth/age"
.noConflict()
Restores a conflicting JsonPointer
variable in the global/root namespace (not necessary in node, but useful in browsers).
example:
<!-- ur codez -->
<script src="/json-ptr-0.3.0.min.js"></script>
<script>
// At this point, JsonPointer is the json-ptr module
var ptr = JsonPointer.noConflict();
// and now it is restored to whatever it was before the json-ptr import.
</script>
JsonPointer
Class
Encapsulates pointer related operations for a specified pointer
.
properties:
.path
: array – contains the pointer's path segements..pointer
: string – the pointer's JSON string representation.uriFragmentIdentifier
: string – the pointer's URI fragment identifier representation
methods:
.has(target)
Determins whether the specified target
has a value at the pointer's path.
.get(target)
Looks up the specified target
's value at the pointer's path if such exists; otherwise undefined.
.set(target, value, force)
Sets the specified target
's value at the pointer's path, if such exists.If force
is specified (truthy), missing path segments are created and the value is always set at the pointer's path.
arguments:
target
: object, required – the target objectvalue
: any – the value to be set at the specifiedpointer
's pathforce
: boolean, optional – indicates whether nonexistent paths are created during the call
result:
- The prior value at the pointer's path — therefore, undefined means the pointer's path was nonexistent.
Tests
Tests are written using mocha and expect.js.
npm test
... or ...
mocha