@thomasfosterau/effect-rdf 0.0.0-stage → 0.1.0

package/src/Iri.ts

@@ -0,0 +1,322 @@
+/**
+ * IRI utilities: RFC 3986 reference resolution, relativisation and
+ * validation.
+ *
+ * @since 0.1.0
+ */
+import * as Equal from 'effect/Equal';
+import * as Str from 'effect/String';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import { loop } from './internal/loop.ts';
+
+interface Parts {
+  readonly scheme: Option.Option<string>;
+  readonly authority: Option.Option<string>;
+  readonly path: string;
+  readonly query: Option.Option<string>;
+  readonly fragment: Option.Option<string>;
+}
+
+const PARTS =
+  /^(?:([A-Za-z][A-Za-z0-9+.-]*):)?(?:\/\/([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?$/s;
+
+const parse = (iri: string): Parts => {
+  // Every part of the pattern is optional, so it matches any string
+  const m = PARTS.exec(iri) ?? [];
+  return {
+    scheme: Option.fromUndefinedOr(m[1]),
+    authority: Option.fromUndefinedOr(m[2]),
+    path: m[3] ?? '',
+    query: Option.fromUndefinedOr(m[4]),
+    fragment: Option.fromUndefinedOr(m[5]),
+  };
+};
+
+// A document resolves many references against one base, so the last base's
+// parts are kept. `Parts` are never mutated once parsed.
+let lastBase = '';
+let lastBaseParts: Parts = parse('');
+
+const parseBase = (base: string): Parts => {
+  if (base !== lastBase) {
+    lastBaseParts = parse(base);
+    lastBase = base;
+  }
+  return lastBaseParts;
+};
+
+/** `part` between `before` and `after`, or nothing when it is absent. */
+const affix = (part: Option.Option<string>, before: string, after: string): string =>
+  Option.match(part, { onNone: () => '', onSome: (v) => `${before}${v}${after}` });
+
+const recompose = (p: Parts): string =>
+  affix(p.scheme, '', ':') +
+  affix(p.authority, '//', '') +
+  p.path +
+  affix(p.query, '?', '') +
+  affix(p.fragment, '#', '');
+
+// A `.` or `..` segment: the only thing `removeDotSegments` changes.
+const DOT_SEGMENT = /(?:^|\/)\.\.?(?:\/|$)/;
+
+/**
+ * Removes `.` and `..` segments from a path (RFC 3986 §5.2.4).
+ *
+ * @since 0.1.0
+ */
+export const removeDotSegments = (path: string): string => {
+  // Most paths have no dot segment, and the algorithm leaves those unchanged.
+  if (!DOT_SEGMENT.test(path)) return path;
+  let input = path;
+  const output: Array<string> = [];
+  loop(() => {
+    if (!Str.isNonEmpty(input)) return false;
+    if (input.startsWith('../')) input = input.slice(3);
+    else if (input.startsWith('./')) input = input.slice(2);
+    else if (input.startsWith('/./')) input = input.slice(2);
+    else if (input === '/.') input = '/';
+    else if (input.startsWith('/../')) {
+      input = input.slice(3);
+      output.pop();
+    } else if (input === '/..') {
+      input = '/';
+      output.pop();
+    } else if (input === '.' || input === '..') input = '';
+    else {
+      const start = input.startsWith('/') ? 1 : 0;
+      const next = input.indexOf('/', start);
+      const segment = next === -1 ? input : input.slice(0, next);
+      output.push(segment);
+      input = next === -1 ? '' : input.slice(next);
+    }
+    return true;
+  });
+  return output.join('');
+};
+
+const merge = (base: Parts, ref: string): string => {
+  if (Option.isSome(base.authority) && base.path === '') return `/${ref}`;
+  const i = base.path.lastIndexOf('/');
+  return i === -1 ? ref : base.path.slice(0, i + 1) + ref;
+};
+
+// Hoisted: a regex literal makes a new `RegExp` each time it is evaluated.
+const SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+
+/**
+ * Whether a string is an absolute IRI (has a scheme).
+ *
+ * @since 0.1.0
+ */
+export const isAbsolute = (iri: string): boolean => SCHEME.test(iri);
+
+const SCHEME_THEN_PATH = /^[A-Za-z][A-Za-z0-9+.-]*:(?!\.)/;
+
+/**
+ * Whether `iri` has a scheme and no `.` or `..` segment anywhere, without
+ * splitting it into its parts: such a reference resolves to itself
+ * (RFC 3986 §5.2.2), and most references in a document are like that. A
+ * `/.` anywhere (even in the query or fragment) or a path starting with `.`
+ * sends the reference down the full algorithm.
+ */
+const isPlainAbsolute = (iri: string): boolean => SCHEME_THEN_PATH.test(iri) && !iri.includes('/.');
+
+/**
+ * Resolves a (possibly relative) IRI reference against a base IRI, following
+ * RFC 3986 §5.2.
+ *
+ * @since 0.1.0
+ */
+export const resolve = (reference: string, base: string | undefined): string => {
+  if (base === undefined || base === '') return reference;
+  if (isPlainAbsolute(reference)) return reference;
+  const r = parse(reference);
+  // An absolute reference without dot segments resolves to itself (§5.2.2:
+  // only its path is rewritten, by `removeDotSegments`).
+  if (Option.isSome(r.scheme) && !DOT_SEGMENT.test(r.path)) return reference;
+  const b = parseBase(base);
+  const fragment = r.fragment;
+  const t: Parts = Option.isSome(r.scheme)
+    ? {
+        scheme: r.scheme,
+        authority: r.authority,
+        path: removeDotSegments(r.path),
+        query: r.query,
+        fragment,
+      }
+    : Option.isSome(r.authority)
+      ? {
+          scheme: b.scheme,
+          authority: r.authority,
+          path: removeDotSegments(r.path),
+          query: r.query,
+          fragment,
+        }
+      : r.path === ''
+        ? {
+            scheme: b.scheme,
+            authority: b.authority,
+            path: b.path,
+            query: Option.orElse(r.query, () => b.query),
+            fragment,
+          }
+        : {
+            scheme: b.scheme,
+            authority: b.authority,
+            path: r.path.startsWith('/')
+              ? removeDotSegments(r.path)
+              : removeDotSegments(merge(b, r.path)),
+            query: r.query,
+            fragment,
+          };
+  return recompose(t);
+};
+
+/**
+ * Removes the fragment from an IRI.
+ *
+ * @since 0.1.0
+ */
+export const withoutFragment = (iri: string): string => {
+  const i = iri.indexOf('#');
+  return i === -1 ? iri : iri.slice(0, i);
+};
+
+/**
+ * Computes a relative reference for `iri` with respect to `base`, if a
+ * simple one exists (same scheme and authority). Resolving the result against
+ * `base` always yields `iri`.
+ *
+ * @since 0.1.0
+ */
+export const relativize = (iri: string, base: string): Option.Option<string> => {
+  if (iri === base) return Option.some('');
+  const i = parse(iri);
+  const b = parse(base);
+  if (
+    !Equal.equals(i.scheme, b.scheme) ||
+    !Equal.equals(i.authority, b.authority) ||
+    Option.isNone(i.scheme)
+  ) {
+    return Option.none();
+  }
+  // `iri` as a reference with only `path` and its query and fragment
+  const relative = (path: string): string =>
+    recompose({
+      scheme: Option.none(),
+      authority: Option.none(),
+      path,
+      query: i.query,
+      fragment: i.fragment,
+    });
+  const dir = b.path.slice(0, b.path.lastIndexOf('/') + 1);
+  const rest = i.path.slice(dir.length);
+  const candidate: Option.Option<string> =
+    i.path === b.path
+      ? Equal.equals(i.query, b.query)
+        ? Option.map(i.fragment, (f) => `#${f}`)
+        : Option.isSome(i.query)
+          ? Option.some(relative(''))
+          : Option.none()
+      : Option.orElse(
+          // Avoid references whose first segment looks like a scheme.
+          dir !== '' && i.path.startsWith(dir) && rest !== '' && !/^[^/]*:/.test(rest)
+            ? Option.some(relative(rest))
+            : Option.none(),
+          () =>
+            i.path.startsWith('/') && !i.path.startsWith('//')
+              ? Option.some(relative(i.path))
+              : Option.none(),
+        );
+  return Option.filter(candidate, (c) => resolve(c, base) === iri);
+};
+
+// IRI grammar (RFC 3987) character classes, used for validation.
+const UCSCHAR =
+  '\\u00A0-\\uD7FF\\uF900-\\uFDCF\\uFDF0-\\uFFEF\\u{10000}-\\u{1FFFD}\\u{20000}-\\u{2FFFD}\\u{30000}-\\u{3FFFD}\\u{40000}-\\u{4FFFD}\\u{50000}-\\u{5FFFD}\\u{60000}-\\u{6FFFD}\\u{70000}-\\u{7FFFD}\\u{80000}-\\u{8FFFD}\\u{90000}-\\u{9FFFD}\\u{A0000}-\\u{AFFFD}\\u{B0000}-\\u{BFFFD}\\u{C0000}-\\u{CFFFD}\\u{D0000}-\\u{DFFFD}\\u{E1000}-\\u{EFFFD}';
+const IPRIVATE = '\\uE000-\\uF8FF\\u{F0000}-\\u{FFFFD}\\u{100000}-\\u{10FFFD}';
+const IUNRESERVED = `A-Za-z0-9\\-._~${UCSCHAR}`;
+const SUBDELIMS = "!$&'()*+,;=";
+const PCT = '%[0-9A-Fa-f]{2}';
+const IPCHAR = `(?:[${IUNRESERVED}${SUBDELIMS}:@]|${PCT})`;
+// `ihier-part` / `irelative-part` (optional authority, then a path), query and fragment: the
+// IRI grammar after the scheme, shared by absolute IRIs and relative references.
+const IRI_AFTER_SCHEME =
+  `(?://(?:(?:[${IUNRESERVED}${SUBDELIMS}:]|${PCT})*@)?(?:\\[[0-9A-Fa-f:.vV${IUNRESERVED}${SUBDELIMS}]*\\]|(?:[${IUNRESERVED}${SUBDELIMS}]|${PCT})*)(?::[0-9]*)?)?` +
+  `(?:/?${IPCHAR}*)*` +
+  `(?:\\?(?:${IPCHAR}|[/?${IPRIVATE}])*)?` +
+  `(?:#(?:${IPCHAR}|[/?])*)?`;
+const IRI_RE = new RegExp(`^[A-Za-z][A-Za-z0-9+.\\-]*:${IRI_AFTER_SCHEME}$`, 'u');
+
+/**
+ * Whether a string is a syntactically valid absolute IRI (RFC 3987).
+ *
+ * @since 0.1.0
+ */
+export const isValid = (iri: string): boolean => IRI_RE.test(iri);
+
+// A relative reference (RFC 3987 `irelative-ref`): the IRI grammar without the scheme.
+const RELATIVE_RE = new RegExp(`^${IRI_AFTER_SCHEME}$`, 'u');
+
+/**
+ * Whether a string is a syntactically valid IRI reference (RFC 3987): an
+ * absolute IRI, or a relative reference whose first path segment has no `:`.
+ *
+ * @since 0.1.0
+ */
+export const isValidReference = (reference: string): boolean =>
+  isAbsolute(reference)
+    ? isValid(reference)
+    : !/^[^/?#]*:/.test(reference) && RELATIVE_RE.test(reference);
+
+/**
+ * Schema of an absolute IRI (`isValid`): a string, with JSON Schema
+ * `format: "iri"`. Use it to validate IRIs from `Config`, CLI flags or HTTP
+ * parameters.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const IriSchema: Schema.String = Schema.String.check(
+  Schema.makeFilter((s: string) => isValid(s), {
+    identifier: 'isIri',
+    title: 'IRI',
+    description: 'An absolute IRI (RFC 3987).',
+    expected: 'an absolute IRI',
+    toJsonSchema: () => ({ format: 'iri' }),
+  }),
+).annotate({ identifier: 'Iri' });
+
+/**
+ * The type `IriSchema` decodes to: a string.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export type IriSchema = typeof IriSchema.Type;
+
+/**
+ * Schema of an IRI reference, absolute or relative (`isValidReference`): a
+ * string, with JSON Schema `format: "iri-reference"`.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const IriReferenceSchema: Schema.String = Schema.String.check(
+  Schema.makeFilter((s: string) => isValidReference(s), {
+    identifier: 'isIriReference',
+    title: 'IRI reference',
+    description: 'An absolute IRI or relative reference (RFC 3987).',
+    expected: 'an IRI reference',
+    toJsonSchema: () => ({ format: 'iri-reference' }),
+  }),
+).annotate({ identifier: 'IriReference' });
+
+/**
+ * The type `IriReferenceSchema` decodes to: a string.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export type IriReferenceSchema = typeof IriReferenceSchema.Type;

package/src/Isomorphism.ts

@@ -0,0 +1,319 @@
+/**
+ * Blank-node-aware dataset comparison (RDF graph isomorphism).
+ *
+ * Uses iterative signature refinement to partition blank nodes, then a
+ * backtracking search over the (usually tiny) ambiguous classes.
+ *
+ * @since 0.1.0
+ */
+import * as Arr from 'effect/Array';
+import { dual } from 'effect/Function';
+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 * as Order from 'effect/Order';
+import * as Predicate from 'effect/Predicate';
+import * as Dataset from './Dataset.ts';
+import { loop } from './internal/loop.ts';
+import * as Term from './Term.ts';
+
+/** Blank node labels, by blank node label. */
+type Labels = MutableHashMap.MutableHashMap<string, string>;
+
+const fnv = (s: string): string => {
+  let h1 = 0x811c9dc5;
+  let h2 = 0x01000193;
+  loop((i) => {
+    if (i >= s.length) return false;
+    const c = s.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193);
+    h2 = Math.imul(h2 ^ c, 0x5bd1e995);
+    return true;
+  });
+  return (h1 >>> 0).toString(36) + (h2 >>> 0).toString(36);
+};
+
+/** Appends the blank nodes of `t` (and of the triple terms inside it) to `out`, each once. */
+const collectBlankNodes = (t: Term.Term, out: Array<string>): void => {
+  if (Term.isBlankNode(t)) {
+    if (!out.includes(t.value)) out.push(t.value);
+  } else if (Term.isTriple(t)) {
+    collectBlankNodes(t.subject, out);
+    collectBlankNodes(t.object, out);
+  }
+};
+
+/** The distinct blank nodes of a quad, in order of first occurrence. */
+const quadBlankNodes = (q: Term.Quad): ReadonlyArray<string> => {
+  const out: Array<string> = [];
+  collectBlankNodes(q.subject, out);
+  collectBlankNodes(q.object, out);
+  collectBlankNodes(q.graph, out);
+  return out;
+};
+
+const labelOf = (labels: Labels, node: string): string =>
+  Option.getOrElse(MutableHashMap.get(labels, node), () => '');
+
+/**
+ * A quad's signature for one of its blank nodes, compiled once: text, and in
+ * between the indexes (into `Partition.nodes`) of the other blank nodes,
+ * whose current labels each refinement round fills in. The node itself is
+ * `@self`.
+ */
+type Template = ReadonlyArray<string | number>;
+
+const compile = (
+  t: Term.Term,
+  self: string,
+  index: MutableHashMap.MutableHashMap<string, number>,
+  out: Array<string | number>,
+): void => {
+  if (Term.isBlankNode(t)) {
+    if (t.value === self) out.push('@self');
+    else out.push(Option.getOrElse(MutableHashMap.get(index, t.value), () => '@'));
+  } else if (Term.isTriple(t)) {
+    out.push('<<');
+    compile(t.subject, self, index, out);
+    out.push(` ${t.predicate.key} `);
+    compile(t.object, self, index, out);
+    out.push('>>');
+  } else out.push(t.key);
+};
+
+const template = (
+  q: Term.Quad,
+  self: string,
+  index: MutableHashMap.MutableHashMap<string, number>,
+): Template => {
+  const out: Array<string | number> = [];
+  compile(q.subject, self, index, out);
+  out.push(` ${q.predicate.key} `);
+  compile(q.object, self, index, out);
+  out.push(' ');
+  compile(q.graph, self, index, out);
+  return out;
+};
+
+/** A template with the blank nodes' labels filled in. */
+const render = (t: Template, labels: ReadonlyArray<string>): string =>
+  t.map((part) => (Predicate.isString(part) ? part : `@${labels[part] ?? ''}`)).join('');
+
+interface Partition {
+  readonly nodes: ReadonlyArray<string>;
+  readonly labels: Labels;
+  readonly byNode: MutableHashMap.MutableHashMap<string, Array<Term.Quad>>;
+}
+
+/** The quads a blank node occurs in. */
+const quadsOf = (p: Partition, node: string): ReadonlyArray<Term.Quad> =>
+  Option.getOrElse(MutableHashMap.get(p.byNode, node), () => []);
+
+const refine = (quads: ReadonlyArray<Term.Quad>): Partition => {
+  const byNode = MutableHashMap.empty<string, Array<Term.Quad>>();
+  quads.forEach((q) => {
+    quadBlankNodes(q).forEach((b) => {
+      const list = MutableHashMap.get(byNode, b);
+      if (Option.isSome(list)) list.value.push(q);
+      else MutableHashMap.set(byNode, b, [q]);
+    });
+  });
+  const nodes = Arr.fromIterable(MutableHashMap.keys(byNode));
+  const index = MutableHashMap.fromIterable(nodes.map((n, i) => [n, i] as const));
+  const templates = nodes.map((n) =>
+    Option.getOrElse(MutableHashMap.get(byNode, n), () => []).map((q) => template(q, n, index)),
+  );
+  let labels: ReadonlyArray<string> = nodes.map(() => '');
+  let classes = 1;
+  // Refine until the number of classes stops growing (at most one round per node)
+  loop((round) => {
+    if (round > nodes.length) return false;
+    const current = labels;
+    const next = templates.map((ts, i) =>
+      fnv(
+        `${current[i] ?? ''}|${Arr.sort(
+          ts.map((t) => render(t, current)),
+          Order.String,
+        ).join('\n')}`,
+      ),
+    );
+    const nextClasses = MutableHashSet.size(MutableHashSet.fromIterable(next));
+    labels = next;
+    if (nextClasses === classes) return false;
+    classes = nextClasses;
+    return true;
+  });
+  const final = labels;
+  return {
+    nodes,
+    labels: MutableHashMap.fromIterable(nodes.map((n, i) => [n, final[i] ?? ''] as const)),
+    byNode,
+  };
+};
+
+/** `q` with its blank nodes renamed by `mapping` (those it does not map are kept). */
+const renameBlankNodes = (q: Term.Quad, mapping: Labels): Term.Quad =>
+  Term.mapTerms(q, (t) =>
+    Term.isBlankNode(t)
+      ? new Term.BlankNode(Option.getOrElse(MutableHashMap.get(mapping, t.value), () => t.value))
+      : t,
+  );
+
+const rename = (q: Term.Quad, mapping: Labels): string => renameBlankNodes(q, mapping).key;
+
+/** The blank nodes of a partition grouped by label, in order. */
+const groupsOf = (p: Partition): MutableHashMap.MutableHashMap<string, Array<string>> => {
+  const groups = MutableHashMap.empty<string, Array<string>>();
+  p.nodes.forEach((n) => {
+    const l = labelOf(p.labels, n);
+    const group = MutableHashMap.get(groups, l);
+    if (Option.isSome(group)) group.value.push(n);
+    else MutableHashMap.set(groups, l, [n]);
+  });
+  return groups;
+};
+
+/** The class of `node`: the nodes of `groups` with its label in `labels`. */
+const classOf = (
+  groups: MutableHashMap.MutableHashMap<string, ReadonlyArray<string>>,
+  labels: Labels,
+  node: string,
+): ReadonlyArray<string> =>
+  Option.getOrElse(MutableHashMap.get(groups, labelOf(labels, node)), () => []);
+
+/**
+ * The public result of `bijection`: a native `ReadonlyMap`, copied once
+ * from the search's map at the end.
+ */
+const toReadonlyMap = (mapping: Labels): ReadonlyMap<string, string> => new Map(mapping);
+
+/**
+ * Finds a blank node bijection from `self` to `that` under which the two
+ * datasets are equal, if one exists.
+ *
+ * @since 0.1.0
+ * @category isomorphism
+ */
+export const bijection = (
+  self: Dataset.Dataset,
+  that: Dataset.Dataset,
+): Option.Option<ReadonlyMap<string, string>> => {
+  if (self.size !== that.size) return Option.none();
+  const aBlank: Array<Term.Quad> = [];
+  const groundMissing = Iterable.some(self, (q) => {
+    if (!Term.hasBlankNodes(q)) return !Dataset.has(that, q);
+    aBlank.push(q);
+    return false;
+  });
+  if (groundMissing) return Option.none();
+  const bBlank = Arr.filter(Arr.fromIterable(that), (q) => Term.hasBlankNodes(q));
+  if (aBlank.length !== bBlank.length) return Option.none();
+  if (Arr.isReadonlyArrayEmpty(aBlank)) return Option.some(toReadonlyMap(MutableHashMap.empty()));
+
+  const a = refine(aBlank);
+  const b = refine(bBlank);
+  if (a.nodes.length !== b.nodes.length) return Option.none();
+
+  const groupsB = groupsOf(b);
+  const groupsA = groupsOf(a);
+  const sameClasses = !Iterable.some(
+    groupsA,
+    ([l, g]) => !Option.exists(MutableHashMap.get(groupsB, l), (gb) => gb.length === g.length),
+  );
+  if (!sameClasses) return Option.none();
+
+  const target = MutableHashSet.fromIterable(bBlank.map((q) => q.key));
+  const mapping: Labels = MutableHashMap.empty();
+  const used = MutableHashSet.empty<string>();
+  // Assign unambiguous nodes first, then search the rest smallest class first.
+  const order = Arr.sort(
+    a.nodes,
+    Order.mapInput(Order.Number, (x: string) => classOf(groupsA, a.labels, x).length),
+  );
+
+  const consistent = (node: string): boolean =>
+    !quadsOf(a, node).some((q) => {
+      const complete = quadBlankNodes(q).every((x) => MutableHashMap.has(mapping, x));
+      return complete && !MutableHashSet.has(target, rename(q, mapping));
+    });
+
+  // Iterative depth-first search (graphs can have many thousands of blank nodes).
+  const cursors: Array<number> = [0];
+  let found = false;
+  loop(() => {
+    const i = cursors.length - 1;
+    const node = order[i];
+    if (i < 0 || node === undefined) {
+      // The search is exhausted, or every node is assigned
+      found = i === order.length;
+      return false;
+    }
+    const candidates = classOf(groupsB, a.labels, node);
+    const previous = MutableHashMap.get(mapping, node);
+    if (Option.isSome(previous)) {
+      MutableHashMap.remove(mapping, node);
+      MutableHashSet.remove(used, previous.value);
+    }
+    let next = cursors[i] ?? 0;
+    let advanced = false;
+    loop(() => {
+      const candidate = candidates[next];
+      if (candidate === undefined) return false;
+      next++;
+      if (MutableHashSet.has(used, candidate)) return true;
+      MutableHashMap.set(mapping, node, candidate);
+      MutableHashSet.add(used, candidate);
+      if (consistent(node)) {
+        advanced = true;
+        return false;
+      }
+      MutableHashMap.remove(mapping, node);
+      MutableHashSet.remove(used, candidate);
+      return true;
+    });
+    cursors[i] = next;
+    if (advanced) cursors.push(0);
+    else cursors.pop();
+    return true;
+  });
+  return found ? Option.some(toReadonlyMap(mapping)) : Option.none();
+};
+
+/**
+ * Whether two datasets are isomorphic: equal up to a consistent renaming of
+ * blank nodes.
+ *
+ * @since 0.1.0
+ * @category isomorphism
+ */
+export const isomorphic: {
+  (that: Dataset.Dataset): (self: Dataset.Dataset) => boolean;
+  (self: Dataset.Dataset, that: Dataset.Dataset): boolean;
+} = dual(2, (self: Dataset.Dataset, that: Dataset.Dataset): boolean =>
+  Option.isSome(bijection(self, that)),
+);
+
+/**
+ * Relabels blank nodes in a dataset with fresh labels `prefix0`, `prefix1`,
+ * … in a deterministic order derived from their structural signatures.
+ *
+ * Isomorphic datasets without automorphic blank nodes yield identical
+ * results; this is not a full canonicalisation algorithm.
+ *
+ * @since 0.1.0
+ * @category isomorphism
+ */
+export const relabel = (self: Dataset.Dataset, prefix = 'c'): Dataset.Dataset => {
+  const blank = Array.from(self).filter(Term.hasBlankNodes);
+  if (Arr.isReadonlyArrayEmpty(blank)) return self;
+  const { nodes, labels } = refine(blank);
+  const sorted = Arr.sort(
+    nodes,
+    Order.mapInput(Order.String, (x: string) => labelOf(labels, x)),
+  );
+  const mapping: Labels = MutableHashMap.fromIterable(
+    sorted.map((n, i) => [n, `${prefix}${i}`] as const),
+  );
+  return Dataset.map(self, (q) => renameBlankNodes(q, mapping));
+};