@lde/pipeline 0.5.0 → 0.6.0

package/dist/distribution/analyzer.js

@@ -0,0 +1,120 @@
+import { Distribution } from '@lde/dataset';
+import { ImportFailed, ImportSuccessful, NotSupported, } from '@lde/sparql-importer';
+import { DataFactory, Store } from 'n3';
+import { probe, NetworkError, SparqlProbeResult, } from './probe.js';
+export { ImportFailed, ImportSuccessful, NotSupported };
+const { quad, namedNode, blankNode, literal } = DataFactory;
+// Namespace prefixes
+const RDF = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#';
+const SCHEMA = 'https://schema.org/';
+const VOID = 'http://rdfs.org/ns/void#';
+const XSD = 'http://www.w3.org/2001/XMLSchema#';
+const HTTP_STATUS = 'https://www.w3.org/2011/http-statusCodes#';
+/**
+ * Result indicating the analyzer could not find a usable distribution.
+ */
+export class NoDistributionAvailable {
+    message;
+    constructor(message) {
+        this.message = message;
+    }
+}
+/**
+ * Analyzes dataset distributions by probing their availability.
+ *
+ * - Probes SPARQL endpoints with a simple SELECT query
+ * - Probes data dumps with HEAD/GET requests
+ * - Records probe results as RDF (schema:Action)
+ * - Updates distribution metadata (isValid, lastModified, byteSize)
+ * - Optionally imports data dumps if no SPARQL endpoint is available
+ */
+export class DistributionAnalyzer {
+    name = 'distribution';
+    importer;
+    timeout;
+    constructor(options) {
+        this.importer = options?.importer;
+        this.timeout = options?.timeout ?? 5000;
+    }
+    /**
+     * Analyze all distributions of a dataset.
+     *
+     * @returns Store with probe results as RDF, or NoDistributionAvailable if no usable distribution found
+     */
+    async execute(dataset) {
+        const results = await Promise.all(dataset.distributions.map((distribution) => probe(distribution, this.timeout)));
+        const store = this.buildProbeResultsRdf(results, dataset);
+        // If no SPARQL endpoint available, try to import a data dump
+        if (dataset.getSparqlDistribution() === null && this.importer) {
+            const importResult = await this.importer.import(dataset);
+            if (importResult instanceof ImportSuccessful) {
+                // Add imported SPARQL distribution to dataset so subsequent steps can use it
+                const distribution = Distribution.sparql(importResult.distribution.accessUrl, importResult.identifier);
+                dataset.distributions.push(distribution);
+            }
+            else if (importResult instanceof ImportFailed) {
+                // Record import error in the store
+                this.addImportError(store, importResult);
+            }
+        }
+        if (dataset.getSparqlDistribution() === null) {
+            return new NoDistributionAvailable('No SPARQL endpoint or importable data dump available');
+        }
+        return store;
+    }
+    /**
+     * Cleanup resources (e.g., importer connections).
+     */
+    async finish() {
+        await this.importer?.finish?.();
+    }
+    buildProbeResultsRdf(results, dataset) {
+        const store = new Store();
+        for (const result of results) {
+            const action = blankNode();
+            // Base action triples
+            store.addQuads([
+                quad(action, namedNode(`${RDF}type`), namedNode(`${SCHEMA}Action`)),
+                quad(action, namedNode(`${SCHEMA}target`), namedNode(result.url)),
+            ]);
+            if (result instanceof NetworkError) {
+                store.addQuad(action, namedNode(`${SCHEMA}error`), literal(result.message));
+            }
+            else if (result.isSuccess()) {
+                this.addSuccessTriples(store, action, result, dataset);
+            }
+            else {
+                // HTTP error
+                const statusUri = `${HTTP_STATUS}${result.statusText.replace(/ /g, '')}`;
+                store.addQuad(action, namedNode(`${SCHEMA}error`), namedNode(statusUri));
+            }
+        }
+        return store;
+    }
+    addSuccessTriples(store, action, result, dataset) {
+        const distributionUrl = namedNode(result.url);
+        store.addQuad(action, namedNode(`${SCHEMA}result`), distributionUrl);
+        if (result.lastModified) {
+            store.addQuad(distributionUrl, namedNode(`${SCHEMA}dateModified`), literal(result.lastModified.toISOString(), namedNode(`${XSD}dateTime`)));
+        }
+        if (result instanceof SparqlProbeResult) {
+            store.addQuad(namedNode(dataset.iri.toString()), namedNode(`${VOID}sparqlEndpoint`), distributionUrl);
+        }
+        else {
+            store.addQuad(namedNode(dataset.iri.toString()), namedNode(`${VOID}dataDump`), distributionUrl);
+            if (result.contentSize) {
+                store.addQuad(distributionUrl, namedNode(`${SCHEMA}contentSize`), literal(result.contentSize));
+            }
+            if (result.contentType) {
+                store.addQuad(distributionUrl, namedNode(`${SCHEMA}encodingFormat`), literal(result.contentType));
+            }
+        }
+    }
+    addImportError(store, importResult) {
+        // Find the action for this download URL and add the error
+        const matches = store.match(null, namedNode(`${SCHEMA}target`), namedNode(importResult.distribution.accessUrl.toString()));
+        for (const match of matches) {
+            store.addQuad(match.subject, namedNode(`${SCHEMA}error`), literal(importResult.error));
+        }
+    }
+}

