Add async `waitFor()` helper for DOM-based detections #227

Copilot · 2026-01-24T10:04:10Z

DOM-based detections like isOrganizationProfile() can fail if called before elements render. This adds an async wrapper to poll detections until they return true or the document completes loading.

Implementation

utils.waitFor(detection): Polls detection function via requestAnimationFrame until it returns true or document.readyState === 'complete'
Returns final detection result as Promise<boolean>
Exported via utils object for better organization

Usage

import {utils, isOrganizationProfile} from 'github-url-detection';

async function init() {
  if (!await utils.waitFor(isOrganizationProfile)) {
    return;
  }
  // Element is now present or document is complete
}

Works with any detection function. Useful for features that initialize before page load completes.

Original prompt

This section details on the original issue you should resolve

<issue_title>Add elementReady-like helper for DOM detections</issue_title>
<issue_description>Sometimes we want to test whether a page matches before it's done downloading, this can be done by passing a selector to element-ready.

I have 2 ideas:

Static definitions

Instead of being just a function, we can define the detections as a list of constraints like:
- const canUserEditOrg = (url) => isOrganizationProfile() && exists('.pagehead-tabs-item[href$="/settings/profile"]')
+ const canUserEditOrgDefinition = [isOrganizationProfile, '.pagehead-tabs-item[href$="/settings/profile"]']
+ export canUserEditOrg = solveConstraints(canUserEditOrgDefinition);
+ export canUserEditOrgAsync = solveConstraintsAsync(canUserEditOrgDefinition);
But this gets wordy FAST

Duplicate functions
  const canUserEditOrg = (url) => isOrganizationProfile() && exists('.pagehead-tabs-item[href$="/settings/profile"]')
+ const canUserEditOrgAsync = async (url) => isOrganizationProfile() && await existsReady('.pagehead-tabs-item[href$="/settings/profile"]')
</issue_description>

Comments on the Issue (you are @copilot in this section)
@fregante ### Wrapper idea
ElementReady is nothing but a requestAnimationFrame-based loop that calls querySelector until found. This means we can offer a simple wrapper that does this with any detection:
import {wait, canEditSidebar} from '';

function init() {
  if(!await wait(canEditSidebar)) 
    return false
}
Pure DOM-based detections would be perfect this way;

Pure URL-based detections wouldn’t need it;

Mixed detections would unnecessarily test the URL every time, but probably we don’t have to worry about the “performance impact” of this

Alternatively the detections could internally replace exists with an async version, but it would be impossible to effectively handle multiple checks in the same detection:
await canEditSidebar({async: true})
```</body></comment_new>
<comment_new><author>@fregante</author><body>
Something like:
```js
export async function wait(detection) {
	while (!detection() && document isn't ready) {
		await Promise(requestAnimationFrame)
	}

	return detection();
}
```</body></comment_new>
<comment_new><author>@fregante</author><body>
Note that we moved these user-capability detections to the API in Refined GitHub:

- https://github.com/refined-github/refined-github/pull/7798

However there are still other DOM-based detection like `isOrganizationProfile` that would benefit from this</body></comment_new>
</comments>

Fixes Add elementReady-like helper for DOM detections #85

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Implement the wait() async helper function that waits for a detection to return true by repeatedly checking it on each animation frame. This is useful for DOM-based detections that need to wait for elements to appear before the document is fully loaded. - Add wait() function that loops using requestAnimationFrame - Add comprehensive tests for the wait function - Update test infrastructure to support async detection functions - Add JSDoc documentation with usage examples Co-authored-by: fregante <1402241+fregante@users.noreply.github.com>

Co-authored-by: fregante <1402241+fregante@users.noreply.github.com>

fregante · 2026-01-24T10:46:28Z

index.ts

+ * }
+ * ```
+ */
+export async function wait(detection: () => boolean): Promise<boolean> {


@copilot

Export via utils only.

Revert type changes (detectionFn = detect as) in index.test.ts

Rename to waitFor

Done in commit b177e73:

Renamed wait to waitFor

Moved to utils export only (removed direct export)

Reverted type assertion changes in index.test.ts

fregante

Hopefully this works well 😍

- Renamed wait() to waitFor() as requested - Moved export to utils object instead of direct export - Reverted type assertion changes in index.test.ts - Updated README to show usage via utils.waitFor() - Updated JSDoc example to reflect new API Co-authored-by: fregante <1402241+fregante@users.noreply.github.com>

Initial plan

588f603

Copilot AI assigned Copilot and fregante Jan 24, 2026

Copilot started work on behalf of fregante January 24, 2026 10:04 View session

Copilot AI and others added 2 commits January 24, 2026 10:10

Add wait helper documentation to README

95239d0

Co-authored-by: fregante <1402241+fregante@users.noreply.github.com>

fregante marked this pull request as ready for review January 24, 2026 10:12

Fix test cleanup in wait test to handle undefined descriptor

4efdd75

Co-authored-by: fregante <1402241+fregante@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add elementReady-like helper for DOM detections~~ Add async wait() helper for DOM-based detections Jan 24, 2026

Copilot AI requested a review from fregante January 24, 2026 10:17

Copilot finished work on behalf of fregante January 24, 2026 10:17

fregante reviewed Jan 24, 2026

View reviewed changes

fregante approved these changes Jan 24, 2026

View reviewed changes

Copilot started work on behalf of fregante January 24, 2026 10:46 View session

Copilot AI changed the title ~~Add async wait() helper for DOM-based detections~~ Add async waitFor() helper for DOM-based detections Jan 24, 2026

Copilot AI requested a review from fregante January 24, 2026 10:51

Copilot finished work on behalf of fregante January 24, 2026 10:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add async `waitFor()` helper for DOM-based detections #227

Add async `waitFor()` helper for DOM-based detections #227

Copilot AI commented Jan 24, 2026 •

edited

Loading

Uh oh!

fregante Jan 24, 2026

Uh oh!

Copilot AI Jan 24, 2026

Uh oh!

fregante left a comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Uh oh!

Add async waitFor() helper for DOM-based detections #227

Are you sure you want to change the base?

Add async waitFor() helper for DOM-based detections #227

Conversation

Copilot AI commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Implementation

Usage

Static definitions

Duplicate functions

Comments on the Issue (you are @copilot in this section)

Uh oh!

fregante Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

fregante left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Add async `waitFor()` helper for DOM-based detections #227

Add async `waitFor()` helper for DOM-based detections #227

Copilot AI commented Jan 24, 2026 •

edited

Loading