{"id":13580079,"url":"https://github.com/joelvh/json2json","last_synced_at":"2025-04-06T05:17:32.468Z","repository":{"id":2031837,"uuid":"2968409","full_name":"joelvh/json2json","owner":"joelvh","description":"Transform (reformat) JSON structures from one to another using JavaScript","archived":false,"fork":false,"pushed_at":"2021-07-26T10:15:05.000Z","size":78,"stargazers_count":190,"open_issues_count":5,"forks_count":39,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-04-17T03:50:18.621Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"CoffeeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joelvh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-12-12T23:41:16.000Z","updated_at":"2024-03-08T00:46:11.000Z","dependencies_parsed_at":"2022-08-28T21:10:22.043Z","dependency_job_id":null,"html_url":"https://github.com/joelvh/json2json","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joelvh%2Fjson2json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joelvh%2Fjson2json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joelvh%2Fjson2json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joelvh%2Fjson2json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joelvh","download_url":"https://codeload.github.com/joelvh/json2json/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247436290,"owners_count":20938533,"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":[],"created_at":"2024-08-01T15:01:46.893Z","updated_at":"2025-04-06T05:17:32.441Z","avatar_url":"https://github.com/joelvh.png","language":"CoffeeScript","funding_links":[],"categories":["CoffeeScript","Transformations"],"sub_categories":[],"readme":"# About json2json [![Build Status](https://travis-ci.org/joelvh/json2json.svg?branch=master)](https://travis-ci.org/joelvh/json2json)\n\nTransforms one JSON object structure to another structure as defined by template rules.\nIdeal for transforming JSON retrieved from web services to be used the way you need it in your application.\n\n[json2json](https://github.com/joelvh/json2json) is written in [CoffeeScript](http://coffeescript.org) and designed to run in a [Node.js](http://nodejs.org) envirionment.\nIt can be easily converted to JavaScript to be used in a browser as well.\n\n# Tutorial\n\n## Template rules\n\nTemplate rules specify how the \"original JSON\" (raw data) is transformed to the \"new JSON\" format you need:\n\nA template specifies the **path** to the value on your original JSON you want to transform\nand assumes that value is either an object or an array.\nIf it's an object, you can **choose** which properties you want to transform.\nIf it's an array, you can **aggregate** the values you want to transform.\n\nSometimes you want to convert an array to a map (aka JSON object).\nTo do this, you can specify what value on your original JSON to use as the **key**.\nIf you want to make it a really simple map,\nyou can specify what value on your original JSON to use as the **value**.\n\nTemplates specify how the original JSON data will be represented **as** properties on the new JSON.\n(The only time the **as** rules are ignored is if the **value** rule exists\nwhen converting an array to a map.)\n\n## Describing the example template\n\n(Look at the \"[example](example)\" folder to see this [template](example/template.coffee) and the JSON [before](example/original.json) and [after](example/transformed.json) transformation.)\n\nA template specifies a set of rules that describe how to transform a property in your original JSON.\nA template itself is a javascript object.\nThis example is written in CoffeeScript and has comments to explain each property:\n\nThe template object is stored as the \"tmpl\" variable.\nThe template typically matches the root of the original JSON.\n\n    tmpl =\n\nThe \"path\" property specifies what property on the JSON object to process.\nThe '.' value specifies to use the root in this case.\nThe original JSON can be an array as well.\n\n      path: '.'\n\nThe \"aggregate\" property (optional) is used if you are processing an array.\nIt lets you process values of an array and combine them into one value or effectively filter an array.\nThe properties in the \"aggregate\" object are used as properties on your new JSON object.\nThe \"existing\" parameter sent to each aggregate function specifies a value if one exists on your new JSON object.\n\n      aggregate:  \n        total: (key, value, existing) -\u003e if !sysmo.isArray(value) then value else value.sort().reverse()[0]\n        pages: (key, value, existing) -\u003e if !sysmo.isArray(value) then value else value.sort().reverse()[0]\n\nThe \"as\" property lets you specify all the properties you want on your new JSON object.\n(These are the only properties that will be created on the new JSON object.)\nThis is where you define the mapping rules.\nIt is effectively a list of nested templates.\n\n      as:\n\nThe \"bins\" property is going to be created on your new JSON object.\nThe template defined for \"bins\" here is another set of rules that specify what property\non the original JSON object to transform.\n\n        bins:  \n\nThe \"path\" property was described previously.\nHowever, this time the path is relative to the value in the original JSON that was selected by the previous \"path\" (above).\nIt is possible to access properties of objects that are in an array.\nA flattened array of all values will be returned and used as the value to transform.\n\n          path: 'Items.SearchBinSets.SearchBinSet.Bin'\n\nThe \"key\" property indicates you want to convert an array to a map.\nThe \"key\" property lets you specify the property in the original JSON object to use as the key in the new map.\nThe value retrieved from the original JSON object will be converted to a string.\n(Alternatively, you can specify a function that is passed the original JSON value and returns a key to use.)\n\n          key: 'BinParameter.Value'\n\nThe \"value\" property (optional) lets you specify the property in the original JSON object to use as the value in the new map.\n(Alternatively, you can specify a function that is passed the original JSON value and returns a value to use.)\n\n          value: 'BinItemCount'\n\nThe \"aggregate\" property works the same as previously described, but instead of specifying a map of functions,\na single function is used to aggregate the array values being processed on the original JSON object.\n\n          aggregate: (key, value, existing) -\u003e Math.max(value, existing || 0)\n        items:  \n          path: 'Items.Item'\n\nThe \"all\" property specifies that all properties on the matched object in the original JSON object for which\nno rule has been defined should automatically be copied to the new JSON object.\n(By default, only the properties specified in the \"as\" template are created on the new JSON.)\nThe \"all\" option only works if \"choose\" is not defined (see below).\n\n          all: true\n          as:\n            title: 'ItemAttributes.Title'\n            price: 'Offers.Offer.OfferListing.Price.FormattedPrice'\n            similar:\n              path: 'SimilarProducts.SimilarProduct'\n              key: 'ASIN'\n              value: 'Title'\n            images:\n              path: '.'\n\nAny properties on the matched object that are null or undefined will not be copied to the new JSON object.\nTo include these properties set \"ignoreEmpty\" to false.\n\n          ignoreEmpty: false\n\nThe \"choose\" property defines an array of properties on the original JSON object to transform and skip the rest.\n\n              choose: ['SmallImage', 'MediumImage', 'LargeImage']\n\nThe \"format\" property defines a function that processes each of the values retrieved from the original JSON object\nand returns an object with \"key\" and \"value\" properties or an array which contains object(s) with \"key\" and \"value\" properties. If an array is returned, all entries in the array are added to the current context node in the new JSON.\nThis allows you to format the key and value however you wish.\n(If a \"key\" or \"value\" property is not returned, the original value is used.)\nThe \"node\" parameter to the format function is the object or array in the original JSON that is being transformed.\n(It is the object that contains the properties defined by the \"choose\" array.)\n\n              format: (node, value, key) -\u003e key: key.replace(/Image$/, '').toLowerCase()\n\nThe \"nested\" property indicates that the value of each property specified by \"choose\" should be a new object.\nThe properties defined in the \"as\" template below will be stored in the nested object instead of the object that the\n\"choose\" properties are created on.\n\n              nested: true\n              as:\n                url: 'URL'\n                height: 'Height.#'  \n                width: 'Width.#'\n            image_sets:\n              path: 'ImageSets.ImageSet'\n              key: '@.Category'\n\nThe \"choose\" property can be a function that returns a boolean.\nIn the previous \"choose\" example, an array of property names (e.g. map/hash \"keys\") were specified,\nwhich indicated what properties on the original JSON value to transform.\nTo provide more flexibility, a function can be used to dynamically choose which properties to transform.\n\n              choose: (node, value, key) -\u003e key isnt '@'\n              format: (node, value, key) -\u003e key: key.replace(/Image$/, '').toLowerCase()\n              nested: true\n              as:\n                url: 'URL'\n                height: 'Height.#'\n                width: 'Width.#'\n\nThe \"ensureArray\" property indicates that the matched property should be wrapped in an array if it is not already an array.\n\n              ensureArray: true\n\nTo convert an object into an array, the following properties must be specified\n\n              key: false\n              as: false\n              mapToArray: true\n\nThis will push all values of properties in the object into an array.\n\nTo select the keys whose values are pushed into the array, specify the keys in the \"choose\" property.\n\n              choose: ['SmallImage', 'MediumImage', 'LargeImage']\n\nIf the data you want to transform contains an array of objects and you want all the values pushed into a single array instead of nested arrays, specify the \"flatArray\" property.\n\n              flatArray: true\n\nAnd finally, create an instance of the \"ObjectTemplate\" object,\npassing the template to the constructor.\nThen call the \"transform\" method, passing it the data you want to transform.\n\n    new ObjectTemplate(tmpl).transform data\n\n## Overriding the default template rules\n\nThe default rules used when creating templates (and nested templates) can be overridden via \"TemplateConfig.defaults\":\n\n    TemplateConfig.defaults.ignoreEmpty = false\n\n# Using json2json in your browser\n\nYou can use the json2json library in your browser by converting the CoffeeScript files to JavaScript first.\nYou'll also need to include the [Sysmo.js](https://github.com/joelvh/Sysmo.js) dependency.\nInclude the files in this order (the [json2json.coffee](lib/json2json.coffee) file is not necessary):\n\n  1. [Sysmo.js](https://github.com/joelvh/Sysmo.js)\n  2. TemplateConfig.js (converted from [TemplateConfig.coffee](lib/TemplateConfig.coffee))\n  3. ObjectTemplate.js (converted from [ObjectTemplate.coffee](lib/ObjectTemplate.coffee))\n\nFrom there on out, you can define your template (see [template example](example/template.coffee)) and use the classes in your JavaScript code.\n\n## License\n\nCreated by Joel Van Horn. Free to use however you please.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoelvh%2Fjson2json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoelvh%2Fjson2json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoelvh%2Fjson2json/lists"}