@thomasfosterau/effect-rdf 0.0.0-stage → 0.1.0

package/src/Dataset.ts

@@ -0,0 +1,1085 @@
+/**
+ * Immutable, indexed RDF datasets.
+ *
+ * A `Dataset` is a persistent set of quads backed by Effect `HashMap`s, with
+ * per-position indexes so that pattern matching only scans the most
+ * selective index. Datasets implement `Equal` (set equality — use
+ * `Isomorphism.isomorphic` for blank-node-aware comparison), `Hash`,
+ * `Iterable<Quad>` and `Pipeable`.
+ *
+ * @since 0.1.0
+ */
+import * as Arr from 'effect/Array';
+import { dual } from 'effect/Function';
+import * as Equal from 'effect/Equal';
+import * as Graph from 'effect/Graph';
+import * as Hash from 'effect/Hash';
+import * as HashMap from 'effect/HashMap';
+import * as HashSet from 'effect/HashSet';
+import { NodeInspectSymbol, type Inspectable } from 'effect/Inspectable';
+import * as Iterable from 'effect/Iterable';
+import * as MutableHashMap from 'effect/MutableHashMap';
+import * as MutableHashSet from 'effect/MutableHashSet';
+import * as Option from 'effect/Option';
+import { pipeArguments, type Pipeable } from 'effect/Pipeable';
+import { hasProperty } from 'effect/Predicate';
+import * as Schema from 'effect/Schema';
+import * as SchemaTransformation from 'effect/SchemaTransformation';
+import { MAX_DATASET_SIZE } from './internal/arbitrary.ts';
+import { loop } from './internal/loop.ts';
+import * as Term from './Term.ts';
+import { pendingQuads } from './internal/pending.ts';
+import { rdf } from './Vocab.ts';
+
+/**
+ * @since 0.1.0
+ * @category symbols
+ */
+export const TypeId: unique symbol = Symbol.for('@thomasfosterau/effect-rdf/Dataset');
+
+/**
+ * @since 0.1.0
+ * @category symbols
+ */
+export type TypeId = typeof TypeId;
+
+type Index = HashMap.HashMap<string, HashMap.HashMap<string, Term.Quad>>;
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export interface Dataset extends Iterable<Term.Quad>, Equal.Equal, Pipeable, Inspectable {
+  readonly [TypeId]: TypeId;
+  readonly size: number;
+  /** @internal */
+  readonly quads: HashMap.HashMap<string, Term.Quad>;
+}
+
+/**
+ * A quad pattern. Omitted positions, `undefined` and variables match any
+ * term.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Pattern {
+  readonly subject?: Term.Subject | Term.Variable | undefined;
+  readonly predicate?: Term.Predicate | Term.Variable | undefined;
+  readonly object?: Term.Object | Term.Variable | undefined;
+  readonly graph?: Term.Graph | Term.Variable | undefined;
+}
+
+/** `isDataset` for a value already known to be an object. */
+const hasDatasetTypeId = (u: Equal.Equal | Iterable<Term.Quad>): u is Dataset => TypeId in u;
+
+type Spog = readonly [Index, Index, Index, Index];
+
+/**
+ * The indexes of the datasets that have been matched against, built on
+ * first use: parsing a document and serializing it never pays for them. A
+ * `WeakMap` rather than a field, so a dataset's own properties do not depend
+ * on whether it has been matched.
+ */
+const indexes = new WeakMap<Dataset, Spog>();
+
+/**
+ * A parser's dataset is often only iterated or serialized once, or not at
+ * all, so `fromIterable` keeps its quads (`pendingQuads`) and the persistent
+ * map is built the first time it is needed (a lookup, a match or an update),
+ * with the same contents.
+ */
+const pending = pendingQuads;
+
+/**
+ * The distinct quads of the datasets made by `fromIterable`, in the order
+ * first given: what such a dataset iterates (before and after its quad set
+ * is built), so that iterating, counting or serializing it never builds the
+ * persistent map.
+ */
+const ordered = new WeakMap<Dataset, ReadonlyArray<Term.Quad>>();
+
+/** Combines two hashes (a multiply-rotate step); `distinct` finishes them with `avalanche`. */
+const mix = (a: number, b: number): number => Math.imul((a << 5) | (a >>> 27), 0x9e3779b1) ^ b;
+
+/** The final mixing of a hash (MurmurHash3's), so that its low bits pick table slots well. */
+const avalanche = (h: number): number => {
+  let x = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
+  x = Math.imul(x ^ (x >>> 13), 0xc2b2ae35);
+  return x ^ (x >>> 16);
+};
+
+/**
+ * A hash of a subject or object (equal terms hash equally) that builds no
+ * key: a term's own hash, which IRIs, blank nodes and literals compute from
+ * their values and cache, and for a triple term, its parts'.
+ */
+const termHash = (t: Term.Term): number =>
+  t instanceof Term.Triple
+    ? mix(mix(termHash(t.subject), t.predicate[Hash.symbol]()), termHash(t.object))
+    : // IRIs, blank nodes and literals hash their values and cache the result, so a node a
+      // parser shares between statements (a description's subject) is hashed once
+      t[Hash.symbol]();
+
+/**
+ * A quad's hash for `distinct`: its predicate and graph, usually shared
+ * nodes, by their own cached hashes; its subject and object by `termHash`.
+ * Each position is hashed the same way for every quad, so equal quads hash
+ * equally.
+ */
+const quadHash = (q: Term.Quad): number =>
+  mix(
+    mix(mix(termHash(q.subject), q.predicate[Hash.symbol]()), termHash(q.object)),
+    q.graph[Hash.symbol](),
+  );
+
+/**
+ * The distinct quads of `quads` (equal keys), keeping the first of each in
+ * order: open addressing over their structural hashes, comparing keys only
+ * when two hashes are equal, so that no key is built for quads that differ.
+ */
+const distinct = (quads: ReadonlyArray<Term.Quad>): ReadonlyArray<Term.Quad> => {
+  const n = quads.length;
+  if (n < 2) return quads;
+  const mask = 2 ** Math.ceil(Math.log2(n * 2)) - 1;
+  const hashes = new Int32Array(mask + 1);
+  const slots = new Int32Array(mask + 1);
+  const out: Array<Term.Quad> = [];
+  quads.forEach((q, k) => {
+    const hash = avalanche(quadHash(q));
+    let i = hash & mask;
+    let duplicate = false;
+    // Linear probing: step to the next slot until an empty one or an equal quad
+    loop(() => {
+      const slot = slots[i] ?? 0;
+      if (slot === 0) return false;
+      if (hashes[i] === hash && (quads[slot - 1] ?? q).key === q.key) {
+        duplicate = true;
+        return false;
+      }
+      i = (i + 1) & mask;
+      return true;
+    });
+    if (duplicate) return;
+    hashes[i] = hash;
+    slots[i] = k + 1;
+    out.push(q);
+  });
+  return out.length === n ? quads : out;
+};
+
+/** The distinct quads, in order, of a dataset made by `fromIterable` (none for any other). */
+const orderedOf = (self: Dataset): Option.Option<ReadonlyArray<Term.Quad>> => {
+  const known = ordered.get(self);
+  if (known !== undefined) return Option.some(known);
+  const given = pending.get(self);
+  if (given === undefined) return Option.none();
+  const quads = distinct(given);
+  ordered.set(self, quads);
+  return Option.some(quads);
+};
+
+/** Builds a pending dataset's quad set, making it like any other dataset. */
+const materialize = (self: Dataset): HashMap.HashMap<string, Term.Quad> => {
+  const quads = buildQuads(Option.getOrElse(orderedOf(self), () => []));
+  pending.delete(self);
+  Object.defineProperty(self, 'quads', { value: quads, enumerable: true });
+  return quads;
+};
+
+const Proto: Omit<Dataset, 'size' | 'quads'> & Pick<Dataset, 'size' | 'quads'> = {
+  [TypeId]: TypeId,
+  // Only a pending dataset reaches these: any other has its own `quads` and `size`
+  get quads(): HashMap.HashMap<string, Term.Quad> {
+    // SAFETY: the getter is only ever called on a dataset made from this prototype.
+    return materialize(this);
+  },
+  get size(): number {
+    // SAFETY: as for `quads`.
+    const size = Option.getOrElse(orderedOf(this), () => []).length;
+    Object.defineProperty(this, 'size', { value: size, enumerable: true });
+    return size;
+  },
+  [Symbol.iterator](this: Dataset): Iterator<Term.Quad> {
+    // A dataset made by `fromIterable` iterates its quads in the order first given
+    return Option.getOrElse(orderedOf(this), () => HashMap.values(this.quads))[Symbol.iterator]();
+  },
+  [Equal.symbol](this: Dataset, that: Equal.Equal): boolean {
+    if (!hasDatasetTypeId(that) || that.size !== this.size) return false;
+    const theirs = that.quads;
+    return HashMap.every(this.quads, (_quad, key) => HashMap.has(theirs, key));
+  },
+  [Hash.symbol](this: Dataset): number {
+    return Hash.optimize(Iterable.reduce(this, 0, (h, q) => (h + Hash.hash(q)) | 0));
+  },
+  pipe() {
+    return pipeArguments(this, arguments);
+  },
+  toString(this: Dataset) {
+    return toNQuads(this);
+  },
+  toJSON(this: Dataset) {
+    return { _id: 'Dataset', size: this.size, quads: Array.from(this, (q) => q.toString()) };
+  },
+  [NodeInspectSymbol](this: Dataset) {
+    return this.toJSON();
+  },
+};
+
+const makeDataset = (quads: HashMap.HashMap<string, Term.Quad>): Dataset => {
+  // Own data properties, which shadow the prototype's getters for pending datasets
+  return Object.create(Proto, {
+    quads: { value: quads, enumerable: true },
+    size: { value: HashMap.size(quads), enumerable: true },
+  });
+};
+
+const emptyIndex: Index = HashMap.empty();
+
+const emptySpog: Spog = [emptyIndex, emptyIndex, emptyIndex, emptyIndex];
+
+/**
+ * @since 0.1.0
+ * @category guards
+ */
+export const isDataset = (u: unknown): u is Dataset => hasProperty(u, TypeId);
+
+/**
+ * @since 0.1.0
+ * @category constructors
+ */
+export const empty: Dataset = makeDataset(HashMap.empty());
+
+// -----------------------------------------------------------------------------
+// Mutation (internal builder)
+// -----------------------------------------------------------------------------
+
+/**
+ * A transient builder used by `mutate` to apply many updates efficiently.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Builder {
+  readonly add: (quad: Term.Quad) => Builder;
+  readonly addAll: (quads: Iterable<Term.Quad>) => Builder;
+  readonly remove: (quad: Term.Quad) => Builder;
+  readonly has: (quad: Term.Quad) => boolean;
+  readonly size: () => number;
+}
+
+/** The inner maps of one index made mutable during a batch, by term key. */
+type Transients = MutableHashMap.MutableHashMap<string, HashMap.HashMap<string, Term.Quad>>;
+
+const transients = (): Transients => MutableHashMap.empty();
+
+const positions = (q: Term.Quad): readonly [string, string, string, string] => [
+  q.subject.key,
+  q.predicate.key,
+  q.object.key,
+  q.graph.key,
+];
+
+/** Updates to a dataset's four indexes, applied in place until `finish`. */
+interface IndexBatch {
+  readonly add: (quad: Term.Quad, key: string) => void;
+  readonly remove: (quad: Term.Quad, key: string) => void;
+  readonly finish: () => Spog;
+}
+
+const indexBatch = (spog: Spog): IndexBatch => {
+  const idx: [Index, Index, Index, Index] = [
+    HashMap.beginMutation(spog[0]),
+    HashMap.beginMutation(spog[1]),
+    HashMap.beginMutation(spog[2]),
+    HashMap.beginMutation(spog[3]),
+  ];
+  // The inner maps this batch has made mutable, per position, so that adding
+  // a quad updates its four inner maps in place instead of copying a path of
+  // each (they are frozen again by `finish`).
+  const open: [Transients, Transients, Transients, Transients] = [
+    transients(),
+    transients(),
+    transients(),
+    transients(),
+  ];
+  const inner = (i: 0 | 1 | 2 | 3, termKey: string): HashMap.HashMap<string, Term.Quad> => {
+    const opened = open[i];
+    const known = MutableHashMap.get(opened, termKey);
+    if (Option.isSome(known)) return known.value;
+    const map = HashMap.beginMutation(
+      Option.getOrElse(HashMap.get(idx[i], termKey), () => HashMap.empty<string, Term.Quad>()),
+    );
+    // Stored in `idx[i]` by `close`, once the batch is done: setting it here,
+    // still equal to the map it copies, is a no-op on effect 4.0.x, whose
+    // `HashMap.set` keeps an existing value `Equal.equals` to the new one
+    MutableHashMap.set(opened, termKey, map);
+    return map;
+  };
+  // A mutable map is updated in place, so the results of `set` and `remove` are the map itself
+  const addAt = (i: 0 | 1 | 2 | 3, termKey: string, key: string, quad: Term.Quad): void => {
+    HashMap.set(inner(i, termKey), key, quad);
+  };
+  const removeAt = (i: 0 | 1 | 2 | 3, termKey: string, key: string): void => {
+    if (MutableHashMap.has(open[i], termKey) || HashMap.has(idx[i], termKey)) {
+      HashMap.remove(inner(i, termKey), key);
+    }
+  };
+  const close = (i: 0 | 1 | 2 | 3): void => {
+    MutableHashMap.forEach(open[i], (map, termKey) => {
+      HashMap.endMutation(map);
+      idx[i] =
+        HashMap.size(map) === 0
+          ? HashMap.remove(idx[i], termKey)
+          : HashMap.set(idx[i], termKey, map);
+    });
+  };
+  return {
+    add(quad, key) {
+      addAt(0, quad.subject.key, key, quad);
+      addAt(1, quad.predicate.key, key, quad);
+      addAt(2, quad.object.key, key, quad);
+      addAt(3, quad.graph.key, key, quad);
+    },
+    remove(quad, key) {
+      removeAt(0, quad.subject.key, key);
+      removeAt(1, quad.predicate.key, key);
+      removeAt(2, quad.object.key, key);
+      removeAt(3, quad.graph.key, key);
+    },
+    finish() {
+      close(0);
+      close(1);
+      close(2);
+      close(3);
+      return [
+        HashMap.endMutation(idx[0]),
+        HashMap.endMutation(idx[1]),
+        HashMap.endMutation(idx[2]),
+        HashMap.endMutation(idx[3]),
+      ];
+    },
+  };
+};
+
+/** The indexes of a dataset, built the first time they are needed. */
+const indexesOf = (self: Dataset): Spog => {
+  const built = indexes.get(self);
+  if (built !== undefined) return built;
+  const batch = indexBatch(emptySpog);
+  HashMap.forEach(self.quads, (quad, key) => batch.add(quad, key));
+  const spog = batch.finish();
+  indexes.set(self, spog);
+  return spog;
+};
+
+/**
+ * Applies a batch of updates to a dataset using a transient builder.
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export const mutate: {
+  (f: (builder: Builder) => void): (self: Dataset) => Dataset;
+  (self: Dataset, f: (builder: Builder) => void): Dataset;
+} = dual(2, (self: Dataset, f: (builder: Builder) => void): Dataset => {
+  let quads = HashMap.beginMutation(self.quads);
+  // Indexes already built are kept up to date; otherwise the result builds its own when matched
+  const spog = indexes.get(self);
+  const batch = spog === undefined ? undefined : indexBatch(spog);
+  const builder: Builder = {
+    add(quad) {
+      const key = quad.key;
+      // One lookup: `set` on the mutable map grows it only if the quad is new. A duplicate
+      // replaces the stored quad with an equal one.
+      const before = HashMap.size(quads);
+      quads = HashMap.set(quads, key, quad);
+      if (HashMap.size(quads) !== before) batch?.add(quad, key);
+      return builder;
+    },
+    addAll(iterable) {
+      Iterable.forEach(iterable, (q) => {
+        builder.add(q);
+      });
+      return builder;
+    },
+    remove(quad) {
+      const key = quad.key;
+      if (!HashMap.has(quads, key)) return builder;
+      quads = HashMap.remove(quads, key);
+      batch?.remove(quad, key);
+      return builder;
+    },
+    has: (quad) => HashMap.has(quads, quad.key),
+    size: () => HashMap.size(quads),
+  };
+  f(builder);
+  const result = makeDataset(HashMap.endMutation(quads));
+  if (batch !== undefined) indexes.set(result, batch.finish());
+  return result;
+});
+
+// -----------------------------------------------------------------------------
+// Constructors
+// -----------------------------------------------------------------------------
+
+/**
+ * @since 0.1.0
+ * @category constructors
+ */
+export const fromIterable = (quads: Iterable<Term.Quad>): Dataset => {
+  if (hasDatasetTypeId(quads)) return quads;
+  const self: Dataset = Object.create(Proto);
+  pending.set(self, Array.from(quads));
+  return self;
+};
+
+/** The quad set of `quads`, deduplicated by key (the first of equal quads is kept). */
+const buildQuads = (quads: ReadonlyArray<Term.Quad>): HashMap.HashMap<string, Term.Quad> =>
+  mutate(empty, (b) => b.addAll(quads)).quads;
+
+/**
+ * @since 0.1.0
+ * @category constructors
+ */
+export const make = (...quads: ReadonlyArray<Term.Quad>): Dataset => fromIterable(quads);
+
+/**
+ * Creates a dataset from triples, placing them in the given graph (the
+ * default graph when omitted).
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const fromTriples = (
+  triples: Iterable<Term.Triple>,
+  graph: Term.Graph = Term.defaultGraph,
+): Dataset =>
+  mutate(empty, (b) => {
+    Iterable.forEach(triples, (t) => {
+      b.add(new Term.Quad(t.subject, t.predicate, t.object, graph));
+    });
+  });
+
+// -----------------------------------------------------------------------------
+// Updates
+// -----------------------------------------------------------------------------
+
+/**
+ * @since 0.1.0
+ * @category combinators
+ */
+export const add: {
+  (quad: Term.Quad): (self: Dataset) => Dataset;
+  (self: Dataset, quad: Term.Quad): Dataset;
+} = dual(2, (self: Dataset, quad: Term.Quad): Dataset =>
+  HashMap.has(self.quads, quad.key) ? self : mutate(self, (b) => b.add(quad)),
+);
+
+/**
+ * @since 0.1.0
+ * @category combinators
+ */
+export const addAll: {
+  (quads: Iterable<Term.Quad>): (self: Dataset) => Dataset;
+  (self: Dataset, quads: Iterable<Term.Quad>): Dataset;
+} = dual(2, (self: Dataset, quads: Iterable<Term.Quad>): Dataset =>
+  mutate(self, (b) => b.addAll(quads)),
+);
+
+/**
+ * @since 0.1.0
+ * @category combinators
+ */
+export const remove: {
+  (quad: Term.Quad): (self: Dataset) => Dataset;
+  (self: Dataset, quad: Term.Quad): Dataset;
+} = dual(2, (self: Dataset, quad: Term.Quad): Dataset =>
+  HashMap.has(self.quads, quad.key) ? mutate(self, (b) => b.remove(quad)) : self,
+);
+
+/**
+ * Removes every quad matching a pattern.
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export const removeMatches: {
+  (pattern: Pattern): (self: Dataset) => Dataset;
+  (self: Dataset, pattern: Pattern): Dataset;
+} = dual(2, (self: Dataset, pattern: Pattern): Dataset => {
+  const matches = match(self, pattern);
+  return Arr.isReadonlyArrayEmpty(matches) ? self : mutate(self, (b) => matches.forEach(b.remove));
+});
+
+// -----------------------------------------------------------------------------
+// Queries
+// -----------------------------------------------------------------------------
+
+/**
+ * @since 0.1.0
+ * @category predicates
+ */
+export const has: {
+  (quad: Term.Quad): (self: Dataset) => boolean;
+  (self: Dataset, quad: Term.Quad): boolean;
+} = dual(2, (self: Dataset, quad: Term.Quad): boolean => HashMap.has(self.quads, quad.key));
+
+/**
+ * @since 0.1.0
+ * @category predicates
+ */
+export const isEmpty = (self: Dataset): boolean => self.size === 0;
+
+/** A position of a quad: subject, predicate, object or graph (the index of its `Spog` index). */
+type Position = 0 | 1 | 2 | 3;
+
+/** A bound position of a pattern, with the key its term must have. */
+interface Check {
+  readonly position: Position;
+  readonly key: string;
+}
+
+/** The bound positions of a pattern (omitted positions and variables match any term). */
+const checksOf = (pattern: Pattern): ReadonlyArray<Check> => {
+  const checks: Array<Check> = [];
+  const at = (position: Position, t: Pattern[keyof Pattern]): void => {
+    if (t !== undefined && !Term.isVariable(t)) checks.push({ position, key: t.key });
+  };
+  at(0, pattern.subject);
+  at(1, pattern.predicate);
+  at(2, pattern.object);
+  at(3, pattern.graph);
+  return checks;
+};
+
+/**
+ * Returns all quads matching a pattern, using the most selective index.
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export const match: {
+  (pattern: Pattern): (self: Dataset) => ReadonlyArray<Term.Quad>;
+  (self: Dataset, pattern: Pattern): ReadonlyArray<Term.Quad>;
+} = dual(2, (self: Dataset, pattern: Pattern): ReadonlyArray<Term.Quad> => {
+  const checks = checksOf(pattern);
+  let candidates: Option.Option<HashMap.HashMap<string, Term.Quad>> = Option.none();
+  let candidateSize = Infinity;
+  // The smallest inner map of the bound positions; none of them holding the term matches nothing
+  const missing = checks.some(({ position, key }) => {
+    const inner = HashMap.get(indexesOf(self)[position], key);
+    if (Option.isNone(inner)) return true;
+    const size = HashMap.size(inner.value);
+    if (size < candidateSize) {
+      candidates = inner;
+      candidateSize = size;
+    }
+    return false;
+  });
+  if (missing) return [];
+  const source = Option.getOrElse(candidates, () => self.quads);
+  const out: Array<Term.Quad> = [];
+  if (checks.length > 1) {
+    HashMap.forEach(source, (q) => {
+      const ks = positions(q);
+      if (checks.every(({ position, key }) => ks[position] === key)) out.push(q);
+    });
+  } else {
+    HashMap.forEach(source, (q) => {
+      out.push(q);
+    });
+  }
+  return out;
+});
+
+/**
+ * Counts the quads matching a pattern.
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export const count: {
+  (pattern: Pattern): (self: Dataset) => number;
+  (self: Dataset, pattern: Pattern): number;
+} = dual(2, (self: Dataset, pattern: Pattern): number => match(self, pattern).length);
+
+/**
+ * Returns a dataset containing only the quads matching a pattern.
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export const filterMatches: {
+  (pattern: Pattern): (self: Dataset) => Dataset;
+  (self: Dataset, pattern: Pattern): Dataset;
+} = dual(2, (self: Dataset, pattern: Pattern): Dataset => fromIterable(match(self, pattern)));
+
+/**
+ * The objects of all quads with the given subject and predicate (in any
+ * graph unless one is specified).
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export const objectsOf = (
+  self: Dataset,
+  subject: Term.Subject,
+  predicate: Term.Predicate,
+  graph?: Term.Graph,
+): ReadonlyArray<Term.Object> =>
+  uniqueTerms(match(self, { subject, predicate, graph }).map((q) => q.object));
+
+/**
+ * The first object of a subject/predicate pair, if any.
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export const objectOf = (
+  self: Dataset,
+  subject: Term.Subject,
+  predicate: Term.Predicate,
+  graph?: Term.Graph,
+): Option.Option<Term.Object> =>
+  Option.fromNullishOr(match(self, { subject, predicate, graph })[0]?.object);
+
+/**
+ * The subjects of all quads with the given predicate and object.
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export const subjectsOf = (
+  self: Dataset,
+  predicate: Term.Predicate,
+  object: Term.Object,
+  graph?: Term.Graph,
+): ReadonlyArray<Term.Subject> =>
+  uniqueTerms(match(self, { predicate, object, graph }).map((q) => q.subject));
+
+const uniqueTerms = <T extends Term.Term>(terms: ReadonlyArray<T>): ReadonlyArray<T> => {
+  if (terms.length < 2) return terms;
+  return uniqueByKey(terms);
+};
+
+/** The first of each group of values with equal keys, in order. */
+const uniqueByKey = <T extends { readonly key: string }>(values: Iterable<T>): Array<T> => {
+  const seen = MutableHashMap.empty<string, T>();
+  Iterable.forEach(values, (t) => {
+    if (!MutableHashMap.has(seen, t.key)) MutableHashMap.set(seen, t.key, t);
+  });
+  return Arr.fromIterable(MutableHashMap.values(seen));
+};
+
+const termsAt = <T extends Term.Term>(
+  self: Dataset,
+  position: Position,
+  pick: (q: Term.Quad) => T,
+): ReadonlyArray<T> =>
+  // An inner map is removed from the index when its last quad goes, so each holds one
+  Arr.flatMap(Arr.fromIterable(HashMap.values(indexesOf(self)[position])), (inner) =>
+    Arr.fromOption(Option.map(Iterable.head(HashMap.values(inner)), pick)),
+  );
+
+/**
+ * All distinct subjects.
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export const subjects = (self: Dataset): ReadonlyArray<Term.Subject> =>
+  termsAt(self, 0, (q) => q.subject);
+
+/**
+ * All distinct predicates.
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export const predicates = (self: Dataset): ReadonlyArray<Term.Predicate> =>
+  termsAt(self, 1, (q) => q.predicate);
+
+/**
+ * All distinct objects.
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export const objects = (self: Dataset): ReadonlyArray<Term.Object> =>
+  termsAt(self, 2, (q) => q.object);
+
+/**
+ * All distinct graph names (including the default graph if it is non-empty).
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export const graphs = (self: Dataset): ReadonlyArray<Term.Graph> =>
+  termsAt(self, 3, (q) => q.graph);
+
+/**
+ * The quads of one graph.
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export const graph: {
+  (graph: Term.Graph): (self: Dataset) => Dataset;
+  (self: Dataset, graph: Term.Graph): Dataset;
+} = dual(2, (self: Dataset, graphName: Term.Graph): Dataset =>
+  filterMatches(self, { graph: graphName }),
+);
+
+/**
+ * The triples of the dataset, ignoring graph names (duplicates across graphs
+ * are merged).
+ *
+ * @since 0.1.0
+ * @category conversions
+ */
+export const triples = (self: Dataset): ReadonlyArray<Term.Triple> => {
+  return uniqueByKey(Iterable.map(self, (q) => q.triple));
+};
+
+/**
+ * Moves every quad into a single graph.
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export const withGraph: {
+  (graph: Term.Graph): (self: Dataset) => Dataset;
+  (self: Dataset, graph: Term.Graph): Dataset;
+} = dual(2, (self: Dataset, graphName: Term.Graph): Dataset =>
+  fromIterable(Array.from(self, (q) => new Term.Quad(q.subject, q.predicate, q.object, graphName))),
+);
+
+/**
+ * Reads an RDF collection (`rdf:first`/`rdf:rest` list) starting at `head`.
+ * Returns `None` if the list is malformed (missing or multiple `first`/`rest`
+ * values, or cyclic).
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export const list = (
+  self: Dataset,
+  head: Term.Object,
+  graphName?: Term.Graph,
+): Option.Option<ReadonlyArray<Term.Object>> => {
+  const items: Array<Term.Object> = [];
+  const seen = MutableHashSet.empty<string>();
+  let node: Term.Object = head;
+  let wellFormed = true;
+  // Follow `rdf:rest` to `rdf:nil`, stopping at a literal, a cycle or a node without one value each
+  loop(() => {
+    const current = node;
+    if (Term.isNamedNode(current) && current.value === rdf.nil.value) return false;
+    if (Term.isLiteral(current) || MutableHashSet.has(seen, current.key)) {
+      wellFormed = false;
+      return false;
+    }
+    MutableHashSet.add(seen, current.key);
+    const first = objectsOf(self, current, rdf.first, graphName);
+    const rest = objectsOf(self, current, rdf.rest, graphName);
+    if (
+      !Arr.isReadonlyArrayNonEmpty(first) ||
+      !Arr.isReadonlyArrayNonEmpty(rest) ||
+      first.length !== 1 ||
+      rest.length !== 1
+    ) {
+      wellFormed = false;
+      return false;
+    }
+    items.push(first[0]);
+    node = rest[0];
+    return true;
+  });
+  return wellFormed ? Option.some(items) : Option.none();
+};
+
+// -----------------------------------------------------------------------------
+// Set operations and folds
+// -----------------------------------------------------------------------------
+
+/**
+ * @since 0.1.0
+ * @category combinators
+ */
+export const union: {
+  (that: Dataset): (self: Dataset) => Dataset;
+  (self: Dataset, that: Dataset): Dataset;
+} = dual(2, (self: Dataset, that: Dataset): Dataset =>
+  self.size >= that.size ? addAll(self, that) : addAll(that, self),
+);
+
+/**
+ * @since 0.1.0
+ * @category combinators
+ */
+export const intersection: {
+  (that: Dataset): (self: Dataset) => Dataset;
+  (self: Dataset, that: Dataset): Dataset;
+} = dual(2, (self: Dataset, that: Dataset): Dataset => filter(self, (q) => has(that, q)));
+
+/**
+ * @since 0.1.0
+ * @category combinators
+ */
+export const difference: {
+  (that: Dataset): (self: Dataset) => Dataset;
+  (self: Dataset, that: Dataset): Dataset;
+} = dual(2, (self: Dataset, that: Dataset): Dataset =>
+  mutate(self, (b) => {
+    Iterable.forEach(that, (q) => {
+      b.remove(q);
+    });
+  }),
+);
+
+/**
+ * @since 0.1.0
+ * @category combinators
+ */
+export const filter: {
+  (predicate: (quad: Term.Quad) => boolean): (self: Dataset) => Dataset;
+  (self: Dataset, predicate: (quad: Term.Quad) => boolean): Dataset;
+} = dual(2, (self: Dataset, predicate: (quad: Term.Quad) => boolean): Dataset =>
+  mutate(empty, (b) => {
+    Iterable.forEach(self, (q) => {
+      if (predicate(q)) b.add(q);
+    });
+  }),
+);
+
+/**
+ * @since 0.1.0
+ * @category combinators
+ */
+export const map: {
+  (f: (quad: Term.Quad) => Term.Quad): (self: Dataset) => Dataset;
+  (self: Dataset, f: (quad: Term.Quad) => Term.Quad): Dataset;
+} = dual(2, (self: Dataset, f: (quad: Term.Quad) => Term.Quad): Dataset =>
+  mutate(empty, (b) => {
+    Iterable.forEach(self, (q) => {
+      b.add(f(q));
+    });
+  }),
+);
+
+/**
+ * @since 0.1.0
+ * @category combinators
+ */
+export const flatMap: {
+  (f: (quad: Term.Quad) => Iterable<Term.Quad>): (self: Dataset) => Dataset;
+  (self: Dataset, f: (quad: Term.Quad) => Iterable<Term.Quad>): Dataset;
+} = dual(2, (self: Dataset, f: (quad: Term.Quad) => Iterable<Term.Quad>): Dataset =>
+  mutate(empty, (b) => {
+    Iterable.forEach(self, (q) => {
+      b.addAll(f(q));
+    });
+  }),
+);
+
+/**
+ * @since 0.1.0
+ * @category folding
+ */
+export const reduce: {
+  <B>(initial: B, f: (acc: B, quad: Term.Quad) => B): (self: Dataset) => B;
+  <B>(self: Dataset, initial: B, f: (acc: B, quad: Term.Quad) => B): B;
+} = dual(3, <B>(self: Dataset, initial: B, f: (acc: B, quad: Term.Quad) => B): B =>
+  Iterable.reduce(self, initial, (acc, q) => f(acc, q)),
+);
+
+/**
+ * @since 0.1.0
+ * @category predicates
+ */
+export const some: {
+  (predicate: (quad: Term.Quad) => boolean): (self: Dataset) => boolean;
+  (self: Dataset, predicate: (quad: Term.Quad) => boolean): boolean;
+} = dual(2, (self: Dataset, predicate: (quad: Term.Quad) => boolean): boolean =>
+  Iterable.some(self, (q) => predicate(q)),
+);
+
+/**
+ * @since 0.1.0
+ * @category predicates
+ */
+export const every: {
+  (predicate: (quad: Term.Quad) => boolean): (self: Dataset) => boolean;
+  (self: Dataset, predicate: (quad: Term.Quad) => boolean): boolean;
+} = dual(
+  2,
+  (self: Dataset, predicate: (quad: Term.Quad) => boolean): boolean =>
+    !Iterable.some(self, (q) => !predicate(q)),
+);
+
+/**
+ * Whether every quad of `self` is in `that`.
+ *
+ * @since 0.1.0
+ * @category predicates
+ */
+export const isSubset: {
+  (that: Dataset): (self: Dataset) => boolean;
+  (self: Dataset, that: Dataset): boolean;
+} = dual(2, (self: Dataset, that: Dataset): boolean => every(self, (q) => has(that, q)));
+
+// -----------------------------------------------------------------------------
+// Conversions
+// -----------------------------------------------------------------------------
+
+/**
+ * @since 0.1.0
+ * @category conversions
+ */
+export const toArray = (self: Dataset): ReadonlyArray<Term.Quad> => Array.from(self);
+
+/**
+ * The quads in a deterministic order (graph, subject, predicate, object).
+ *
+ * @since 0.1.0
+ * @category conversions
+ */
+export const toSortedArray = (self: Dataset): ReadonlyArray<Term.Quad> =>
+  Arr.sort(self, Term.compareQuads);
+
+/**
+ * Serialises to canonical, sorted N-Quads (one statement per line).
+ *
+ * @since 0.1.0
+ * @category conversions
+ */
+export const toNQuads = (self: Dataset): string =>
+  toSortedArray(self)
+    .map((q) => `${q.toString()}\n`)
+    .join('');
+
+/**
+ * Schema of a dataset; its JSON codec is an array of `TermJson.Quad`s in
+ * `toSortedArray` order, so encoding is deterministic.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const DatasetSchema: Schema.declare<Dataset> = Schema.declare(isDataset, {
+  identifier: 'Dataset',
+  // An array of JSON quads in `toSortedArray` order, so encoding is deterministic.
+  toCodecJson: () =>
+    Schema.link<Dataset>()(
+      Schema.Array(Term.QuadSchema),
+      SchemaTransformation.transform({ decode: fromIterable, encode: toSortedArray }),
+    ),
+  // Up to a dozen generated quads, whose terms are drawn from small pools so they share
+  // subjects, objects and graphs.
+  toCodecArbitrary: () =>
+    Schema.link<Dataset>()(
+      Schema.Array(Term.QuadSchema).check(Schema.isMaxLength(MAX_DATASET_SIZE)),
+      SchemaTransformation.transform({ decode: fromIterable, encode: toSortedArray }),
+    ),
+});
+
+/**
+ * The type `DatasetSchema` decodes to.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export type DatasetSchema = typeof DatasetSchema.Type;
+
+// -----------------------------------------------------------------------------
+// Graph algorithms
+// -----------------------------------------------------------------------------
+
+/**
+ * Options for `toGraph`.
+ *
+ * @since 0.1.0
+ * @category graphs
+ */
+export interface ToGraphOptions {
+  /** Only these predicates become edges (e.g. `[rdfs.subClassOf]`); all of them when omitted. */
+  readonly predicates?: ReadonlyArray<Term.NamedNode> | undefined;
+  /** Only quads in this graph; every graph when omitted. */
+  readonly graph?: Term.Graph | undefined;
+  /** Whether literal objects become nodes (default `false`: their quads are left out). */
+  readonly literals?: boolean | undefined;
+}
+
+/**
+ * A dataset as an `effect/Graph` directed graph, with the lookup from terms
+ * to node indices that graph algorithms start from.
+ *
+ * @since 0.1.0
+ * @category graphs
+ */
+export interface TermGraph {
+  /** Nodes are the subjects and objects; each quad is an edge labelled with its predicate. */
+  readonly graph: Graph.DirectedGraph<Term.Subject | Term.Object, Term.NamedNode>;
+  /** Each term's node index. */
+  readonly nodes: HashMap.HashMap<Term.Subject | Term.Object, Graph.NodeIndex>;
+}
+
+/**
+ * Converts a dataset to an `effect/Graph` directed graph for graph
+ * algorithms — topological order of a class hierarchy, cycle detection,
+ * shortest paths, reachability, connected components. Every subject and
+ * object becomes one node (equal terms share it) and every quad an edge
+ * from its subject to its object, labelled with its predicate; triple terms
+ * are nodes, not expanded.
+ *
+ * @since 0.1.0
+ * @category graphs
+ */
+export const toGraph = (self: Dataset, options: ToGraphOptions = {}): TermGraph => {
+  const keep =
+    options.predicates === undefined ? undefined : HashSet.fromIterable(options.predicates);
+  const edges = Arr.filter(
+    options.graph === undefined ? Arr.fromIterable(self) : match(self, { graph: options.graph }),
+    (q) =>
+      (keep === undefined || HashSet.has(keep, q.predicate)) &&
+      (options.literals === true || !Term.isLiteral(q.object)),
+  );
+  let nodes = HashMap.empty<Term.Subject | Term.Object, Graph.NodeIndex>();
+  const directed = Graph.directed<Term.Subject | Term.Object, Term.NamedNode>((mutable) => {
+    // Equal terms share a node: `nodes` is keyed by term value.
+    const nodeOf = (term: Term.Subject | Term.Object): Graph.NodeIndex =>
+      Option.getOrElse(HashMap.get(nodes, term), () => {
+        const added = Graph.addNode(mutable, term);
+        nodes = HashMap.set(nodes, term, added);
+        return added;
+      });
+    Arr.forEach(edges, (q) => {
+      Graph.addEdge(mutable, nodeOf(q.subject), nodeOf(q.object), q.predicate);
+    });
+    return undefined;
+  });
+  return { graph: directed, nodes };
+};
+
+/**
+ * Converts a directed graph whose nodes are terms and whose edges are
+ * predicates back to a dataset: each edge becomes a quad in `graphName` (the
+ * default graph when omitted). Edges from a node that cannot be a subject
+ * (a literal) are left out.
+ *
+ * @since 0.1.0
+ * @category graphs
+ */
+export const fromGraph = (
+  source: Graph.DirectedGraph<Term.Subject | Term.Object, Term.NamedNode>,
+  graphName: Term.Graph = Term.defaultGraph,
+): Dataset =>
+  fromIterable(
+    Arr.flatMap(Arr.fromIterable(Graph.edges(source)), ([, edge]) => {
+      const subject = Graph.getNode(source, edge.source);
+      const object = Graph.getNode(source, edge.target);
+      return Option.isSome(subject) && Option.isSome(object) && Term.isSubject(subject.value)
+        ? [Term.quad(subject.value, edge.data, object.value, graphName)]
+        : [];
+    }),
+  );