@thomasfosterau/effect-rdf 0.0.0-stage → 0.1.0

package/src/sparql/Errors.ts

@@ -0,0 +1,30 @@
+/**
+ * Errors raised while evaluating queries and updates.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from 'effect/Schema';
+
+/**
+ * A failure while evaluating a query (other than expression errors, which
+ * SPARQL handles internally), e.g. a failing `SERVICE` call.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export class EvaluationError extends Schema.TaggedError<EvaluationError>()('EvaluationError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect()),
+}) {}
+
+/**
+ * A failure of an update operation, e.g. `CREATE GRAPH` on an existing graph
+ * or `DROP GRAPH` on a missing one (without `SILENT`).
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export class UpdateError extends Schema.TaggedError<UpdateError>()('UpdateError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect()),
+}) {}

package/src/sparql/Expression.ts

@@ -0,0 +1,360 @@
+/**
+ * Evaluation of SPARQL expressions over solution mappings: all operators and
+ * functional forms (`&&`, `||`, `!`, `IN`, `IF`, `COALESCE`, `BOUND`,
+ * `EXISTS`), the built-in functions of SPARQL 1.1 and 1.2, XSD casts and
+ * extension functions, with SPARQL's error semantics.
+ *
+ * Also exports the effective boolean value, value equality / ordering and
+ * the `ORDER BY` term ordering.
+ *
+ * @since 0.1.0
+ */
+import * as Arr from 'effect/Array';
+import * as DateTime from 'effect/DateTime';
+import * as MutableHashMap from 'effect/MutableHashMap';
+import * as Option from 'effect/Option';
+import * as Predicate from 'effect/Predicate';
+import * as Random from 'effect/Random';
+import * as Result from 'effect/Result';
+import * as Term from '../Term.ts';
+import type * as Algebra from './Algebra.ts';
+import type * as Ast from './Ast.ts';
+import type { Bindings } from './Bindings.ts';
+import * as Functions from './Functions.ts';
+import * as V from './internal/values.ts';
+
+/**
+ * The context of expression evaluation.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Context extends Functions.FunctionContext {
+  /** Extension functions by IRI. */
+  readonly functions: Functions.Registry;
+  /**
+   * Evaluates an `EXISTS` pattern for a solution. The engine precomputes
+   * these (pattern evaluation is effectful) before evaluating the
+   * expression; without it `EXISTS` is an error.
+   */
+  readonly exists?: ((e: Algebra.ExistsExpression, solution: Bindings) => boolean) | undefined;
+}
+
+/**
+ * Creates an evaluation context.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const makeContext = (options?: {
+  readonly now?: Date | undefined;
+  readonly baseIri?: string | undefined;
+  readonly functions?: Functions.Registry | undefined;
+  readonly random?: (() => number) | undefined;
+}): Context => {
+  const scopes = new WeakMap<Bindings, MutableHashMap.MutableHashMap<string, Term.BlankNode>>();
+  let counter = 0;
+  // A plain constructor, outside any Effect: the defaults are the default
+  // `Random` service (`Math.random`) and the current time.
+  const defaultRandom = Random.Random.defaultValue();
+  const prefix = `e${Math.floor(defaultRandom.nextDoubleUnsafe() * 0xffffff).toString(36)}_`;
+  return {
+    now: options?.now ?? DateTime.toDateUtc(DateTime.nowUnsafe()),
+    baseIri: options?.baseIri,
+    functions: options?.functions ?? Functions.registry({}),
+    random: options?.random ?? (() => defaultRandom.nextDoubleUnsafe()),
+    blankNode: (label, solution) => {
+      if (label === undefined) return Term.blankNode(`${prefix}${counter++}`);
+      const row = solution.origin ?? solution;
+      let scope = scopes.get(row);
+      if (scope === undefined) scopes.set(row, (scope = MutableHashMap.empty()));
+      const existing = MutableHashMap.get(scope, label);
+      if (Option.isSome(existing)) return existing.value;
+      const node = Term.blankNode(`${prefix}${counter++}`);
+      MutableHashMap.set(scope, label, node);
+      return node;
+    },
+  };
+};
+
+/**
+ * A term with its variables replaced by their bindings. Plain branches rather
+ * than `Match`: it runs for every variable of every evaluated expression.
+ */
+const substitute = (t: Term.Term, solution: Bindings): Term.GroundTerm => {
+  if (Term.isVariable(t))
+    return solution.map.get(t.value) ?? V.fail(`Unbound variable ?${t.value}`);
+  if (Term.isTriple(t)) {
+    // Substitution keeps each position's kind for the ground terms a pattern can be bound to;
+    // like the triple patterns it comes from, the result is not checked again.
+    return Term.triple<any, any, any>(
+      substitute(t.subject, solution),
+      substitute(t.predicate, solution),
+      substitute(t.object, solution),
+    );
+  }
+  if (Term.isDefaultGraph(t)) return V.fail('Invalid term');
+  return t;
+};
+
+/**
+ * Evaluates an expression; throws `EvalFailure` on errors. Plain branches
+ * rather than `Match`: it runs once per expression node per solution.
+ *
+ * @internal
+ */
+export const evaluateUnsafe = (
+  e: Algebra.Expression,
+  solution: Bindings,
+  ctx: Context,
+): Term.GroundTerm => {
+  if (Predicate.isTagged(e, 'Operation')) return operation(e, solution, ctx);
+  if (Term.isVariable(e) || Term.isTriple(e)) return substitute(e, solution);
+  if (Predicate.isTagged(e, 'FunctionCall')) return functionCall(e, solution, ctx);
+  if (Predicate.isTagged(e, 'Exists')) {
+    if (ctx.exists === undefined) return V.fail('EXISTS is not supported here');
+    const r = ctx.exists(e, solution);
+    return V.bool(e.negated ? !r : r);
+  }
+  return e;
+};
+
+const functionCall = (
+  call: Algebra.FunctionCallExpression,
+  solution: Bindings,
+  ctx: Context,
+): Term.GroundTerm => {
+  const iri = call.function.value;
+  const args = call.args.map((a) => evaluateUnsafe(a, solution, ctx));
+  const f = ctx.functions.get(iri);
+  if (f !== undefined) return f(args, ctx);
+  if (Functions.isCast(iri)) {
+    const [arg, ...rest] = args;
+    if (arg === undefined || Arr.isReadonlyArrayNonEmpty(rest)) {
+      return V.fail('Casts take one argument');
+    }
+    return Functions.cast(iri, arg);
+  }
+  return V.fail(`Unknown function <${iri}>`);
+};
+
+const ebvOf = (e: Algebra.Expression, solution: Bindings, ctx: Context): boolean =>
+  V.ebv(evaluateUnsafe(e, solution, ctx));
+
+const toError = (failure: V.EvalFailure): Functions.ExpressionError =>
+  new Functions.ExpressionError({ message: failure.message });
+
+const attempt = <A>(f: () => A): A | V.EvalFailure => Result.merge(V.catchEvalFailure(f));
+
+/** Argument `i` of an operation (the parser checked each operator's arity). */
+const argAt = (e: Algebra.OperationExpression, i: number): Algebra.Expression =>
+  e.args[i] ?? V.fail(`${e.operator} is missing argument ${i + 1}`);
+
+/** Evaluates argument `i` of an operation. */
+const argOf = (e: Algebra.OperationExpression, i: number, solution: Bindings, ctx: Context) =>
+  evaluateUnsafe(argAt(e, i), solution, ctx);
+
+const or = (e: Algebra.OperationExpression, solution: Bindings, ctx: Context): Term.GroundTerm => {
+  const a = attempt(() => ebvOf(argAt(e, 0), solution, ctx));
+  if (a === true) return V.TRUE;
+  const b = ebvOf(argAt(e, 1), solution, ctx);
+  if (b) return V.TRUE;
+  if (a instanceof V.EvalFailure) throw a;
+  return V.FALSE;
+};
+
+const and = (e: Algebra.OperationExpression, solution: Bindings, ctx: Context): Term.GroundTerm => {
+  const a = attempt(() => ebvOf(argAt(e, 0), solution, ctx));
+  if (a === false) return V.FALSE;
+  const b = ebvOf(argAt(e, 1), solution, ctx);
+  if (!b) return V.FALSE;
+  if (a instanceof V.EvalFailure) throw a;
+  return V.TRUE;
+};
+
+const order = (
+  op: '<' | '>' | '<=' | '>=',
+  e: Algebra.OperationExpression,
+  solution: Bindings,
+  ctx: Context,
+): Term.GroundTerm => {
+  const a = argOf(e, 0, solution, ctx);
+  const b = argOf(e, 1, solution, ctx);
+  if (!Term.isLiteral(a) || !Term.isLiteral(b)) return V.fail('Cannot order non-literals');
+  const c = V.compareLiterals(a, b);
+  if (Number.isNaN(c)) return V.FALSE;
+  return V.bool(op === '<' ? c < 0 : op === '>' ? c > 0 : op === '<=' ? c <= 0 : c >= 0);
+};
+
+const isIn = (
+  e: Algebra.OperationExpression,
+  solution: Bindings,
+  ctx: Context,
+  negated: boolean,
+): Term.GroundTerm => {
+  const value = argOf(e, 0, solution, ctx);
+  let failure = Option.none<V.EvalFailure>();
+  const found = e.args.some((x, i) => {
+    if (i === 0) return false;
+    const r = attempt(() => V.equals(value, evaluateUnsafe(x, solution, ctx)));
+    if (r instanceof V.EvalFailure) failure = Option.some(r);
+    return r === true;
+  });
+  if (found) return V.bool(!negated);
+  if (Option.isSome(failure)) throw failure.value;
+  return V.bool(negated);
+};
+
+const coalesce = (
+  e: Algebra.OperationExpression,
+  solution: Bindings,
+  ctx: Context,
+): Term.GroundTerm => {
+  let value = Option.none<Term.GroundTerm>();
+  e.args.some((x) => {
+    const r = attempt(() => evaluateUnsafe(x, solution, ctx));
+    if (r instanceof V.EvalFailure) return false;
+    value = Option.some(r);
+    return true;
+  });
+  return Option.isSome(value) ? value.value : V.fail('COALESCE: no argument could be evaluated');
+};
+
+const builtIn = (
+  op: Ast.BuiltInName,
+  e: Algebra.OperationExpression,
+  solution: Bindings,
+  ctx: Context,
+): Term.GroundTerm => {
+  const f = Functions.builtIns[op];
+  if (f === undefined) return V.fail(`Unsupported operator ${op}`);
+  const values = e.args.map((a) => evaluateUnsafe(a, solution, ctx));
+  // SAFETY: `BuiltInArgs` types the first three slots as present; each built-in checks its own
+  // arity before reading them.
+  return f(values as unknown as Functions.BuiltInArgs, ctx, solution);
+};
+
+/**
+ * Evaluates an operation, by operator. Plain branches rather than `Match`:
+ * it runs once per operation per solution.
+ */
+const operation = (
+  e: Algebra.OperationExpression,
+  solution: Bindings,
+  ctx: Context,
+): Term.GroundTerm => {
+  const op = e.operator;
+  if (op === '||') return or(e, solution, ctx);
+  if (op === '&&') return and(e, solution, ctx);
+  if (op === '=') return V.bool(V.equals(argOf(e, 0, solution, ctx), argOf(e, 1, solution, ctx)));
+  if (op === '!=') {
+    return V.bool(!V.equals(argOf(e, 0, solution, ctx), argOf(e, 1, solution, ctx)));
+  }
+  if (op === '<' || op === '>' || op === '<=' || op === '>=') return order(op, e, solution, ctx);
+  if (op === '!') return V.bool(!ebvOf(argAt(e, 0), solution, ctx));
+  if (op === '+' || op === '-' || op === '*' || op === '/') {
+    return V.arithmetic(op, argOf(e, 0, solution, ctx), argOf(e, 1, solution, ctx));
+  }
+  if (op === 'UPLUS') {
+    const a = argOf(e, 0, solution, ctx);
+    return V.isNumeric(a) ? a : V.fail('Unary plus of a non-numeric');
+  }
+  if (op === 'UMINUS') return V.negate(argOf(e, 0, solution, ctx));
+  if (op === 'IN' || op === 'NOT IN') return isIn(e, solution, ctx, op === 'NOT IN');
+  if (op === 'BOUND') {
+    const v = e.args[0];
+    return V.bool(Term.isVariable(v) && solution.map.has(v.value));
+  }
+  if (op === 'IF') {
+    return ebvOf(argAt(e, 0), solution, ctx)
+      ? argOf(e, 1, solution, ctx)
+      : argOf(e, 2, solution, ctx);
+  }
+  if (op === 'COALESCE') return coalesce(e, solution, ctx);
+  return builtIn(op, e, solution, ctx);
+};
+
+/**
+ * Evaluates an expression against a solution.
+ *
+ * @since 0.1.0
+ * @category evaluation
+ */
+export const evaluate = (
+  expression: Algebra.Expression,
+  solution: Bindings,
+  context: Context,
+): Result.Result<Term.GroundTerm, Functions.ExpressionError> =>
+  Result.mapError(
+    V.catchEvalFailure(() => evaluateUnsafe(expression, solution, context)),
+    toError,
+  );
+
+/**
+ * Evaluates an expression, returning `undefined` on errors.
+ *
+ * @since 0.1.0
+ * @category evaluation
+ */
+export const evaluateOrUndefined = (
+  expression: Algebra.Expression,
+  solution: Bindings,
+  context: Context,
+): Term.GroundTerm | undefined =>
+  Result.getOrUndefined(V.catchEvalFailure(() => evaluateUnsafe(expression, solution, context)));
+
+/**
+ * Evaluates a filter condition: the effective boolean value of the
+ * expression, with errors counting as `false`.
+ *
+ * @since 0.1.0
+ * @category evaluation
+ */
+export const test = (
+  expression: Algebra.Expression,
+  solution: Bindings,
+  context: Context,
+): boolean =>
+  Result.getOrElse(
+    V.catchEvalFailure(() => V.ebv(evaluateUnsafe(expression, solution, context))),
+    () => false,
+  );
+
+/**
+ * The effective boolean value of a term (SPARQL 1.1 §17.2.2).
+ *
+ * @since 0.1.0
+ * @category evaluation
+ */
+export const effectiveBooleanValue = (
+  term: Term.GroundTerm,
+): Result.Result<boolean, Functions.ExpressionError> =>
+  Result.mapError(
+    V.catchEvalFailure(() => V.ebv(term)),
+    toError,
+  );
+
+/**
+ * Value equality (the `=` operator). Fails for incomparable literals.
+ *
+ * @since 0.1.0
+ * @category evaluation
+ */
+export const equals = (
+  a: Term.GroundTerm,
+  b: Term.GroundTerm,
+): Result.Result<boolean, Functions.ExpressionError> =>
+  Result.mapError(
+    V.catchEvalFailure(() => V.equals(a, b)),
+    toError,
+  );
+
+/**
+ * The total order on (possibly unbound) terms used by `ORDER BY`: unbound <
+ * blank nodes < IRIs < literals < triple terms.
+ *
+ * @since 0.1.0
+ * @category ordering
+ */
+export const compare = (a: Term.GroundTerm | undefined, b: Term.GroundTerm | undefined): number =>
+  V.orderCompare(Option.fromUndefinedOr(a), Option.fromUndefinedOr(b));

