feat(async+events): change notifications on the asynchronous surface

[jeswr]

What this does

Completes the asynchronous surface with change notifications, mirroring the sync-side proposals in #93/#94:

• AsyncDatasetWrapper.on(listener) / off(listener) — subscribe an IAsyncDatasetChangeListener (new exported type) to every mutation performed through the wrapper: direct add/delete calls, mutator methods of mapping classes projected out of the wrapper, and mutations of an AsyncWrappingSet. Async-specific semantics:
  • Listeners may be asynchronous: they are invoked in subscription order, a returned promise is awaited before the next listener, and the promise returned by the mutation that triggered the notifications only resolves once every listener has settled.
  • Only effective changes notify (per the sync semantics of feat(events): change notifications on DatasetWrapper (on/off) #94): adding a quad the dataset already contains, or deleting an absent one, emits nothing. Because the underlying dataset can only be queried asynchronously, effectiveness is determined with a has() lookup before the mutation — performed only while at least one listener is subscribed, so the unobserved fast path is unchanged.
  • Only mutations performed through the wrapper (or objects bound to it) are observed; mutating the wrapped dataset directly is not. This matches the analogous caveat on the sync side.
• AsyncWrappingSet.on(listener) / off(listener) — set-level subscriptions delivering the kind of mutation and the mapped JavaScript value, exactly like feat(events): WrappingSet.on/off with mapped values #93's WrappingSet.on/off: the same (listener, subject, predicate)-keyed WeakMap adapter registry, so off works across the fresh instances AsyncSetFrom.subjectPredicate returns on every property access, and re-attaching the same listener replaces the previous subscription. Datasets that do not emit change events are rejected with a typed DatasetEventsError.

Stacked on #97 and #98

This is the third slice of the async surface and requires both #97 (AsyncDatasetWrapper) and #98 (AsyncTermWrapper/AsyncWrappingSet/async mappings): only the last commit (feat(async+events): change notifications on the asynchronous surface) is proposed here; the first two commits are #97 and #98 unchanged, plus one reconciliation merge commit that makes the two branches compile together:

• IAsyncTermWrapperConstructor types its dataset parameter as the AsyncDatasetCore interface from @rdfjs/types (as feat(async): AsyncDatasetWrapper query helpers #97 does) rather than the concrete class from @jeswr/async-dataset (as feat(async): AsyncTermWrapper and asynchronous mapping namespaces #98 did), because feat(async): AsyncDatasetWrapper query helpers #97's query helpers hand the AsyncDatasetWrapper itself to mapping-class constructors, and the wrapper implements the interface but is not an instance of the class. AsyncTermWrapper and AsyncWrappingSet type-only imports follow suit; no behaviour change.
• Test models keep feat(async): AsyncTermWrapper and asynchronous mapping namespaces #98's AsyncTermWrapper-based AsyncParent/AsyncChild (a superset of feat(async): AsyncDatasetWrapper query helpers #97's hand-rolled ones); asyncDatasetFromRdf keeps feat(async): AsyncTermWrapper and asynchronous mapping namespaces #98's lazy-thunk source while reusing datasetFromRdf; typedoc.json/mod.ts take the union.

Once #97 and #98 land, this PR rebases down to the one feature commit.

Relation to #73 / #93 / #94

• Supersedes the async notification slice of Omnibus #73 (Omnibus): the AsyncNotifyingDatasetCore concern, AsyncWrappingSet's on/off/adapter registry, and the async event tests (ported into async_wrapping_set_events.test.ts / async_dataset_events.test.ts). Two deliberate deviations from the omnibus:
  • Notification is implemented in AsyncDatasetWrapper itself rather than in a separate AsyncNotifyingDatasetCore wrapper class: the foundation async dataset deliberately stays event-free, every wrapper-driven mutation already flows through AsyncDatasetWrapper.add/delete, and AsyncWrappingSet reaches the notifying surface through AsyncTermWrapper.dataset — so interception at the wrapper delivers the same behaviour with much less machinery.
  • Omnibus #73 notified every mutation; this PR follows feat(events): change notifications on DatasetWrapper (on/off) #94's effective-change semantics instead.
• No ChangeEvent type export: IAsyncDatasetChangeListener and AsyncWrappingSetListener inline the "add" | "delete" union (as feat(events): WrappingSet.on/off with mapped values #93's WrappingSetListener does). If this PR exported its own ChangeEvent alongside feat(events): change notifications on DatasetWrapper (on/off) #94's, the two star re-exports in mod.ts would make the name ambiguous and silently drop it from the public surface.
• src/errors/DatasetEventsError.ts overlaps with feat(events): WrappingSet.on/off with mapped values #93: it is feat(events): WrappingSet.on/off with mapped values #93's class with the dataset parameter widened to DatasetCore | AsyncDatasetCore and the remark retargeted at the async surface. Whichever PR lands second resolves to the widened variant.

No issue is closed by this PR.

Tests

• test/unit/async_dataset_events.test.ts — mirrors feat(events): change notifications on DatasetWrapper (on/off) #94's dataset_events.test.ts on the async fixtures: direct add/delete notifications, effective-change filtering, listener bookkeeping (off, double-subscribe, multiple listeners, unknown-listener off), wrapper-driven events for required/optional/typed properties and set mutations, plus async-specific coverage: an async listener is awaited before the mutation resolves, listeners are dispatched sequentially, and direct mutations of the wrapped dataset do not notify.
• test/unit/async_wrapping_set_events.test.ts — mirrors feat(events): WrappingSet.on/off with mapped values #93's wrapping_set_events.test.ts: mapped-value add/delete/clear emission (term and literal mappings), subject/predicate filtering, direct dataset mutations, no event on ineffective adds, multiple independent listeners, live re-iteration inside an awaited async listener, off across fresh instances / unknown listeners / per-(subject, predicate) detachment, re-subscription replacement, and the DatasetEventsError path.

npx tsc, npm test (222 tests, 0 fail; new code at 100% line/branch coverage), npx typedoc (same 6-warning baseline as the base branch) and npm audit --omit=dev --audit-level=moderate all pass locally on Node 24.

Review timing: This draft was prepared with Claude; I (@jeswr) will personally review it before it progresses. I'm currently batching a lot of work in flight, so expect active review Wednesday-Friday (8-10 July).