package/dist/distribution/index.d.ts

@@ -0,0 +1,3 @@
+export { probe, NetworkError, SparqlProbeResult, DataDumpProbeResult, type ProbeResultType, } from './probe.js';
+export { DistributionAnalyzer, ImportSuccessful, ImportFailed, NoDistributionAvailable, type Importer, type DistributionAnalyzerOptions, } from './analyzer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/distribution/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/distribution/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,KAAK,QAAQ,EACb,KAAK,2BAA2B,GACjC,MAAM,eAAe,CAAC"}

package/dist/distribution/index.js

@@ -0,0 +1,2 @@
+export { probe, NetworkError, SparqlProbeResult, DataDumpProbeResult, } from './probe.js';
+export { DistributionAnalyzer, ImportSuccessful, ImportFailed, NoDistributionAvailable, } from './analyzer.js';

package/dist/distribution/probe.d.ts

@@ -0,0 +1,47 @@
+import { Distribution } from '@lde/dataset';
+/**
+ * Result of a network error during probing.
+ */
+export declare class NetworkError {
+    readonly url: string;
+    readonly message: string;
+    constructor(url: string, message: string);
+}
+/**
+ * Base class for successful probe results.
+ */
+declare abstract class ProbeResult {
+    readonly url: string;
+    readonly statusCode: number;
+    readonly statusText: string;
+    readonly lastModified: Date | null;
+    readonly contentType: string | null;
+    constructor(url: string, response: Response);
+    isSuccess(): boolean;
+}
+/**
+ * Result of probing a SPARQL endpoint.
+ */
+export declare class SparqlProbeResult extends ProbeResult {
+    readonly acceptedContentType = "application/sparql-results+json";
+    isSuccess(): boolean;
+}
+/**
+ * Result of probing a data dump distribution.
+ */
+export declare class DataDumpProbeResult extends ProbeResult {
+    readonly contentSize: number | null;
+    constructor(url: string, response: Response);
+}
+export type ProbeResultType = SparqlProbeResult | DataDumpProbeResult | NetworkError;
+/**
+ * Probe a distribution to check availability and gather metadata.
+ *
+ * For SPARQL endpoints, sends a simple SELECT query.
+ * For data dumps, sends HEAD (or GET if HEAD returns no Content-Length).
+ *
+ * Updates the distribution's isValid, lastModified, and byteSize properties.
+ */
+export declare function probe(distribution: Distribution, timeout?: number): Promise<ProbeResultType>;
+export {};
+//# sourceMappingURL=probe.d.ts.map

