feat: add an optional BgpMatchable interface for matchBGP

.changeset/match-bgp.md

@@ -0,0 +1,5 @@
+---
+"@rdfjs/types": minor
+---
+
+Add an optional `BgpMatchable` interface with a `matchBGP(patterns)` method that yields `Bindings` for basic graph patterns

dataset.d.ts

@@ -3,6 +3,7 @@
 
 import { Quad, BaseQuad, Term } from './data-model.js';
 import { Stream } from './stream.js';
+import { Bindings } from './query/common.js';
 
 export interface DatasetCore<OutQuad extends BaseQuad = Quad, InQuad extends BaseQuad = OutQuad> {
     /**
@@ -202,3 +203,25 @@ export interface DatasetFactory<OutQuad extends BaseQuad = Quad, InQuad extends
      */
     dataset(quads?: Dataset<InQuad>|InQuad[]): D;
 }
+
+/**
+ * An object that can match a basic graph pattern against its quads.
+ *
+ * A basic graph pattern is a set of quad patterns whose terms may be variables.
+ * A solution binds every variable so that all patterns match quads of the dataset at once:
+ * a variable that occurs in several patterns, or several times in one pattern, is bound to the same term everywhere.
+ *
+ * This interface is optional; it can be implemented alongside `DatasetCore` by datasets that can join patterns
+ * more efficiently than repeated calls to `DatasetCore.match`.
+ */
+export interface BgpMatchable<Q extends BaseQuad = Quad, B extends Bindings = Bindings> {
+    /**
+     * Returns one bindings object for every solution of the basic graph pattern.
+     *
+     * Each solution maps every variable in the patterns to the term it is bound to.
+     * The order of the solutions is arbitrary.
+     *
+     * @param patterns The quad patterns of the basic graph pattern; their terms may be variables.
+     */
+    matchBGP(patterns: Iterable<Q>): Iterable<B>;
+}

rdf-js-tests.ts

@@ -1,5 +1,6 @@
 import { BlankNode, DataFactory, Dataset, DatasetCore, DatasetCoreFactory, DatasetFactory, DefaultGraph, Literal,
-  NamedNode, Quad, BaseQuad, Sink, Source, Store, Stream, Term, Variable, Quad_Graph, Quad_Subject } from "./index.js";
+  NamedNode, Quad, BaseQuad, Sink, Source, Store, Stream, Term, Variable, Quad_Graph, Quad_Subject,
+  BgpMatchable, Bindings } from "./index.js";
 import { EventEmitter } from "events";
 
 function test_terms() {
@@ -19,7 +20,7 @@
 
     const namedNodeConstant: NamedNode<'http://example.org'> = <any> {};
     const constantIri: 'http://example.org' = namedNodeConstant.value;
     // @ts-expect-error
     const otherConstantIri: 'http://not-example.org' = namedNodeConstant.value;
     // @ts-expect-error
     const otherNamedNodeConstant: NamedNode<'http://not-example.org'> = namedNodeConstant;
@@ -543,3 +544,20 @@
     const datasetFilter: Dataset = datasetExt.filter();
     const datasetDifference: Dataset = datasetExt.difference();
 }
+
+function testBgpMatchable() {
+    const quad: Quad = <any> {};
+    const baseQuad: BaseQuad = <any> {};
+
+    const matchable: BgpMatchable = <any> {};
+    const solutions1: Iterable<Bindings> = matchable.matchBGP([quad, quad]);
+    const solutions2: Iterable<Bindings> = matchable.matchBGP(new Set([quad]));
+    // @ts-expect-error A BaseQuad may hold terms that a Quad pattern cannot
+    matchable.matchBGP([baseQuad]);
+
+    const baseMatchable: BgpMatchable<BaseQuad> = <any> {};
+    const solutions3: Iterable<Bindings> = baseMatchable.matchBGP([baseQuad, quad]);
+
+    const dataset: DatasetCore & BgpMatchable = <any> {};
+    const datasetSolutions: Iterable<Bindings> = dataset.matchBGP(dataset.match());
+}