{"id":17130047,"url":"https://github.com/serkanyersen/jsonplus","last_synced_at":"2025-04-13T05:34:40.871Z","repository":{"id":36051410,"uuid":"40349304","full_name":"serkanyersen/jsonplus","owner":"serkanyersen","description":"JSON parser that supports self reference and comments","archived":false,"fork":false,"pushed_at":"2018-06-29T20:21:05.000Z","size":42,"stargazers_count":90,"open_issues_count":3,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-26T23:03:38.246Z","etag":null,"topics":["comment","helper","json","json-files","json-parser","npm","plugin","reference-resolver","self-referential-association","utilities"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/serkanyersen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-07T08:14:11.000Z","updated_at":"2024-11-30T05:46:25.000Z","dependencies_parsed_at":"2022-09-01T18:52:06.497Z","dependency_job_id":null,"html_url":"https://github.com/serkanyersen/jsonplus","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serkanyersen%2Fjsonplus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serkanyersen%2Fjsonplus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serkanyersen%2Fjsonplus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serkanyersen%2Fjsonplus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serkanyersen","download_url":"https://codeload.github.com/serkanyersen/jsonplus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248262381,"owners_count":21074295,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["comment","helper","json","json-files","json-parser","npm","plugin","reference-resolver","self-referential-association","utilities"],"created_at":"2024-10-14T19:11:19.552Z","updated_at":"2025-04-13T05:34:40.461Z","avatar_url":"https://github.com/serkanyersen.png","language":"JavaScript","readme":"# JSONPlus\na JSON parser that supports comments and self references\n\n[![Build Status](https://travis-ci.org/serkanyersen/jsonplus.svg?branch=master)](https://travis-ci.org/serkanyersen/jsonplus) [![npm](https://img.shields.io/npm/v/jsonplus.svg)](https://www.npmjs.com/package/jsonplus) [![License](https://img.shields.io/npm/l/jsonplus.svg)](https://github.com/serkanyersen/jsonplus#mit-license)\n[![TypeScript definitions on DefinitelyTyped](http://definitelytyped.org/badges/standard-flat.svg)](https://github.com/serkanyersen/jsonplus/blob/master/jsonplus.d.ts)\n\n## Usage\nInstall using npm\n```\nnpm install --save-dev jsonplus\n```\n\nIt's really simple\n```javascript\nvar jsonplus = require('jsonplus');\n\n// Parse like you would with JSON.parse\nvar response = jsonplus.parse('{\"foo\": 5, \"bar\": \"@self.foo\"}');\n\nconsole.log(response); // { foo: 5, bar: 5 }\n```\n\njsonplus 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.\n\n## Self referencing\nSelf 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`\n\n## Template tags\nYou 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 :)\n\nExample:\n```JSON\n{\n  \"first\": \"john\",\n  \"last\": \"doe\",\n  \"full\": \"{{ first }} {{ last }}\"\n}\n```\nIf 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.\n\n**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.\n\n## External File References\nYou can also make references to external files. JSONPlus will fetch those files and allow you to share values between json files.\n\n```javascript\n{\n  // @ext means external\n  \"@ext\": {\n    // Value of `users` will be replaced with the contents of users.json\n    \"users\": \"/path/to/users.json\"\n  },\n  // Reach the values of external file using @ext prefix\n  \"name\": \"@ext.users[1].name\"\n}\n```\n\n**Notes on external files**:\n - External references can only work on direct objects. json strings that starts with an array ie,`[{ \"my\": \"json\" }]` cannot reference to external files.\n - File paths are relative to where your script is running, *not* to the JSON file.\n - If you reference a file that references to your file back, you'll end up in infinite loop.\n\n## Resolve function\nAdditionally, 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\n\n```javascript\nvar resolve = require('jsonplus').resolve\n\n// This will resolve all reference strings on the given object\nvar object = resolve(AlreadyParsedJSON);\n\n// resolve has a second argument, which provides the context for references\nvar object = resolve({ full: '{{ first }} {{ last }}' }, { first: 'john', last: 'doe' });\n\nconsole.log(object) // { full: 'john doe' }\n```\n\n## A complex example\n```javascript\n{\n  // Get all users\n  \"/api/users\": {\n    // Mock response\n    \"response\": {\n      \"users\": [{\n        \"name\": \"john doe\"\n      }, {\n        \"name\": \"jane doe\"\n      }]\n    }\n  },\n\n  // Get individual user\n  \"/api/user/1\": {\n    // Get already defined user from users mock\n    \"response\": \"@self['/api/users'].response.users[0]\"\n  },\n\n  // Get individual user\n  \"/api/user/2\": {\n    // Get already defined user from users mock\n    \"response\": \"@self['/api/users'].response.users[1]\"\n  }\n}\n```\nIt's quite self explanatory. As you can see it makes things a lot more clearer and shorter.\n\n## Why?\nSelf 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.\n\n## MIT License\n```\nCopyright (c) 2015 Serkan Yersen\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserkanyersen%2Fjsonplus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserkanyersen%2Fjsonplus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserkanyersen%2Fjsonplus/lists"}