Omnibus by jeswr · Pull Request #73 · rdfjs/wrapper

jeswr · 2026-04-19T15:24:27Z

Started to address @jaxoncreed outstanding comments in #43 - ended up implementing the following at the same time:

Support for reading from multiple graphs and writing to one graph via GraphScopedDataset
- In adding this I have also made some opinionated type restrictions. This aligns with the philosophy of Introduce TermWrapper#from and TermWrapper#in #61, which I acknowledge I need to pick back up. The primary restrictions are to have DatasetWrapper match only over the DefaultGraph and output Triples -- with the assumption that you are selecting the named graphs you wish to work over using GraphScopedDataset - or a similar class which encodes logic of how to determine which view of the dataset to read from and how to determine which named graphs to write to.
Support for events, with notifications for changes to the dataset (via a bespoke NotificationsDatasetCore interface)
Support for asynchronous data via AsyncDatasetCore interface

…graph handling

…tWrapper and related classes

- Added ITriple type definition to improve type safety in dataset operations. - Updated IGraphScopedDatasetConstructor to utilize NotifyingDatasetCore for better event handling. - Refactored dataset imports in mod.ts for clarity and organization. - Enhanced ParentDataset to streamline subject and object matching methods. - Improved test coverage for dataset core functionalities, including union and named graph behaviors. - Introduced n3StoreFactory for consistent dataset creation in tests. - Added tests for ProjectedDatasetCoreWrapper to ensure correct behavior with read graphs. - Implemented LazyMatchNotifyingDatasetCore to optimize matching operations with event notifications.

- Introduced a new `dataFactory` utility to standardize the DataFactory usage across tests. - Updated all test files to replace instances of `DataFactory` with the new `dataFactory`. - Enhanced type safety by ensuring proper type casting for Triple and DatasetCore in various test cases. - Refactored dataset creation functions to return wrapped datasets for better integration with RDFJS types. - Improved clarity and maintainability of test code by reducing redundancy in dataset initialization.

…etailed listener functionality and tests

…ntation and examples for better usability

- Added AsyncTermWrapper to provide an asynchronous interface for RDF terms. - Implemented AsyncWrappingSet for live, mutable views over RDF quads in datasets. - Created AsyncLiteralAs, AsyncOptionalAs, AsyncRequiredAs, and AsyncSetFrom for async mappings. - Developed AsyncParent and AsyncChild models to demonstrate async property access and mutation. - Added tests for async dataset wrappers and term wrappers to ensure functionality.

Copilot

Pull request overview

This PR expands the wrapper library to support graph-scoped dataset views, change notifications, and a parallel async API surface, while updating core type constraints to default-graph triples.

Changes:

Introduces GraphScopedDataset / ProjectedDatasetCoreWrapper to read from multiple graphs and write to a configured graph while projecting to default-graph triples.
Adds change-notifying dataset cores (NotifyingDatasetCore*) plus lazy, pattern-aware materialized match views (LazyMatchNotifyingDatasetCore).
Adds async counterparts (Async*) for dataset/term wrappers, mappings, and wrapping sets; updates tests and README accordingly.

Reviewed changes

