@thomasfosterau/effect-rdf 0.0.0 → 0.1.0

package/src/shacl/Vocabulary.ts

@@ -0,0 +1,180 @@
+/**
+ * The SHACL vocabulary (`sh:`, `http://www.w3.org/ns/shacl#`).
+ *
+ * ```ts
+ * import { Vocabulary } from "@thomasfosterau/effect-rdf/shacl"
+ *
+ * Vocabulary.sh.NodeShape // NamedNode<"http://www.w3.org/ns/shacl#NodeShape">
+ * ```
+ *
+ * @since 0.1.0
+ */
+import { Namespace } from '../index.ts';
+
+/**
+ * The SHACL namespace IRI.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export const SH = 'http://www.w3.org/ns/shacl#';
+
+/**
+ * The SHACL vocabulary: classes, properties and individuals of SHACL Core and
+ * SHACL-SPARQL.
+ *
+ * @since 0.1.0
+ * @category vocabularies
+ */
+export const sh = Namespace.vocabulary(SH, [
+  // Shapes and targets
+  'Shape',
+  'NodeShape',
+  'PropertyShape',
+  'targetNode',
+  'targetClass',
+  'targetSubjectsOf',
+  'targetObjectsOf',
+  'target',
+  'Target',
+  'TargetType',
+  'SPARQLTarget',
+  'SPARQLTargetType',
+  'severity',
+  'message',
+  'deactivated',
+  'path',
+  'name',
+  'description',
+  'order',
+  'group',
+  'defaultValue',
+  'shapesGraph',
+  'suggestedShapesGraph',
+  'entailment',
+  'declare',
+  'prefix',
+  'namespace',
+  'prefixes',
+  'PrefixDeclaration',
+  // Paths
+  'alternativePath',
+  'inversePath',
+  'zeroOrMorePath',
+  'oneOrMorePath',
+  'zeroOrOnePath',
+  // Severities
+  'Severity',
+  'Info',
+  'Warning',
+  'Violation',
+  // Validation reports
+  'ValidationReport',
+  'ValidationResult',
+  'AbstractResult',
+  'conforms',
+  'result',
+  'focusNode',
+  'resultPath',
+  'value',
+  'sourceShape',
+  'sourceConstraint',
+  'sourceConstraintComponent',
+  'resultSeverity',
+  'resultMessage',
+  'detail',
+  // Node kinds
+  'NodeKind',
+  'BlankNode',
+  'IRI',
+  'Literal',
+  'BlankNodeOrIRI',
+  'BlankNodeOrLiteral',
+  'IRIOrLiteral',
+  // Constraint parameters
+  'class',
+  'datatype',
+  'nodeKind',
+  'minCount',
+  'maxCount',
+  'minExclusive',
+  'minInclusive',
+  'maxExclusive',
+  'maxInclusive',
+  'minLength',
+  'maxLength',
+  'pattern',
+  'flags',
+  'languageIn',
+  'uniqueLang',
+  'equals',
+  'disjoint',
+  'lessThan',
+  'lessThanOrEquals',
+  'not',
+  'and',
+  'or',
+  'xone',
+  'node',
+  'property',
+  'qualifiedValueShape',
+  'qualifiedValueShapesDisjoint',
+  'qualifiedMinCount',
+  'qualifiedMaxCount',
+  'closed',
+  'ignoredProperties',
+  'hasValue',
+  'in',
+  // Constraint components
+  'ConstraintComponent',
+  'Parameter',
+  'Parameterizable',
+  'parameter',
+  'optional',
+  'validator',
+  'nodeValidator',
+  'propertyValidator',
+  'Validator',
+  'SPARQLAskValidator',
+  'SPARQLSelectValidator',
+  'labelTemplate',
+  'ClassConstraintComponent',
+  'DatatypeConstraintComponent',
+  'NodeKindConstraintComponent',
+  'MinCountConstraintComponent',
+  'MaxCountConstraintComponent',
+  'MinExclusiveConstraintComponent',
+  'MinInclusiveConstraintComponent',
+  'MaxExclusiveConstraintComponent',
+  'MaxInclusiveConstraintComponent',
+  'MinLengthConstraintComponent',
+  'MaxLengthConstraintComponent',
+  'PatternConstraintComponent',
+  'LanguageInConstraintComponent',
+  'UniqueLangConstraintComponent',
+  'EqualsConstraintComponent',
+  'DisjointConstraintComponent',
+  'LessThanConstraintComponent',
+  'LessThanOrEqualsConstraintComponent',
+  'NotConstraintComponent',
+  'AndConstraintComponent',
+  'OrConstraintComponent',
+  'XoneConstraintComponent',
+  'NodeConstraintComponent',
+  'PropertyConstraintComponent',
+  'QualifiedMinCountConstraintComponent',
+  'QualifiedMaxCountConstraintComponent',
+  'ClosedConstraintComponent',
+  'HasValueConstraintComponent',
+  'InConstraintComponent',
+  // SHACL-SPARQL
+  'sparql',
+  'select',
+  'ask',
+  'SPARQLConstraint',
+  'SPARQLConstraintComponent',
+  'SPARQLExecutable',
+  'SPARQLSelectExecutable',
+  'SPARQLAskExecutable',
+  'this',
+]);

