n3 2.7.12 → 2.9.0

package/src/N3Reasoner.js

@@ -23,10 +23,18 @@ export default class N3Reasoner {
   }
 
   _add(subject, predicate, object, graphItem, c, cb) {
-    // Only add to the remaining indexes if there is not already a value in the index
-    if (!this._store._addToIndex(graphItem.subjects,   subject,   predicate, object)) return;
-    this._store._addToIndex(graphItem.predicates, predicate, object,    subject);
-    this._store._addToIndex(graphItem.objects,    object,    subject,   predicate);
+    const store = this._store;
+    // Observing views must see each derivation before indexing
+    // (stores from other N3 versions have no observers)
+    if (store._observers) {
+      if (!store._addQuad(subject, predicate, object, this._graphId)) return;
+    }
+    else {
+      // Only add to the remaining indexes if there is not already a value in the index
+      if (!store._addToIndex(graphItem.subjects,   subject,   predicate, object)) return;
+      store._addToIndex(graphItem.predicates, predicate, object,    subject);
+      store._addToIndex(graphItem.objects,    object,    subject,   predicate);
+    }
     // Count genuinely new derivations and fail past the budget. The check comes
     // after all three indexes are updated, so a caught error leaves the store
     // in a consistent state (the reasoning result is merely incomplete).
@@ -228,6 +236,8 @@ export default class N3Reasoner {
     const graphs = this._store._getGraphs();
     try {
       for (const graphId in graphs) {
+        // Observers compare numeric graph identifiers
+        this._graphId = Number(graphId);
         this._reasonGraphNaive(rules, graphs[graphId]);
       }
     }

package/src/N3Store.js

@@ -8,6 +8,15 @@ import N3Writer from './N3Writer';
 const ITERATOR = Symbol('iter');
 const SIZE = Symbol('size');
 
+// Neither a registration nor its cleanup record may keep a view or store alive.
+// Initialize lazily so importing N3 and using lazy views needs no weak-reference APIs.
+let observerRegistry;
+function finalizeObserver({ store, observer }) {
+  const target = store.deref();
+  if (target)
+    target._removeObserver(observer);
+}
+
 function hasInIndex(index0, key0, key1, key2) {
   const index1 = index0 && index0[key0];
   const index2 = index1 && index1[key1];
@@ -189,12 +198,15 @@ export default class N3Store {
     this._size = 0;
     // `_graphs` contains subject, predicate, and object indexes per graph
     this._graphs = Object.create(null);
+    // `_observers` contains weak references to views notified before every mutation
+    this._observers = null;
 
     // Shift parameters if `quads` is not given
     if (!options && quads && !quads[0] && !(typeof quads.match === 'function'))
       options = quads, quads = null;
     options = options || {};
     this._factory = options.factory || N3DataFactory;
+    this._matchSemantics = validateMatchSemantics(options.matchSemantics);
     this._entityIndex = options.entityIndex || new N3EntityIndex({ factory: this._factory });
     this._entities = this._entityIndex._entities;
     this._termFromId = this._entityIndex._termFromId.bind(this._entityIndex);
@@ -402,6 +414,38 @@ export default class N3Store {
     return typeof graph !== 'number' ? this._graphs : { [graph]: this._graphs[graph] };
   }
 
+  // ### `_addObserver` registers a mutation observer.
+  _addObserver(view) {
+    const observer = new WeakRef(view);
+    const registry = observerRegistry || (observerRegistry = new FinalizationRegistry(finalizeObserver));
+    registry.register(view, { store: new WeakRef(this), observer }, observer);
+    (this._observers || (this._observers = new Set())).add(observer);
+    return observer;
+  }
+
+  // ### `_removeObserver` unregisters a mutation observer.
+  _removeObserver(observer) {
+    observerRegistry.unregister(observer);
+    if (this._observers) {
+      this._observers.delete(observer);
+      if (this._observers.size === 0)
+        this._observers = null;
+    }
+  }
+
+  // ### `_notifyObservers` notifies observers of a mutation.
+  _notifyObservers(subjectId, predicateId, objectId, graphId, added) {
+    // Observers can remove themselves during Set iteration
+    for (const observer of this._observers) {
+      const view = observer.deref();
+      if (view)
+        view._onParentMutation(subjectId, predicateId, objectId, graphId, added);
+      else
+        // Finalization may be delayed; also prune collected views during notification.
+        this._removeObserver(observer);
+    }
+  }
+
   // ### `_uniqueEntities` returns a function that accepts an entity ID
   // and passes the corresponding entity to callback if it hasn't occurred before.
   _uniqueEntities(callback) {
@@ -435,6 +479,15 @@ export default class N3Store {
     // Convert terms to internal string representation
     graph = graph ? this._termToNewNumericId(graph) : 1;
 
+    // Map long IRIs to shared numeric identifiers before updating the indexes.
+    subject   = this._termToNewNumericId(subject);
+    predicate = this._termToNewNumericId(predicate);
+    object    = this._termToNewNumericId(object);
+    return this._addQuad(subject, predicate, object, graph);
+  }
+
+  // ### `_addQuad` adds a quad using identifiers from this store's entity index.
+  _addQuad(subject, predicate, object, graph) {
     // Find the graph that will contain the triple
     let graphItem = this._graphs[graph];
     // Create the graph if it doesn't exist yet
@@ -449,12 +502,12 @@ export default class N3Store {
       Object.freeze(graphItem);
     }
 
-    // Since entities can often be long IRIs, we avoid storing them in every index.
-    // Instead, we have a separate index that maps entities to numbers,
-    // which are then used as keys in the other indexes.
-    subject   = this._termToNewNumericId(subject);
-    predicate = this._termToNewNumericId(predicate);
-    object    = this._termToNewNumericId(object);
+    // Notify observers before inserting a new quad so snapshots retain their prior contents
+    if (this._observers !== null) {
+      if (hasInIndex(graphItem.subjects, subject, predicate, object))
+        return false;
+      this._notifyObservers(subject, predicate, object, graph, true);
+    }
 
     if (!this._addToIndex(graphItem.subjects,   subject,   predicate, object))
       return false;
@@ -510,17 +563,25 @@ export default class N3Store {
     // Convert terms to internal string representation
     graph = graph ? this._termToNumericId(graph) : 1;
 
-    // Find internal identifiers for all components
-    // and verify the quad exists.
+    if (!(subject   = subject && this._termToNumericId(subject)) ||
+        !(predicate = predicate && this._termToNumericId(predicate)) ||
+        !(object    = object && this._termToNumericId(object)))
+      return false;
+    return this._removeQuad(subject, predicate, object, graph);
+  }
+
+  // ### `_removeQuad` removes a quad using identifiers from this store's entity index.
+  _removeQuad(subject, predicate, object, graph) {
+    // Verify the quad exists before notifying observers or changing any indexes.
     const graphs = this._graphs;
-    let graphItem, subjects, predicates;
-    if (!(subject    = subject && this._termToNumericId(subject)) || !(predicate = predicate && this._termToNumericId(predicate)) ||
-        !(object     = object && this._termToNumericId(object))  || !(graphItem = graphs[graph])  ||
-        !(subjects   = graphItem.subjects[subject]) ||
-        !(predicates = subjects[predicate]) ||
-        !(object in predicates))
+    const graphItem = graphs[graph];
+    if (!graphItem || !hasInIndex(graphItem.subjects, subject, predicate, object))
       return false;
 
+    // Notify observers before the mutation
+    if (this._observers !== null)
+      this._notifyObservers(subject, predicate, object, graph, false);
+
     // Remove it from all indexes
     this._removeFromIndex(graphItem.subjects,   subject,   predicate, object);
     this._removeFromIndex(graphItem.predicates, predicate, object,    subject);
@@ -627,8 +688,13 @@ export default class N3Store {
   // Note: Since a DatasetCore is an unordered set, the order of the quads within the returned sequence is arbitrary.
   // Setting any field to `undefined` or `null` indicates a wildcard.
   // For backwards compatibility, the object return also implements the Readable stream interface.
-  match(subject, predicate, object, graph) {
-    return new DatasetCoreAndReadableStream(this, subject, predicate, object, graph, { entityIndex: this._entityIndex });
+  // `options.matchSemantics` controls how the view reacts to later mutations.
+  match(subject, predicate, object, graph, options = null) {
+    return new DatasetCoreAndReadableStream(this, subject, predicate, object, graph, {
+      entityIndex: this._entityIndex,
+      matchSemantics: options && options.matchSemantics !== undefined ?
+        options.matchSemantics : this._matchSemantics,
+    });
   }
 
   // ### `countQuads` returns the number of quads matching a pattern.
@@ -957,7 +1023,8 @@ export default class N3Store {
 
     if (Array.isArray(quads))
       this.addQuads(quads);
-    else if (quads instanceof N3Store && quads._entityIndex === this._entityIndex) {
+    // Index merging bypasses observer notifications
+    else if (this._observers === null && quads instanceof N3Store && quads._entityIndex === this._entityIndex) {
       if (quads._size !== 0) {
         this._graphs = merge(this._graphs, quads._graphs);
         this._size = null; // Invalidate the cached size
@@ -1015,7 +1082,7 @@ export default class N3Store {
    * @param graph     The optional exact graph to match.
    */
   deleteMatches(subject, predicate, object, graph) {
-    for (const quad of this.match(subject, predicate, object, graph))
+    for (const quad of this.match(subject, predicate, object, graph, { matchSemantics: 'lazy' }))
       this.removeQuad(quad);
     return this;
   }
@@ -1143,7 +1210,7 @@ export default class N3Store {
    * Returns a stream that contains all quads of the dataset.
    */
   toStream() {
-    return this.match();
+    return this.match(null, null, null, null, { matchSemantics: 'lazy' });
   }
 
   /**
@@ -1203,6 +1270,98 @@ function indexMatch(index, ids, depth = 0) {
   return target;
 }
 
+// Capture a read in the same index order as readQuads, without constructing RDF terms.
+// A flat list avoids allocating a Quad (and its terms) for every unread result.
+function snapshotMatch(store, subject, predicate, object, graph) {
+  const snapshot = { store, ids: [] };
+  const subjectId = subject && store._termToNumericId(subject);
+  const predicateId = predicate && store._termToNumericId(predicate);
+  const objectId = object && store._termToNumericId(object);
+  // Only active reads are frozen: bound terms and graphs have already resolved,
+  // and notifications run before deletion. Entity IDs are never removed.
+
+  // Keep this choice aligned with readQuads: changing order would repeat or skip
+  // results when an iterator resumes partway through its snapshot.
+  let indexName, key0, key1, key2, positions;
+  if (objectId && (subjectId || !predicateId)) {
+    indexName = 'objects';
+    [key0, key1, key2] = [objectId, subjectId, predicateId];
+    positions = [2, 0, 1];
+  }
+  else if (!subjectId && predicateId) {
+    indexName = 'predicates';
+    [key0, key1, key2] = [predicateId, objectId, subjectId];
+    positions = [1, 2, 0];
+  }
+  else {
+    indexName = 'subjects';
+    [key0, key1, key2] = [subjectId, predicateId, objectId];
+    positions = [0, 1, 2];
+  }
+
+  const graphs = store._getGraphs(graph), parts = [];
+  for (const graphId in graphs) {
+    const index = graphs[graphId][indexName];
+    const graphKey = Number(graphId);
+    for (const value0 in (key0 ? { [key0]: index[key0] } : index)) {
+      const index1 = index[value0];
+      if (!index1) continue; // eslint-disable-line no-continue
+      parts[positions[0]] = Number(value0);
+      for (const value1 in (key1 ? { [key1]: index1[key1] } : index1)) {
+        const index2 = index1[value1];
+        if (!index2) continue; // eslint-disable-line no-continue
+        parts[positions[1]] = Number(value1);
+        for (const value2 in (key2 ? (key2 in index2 ? { [key2]: null } : {}) : index2)) {
+          parts[positions[2]] = Number(value2);
+          snapshot.ids.push(parts[0], parts[1], parts[2], graphKey);
+        }
+      }
+    }
+  }
+  return snapshot;
+}
+
+// Skip already-yielded IDs in constant time; only materialize the requested tail.
+function* iterateSnapshot({ store, ids }, offset) {
+  const entities = store._entities;
+  let subject, predicate, object, graph;
+  let subjectId, predicateId, objectId, graphId;
+  for (let i = offset * 4; i < ids.length; i += 4) {
+    if (subjectId !== ids[i])
+      subject = store._termFromId(entities[subjectId = ids[i]]);
+    if (predicateId !== ids[i + 1])
+      predicate = store._termFromId(entities[predicateId = ids[i + 1]]);
+    if (objectId !== ids[i + 2])
+      object = store._termFromId(entities[objectId = ids[i + 2]]);
+    if (graphId !== ids[i + 3])
+      graph = store._termFromId(entities[graphId = ids[i + 3]]);
+    yield store._factory.quad(subject, predicate, object, graph);
+  }
+}
+
+function validateMatchSemantics(semantics = 'lazy') {
+  if (semantics !== 'lazy' && semantics !== 'snapshot' && semantics !== 'forwarded')
+    throw new Error(`Unknown matchSemantics: ${semantics}`);
+  if (semantics !== 'lazy' && (typeof WeakRef !== 'function' || typeof FinalizationRegistry !== 'function'))
+    throw new Error('Non-lazy matchSemantics requires WeakRef and FinalizationRegistry support');
+  return semantics;
+}
+
+// Returns the intersection of two quad patterns, or false if they conflict.
+function intersectMatchPatterns(left, right) {
+  const result = new Array(4);
+  for (let i = 0; i < 4; i++) {
+    const leftTerm = left[i], rightTerm = right[i];
+    if (leftTerm === null || leftTerm === undefined)
+      result[i] = rightTerm;
+    else if (rightTerm === null || rightTerm === undefined || termToId(leftTerm) === termToId(rightTerm))
+      result[i] = leftTerm;
+    else
+      return false;
+  }
+  return result;
+}
+
 /**
  * A class that implements both DatasetCore and Readable.
  */
@@ -1210,13 +1369,103 @@ class DatasetCoreAndReadableStream extends Readable {
   constructor(n3Store, subject, predicate, object, graph, options) {
     super({ objectMode: true });
     Object.assign(this, { n3Store, subject, predicate, object, graph, options });
+    const semantics = this._semantics = validateMatchSemantics(options.matchSemantics);
+
+    if (options.matchesNothing) {
+      this._matchesNothing = true;
+      this._filtered = new N3Store({ factory: n3Store._factory, entityIndex: options.entityIndex });
+    }
+
+    if (semantics !== 'lazy') {
+      // Active reads share a snapshot only when their source changes.
+      this._readers = null;
+      // Cache pattern ids on first use
+      this._subjectId = this._predicateId = this._objectId = this._graphId = undefined;
+      if (!this._matchesNothing) {
+        this._observer = n3Store._addObserver(this);
+      }
+    }
+  }
+
+  // ### `_matchesPattern` tests quad ids against this view.
+  _matchesPattern(subjectId, predicateId, objectId, graphId) {
+    const { subject, predicate, object, graph, n3Store } = this;
+    if (subject && subjectId !== (this._subjectId || (this._subjectId = n3Store._termToNumericId(subject))))
+      return false;
+    if (predicate && predicateId !== (this._predicateId || (this._predicateId = n3Store._termToNumericId(predicate))))
+      return false;
+    if (object && objectId !== (this._objectId || (this._objectId = n3Store._termToNumericId(object))))
+      return false;
+    return graph === null || graph === undefined ||
+      graphId === (this._graphId || (this._graphId =
+        graph === '' || isDefaultGraph(graph) ? 1 : n3Store._termToNumericId(graph)));
+  }
+
+  // ### `_matchesQuad` tests a Quad against this view.
+  _matchesQuad(quad) {
+    const { subject, predicate, object, graph } = this;
+    return !this._matchesNothing &&
+      (subject === null || subject === undefined || termToId(subject) === termToId(quad.subject)) &&
+      (predicate === null || predicate === undefined || termToId(predicate) === termToId(quad.predicate)) &&
+      (object === null || object === undefined || termToId(object) === termToId(quad.object)) &&
+      (graph === null || graph === undefined || termToId(graph) === termToId(quad.graph));
+  }
+
+  // ### `_assertMatchesPattern` rejects a Quad outside this view.
+  _assertMatchesPattern(quad) {
+    if (!this._matchesQuad(quad))
+      throw new Error('Quad does not match the forwarded view pattern');
+  }
+
+  // ### `_sourceIterator` returns an iterator over the current backing store.
+  _sourceIterator() {
+    return this._filtered ? this._filtered[Symbol.iterator]() :
+      this.n3Store.readQuads(this.subject, this.predicate, this.object, this.graph);
+  }
+
+  // ### `_freezeCurrentIterators` freezes only readers still using the live source.
+  _freezeCurrentIterators() {
+    if (this._readers) {
+      this._readers.snapshot = this._filtered ? snapshotMatch(this._filtered) :
+        snapshotMatch(this.n3Store, this.subject, this.predicate, this.object, this.graph);
+      // Each iterator retains its own group. New reads must see the new source;
+      // the view must not retain snapshots belonging to suspended or abandoned reads.
+      this._readers = null;
+    }
+  }
+
+  // ### `_onParentMutation` applies a parent mutation to this view.
+  _onParentMutation(subjectId, predicateId, objectId, graphId, added) {
+    if (!this._matchesPattern(subjectId, predicateId, objectId, graphId))
+      return;
+
+    this._freezeCurrentIterators();
+
+    // Keep using the parent until materialization
+    if (this._semantics === 'forwarded') {
+      if (this._filtered) {
+        if (added)
+          this._filtered._addQuad(subjectId, predicateId, objectId, graphId);
+        else
+          this._filtered._removeQuad(subjectId, predicateId, objectId, graphId);
+      }
+      return;
+    }
+
+    // Capture the pre-mutation snapshot
+    this._filtered = this.filtered;
   }
 
   get filtered() {
     if (!this._filtered) {
       const { n3Store, graph, object, predicate, subject } = this;
+      if (this._semantics !== 'lazy')
+        this._freezeCurrentIterators();
       const newStore = this._filtered = new N3Store({ factory: n3Store._factory, entityIndex: this.options.entityIndex });
 
+      if (this._semantics === 'snapshot')
+        this._detachObserver();
+
       let subjectId, predicateId, objectId;
 
       // Translate IRIs to internal index keys.
@@ -1273,7 +1522,42 @@ class DatasetCoreAndReadableStream extends Readable {
     }
   }
 
+  // ### `_destroy` closes the cached iterator.
+  _destroy(error, callback) {
+    if (this[ITERATOR]) {
+      this[ITERATOR].return();
+      this[ITERATOR] = null;
+    }
+    callback(error);
+  }
+
+  // ### `_detachObserver` stops observing the parent store.
+  _detachObserver() {
+    if (this._observer) {
+      this.n3Store._removeObserver(this._observer);
+      this._observer = null;
+    }
+  }
+
+  // ### `_detach` freezes the view and stops observing the parent.
+  _detach() {
+    this._filtered = this.filtered;
+    this._detachObserver();
+    // Lazy views deferred this state
+    if (this._semantics === 'lazy')
+      this._readers = null;
+    this._semantics = 'snapshot';
+    return this;
+  }
+
   addAll(quads) {
+    if (this._semantics === 'forwarded') {
+      for (const quad of quads) {
+        this._assertMatchesPattern(quad);
+        this.n3Store.addQuad(quad);
+      }
+      return this;
+    }
     return this.filtered.addAll(quads);
   }
 
@@ -1282,6 +1566,19 @@ class DatasetCoreAndReadableStream extends Readable {
   }
 
   deleteMatches(subject, predicate, object, graph) {
+    if (this._semantics === 'forwarded') {
+      // No deletion pattern can match a view with conflicting ancestor patterns.
+      if (this._matchesNothing)
+        throw new Error('Cannot delete from a conflicting forwarded view pattern');
+      const pattern = intersectMatchPatterns(
+        [this.subject, this.predicate, this.object, this.graph],
+        [subject, predicate, object, graph],
+      );
+      if (!pattern)
+        throw new Error('Deletion pattern does not match the forwarded view pattern');
+      this.n3Store.deleteMatches(...pattern);
+      return this;
+    }
     return this.filtered.deleteMatches(subject, predicate, object, graph);
   }
 
@@ -1294,19 +1591,41 @@ class DatasetCoreAndReadableStream extends Readable {
   }
 
   every(callback, subject, predicate, object, graph) {
-    return this.filtered.every(callback, subject, predicate, object, graph);
+    return this.filtered.every(this._semantics === 'forwarded' ?
+      quad => callback(quad, this) : callback, subject, predicate, object, graph);
   }
 
   filter(iteratee) {
-    return this.filtered.filter(iteratee);
+    return this.filtered.filter(this._semantics === 'forwarded' ?
+      quad => iteratee(quad, this) : iteratee);
   }
 
   forEach(callback, subject, predicate, object, graph) {
-    return this.filtered.forEach(callback, subject, predicate, object, graph);
+    return this.filtered.forEach(this._semantics === 'forwarded' ?
+      quad => callback(quad, this) : callback, subject, predicate, object, graph);
   }
 
   import(stream) {
-    return this.filtered.import(stream);
+    if (this._semantics !== 'forwarded')
+      return this.filtered.import(stream);
+
+    const view = this;
+    function onData(quad) {
+      try {
+        view._assertMatchesPattern(quad);
+        view.n3Store.addQuad(quad);
+      }
+      catch (error) {
+        // Stop this import; RDF/JS streams need not implement destroy()
+        stream.removeListener('data', onData);
+        if (typeof stream.destroy === 'function')
+          stream.destroy(error);
+        else
+          stream.emit('error', error);
+      }
+    }
+    stream.on('data', onData);
+    return stream;
   }
 
   intersection(other) {
@@ -1314,11 +1633,13 @@ class DatasetCoreAndReadableStream extends Readable {
   }
 
   map(iteratee) {
-    return this.filtered.map(iteratee);
+    return this.filtered.map(this._semantics === 'forwarded' ?
+      quad => iteratee(quad, this) : iteratee);
   }
 
   some(callback, subject, predicate, object, graph) {
-    return this.filtered.some(callback, subject, predicate, object, graph);
+    return this.filtered.some(this._semantics === 'forwarded' ?
+      quad => callback(quad, this) : callback, subject, predicate, object, graph);
   }
 
   toCanonical() {
@@ -1326,23 +1647,29 @@ class DatasetCoreAndReadableStream extends Readable {
   }
 
   toStream() {
+    if (this._semantics !== 'lazy')
+      // Use a fresh sync iterator instead of consuming this view's own readable stream.
+      return Readable.from(this[Symbol.iterator]());
     return this._filtered ?
       this._filtered.toStream()
-      : this.n3Store.match(this.subject, this.predicate, this.object, this.graph);
+      : this.n3Store.match(this.subject, this.predicate, this.object, this.graph, { matchSemantics: 'lazy' });
   }
 
   union(quads) {
     return this._filtered ?
       this._filtered.union(quads)
-      : this.n3Store.match(this.subject, this.predicate, this.object, this.graph).addAll(quads);
+      : this.n3Store.match(this.subject, this.predicate, this.object, this.graph, { matchSemantics: 'lazy' }).addAll(quads);
   }
 
   toArray() {
+    if (this._semantics !== 'lazy')
+      return [...this];
     return this._filtered ? this._filtered.toArray() : this.n3Store.getQuads(this.subject, this.predicate, this.object, this.graph);
   }
 
   reduce(callback, initialValue) {
-    return this.filtered.reduce(callback, initialValue);
+    return this.filtered.reduce(this._semantics === 'forwarded' ?
+      (accumulator, quad) => callback(accumulator, quad, this) : callback, initialValue);
   }
 
   toString() {
@@ -1350,10 +1677,20 @@ class DatasetCoreAndReadableStream extends Readable {
   }
 
   add(quad) {
+    if (this._semantics === 'forwarded') {
+      this._assertMatchesPattern(quad);
+      this.n3Store.addQuad(quad);
+      return this;
+    }
     return this.filtered.add(quad);
   }
 
   delete(quad) {
+    if (this._semantics === 'forwarded') {
+      this._assertMatchesPattern(quad);
+      this.n3Store.removeQuad(quad);
+      return this;
+    }
     return this.filtered.delete(quad);
   }
 
@@ -1361,12 +1698,61 @@ class DatasetCoreAndReadableStream extends Readable {
     return this.filtered.has(quad);
   }
 
-  match(subject, predicate, object, graph) {
-    return new DatasetCoreAndReadableStream(this.filtered, subject, predicate, object, graph, this.options);
+  match(subject, predicate, object, graph, options = null) {
+    const requestedSemantics = options && options.matchSemantics;
+    if (options && requestedSemantics !== undefined) {
+      validateMatchSemantics(requestedSemantics);
+      if (requestedSemantics !== this._semantics)
+        throw new Error(`Cannot override matchSemantics on a view: inherited "${this._semantics}", received "${requestedSemantics}"`);
+    }
+
+    if (this._semantics !== 'forwarded')
+      return new DatasetCoreAndReadableStream(this.filtered, subject, predicate, object, graph, {
+        entityIndex: this.options.entityIndex,
+        matchSemantics: this._semantics,
+      });
+
+    const pattern = !this._matchesNothing && intersectMatchPatterns(
+      [this.subject, this.predicate, this.object, this.graph],
+      [subject, predicate, object, graph],
+    );
+    const [matchedSubject, matchedPredicate, matchedObject, matchedGraph] = pattern || [null, null, null, null];
+    return new DatasetCoreAndReadableStream(
+      this.n3Store, matchedSubject, matchedPredicate, matchedObject, matchedGraph, {
+        entityIndex: this.options.entityIndex,
+        matchSemantics: 'forwarded',
+        matchesNothing: !pattern,
+      });
   }
 
   [Symbol.iterator]() {
-    return this._filtered ? this._filtered[Symbol.iterator]() :
-      this.n3Store.readQuads(this.subject, this.predicate, this.object, this.graph);
+    return this._semantics === 'lazy' ? this._sourceIterator() : this._iterateStable();
+  }
+
+  *_iterateStable() {
+    const readers = this._readers || (this._readers = { count: 0, snapshot: null });
+    const source = this._sourceIterator();
+    let yielded = 0;
+    readers.count++;
+    try {
+      while (!readers.snapshot) {
+        const { value, done } = source.next();
+        // A custom factory can mutate the store inside next(), even on its first call.
+        if (readers.snapshot || done)
+          break;
+        yielded++;
+        yield value;
+      }
+      if (readers.snapshot)
+        yield* iterateSnapshot(readers.snapshot, yielded);
+    }
+    finally {
+      source.return();
+      if (--readers.count === 0) {
+        readers.snapshot = null;
+        if (this._readers === readers)
+          this._readers = null;
+      }
+    }
   }
 }