@lde/pipeline 0.31.5 → 0.33.0

package/dist/sparql/{executor.d.ts → reader.d.ts}

@@ -4,7 +4,7 @@ import type { NamedNode, Quad } from '@rdfjs/types';
 import { Transform } from 'node:stream';
 import { type TimeoutPolicy } from './timeoutPolicy.js';
 /**
- * An executor could not run because the dataset lacks a supported distribution.
+ * A reader could not run because the dataset lacks a supported distribution.
  */
 export declare class NotSupported {
     readonly message: string;
@@ -12,30 +12,30 @@ export declare class NotSupported {
 }
 /** A single row of variable bindings (variable name → NamedNode). */
 export type VariableBindings = Record<string, NamedNode>;
-export interface ExecuteOptions {
+export interface ReadOptions {
     /**
      * Variable bindings to inject as a VALUES clause into the query.
      * When non-empty, a VALUES block is prepended to the WHERE clause.
      */
     bindings?: VariableBindings[];
     /**
-     * Per-call {@link TimeoutPolicy}. When supplied, the executor calls
+     * Per-call {@link TimeoutPolicy}. When supplied, the reader calls
      * {@link TimeoutPolicy.beforeRequest} once per attempt (including
      * retries), installs an {@link AbortSignal} with the returned budget,
      * and reports the outcome via {@link TimeoutPolicy.afterRequest}.
      *
-     * Overrides the executor-level policy passed at construction time.
+     * Overrides the reader-level policy passed at construction time.
      * Pipeline runners use this to thread the per-dataset policy through.
      */
     timeout?: TimeoutPolicy;
 }
-export interface Executor {
-    execute(dataset: Dataset, distribution: Distribution, options?: ExecuteOptions): Promise<AsyncIterable<Quad> | NotSupported>;
+export interface Reader {
+    read(dataset: Dataset, distribution: Distribution, options?: ReadOptions): Promise<AsyncIterable<Quad> | NotSupported>;
 }
 /**
- * Options for SparqlConstructExecutor.
+ * Options for SparqlConstructReader.
  */
-export interface SparqlConstructExecutorOptions {
+export interface SparqlConstructReaderOptions {
     /**
      * SPARQL CONSTRUCT query to execute.
      */
@@ -48,13 +48,13 @@ export interface SparqlConstructExecutorOptions {
     /**
      * Optional custom SparqlEndpointFetcher instance.
      *
-     * When supplied, the executor uses this fetcher as-is for every attempt
+     * When supplied, the reader uses this fetcher as-is for every attempt
      * — the per-attempt timeout from the {@link TimeoutPolicy} is **not**
      * enforced (the supplied fetcher’s own `timeout` governs). Policy
      * `beforeRequest`/`afterRequest` hooks still fire so outcome
      * classification works, but adaptive tightening cannot apply.
      *
-     * When omitted, the executor builds a fresh
+     * When omitted, the reader builds a fresh
      * {@link SparqlEndpointFetcher} per attempt with the per-attempt timeout
      * baked in.
      *
@@ -82,7 +82,7 @@ export interface SparqlConstructExecutorOptions {
      * every solution row. When enabled, a streaming identity filter removes
      * duplicates inline without buffering.
      *
-     * The dedup set is scoped to each {@link execute} call, so memory stays
+     * The dedup set is scoped to each {@link read} call, so memory stays
      * bounded to the number of unique quads per call (typically one batch).
      *
      * Inspired by Comunica's `distinctConstruct` context option.
@@ -92,23 +92,23 @@ export interface SparqlConstructExecutorOptions {
     deduplicate?: boolean;
 }
 /**
- * A streaming SPARQL CONSTRUCT executor.
+ * A streaming SPARQL CONSTRUCT reader.
  *
  * Queries **without** `#subjectFilter#` are parsed once in the constructor
  * (fast path). Queries that contain the template are stored as raw strings
- * and parsed at {@link execute} time after substitution.
+ * and parsed at {@link read} time after substitution.
  *
  * Template substitution (applied in order):
- * 1. `#subjectFilter#` — replaced with `distribution.subjectFilter` (deferred to execute)
+ * 1. `#subjectFilter#` — replaced with `distribution.subjectFilter` (deferred to read)
  * 2. `FROM <graph>` — set via `withDefaultGraph` if the distribution has a named graph
  * 3. `?dataset` — replaced with the dataset IRI (string substitution on the serialised query)
  *
  * @example
  * ```typescript
- * const executor = new SparqlConstructExecutor({
+ * const reader = new SparqlConstructReader({
  *   query: 'CONSTRUCT { ?dataset ?p ?o } WHERE { ?s ?p ?o }',
  * });
- * const result = await executor.execute(dataset, distribution);
+ * const result = await reader.read(dataset, distribution);
  * if (result instanceof NotSupported) {
  *   console.log(result.message);
  * } else {
@@ -118,7 +118,7 @@ export interface SparqlConstructExecutorOptions {
  * }
  * ```
  */
-export declare class SparqlConstructExecutor implements Executor {
+export declare class SparqlConstructReader implements Reader {
     private readonly rawQuery;
     private readonly preParsed?;
     private readonly userFetcher?;
@@ -126,16 +126,17 @@ export declare class SparqlConstructExecutor implements Executor {
     private readonly lineBuffer;
     private readonly deduplicate;
     private readonly generator;
-    constructor(options: SparqlConstructExecutorOptions);
+    constructor(options: SparqlConstructReaderOptions);
     /**
-     * Execute the SPARQL CONSTRUCT query against the distribution's endpoint.
+     * Read quads by executing the SPARQL CONSTRUCT query against the
+     * distribution's endpoint.
      *
-     * @param dataset The dataset to execute against.
+     * @param dataset The dataset to read from.
      * @param distribution The distribution providing the SPARQL endpoint.
-     * @param options Optional execution options (bindings).
+     * @param options Optional read options (bindings).
      * @returns AsyncIterable<Quad> stream of results.
      */
-    execute(dataset: Dataset, distribution: Distribution, options?: ExecuteOptions): Promise<AsyncIterable<Quad>>;
+    read(dataset: Dataset, distribution: Distribution, options?: ReadOptions): Promise<AsyncIterable<Quad>>;
     /**
      * Run a single attempt against the endpoint with a per-call abort
      * signal derived from {@link TimeoutPolicy.beforeRequest}. Reports the
@@ -147,7 +148,7 @@ export declare class SparqlConstructExecutor implements Executor {
      * Pick the fetcher to use for a single attempt. A user-supplied fetcher
      * is used as-is and its own timeout governs the request; the per-attempt
      * policy budget is bypassed in that case (see the JSDoc on
-     * {@link SparqlConstructExecutorOptions.fetcher}). Otherwise a fresh
+     * {@link SparqlConstructReaderOptions.fetcher}). Otherwise a fresh
      * {@link SparqlEndpointFetcher} is constructed per attempt with the
      * policy-supplied timeout baked in.
      */
@@ -159,12 +160,12 @@ export declare class SparqlConstructExecutor implements Executor {
      */
     private fetchQuads;
     /**
-     * Create an executor from a query file.
+     * Create a reader from a query file.
      *
      * @param filename Path to the query file.
-     * @param options Optional executor options (timeout, fetcher).
+     * @param options Optional reader options (timeout, fetcher).
      */
-    static fromFile(filename: string, options?: Omit<SparqlConstructExecutorOptions, 'query'>): Promise<SparqlConstructExecutor>;
+    static fromFile(filename: string, options?: Omit<SparqlConstructReaderOptions, 'query'>): Promise<SparqlConstructReader>;
 }
 /**
  * Read a SPARQL query from a file.
@@ -213,4 +214,4 @@ export declare class LineBufferTransform extends Transform {
  * ```
  */
 export declare function deduplicateQuads(quads: AsyncIterable<Quad>): AsyncIterable<Quad>;
-//# sourceMappingURL=executor.d.ts.map
+//# sourceMappingURL=reader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/sparql/reader.ts"],"names":[],"mappings":"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"}

package/dist/sparql/{executor.js → reader.js}

@@ -14,12 +14,12 @@ import { injectValues } from './values.js';
 import { ConstantTimeoutPolicy, } from './timeoutPolicy.js';
 /**
  * Fallback policy when no per-call `TimeoutPolicy` is supplied via
- * {@link ExecuteOptions.timeout}. Pipeline always supplies one, so this only
- * matters when the executor is driven directly (without a Pipeline).
+ * {@link ReadOptions.timeout}. Pipeline always supplies one, so this only
+ * matters when the reader is driven directly (without a Pipeline).
  */
 const defaultTimeoutPolicy = new ConstantTimeoutPolicy(300_000);
 /**
- * An executor could not run because the dataset lacks a supported distribution.
+ * A reader could not run because the dataset lacks a supported distribution.
  */
 export class NotSupported {
     message;
@@ -28,23 +28,23 @@ export class NotSupported {
     }
 }
 /**
- * A streaming SPARQL CONSTRUCT executor.
+ * A streaming SPARQL CONSTRUCT reader.
  *
  * Queries **without** `#subjectFilter#` are parsed once in the constructor
  * (fast path). Queries that contain the template are stored as raw strings
- * and parsed at {@link execute} time after substitution.
+ * and parsed at {@link read} time after substitution.
  *
  * Template substitution (applied in order):
- * 1. `#subjectFilter#` — replaced with `distribution.subjectFilter` (deferred to execute)
+ * 1. `#subjectFilter#` — replaced with `distribution.subjectFilter` (deferred to read)
  * 2. `FROM <graph>` — set via `withDefaultGraph` if the distribution has a named graph
  * 3. `?dataset` — replaced with the dataset IRI (string substitution on the serialised query)
  *
  * @example
  * ```typescript
- * const executor = new SparqlConstructExecutor({
+ * const reader = new SparqlConstructReader({
  *   query: 'CONSTRUCT { ?dataset ?p ?o } WHERE { ?s ?p ?o }',
  * });
- * const result = await executor.execute(dataset, distribution);
+ * const result = await reader.read(dataset, distribution);
  * if (result instanceof NotSupported) {
  *   console.log(result.message);
  * } else {
@@ -54,7 +54,7 @@ export class NotSupported {
  * }
  * ```
  */
-export class SparqlConstructExecutor {
+export class SparqlConstructReader {
     rawQuery;
     preParsed;
     userFetcher;
@@ -77,14 +77,15 @@ export class SparqlConstructExecutor {
         this.userFetcher = options.fetcher;
     }
     /**
-     * Execute the SPARQL CONSTRUCT query against the distribution's endpoint.
+     * Read quads by executing the SPARQL CONSTRUCT query against the
+     * distribution's endpoint.
      *
-     * @param dataset The dataset to execute against.
+     * @param dataset The dataset to read from.
      * @param distribution The distribution providing the SPARQL endpoint.
-     * @param options Optional execution options (bindings).
+     * @param options Optional read options (bindings).
      * @returns AsyncIterable<Quad> stream of results.
      */
-    async execute(dataset, distribution, options) {
+    async read(dataset, distribution, options) {
         const endpoint = distribution.accessUrl;
         let ast;
         if (this.preParsed) {
@@ -148,7 +149,7 @@ export class SparqlConstructExecutor {
      * Pick the fetcher to use for a single attempt. A user-supplied fetcher
      * is used as-is and its own timeout governs the request; the per-attempt
      * policy budget is bypassed in that case (see the JSDoc on
-     * {@link SparqlConstructExecutorOptions.fetcher}). Otherwise a fresh
+     * {@link SparqlConstructReaderOptions.fetcher}). Otherwise a fresh
      * {@link SparqlEndpointFetcher} is constructed per attempt with the
      * policy-supplied timeout baked in.
      */
@@ -172,14 +173,14 @@ export class SparqlConstructExecutor {
             .pipe(new StreamParser({ format: contentType }));
     }
     /**
-     * Create an executor from a query file.
+     * Create a reader from a query file.
      *
      * @param filename Path to the query file.
-     * @param options Optional executor options (timeout, fetcher).
+     * @param options Optional reader options (timeout, fetcher).
      */
     static async fromFile(filename, options) {
         const query = await readQueryFile(filename);
-        return new SparqlConstructExecutor({ ...options, query });
+        return new SparqlConstructReader({ ...options, query });
     }
 }
 /**

package/dist/sparql/selector.d.ts

@@ -1,7 +1,7 @@
 import type { Distribution } from '@lde/dataset';
 import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
 import type { ItemSelector, SelectOptions } from '../stage.js';
-import type { VariableBindings } from './executor.js';
+import type { VariableBindings } from './reader.js';
 export interface SparqlItemSelectorOptions {
     /**
      * SELECT query projecting at least one named variable.

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

@@ -1 +1 @@
-{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../src/sparql/selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAQ9D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAoBtD,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAwB;gBAEzC,OAAO,EAAE,yBAAyB;IAmBvC,MAAM,CACX,YAAY,EAAE,YAAY,EAC1B,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,qBAAqB,CAAC,gBAAgB,CAAC;IA4D1C;;;;OAIG;YACW,uBAAuB;CA8BtC"}
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../src/sparql/selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAQ9D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAoBpD,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAwB;gBAEzC,OAAO,EAAE,yBAAyB;IAmBvC,MAAM,CACX,YAAY,EAAE,YAAY,EAC1B,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,qBAAqB,CAAC,gBAAgB,CAAC;IA4D1C;;;;OAIG;YACW,uBAAuB;CA8BtC"}

package/dist/sparql/values.d.ts

@@ -1,5 +1,5 @@
 import { type Pattern, type QueryConstruct, type QuerySelect } from '@traqula/rules-sparql-1-1';
-import type { VariableBindings } from './executor.js';
+import type { VariableBindings } from './reader.js';
 /**
  * Find the first SubSelect within a list of patterns, looking through
  * intermediate group patterns (the parser wraps `{ SELECT }` in a group).

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

@@ -1 +1 @@
-{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/sparql/values.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,OAAO,EAGZ,KAAK,cAAc,EACnB,KAAK,WAAW,EAEjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAItD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,WAAW,GAAG,SAAS,CAW1E;AA0DD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,gBAAgB,EAAE,GAC3B,cAAc,CAoBhB"}
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/sparql/values.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,OAAO,EAGZ,KAAK,cAAc,EACnB,KAAK,WAAW,EAEjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,WAAW,GAAG,SAAS,CAW1E;AA0DD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,gBAAgB,EAAE,GAC3B,cAAc,CAoBhB"}

package/dist/stage.d.ts

@@ -1,10 +1,10 @@
 import { Dataset, Distribution } from '@lde/dataset';
 import type { Quad } from '@rdfjs/types';
-import type { Executor, VariableBindings } from './sparql/executor.js';
-import { NotSupported } from './sparql/executor.js';
+import type { Reader, VariableBindings } from './sparql/reader.js';
+import { NotSupported } from './sparql/reader.js';
 import type { TimeoutPolicy } from './sparql/timeoutPolicy.js';
 import type { Validator } from './validator.js';
-import type { Writer } from './writer/writer.js';
+import type { DatasetWriter } from './writer/writer.js';
 /**
  * Transforms a quad stream, given the context of its extension point.
  *
@@ -15,42 +15,42 @@ import type { Writer } from './writer/writer.js';
  */
 export type QuadTransform<Ctx> = (quads: AsyncIterable<Quad>, context: Ctx) => AsyncIterable<Quad>;
 /**
- * Context handed to a {@link QuadTransform} attached to an executor (extension
- * point 1: per-executor output, pre-merge).
+ * Context handed to a {@link QuadTransform} attached to a reader (extension
+ * point 1: per-reader output, pre-merge).
  *
  * `distribution` gives the transform endpoint reach – it may fire its own
  * SPARQL queries – and `stage` carries the stage identity.
  */
-export interface ExecutorContext {
+export interface ReaderContext {
     dataset: Dataset;
     distribution: Distribution;
     stage: string;
 }
 /**
- * An {@link Executor} with zero or more {@link QuadTransform}s attached as data.
+ * An {@link Reader} with zero or more {@link QuadTransform}s attached as data.
  *
- * The stage runner applies the transform(s) in order to **this executor's
- * output** before merging it with sibling executors. The window is one
- * `execute()` call:
+ * The stage runner applies the transform(s) in order to **this reader's
+ * output** before merging it with sibling readers. The window is one
+ * `read()` call:
  *
- * - for a global stage that is the executor's complete output;
+ * - for a global stage that is the reader's complete output;
  * - for a per-class stage that is one batch – one class at `batchSize: 1`.
  *
- * Decorating an executor is therefore construction-time data, not a wrapping
- * class: the runner is the only code that delegates to the inner executor.
+ * Decorating a reader is therefore construction-time data, not a wrapping
+ * class: the runner is the only code that delegates to the inner reader.
  */
-export interface AttachedExecutor {
-    executor: Executor;
-    transform?: QuadTransform<ExecutorContext> | QuadTransform<ExecutorContext>[];
+export interface AttachedReader {
+    reader: Reader;
+    transform?: QuadTransform<ReaderContext> | QuadTransform<ReaderContext>[];
 }
-/** One or more executors, each optionally carrying attached transforms. */
-export type StageExecutors = Executor | AttachedExecutor | (Executor | AttachedExecutor)[];
+/** One or more readers, each optionally carrying attached transforms. */
+export type StageReaders = Reader | AttachedReader | (Reader | AttachedReader)[];
 export interface StageOptions {
     name: string;
-    executors: StageExecutors;
+    readers: StageReaders;
     itemSelector?: ItemSelector;
     /**
-     * Maximum number of bindings per executor call.
+     * Maximum number of bindings per reader call.
      *
      * Also used as the selector's page size so that each paginated request
      * fills exactly one batch. A `LIMIT` clause in the selector query
@@ -61,8 +61,8 @@ export interface StageOptions {
     batchSize?: number;
     /**
      * Maximum concurrent in-flight SPARQL queries. Within each batch, all
-     * executors run in parallel; the number of concurrent batches is
-     * automatically reduced to `⌊maxConcurrency / executorCount⌋` so the
+     * readers run in parallel; the number of concurrent batches is
+     * automatically reduced to `⌊maxConcurrency / readerCount⌋` so the
      * total query pressure stays within this limit.
      *
      * @default 10
@@ -87,7 +87,7 @@ export interface StageOptions {
      * @default false
      */
     expectsOutput?: boolean;
-    /** Optional validation of the combined quads produced by all executors per batch. */
+    /** Optional validation of the combined quads produced by all readers per batch. */
     validation?: {
         validator: Validator;
         /** What to do when a batch fails validation. @default 'write' */
@@ -97,7 +97,7 @@ export interface StageOptions {
 export interface RunOptions {
     onProgress?: (itemsProcessed: number, quadsGenerated: number) => void;
     /**
-     * Per-dataset {@link TimeoutPolicy} threaded through to executors and
+     * Per-dataset {@link TimeoutPolicy} threaded through to readers and
      * item selectors. The Pipeline owns lifecycle (factory invocation per
      * dataset), so a single policy instance covers all stages and child
      * stages within one dataset.
@@ -114,7 +114,7 @@ export declare class Stage {
     readonly stages: readonly Stage[];
     /** Whether an empty result is treated as a hard failure. @see {@link StageOptions.expectsOutput} */
     readonly expectsOutput: boolean;
-    private readonly executors;
+    private readonly readers;
     private readonly itemSelector?;
     private readonly batchSize;
     private readonly maxConcurrency;
@@ -122,7 +122,7 @@ export declare class Stage {
     constructor(options: StageOptions);
     /** The validator for this stage, if configured. */
     get validator(): Validator | undefined;
-    run(dataset: Dataset, distribution: Distribution, writer: Writer, options?: RunOptions): Promise<NotSupported | void>;
+    run(dataset: Dataset, distribution: Distribution, writer: DatasetWriter, options?: RunOptions): Promise<NotSupported | void>;
     /**
      * Throw when {@link StageOptions.expectsOutput} is set but the stage produced
      * no quads — a supported-but-empty result that signals a truncated or aborted
@@ -135,16 +135,16 @@ export declare class Stage {
      * (empty array when skipping invalid batches).
      */
     private validateBuffer;
-    private executeAll;
+    private readAll;
     /**
-     * Fold an executor's attached transforms over its output stream, in order,
-     * supplying the {@link ExecutorContext}. A transform sees one `execute()`
-     * call's output (see {@link AttachedExecutor}); `NotSupported` is handled by
+     * Fold a reader's attached transforms over its output stream, in order,
+     * supplying the {@link ReaderContext}. A transform sees one `read()`
+     * call's output (see {@link AttachedReader}); `NotSupported` is handled by
      * the caller and never reaches a transform.
      */
     private applyTransforms;
 }
-/** Selects items (as variable bindings) for executors to process. Pagination is an implementation detail. */
+/** Selects items (as variable bindings) for readers to process. Pagination is an implementation detail. */
 export interface ItemSelector {
     select(distribution: Distribution, batchSize?: number, options?: SelectOptions): AsyncIterable<VariableBindings>;
 }

package/dist/stage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGjD;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,CAAC,GAAG,IAAI,CAC/B,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,EAC1B,OAAO,EAAE,GAAG,KACT,aAAa,CAAC,IAAI,CAAC,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,aAAa,CAAC,eAAe,CAAC,EAAE,CAAC;CAC/E;AAED,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,gBAAgB,GAChB,CAAC,QAAQ,GAAG,gBAAgB,CAAC,EAAE,CAAC;AAQpC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,cAAc,CAAC;IAC1B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qFAAqF;IACrF,UAAU,CAAC,EAAE;QACX,SAAS,EAAE,SAAS,CAAC;QACrB,iEAAiE;QACjE,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;KACvC,CAAC;CACH;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;IACtE;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,qBAAa,KAAK;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,oGAAoG;IACpG,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA6B;gBAE7C,OAAO,EAAE,YAAY;IAWjC,mDAAmD;IACnD,IAAI,SAAS,IAAI,SAAS,GAAG,SAAS,CAErC;IAEK,GAAG,CACP,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAqE/B;;;;OAIG;IACH,OAAO,CAAC,cAAc;YAMR,eAAe;IAgK7B;;;OAGG;YACW,cAAc;YAqBd,UAAU;IA6BxB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;CAiBxB;AAiDD,6GAA6G;AAC7G,MAAM,WAAW,YAAY;IAC3B,MAAM,CACJ,YAAY,EAAE,YAAY,EAC1B,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CAAC,gBAAgB,CAAC,CAAC;CACpC"}
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":"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"}

package/dist/stage.js

@@ -1,4 +1,4 @@
-import { NotSupported } from './sparql/executor.js';
+import { NotSupported } from './sparql/reader.js';
 import { batch } from './batch.js';
 import { AsyncQueue } from './asyncQueue.js';
 export class Stage {
@@ -6,7 +6,7 @@ export class Stage {
     stages;
     /** Whether an empty result is treated as a hard failure. @see {@link StageOptions.expectsOutput} */
     expectsOutput;
-    executors;
+    readers;
     itemSelector;
     batchSize;
     maxConcurrency;
@@ -14,7 +14,7 @@ export class Stage {
     constructor(options) {
         this.name = options.name;
         this.stages = options.stages ?? [];
-        this.executors = normalizeExecutors(options.executors);
+        this.readers = normalizeReaders(options.readers);
         this.itemSelector = options.itemSelector;
         this.batchSize = options.batchSize ?? 10;
         this.maxConcurrency = options.maxConcurrency ?? 10;
@@ -32,11 +32,11 @@ export class Stage {
                 timeout,
             }), dataset, distribution, writer, options);
         }
-        const streams = await this.executeAll(dataset, distribution, timeout);
+        const streams = await this.readAll(dataset, distribution, timeout);
         if (streams instanceof NotSupported) {
             return streams;
         }
-        // Quads the executors produced (before any validation filtering); used to
+        // Quads the readers produced (before any validation filtering); used to
         // enforce `expectsOutput` below.
         let produced = 0;
         if (this.validation) {
@@ -116,10 +116,10 @@ export class Stage {
         const dispatch = async () => {
             const inFlight = new Set();
             let firstError;
-            // Divide maxConcurrency by executor count so the total concurrent
+            // Divide maxConcurrency by reader count so the total concurrent
             // SPARQL queries stays at maxConcurrency (each batch runs all
-            // executors in parallel).
-            const maxConcurrentBatches = Math.max(1, Math.floor(this.maxConcurrency / this.executors.length));
+            // readers in parallel).
+            const maxConcurrentBatches = Math.max(1, Math.floor(this.maxConcurrency / this.readers.length));
             const track = (promise) => {
                 const p = promise.then(() => {
                     inFlight.delete(p);
@@ -140,9 +140,9 @@ export class Stage {
                             break;
                     }
                     track((async () => {
-                        // Run all executors for this batch in parallel.
-                        const executorOutputs = await Promise.all(this.executors.map(async ({ executor, transforms }) => {
-                            const result = await executor.execute(dataset, distribution, {
+                        // Run all readers for this batch in parallel.
+                        const readerOutputs = await Promise.all(this.readers.map(async ({ reader, transforms }) => {
+                            const result = await reader.read(dataset, distribution, {
                                 bindings,
                                 timeout: options?.timeout,
                             });
@@ -156,7 +156,7 @@ export class Stage {
                             }
                             return quads;
                         }));
-                        const batchQuads = executorOutputs.flat();
+                        const batchQuads = readerOutputs.flat();
                         if (this.validation &&
                             batchQuads.length > 0 &&
                             onInvalid !== 'write') {
@@ -208,7 +208,7 @@ export class Stage {
         })();
         await Promise.all([dispatchPromise, writePromise]);
         if (!hasResults) {
-            return new NotSupported('All executors returned NotSupported');
+            return new NotSupported('All readers returned NotSupported');
         }
         this.assertProduced(quadsGenerated);
     }
@@ -228,9 +228,9 @@ export class Stage {
         // 'skip': discard
         return [];
     }
-    async executeAll(dataset, distribution, timeout) {
-        const results = await Promise.all(this.executors.map(async ({ executor, transforms }) => {
-            const result = await executor.execute(dataset, distribution, {
+    async readAll(dataset, distribution, timeout) {
+        const results = await Promise.all(this.readers.map(async ({ reader, transforms }) => {
+            const result = await reader.read(dataset, distribution, {
                 timeout,
             });
             if (result instanceof NotSupported)
@@ -244,14 +244,14 @@ export class Stage {
             }
         }
         if (streams.length === 0) {
-            return new NotSupported('All executors returned NotSupported');
+            return new NotSupported('All readers returned NotSupported');
         }
         return streams;
     }
     /**
-     * Fold an executor's attached transforms over its output stream, in order,
-     * supplying the {@link ExecutorContext}. A transform sees one `execute()`
-     * call's output (see {@link AttachedExecutor}); `NotSupported` is handled by
+     * Fold a reader's attached transforms over its output stream, in order,
+     * supplying the {@link ReaderContext}. A transform sees one `read()`
+     * call's output (see {@link AttachedReader}); `NotSupported` is handled by
      * the caller and never reaches a transform.
      */
     applyTransforms(transforms, stream, dataset, distribution) {
@@ -265,20 +265,20 @@ export class Stage {
         return transforms.reduce((quads, transform) => transform(quads, context), stream);
     }
 }
-/** Normalise the {@link StageExecutors} union to executor + transforms pairs. */
-function normalizeExecutors(executors) {
-    const list = Array.isArray(executors) ? executors : [executors];
+/** Normalise the {@link StageReaders} union to reader + transforms pairs. */
+function normalizeReaders(readers) {
+    const list = Array.isArray(readers) ? readers : [readers];
     return list.map((entry) => {
-        if ('execute' in entry) {
-            return { executor: entry, transforms: [] };
+        if ('read' in entry) {
+            return { reader: entry, transforms: [] };
         }
-        const { executor, transform } = entry;
+        const { reader, transform } = entry;
         const transforms = transform === undefined
             ? []
             : Array.isArray(transform)
                 ? [...transform]
                 : [transform];
-        return { executor, transforms };
+        return { reader, transforms };
     });
 }
 async function* mergeStreams(streams) {