package/src/shacl/index.ts

@@ -0,0 +1,22 @@
+/**
+ * SHACL Core validation for `@thomasfosterau/effect-rdf`: typed shapes
+ * graphs, property paths, validation reports and an Effect-native validator
+ * with an extension point for SHACL-SPARQL.
+ *
+ * @since 0.1.0
+ */
+
+/** @since 0.1.0 */
+export * as Message from './Message.ts';
+/** @since 0.1.0 */
+export * as Path from './Path.ts';
+/** @since 0.1.0 */
+export * as Shapes from './Shapes.ts';
+/** @since 0.1.0 */
+export * as Sparql from './Sparql.ts';
+/** @since 0.1.0 */
+export * as ValidationReport from './ValidationReport.ts';
+/** @since 0.1.0 */
+export * as Validator from './Validator.ts';
+/** @since 0.1.0 */
+export * as Vocabulary from './Vocabulary.ts';

package/src/shacl/internal/compare.ts

@@ -0,0 +1,128 @@
+/**
+ * Ordering of RDF terms following the SPARQL `<` operator, as required by the
+ * SHACL value range and property pair constraint components.
+ *
+ * @internal
+ */
+import { Term, Xsd } from '../../index.ts';
+import * as BigDecimal from 'effect/BigDecimal';
+import * as Match from 'effect/Match';
+import * as Option from 'effect/Option';
+import * as Predicate from 'effect/Predicate';
+
+const XSD_STRING = 'http://www.w3.org/2001/XMLSchema#string';
+
+type Sign = -1 | 0 | 1;
+
+type Num =
+  | { readonly kind: 'integer'; readonly value: bigint }
+  | { readonly kind: 'decimal'; readonly value: BigDecimal.BigDecimal }
+  | { readonly kind: 'float'; readonly value: number };
+
+// Built once: `toNum` runs for every numeric comparison.
+const toNum: (v: Xsd.Value) => Option.Option<Num> = Match.type<Xsd.Value>().pipe(
+  Match.tag('Integer', (v) => Option.some<Num>({ kind: 'integer', value: v.value })),
+  Match.tag('Decimal', (v) => Option.some<Num>({ kind: 'decimal', value: v.value })),
+  Match.tag('Float', 'Double', (v) => Option.some<Num>({ kind: 'float', value: v.value })),
+  Match.orElse(() => Option.none<Num>()),
+);
+
+const sign = (n: number): Sign => (n < 0 ? -1 : n > 0 ? 1 : 0);
+
+const toFloat = (n: Num): number =>
+  n.kind === 'float'
+    ? n.value
+    : Number(n.kind === 'integer' ? n.value : BigDecimal.format(n.value));
+
+const toDecimal = (n: Exclude<Num, { readonly kind: 'float' }>): BigDecimal.BigDecimal =>
+  n.kind === 'integer' ? BigDecimal.fromBigInt(n.value) : n.value;
+
+const compareNum = (a: Num, b: Num): Option.Option<Sign> => {
+  if (a.kind === 'float' || b.kind === 'float') {
+    const x = toFloat(a);
+    const y = toFloat(b);
+    if (Number.isNaN(x) || Number.isNaN(y)) return Option.none();
+    return Option.some(sign(x - y) || (x < y ? -1 : x > y ? 1 : 0));
+  }
+  if (a.kind === 'integer' && b.kind === 'integer')
+    return Option.some(a.value < b.value ? -1 : a.value > b.value ? 1 : 0);
+  return Option.some(BigDecimal.Order(toDecimal(a), toDecimal(b)));
+};
+
+const FOURTEEN_HOURS = 14 * 60 * 60 * 1000;
+
+const order = <A>(x: A, y: A): Sign => (x < y ? -1 : x > y ? 1 : 0);
+
+const isString = Predicate.isTagged('String');
+const isBoolean = Predicate.isTagged('Boolean');
+const isDateTime = Predicate.isTagged('DateTime');
+const isDuration = Predicate.isTagged('Duration');
+const isOther = Predicate.isTagged('Other');
+
+/** Simple literals / xsd:string are ordered; language-tagged strings only when they share a tag. */
+const stringsComparable = (a: Term.Literal, b: Term.Literal): boolean =>
+  a.language !== '' || b.language !== ''
+    ? a.language.toLowerCase() === b.language.toLowerCase()
+    : a.datatype.value === XSD_STRING && b.datatype.value === XSD_STRING;
+
+const none = Option.none<Sign>();
+
+const compareDateTimes = (
+  x: Extract<Xsd.Value, { readonly _tag: 'DateTime' }>,
+  y: Extract<Xsd.Value, { readonly _tag: 'DateTime' }>,
+): Option.Option<Sign> => {
+  if (x.kind !== y.kind) return none;
+  const d = x.epochMillis - y.epochMillis;
+  // One value has a timezone and the other does not: the result is only
+  // determinate when they are more than 14 hours apart.
+  return Predicate.isUndefined(x.timezone) === Predicate.isUndefined(y.timezone) ||
+    Math.abs(d) > FOURTEEN_HOURS
+    ? Option.some(sign(d))
+    : none;
+};
+
+const compareDurations = (
+  x: Extract<Xsd.Value, { readonly _tag: 'Duration' }>,
+  y: Extract<Xsd.Value, { readonly _tag: 'Duration' }>,
+): Option.Option<Sign> => {
+  const m = sign(x.months - y.months);
+  const s = sign(x.seconds - y.seconds);
+  if (m === 0) return Option.some(s);
+  return s === 0 || s === m ? Option.some(m) : none;
+};
+
+// Plain guards rather than a `Match`: this runs for every value of every
+// range and property pair constraint. The right value must be of the same kind.
+const compareValues = (
+  va: Xsd.Value,
+  vb: Xsd.Value,
+  a: Term.Literal,
+  b: Term.Literal,
+): Option.Option<Sign> => {
+  if (isString(va))
+    return isString(vb) && stringsComparable(a, b) ? Option.some(order(va.value, vb.value)) : none;
+  if (isBoolean(va))
+    return isBoolean(vb) ? Option.some(va.value === vb.value ? 0 : va.value ? 1 : -1) : none;
+  if (isDateTime(va)) return isDateTime(vb) ? compareDateTimes(va, vb) : none;
+  if (isDuration(va)) return isDuration(vb) ? compareDurations(va, vb) : none;
+  return isOther(va) && isOther(vb) && a.key === b.key ? Option.some(0) : none;
+};
+
+const compareLiterals = (a: Term.Literal, b: Term.Literal): Option.Option<Sign> => {
+  const va = Xsd.toValue(a);
+  const vb = Xsd.toValue(b);
+  const na = toNum(va);
+  const nb = toNum(vb);
+  if (Option.isSome(na) && Option.isSome(nb)) return compareNum(na.value, nb.value);
+  if (Option.isSome(na) || Option.isSome(nb)) return Option.none();
+  return compareValues(va, vb, a, b);
+};
+
+/**
+ * Compares two terms. Returns `None` when they are not comparable (in which
+ * case every SPARQL comparison yields an error, i.e. false).
+ *
+ * @internal
+ */
+export const compareTerms = (a: Term.Term, b: Term.Term): Option.Option<Sign> =>
+  Term.isLiteral(a) && Term.isLiteral(b) ? compareLiterals(a, b) : Option.none();