package/dist/distribution/probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../../src/distribution/probe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C;;GAEG;AACH,qBAAa,YAAY;aACK,GAAG,EAAE,MAAM;aAAkB,OAAO,EAAE,MAAM;gBAA5C,GAAG,EAAE,MAAM,EAAkB,OAAO,EAAE,MAAM;CACzE;AAED;;GAEG;AACH,uBAAe,WAAW;aAMI,GAAG,EAAE,MAAM;IALvC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAQ;IACjD,SAAgB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEf,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ;IAUpD,SAAS,IAAI,OAAO;CAG5B;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;IAChD,SAAgB,mBAAmB,qCAAqC;IAE/D,SAAS,IAAI,OAAO;CAM9B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IAClD,SAAgB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAEtC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ;CAO5C;AAED,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,mBAAmB,GACnB,YAAY,CAAC;AAEjB;;;;;;;GAOG;AACH,wBAAsB,KAAK,CACzB,YAAY,EAAE,YAAY,EAC1B,OAAO,SAAO,GACb,OAAO,CAAC,eAAe,CAAC,CAY1B"}

package/dist/distribution/probe.js

@@ -0,0 +1,120 @@
+/**
+ * Result of a network error during probing.
+ */
+export class NetworkError {
+    url;
+    message;
+    constructor(url, message) {
+        this.url = url;
+        this.message = message;
+    }
+}
+/**
+ * Base class for successful probe results.
+ */
+class ProbeResult {
+    url;
+    statusCode;
+    statusText;
+    lastModified = null;
+    contentType;
+    constructor(url, response) {
+        this.url = url;
+        this.statusCode = response.status;
+        this.statusText = response.statusText;
+        this.contentType = response.headers.get('Content-Type');
+        const lastModifiedHeader = response.headers.get('Last-Modified');
+        if (lastModifiedHeader) {
+            this.lastModified = new Date(lastModifiedHeader);
+        }
+    }
+    isSuccess() {
+        return this.statusCode >= 200 && this.statusCode < 400;
+    }
+}
+/**
+ * Result of probing a SPARQL endpoint.
+ */
+export class SparqlProbeResult extends ProbeResult {
+    acceptedContentType = 'application/sparql-results+json';
+    isSuccess() {
+        return (super.isSuccess() &&
+            (this.contentType?.startsWith(this.acceptedContentType) ?? false));
+    }
+}
+/**
+ * Result of probing a data dump distribution.
+ */
+export class DataDumpProbeResult extends ProbeResult {
+    contentSize = null;
+    constructor(url, response) {
+        super(url, response);
+        const contentLengthHeader = response.headers.get('Content-Length');
+        if (contentLengthHeader) {
+            this.contentSize = parseInt(contentLengthHeader);
+        }
+    }
+}
+/**
+ * Probe a distribution to check availability and gather metadata.
+ *
+ * For SPARQL endpoints, sends a simple SELECT query.
+ * For data dumps, sends HEAD (or GET if HEAD returns no Content-Length).
+ *
+ * Updates the distribution's isValid, lastModified, and byteSize properties.
+ */
+export async function probe(distribution, timeout = 5000) {
+    try {
+        if (distribution.isSparql()) {
+            return await probeSparqlEndpoint(distribution, timeout);
+        }
+        return await probeDataDump(distribution, timeout);
+    }
+    catch (e) {
+        return new NetworkError(distribution.accessUrl?.toString() ?? 'unknown', e instanceof Error ? e.message : String(e));
+    }
+}
+async function probeSparqlEndpoint(distribution, timeout) {
+    const url = distribution.accessUrl.toString();
+    const response = await fetch(url, {
+        signal: AbortSignal.timeout(timeout),
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8',
+            Accept: 'application/sparql-results+json',
+        },
+        body: `query=${encodeURIComponent('SELECT * { ?s ?p ?o } LIMIT 1')}`,
+    });
+    const result = new SparqlProbeResult(url, response);
+    distribution.isValid = result.isSuccess();
+    return result;
+}
+async function probeDataDump(distribution, timeout) {
+    const url = distribution.accessUrl.toString();
+    const requestOptions = {
+        signal: AbortSignal.timeout(timeout),
+        headers: {
+            Accept: distribution.mimeType ?? '*/*',
+            'Accept-Encoding': 'identity', // Return uncompressed responses.
+        },
+    };
+    let response = await fetch(url, {
+        method: 'HEAD',
+        ...requestOptions,
+    });
+    const contentLength = response.headers.get('Content-Length');
+    if (contentLength === null || contentLength === '0') {
+        // Retry as GET request for servers incorrectly returning HEAD request Content-Length,
+        // which *should* be the size of the response body when issuing a GET, not that of
+        // the response to a HEAD request, which is intentionally 0.
+        response = await fetch(url, {
+            method: 'GET',
+            ...requestOptions,
+        });
+    }
+    const result = new DataDumpProbeResult(url, response);
+    distribution.isValid = result.isSuccess();
+    distribution.lastModified ??= result.lastModified ?? undefined;
+    distribution.byteSize ??= result.contentSize ?? undefined;
+    return result;
+}

