@thomasfosterau/effect-rdf 0.0.0-stage → 0.1.0

package/src/jsonld/JsonLd.ts

@@ -0,0 +1,847 @@
+/**
+ * The JSON-LD 1.1 processor: expansion, compaction, flattening, framing and
+ * conversion to and from RDF, plus a `Serialization.Codec` for the
+ * `application/ld+json` media type.
+ *
+ * Remote documents and contexts are loaded through the `DocumentLoader`
+ * service when it is provided (or through `options.documentLoader`); without
+ * one, any remote reference fails with `loading remote context failed` /
+ * `loading document failed`.
+ *
+ * @since 0.1.0
+ */
+import * as Dataset from '../Dataset.ts';
+import * as PrefixMap from '../PrefixMap.ts';
+import * as Serialization from '../Serialization.ts';
+import * as Term from '../Term.ts';
+import * as Arr from 'effect/Array';
+import * as Effect from 'effect/Effect';
+import * as MutableHashMap from 'effect/MutableHashMap';
+import * as Option from 'effect/Option';
+import * as Record from 'effect/Record';
+import * as Result from 'effect/Result';
+import * as Schema from 'effect/Schema';
+import * as DocumentLoader from './DocumentLoader.ts';
+import * as JsonLdError from './JsonLdError.ts';
+import { compactElement, compactIri } from './internal/compact.ts';
+import {
+  type ActiveContext,
+  type Env,
+  type LoadedDocument,
+  NeedDocument,
+  type ProcessingMode,
+  expandIri,
+  initialContext,
+  processContext,
+} from './internal/context.ts';
+import { expandElement } from './internal/expand.ts';
+import { flattenExpanded } from './internal/flatten.ts';
+import { cleanupNull, frame as frameAlgorithm } from './internal/frame.ts';
+import * as Rdf from './internal/rdf.ts';
+import {
+  type Json,
+  type JsonObject,
+  fail,
+  isEmptyObject,
+  isObject,
+  isString,
+  loop,
+} from './internal/util.ts';
+import { parseJson } from './internal/json.ts';
+import * as Predicate from 'effect/Predicate';
+
+/** An empty context (`{}` or `[]`), which compaction leaves out of the output. */
+const isEmptyContext = (context: Json): boolean =>
+  isEmptyObject(context) || (Array.isArray(context) && Arr.isReadonlyArrayEmpty(context));
+
+/**
+ * Any JSON value.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type JsonValue = null | boolean | number | string | JsonArray | JsonObjectValue;
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export interface JsonArray extends ReadonlyArray<JsonValue> {}
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export interface JsonObjectValue {
+  readonly [key: string]: JsonValue;
+}
+
+/**
+ * The input of the JSON-LD algorithms: a JSON document (object or array), the
+ * URL of a document to load, or an already loaded `RemoteDocument`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type Input = JsonValue | DocumentLoader.RemoteDocument | object;
+
+/**
+ * Options shared by all JSON-LD algorithms (the `JsonLdOptions` of the
+ * JSON-LD API).
+ *
+ * @since 0.1.0
+ * @category options
+ */
+export interface Options {
+  /** The base IRI. Defaults to the URL of the input document, if any. */
+  readonly base?: string | null | undefined;
+  /** `json-ld-1.1` (default) or `json-ld-1.0`. */
+  readonly processingMode?: ProcessingMode | undefined;
+  /** A context to apply before expanding the input. */
+  readonly expandContext?: unknown;
+  /** Process map entries in lexicographical order. Defaults to `false`. */
+  readonly ordered?: boolean | undefined;
+  /** Replace single-element arrays by their element. Defaults to `true`. */
+  readonly compactArrays?: boolean | undefined;
+  /** Make IRIs relative to the base IRI when compacting. Defaults to `true`. */
+  readonly compactToRelative?: boolean | undefined;
+  /** Extract all JSON-LD script elements from HTML input. */
+  readonly extractAllScripts?: boolean | undefined;
+  /**
+   * A document loader to use instead of the `DocumentLoader` service from
+   * the environment.
+   */
+  readonly documentLoader?: DocumentLoader.Loader | undefined;
+}
+
+/**
+ * Options for `toRdf`.
+ *
+ * @since 0.1.0
+ * @category options
+ */
+export interface ToRdfOptions extends Options {
+  /**
+   * How to represent `@direction`: as `i18n-datatype` literals, as
+   * `compound-literal` blank nodes, or not at all (default).
+   */
+  readonly rdfDirection?: 'i18n-datatype' | 'compound-literal' | null | undefined;
+  /**
+   * Generalized RDF (blank node predicates) cannot be represented by the
+   * core term model; such triples are always dropped.
+   */
+  readonly produceGeneralizedRdf?: boolean | undefined;
+}
+
+/**
+ * Options for `fromRdf`.
+ *
+ * @since 0.1.0
+ * @category options
+ */
+export interface FromRdfOptions {
+  readonly processingMode?: ProcessingMode | undefined;
+  readonly ordered?: boolean | undefined;
+  /** Convert `xsd:boolean`, `xsd:integer` and `xsd:double` to native JSON values. */
+  readonly useNativeTypes?: boolean | undefined;
+  /** Keep `rdf:type` as a regular property instead of `@type`. */
+  readonly useRdfType?: boolean | undefined;
+  readonly rdfDirection?: 'i18n-datatype' | 'compound-literal' | null | undefined;
+}
+
+/**
+ * Options for `frame`.
+ *
+ * @since 0.1.0
+ * @category options
+ */
+export interface FrameOptions extends Options {
+  /** The default `@embed` flag: `@once` (default), `@always`, `@never` or `@link`. */
+  readonly embed?: '@once' | '@always' | '@never' | '@link' | undefined;
+  /** The default `@explicit` flag. */
+  readonly explicit?: boolean | undefined;
+  /** The default `@omitDefault` flag. */
+  readonly omitDefault?: boolean | undefined;
+  /** The default `@requireAll` flag. */
+  readonly requireAll?: boolean | undefined;
+  /** Omit `@graph` when the result is a single node. Defaults to `false` in 1.1. */
+  readonly omitGraph?: boolean | undefined;
+}
+
+// -----------------------------------------------------------------------------
+// Driver
+// -----------------------------------------------------------------------------
+
+type DocResult = Result.Result<LoadedDocument, JsonLdError.JsonLdError>;
+
+const getLoader = (options?: Options) =>
+  options?.documentLoader !== undefined
+    ? Effect.succeed(options.documentLoader)
+    : Effect.map(Effect.serviceOption(DocumentLoader.DocumentLoader), (o) =>
+        Option.getOrElse(o, () => DocumentLoader.none),
+      );
+
+/**
+ * The environment of one algorithm run: documents come from `docs`, and a
+ * document not loaded yet aborts the run with `NeedDocument`.
+ */
+const makeEnv = (
+  docs: MutableHashMap.MutableHashMap<string, DocResult>,
+  options?: Options,
+): Env => ({
+  processingMode: options?.processingMode ?? 'json-ld-1.1',
+  contextCache: MutableHashMap.empty(),
+  load: (url) => {
+    const hit = MutableHashMap.get(docs, url);
+    if (Option.isNone(hit)) throw new NeedDocument(url);
+    if (Result.isFailure(hit.value)) throw hit.value.failure;
+    return hit.value.success;
+  },
+});
+
+/**
+ * Runs the algorithm once. A `NeedDocument` or `JsonLdError` it throws is the
+ * failure; anything else is a bug and propagates (a defect in `run`).
+ */
+const attempt = <A>(
+  f: (env: Env) => A,
+  env: Env,
+): Result.Result<A, NeedDocument | JsonLdError.JsonLdError> =>
+  Result.try({
+    try: () => f(env),
+    catch: (e) => {
+      if (e instanceof NeedDocument || JsonLdError.isJsonLdError(e)) return e;
+      throw e;
+    },
+  });
+
+/**
+ * Runs a pure algorithm, loading documents on demand: when the algorithm
+ * needs a document that has not been loaded yet it aborts with
+ * `NeedDocument`, the document is loaded, and the algorithm is restarted.
+ */
+const run = <A>(f: (env: Env) => A, options?: Options): Effect.Effect<A, JsonLdError.JsonLdError> =>
+  Effect.gen(function* () {
+    const loader = yield* getLoader(options);
+    const docs = MutableHashMap.empty<string, DocResult>();
+    const env = makeEnv(docs, options);
+    // Re-run `f` until it no longer stops on a document it has not seen: each
+    // stop loads that one document into `docs`, which `f` reads on the next run.
+    const go: Effect.Effect<A, JsonLdError.JsonLdError> = Effect.suspend(() => {
+      const step = attempt(f, env);
+      if (Result.isSuccess(step)) return Effect.succeed(step.success);
+      const failure = step.failure;
+      if (!(failure instanceof NeedDocument)) return Effect.fail(failure);
+      return Effect.flatMap(
+        Effect.result(
+          loader.load(failure.url, { profile: 'http://www.w3.org/ns/json-ld#context' }),
+        ),
+        (r) => {
+          MutableHashMap.set(docs, failure.url, r);
+          return go;
+        },
+      );
+    });
+    return yield* go;
+  });
+
+interface ResolvedInput {
+  readonly document: Json;
+  /** The URL of the document, which is the base IRI (`null`: none) unless one is given. */
+  readonly documentUrl: string | null;
+  /** A context referenced by an HTTP `Link` header. */
+  readonly contextUrl: Option.Option<string>;
+}
+
+const isRemoteDocument = (u: unknown): u is DocumentLoader.RemoteDocument =>
+  isObject(u) && Predicate.isString(u['documentUrl']) && 'document' in u;
+
+/** Resolves an input (an `Input`, or a frame, which is any JSON-LD input). */
+const resolveInput = (
+  input: unknown,
+  options?: Options,
+): Effect.Effect<ResolvedInput, JsonLdError.JsonLdError> =>
+  Effect.gen(function* () {
+    if (isString(input)) {
+      const loader = yield* getLoader(options);
+      const doc = yield* loader
+        .load(input, { extractAllScripts: options?.extractAllScripts })
+        .pipe(
+          Effect.mapError((e) =>
+            e.code === 'loading document failed' || e.code === 'multiple context link headers'
+              ? e
+              : JsonLdError.make('loading document failed', e.message),
+          ),
+        );
+      return {
+        document: doc.document,
+        documentUrl: doc.documentUrl,
+        contextUrl: Option.fromUndefinedOr(doc.contextUrl),
+      };
+    }
+    if (isRemoteDocument(input)) {
+      return {
+        document: input.document,
+        documentUrl: input.documentUrl,
+        contextUrl: Option.fromUndefinedOr(input.contextUrl),
+      };
+    }
+    return { document: input, documentUrl: null, contextUrl: Option.none() };
+  });
+
+const expandSync = (
+  env: Env,
+  input: ResolvedInput,
+  frameExpansion: boolean,
+  options?: Options,
+): Array<JsonObject> => {
+  const base = options?.base !== undefined ? options.base : input.documentUrl;
+  let active: ActiveContext = initialContext(base);
+  if (options?.expandContext !== undefined && options.expandContext !== null) {
+    // `expandContext` is a JSON value supplied by the caller.
+    let ctx: Json = options.expandContext;
+    if (isObject(ctx) && '@context' in ctx) ctx = ctx['@context'];
+    active = processContext(env, active, ctx, active.originalBase);
+  }
+  if (Option.isSome(input.contextUrl)) {
+    const contextUrl = input.contextUrl.value;
+    active = processContext(env, active, contextUrl, contextUrl);
+  }
+  let expanded = expandElement(
+    env,
+    active,
+    Option.none(),
+    input.document,
+    input.documentUrl ?? base,
+    {
+      frameExpansion,
+      ordered: options?.ordered ?? false,
+    },
+  );
+  if (isObject(expanded) && Record.keys(expanded).length === 1 && '@graph' in expanded) {
+    expanded = expanded['@graph'];
+  }
+  if (expanded === null || expanded === undefined) expanded = [];
+  if (!Array.isArray(expanded)) expanded = [expanded];
+  return expanded;
+};
+
+const compactSync = (
+  env: Env,
+  expanded: Json,
+  context: Json,
+  documentUrl: string | null,
+  options?: Options,
+): JsonObject => {
+  if (isObject(context) && '@context' in context) context = context['@context'];
+  const compactToRelative = options?.compactToRelative ?? true;
+  const base =
+    options?.base !== undefined && options.base !== null
+      ? options.base
+      : compactToRelative
+        ? documentUrl
+        : null;
+  const contextBase = isString(context) ? context : (options?.base ?? documentUrl ?? null);
+  let active = initialContext(base);
+  active = processContext(env, active, context ?? null, contextBase);
+  const compactOptions = {
+    compactArrays: options?.compactArrays ?? true,
+    ordered: options?.ordered ?? false,
+    compactToRelative,
+  };
+  let compacted = compactElement(env, active, Option.none(), expanded, compactOptions);
+  if (Array.isArray(compacted)) {
+    compacted = Arr.isReadonlyArrayEmpty(compacted)
+      ? {}
+      : { [compactIri(env, active, '@graph', null, true, false, compactOptions)]: compacted };
+  }
+  if (compacted === null || compacted === undefined) compacted = {};
+  if (context !== null && context !== undefined && !isEmptyContext(context)) {
+    compacted = { '@context': context, ...compacted };
+  }
+  return compacted;
+};
+
+// -----------------------------------------------------------------------------
+// API
+// -----------------------------------------------------------------------------
+
+/**
+ * Expands a JSON-LD document (JSON-LD 1.1 API, Expansion Algorithm).
+ *
+ * @since 0.1.0
+ * @category algorithms
+ */
+export const expand = (
+  input: Input,
+  options?: Options,
+): Effect.Effect<Array<JsonObjectValue>, JsonLdError.JsonLdError> =>
+  Effect.flatMap(resolveInput(input, options), (resolved) =>
+    run((env) => expandSync(env, resolved, false, options), options),
+  );
+
+/**
+ * Compacts a JSON-LD document against a context (JSON-LD 1.1 API,
+ * Compaction Algorithm). The context may be a context definition, an array
+ * of contexts, an IRI, or a document with an `@context` entry.
+ *
+ * @since 0.1.0
+ * @category algorithms
+ */
+export const compact = (
+  input: Input,
+  context: unknown,
+  options?: Options,
+): Effect.Effect<JsonObjectValue, JsonLdError.JsonLdError> =>
+  Effect.flatMap(resolveInput(input, options), (resolved) =>
+    run((env) => {
+      const expanded = expandSync(env, resolved, false, { ...options, ordered: false });
+      return compactSync(env, expanded, context, resolved.documentUrl, options);
+    }, options),
+  );
+
+/**
+ * Flattens a JSON-LD document (JSON-LD 1.1 API, Flattening Algorithm),
+ * optionally compacting the result.
+ *
+ * @since 0.1.0
+ * @category algorithms
+ */
+export const flatten = (
+  input: Input,
+  context?: unknown,
+  options?: Options,
+): Effect.Effect<JsonValue, JsonLdError.JsonLdError> =>
+  Effect.flatMap(resolveInput(input, options), (resolved) =>
+    run((env) => {
+      const expanded = expandSync(env, resolved, false, options);
+      const flattened = flattenExpanded(expanded, options?.ordered ?? false);
+      if (context === undefined || context === null) return flattened;
+      const compacted = compactSync(env, flattened, context, resolved.documentUrl, options);
+      return compacted;
+    }, options),
+  );
+
+/**
+ * Frames a JSON-LD document (JSON-LD 1.1 Framing).
+ *
+ * @since 0.1.0
+ * @category algorithms
+ */
+export const frame = (
+  input: Input,
+  frameInput: unknown,
+  options?: FrameOptions,
+): Effect.Effect<JsonObjectValue, JsonLdError.JsonLdError> =>
+  Effect.gen(function* () {
+    const resolved = yield* resolveInput(input, options);
+    // A frame is a JSON-LD input (document, URL or object), as `resolveInput` takes.
+    const resolvedFrame = yield* resolveInput(frameInput, options);
+    return yield* run((env) => frameSync(env, resolved, resolvedFrame, options), options);
+  });
+
+/** The `@context` entry of a document (`null` when it has none). */
+const contextOf = (document: JsonObject): Json => document['@context'] ?? null;
+
+const frameSync = (
+  env: Env,
+  resolved: ResolvedInput,
+  resolvedFrame: ResolvedInput,
+  options?: FrameOptions,
+): JsonObject => {
+  const frameDocument: Json = resolvedFrame.document;
+  if (!isObject(frameDocument) && !Array.isArray(frameDocument)) {
+    return fail('invalid frame', 'a frame must be a JSON object');
+  }
+  const context: Json = isObject(frameDocument) ? contextOf(frameDocument) : null;
+  const base = options?.base !== undefined ? options.base : resolved.documentUrl;
+  const frameBase = resolvedFrame.documentUrl ?? base;
+  const frameContext = processContext(env, initialContext(frameBase), context, frameBase);
+  const merged = !(
+    isObject(frameDocument) &&
+    Record.keys(frameDocument).some((k) => expandIri(env, frameContext, k, true) === '@graph')
+  );
+  const expanded = expandSync(env, resolved, false, { ...options, ordered: false });
+  const expandedFrame = expandSync(env, resolvedFrame, true, { ...options, ordered: false });
+  const is11 = env.processingMode !== 'json-ld-1.0';
+  const framed = frameAlgorithm(expanded, expandedFrame, {
+    embed: options?.embed ?? '@once',
+    explicit: options?.explicit ?? false,
+    omitDefault: options?.omitDefault ?? false,
+    requireAll: options?.requireAll ?? false,
+    ordered: options?.ordered ?? false,
+    merged,
+    is11,
+  });
+  const compactToRelative = options?.compactToRelative ?? true;
+  let active = initialContext(
+    options?.base != null ? options.base : compactToRelative ? resolved.documentUrl : null,
+  );
+  active = processContext(env, active, context, frameBase);
+  const compactOptions = {
+    compactArrays: options?.compactArrays ?? true,
+    ordered: options?.ordered ?? false,
+    compactToRelative,
+  };
+  const omitGraph = options?.omitGraph ?? is11;
+  let compacted = compactElement(env, active, Option.none(), framed, compactOptions);
+  if (omitGraph && Array.isArray(compacted)) {
+    if (compacted.length === 1 && compactOptions.compactArrays) compacted = compacted[0];
+  } else if (!omitGraph && isObject(compacted)) {
+    compacted = [compacted];
+  }
+  if (Array.isArray(compacted)) {
+    const graphKey = compactIri(env, active, '@graph', null, true, false, compactOptions);
+    compacted = { [graphKey]: compacted };
+  }
+  if (compacted === null || compacted === undefined) compacted = {};
+  if (context !== null && !isEmptyContext(context)) {
+    compacted = { '@context': context, ...compacted };
+  }
+  return cleanupNull(compacted);
+};
+
+/**
+ * Converts a JSON-LD document to an RDF dataset (Deserialize JSON-LD to RDF
+ * Algorithm).
+ *
+ * @since 0.1.0
+ * @category algorithms
+ */
+export const toRdf = (
+  input: Input,
+  options?: ToRdfOptions,
+): Effect.Effect<Dataset.Dataset, JsonLdError.JsonLdError> =>
+  Effect.map(toQuads(input, options), Dataset.fromIterable);
+
+/**
+ * Like `toRdf`, but returns the quads in document order.
+ *
+ * @since 0.1.0
+ * @category algorithms
+ */
+export const toQuads = (
+  input: Input,
+  options?: ToRdfOptions,
+): Effect.Effect<ReadonlyArray<Term.Quad>, JsonLdError.JsonLdError> => quadsOf(input, options);
+
+/** `toQuads` over any parsed JSON document. */
+const quadsOf = (
+  input: unknown,
+  options?: ToRdfOptions,
+): Effect.Effect<ReadonlyArray<Term.Quad>, JsonLdError.JsonLdError> =>
+  Effect.flatMap(resolveInput(input, options), (resolved) =>
+    run((env) => {
+      const expanded = expandSync(env, resolved, false, options);
+      return Rdf.toRdf(expanded, {
+        produceGeneralizedRdf: options?.produceGeneralizedRdf ?? false,
+        rdfDirection: Option.fromNullishOr(options?.rdfDirection),
+      });
+    }, options),
+  );
+
+/**
+ * Converts RDF quads to expanded JSON-LD (Serialize RDF as JSON-LD
+ * Algorithm).
+ *
+ * @since 0.1.0
+ * @category algorithms
+ */
+export const fromRdf = (
+  quads: Iterable<Term.Quad>,
+  options?: FromRdfOptions,
+): Effect.Effect<Array<JsonObjectValue>, JsonLdError.JsonLdError> =>
+  Effect.try({
+    try: () =>
+      Rdf.fromRdf(quads, {
+        rdfDirection: Option.fromNullishOr(options?.rdfDirection),
+        useNativeTypes: options?.useNativeTypes ?? false,
+        useRdfType: options?.useRdfType ?? false,
+        ordered: options?.ordered ?? false,
+        processingMode: options?.processingMode ?? 'json-ld-1.1',
+      }),
+    catch: (e) =>
+      JsonLdError.isJsonLdError(e) ? e : JsonLdError.make('invalid JSON literal', String(e)),
+  });
+
+// -----------------------------------------------------------------------------
+// Codec
+// -----------------------------------------------------------------------------
+
+/**
+ * The JSON-LD format.
+ *
+ * @since 0.1.0
+ * @category formats
+ */
+export const format: Serialization.Format = Serialization.makeFormat({
+  name: 'JSON-LD',
+  mediaType: 'application/ld+json',
+  extensions: ['jsonld'],
+  datasets: true,
+});
+
+// Spans are named `JsonLd.parse`, `JsonLd.serialize`.
+const trace: Serialization.SpanTarget = { module: 'JsonLd', format };
+
+/**
+ * Options for parsing JSON-LD documents to RDF.
+ *
+ * @since 0.1.0
+ * @category options
+ */
+export interface ParseOptions extends Serialization.ParseOptions, ToRdfOptions {}
+
+/**
+ * Options for serialising RDF as JSON-LD.
+ *
+ * @since 0.1.0
+ * @category options
+ */
+export interface SerializeOptions extends Serialization.SerializeOptions, FromRdfOptions {
+  /** A context to compact the output with. */
+  readonly context?: unknown;
+  /** Replace single-element arrays by their element. Defaults to `true`. */
+  readonly compactArrays?: boolean | undefined;
+  /** JSON indentation. Defaults to 2; use 0 for compact output. */
+  readonly indent?: number | undefined;
+  readonly documentLoader?: DocumentLoader.Loader | undefined;
+}
+
+// A sticky scanner for `jsonErrorOffset`: JSON whitespace.
+const JSON_WS = /[ \t\n\r]*/y;
+
+/** Finds the offset of the first JSON syntax error in `input`. */
+const jsonErrorOffset = (input: string): number => {
+  let i = 0;
+  const scan = (re: RegExp) => {
+    re.lastIndex = i;
+    re.exec(input);
+    i = re.lastIndex;
+  };
+  const ws = () => scan(JSON_WS);
+  const stop = (): never => {
+    throw i;
+  };
+  const literal = (word: string) => {
+    if (input.startsWith(word, i)) i += word.length;
+    else stop();
+  };
+  const string = () => {
+    i++;
+    // One character (or escape) per step, up to the closing quote.
+    loop(true, () => {
+      if (i >= input.length || input[i] === '"') return Option.none();
+      if (input[i] === '\\') i++;
+      else if (input.charCodeAt(i) < 0x20) stop();
+      i++;
+      return Option.some(true);
+    });
+    if (i >= input.length) stop();
+    i++;
+  };
+  const value = (): void => {
+    ws();
+    const c = input[i];
+    if (c === '{' || c === '[') {
+      const close = c === '{' ? '}' : ']';
+      i++;
+      ws();
+      if (input[i] === close) {
+        i++;
+        return;
+      }
+      // One member per step, until the closing bracket.
+      loop(true, () => {
+        if (c === '{') {
+          ws();
+          if (input[i] !== '"') stop();
+          string();
+          ws();
+          if (input[i] !== ':') stop();
+          i++;
+        }
+        value();
+        ws();
+        if (input[i] === ',') {
+          i++;
+          return Option.some(true);
+        }
+        if (input[i] !== close) stop();
+        i++;
+        return Option.none();
+      });
+    } else if (c === '"') string();
+    else if (c === 't') literal('true');
+    else if (c === 'f') literal('false');
+    else if (c === 'n') literal('null');
+    else {
+      const m = /^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?/.exec(input.slice(i));
+      if (m === null || m[0] === '') return stop();
+      i += m[0].length;
+    }
+  };
+  // `stop` throws at the offending offset, which is `i`.
+  return Result.merge(
+    Result.try({
+      try: () => {
+        value();
+        ws();
+        return i;
+      },
+      catch: () => i,
+    }),
+  );
+};
+
+const positionOf = (input: string) => {
+  const pos = jsonErrorOffset(input);
+  const before = input.slice(0, pos);
+  return { line: before.split('\n').length, column: pos - before.lastIndexOf('\n') };
+};
+
+/**
+ * Parses a JSON-LD document into RDF.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export const parse = (
+  input: string,
+  options?: ParseOptions,
+): Effect.Effect<Serialization.ParseResult, Serialization.RdfParseError> =>
+  Effect.gen(function* () {
+    const json = yield* Effect.fromResult(parseJson(input)).pipe(
+      Effect.mapError(
+        (e) =>
+          new Serialization.RdfParseError({
+            format: format.name,
+            message: `invalid JSON: ${String(e)}`,
+            ...positionOf(input),
+          }),
+      ),
+    );
+    const base = options?.base !== undefined ? options.base : (options?.baseIri ?? null);
+    const quads = yield* quadsOf(json, { ...options, base }).pipe(
+      Effect.mapError(
+        (e) => new Serialization.RdfParseError({ format: format.name, message: e.message }),
+      ),
+    );
+    const prefix = options?.blankNodePrefix ?? Serialization.freshBlankNodePrefix();
+    const graph = options?.graph;
+    const relabel = (t: Term.Term): Term.Term =>
+      Term.isBlankNode(t) ? Term.blankNode(`${prefix}${t.value}`) : t;
+    const dataset = Dataset.fromIterable(
+      quads.map((q) => {
+        const relabelled = Term.mapTerms(q, relabel);
+        return graph !== undefined && Term.isDefaultGraph(relabelled.graph)
+          ? Term.quad(relabelled.subject, relabelled.predicate, relabelled.object, graph)
+          : relabelled;
+      }),
+    );
+    return {
+      dataset,
+      prefixes: prefixesOf(json),
+      baseIri: base ?? undefined,
+    };
+  }).pipe(Serialization.withParseSpan(trace, input));
+
+const prefixesOf = (json: Json): PrefixMap.PrefixMap => {
+  const entries: Array<[string, string]> = [];
+  const visit = (ctx: Json): void => {
+    if (Array.isArray(ctx)) ctx.forEach(visit);
+    else if (isObject(ctx)) {
+      Record.keys(ctx).forEach((k) => {
+        if (k.startsWith('@') || k.includes(':')) return;
+        const v = ctx[k];
+        const iri = isString(v) ? v : isObject(v) && isString(v['@id']) ? v['@id'] : undefined;
+        if (iri !== undefined && /[/#:]$/.test(iri) && /^[a-z][a-z0-9+.-]*:/i.test(iri)) {
+          entries.push([k, iri]);
+        }
+      });
+    }
+  };
+  if (isObject(json)) visit(json['@context']);
+  return PrefixMap.make(entries);
+};
+
+/**
+ * Serialises quads as a JSON-LD document. Without a context (and without
+ * prefixes) the output is expanded JSON-LD; otherwise it is compacted with
+ * the given context, extended with one term per prefix.
+ *
+ * @since 0.1.0
+ * @category serializing
+ */
+export const serialize = (
+  quads: Iterable<Term.Quad>,
+  options?: SerializeOptions,
+): Effect.Effect<string, Serialization.RdfSerializeError> =>
+  Effect.gen(function* () {
+    const expanded = yield* fromRdf(quads, options);
+    let context: Json = options?.context ?? null;
+    if (isObject(context) && '@context' in context) context = context['@context'];
+    if (options?.prefixes !== undefined && options.prefixes.prefixes.size > 0) {
+      const prefixContext: JsonObject = {};
+      options.prefixes.prefixes.forEach((namespace, prefix) => {
+        prefixContext[prefix] = namespace;
+      });
+      if (options.baseIri !== undefined) prefixContext['@base'] = options.baseIri;
+      context =
+        context === null
+          ? prefixContext
+          : Array.isArray(context)
+            ? [prefixContext, ...context]
+            : [prefixContext, context];
+    }
+    const output: Json =
+      context === null
+        ? expanded
+        : yield* compact(expanded, context, {
+            base: options?.baseIri ?? null,
+            compactArrays: options?.compactArrays,
+            processingMode: options?.processingMode,
+            documentLoader: options?.documentLoader,
+          });
+    return yield* Schema.encodeEffect(
+      Schema.fromJsonString(Schema.Unknown, { space: options?.indent ?? 2 }),
+    )(output);
+  }).pipe(
+    Effect.mapError(
+      (e) => new Serialization.RdfSerializeError({ format: format.name, message: e.message }),
+    ),
+    Serialization.withSerializeSpan(trace),
+  );
+
+/**
+ * The JSON-LD parser.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export const parser: Serialization.Parser<ParseOptions> = Serialization.makeParser({
+  format,
+  parse,
+});
+
+/**
+ * The JSON-LD serializer.
+ *
+ * @since 0.1.0
+ * @category serializing
+ */
+export const serializer: Serialization.Serializer<SerializeOptions> = Serialization.makeSerializer({
+  format,
+  serialize,
+});
+
+/**
+ * The JSON-LD codec.
+ *
+ * @since 0.1.0
+ * @category codecs
+ */
+export const codec: Serialization.Codec<ParseOptions, SerializeOptions> = Serialization.makeCodec(
+  parser,
+  serializer,
+);