{"id":20513947,"url":"https://github.com/webreflection/tag-params","last_synced_at":"2025-04-14T00:03:12.757Z","repository":{"id":65514037,"uuid":"272659444","full_name":"WebReflection/tag-params","owner":"WebReflection","description":"Transform a generic string into parameters suitable for template literals functions tags.","archived":false,"fork":false,"pushed_at":"2020-06-25T15:20:58.000Z","size":40,"stargazers_count":30,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-31T15:41:13.601Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebReflection.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":"2020-06-16T08:59:07.000Z","updated_at":"2024-04-18T10:04:46.000Z","dependencies_parsed_at":"2023-01-26T20:55:23.907Z","dependency_job_id":null,"html_url":"https://github.com/WebReflection/tag-params","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Ftag-params","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Ftag-params/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Ftag-params/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Ftag-params/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebReflection","download_url":"https://codeload.github.com/WebReflection/tag-params/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233828165,"owners_count":18736581,"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-11-15T21:14:01.628Z","updated_at":"2025-01-14T01:10:16.076Z","avatar_url":"https://github.com/WebReflection.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tag-params\n\n[![Build Status](https://travis-ci.com/WebReflection/tag-params.svg?branch=master)](https://travis-ci.com/WebReflection/tag-params) [![Coverage Status](https://coveralls.io/repos/github/WebReflection/tag-params/badge.svg?branch=master)](https://coveralls.io/github/WebReflection/tag-params?branch=master)\n\nTransform a generic string into parameters suitable for template literals functions tags.\n\n```js\nimport {params} from 'tag-params';\n// const {params} = require('tag-params');\n// \u003cscript src=\"//unpkg.com/tag-params\"\u003e\u003c/script\u003e\n\nconsole.log(\n  params('Random: ${Math.random()}!')\n);\n// [[\"Random: \", \"!\"], 0.3456787643]\n\nconsole.log(\n  params('Hello ${user}', {user: 'test'})\n);\n// [[\"Hello \", \"\"], \"test\"]\n\n// invoke tags through the returned parameters\ngenericTag(...params(content, namespace));\n```\n\n\n## API\n\nThere are 3 utilities exported by this module, so that accordingly with your import, you should get:\n\n  * `params`, the main utility, which parses and resolves _values_ in one go.\n  * `parse`, which returns a `{template, values}` object, with mapped \"_chunks_\" in the template, and the list of _values_ (interpolations/holes), where each value is a string.\n  * `partial`, which uses `parse` and returns a callback that will map new values through the optional `object` passed along.\n\n\n### params(content:string, object?:any) =\u003e [string[], ...any[]]\n\nIt's the \"_default_\" use case of this utility. It parses the `content` and returns a `[template, ...values]` _Array_ with values retrieved through the optional `object`. If no `object` is passed along, it simply evaluates interpolations as plain JavaScript.\n\nThis utility is a shortcut for a one-off `partial(content)(object)` call.\n\n\n### parse(content:string, transform?:function) =\u003e {template:string[], values:string[]}\n\nIt parses a string, and it uses the optional `transform` callback, which is _no-op_ as default, to assign each _value_ to the list of expected _values_.\n\nThe `transform` optional callback is specially useful when the interpolated content might contains _HTML_ normalized chars, such as `value =\u0026gt; stuff(value)` instead of `value =\u003e stuff(value)`, which is normal when the content is retrieved via `element.innerHTML`, as example.\n\nThe `template` property contains all chunks around `${...}` interpolations, while `values` contains all interpolations content as string.\n\n\n### partial(content:string, transform?:function) =\u003e (object?) =\u003e [string[], ...any[]]\n\nThis utility parses the `content` through an optional `transform`, and returns a _callback_ that accepts a new object each time.\n\nThis is particularly useful to avoid parsing the same template content over and over, and just update its interpolation _values_ through the optional `object`.\n\n```js\nimport {partial} from 'tag-params';\nconst update = partial('Hello ${user}!');\n\nconsole.log(update({user: 'First'}));\n// [[\"Hello \", \"!\"], \"First\"]\n\nconsole.log(update({user: 'Second'}));\n// [[\"Hello \", \"!\"], \"Second\"]\n\n// always true\nconsole.assert(\n  update({user: 'First'})[0] ===\n  update({user: 'Second'})[0]\n);\n```\n\nThe main advantage of this utility is that it parses the `content` and it creates the `template` _Array_ only **once**, meaning every template literal based library could benefit from it, using the uniqueness of the `template` to parse complex chunks of _HTML_, or anything else, once, enabling repeated updates at almost zero performance cost.\n\n\n\n## Use Cases\n\nThe most common/requested use case for this is likely landing templates on the page and use their content, [as shown in this CodePen example](https://codepen.io/WebReflection/pen/OJMRZow?editors=0010):\n\n```html\n\u003ctemplate id=\"list\"\u003e\n  \u003cul\u003e${items.map(function (item) {\n    return html`\u003cli\u003e${item.text}\u003c/li\u003e`;\n  })}\u003c/ul\u003e\n\u003c/template\u003e\n\u003cdiv id=\"app\"\u003e\u003c/div\u003e\n\n\u003cscript type=\"module\"\u003e\nimport {params} from '//unpkg.com/tag-params?module';\nimport {render, html} from '//unpkg.com/uhtml?module';\n\nrender(\n  document.getElementById('app'),\n  html(...params(\n    document.getElementById('list').innerHTML,\n    {\n      html,\n      items: [{text: 'first'}, {text: 'second'}]\n    }\n  ))\n);\n\u003c/script\u003e\n```\n\nThis works well with libraries such as [uhtml](https://github.com/WebReflection/uhtml#readme), [lighterhtml](https://github.com/WebReflection/lighterhtml#readme), or [hyperHTML](https://github.com/WebReflection/hyperHTML#readme), as well as any library based on template literals tags.\n\nHowever, this module can work with literally any possible template literal tag function, as these all share the same signature, hence will accept transformed chunks, as _template_, and the rest of the interpolations as _values_.\n\n\n## Caveats\n\nPlease note this module inevitably needs/uses `Function` to evaluate the code within a `with` statement, as there's no other way to evaluate interpolations through passed data.\n\nMoreover, the current interpolations parser is extremely rudimental, it simply skips extra `{` and `}` chars within the value, but it doesn't parse all possible JS syntax.\n\nThis means that if an interpolation contains a string such as `${\"breaking { char\"}` or `${\"breaking } char\"}` the result will break.\n\nThe good practice here is to pass strings via the `object`, instead of hard coding these within interpolations, as this won't likely get fixed any time soon (if ever).\n\n\n\n## Compatibility\n\nEvery JavaScript engine, either client, server, or IoT, that supports `string[index]` access, as I couldn't bother myself adding a slow and jurassic `string.charAt(index)` in the code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebreflection%2Ftag-params","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebreflection%2Ftag-params","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebreflection%2Ftag-params/lists"}