package/dist/index.d.ts

@@ -2,4 +2,8 @@ export * from './pipeline.js';
 export * from './selector.js';
 export * from './step.js';
 export * from './step/sparqlQuery.js';
+export * from './builder.js';
+export * from './config.js';
+export * from './sparql/index.js';
+export * from './distribution/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC"}

package/dist/index.js

@@ -2,3 +2,7 @@ export * from './pipeline.js';
 export * from './selector.js';
 export * from './step.js';
 export * from './step/sparqlQuery.js';
+export * from './builder.js';
+export * from './config.js';
+export * from './sparql/index.js';
+export * from './distribution/index.js';

package/dist/sparql/collect.d.ts

@@ -0,0 +1,19 @@
+import { Store } from 'n3';
+import type { QuadStream } from './executor.js';
+/**
+ * Collect all quads from a stream into an N3 Store.
+ *
+ * @param stream The quad stream to collect from.
+ * @returns Promise that resolves to a Store containing all quads.
+ *
+ * @example
+ * ```typescript
+ * const result = await executor.execute(dataset);
+ * if (!(result instanceof NotSupported)) {
+ *   const store = await collect(result);
+ *   console.log(`Collected ${store.size} quads`);
+ * }
+ * ```
+ */
+export declare function collect(stream: QuadStream): Promise<Store>;
+//# sourceMappingURL=collect.d.ts.map

package/dist/sparql/collect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../src/sparql/collect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAMhE"}

package/dist/sparql/collect.js

@@ -0,0 +1,23 @@
+import { Store } from 'n3';
+/**
+ * Collect all quads from a stream into an N3 Store.
+ *
+ * @param stream The quad stream to collect from.
+ * @returns Promise that resolves to a Store containing all quads.
+ *
+ * @example
+ * ```typescript
+ * const result = await executor.execute(dataset);
+ * if (!(result instanceof NotSupported)) {
+ *   const store = await collect(result);
+ *   console.log(`Collected ${store.size} quads`);
+ * }
+ * ```
+ */
+export async function collect(stream) {
+    const store = new Store();
+    for await (const quad of stream) {
+        store.addQuad(quad);
+    }
+    return store;
+}

package/dist/sparql/executor.d.ts

