Nocturnal Pumpkin Maelstrom

    jsonplus

    1.2.1 • Public • Published

    JSONPlus

    a JSON parser that supports comments and self references

    Build Status npm License

    Usage

    Install using npm

    npm install --save-dev jsonplus
    

    It's really simple

    var jsonplus = require('jsonplus');
     
    // Parse like you would with JSON.parse
    var response = jsonplus.parse('{"foo": 5, "bar": "@self.foo"}');
     
    console.log(response); // { foo: 5, bar: 5 }

    jsonplus uses JSON.parse internally so there shouldn't be any performance impact. We only go through JSON object once to find the reference strings and replace them with actual values. The impact is minimal considering the gained value.

    Self referencing

    Self referencing only works on values at the moment. Values start with @self will be parsed as a reference. Think of @self as this; the rest of it is usual object navigation such as @self.foo.bar.list[1]. If a self reference cannot be found, it will be replaced with undefined

    Template tags

    You can also use template tags in the values, this is the same thing as self referencing but you can use multiple references in the same value. One of the advantages of having template tags is you can simply omit the @self prefix all together -- or keep using it it's up to you :)

    Example:

    {
      "first": "john",
      "last": "doe",
      "full": "{{ first }} {{ last }}"
    }

    If your JSON is a first level array you can use paths like this {{ [0].first }} or if you think it's more readable, {{ @self[0].first }} works as well.

    Note: Due to the nature of template tags, everything that passes through them will be converted to string, whereas @self notation can replace itself with whatever it is referencing.

    External File References

    You can also make references to external files. JSONPlus will fetch those files and allow you to share values between json files.

    {
      // @ext means external
      "@ext": {
        // Value of `users` will be replaced with the contents of users.json
        "users": "/path/to/users.json"
      },
      // Reach the values of external file using @ext prefix
      "name": "@ext.users[1].name"
    }

    Notes on external files:

    • External references can only work on direct objects. json strings that starts with an array ie,[{ "my": "json" }] cannot reference to external files.
    • File paths are relative to where your script is running, not to the JSON file.
    • If you reference a file that references to your file back, you'll end up in infinite loop.

    Resolve function

    Additionally, you can use the reference resolver directly. You might be parsing your JSON files with your own system i.e. streaming and you might only want to have the reference resolver. Here is an example

    var resolve = require('jsonplus').resolve
     
    // This will resolve all reference strings on the given object
    var object = resolve(AlreadyParsedJSON);
     
    // resolve has a second argument, which provides the context for references
    var object = resolve({ full: '{{ first }} {{ last }}' }, { first: 'john', last: 'doe' });
     
    console.log(object) // { full: 'john doe' }

    A complex example

    {
      // Get all users
      "/api/users": {
        // Mock response
        "response": {
          "users": [{
            "name": "john doe"
          }, {
            "name": "jane doe"
          }]
        }
      },
     
      // Get individual user
      "/api/user/1": {
        // Get already defined user from users mock
        "response": "@self['/api/users'].response.users[0]"
      },
     
      // Get individual user
      "/api/user/2": {
        // Get already defined user from users mock
        "response": "@self['/api/users'].response.users[1]"
      }
    }

    It's quite self explanatory. As you can see it makes things a lot more clearer and shorter.

    Why?

    Self referencing and comments in JSON files can be really useful while creating fixture files. I don't expect anyone to use this for production purposes. JSONPlus should help you create simpler fixtures with comments and can be also used for configuration files.

    MIT License

    Copyright (c) 2015 Serkan Yersen
    
    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
    

    Install

    npm i jsonplus

    DownloadsWeekly Downloads

    118

    Version

    1.2.1

    License

    MIT

    Last publish

    Collaborators

    • serkanyersen