@thomasfosterau/effect-rdf 0.0.0-stage → 0.1.0

package/src/shex/ShapeMap.ts

@@ -0,0 +1,385 @@
+/**
+ * ShapeMaps: associations of nodes with shapes, used both as validation
+ * input and output. Supports the ShapeMap compact syntax for fixed maps
+ * (`node@shape`, `node@START`) and query maps with triple pattern node
+ * selectors (`{FOCUS p _}`, `{_ p FOCUS}`), as well as the JSON form.
+ *
+ * @since 0.1.0
+ */
+import * as Context from 'effect/Context';
+import * as Iterable from 'effect/Iterable';
+import * as Effect from 'effect/Effect';
+import * as MutableHashSet from 'effect/MutableHashSet';
+import * as Option from 'effect/Option';
+import * as Result from 'effect/Result';
+import * as Compiler from '@thomasfosterau/effect-parse/Compiler';
+import * as Parser from '@thomasfosterau/effect-parse/Parser';
+import * as Token from '@thomasfosterau/effect-parse/Token';
+import * as Dataset from '../Dataset.ts';
+import * as Iri from '../Iri.ts';
+import { RdfParseError } from '../Serialization.ts';
+import * as Term from '../Term.ts';
+import * as TurtleGrammar from '../turtle/Grammar.ts';
+import * as Tokens from './internal/tokens.ts';
+import * as Predicate from 'effect/Predicate';
+
+const XSD = 'http://www.w3.org/2001/XMLSchema#';
+const RDF_TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
+
+/**
+ * The `START` shape of a schema.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Start {
+  readonly _tag: 'Start';
+}
+
+/**
+ * @since 0.1.0
+ * @category constructors
+ */
+export const start: Start = { _tag: 'Start' };
+
+/**
+ * A shape label or `START`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type ShapeSelector = string | Start;
+
+/**
+ * @since 0.1.0
+ * @category guards
+ */
+export const isStart = (s: ShapeSelector): s is Start => !Predicate.isString(s);
+
+/**
+ * A triple pattern selecting focus nodes: exactly one of `subject` and
+ * `object` is `'FOCUS'`; the other is a term or the wildcard `'_'`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface TriplePattern {
+  readonly _tag: 'TriplePattern';
+  readonly subject: Term.Subject | 'FOCUS' | '_';
+  readonly predicate: Term.NamedNode;
+  readonly object: Term.Object | 'FOCUS' | '_';
+}
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export type NodeSelector = Term.GroundTerm | TriplePattern;
+
+/**
+ * An association in a query shape map.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface QueryAssociation {
+  readonly node: NodeSelector;
+  readonly shape: ShapeSelector;
+}
+
+/**
+ * An association in a fixed shape map.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Association {
+  readonly node: Term.GroundTerm;
+  readonly shape: ShapeSelector;
+}
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export type QueryShapeMap = ReadonlyArray<QueryAssociation>;
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export type FixedShapeMap = ReadonlyArray<Association>;
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export interface ParseOptions {
+  readonly baseIri?: string | undefined;
+  readonly prefixes?: Readonly<Record<string, string>> | undefined;
+  /** Prefixes used only for shape labels (e.g. those of the schema). */
+  readonly shapePrefixes?: Readonly<Record<string, string>> | undefined;
+}
+
+/** The options of the current parse, for resolving IRIs. */
+class Options extends Context.Service<Options, ParseOptions>()(
+  '@thomasfosterau/effect-rdf/shex/ShapeMap/Options',
+) {}
+
+const lex = Tokens.lexeme;
+
+/**
+ * An IRI: an `IRIREF` resolved against the base IRI, or a prefixed name
+ * expanded with `prefixes` (falling back to the options' prefixes).
+ */
+const iri = (
+  prefixes: (options: ParseOptions) => Option.Option<Readonly<Record<string, string>>>,
+): Parser.Parser<string, string, Options> =>
+  Parser.alt(
+    Parser.seq(Parser.service(Options), TurtleGrammar.iriRef).pipe(
+      Parser.map(([{ baseIri }, value]) =>
+        baseIri === undefined || Iri.isAbsolute(value) ? value : Iri.resolve(value, baseIri),
+      ),
+    ),
+    // Once a prefixed name has matched, an unknown prefix is an error.
+    Parser.preceded(
+      Parser.peek(TurtleGrammar.prefixedName),
+      Parser.cut(
+        Parser.seq(Parser.service(Options), TurtleGrammar.prefixedName).pipe(
+          Parser.tryMap(([options, { prefix, local }]) => {
+            const ns = Option.orElse(
+              Option.flatMap(prefixes(options), (p) => Option.fromUndefinedOr(p[prefix])),
+              () => Option.fromUndefinedOr(options.prefixes?.[prefix]),
+            );
+            return Option.match(ns, {
+              onNone: () => Result.fail(`unknown prefix "${prefix}:"`),
+              onSome: (namespace) => Result.succeed(namespace + local),
+            });
+          }),
+        ),
+      ),
+    ),
+  );
+
+const noPrefixes = () => Option.none();
+
+const namedNode = iri(noPrefixes).pipe(Parser.map((value) => Term.namedNode(value)));
+
+const literal = Parser.seq(
+  TurtleGrammar.stringLiteral,
+  Parser.opt(
+    Parser.alt(
+      TurtleGrammar.langTag,
+      Parser.preceded(
+        Token.literal('^^'),
+        Parser.cut(lex(namedNode).pipe(Parser.expected('a datatype IRI'))),
+      ),
+    ),
+  ),
+).pipe(
+  Parser.map(([value, suffix]) =>
+    // The suffix is a language tag string or a datatype named node.
+    Option.match(suffix, {
+      onNone: () => Term.literal(value),
+      onSome: (s) => Term.literal(value, s),
+    }),
+  ),
+);
+
+const term: Parser.Parser<Term.GroundTerm, string, Options> = lex(
+  Parser.alt(
+    namedNode,
+    TurtleGrammar.blankNodeLabel.pipe(Parser.map((label) => Term.blankNode(label))),
+    literal,
+    TurtleGrammar.numericLiteral.pipe(
+      Parser.map(([value, type]) => Term.literal(value, Term.namedNode(XSD + type))),
+    ),
+    TurtleGrammar.booleanLiteral.pipe(
+      Parser.map((value) => Term.literal(value, Term.namedNode(`${XSD}boolean`))),
+    ),
+  ),
+);
+
+const predicate = lex(
+  Parser.alt(
+    Parser.terminated(
+      Token.literal('a'),
+      Parser.not(Token.oneOf([TurtleGrammar.pnChars, ':'])),
+    ).pipe(Parser.as(Term.namedNode(RDF_TYPE))),
+    namedNode,
+  ),
+).pipe(Parser.expected('a predicate'));
+
+const focus = lex(Tokens.keyword('FOCUS')).pipe(Parser.as('FOCUS' as const));
+const wildcard = lex(Parser.terminated(Token.literal('_'), Parser.not(Token.literal(':'))));
+
+const triplePattern = Parser.preceded(
+  lex(Token.literal('{')),
+  Parser.cut(
+    Parser.terminated(
+      Parser.seq(
+        Parser.alt(
+          focus,
+          wildcard,
+          term.pipe(
+            Parser.filter((t): t is Term.Subject => !Term.isLiteral(t)),
+            Parser.expected('a subject'),
+          ),
+        ),
+        predicate,
+        Parser.alt(focus, wildcard, term.pipe(Parser.expected('an object'))),
+      ),
+      lex(Token.literal('}')),
+    ).pipe(
+      Parser.tryMap(([subject, verb, object]) =>
+        (subject === 'FOCUS') === (object === 'FOCUS')
+          ? Result.fail('a triple pattern needs exactly one FOCUS')
+          : Result.succeed<NodeSelector>({
+              _tag: 'TriplePattern',
+              subject,
+              predicate: verb,
+              object,
+            }),
+      ),
+    ),
+  ),
+);
+
+const nodeSelector: Parser.Parser<NodeSelector, string, Options> = Parser.alt(
+  triplePattern,
+  term,
+).pipe(Parser.expected('a node selector'));
+
+const shapeSelector: Parser.Parser<ShapeSelector, string, Options> = Parser.preceded(
+  lex(Token.literal('@')),
+  Parser.cut(
+    Parser.alt(
+      lex(Tokens.keyword('START')).pipe(Parser.as(start)),
+      lex(iri((options) => Option.fromUndefinedOr(options.shapePrefixes))),
+      lex(TurtleGrammar.blankNodeLabel).pipe(Parser.map((label) => `_:${label}`)),
+    ).pipe(Parser.expected('a shape label')),
+  ),
+);
+
+const shapeMap: Parser.Parser<QueryShapeMap, string, Options> = Compiler.jit(
+  Parser.terminated(
+    Parser.separated(
+      Parser.struct({ node: nodeSelector, shape: shapeSelector }),
+      lex(Token.literal(',')),
+    ),
+    Tokens.skip,
+  ),
+);
+
+/**
+ * Parses a (query) shape map in the compact syntax.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export const parse = (
+  input: string,
+  options: ParseOptions = {},
+): Effect.Effect<QueryShapeMap, RdfParseError> =>
+  Effect.suspend(() => {
+    const result = Parser.parse(shapeMap, input, { context: Context.make(Options, options) });
+    if (Result.isSuccess(result)) return Effect.succeed(result.success);
+    const error = result.failure;
+    const { line, column } = error.position;
+    const message = error.cause ?? error.message.slice(error.message.lastIndexOf('\n') + 1);
+    return Effect.fail(new RdfParseError({ format: 'ShapeMap', message, line, column }));
+  });
+
+// Compiled once; the options reach `Parser.service(Options)` through the run's
+// context rather than a `provideService` wrapper built per call.
+const groundTerm = Compiler.jit(Parser.terminated(term, Tokens.skip));
+
+/**
+ * Parses a single RDF term in N-Triples / Turtle notation (`<iri>`,
+ * `_:label`, `"lexical"^^<dt>`, …), as used by the JSON form of shape maps.
+ * A bare string that is not a term is taken as an IRI.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export const parseTerm = (input: string, options: ParseOptions = {}): Term.GroundTerm => {
+  const result = Parser.parse(groundTerm, input, { context: Context.make(Options, options) });
+  if (Result.isSuccess(result)) return result.success;
+  if (input.startsWith('_:')) return Term.blankNode(input.slice(2));
+  return Term.namedNode(
+    options.baseIri === undefined || Iri.isAbsolute(input)
+      ? input
+      : Iri.resolve(input, options.baseIri),
+  );
+};
+
+/**
+ * Reads the JSON form of a fixed shape map: an array of
+ * `{ "node": term, "shape": label | "START" }` objects. Node terms use
+ * N-Triples notation or are bare IRIs.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export const fromJson = (json: unknown, options: ParseOptions = {}): FixedShapeMap => {
+  if (!Array.isArray(json)) return [];
+  return json.map((entry: { node: string; shape: string }) => ({
+    node: parseTerm(entry.node, options),
+    shape:
+      entry.shape === 'START'
+        ? start
+        : entry.shape.startsWith('_:') ||
+            options.baseIri === undefined ||
+            Iri.isAbsolute(entry.shape)
+          ? entry.shape
+          : Iri.resolve(entry.shape, options.baseIri),
+  }));
+};
+
+/**
+ * Resolves a query shape map against a dataset, producing a fixed shape map
+ * (duplicates removed, order preserved).
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export const resolve = (map: QueryShapeMap, dataset: Dataset.Dataset): FixedShapeMap => {
+  const out: Array<Association> = [];
+  const seen = MutableHashSet.empty<string>();
+  const push = (node: Term.GroundTerm, shape: ShapeSelector) => {
+    const key = `${node.key} ${isStart(shape) ? '' : shape}`;
+    if (MutableHashSet.has(seen, key)) return;
+    MutableHashSet.add(seen, key);
+    out.push({ node, shape });
+  };
+  map.forEach(({ node, shape }) => {
+    if (!Predicate.isTagged(node, 'TriplePattern')) return push(node, shape);
+    const pattern: Dataset.Pattern = {
+      predicate: node.predicate,
+      subject: node.subject !== 'FOCUS' && node.subject !== '_' ? node.subject : undefined,
+      object: node.object !== 'FOCUS' && node.object !== '_' ? node.object : undefined,
+    };
+    Iterable.forEach(Dataset.match(dataset, pattern), (q) =>
+      push(node.subject === 'FOCUS' ? q.subject : q.object, shape),
+    );
+  });
+  return out;
+};
+
+/**
+ * Formats a shape selector for display.
+ *
+ * @since 0.1.0
+ * @category formatting
+ */
+export const formatShape = (shape: ShapeSelector): string =>
+  isStart(shape) ? 'START' : shape.startsWith('_:') ? shape : `<${shape}>`;
+
+/**
+ * Formats a fixed shape map in the compact syntax.
+ *
+ * @since 0.1.0
+ * @category formatting
+ */
+export const format = (map: FixedShapeMap): string =>
+  map.map((a) => `${a.node.key}@${formatShape(a.shape)}`).join(',\n');