Skip to content

feat(async): AsyncDatasetWrapper query helpers#97

Draft
jeswr wants to merge 1 commit into
rdfjs:mainfrom
jeswr:feat/async-dataset-wrapper
Draft

feat(async): AsyncDatasetWrapper query helpers#97
jeswr wants to merge 1 commit into
rdfjs:mainfrom
jeswr:feat/async-dataset-wrapper

Conversation

@jeswr

@jeswr jeswr commented Jul 6, 2026

Copy link
Copy Markdown
Collaborator

What this does

Adds an asynchronous counterpart of DatasetWrapper for datasets whose contents cannot be read synchronously — for example disk- or remote-backed stores:

  • AsyncDatasetWrapper (src/async/AsyncDatasetWrapper.ts) implements the proposed RDF/JS AsyncDatasetCore interface by delegation — Promise-based size/add/delete/has, for await iteration, and (potentially lazily evaluated) match views — and offers the same protected query helpers as DatasetWrapper: subjectsOf, objectsOf, instancesOf, matchSubjectsOf, matchObjectsOf, each returning an AsyncIterable<T> of mapping-class instances.
  • IAsyncTermWrapperConstructor (src/async/type/IAsyncTermWrapperConstructor.ts) mirrors ITermWrapperConstructor for the asynchronous surface: new (term, dataset: AsyncDatasetCore, factory) => T.
  • The constructor accepts an AsyncDatasetCore or any synchronous DatasetCore source (an instance, a promise of one, or a lazy thunk). Synchronous sources are adapted automatically via the @jeswr/async-dataset foundation package (this repo's first runtime dependency — a deliberate, visible decision), so existing sync stores such as an n3 Store work unchanged.
  • The @rdfjs/types devDependency moves to jeswr/types#async-eventful-dataset-types, which adds the proposed AsyncDatasetCore/AsyncDataset interfaces (see feat: add AsyncDataset and EventfulDataset interface variants jeswr/types#2 for the upstream type proposal).
  • Ports the async_dataset_wrapper.test.ts slice with AsyncParent/AsyncChild/AsyncParentDataset fixture models covering all five helpers, both wrapping paths (already-async and sync-backed, including a lazy thunk), iteration, size, match, and the add/has/delete round trip.

Scope

Supersedes the AsyncDatasetWrapper slice of #73 (dataset-side async concern) — deliberately minus the notification surface (on/off), the default-graph-only Triple restriction, and the datasetFactory constructor parameter from that omnibus branch, which belong to separate slices. The term-side async concern (AsyncTermWrapper and async mappings) is a separate upcoming slice that builds on the IAsyncTermWrapperConstructor type introduced here; the test models in this PR intentionally use plain hand-rolled classes so this slice stands alone.

No issue is closed by this PR.

Checks

  • npx tsc, npm test (133 tests, 0 fail; new code at ~99% line / 100% branch coverage), npx typedoc (no new warnings) 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).

Adds an asynchronous counterpart of DatasetWrapper for datasets whose
contents cannot be read synchronously (disk- or remote-backed stores):

- src/async/AsyncDatasetWrapper.ts implements the proposed RDF/JS
  AsyncDatasetCore interface by delegation (Promise-based size/add/
  delete/has, for-await iteration, lazy match views) and provides the
  same protected query helpers as DatasetWrapper - subjectsOf,
  objectsOf, instancesOf, matchSubjectsOf, matchObjectsOf - returning
  AsyncIterable<T> built from an IAsyncTermWrapperConstructor.
- src/async/type/IAsyncTermWrapperConstructor.ts mirrors
  ITermWrapperConstructor for the asynchronous surface.
- Synchronous DatasetCore sources (instance, promise or lazy thunk)
  are adapted automatically via the @jeswr/async-dataset foundation
  package, so existing sync stores (e.g. an n3 Store) work unchanged.
- Ports the async_dataset_wrapper.test.ts slice with AsyncParent/
  AsyncChild/AsyncParentDataset fixture models.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant