@thomasfosterau/effect-sparql-node 0.0.0-stage → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,6 @@
+import { t as NodeSparqlServer_d_exports } from "./NodeSparqlServer-1vSrPk3J.mjs";
+import { r as Cli_d_exports } from "./Cli-DE0eXMJr.mjs";
+import { g as SparqlApi_d_exports } from "./SparqlApi-BKE9nIf4.mjs";
+import { n as SparqlApiBuilder_d_exports } from "./SparqlApiBuilder-BAMpMy-Z.mjs";
+import { c as SparqlApiClient_d_exports } from "./SparqlApiClient-C82RGMEF.mjs";
+export { Cli_d_exports as Cli, NodeSparqlServer_d_exports as NodeSparqlServer, SparqlApi_d_exports as SparqlApi, SparqlApiBuilder_d_exports as SparqlApiBuilder, SparqlApiClient_d_exports as SparqlApiClient };

package/dist/index.mjs

@@ -0,0 +1,6 @@
+import { t as NodeSparqlServer_exports } from "./NodeSparqlServer-CYAd_6BG.mjs";
+import { n as Cli_exports } from "./Cli-DFvng1N8.mjs";
+import { m as SparqlApi_exports } from "./SparqlApi-BuycDkWu.mjs";
+import { t as SparqlApiBuilder_exports } from "./SparqlApiBuilder-GT7EopBq.mjs";
+import { n as SparqlApiClient_exports } from "./SparqlApiClient-CJcoFy5b.mjs";
+export { Cli_exports as Cli, NodeSparqlServer_exports as NodeSparqlServer, SparqlApi_exports as SparqlApi, SparqlApiBuilder_exports as SparqlApiBuilder, SparqlApiClient_exports as SparqlApiClient };

package/dist/rolldown-runtime-D8jQpDG7.mjs

@@ -0,0 +1,12 @@
+// \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+export { __exportAll as t };

package/package.json

@@ -1,6 +1,70 @@
 {
+  "$schema": "https://www.schemastore.org/package",
   "name": "@thomasfosterau/effect-sparql-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The Node side of @thomasfosterau/effect-rdf/sparql: a SPARQL 1.1 Protocol / Graph Store server on node:http, its command-line launcher, and the typed SparqlApi HttpApi definition, server and client",
+  "keywords": [
+    "effect",
+    "http-api",
+    "rdf",
+    "sparql",
+    "sparql-protocol",
+    "typescript"
+  ],
+  "homepage": "https://github.com/thomasfosterau/effect-rdf/tree/main/packages/sparql-node#readme",
+  "bugs": {
+    "url": "https://github.com/thomasfosterau/effect-rdf/issues"
+  },
+  "license": "MIT",
+  "author": "Thomas Foster <me@thomasfoster.au>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thomasfosterau/effect-rdf.git",
+    "directory": "packages/sparql-node"
+  },
+  "bin": {
+    "effect-sparql-server": "./bin/effect-sparql-server.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./*": {
+      "types": "./dist/*.d.mts",
+      "default": "./dist/*.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.1.2",
+    "@thomasfosterau/effect-rdf": "0.1.0"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.1.2",
+    "@thomasfosterau/effect-parse": "0.4.1",
+    "effect": "4.1.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "@thomasfosterau/effect-parse": "^0.4.0",
+    "effect": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "start": "node --experimental-transform-types --no-warnings bin/effect-sparql-server.mjs"
+  }
 }

package/src/Cli.ts