@@ -0,0 +1,121 @@
+import { Dataset, Distribution } from '@lde/dataset';
+import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
+import type { Quad, Stream } from '@rdfjs/types';
+import type { Readable } from 'node:stream';
+import { NotSupported } from '../step.js';
+export { NotSupported } from '../step.js';
+/**
+ * A quad stream that is both an RDFJS Stream and Node.js Readable (async iterable).
+ * This is the actual return type from SparqlEndpointFetcher.fetchTriples().
+ */
+export type QuadStream = Readable & Stream<Quad>;
+/**
+ * Extended dataset with optional SPARQL filtering options.
+ */
+export interface ExecutableDataset extends Dataset {
+    /**
+     * Optional SPARQL filter clause to restrict analysis to a subset of the data.
+     * This is substituted for `#subjectFilter#` in queries.
+     */
+    subjectFilter?: string;
+}
+/**
+ * Options for SparqlConstructExecutor.
+ */
+export interface SparqlConstructExecutorOptions {
+    /**
+     * SPARQL CONSTRUCT query to execute.
+     */
+    query: string;
+    /**
+     * Optional timeout for SPARQL queries in milliseconds.
+     * @default 300000 (5 minutes)
+     */
+    timeout?: number;
+    /**
+     * Optional custom SparqlEndpointFetcher instance.
+     */
+    fetcher?: SparqlEndpointFetcher;
+}
+/**
+ * Options for `execute()`.
+ */
+export interface ExecuteOptions {
+    /**
+     * Explicit SPARQL endpoint URL. If not provided, uses the dataset's SPARQL distribution.
+     */
+    endpoint?: URL;
+    /**
+     * Variable bindings to substitute in the query before standard template substitution.
+     * Each key is a literal string to replace, each value is its replacement.
+     *
+     * @example
+     * ```typescript
+     * await executor.execute(dataset, {
+     *   bindings: { '<#class#>': '<http://schema.org/Person>' },
+     * });
+     * ```
+     */
+    bindings?: Record<string, string>;
+}
+/**
+ * A streaming SPARQL CONSTRUCT executor with template substitution.
+ *
+ * Supports template substitution (applied in order):
+ * 1. `bindings` — any provided variable bindings
+ * 2. `#subjectFilter#` — replaced with the distribution's subject filter or dataset's subjectFilter
+ * 3. `#namedGraph#` — replaced with `FROM <graph>` clause if the distribution has a named graph
+ * 4. `?dataset` — replaced with the dataset IRI
+ *
+ * @example
+ * ```typescript
+ * const executor = new SparqlConstructExecutor({
+ *   query: 'CONSTRUCT { ?dataset ?p ?o } WHERE { ?s ?p ?o }',
+ * });
+ * const result = await executor.execute(dataset);
+ * if (result instanceof NotSupported) {
+ *   console.log(result.message);
+ * } else {
+ *   for await (const quad of result) {
+ *     console.log(quad);
+ *   }
+ * }
+ * ```
+ */
+export declare class SparqlConstructExecutor {
+    private readonly query;
+    private readonly fetcher;
+    constructor(options: SparqlConstructExecutorOptions);
+    /**
+     * Execute the SPARQL CONSTRUCT query against the dataset's SPARQL endpoint.
+     *
+     * @param dataset The dataset to execute against.
+     * @param options Optional endpoint override and variable bindings.
+     * @returns AsyncIterable<Quad> stream of results, or NotSupported if no SPARQL endpoint available.
+     */
+    execute(dataset: ExecutableDataset, options?: ExecuteOptions): Promise<QuadStream | NotSupported>;
+    /**
+     * Substitute template variables in the query.
+     */
+    private substituteTemplates;
+    /**
+     * Create an executor from a query file.
+     *
+     * @param filename Path to the query file.
+     * @param options Optional executor options (timeout, fetcher).
+     */
+    static fromFile(filename: string, options?: Omit<SparqlConstructExecutorOptions, 'query'>): Promise<SparqlConstructExecutor>;
+}
+/**
+ * Substitute template variables in a SPARQL query.
+ *
+ * - `#subjectFilter#` — replaced with the distribution's or dataset's subject filter
+ * - `#namedGraph#` — replaced with `FROM <graph>` clause if the distribution has a named graph
+ * - `?dataset` — replaced with the dataset IRI
+ */
+export declare function substituteQueryTemplates(query: string, distribution: Distribution | null, dataset: ExecutableDataset): string;
+/**
+ * Read a SPARQL query from a file.
+ */
+export declare function readQueryFile(filename: string): Promise<string>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/sparql/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/sparql/executor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,OAAO;IAChD;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAC;IAEf;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;gBAEpC,OAAO,EAAE,8BAA8B;IASnD;;;;;;OAMG;IACG,OAAO,CACX,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,UAAU,GAAG,YAAY,CAAC;IAyBrC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;;;;OAKG;WACiB,QAAQ,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,IAAI,CAAC,8BAA8B,EAAE,OAAO,CAAC,GACtD,OAAO,CAAC,uBAAuB,CAAC;CAIpC;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,OAAO,EAAE,iBAAiB,GACzB,MAAM,CAYR;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAErE"}

