feat: match Variables inside Quad pattern terms

README.md

@@ -429,6 +429,20 @@ The store provides the following search methods
 - `getGraphs` returns an array of unique graphs occurring in matching quad
 - `forGraphs` executes a callback on unique graphs occurring in matching quads
 
+An array in the subject, object, or graph slot of `match`, `getQuads`, `countQuads`, `has`, and friends structurally matches an RDF 1.2 triple term. Its four entries represent the term's subject, predicate, object, and graph: `null` or `undefined` is a wildcard, RDF terms match exactly, and nested arrays recurse. Regular `Quad` and `Variable` terms retain exact-match semantics (see [#633](https://github.com/rdfjs/N3.js/issues/633)):
+
+```JavaScript
+// All quads reifying a statement about :s, in any graph component
+const { namedNode } = N3.DataFactory;
+const reifications = store.getQuads(
+  null,
+  namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#reifies'),
+  [namedNode('http://ex.org/s'), null, null, null],
+);
+```
+
+The entity loops (`getSubjects`/`forObjects` and friends) continue to accept RDF terms rather than structural arrays.
+
 ## Reasoning
 
 N3.js supports reasoning as follows:

perf/N3StoreStar-perf.js

@@ -116,3 +116,60 @@ for (i = 0; i < dim; i++)
       ).length,
       dimSquared);
 console.timeEnd(TEST);
+
+// ## Matching patterns inside triple terms (issue #633)
+// Workload: `ex:r{i} ex:reifies <<( ex:s{i%K} ex:p{i%16} ex:o{i} )>>`,
+// with K = N/100 (100 quads per inner subject)
+const { namedNode, variable, quad } = N3.DataFactory;
+const N = Number.parseInt(process.argv[3], 10) || 100000;
+const K = Math.max(N / 100, 1);
+const reifies = namedNode(`${prefix}reifies`);
+
+const starStore = new N3.Store();
+TEST = `- Adding ${N} quads with triple terms`;
+console.time(TEST);
+for (i = 0; i < N; i++)
+  starStore.addQuad(
+    namedNode(`${prefix}r${i}`),
+    reifies,
+    quad(namedNode(`${prefix}s${i % K}`), namedNode(`${prefix}p${i % 16}`), namedNode(`${prefix}o${i}`)));
+console.timeEnd(TEST);
+
+const plainStore = new N3.Store();
+TEST = `- Adding ${N} plain control quads`;
+console.time(TEST);
+for (i = 0; i < N; i++)
+  plainStore.addQuad(
+    namedNode(`${prefix}s${i}`),
+    namedNode(`${prefix}p${i % 16}`),
+    namedNode(`${prefix}o${i}`));
+console.timeEnd(TEST);
+
+TEST = `- Exact triple-term match, ${K} times`;
+console.time(TEST);
+for (i = 0; i < K; i++)
+  assert.equal(starStore.getQuads(null, null,
+    quad(namedNode(`${prefix}s${i % K}`), namedNode(`${prefix}p${i % 16}`), namedNode(`${prefix}o${i}`))).length, 1);
+console.timeEnd(TEST);
+
+TEST = `- Wildcard match <<( s0 ?p ?o )>>, ${N / K} results`;
+console.time(TEST);
+assert.equal(starStore.getQuads(null, null,
+  quad(namedNode(`${prefix}s0`), variable('p'), variable('o'))).length, N / K);
+console.timeEnd(TEST);
+
+TEST = `- Hard wildcard match <<( ?s p3 ?o )>>, ${Math.ceil((N - 3) / 16)} results`;
+console.time(TEST);
+assert.equal(starStore.getQuads(null, null,
+  quad(variable('s'), namedNode(`${prefix}p3`), variable('o'))).length, Math.ceil((N - 3) / 16));
+console.timeEnd(TEST);
+
+TEST = `- Scan workaround for <<( s0 ?p ?o )>>, ${N / K} results`;
+console.time(TEST);
+let found = 0;
+for (const starQuad of starStore) {
+  if (starQuad.object.termType === 'Quad' && starQuad.object.subject.value === `${prefix}s0`)
+    found++;
+}
+assert.equal(found, N / K);
+console.timeEnd(TEST);