Copilot reviewed 64 out of 64 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
test/unit/wrapping_map.test.ts	Switches tests to use the new typed `dataFactory` helper.
test/unit/util/n3StoreFactory.ts	Adds a test factory producing notifying datasets backed by `n3` `Store`.
test/unit/util/datasetFromRdf.ts	Updates RDF parsing helper to return a notifying default-dataset view.
test/unit/util/dataFactory.ts	Adds a test `DataFactory` helper typed to wrapper `Triple`.
test/unit/util/asyncN3StoreFactory.ts	Adds async notifying dataset factory for tests (sync store bridged to async).
test/unit/util/asyncDatasetFromRdf.ts	Adds async RDF parsing helper returning an async notifying dataset view.
test/unit/union_graph.test.ts	Adds coverage for union projection behavior via `GraphScopedDataset`.
test/unit/term_wrapper.test.ts	Updates term wrapper tests to use new factory/dataset wiring.
test/unit/rdf_list.test.ts	Updates list tests to use new factory/dataset wiring.
test/unit/projected_dataset.test.ts	Adds tests for `ProjectedDatasetCoreWrapper` behavior + event forwarding/dedup.
test/unit/named_graph_integration.test.ts	Migrates integration coverage from `NamedGraphDataset` to `GraphScopedDataset`.
test/unit/named_graph.test.ts	Migrates named-graph unit tests to `GraphScopedDataset` projection semantics.
test/unit/model/ParentDataset.ts	Updates generated dataset wrapper methods to new graph/default constraints.
test/unit/model/AsyncParentDataset.ts	Adds async dataset wrapper used in async tests.
test/unit/model/AsyncParent.ts	Adds async term wrapper model exercising async mappings.
test/unit/model/AsyncChild.ts	Adds async child wrapper model.
test/unit/literalAs.test.ts	Updates tests to use notifying dataset core + typed factory.
test/unit/dataset_wrapper.test.ts	Updates dataset wrapper tests to pass datasetFactory.
test/unit/dataset_module.test.ts	Adds tests for new dataset modules: defaultGraph, notifying wrapper, lazy match, empty dataset.
test/unit/dataset_events_examples.test.ts	Adds example-style tests for dataset-level and set-level notifications.
test/unit/dataset_events.test.ts	Adds unit tests for dataset change notifications via wrappers and direct mutation.
test/unit/dataset_core_base.test.ts	Updates core dataset tests to default-graph match usage.
test/unit/async_term_wrapper.test.ts	Adds async term wrapper tests for mappings, sets, and async notifications.
test/unit/async_dataset_wrapper.test.ts	Adds async dataset wrapper tests for traversal/iteration/size.
src/type/ITriple.ts	Introduces `Triple`/`BaseTriple` types constrained to default graph.
src/type/ITermWrapperConstructor.ts	Tightens wrapper constructor signature to `DefaultDatasetCore` + `DataFactory<Triple, Triple>`.
src/type/INamedGraphDatasetConstructor.ts	Removes old named-graph constructor type.
src/type/IGraphScopedDatasetConstructor.ts	Adds constructor signature for graph-scoped dataset views.
src/mod.ts	Re-exports new graph-scoping, notifications, lazy views, and async surface.
src/mapping/SetFrom.ts	Updates return type to `WrappingSet` (notification-capable set wrapper).
src/mapping/RequiredFrom.ts	Forces default-graph matching and updates subject typing.
src/mapping/OptionalFrom.ts	Forces default-graph matching and updates subject typing.
src/mapping/OptionalAs.ts	Forces default-graph matching for delete-before-add semantics.
src/errors/QuadError.ts	Broadens quad payload typing to `BaseQuad`.
src/errors/NamedGraphError.ts	Updates to accept `BaseQuad` and fixes message to reference `quad.graph.value`.
src/ensure.ts	Updates `ensureDefaultGraph` to assert `BaseTriple` and throw `NamedGraphError`.
src/dataset/terms.ts	Adds a shared `defaultGraph` singleton term.
src/dataset/ProjectedDataset.ts	Adds projected dataset core wrapper with union/scoped read graphs + event dedup.
src/dataset/NotifyingDatasetCore.ts	Adds notifying dataset interfaces, wrapper, and factory helpers.
src/dataset/LazyMaterialize.ts	Adds lazy materialized match view with pattern-filtered events and disposal.
src/dataset/GraphScopedDataset.ts	Adds dataset wrapper that projects scoped graphs onto default graph.
src/async/type/IAsyncTermWrapperConstructor.ts	Adds constructor signature for async term wrappers.
src/async/type/IAsyncTermFromValueMapping.ts	Adds async “from” mapping type (still sync function).
src/async/type/IAsyncTermAsValueMapping.ts	Adds async “as” mapping type (sync-or-async).
src/async/mapping/AsyncTermAs.ts	Adds async counterpart of `TermAs`.
src/async/mapping/AsyncSetFrom.ts	Adds async counterpart of `SetFrom`.
src/async/mapping/AsyncRequiredFrom.ts	Adds async counterpart of required reads.
src/async/mapping/AsyncRequiredAs.ts	Adds async counterpart of required writes.
src/async/mapping/AsyncOptionalFrom.ts	Adds async counterpart of optional reads.
src/async/mapping/AsyncOptionalAs.ts	Adds async counterpart of optional writes (materializes before deletes).
src/async/mapping/AsyncLiteralAs.ts	Adds async-compatible literal mappers (pure, sync return).
src/async/AsyncWrappingSet.ts	Adds async live set wrapper with async listener support and stable off() identity.
src/async/AsyncTermWrapper.ts	Adds async term wrapper bound to async default dataset core.
src/async/AsyncNotifyingDatasetCore.ts	Adds async dataset core + notifying wrapper + sync-to-async adapter.
src/async/AsyncDatasetWrapper.ts	Adds async dataset wrapper mirroring sync helper APIs and notifications.
src/async/AsyncDatasetCore.ts	Adds base async dataset core and factory interfaces.
src/WrappingSet.ts	Extends set wrapper to default-graph matching and adds set-level notifications.
src/WrappingMap.ts	Forces default-graph matching for map-backed wrappers.
src/TermWrapper.ts	Tightens term wrapper to `DefaultDatasetCore` + `DataFactory<Triple, Triple>`.
src/NamedGraphDataset.ts	Removes old named-graph dataset wrapper implementation.
src/ListItem.ts	Updates list item wrapper signatures to new default-graph dataset/factory types.
src/EventEmitter.ts	Adds generic event emitter + pattern-filtering emitter for dataset change dispatch.
src/DatasetWrapper.ts	Reworks wrapper to default-graph-only view, adds notifications, and introduces `scoped()`.
README.md	Updates docs for graph scoping, notifications, set notifications, and async API usage.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-19T15:30:07Z

 /**
 * Thrown when a named graph is used on a dataset view that only supports the default graph.
 *
 * @see {@link namedGraph}
 */
 export class NamedGraphError extends QuadError {
-    constructor(quad: Quad, cause?: any) {
-        super(quad, `Graph must be default (empty) but was ${quad.value}`, cause)
+    constructor(quad: BaseQuad, cause?: any) {
+        super(quad, `Graph must be default (empty) but was ${quad.graph.value}`, cause)


The JSDoc @see {@link namedGraph} reference is now stale (the old namedGraph/NamedGraphDataset API was removed in this PR). Update the link to the new entry point (DatasetWrapper.scoped / GraphScopedDataset) so generated docs don’t contain a broken symbol reference.

@copilot apply changes based on this feedback

Updated in 40f3ad1: NamedGraphError JSDoc now references DatasetWrapper.scoped and GraphScopedDataset instead of the removed namedGraph symbol. No UI changes in this update.

Copilot · 2026-04-19T15:30:08Z

 import type { Quad_Object, Quad_Subject, Term } from "@rdfjs/types"
+import type { Triple } from "../type/ITriple.js"


Unused import: Triple is imported but never referenced in this file. Please remove it to avoid unnecessary coupling/extra module graph edges.

@copilot apply changes based on this feedback

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…tion or class' Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…tion or class' Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

Agent-Logs-Url: https://github.com/rdfjs/wrapper/sessions/1a12314a-54af-47f5-a01e-20bdadb5a9fb Co-authored-by: jeswr <63333554+jeswr@users.noreply.github.com>

jeswr added 12 commits April 18, 2026 19:51

feat: introduce GraphScopedDataset and ProjectedDataset for enhanced …

d230929

…graph handling

WIP

4ee543c

WIP

fca8e40

WIP

ccccaad

WIP

dfd74e3

feat: update dataset factory types for improved type safety in Datase…

ad44fc0

…tWrapper and related classes

WIP

cc75d57

feat: enhance event handling in DatasetWrapper and WrappingSet with d…

582b131

…etailed listener functionality and tests

feat: enhance GraphScopedDataset and WrappingSet with detailed docume…

ed3bfee

…ntation and examples for better usability

jeswr requested a review from matthieubosquet as a code owner April 19, 2026 15:24

Copilot AI review requested due to automatic review settings April 19, 2026 15:24

jeswr requested a review from langsamu as a code owner April 19, 2026 15:24

Copilot started reviewing on behalf of jeswr April 19, 2026 15:24 View session

Merge branch 'main' into feat/scoped-dataset

db30314

github-code-quality bot found potential problems Apr 19, 2026

View reviewed changes

Comment thread src/EventEmitter.ts Fixed

Comment thread src/DatasetWrapper.ts Fixed

Comment thread src/async/type/IAsyncTermWrapperConstructor.ts Fixed

Comment thread src/dataset/ProjectedDataset.ts Fixed

Comment thread test/unit/dataset_module.test.ts Fixed

Copilot AI reviewed Apr 19, 2026

View reviewed changes

jeswr and others added 6 commits April 19, 2026 16:37

Update src/EventEmitter.ts

fa8174c

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding 'Unused variable, import, func…

63f6283

…tion or class' Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

Potential fix for pull request finding 'Unused variable, import, func…

361cc12

…tion or class' Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

Update src/dataset/terms.ts

a40b3f0

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding 'Unused variable, import, func…

e897fd8

…tion or class' Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

Potential fix for pull request finding 'Unused variable, import, func…

b39f694

…tion or class' Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

Copilot started work on behalf of jeswr April 19, 2026 17:05 View session

docs: update NamedGraphError JSDoc links to scoped APIs

40f3ad1

Agent-Logs-Url: https://github.com/rdfjs/wrapper/sessions/1a12314a-54af-47f5-a01e-20bdadb5a9fb Co-authored-by: jeswr <63333554+jeswr@users.noreply.github.com>

Copilot finished work on behalf of jeswr April 19, 2026 17:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Omnibus#73

Omnibus#73
jeswr wants to merge 20 commits intomainfrom
feat/scoped-dataset

jeswr commented Apr 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

jeswr Apr 19, 2026

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 19, 2026

Uh oh!

jeswr Apr 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		import type { Quad_Object, Quad_Subject, Term } from "@rdfjs/types"
		import type { Triple } from "../type/ITriple.js"

Conversation

jeswr commented Apr 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

jeswr Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

jeswr Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jeswr commented Apr 19, 2026 •

edited

Loading