package/dist/sparql/executor.js

@@ -0,0 +1,107 @@
+import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { NotSupported } from '../step.js';
+// Re-export for convenience
+export { NotSupported } from '../step.js';
+/**
+ * A streaming SPARQL CONSTRUCT executor with template substitution.
+ *
+ * Supports template substitution (applied in order):
+ * 1. `bindings` — any provided variable bindings
+ * 2. `#subjectFilter#` — replaced with the distribution's subject filter or dataset's subjectFilter
+ * 3. `#namedGraph#` — replaced with `FROM <graph>` clause if the distribution has a named graph
+ * 4. `?dataset` — replaced with the dataset IRI
+ *
+ * @example
+ * ```typescript
+ * const executor = new SparqlConstructExecutor({
+ *   query: 'CONSTRUCT { ?dataset ?p ?o } WHERE { ?s ?p ?o }',
+ * });
+ * const result = await executor.execute(dataset);
+ * if (result instanceof NotSupported) {
+ *   console.log(result.message);
+ * } else {
+ *   for await (const quad of result) {
+ *     console.log(quad);
+ *   }
+ * }
+ * ```
+ */
+export class SparqlConstructExecutor {
+    query;
+    fetcher;
+    constructor(options) {
+        this.query = options.query;
+        this.fetcher =
+            options.fetcher ??
+                new SparqlEndpointFetcher({
+                    timeout: options.timeout ?? 300_000,
+                });
+    }
+    /**
+     * Execute the SPARQL CONSTRUCT query against the dataset's SPARQL endpoint.
+     *
+     * @param dataset The dataset to execute against.
+     * @param options Optional endpoint override and variable bindings.
+     * @returns AsyncIterable<Quad> stream of results, or NotSupported if no SPARQL endpoint available.
+     */
+    async execute(dataset, options) {
+        const distribution = dataset.getSparqlDistribution();
+        let endpoint = options?.endpoint;
+        if (endpoint === undefined) {
+            if (distribution === null || !distribution.isValid) {
+                return new NotSupported('No SPARQL distribution available');
+            }
+            endpoint = distribution.accessUrl;
+        }
+        let query = this.query;
+        // Apply bindings first.
+        if (options?.bindings) {
+            for (const [variable, value] of Object.entries(options.bindings)) {
+                query = query.replaceAll(variable, value);
+            }
+        }
+        query = this.substituteTemplates(query, distribution, dataset);
+        return await this.fetcher.fetchTriples(endpoint.toString(), query);
+    }
+    /**
+     * Substitute template variables in the query.
+     */
+    substituteTemplates(query, distribution, dataset) {
+        return substituteQueryTemplates(query, distribution, dataset);
+    }
+    /**
+     * Create an executor from a query file.
+     *
+     * @param filename Path to the query file.
+     * @param options Optional executor options (timeout, fetcher).
+     */
+    static async fromFile(filename, options) {
+        const query = await readQueryFile(filename);
+        return new SparqlConstructExecutor({ ...options, query });
+    }
+}
+/**
+ * Substitute template variables in a SPARQL query.
+ *
+ * - `#subjectFilter#` — replaced with the distribution's or dataset's subject filter
+ * - `#namedGraph#` — replaced with `FROM <graph>` clause if the distribution has a named graph
+ * - `?dataset` — replaced with the dataset IRI
+ */
+export function substituteQueryTemplates(query, distribution, dataset) {
+    const subjectFilter = distribution?.subjectFilter ?? dataset.subjectFilter ?? '';
+    const namedGraph = distribution?.namedGraph
+        ? `FROM <${distribution.namedGraph}>`
+        : '';
+    return query
+        .replace('#subjectFilter#', subjectFilter)
+        .replaceAll('?dataset', `<${dataset.iri}>`)
+        .replace('#namedGraph#', namedGraph);
+}
+/**
+ * Read a SPARQL query from a file.
+ */
+export async function readQueryFile(filename) {
+    return (await readFile(resolve(filename))).toString();
+}