package/src/shacl/internal/regex.ts

@@ -0,0 +1,56 @@
+/**
+ * Translation of XPath/XML Schema regular expressions (as used by
+ * `sh:pattern` and `sh:flags`) to JavaScript `RegExp`s.
+ *
+ * @internal
+ */
+import * as Arr from 'effect/Array';
+import * as Option from 'effect/Option';
+import * as Result from 'effect/Result';
+import * as Schema from 'effect/Schema';
+
+/** A string as a JSON string literal, for messages. */
+const quote = Schema.encodeSync(Schema.fromJsonString(Schema.String));
+
+const escapeAll = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Removes whitespace outside character classes (the XPath `x` flag). */
+const stripWhitespace = (s: string): string => {
+  let inClass = false;
+  return s.replace(/\\[\s\S]?|[[\]]|[\t\n\r ]/g, (token) => {
+    if (token === '[') inClass = true;
+    else if (token === ']') inClass = false;
+    else if (WHITESPACE.test(token)) return inClass ? token : '';
+    return token;
+  });
+};
+
+const WHITESPACE = /^[\t\n\r ]$/;
+
+/**
+ * Compiles an XPath regular expression with optional XPath flags
+ * (`s`, `m`, `i`, `x`, `q`). Fails with an error message for invalid input.
+ *
+ * @internal
+ */
+export const compile = (pattern: string, flags: string): Result.Result<RegExp, string> => {
+  const chars = Arr.fromIterable(flags);
+  const unsupported = Arr.findFirst(chars, (f) => !'smixq'.includes(f));
+  if (Option.isSome(unsupported))
+    return Result.fail(`unsupported regular expression flag '${unsupported.value}'`);
+  const jsFlags = Arr.join(Arr.dedupe(Arr.filter(chars, (f) => 'smi'.includes(f))), '');
+  const source = flags.includes('q')
+    ? escapeAll(pattern)
+    : flags.includes('x')
+      ? stripWhitespace(pattern)
+      : pattern;
+  // Unicode mode first (XPath character classes need it), then the legacy
+  // syntax that accepts the escapes Unicode mode rejects.
+  return Result.mapError(
+    Result.orElse(
+      Result.try(() => new RegExp(source, `${jsFlags}u`)),
+      () => Result.try(() => new RegExp(source, jsFlags)),
+    ),
+    (failure) => `invalid regular expression ${quote(pattern)}: ${String(failure)}`,
+  );
+};

