{"id":26758759,"url":"https://github.com/1natsu172/wait-element","last_synced_at":"2025-04-15T05:57:19.514Z","repository":{"id":50457133,"uuid":"123768529","full_name":"1natsu172/wait-element","owner":"1natsu172","description":"Detect the appearance of an element in the browser DOM","archived":false,"fork":false,"pushed_at":"2025-04-13T14:54:24.000Z","size":453,"stargazers_count":14,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-15T05:57:12.045Z","etag":null,"topics":["dom-element","mutationobserver","npm-module","promise-api","queryselector","selector"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@1natsu/wait-element","language":"TypeScript","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/1natsu172.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-04T07:56:57.000Z","updated_at":"2025-04-13T10:58:31.000Z","dependencies_parsed_at":"2024-09-06T20:44:44.007Z","dependency_job_id":"fafd28cb-b82e-4582-a740-2004f9802617","html_url":"https://github.com/1natsu172/wait-element","commit_stats":{"total_commits":74,"total_committers":2,"mean_commits":37.0,"dds":"0.013513513513513487","last_synced_commit":"61736250709806d47e027cd029e785dff5041f41"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1natsu172%2Fwait-element","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1natsu172%2Fwait-element/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1natsu172%2Fwait-element/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1natsu172%2Fwait-element/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/1natsu172","download_url":"https://codeload.github.com/1natsu172/wait-element/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249016321,"owners_count":21198832,"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":["dom-element","mutationobserver","npm-module","promise-api","queryselector","selector"],"created_at":"2025-03-28T16:32:43.763Z","updated_at":"2025-04-15T05:57:19.497Z","avatar_url":"https://github.com/1natsu172.png","language":"TypeScript","readme":"# wait-element\n[![npm](https://img.shields.io/npm/v/@1natsu/wait-element.svg?style=for-the-badge)](https://www.npmjs.com/package/@1natsu/wait-element)\n![npm bundle size (minified)](https://img.shields.io/bundlephobia/min/@1natsu/wait-element.svg?style=for-the-badge)\n![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/@1natsu/wait-element.svg?style=for-the-badge)\n\n\n\u003e Detect the appearance of an element in the browser DOM\n\n## a.k.a promise-querySelector\n\n* Promise API\n* Driven by `MutationObserver`\n* Detect by `querySelecrtor`\n* Possible to abort with `AbortSignal`\n\nIf the target element already exists when execution of \"wait-element\", it immediately `resolve` and return the element.\n\n\n## Install\n\n```bash\nnpm install @1natsu/wait-element\n```\n```bash\nyarn add @1natsu/wait-element\n```\n```bash\npnpm add @1natsu/wait-element\n```\n```bash\nbun add @1natsu/wait-element\n```\n\n## Usage\n\n### Module specifiers\n\n```js\nimport { waitElement } from \"@1natsu/wait-element\";\n```\n\n#### Basically\n\n```js\nconst el = await waitElement(\".late-comming\");\nconsole.log(el);\n//=\u003e example: \"\u003cdiv class=\"late-comming\"\u003eI'm late\u003c/div\u003e\"\n```\n\n#### Specify parent target element (specify MutationObserve target)\n\n```js\nconst parent = await waitElement(\"#parent\");\nconst el = await waitElement(\".late-comming\", { target: parent });\nconsole.log(el);\n//=\u003e example: \"\u003cdiv class=\"late-comming\"\u003eI'm late\u003c/div\u003e\"\n```\n\n#### Setting timeout\n\n```js\nconst el = await waitElement(\".late-comming\", { signal: AbortSignal.timeout(1000) }).catch(err =\u003e console.log(err));\nconsole.log(el);\n//=\u003e If detected element: \"\u003cdiv class=\"late-comming\"\u003eI'm late\u003c/div\u003e\"\n//=\u003e If timeouted: DOMException: TimeoutError\n```\n\n#### Abort the waiting\n\n```js\ntry {\n\tconst waitAbortable = new AbortController();\n\n\tconst checkElement = waitElement(\".late-comming\", { signal: waitAbortable.signal });\n\n\twaitAbortable.abort(\"abort this time!\");\n\n} catch(error) {\n\t// After abort handling...\n}\n```\n\n#### Custom detect condition\n\n```js\nconst el = await waitElement(\"#animal\", {\n  detector: (element) =\u003e\n\t\telement?.textContent === \"Tiger\"\n\t\t\t? { isDetected: true, result: element }\n\t\t\t: { isDetected: false },\n});\nconsole.log(el.textContent);\n//=\u003e example: Tiger\n```\n\n```js\nimport { isNotExist } from \"@1natsu/wait-element/detectors\";\n\n// when resolve if “not exist” or “disappear” at the time of call\nconst result = await waitElement(\".hero\", { detector: isNotExist });\n//=\u003e result: null\n```\n\n#### Unify waiting process\n\nUnifies the process of finding an element. If set `true`, increases efficiency. Unify the same arguments(includes options) with each other.\n\n```js\nconst A = waitElement(\".late-comming\", {\n\tunifyProcess: true,\n});\n\nconst B = waitElement(\".late-comming\", {\n\tunifyProcess: true,\n});\n\nconst C = waitElement(\".late-comming\", {\n\tunifyProcess: true,\n\tsignal: AbortSignal.timeout(1000)\n});\n\nconst D = waitElement(\".late-comming\", {\n\tunifyProcess: false,\n});\n\n// Unified:\n// A === B\n// B !== C\n// B !== D\n```\n\n\n## API\n\n### waitElement(selector, [options])\n\n#### selector\n\nType: `string`\n\nFormat is [CSS-selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Introduction_to_CSS/Selectors)\n\n#### options\n\nPassed options is merged with default configs.\n\n[See TS definition for detailed information](https://github.com/1natsu172/wait-element/blob/master/src/options.ts)\n\n### createWaitElement(initOptions)\n\nCustom waitElement function can be created.\n\n## Similar\n\nThe very similar library.\n\n* [element-ready](https://github.com/sindresorhus/element-ready)\n  * Implementation method is different from this library.\n\n## License\n\nMIT © [1natsu172](https://github.com/1natsu172)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1natsu172%2Fwait-element","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F1natsu172%2Fwait-element","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1natsu172%2Fwait-element/lists"}