roam

    0.3.0 • Public • Published

    Roam

    Build Status Code Climate Test Coverage

    XPath-like queries and in-place transformations for JSON documents.

    Install

    npm install --save roam
    

    or

    bower install --save roam
    

    In the browser, Roam can be used with or without RequireJS.

    The basics

    Given the following JSON:

    {
      "menu": {
        "id": "file",
        "value": "File",
        "popup": {
          "menuitem": [
            {"value": "New", "onclick": "CreateNewDoc()"},
            {"value": "Open", "onclick": "OpenDoc()"},
            {"value": "Close", "onclick": "CloseDoc()"}
          ]
        }
      }
    }

    All of the following, in order of best to worst performance:

    roam(json).get('menu.popup.menuitem.onclick')
    roam(json).get('*popup.menuitem.onclick')
    roam(json).get('*menuitem.onclick')
    roam(json).get('*onclick')

    Will return:

    [
      "CreateNewDoc()",
      "OpenDoc()",
      "CloseDoc()"
    ]

    Roam

    • roam({Object|String})

    Construct a roam object by wrapping a JSON object or string.

    Search

    Search-methods locate and return values based on a given path. Path segments are separated by periods.

    Get

    • .get({String})

    .get traverses the document and returns an array of matching values.

    roam(json).get('menu.id') returns ["file"]

    One

    • .one({String})

    .one immediately returns the first matched property.

    roam(json).one('*menuitem.onclick') returns "CreateNewDoc()"

    Recursive queries

    You can prefix any property with * to have roam search the document (or current result set) recursively for a matching value.

    roam(json).get('*value') returns ["File", "New", "Open", "Close"]

    but

    roam(json).get('menu.popup.*value') returns ["New", "Open", "Close"]

    If the first segment is a recursive query, roam will traverse the entire document. If at all possible, try to narrow down the search area before going recursive.

    Arrays

    You can also ask for values at specific array indexes. All of these:

    roam(json).get('menu.popup.menuitem.1')
    roam(json).get('*popup.menuitem.1')
    roam(json).get('*menuitem.1')

    Will return:

    [
      {
        "value": "Open",
        "onclick": "OpenDoc()"
      }
    ]

    Transform

    • .transform({String}, {Function(value)})

    .transform traverses the document, replaces matching values with the return value of the callback, and returns the document in its entirety.

    roam(json).transform('*value', function(value) {
      return value.toUpperCase();
    });

    Returns:

    {
      "menu": {
        "id": "file",
        "value": "FILE",
        "popup": {
          "menuitem": [
            {"value": "NEW", "onclick": "CreateNewDoc()"},
            {"value": "OPEN", "onclick": "OpenDoc()"},
            {"value": "CLOSE", "onclick": "CloseDoc()"}
          ]
        }
      }
    }

    Or, a slightly sillier example:

    roam(json).transform('menu.popup.menuitem.value', function(value) {
      return value.split("").map(function(letter, index) {
        return {
          letter: letter,
          index: index
        };
      });
    });

    Returns:

    {
       "menu":{
          "id":"file",
          "value":"File",
          "popup":{
             "menuitem":[
                {
                   "value":[
                      {
                         "letter":"N",
                         "index":0
                      },
                      {
                         "letter":"e",
                         "index":1
                      },
                      {
                         "letter":"w",
                         "index":2
                      }
                   ],
                   "onclick":"CreateNewDoc()"
                },
                {
                   "value":[
                      {
                         "letter":"O",
                         "index":0
                      },
                      {
                         "letter":"p",
                         "index":1
                      },
                      {
                         "letter":"e",
                         "index":2
                      },
                      {
                         "letter":"n",
                         "index":3
                      }
                   ],
                   "onclick":"OpenDoc()"
                },
                {
                   "value":[
                      {
                         "letter":"C",
                         "index":0
                      },
                      {
                         "letter":"l",
                         "index":1
                      },
                      {
                         "letter":"o",
                         "index":2
                      },
                      {
                         "letter":"s",
                         "index":3
                      },
                      {
                         "letter":"e",
                         "index":4
                      }
                   ],
                   "onclick":"CloseDoc()"
                }
             ]
          }
       }
    }

    Map

    • .map({String}, {Function(value, index, array)})

    .map is a convenience method, equivalent to running .map or _.map on the returned array from a .get. Roam's .map is significantly faster than JavaScript's native .map, and roughly equivalent to lodash's _.map. For details on how a map function works, see the documentation for map.

    roam(json).map('*value', function(val) {
      return val.toUpperCase();
    });

    Returns:

    [
      "FILE",
      "NEW",
      "OPEN",
      "CLOSE"
    ]

    Filter

    • .filter({String}, {Function(value, index, array)})

    .filter is a convenience method in the same vein as map, and shares its performance characteristics. For details on how a filter function works, see the documentation for filter.

    roam(json).filter('*value', function(val) {
      return val.slice(-1) === 'e';
    });

    Returns:

    [
      "File",
      "Close"
    ]
    A note on map and filter

    Neither map nor filter support binding a custom value to this within the callback.

    Utilities

    Count

    • .count({String})

    .count is a wrapper around .get and will return the number of matched elements.

    Has

    • .has({String})

    .has is a wrapper around .one and will return true or false depending on whether a match could be found.

    Install

    npm i roam

    DownloadsWeekly Downloads

    1

    Version

    0.3.0

    License

    MIT

    Last publish

    Collaborators

    • ketilovre