readme.md

wait-element

Detect the appearance of an element in the browser DOM

a.k.a promise-querySelector

• Promise API
• Driven by MutationObserver
• Detect by querySelecrtor
• Possible to abort with AbortSignal

If the target element already exists when execution of "wait-element", it immediately resolve and return the element.

Install

npm install @1natsu/wait-element

yarn add @1natsu/wait-element

pnpm add @1natsu/wait-element

bun add @1natsu/wait-element

Usage

Module specifiers

import { waitElement } from "@1natsu/wait-element";

Basically

const el = await waitElement(".late-comming");
console.log(el);
//=> example: "<div class="late-comming">I'm late</div>"

Specify parent target element (specify MutationObserve target)

const parent = await waitElement("#parent");
const el = await waitElement(".late-comming", { target: parent });
console.log(el);
//=> example: "<div class="late-comming">I'm late</div>"

Setting timeout

const el = await waitElement(".late-comming", { signal: AbortSignal.timeout(1000) }).catch(err => console.log(err));
console.log(el);
//=> If detected element: "<div class="late-comming">I'm late</div>"
//=> If timeouted: DOMException: TimeoutError

Abort the waiting

try {
	const waitAbortable = new AbortController();

	const checkElement = waitElement(".late-comming", { signal: waitAbortable.signal });

	waitAbortable.abort("abort this time!");

} catch(error) {
	// After abort handling...
}

Custom detect condition

const el = await waitElement("#animal", {
  detector: (element) =>
		element?.textContent === "Tiger"
			? { isDetected: true, result: element }
			: { isDetected: false },
});
console.log(el.textContent);
//=> example: Tiger

import { isNotExist } from "@1natsu/wait-element/detectors";

// when resolve if “not exist” or “disappear” at the time of call
const result = await waitElement(".hero", { detector: isNotExist });
//=> result: null

Unify waiting process

Unifies the process of finding an element. If set true, increases efficiency. Unify the same arguments(includes options) with each other.

const A = waitElement(".late-comming", {
	unifyProcess: true,
});

const B = waitElement(".late-comming", {
	unifyProcess: true,
});

const C = waitElement(".late-comming", {
	unifyProcess: true,
	signal: AbortSignal.timeout(1000)
});

const D = waitElement(".late-comming", {
	unifyProcess: false,
});

// Unified:
// A === B
// B !== C
// B !== D

API

waitElement(selector, [options])

selector

Type: string

Format is CSS-selector

options

Passed options is merged with default configs.

See TS definition for detailed information

createWaitElement(initOptions)

Custom waitElement function can be created.

Similar

The very similar library.

• element-ready
  • Implementation method is different from this library.

License

MIT © 1natsu172