feat!: rename watch() to observe() and wait() to observeOnce() for alignment with native API

[untemps]

Summary

⚠️ Breaking change

Rename watch() to observe() and wait() to observeOnce() to align naming with the native MutationObserver.observe() API and make the one-shot vs continuous distinction self-evident from the method name.

Motivation

The current names watch() and wait() are concise but have drawbacks:

• wait() implies blocking/async but doesn't immediately convey that it's DOM mutation-based
• watch() is used in many unrelated libraries (Lodash, Vue reactivity, fs.watch) with varying semantics
• Neither name references the underlying MutationObserver vocabulary, making the library harder to discover via search or docs
• The wait/watch distinction (one-shot vs continuous) is subtle — developers unfamiliar with the library must read docs to understand which is which

Proposed renaming

Current	Proposed	Rationale
watch(target, cb, opts)	observe(target, cb, opts)	Direct analogue of MutationObserver.observe()
wait(target, opts)	observeOnce(target, opts)	observe + Once suffix makes one-shot semantics explicit
clear()	disconnect()	Mirrors MutationObserver.disconnect()

Usage after rename:

const obs = createDOMObserver()

// Continuous
obs.observe('#foo', ({ node, event }) => { ... })

// One-shot
const { node } = await obs.observeOnce('#foo')

// Stop
obs.disconnect()

Alternative considered

Keep wait() / watch() as aliases and add observe() / observeOnce() as the preferred names. This would be a non-breaking addition first, with deprecation of the old names in a future major.

Breaking change scope

Every call site using wait(), watch(), or clear() must be updated. A codemod handles this mechanically:

watch( → observe(
wait(  → observeOnce(
.clear() → .disconnect()

Notes

• isObserving getter can remain as-is or be renamed to isActive / isConnected — isObserving is still readable and not tied to the method names.
• This rename is most impactful when combined with the factory API (see issue #BR6) — createDOMObserver().observe(...) reads cleanly and is discoverable alongside native MutationObserver.

[untemps]

🎉 This issue has been resolved in version 5.0.0-beta.7 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