@lde/pipeline 0.6.12 → 0.6.13

package/dist/sparql/executor.d.ts

@@ -1,11 +1,13 @@
 import { Dataset, Distribution } from '@lde/dataset';
 import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
-import type { Quad, Stream } from '@rdfjs/types';
+import type { NamedNode, Quad, Stream } from '@rdfjs/types';
 import type { Readable } from 'node:stream';
 import { NotSupported } from '../step.js';
 export { NotSupported } from '../step.js';
+/** A single row of variable bindings (variable name → NamedNode). */
+export type VariableBindings = Record<string, NamedNode>;
 export interface Executor {
-    execute(dataset: ExecutableDataset): Promise<AsyncIterable<Quad> | NotSupported>;
+    execute(dataset: ExecutableDataset, options?: SparqlConstructExecuteOptions): Promise<AsyncIterable<Quad> | NotSupported>;
 }
 /**
  * A quad stream that is both an RDFJS Stream and Node.js Readable (async iterable).
@@ -49,26 +51,18 @@ export interface SparqlConstructExecuteOptions {
      */
     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>' },
-     * });
-     * ```
+     * Variable bindings to inject as a VALUES clause into the query.
+     * When non-empty, a VALUES block is prepended to the WHERE clause.
      */
-    bindings?: Record<string, string>;
+    bindings?: VariableBindings[];
 }
 /**
- * A streaming SPARQL CONSTRUCT executor with template substitution.
+ * A streaming SPARQL CONSTRUCT executor that parses the query once (in the
+ * constructor) and operates on the AST for graph and VALUES injection.
  *
- * 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
+ * Template substitution (applied in order):
+ * 1. `FROM <graph>` — set via `withDefaultGraph` if the distribution has a named graph
+ * 2. `?dataset` — replaced with the dataset IRI (string substitution on the serialised query)
  *
  * @example
  * ```typescript
