{"id":20471367,"url":"https://github.com/statewalker/statewalker-utils-dom","last_synced_at":"2025-10-13T04:10:26.654Z","repository":{"id":57940260,"uuid":"529309358","full_name":"statewalker/statewalker-utils-dom","owner":"statewalker","description":null,"archived":false,"fork":false,"pushed_at":"2023-05-07T14:32:41.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-11T17:34:50.269Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statewalker.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-26T15:23:57.000Z","updated_at":"2022-08-26T15:26:55.000Z","dependencies_parsed_at":"2025-01-16T02:21:28.862Z","dependency_job_id":"c3f2248f-e36c-4b1f-b24e-bfb0612f4a81","html_url":"https://github.com/statewalker/statewalker-utils-dom","commit_stats":{"total_commits":23,"total_committers":1,"mean_commits":23.0,"dds":0.0,"last_synced_commit":"8edc2f139167853f5b89bd1cc75bbaa6a2f0e037"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/statewalker/statewalker-utils-dom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fstatewalker-utils-dom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fstatewalker-utils-dom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fstatewalker-utils-dom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fstatewalker-utils-dom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statewalker","download_url":"https://codeload.github.com/statewalker/statewalker-utils-dom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statewalker%2Fstatewalker-utils-dom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013591,"owners_count":26085389,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-15T14:15:54.992Z","updated_at":"2025-10-13T04:10:26.598Z","avatar_url":"https://github.com/statewalker.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @statewalker/utils-dom: DOM Utilities\n\nThis package contains the following DOM utilities used in other packages:\n* `bindView(iterator, action, options)` - creates and returns a DOM element which is updated each time when the given iterator returns a new value\n* `getElementInvalidation(element)` - returns a Promise instance associated with the given DOM element; the returned promise is resolved when the element is removed from the DOM tree \n* `replaceDomContent(element, node)` - replaces the content of the given DOM element by the given DOM node (element or text node).\n* `trackDomNode(node, { onAdd, onRemove, getContainer })` - tracks the node and calls the specified onAdd/onRemove methods when the node is attached/removed from the DOM\n* `toDomNode(value, doc)` - transforms the given JavaScript value to a DOM node; text, numbers and boolean values are tranformed to Text instances; objects are serialized (with the JSON.stringify method) and also transformed to Text instances; DOM nodes are returned \"as is\", without modifications.\n\n## `getElementInvalidation(element)`\n\nThis method returns a Promise instance associated with the given DOM element; the returned promise is resolved when the element is removed from the DOM tree.\n\nThis method returns a single Promise instance for the specific DOM element. This Promise is stored in the `invalidation` field of the element.\n\n\n```javascript\n\nconst div = document.createElement(\"div\");\ndocument.body.appendChild(div);\n\n// Get the invalidation promise associated with the given element:\nconst invalidation = getElementInvalidation(div);\n...\n// This function is called when the DOM element is detached from the DOM tree:\nconst onDetach = () =\u003e console.log('The element was detached from DOM...');\ninvalidation.then(onDetach);\n\n// Check that the second time this method returns the same invalidation instance:\nconst invalidation2 = getElementInvalidation(div);\nassert(invalidation === invalidation2);\n\n// Shows this message:\n// 'The element was detached from DOM...'\n```\n\n\n## `bindView(iterator, action, options)`\n\nThis utility function allows to update HTML elements when the specified iterator yields a new value.\nIt also allows to easily initialize the element and cleanup associated resources when this element is detached from DOM.\n\n\n```javascript\nconst elm: Element = bindView(\n  // Async iterator returning new values to visualize:\n  iterator : AsyncIterator,\n\n  // The function returning the element\n  action : Function,\n\n  // Optional parameters:\n  options : Object = {\n    // Function used to handle errors\n    handleError = console.error,\n\n    // This function returns the root element to listen\n    getRoot\n    \n  } : object = {}\n)\n```\n\nThe `action(...)` callback method recieves the following structure:\n* `params` : parameters object\n* `params.init` - sets the initialization function; it is called when the view is attached to the DOM\n* `params.done` - sets the finalization function which is called when the view is removed from the DOM\n* `params.update` - sets a new function to call on each value update; the function defined with the `update` method has the following signature: `(view, value, oldValue) =\u003e { ... }`\n\nExample 1: in this example the activation method registers only one method to init/done/update the created view.\n```javascript\nimport { bindView } from '@statewalker/utils-dom'\n\n// Generate a new sequence of values to update\n// (see below for the implementation of the \"generateValues\" method):\nconst it = generateValues(50, 2000);\n\n// Create a new view to append to the document.\nconst view = bindView(it, ({ init, update, done }) =\u003e {\n  // View initialization:\n  init((view) =\u003e view.innerHTML = \"Initializing...\");\n  // Destroys the view and cleans up all associated resources:\n  done((view) =\u003e view.innerHTML = \"Destroying...\");\n  // This method is called each time when the iterator returns a new value:\n  update((view, value, oldValue) =\u003e {\n    view.innerText = `Counter: ${value}!`;\n  })\n  // Create and returns the view to update:\n  return document.createElement(\"div\");\n})\n\n// Append the resulting view to the document:\ndocument.body.appendChild(view);\n```\n\n\nExample 2: in this example the activation method registers two methods\nfor each of the \"init/done/update\" stages:\n```javascript\nimport { bindView } from '@statewalker/utils-dom'\n\n// Generate a new sequence of values to update:\n// (see below for the implementation of the \"generateValues\" method):\nconst it = generateValues(50, 2000);\n\n// In this example the activation function registers two callbacks \n// for each of the \"init/update/done\" stages:\n// - one method changes the conntent of the view\n// - the second method prints some messages in the log\nconst div = bindView(it, ({ init, update, done }) =\u003e {\n  \n  // View initialization:\n  init((view) =\u003e view.innerHTML = \"Initializing...\");\n  // The second function to call on the view initialization:\n  init(() =\u003e console.log(\"Init.\"))\n  \n  // Destroys the view and cleans up all associated resources:\n  done((view) =\u003e view.innerHTML = \"Destroying...\");\n  // The second method to call on initialization:\n  done(() =\u003e console.log(\"Done.\"))\n\n  // This method is called each time when the iterator returns a new value:\n  update((view, value, oldValue) =\u003e {\n    view.innerText = `Counter: ${value}!`;\n  })\n  // Print the values returned by the iterator:\n  done((view, newValue, oldValue) =\u003e console.log(\"- Update:\", { oldValue, newValue }));\n\n  // Create and returns the view to update:\n  return document.createElement(\"div\");\n})\n// Append the resulting view to the document:\ndocument.body.appendChild(div);\n\n```\n\nThe `generateValues` method used in the examples above:\n```javascript\n// This function generates values used to update the view\nasync function* generateValues(count = 100, maxTimeout = 1000) {\n  for (let i = 0; i \u003c count; i++) {\n    yield i;\n    await new Promise(r =\u003e setTimeout(Math.random() * maxTimeout));\n  }\n}\n\n```\n\n## `replaceDomContent(element, node)` \n\nThis method replaces the content of the given DOM element by the given DOM node (element or text node).\n\nExample:\n```javascript\nimport { replaceDomContent } from '@statewalker/utils-dom'\n\nconst root = document.querySelector(\"#root\");\n\nconst div = document.createElement(\"div\");\ndiv.innerText = 'Hello, world';\nreplaceDomContent(root, div);\n\n```\n\n## `trackDomNode(node, { onAdd, onRemove, getContainer })`\n\nThis method tracks the node and calls the specified onAdd/onRemove methods when the node is attached/removed from the DOM.\n\nParameters: \n* `node` - the DOM node to track\n* `params` - an object containing method parameters\n* `params.onAdd` - an optional callback method invoked after the node is attached to DOM; it takes the node as the single parameter\n* `params.onRemove` - an optional callback method invoked when the node is removed from DOM; it recieves two parameters: the node itself and a boolean flag showing if the node was notified as attached or not (if the onAdd method was called before)\n* `params.getContainer` - returns the container to track for the specified node\n\n\n## `toDomNode(value, doc)`\n\nThis method transforms the given JavaScript value to a DOM node; text, numbers and boolean values are tranformed to Text instances; objects are serialized (with the JSON.stringify method) and also transformed to Text instances; DOM nodes are returned \"as is\", without modifications.\n\nExample:\n```javascript\nimport { toDomNode } from '@statewalker/utils-dom'\n\nconst root = document.querySelector(\"#root\");\n\n// Transforms string a Text instance:\nroot.appendChild(toDomNode(\"Hello, world\")) \n\n// Transforms the given number to a Text instance:\nroot.appendChild(toDomNode(12345)) \n\n// Returnes the DOM node without modifications: \nconst h3 = toDomNode(document.createElement(\"h3\"));\nh3.innerHTML = \"Hello, there!\"\nroot.appendChild(h3)\n\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatewalker%2Fstatewalker-utils-dom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatewalker%2Fstatewalker-utils-dom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatewalker%2Fstatewalker-utils-dom/lists"}