reftools

What is reftools?

The reftools npm package is a utility library designed for managing and manipulating JSON references within JavaScript objects. It provides tools for resolving, merging, and cloning JSON references, making it useful for handling complex JSON structures that include internal references.

What are reftools's main functionalities?

resolve

This feature resolves JSON references within the document. It replaces references with the actual data they refer to, simplifying the structure for easier manipulation and access.

const reftools = require('reftools');
let doc = { a: { b: { $ref: '#/c' } }, c: { d: 'hello' } };
let resolved = reftools.resolve(doc);
console.log(resolved);

merge

This feature merges two JavaScript objects, incorporating properties from the source object into the destination object. It's particularly useful for combining configurations or settings.

const reftools = require('reftools');
let src = { a: 1 };
let dst = { b: 2 };
reftools.merge(src, dst);
console.log(dst);

clone

This feature creates a deep clone of an object, including resolving any internal JSON references. This is useful for creating independent copies of complex objects that include references.

const reftools = require('reftools');
let original = { a: { b: { $ref: '#/c' } }, c: { d: 'hello' } };
let cloned = reftools.clone(original);
console.log(cloned);

Other packages similar to reftools

json-refs

json-refs is a package that provides tools for resolving references in JSON objects. It is similar to reftools but focuses more on the resolution aspect and includes additional utilities for finding and listing unresolved references.

swagger-tools

swagger-tools is a package primarily used for building and managing Swagger documents but includes functionality for resolving JSON references similar to reftools. It differs in that it is more specialized towards Swagger, whereas reftools is more general-purpose.

README

RefTools

Functions

nop(obj) ⇒

a no-op placeholder which returns the given object unchanged useful for when a clone function needs to be passed but cloning is not required

clone(obj) ⇒

clones the given object using JSON.parse and JSON.stringify

shallowClone(obj) ⇒

clones the given object's properties shallowly, ignores properties from prototype

deepClone(obj) ⇒

clones the given object's properties deeply, ignores properties from prototype

fastClone(obj) ⇒

clones the given object's properties shallowly, using Object.assign

circularClone()

Source: stackoverflow http://bit.ly/2A1Kha6

dereference(o) ⇒

dereferences the given object

flatten(obj, callback) ⇒

flattens an object into an array of properties

jpescape(s) ⇒

escapes JSON Pointer using ~0 for ~ and ~1 for /

jpunescape(s) ⇒

unescapes JSON Pointer using ~0 for ~ and ~1 for /

jptr(obj, prop, newValue) ⇒

from obj, return the property with a JSON Pointer prop, optionally setting it to newValue

recurse(object, state, callback)

recurses through the properties of an object, given an optional starting state anything you pass in state.payload is passed to the callback each time

reref(obj, options) ⇒

Simply modifies an object to have no self-references by replacing them with $ref pointers

objToGraph(obj, containerName) ⇒

Takes an object and creates a graph of JSON Pointer / References

visit(obj, comparison, callbacks) ⇒

Given an expanded object and an optional object to compare to (e.g. its $ref'd form), will call the following functions:

• callbacks.before - lets you modify the initial starting state, must return it
• callbacks.where - lets you select a subset of properties, return a truthy value
• callbacks.filter - called for all selected properties, can mutate/remove (by setting to undefined)
• callbacks.compare - allowing the objects to be compared by path (i.e. for $ref reinstating)
• callbacks.identity - called on any object identity (previously seen) properties
• callbacks.selected - called for all selected/unfiltered properties, does not mutate directly
• callbacks.count - called at the end with the number of selected properties
• callbacks.finally - called at the end of the traversal

Typedefs

Result ⇒ Result

Try to get a topological sorting out of directed graph.

nop(obj) ⇒

a no-op placeholder which returns the given object unchanged useful for when a clone function needs to be passed but cloning is not required

Kind: global function
Returns: the input object, unchanged

Param	Description
obj	the input object

clone(obj) ⇒

clones the given object using JSON.parse and JSON.stringify

Kind: global function
Returns: the cloned object

Param	Description
obj	the object to clone

shallowClone(obj) ⇒

clones the given object's properties shallowly, ignores properties from prototype

Kind: global function
Returns: the cloned object

Param	Description
obj	the object to clone

deepClone(obj) ⇒

clones the given object's properties deeply, ignores properties from prototype

Kind: global function
Returns: the cloned object

Param	Description
obj	the object to clone

fastClone(obj) ⇒

clones the given object's properties shallowly, using Object.assign

Kind: global function
Returns: the cloned object

Param	Description
obj	the object to clone

circularClone()

Source: stackoverflow http://bit.ly/2A1Kha6

Kind: global function

dereference(o) ⇒

dereferences the given object

Kind: global function
Returns: the dereferenced object
Definitions: a source of definitions to reference
Options: optional settings (used recursively)

Param	Description
o	the object to dereference

flatten(obj, callback) ⇒

flattens an object into an array of properties

Kind: global function
Returns: the flattened object as an array of properties

Param	Description
obj	the object to flatten
callback	a function which can mutate or filter the entries (by returning null)

jpescape(s) ⇒

escapes JSON Pointer using ~0 for ~ and ~1 for /

Kind: global function
Returns: the escaped string

Param	Description
s	the string to escape

jpunescape(s) ⇒

unescapes JSON Pointer using ~0 for ~ and ~1 for /

Kind: global function
Returns: the unescaped string

Param	Description
s	the string to unescape

jptr(obj, prop, newValue) ⇒

from obj, return the property with a JSON Pointer prop, optionally setting it to newValue

Kind: global function
Returns: the found property, or false

Param	Description
obj	the object to point into
prop	the JSON Pointer or JSON Reference
newValue	optional value to set the property to

recurse(object, state, callback)

recurses through the properties of an object, given an optional starting state anything you pass in state.payload is passed to the callback each time

Kind: global function

Param	Description
object	the object to recurse through
state	optional starting state, can be set to null or
callback	the function which receives object,key,state on each property

reref(obj, options) ⇒

Simply modifies an object to have no self-references by replacing them with $ref pointers

Kind: global function
Returns: the re-referenced object (mutated)

Param	Description
obj	the object to re-reference
options	may contain a prefix property for the generated refs

objToGraph(obj, containerName) ⇒

Takes an object and creates a graph of JSON Pointer / References

Kind: global function
Returns: the graph suitable for passing to toposort()

Param	Description
obj	the object to convert
containerName	the property containing definitions. Default: definitions

visit(obj, comparison, callbacks) ⇒

Given an expanded object and an optional object to compare to (e.g. its $ref'd form), will call the following functions:

• callbacks.before - lets you modify the initial starting state, must return it
• callbacks.where - lets you select a subset of properties, return a truthy value
• callbacks.filter - called for all selected properties, can mutate/remove (by setting to undefined)
• callbacks.compare - allowing the objects to be compared by path (i.e. for $ref reinstating)
• callbacks.identity - called on any object identity (previously seen) properties
• callbacks.selected - called for all selected/unfiltered properties, does not mutate directly
• callbacks.count - called at the end with the number of selected properties
• callbacks.finally - called at the end of the traversal

Kind: global function
Returns: the possibly mutated object

Param	Description
obj	the object to visit
comparison	optional object to compare to
callbacks	object containing functions as above

Result ⇒ Result

Try to get a topological sorting out of directed graph.

Kind: global typedef

Param	Type	Description
nodes	Object	A list of nodes, including edges (see below).

Properties

Name	Type	Description
sort	array	the sort, empty if not found
nodesWithEdges,	array	will be empty unless a cycle is found