package/src/sparql/Federation.ts

@@ -0,0 +1,187 @@
+/**
+ * Federation for the in-memory SPARQL engine: an `Engine.ServiceHandler`
+ * that evaluates `SERVICE <endpoint> { … }` patterns remotely with the
+ * SPARQL client, and an `Engine.Loader` that fetches documents for `LOAD`.
+ *
+ * ```ts
+ * const EngineLive = Federation.layerEngine().pipe(
+ *   Layer.provide(Store.layerMemory(data)),
+ *   Layer.provide(FetchHttpClient.layer),
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as MutableHashMap from 'effect/MutableHashMap';
+import * as Option from 'effect/Option';
+import * as Predicate from 'effect/Predicate';
+import * as Record from 'effect/Record';
+import * as Stream from 'effect/Stream';
+import * as HttpClient from 'effect/http/HttpClient';
+import * as HttpClientRequest from 'effect/http/HttpClientRequest';
+import * as Serialization from '../Serialization.ts';
+import type * as Term from '../Term.ts';
+import * as Engine from './Engine.ts';
+import { EvaluationError, UpdateError } from './Errors.ts';
+import * as Generator from './Generator.ts';
+import * as Store from './Store.ts';
+import type * as ClientErrors from './ClientErrors.ts';
+import * as ClientFormats from './ClientFormats.ts';
+import * as SparqlClient from './SparqlClient.ts';
+
+/**
+ * Client settings used for remote endpoints (everything but the endpoint
+ * URLs).
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type RemoteConfig = Omit<
+  SparqlClient.Config,
+  'endpoint' | 'updateEndpoint' | 'graphStoreEndpoint'
+>;
+
+/**
+ * The query sent to a remote endpoint for a `SERVICE` pattern:
+ * `SELECT * WHERE { … }` with the prefixes of the original query.
+ *
+ * @since 0.1.0
+ * @category federation
+ */
+export const serviceQuery = (service: Parameters<Engine.ServiceHandler>[1]): string => {
+  const prologue = Record.toEntries(service.prefixes)
+    .map(([prefix, iri]) => `PREFIX ${prefix}: <${iri}>\n`)
+    .join('');
+  return `${prologue}SELECT * WHERE ${Generator.printPattern(service.pattern, service.prefixes)}`;
+};
+
+const describeError = (e: ClientErrors.SparqlClientError): string =>
+  Predicate.isTagged(e, 'HttpStatusError') ? e.message : `${e._tag}: ${e.message}`;
+
+/**
+ * Builds a `SERVICE` handler that sends each remote pattern to its endpoint
+ * with the `HttpClient` from the context. Clients are cached per endpoint.
+ *
+ * @since 0.1.0
+ * @category federation
+ */
+export const serviceHandler = (
+  config: RemoteConfig = {},
+): Effect.Effect<Engine.ServiceHandler, never, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const context = yield* Effect.context<HttpClient.HttpClient>();
+    const clients = MutableHashMap.empty<string, SparqlClient.SparqlClientShape>();
+    const clientFor = (endpoint: Term.NamedNode) =>
+      Effect.suspend(() => {
+        const cached = MutableHashMap.get(clients, endpoint.value);
+        if (Option.isSome(cached)) return Effect.succeed(cached.value);
+        return Effect.tap(
+          Effect.provideContext(
+            SparqlClient.make({ ...config, endpoint: endpoint.value }),
+            context,
+          ),
+          (client) => Effect.sync(() => MutableHashMap.set(clients, endpoint.value, client)),
+        );
+      });
+    return (endpoint, service) =>
+      Stream.unwrap(
+        Effect.map(clientFor(endpoint), (client) =>
+          client.selectBindings(serviceQuery(service)).pipe(
+            Stream.mapError(
+              (e) =>
+                new EvaluationError({
+                  message: `SERVICE <${endpoint.value}> failed: ${describeError(e)}`,
+                  cause: e,
+                }),
+            ),
+          ),
+        ),
+      ).pipe(Stream.withSpan('Federation.service', { attributes: { endpoint: endpoint.value } }));
+  });
+
+const loadFailed = (iri: Term.NamedNode, message: string, cause?: unknown) =>
+  new UpdateError({ message: `LOAD <${iri.value}> failed: ${message}`, cause });
+
+/**
+ * Builds a `LOAD` handler that fetches documents over HTTP and parses them
+ * with the `Serialization.Formats` service (or the default formats), by
+ * media type or, failing that, by file extension.
+ *
+ * @since 0.1.0
+ * @category federation
+ */
+export const loader = (
+  config: Pick<RemoteConfig, 'headers' | 'timeout'> = {},
+): Effect.Effect<Engine.Loader, never, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const http = yield* HttpClient.HttpClient;
+    const formats = Option.getOrElse(
+      yield* Effect.serviceOption(Serialization.Formats),
+      () => ClientFormats.defaults,
+    );
+    const accept = ClientFormats.acceptHeader(formats);
+    return (iri: Term.NamedNode) =>
+      Effect.gen(function* () {
+        const request = HttpClientRequest.get(iri.value, {
+          headers: { ...config.headers, accept },
+        });
+        const exchange = Effect.flatMap(http.execute(request), (response) =>
+          Effect.map(response.text, (text) => ({ response, text })),
+        );
+        const { response, text } = yield* (
+          config.timeout === undefined
+            ? exchange
+            : Effect.timeoutOrElse(exchange, {
+                duration: config.timeout,
+                orElse: () => Effect.fail(loadFailed(iri, 'timed out')),
+              })
+        ).pipe(
+          Effect.mapError((e) =>
+            Predicate.isTagged(e, 'UpdateError') ? e : loadFailed(iri, e.message, e),
+          ),
+        );
+        if (response.status < 200 || response.status >= 300) {
+          return yield* loadFailed(iri, `status ${response.status}`);
+        }
+        const mediaType = ((response.headers['content-type'] ?? '').split(';', 1)[0] ?? '').trim();
+        const byType = Serialization.parserFor(formats, mediaType);
+        const extension = new URL(iri.value).pathname.replace(/^.*\./, '');
+        const parser = Option.isSome(byType)
+          ? byType
+          : Serialization.parserForExtension(formats, extension);
+        if (Option.isNone(parser)) {
+          return yield* loadFailed(iri, `unsupported media type '${mediaType}'`);
+        }
+        const parsed = yield* parser.value
+          .parse(text, { baseIri: iri.value })
+          .pipe(Effect.mapError((e) => loadFailed(iri, Serialization.formatError(e), e)));
+        return parsed.dataset;
+      }).pipe(Effect.withSpan('Federation.load', { attributes: { iri: iri.value } }));
+  });
+
+/**
+ * A `SparqlEngine` layer whose `SERVICE` patterns are evaluated remotely and
+ * whose `LOAD` fetches documents over HTTP.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerEngine = (
+  options: Engine.EngineOptions = {},
+  config: RemoteConfig = {},
+): Layer.Layer<Engine.SparqlEngine, never, Store.QuadStore | HttpClient.HttpClient> =>
+  Layer.effect(
+    Engine.SparqlEngine,
+    Effect.gen(function* () {
+      const store = yield* Store.QuadStore;
+      const service = yield* serviceHandler(config);
+      const load = yield* loader(config);
+      return Engine.make(store, {
+        ...options,
+        service: options.service ?? service,
+        load: options.load ?? load,
+      });
+    }),
+  );