{"id":22645523,"url":"https://github.com/akmjenkins/unterpolate","last_synced_at":"2025-03-29T06:21:15.031Z","repository":{"id":43983650,"uuid":"244508100","full_name":"akmjenkins/unterpolate","owner":"akmjenkins","description":"Map any value/template combination containing interpolations to an object (and back!)","archived":false,"fork":false,"pushed_at":"2023-01-05T08:53:10.000Z","size":1369,"stargazers_count":2,"open_issues_count":15,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-03-24T06:02:54.358Z","etag":null,"topics":["flat","interpolate","interpolation","map","object-mapping","transformations","transforms"],"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/akmjenkins.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":"2020-03-03T00:47:49.000Z","updated_at":"2021-08-20T22:18:32.000Z","dependencies_parsed_at":"2023-02-03T21:31:38.900Z","dependency_job_id":null,"html_url":"https://github.com/akmjenkins/unterpolate","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/akmjenkins%2Funterpolate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akmjenkins%2Funterpolate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akmjenkins%2Funterpolate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akmjenkins%2Funterpolate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akmjenkins","download_url":"https://codeload.github.com/akmjenkins/unterpolate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246145605,"owners_count":20730593,"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":["flat","interpolate","interpolation","map","object-mapping","transformations","transforms"],"created_at":"2024-12-09T06:06:18.884Z","updated_at":"2025-03-29T06:21:15.016Z","avatar_url":"https://github.com/akmjenkins.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# unterpolate\n\nUnterpolate is used to map a template (`string`, `array`, `object`) and value to an object representation **and back again**.\n\n```js\nimport { to, from } from 'unterpolate';\n\nconst template = '{year}-{month}-{day}';\nconst interpolated = '2019-10-01';\n\nto(template,interpolated) \n/*\n{\n    year:'2019',\n    month:'10',\n    day:'01'\n}\n*/\n\nfrom(template,{\n    year:'2019',\n    month:'10',\n    day:'01'\n});\n\n// '2019-10-01'\n```\n\n## Installation\n\nSame as usual, npm:\n```\nnpm install unterpolate\n```\n\nor yarn:\n```\nyarn add unterpolate\n```\n\n## Usage\n\nInterpolations are ubiquitous, from the first templating engines, to internationalization, etc.\n\nInterpolations don't have to just work for creating strings, however. With the right tools, it can be used to create more complex data transformations, which is the purpose of `unterpolate`.\n\n### simple string mapping\n\nIn addition to simple string mapping (see the first `to`/`from` example) `unterpolate` supports nested transformations care of [flat](https://www.npmjs.com/package/flat) and [property-expr](https://www.npmjs.com/package/property-expr).\n\n```js\nimport { to, from } from 'unterpolate';\n\n\nconst template = '{first.second}-{first.third}-something-{first.fifth.0}';\nconst interpolated = '2019-10-something-01';\n\nto(template,interpolated) \n\n/*\n{\n    first: {\n        second:'2019',\n        third:'10',\n        fifth:['01']\n    }\n}\n*/\n\nfrom(template,{\n    first: {\n        second:'2019',\n        third:'10',\n        fifth:['01','02','03','04'] // extraneous values will be ignored\n    }\n});\n\n// '2019-10-something-01'\n\n\n```\n\n### complex object/array mapping\n\nWe don't only `interpolate` an object's values to a string, we can interpolate them into a complex structure:\n\n#### interpolated value is an array\n\n```js\nconst template = ['{first}','{second.first}','{third}-something'];\nconst interpolated = [['an','array'],20,'somestring-something'];\n\nto(template,interpolated);\n/*\n{\n    first: ['an','array'],\n    second: {\n        first:20\n    },\n    third: 'somestring'\n}\n*/\n\n// and magically...\n\nfrom(template,{\n    first:{\n        first:'a',\n        second:'b',\n    },\n    second: {\n        first:['an','array']\n    },\n    third:'must be a string'\n});\n\n/*\n[\n    {\n        first:'a',\n        second:'b'\n    },\n    ['an','array'],\n    'must be a string-something'\n]\n*/\n\n```\n\n#### interpolated value is an object\n\n```js\nconst template = {\n    first:'{someKey}',\n    second: {\n        third: '{first.first.0}'\n    },\n    fourth:[\n        'key1', // no { }\n        '{key1}',\n        '{first.second}'\n    ]\n}\n\nconst interpolated = {\n    first:'something',\n    second: {\n        third: ['joe']\n    },\n    fourth: [\n        'key1',\n        'tom',\n        'bill'\n    ]\n}\n\nto(template,interpolated);\n/*\n{\n    someKey:'something',\n    first: {\n        first:['joe'],\n        second:'bill'\n    },\n    key1:'tom',\n}\n*/\n\n\n```\n\n### in/unterpolating using a function\n\nTruth be told, `unterpolate` was created to be able to do transformations through configuration which, under the circumstances in which it was developed,  generally meant \"through strings\".\n\nFor full flexibility, `unterpolate` does support using a function to perform `interpolations` and their reverse operations.\n\nThe function receives the the `value` being in/unterpolated and the options given to the `to/from` function with a key of `how` whose value is either `to` or `from`.\n\nNote: If `to` the return value from the function **must be false-y or an object** - anything else will throw an error.\n\n```js\nimport { to, from } from 'unterpolate';\n\nconst template = {\n    first: (val, opts) =\u003e opts.how === 'to' ? { prop: val / 2 } : val['prop'] * 2\n};\n\nconst value = {\n    first: 20,\n};\n\nconst expected = {\n    prop: 10,\n};\n\nto(template,value); // { prop: 10 }\nfrom(template,expected); // { first: 20 }\n```\n\n### `match` regexp\n\nThe default `RegExp` that determines what is an interpolation is `/\\{(.+?)\\}/g` - or **anything enclosed in curly braces** - i.e. `{first}`.\n\nAn object is created out of the matched strings which is then [unflattened](https://www.npmjs.com/package/flat#unflattenoriginal-options) to create non-trivial structures.\n\nYou can pass a different `match` regexp, if it suits your purposes, to `to` and `from` like so:\n\n```js\n\nconst template = '$year$-$month$-$day$'\nto(template,'2019-10-01',{match:/\\$(.+?)\\$/g})\n\n/*\n{\n    year:'2019',\n    month:'10',\n    day:'01'\n}\n*\n\n```\n\n## API\n\n### `to(template: string | function | object | array, value: any, options: {match: RegExp}): Uninterpolated Object`\n\nThe `to` method is what creates the uninterpolated object from the template and value.\n\n### `from(template: string | function | object | array, value: object, options: {match: RegExp}): Interpolated Value`\n\nThe `from` method is what creates the interpolated value from the object","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakmjenkins%2Funterpolate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakmjenkins%2Funterpolate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakmjenkins%2Funterpolate/lists"}