@@ -88,19 +82,16 @@ export interface SparqlConstructExecuteOptions {
 export declare class SparqlConstructExecutor implements Executor {
     private readonly query;
     private readonly fetcher;
+    private readonly generator;
     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.
+     * @param options Optional endpoint override.
      * @returns AsyncIterable<Quad> stream of results, or NotSupported if no SPARQL endpoint available.
      */
     execute(dataset: ExecutableDataset, options?: SparqlConstructExecuteOptions): Promise<QuadStream | NotSupported>;
-    /**
-     * Substitute template variables in the query.
-     */
-    private substituteTemplates;
     /**
      * Create an executor from a query file.
      *

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

@@ -1 +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,MAAM,WAAW,QAAQ;IACvB,OAAO,CACL,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,CAAC;CAChD;AAED;;;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,6BAA6B;IAC5C;;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,uBAAwB,YAAW,QAAQ;IACtD,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,6BAA6B,GACtC,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"}
+{"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,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAI5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK1C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAEzD,MAAM,WAAW,QAAQ;IACvB,OAAO,CACL,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,6BAA6B,GACtC,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,CAAC;CAChD;AAED;;;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,6BAA6B;IAC5C;;OAEG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAC;IAEf;;;OAGG;IACH,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,uBAAwB,YAAW,QAAQ;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;gBAEjC,OAAO,EAAE,8BAA8B;IAcnD;;;;;;OAMG;IACG,OAAO,CACX,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,6BAA6B,GACtC,OAAO,CAAC,UAAU,GAAG,YAAY,CAAC;IA4BrC;;;;;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

@@ -1,17 +1,19 @@
 import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { Generator, Parser } from 'sparqljs';
 import { NotSupported } from '../step.js';
+import { withDefaultGraph } from './graph.js';
+import { injectValues } from './values.js';
 // Re-export for convenience
 export { NotSupported } from '../step.js';
 /**
- * A streaming SPARQL CONSTRUCT executor with template substitution.
+ * A streaming SPARQL CONSTRUCT executor that parses the query once (in the
+ * constructor) and operates on the AST for graph and VALUES injection.
  *
- * 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
+ * Template substitution (applied in order):
+ * 1. `FROM <graph>` — set via `withDefaultGraph` if the distribution has a named graph
+ * 2. `?dataset` — replaced with the dataset IRI (string substitution on the serialised query)
  *
  * @example
  * ```typescript
@@ -31,8 +33,14 @@ export { NotSupported } from '../step.js';
 export class SparqlConstructExecutor {
     query;
     fetcher;
+    generator = new Generator();
     constructor(options) {
-        this.query = options.query;
+        const parser = new Parser();
+        const parsed = parser.parse(options.query);
+        if (parsed.type !== 'query' || parsed.queryType !== 'CONSTRUCT') {
+            throw new Error('Query must be a CONSTRUCT query');
+        }
+        this.query = parsed;
         this.fetcher =
             options.fetcher ??
                 new SparqlEndpointFetcher({
@@ -43,7 +51,7 @@ export class SparqlConstructExecutor {
      * 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.
+     * @param options Optional endpoint override.
      * @returns AsyncIterable<Quad> stream of results, or NotSupported if no SPARQL endpoint available.
      */
     async execute(dataset, options) {
@@ -55,22 +63,18 @@ export class SparqlConstructExecutor {
             }
             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);
-            }
+        let ast = structuredClone(this.query);
+        if (distribution?.namedGraph) {
+            withDefaultGraph(ast, distribution.namedGraph);
+        }
+        const bindings = options?.bindings;
+        if (bindings !== undefined && bindings.length > 0) {
+            ast = injectValues(ast, bindings);
         }
-        query = this.substituteTemplates(query, distribution, dataset);
+        let query = this.generator.stringify(ast);
+        query = query.replaceAll('?dataset', `<${dataset.iri}>`);
         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.
      *

package/dist/sparql/graph.d.ts

@@ -0,0 +1,8 @@
+import type { ConstructQuery } from 'sparqljs';
+/**
+ * Set the default graph (FROM clause) on a parsed CONSTRUCT query.
+ *
+ * Mutates the query in place, replacing any existing FROM clause.
+ */
+export declare function withDefaultGraph(query: ConstructQuery, graphIri: string): void;
+//# sourceMappingURL=graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/sparql/graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,MAAM,GACf,IAAI,CAEN"}

package/dist/sparql/graph.js

@@ -0,0 +1,9 @@
+import { DataFactory } from 'n3';
+/**
+ * Set the default graph (FROM clause) on a parsed CONSTRUCT query.
+ *
+ * Mutates the query in place, replacing any existing FROM clause.
+ */
+export function withDefaultGraph(query, graphIri) {
+    query.from = { default: [DataFactory.namedNode(graphIri)], named: [] };
+}

package/dist/sparql/index.d.ts

@@ -1,4 +1,6 @@
-export { SparqlConstructExecutor, substituteQueryTemplates, NotSupported, readQueryFile, type ExecutableDataset, type Executor, type SparqlConstructExecuteOptions, type SparqlConstructExecutorOptions, type QuadStream, } from './executor.js';
+export { SparqlConstructExecutor, substituteQueryTemplates, NotSupported, readQueryFile, type ExecutableDataset, type Executor, type SparqlConstructExecuteOptions, type SparqlConstructExecutorOptions, type QuadStream, type VariableBindings, } from './executor.js';
 export { collect } from './collect.js';
 export { SparqlSelector, type SparqlSelectorOptions } from './selector.js';
+export { injectValues } from './values.js';
+export { withDefaultGraph } from './graph.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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,QAAQ,EACb,KAAK,6BAA6B,EAClC,KAAK,8BAA8B,EACnC,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC"}
+{"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,QAAQ,EACb,KAAK,6BAA6B,EAClC,KAAK,8BAA8B,EACnC,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3E,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/sparql/index.js

@@ -1,3 +1,5 @@
 export { SparqlConstructExecutor, substituteQueryTemplates, NotSupported, readQueryFile, } from './executor.js';
 export { collect } from './collect.js';
 export { SparqlSelector } from './selector.js';
+export { injectValues } from './values.js';
+export { withDefaultGraph } from './graph.js';

package/dist/sparql/selector.d.ts

@@ -1,5 +1,6 @@
 import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
-import type { StageSelectorBindings, StageSelector } from '../stage.js';
+import type { StageSelector } from '../stage.js';
+import type { VariableBindings } from './executor.js';
 export interface SparqlSelectorOptions {
     /** SELECT query projecting at least one named variable. A LIMIT in the query sets the default page size. */
     query: string;
@@ -25,6 +26,6 @@ export declare class SparqlSelector implements StageSelector {
     private readonly pageSize;
     private readonly fetcher;
     constructor(options: SparqlSelectorOptions);
-    [Symbol.asyncIterator](): AsyncIterableIterator<StageSelectorBindings>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<VariableBindings>;
 }
 //# sourceMappingURL=selector.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../src/sparql/selector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAQ9D,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAKxE,MAAM,WAAW,qBAAqB;IACpC,4GAA4G;IAC5G,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,QAAQ,EAAE,GAAG,CAAC;IACd,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAe,YAAW,aAAa;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAM;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;gBAEpC,OAAO,EAAE,qBAAqB;IAmBnC,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,qBAAqB,CAAC,qBAAqB,CAAC;CAkC9E"}
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../src/sparql/selector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAQ9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAKtD,MAAM,WAAW,qBAAqB;IACpC,4GAA4G;IAC5G,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,QAAQ,EAAE,GAAG,CAAC;IACd,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAe,YAAW,aAAa;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAM;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;gBAEpC,OAAO,EAAE,qBAAqB;IAmBnC,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,qBAAqB,CAAC,gBAAgB,CAAC;CAkCzE"}

package/dist/sparql/values.d.ts

@@ -0,0 +1,13 @@
+import type { ConstructQuery } from 'sparqljs';
+import type { VariableBindings } from './executor.js';
+/**
+ * Inject a VALUES clause into a parsed CONSTRUCT query for the given binding rows.
+ *
+ * Each row's keys become `?`-prefixed SPARQL variables; NamedNode values
+ * become IRIs in the VALUES block. The VALUES clause is prepended to the
+ * query's WHERE patterns.
+ *
+ * The caller owns parsing and stringifying; this function operates on the AST.
+ */
+export declare function injectValues(query: ConstructQuery, bindings: VariableBindings[]): ConstructQuery;
+//# sourceMappingURL=values.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/sparql/values.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,UAAU,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,gBAAgB,EAAE,GAC3B,cAAc,CAchB"}

package/dist/sparql/values.js

@@ -0,0 +1,19 @@
+/**
+ * Inject a VALUES clause into a parsed CONSTRUCT query for the given binding rows.
+ *
+ * Each row's keys become `?`-prefixed SPARQL variables; NamedNode values
+ * become IRIs in the VALUES block. The VALUES clause is prepended to the
+ * query's WHERE patterns.
+ *
+ * The caller owns parsing and stringifying; this function operates on the AST.
+ */
+export function injectValues(query, bindings) {
+    const valuesPattern = {
+        type: 'values',
+        values: bindings.map((row) => Object.fromEntries(Object.entries(row).map(([name, node]) => [`?${name}`, node]))),
+    };
+    return {
+        ...query,
+        where: [valuesPattern, ...(query.where ?? [])],
+    };
+}

package/dist/stage.d.ts

@@ -1,19 +1,20 @@
-import type { NamedNode, Quad } from '@rdfjs/types';
-import type { ExecutableDataset, Executor } from './sparql/executor.js';
+import type { Quad } from '@rdfjs/types';
+import type { ExecutableDataset, Executor, VariableBindings } from './sparql/executor.js';
 import { NotSupported } from './sparql/executor.js';
 export interface StageOptions {
     name: string;
     executors: Executor | Executor[];
+    selector?: StageSelector;
 }
 export declare class Stage {
     readonly name: string;
     private readonly executors;
+    private readonly selector?;
     constructor(options: StageOptions);
     run(dataset: ExecutableDataset): Promise<AsyncIterable<Quad> | NotSupported>;
+    private collectBindings;
 }
-/** A single row of variable bindings from a selector query. */
-export type StageSelectorBindings = Record<string, NamedNode>;
 /** Stage-level selector that yields variable bindings for use in executor queries. Pagination is an implementation detail. */
-export interface StageSelector extends AsyncIterable<StageSelectorBindings> {
+export interface StageSelector extends AsyncIterable<VariableBindings> {
 }
 //# sourceMappingURL=stage.d.ts.map

package/dist/stage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAAC;CAClC;AAED,qBAAa,KAAK;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;gBAE3B,OAAO,EAAE,YAAY;IAO3B,GAAG,CACP,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC;CAgB/C;AAUD,+DAA+D;AAC/D,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAE9D,8HAA8H;AAE9H,MAAM,WAAW,aAAc,SAAQ,aAAa,CAAC,qBAAqB,CAAC;CAAG"}
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EACV,iBAAiB,EACjB,QAAQ,EACR,gBAAgB,EACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAAC;IACjC,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,qBAAa,KAAK;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAgB;gBAE9B,OAAO,EAAE,YAAY;IAQ3B,GAAG,CACP,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC;YAoBhC,eAAe;CAW9B;AAUD,8HAA8H;AAE9H,MAAM,WAAW,aAAc,SAAQ,aAAa,CAAC,gBAAgB,CAAC;CAAG"}

package/dist/stage.js

@@ -2,16 +2,20 @@ import { NotSupported } from './sparql/executor.js';
 export class Stage {
     name;
     executors;
+    selector;
     constructor(options) {
         this.name = options.name;
         this.executors = Array.isArray(options.executors)
             ? options.executors
             : [options.executors];
+        this.selector = options.selector;
     }
     async run(dataset) {
+        const bindings = await this.collectBindings();
+        const executeOptions = bindings.length > 0 ? { bindings } : undefined;
         const streams = [];
         for (const executor of this.executors) {
-            const result = await executor.execute(dataset);
+            const result = await executor.execute(dataset, executeOptions);
             if (!(result instanceof NotSupported)) {
                 streams.push(result);
             }
@@ -21,6 +25,16 @@ export class Stage {
         }
         return mergeStreams(streams);
     }
+    async collectBindings() {
+        if (this.selector === undefined) {
+            return [];
+        }
+        const bindings = [];
+        for await (const row of this.selector) {
+            bindings.push(row);
+        }
+        return bindings;
+    }
 }
 async function* mergeStreams(streams) {
     for (const stream of streams) {

package/dist/step/sparqlQuery.d.ts

@@ -1,4 +1,4 @@
-import { DataEmittingStep } from './../step.js';
+import { DataEmittingStep, NotSupported } from './../step.js';
 import { Dataset } from '@lde/dataset';
 import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
 /**
@@ -17,13 +17,15 @@ export interface Args {
  * Executes a SPARQL CONSTRUCT query and emits the resulting quads.
  *
  * This step wraps the SparqlConstructExecutor to provide the DataEmittingStep interface
- * for use in pipelines.
+ * for use in pipelines. Supports legacy template substitution (`#namedGraph#`,
+ * `#subjectFilter#`, `?dataset`); for new code prefer the AST-based executor directly.
  */
 export declare class SparqlQuery implements DataEmittingStep {
     readonly identifier: string;
-    private readonly executor;
+    private readonly query;
+    private readonly fetcher?;
     constructor({ identifier, query, fetcher }: Args);
-    execute(dataset: Dataset): Promise<import("./../step.js").NotSupported | import("../sparql/executor.js").QuadStream>;
+    execute(dataset: Dataset): Promise<NotSupported | import("../sparql/executor.js").QuadStream>;
     static fromFile(filename: string): Promise<SparqlQuery>;
 }
 /**

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,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"}
+{"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;AAO9D;;;;;;GAMG;AACH,MAAM,WAAW,IAAI;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;;;;;GAMG;AACH,qBAAa,WAAY,YAAW,gBAAgB;IAClD,SAAgB,UAAU,SAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAwB;gBAErC,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI;IAM1C,OAAO,CAAC,OAAO,EAAE,OAAO;WAiBV,QAAQ,CAAC,QAAQ,EAAE,MAAM;CAM9C;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,mBAE9C"}

package/dist/step/sparqlQuery.js

@@ -1,22 +1,32 @@
-import { SparqlConstructExecutor, readQueryFile } from '../sparql/index.js';
+import { NotSupported } from './../step.js';
+import { SparqlConstructExecutor, substituteQueryTemplates, readQueryFile, } from '../sparql/index.js';
 /**
  * Executes a SPARQL CONSTRUCT query and emits the resulting quads.
  *
  * This step wraps the SparqlConstructExecutor to provide the DataEmittingStep interface
- * for use in pipelines.
+ * for use in pipelines. Supports legacy template substitution (`#namedGraph#`,
+ * `#subjectFilter#`, `?dataset`); for new code prefer the AST-based executor directly.
  */
 export class SparqlQuery {
     identifier;
-    executor;
+    query;
+    fetcher;
     constructor({ identifier, query, fetcher }) {
         this.identifier = identifier;
-        this.executor = new SparqlConstructExecutor({
-            query,
-            fetcher,
-        });
+        this.query = query;
+        this.fetcher = fetcher;
     }
     async execute(dataset) {
-        return await this.executor.execute(dataset);
+        const distribution = dataset.getSparqlDistribution();
+        if (distribution === null || !distribution.isValid) {
+            return new NotSupported('No SPARQL distribution available');
+        }
+        const substituted = substituteQueryTemplates(this.query, distribution, dataset);
+        const executor = new SparqlConstructExecutor({
+            query: substituted,
+            fetcher: this.fetcher,
+        });
+        return await executor.execute(dataset);
     }
     static async fromFile(filename) {
         return new this({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/pipeline",
-  "version": "0.6.12",
+  "version": "0.6.13",
   "repository": {
     "url": "https://github.com/ldengine/lde",
     "directory": "packages/pipeline"
@@ -35,10 +35,10 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@lde/dataset": "0.6.6",
-    "@lde/dataset-registry-client": "0.6.12",
-    "@lde/sparql-importer": "0.2.6",
-    "@lde/sparql-server": "0.4.6",
+    "@lde/dataset": "0.6.7",
+    "@lde/dataset-registry-client": "0.6.13",
+    "@lde/sparql-importer": "0.2.7",
+    "@lde/sparql-server": "0.4.7",
     "@rdfjs/types": "^2.0.1",
     "c12": "^3.0.2",
     "fetch-sparql-endpoint": "^6.0.0",