package/src/shex/SemAct.ts

@@ -0,0 +1,197 @@
+/**
+ * Semantic actions: a pluggable `SemActHandler` service consulted by the
+ * validator for every semantic action it encounters, and an implementation
+ * of the ShEx Test extension (`http://shex.io/extensions/Test/`).
+ *
+ * Actions whose name no handler recognises are ignored (they succeed), as
+ * the ShEx specification recommends.
+ *
+ * @since 0.1.0
+ */
+import * as Arr from 'effect/Array';
+import * as Context from 'effect/Context';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import * as Record from 'effect/Record';
+import * as Term from '../Term.ts';
+import type * as ShExJ from './ShExJ.ts';
+
+/**
+ * Where a semantic action was found.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type SemActSite =
+  | 'start'
+  | 'shape'
+  | 'tripleExpression'
+  | 'tripleConstraint'
+  | 'nodeConstraint';
+
+/**
+ * The context a semantic action is evaluated in.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface SemActContext {
+  readonly site: SemActSite;
+  /** The node being validated (the focus node, or the value node for node constraints). */
+  readonly node: Term.Term | undefined;
+  /** For triple constraint actions: the matched triple (as written in the data). */
+  readonly triple?: Term.Triple | undefined;
+  /** For shape and triple expression actions: the triples matched. */
+  readonly triples?: ReadonlyArray<Term.Triple> | undefined;
+}
+
+/**
+ * Evaluates a semantic action: `Option.some(true)` for success,
+ * `Option.some(false)` for failure, `Option.none()` when the action is not
+ * handled (it is then ignored).
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type Handler = (action: ShExJ.SemAct, context: SemActContext) => Option.Option<boolean>;
+
+/**
+ * The semantic action handler used by the validator. Defaults to ignoring
+ * every action.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export const SemActHandler: Context.Reference<Handler> = Context.Reference<Handler>(
+  '@thomasfosterau/effect-rdf/shex/SemActHandler',
+  { defaultValue: () => () => Option.none() },
+);
+
+/**
+ * Builds a handler dispatching on action names. A handler registered for a
+ * name ending in `/` or `#` also handles every name it is a prefix of.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const make = (
+  handlers: Record.ReadonlyRecord<
+    string,
+    (code: string | undefined, context: SemActContext) => boolean
+  >,
+): Handler => {
+  const prefixes = Arr.filter(
+    Record.toEntries(handlers),
+    ([name]) => name.endsWith('/') || name.endsWith('#'),
+  );
+  return (action, context) => {
+    const exact = handlers[action.name];
+    if (exact !== undefined) return Option.some(exact(action.code, context));
+    return Option.map(
+      Arr.findFirst(prefixes, ([name]) => action.name.startsWith(name)),
+      ([, h]) => h(action.code, context),
+    );
+  };
+};
+
+/**
+ * Combines handlers: the first one that handles an action wins.
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export const combine =
+  (...handlers: ReadonlyArray<Handler>): Handler =>
+  (action, context) =>
+    Arr.findFirst(handlers, (h) => h(action, context));
+
+/**
+ * Supplies code for actions written without code (`%<name>%`), e.g. from an
+ * external semantic actions file. Actions are matched by name.
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export const withExternalCode =
+  (handler: Handler, external: ReadonlyArray<ShExJ.SemAct>): Handler =>
+  (action, context) => {
+    if (action.code === undefined) {
+      const ext = external.find((e) => e.name === action.name && e.code !== undefined);
+      if (ext !== undefined) return handler(ext, context);
+    }
+    return handler(action, context);
+  };
+
+/**
+ * A layer providing a handler.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layer = (handler: Handler): Layer.Layer<never> =>
+  Layer.succeed(SemActHandler, handler);
+
+// -----------------------------------------------------------------------------
+// The Test extension
+// -----------------------------------------------------------------------------
+
+/**
+ * The namespace of the ShEx Test extension.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export const testExtensionIri = 'http://shex.io/extensions/Test/';
+
+const termText = (t: Term.Term): string =>
+  Term.isLiteral(t)
+    ? t.language !== ''
+      ? `"${t.value}"@${t.language}`
+      : t.datatype.value === 'http://www.w3.org/2001/XMLSchema#string'
+        ? t.value
+        : `"${t.value}"^^${t.datatype.value}`
+    : Term.isResource(t)
+      ? t.value
+      : t.key;
+
+const unescapeBackslashes = (s: string) => s.replace(/\\(.)/gs, '$1');
+
+/**
+ * The ShEx Test extension: `print(s|p|o|n|"text")` records a line and
+ * succeeds, `fail(...)` records a line and fails. The `onPrint` callback
+ * receives each line together with the action name.
+ *
+ * @since 0.1.0
+ * @category test extension
+ */
+export const testExtension = (
+  onPrint: (line: string, name: string) => void = () => {},
+): Handler => {
+  const re =
+    /^\s*(print|fail|p)\s*\(\s*(?:([spon])|"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)')\s*\)\s*$/s;
+  return (action, context) => {
+    if (!action.name.startsWith(testExtensionIri)) return Option.none();
+    if (action.code === undefined) return Option.some(true);
+    const m = re.exec(action.code);
+    if (m === null) return Option.some(true);
+    const [, fn, v, dq, sq] = m;
+    let line: string;
+    if (v !== undefined) {
+      const t = context.triple;
+      line = Option.match(
+        Option.fromUndefinedOr(
+          v === 's'
+            ? (t?.subject ?? context.node)
+            : v === 'p'
+              ? t?.predicate
+              : v === 'o'
+                ? (t?.object ?? context.node)
+                : context.node,
+        ),
+        { onNone: () => '', onSome: termText },
+      );
+    } else line = unescapeBackslashes(dq ?? sq ?? '');
+    onPrint(line, action.name);
+    return Option.some(fn !== 'fail');
+  };
+};