@@ -0,0 +1,373 @@
+/**
+ * The command line entry point: serves RDF files loaded into an in-memory
+ * store.
+ *
+ * ```sh
+ * effect-sparql-server --port 3030 data.ttl more.trig
+ * ```
+ *
+ * Files are parsed with the default formats, chosen by file extension.
+ * Triples go to the default graph, or with `--graph-per-file` to a named
+ * graph per file (named by the file URL); quads keep their graph.
+ *
+ * The command is built with `effect/cli` (generated `--help`, `--version`
+ * and shell completions), and every flag also reads an environment variable
+ * through `Config`: `SPARQL_SERVER_` followed by the flag name in upper
+ * snake case (`--max-results` is `SPARQL_SERVER_MAX_RESULTS`). A flag on the
+ * command line wins over the environment, which wins over the default.
+ *
+ * @since 0.1.0
+ */
+import * as NodeServices from '@effect/platform-node/NodeServices';
+import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem';
+import * as NodePath from '@effect/platform-node/NodePath';
+import * as Config from 'effect/Config';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import * as FileSystem from 'effect/FileSystem';
+import * as Layer from 'effect/Layer';
+import * as Match from 'effect/Match';
+import * as Option from 'effect/Option';
+import * as Path from 'effect/Path';
+import * as PlatformError from 'effect/PlatformError';
+import * as Ref from 'effect/Ref';
+import * as Schema from 'effect/Schema';
+import { Argument, Command, Flag } from 'effect/cli';
+import * as CliErrors from 'effect/cli/CliError';
+import type * as HttpServerError from 'effect/http/HttpServerError';
+import * as Iri from '@thomasfosterau/effect-rdf/Iri';
+import * as Dataset from '@thomasfosterau/effect-rdf/Dataset';
+import * as Serialization from '@thomasfosterau/effect-rdf/Serialization';
+import * as Term from '@thomasfosterau/effect-rdf/Term';
+import * as ServerFormats from '@thomasfosterau/effect-rdf/sparql/ServerFormats';
+import type * as Options from '@thomasfosterau/effect-rdf/sparql/Options';
+import * as NodeSparqlServer from './NodeSparqlServer.ts';
+
+/**
+ * A command line usage error.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export class CliError extends Schema.TaggedError<CliError>()('CliError', {
+  message: Schema.String,
+}) {}
+
+/**
+ * The prefix of the environment variables that back the flags:
+ * `SPARQL_SERVER_PORT`, `SPARQL_SERVER_READ_ONLY`, …
+ *
+ * @since 0.1.0
+ * @category cli
+ */
+export const envPrefix = 'SPARQL_SERVER_';
+
+const envName = (flag: string): string => `${envPrefix}${flag.toUpperCase().replaceAll('-', '_')}`;
+
+/**
+ * A summary of the flags and their environment variables; `--help` prints
+ * the full, generated help.
+ *
+ * @since 0.1.0
+ * @category cli
+ */
+export const usage = `Usage: effect-sparql-server [flags] [files...]
+
+Serves the given RDF files from an in-memory store over the SPARQL 1.1
+Protocol and the Graph Store HTTP Protocol.
+
+Flags (environment variable in brackets; a flag wins over the environment):
+  -p, --port <port>          port to listen on (default 3030) [SPARQL_SERVER_PORT]
+      --host <host>          host to bind (default all interfaces) [SPARQL_SERVER_HOST]
+      --path <path>          SPARQL endpoint path (default /sparql) [SPARQL_SERVER_PATH]
+      --update-path <path>   separate update endpoint path [SPARQL_SERVER_UPDATE_PATH]
+      --graph-store <path>   Graph Store Protocol path (default /rdf-graph-store) [SPARQL_SERVER_GRAPH_STORE]
+      --no-graph-store       disable the Graph Store Protocol [SPARQL_SERVER_NO_GRAPH_STORE]
+      --read-only            reject updates and graph store writes [SPARQL_SERVER_READ_ONLY]
+      --timeout <ms>         query timeout in milliseconds [SPARQL_SERVER_TIMEOUT]
+      --max-results <n>      maximum number of results per query [SPARQL_SERVER_MAX_RESULTS]
+      --cors                 enable permissive CORS [SPARQL_SERVER_CORS]
+      --union-default-graph  query the union of all graphs by default [SPARQL_SERVER_UNION_DEFAULT_GRAPH]
+      --graph-per-file       load each file into a named graph (its file URL) [SPARQL_SERVER_GRAPH_PER_FILE]
+      --base-url <url>       public origin of the server [SPARQL_SERVER_BASE_URL]
+  -h, --help                 show the full help
+`;
+
+/**
+ * Parsed command line arguments.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Arguments {
+  readonly help: boolean;
+  readonly files: ReadonlyArray<string>;
+  readonly graphPerFile: boolean;
+  readonly unionDefaultGraph: boolean;
+  readonly serve: NodeSparqlServer.ServeOptions;
+}
+
+// A string flag, falling back to its environment variable, absent when neither is set.
+const stringFlag = (name: string, description: string) =>
+  Flag.String(name).pipe(
+    Flag.withDescription(`${description} [${envName(name)}]`),
+    Flag.withFallbackConfig(Config.String(envName(name))),
+    Flag.optional,
+  );
+
+// An integer flag, falling back to its environment variable.
+const intFlag = (name: string, description: string) =>
+  Flag.Int(name).pipe(
+    Flag.withDescription(`${description} [${envName(name)}]`),
+    Flag.withFallbackConfig(Config.Int(envName(name))),
+    Flag.optional,
+  );
+
+// A boolean flag, falling back to its environment variable, then to false.
+const booleanFlag = (name: string, description: string) =>
+  Flag.Boolean(name).pipe(
+    Flag.withDescription(`${description} [${envName(name)}]`),
+    Flag.withFallbackConfig(Config.Boolean(envName(name))),
+    Flag.withDefault(false),
+  );
+
+/**
+ * The command's flags and arguments.
+ *
+ * @since 0.1.0
+ * @category cli
+ */
+export const config = {
+  port: intFlag('port', 'port to listen on (default 3030)').pipe(Flag.withAlias('p')),
+  host: stringFlag('host', 'host to bind (default all interfaces)'),
+  path: stringFlag('path', 'SPARQL endpoint path (default /sparql)'),
+  updatePath: stringFlag('update-path', 'separate update endpoint path'),
+  graphStore: stringFlag('graph-store', 'Graph Store Protocol path (default /rdf-graph-store)'),
+  noGraphStore: booleanFlag('no-graph-store', 'disable the Graph Store Protocol'),
+  readOnly: booleanFlag('read-only', 'reject updates and graph store writes'),
+  timeout: intFlag('timeout', 'query timeout in milliseconds'),
+  maxResults: intFlag('max-results', 'maximum number of results per query'),
+  cors: booleanFlag('cors', 'enable permissive CORS'),
+  unionDefaultGraph: booleanFlag('union-default-graph', 'query the union of all graphs by default'),
+  graphPerFile: booleanFlag('graph-per-file', 'load each file into a named graph (its file URL)'),
+  baseUrl: stringFlag('base-url', 'public origin of the server'),
+  files: Argument.String('files').pipe(
+    Argument.withDescription('RDF files to load, in any syntax the server reads'),
+    Argument.variadic(),
+  ),
+} as const;
+
+/**
+ * The values of the flags and arguments, as `effect/cli` parses them.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type Flags = Command.Command.Config.Infer<typeof config>;
+
+const nonNegative = (name: string, value: Option.Option<number>) =>
+  Option.match(value, {
+    onNone: () => Effect.succeed(undefined),
+    onSome: (n) =>
+      Number.isInteger(n) && n >= 0
+        ? Effect.succeed(n)
+        : Effect.fail(new CliError({ message: `--${name} expects a non-negative integer` })),
+  });
+
+const endpointPath = (name: string, value: Option.Option<string>) =>
+  Option.match(value, {
+    onNone: () => Effect.succeed(undefined),
+    onSome: (path) =>
+      Schema.is(EndpointPath)(path)
+        ? Effect.succeed(path)
+        : Effect.fail(new CliError({ message: `--${name} must start with '/'` })),
+  });
+
+const EndpointPath = Schema.TemplateLiteral(['/', Schema.String]);
+
+/**
+ * Validates parsed flags into `Arguments`: integers must be non-negative,
+ * paths must start with `/`, and `--base-url` must be an absolute IRI.
+ *
+ * @since 0.1.0
+ * @category cli
+ */
+export const toArguments = (flags: Flags): Effect.Effect<Arguments, CliError> =>
+  Effect.gen(function* () {
+    const baseUrl = Option.getOrUndefined(flags.baseUrl);
+    if (baseUrl !== undefined && !Iri.isValid(baseUrl)) {
+      return yield* new CliError({ message: `--base-url must be an absolute IRI: ${baseUrl}` });
+    }
+    const graphStore = yield* endpointPath('graph-store', flags.graphStore);
+    const options: Options.Options = {
+      path: yield* endpointPath('path', flags.path),
+      updatePath: yield* endpointPath('update-path', flags.updatePath),
+      graphStorePath: flags.noGraphStore ? false : graphStore,
+      readOnly: flags.readOnly,
+      queryTimeout: yield* nonNegative('timeout', flags.timeout),
+      maxResults: yield* nonNegative('max-results', flags.maxResults),
+      cors: flags.cors,
+      logging: true,
+      baseUrl,
+      unionDefaultGraph: flags.unionDefaultGraph,
+    };
+    return {
+      help: false,
+      files: flags.files,
+      graphPerFile: flags.graphPerFile,
+      unionDefaultGraph: flags.unionDefaultGraph,
+      serve: {
+        ...options,
+        port: (yield* nonNegative('port', flags.port)) ?? 3030,
+        host: Option.getOrUndefined(flags.host),
+      },
+    };
+  });
+
+// The `effect/cli` errors as this module's `CliError` (a help request has no message).
+const fromCliError = (error: CliErrors.CliError): CliError =>
+  new CliError({
+    message: Match.value(error).pipe(
+      Match.tag('ShowHelp', (help) => help.errors.map((e) => e.message).join('\n')),
+      Match.orElse((e) => e.message),
+    ),
+  });
+
+const quiet = (): void => undefined;
+const silentConsole: Console.Console = Object.assign(Object.create(globalThis.console), {
+  log: quiet,
+  error: quiet,
+  info: quiet,
+  warn: quiet,
+});
+
+const isHelp = (argv: ReadonlyArray<string>): boolean =>
+  argv.includes('--help') || argv.includes('-h');
+
+/**
+ * Parses command line arguments, reading unset flags from the environment
+ * (`SPARQL_SERVER_*`). `-h` / `--help` sets `help` instead.
+ *
+ * @since 0.1.0
+ * @category cli
+ */
+export const parse = (argv: ReadonlyArray<string>): Effect.Effect<Arguments, CliError> =>
+  isHelp(argv)
+    ? Effect.succeed({
+        help: true,
+        files: [],
+        graphPerFile: false,
+        unionDefaultGraph: false,
+        serve: { port: 3030 },
+      })
+    : Effect.gen(function* () {
+        const parsed = yield* Ref.make(Option.none<Arguments>());
+        const capture = Command.make('effect-sparql-server', config, (flags) =>
+          Effect.flatMap(toArguments(flags), (args) => Ref.set(parsed, Option.some(args))),
+        );
+        yield* Command.runWith(capture, { version: '', renderErrors: false })(argv).pipe(
+          Effect.catchIf(CliErrors.isCliError, (e) => Effect.fail(fromCliError(e))),
+          // Parsing is programmatic: the help `effect/cli` prints for a usage error stays quiet.
+          Effect.provideService(Console.Console, silentConsole),
+          Effect.provide(NodeServices.layer),
+        );
+        return yield* Effect.flatMap(Ref.get(parsed), Effect.fromOption).pipe(
+          Effect.mapError(() => new CliError({ message: 'no arguments were parsed' })),
+        );
+      });
+
+/**
+ * Loads RDF files into a dataset through Effect's `FileSystem`, choosing
+ * parsers by file extension from the `Formats` service. Relative IRIs
+ * resolve against each file's `file:` URL; with `graphPerFile`, a file's
+ * default-graph triples go into a graph named by that URL.
+ *
+ * @since 0.1.0
+ * @category cli
+ */
+export const load = (
+  files: ReadonlyArray<string>,
+  graphPerFile: boolean,
+): Effect.Effect<
+  Dataset.Dataset,
+  CliError | Serialization.RdfParseError,
+  Serialization.Formats | FileSystem.FileSystem | Path.Path
+> =>
+  Effect.gen(function* () {
+    const formats = yield* Serialization.Formats;
+    const paths = yield* Path.Path;
+    const perFile = yield* Effect.forEach(
+      files,
+      Effect.fnUntraced(function* (file) {
+        const parser = Serialization.parserForExtension(formats, paths.extname(file));
+        if (Option.isNone(parser)) {
+          return yield* new CliError({ message: `Unknown RDF file extension: ${file}` });
+        }
+        const cannotRead = (e: PlatformError.PlatformError) =>
+          new CliError({ message: `Cannot read ${file}: ${e.message}` });
+        const url = (yield* paths
+          .toFileUrl(paths.resolve(file))
+          .pipe(Effect.mapError((e) => cannotRead(new PlatformError.PlatformError(e))))).href;
+        const result = yield* Serialization.readFile(file, {
+          parser: parser.value,
+          baseIri: url,
+        }).pipe(Effect.catchTag('PlatformError', (e) => Effect.fail(cannotRead(e))));
+        const graph = graphPerFile ? Term.namedNode(url) : undefined;
+        const quads = Array.from(result.dataset, (q) =>
+          graph !== undefined && q.graph._tag === 'DefaultGraph'
+            ? new Term.Quad(q.subject, q.predicate, q.object, graph)
+            : q,
+        );
+        yield* Effect.logInfo(`Loaded ${result.dataset.size} quads from ${file}`);
+        return quads;
+      }),
+      { concurrency: 1 },
+    );
+    return Dataset.fromIterable(perFile.flat());
+  });
+
+/**
+ * The `effect/cli` command: parses the flags (and their environment
+ * variables), loads the files and serves them until interrupted.
+ *
+ * @since 0.1.0
+ * @category cli
+ */
+export const command = Command.make('effect-sparql-server', config, (flags) =>
+  Effect.gen(function* () {
+    const args = yield* toArguments(flags);
+    const data = yield* Effect.provide(
+      load(args.files, args.graphPerFile),
+      Layer.mergeAll(ServerFormats.layer, NodeFileSystem.layer, NodePath.layer),
+    );
+    const server = NodeSparqlServer.layerMemory({
+      ...args.serve,
+      data,
+      engine: { unionDefaultGraph: args.unionDefaultGraph },
+    });
+    return yield* Layer.launch(server);
+  }),
+).pipe(
+  Command.withDescription(
+    'Serves the given RDF files from an in-memory store over the SPARQL 1.1 Protocol and the Graph Store HTTP Protocol.',
+  ),
+);
+
+/**
+ * Runs the command line program: parses arguments (printing the generated
+ * help for `--help` or a usage error), loads the files and serves them
+ * until interrupted. `version` is what `--version` prints.
+ *
+ * @since 0.1.0
+ * @category cli
+ */
+export const run = (
+  argv: ReadonlyArray<string>,
+  options?: { readonly version?: string | undefined },
+): Effect.Effect<void, CliError | Serialization.RdfParseError | HttpServerError.ServeError> =>
+  Command.runWith(command, { version: options?.version ?? 'unknown', renderErrors: false })(
+    argv,
+  ).pipe(
+    Effect.catchIf(CliErrors.isCliError, (e) => Effect.fail(fromCliError(e))),
+    Effect.provide(NodeServices.layer),
+  );

