{"id":16884384,"url":"https://github.com/tornqvist/jazzon","last_synced_at":"2025-03-22T08:30:34.829Z","repository":{"id":57279741,"uuid":"42856897","full_name":"tornqvist/jazzon","owner":"tornqvist","description":"Add some jazz to your JSON files","archived":false,"fork":false,"pushed_at":"2015-10-30T10:24:12.000Z","size":168,"stargazers_count":36,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-18T09:45:00.449Z","etag":null,"topics":["javascript","json","mocking","nodejs"],"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/tornqvist.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-09-21T09:31:02.000Z","updated_at":"2025-03-17T13:45:58.000Z","dependencies_parsed_at":"2022-09-11T18:13:48.732Z","dependency_job_id":null,"html_url":"https://github.com/tornqvist/jazzon","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tornqvist%2Fjazzon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tornqvist%2Fjazzon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tornqvist%2Fjazzon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tornqvist%2Fjazzon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tornqvist","download_url":"https://codeload.github.com/tornqvist/jazzon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244227554,"owners_count":20419259,"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":["javascript","json","mocking","nodejs"],"created_at":"2024-10-13T16:27:43.772Z","updated_at":"2025-03-22T08:30:34.403Z","avatar_url":"https://github.com/tornqvist.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jazzon\n\nWorking with static JSON files for mocking data or whatever other purposes can be a real bore. Jazzon is a convenience utility for generating, concatenating and streamlining the handling of static JSON files.\n\n## Installation\n\n```bash\n$ npm install --save jazzon\n```\n\n## Usage\n\nIn and of it self jazzon does nothing, *really*. It's sole purpose is to call registered plugins with the current state and identified helpers. Helpers can be chained passing the current state from one to the next.\n\nTo illustrate a most basic scenario, this is how one might use jazzon together with [jazzon-uuid](https://github.com/tornqvist/jazzon-uuid)\n\n```javascript\nconst jazzon = require('jazzon');\nconst uuid = require('jazzon-uuid');\n\nlet data = { id: \"@{ uuid }\" };\n\njazzon.use(uuid());\n\njazzon\n  .compile(data)\n  .then(result =\u003e console.log(result)); // =\u003e {id: \"6c84fb90-12c4-11e1-840d-7b25c5ee775a\"}\n```\n\nIn this scenario, jazzon encounters the helper `uuid` and calls each registered plugin (in this case `jazzon-uuid`) on it.\n\nHelpers can also be chained using the pipe (`|`) symbol. Each chained helper gets the output (state) of the previous helper to operate on. To illustrate a more complex scenario, take these two models:\n\n```javascript\n// user.json\n\n{\n  \"id\": \"@{ uuid }\",\n  \"name\": \"@{ name.findName }\",\n  \"email\": \"@{ internet.email }\",\n  \"username\": \"@{ internet.userName }\"\n}\n```\n\n```javascript\n// users.json\n\n{\n  \"total\": 3,\n  \"users\": \"@{ import(user.json) | pick(id, username) | repeat(3) }\"\n}\n```\n\nRunning `users.json` through jazzon would produce something like this:\n\n```javascript\n{\n  \"total\": 3,\n  \"users\": [{\n    \"id\": \"a76f535f-cbc6-4c09-8151-573e200c1dbf\",\n    \"username\": \"Doug.Simonis28\"\n  }, {\n    \"id\": \"0a512648-c418-40a6-90ac-1bb5ef1e7fab\",\n    \"username\": \"Virgil_Kunze\"\n  }, {\n    \"id\": \"88d6903f-d13b-4d16-877e-f906461c69aa\",\n    \"username\": \"Grady.Koelpin\"\n  }]\n}\n```\n\n## Syntax\n\nThe syntax of helpers are very similar to [JavaScript template strings](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/template_strings) to clearly illustrate their purpose. But do not confuse them as the pipe separator is not a valid JavaScript operator.\n\nThe string must start with `@{` and end with `}`. Each helper is separated with a `|` symbol. Encountering an invalid template-ish string will throw an error.\n\nUse [this regexr](http://regexr.com/3bsnl) to experiment with the template strings.\n\n## Plugins\n\nPlugins should export a function that get's called once for every helper encountered by jazzon. The convention is to export a factory function that returns the plugin.\n\nA plugin really is just a reducer that jazzon uses to process all the helpers. Therefore a plugin should *always* return a state, even if it does not manipulate the state. A switch statement does the job as so:\n\n```javascript\n// myplugin.js\n\nmodule.exports = function (otions) {\n  return function (state, helper, args) {\n    switch (helper) {\n    case 'name':\n      return args[0] || options.default;\n    case 'wrap':\n      return `Hello ${ state }!`;\n    default:\n      return state;\n    }\n  }\n};\n```\n\n```javascript\n// myprogram.js\n\njazzon\n  .use(myplugin({\n    default: 'world'\n  }))\n  .compile({\n    \"first\": \"@{ name | wrap }\",\n    \"second\": \"@{ name(Joe) | wrap }\"\n  })\n  .then(result =\u003e console.log(result)); // =\u003e {\"first\": \"Hello world!\", \"second\": \"Hello Joe!\"}\n```\n\nJazzon also supports async plugins. Under the hood, jazzon is using [co](https://github.com/tj/co) so anything that co can handle, jazzon can handle. As so, other than just plain strings, a plugin may return a Promise, generator, generator function, function, object or array. Due to the awesome nature of co, objects and arrays may contain nestled objects/arrays containing Promises or any of the other supported types. See some of the plugins for examples of how this is achieved.\n\n### Availible plugins\n\n- [jazzon-uuid](https://github.com/tornqvist/jazzon-uuid) *Generates a UUID*\n- [jazzon-import](https://github.com/tornqvist/jazzon-import) *Import other files in place*\n- [jazzon-faker](https://github.com/tornqvist/jazzon-faker) *Generate fake data using faker*\n- [jazzon-lodash](https://github.com/tornqvist/jazzon-lodash) *Use some lodash goodness with jazzon*\n- [jazzon-repeat](https://github.com/tornqvist/jazzon-repeat) *Repeat given value n number of times*\n- [jazzon-format](https://github.com/tornqvist/jazzon-format) *Format strings using `util.format`*\n\nTo add your own plugin, add it to the list and make a pull request.\n\n## API\n\n- `jazon.create(/*plugins*/)` Creates a new instance of jazzon with optional list of plugins.\n  - *Returns jazzon*\n- `jazzon.use(plugin)` Adds a plugin to be used when transforming template strings.\n  - *Returns jazzon*\n- `jazzon.compile(object)` Iterates over the object looking for template strings to transform.\n  - *Returns a Promise*\n- `jazzon.plugins` An list of registered helpers on this instance.\n  - *Returns an Array*\n  - *Is immutable*\n\n## TODO\n\n- [x] Add documentation\n- [x] Add wrapper for non-Promises returned from plugins\n- [x] Add test for plugins (generator/non-generator)\n- [x] Better error handling\n- [ ] Add CLI\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftornqvist%2Fjazzon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftornqvist%2Fjazzon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftornqvist%2Fjazzon/lists"}