package/dist/sparql/index.d.ts

@@ -0,0 +1,3 @@
+export { SparqlConstructExecutor, substituteQueryTemplates, NotSupported, readQueryFile, type ExecutableDataset, type ExecuteOptions, type SparqlConstructExecutorOptions, type QuadStream, } from './executor.js';
+export { collect } from './collect.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/sparql/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sparql/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,8BAA8B,EACnC,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/sparql/index.js

@@ -0,0 +1,2 @@
+export { SparqlConstructExecutor, substituteQueryTemplates, NotSupported, readQueryFile, } from './executor.js';
+export { collect } from './collect.js';

package/dist/step/sparqlQuery.d.ts

@@ -1,4 +1,4 @@
-import { DataEmittingStep, NotSupported } from './../step.js';
+import { DataEmittingStep } from './../step.js';
 import { Dataset } from '@lde/dataset';
 import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
 /**
@@ -14,15 +14,20 @@ export interface Args {
     fetcher?: SparqlEndpointFetcher;
 }
 /**
- * Executes a SPARQL CONSTRUCT query and emits the resulting
+ * Executes a SPARQL CONSTRUCT query and emits the resulting quads.
+ *
+ * This step wraps the SparqlConstructExecutor to provide the DataEmittingStep interface
+ * for use in pipelines.
  */
 export declare class SparqlQuery implements DataEmittingStep {
     readonly identifier: string;
-    private readonly query;
-    private readonly fetcher;
+    private readonly executor;
     constructor({ identifier, query, fetcher }: Args);
-    execute(dataset: Dataset): Promise<NotSupported | (import("readable-stream").Readable & import("@rdfjs/types").Stream<import("@rdfjs/types").Quad>)>;
+    execute(dataset: Dataset): Promise<import("./../step.js").NotSupported | import("../sparql/executor.js").QuadStream>;
     static fromFile(filename: string): Promise<SparqlQuery>;
 }
+/**
+ * @deprecated Use readQueryFile from '@lde/pipeline/sparql' instead.
+ */
 export declare function fromFile(filename: string): Promise<string>;
 //# sourceMappingURL=sparqlQuery.d.ts.map

package/dist/step/sparqlQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sparqlQuery.d.ts","sourceRoot":"","sources":["../../src/step/sparqlQuery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAI9D;;;;;;GAMG;AACH,MAAM,WAAW,IAAI;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;GAEG;AACH,qBAAa,WAAY,YAAW,gBAAgB;IAClD,SAAgB,UAAU,SAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAEb,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI;IAM1C,OAAO,CAAC,OAAO,EAAE,OAAO;WAqBV,QAAQ,CAAC,QAAQ,EAAE,MAAM;CAM9C;AAED,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,mBAE9C"}
+{"version":3,"file":"sparqlQuery.d.ts","sourceRoot":"","sources":["../../src/step/sparqlQuery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAG9D;;;;;;GAMG;AACH,MAAM,WAAW,IAAI;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,gBAAgB;IAClD,SAAgB,UAAU,SAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;gBAEvC,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI;IAQ1C,OAAO,CAAC,OAAO,EAAE,OAAO;WAIV,QAAQ,CAAC,QAAQ,EAAE,MAAM;CAM9C;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,mBAE9C"}