package/src/NodeSparqlServer.ts

@@ -0,0 +1,71 @@
+/**
+ * The SPARQL 1.1 Protocol and Graph Store HTTP Protocol server of
+ * `@thomasfosterau/effect-rdf/sparql` (`SparqlServer`) on a Node
+ * `node:http` server, through `@effect/platform-node`'s `NodeHttpServer`.
+ *
+ * `SparqlServer` itself is platform-neutral (`handler`, `layerRoutes`,
+ * `layerServe`); this module adds the listening socket.
+ *
+ * @since 0.1.0
+ */
+import { createServer } from 'node:http';
+import * as Layer from 'effect/Layer';
+import type * as HttpServer from 'effect/http/HttpServer';
+import type * as HttpServerError from 'effect/http/HttpServerError';
+import * as NodeHttpServer from '@effect/platform-node/NodeHttpServer';
+import type * as Dataset from '@thomasfosterau/effect-rdf/Dataset';
+import type * as Engine from '@thomasfosterau/effect-rdf/sparql/Engine';
+import type * as Options from '@thomasfosterau/effect-rdf/sparql/Options';
+import * as SparqlServer from '@thomasfosterau/effect-rdf/sparql/SparqlServer';
+
+/**
+ * Options of the Node server.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface ServeOptions extends Options.Options {
+  /** The port to listen on (`0` for an ephemeral port). */
+  readonly port: number;
+  /** The host to bind (default: all interfaces). */
+  readonly host?: string | undefined;
+}
+
+/**
+ * A Node HTTP server serving the SPARQL endpoint and graph store.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layer = (
+  options: ServeOptions,
+): Layer.Layer<HttpServer.HttpServer, HttpServerError.ServeError, SparqlServer.Requirements> => {
+  const { port, host, ...rest } = options;
+  // SAFETY: providing the Node HTTP server leaves `HttpServer` and `SparqlServer.Requirements`; the cast
+  // restates the layer type.
+  return SparqlServer.layerServe(rest).pipe(
+    Layer.provideMerge(
+      NodeHttpServer.layer(createServer, host === undefined ? { port } : { port, host }),
+    ),
+  );
+};
+
+/**
+ * A Node server over an in-memory store.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerMemory = (
+  options: ServeOptions & {
+    readonly data?: Dataset.Dataset | undefined;
+    readonly engine?: Engine.EngineOptions | undefined;
+  },
+): Layer.Layer<HttpServer.HttpServer, HttpServerError.ServeError> => {
+  const { data, engine, ...rest } = options;
+  return layer({
+    ...rest,
+    unionDefaultGraph: rest.unionDefaultGraph ?? engine?.unionDefaultGraph,
+    federation: rest.federation ?? engine?.service !== undefined,
+  }).pipe(Layer.provide(SparqlServer.layerMemoryServices(data, engine)));
+};