@lde/pipeline 0.6.26 → 0.6.28

package/README.md

@@ -2,63 +2,111 @@
 
 Framework for building RDF data processing pipelines with SPARQL.
 
-## Features
-
-- **Pipeline** — orchestrates steps that process DCAT datasets
-- **PipelineBuilder** — fluent API for constructing pipelines from steps and selectors
-- **PipelineConfig** — load pipeline configuration from YAML/JSON files
-- **SparqlConstructExecutor** — streaming SPARQL CONSTRUCT with template substitution and variable bindings
-- **Distribution analysis** — probe and analyze dataset distributions
-
 ## Components
 
 A **Pipeline** consists of:
 
-- one **[Dataset Selector](#dataset-selector)**
-- one **[Distribution Resolver](#distribution-resolver)** that resolves the input dataset to a usable SPARQL distribution
+- a **Dataset Selector** that selects which datasets to process
+- a **Distribution Resolver** that resolves each dataset to a usable SPARQL endpoint
 - one or more **Stages**, each consisting of:
-  - an optional **Selector** that filters resources
-  - one or more **Executors** that generate triples for each selected resource
+  - an optional **Item Selector** that selects resources (as variable bindings) for fan-out
+  - one or more **Executors** that generate triples
 
 ### Dataset Selector
 
-Selects datasets, either manually by the user or dynamically by querying a DCAT Dataset Registry.
+Selects datasets, either manually or by querying a DCAT Dataset Registry:
 
-### Distribution Resolver
+```typescript
+// From a registry
+const selector = new RegistrySelector({
+  registry: new Client(new URL('https://example.com/sparql')),
+});
 
-Resolves each selected dataset to a usable distribution.
+// Manual
+const selector = new ManualDatasetSelection([dataset]);
+```
 
-#### SPARQL Distribution Resolver
+### Item Selector
 
-If a working SPARQL endpoint is already available for the dataset, that is used.
-If not, and a valid RDF datadump is available, that is imported to a local SPARQL server.
+Selects resources from the distribution and fans out executor calls per batch of results. Implements the `ItemSelector` interface:
 
-#### Other Distribution Resolvers
+```typescript
+interface ItemSelector {
+  select(distribution: Distribution): AsyncIterable<VariableBindings>;
+}
+```
 
-### Bindings Selector
+The distribution is received at run time, so selectors don't need the endpoint URL at construction time. Use `SparqlItemSelector` for SPARQL-based selection with automatic pagination:
 
-Selects resources from the dataset and to fan out queries per result in the executor.
-Bindings are free, and replaced with `VALUES { ... }`.
+```typescript
+new SparqlItemSelector({
+  query: 'SELECT DISTINCT ?class WHERE { ?s a ?class }',
+});
+```
+
+For dynamic queries that depend on the distribution, implement `ItemSelector` directly:
+
+```typescript
+const itemSelector: ItemSelector = {
+  select: (distribution) => {
+    const query = buildQuery(distribution);
+    return new SparqlItemSelector({ query }).select(distribution);
+  },
+};
+```
 
 ### Executor
 
+Generates RDF triples. `SparqlConstructExecutor` runs a SPARQL CONSTRUCT query with template substitution and variable bindings:
+
+```typescript
+const executor = new SparqlConstructExecutor({
+  query: 'CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }',
+});
+```
+
+### Writer
+
+Writes generated quads to a destination:
+
+- `SparqlUpdateWriter` — writes to a SPARQL endpoint via UPDATE queries
+- `FileWriter` — writes to local files
+
 ## Usage
 
 ```typescript
 import {
-  PipelineBuilder,
+  Pipeline,
+  Stage,
   SparqlConstructExecutor,
-  collect,
+  SparqlItemSelector,
+  SparqlUpdateWriter,
+  ManualDatasetSelection,
+  SparqlDistributionResolver,
 } from '@lde/pipeline';
 
-// Build a pipeline from steps
-const pipeline = new PipelineBuilder().addStep(myStep).build();
-
-// Or use the SPARQL executor directly
-const executor = new SparqlConstructExecutor({
-  query: 'CONSTRUCT { ?dataset ?p ?o } WHERE { ?s ?p ?o }',
+const pipeline = new Pipeline({
+  name: 'example',
+  datasetSelector: new ManualDatasetSelection([dataset]),
+  distributionResolver: new SparqlDistributionResolver(),
+  stages: [
+    new Stage({
+      name: 'per-class',
+      itemSelector: new SparqlItemSelector({
+        query: 'SELECT DISTINCT ?class WHERE { ?s a ?class }',
+      }),
+      executors: new SparqlConstructExecutor({
+        query:
+          'CONSTRUCT { ?class a <http://example.org/Class> } WHERE { ?s a ?class }',
+      }),
+    }),
+  ],
+  writer: new SparqlUpdateWriter({
+    endpoint: new URL('http://localhost:7200/repositories/lde/statements'),
+  }),
 });
-const result = await executor.execute(dataset);
+
+await pipeline.run();
 ```
 
 ## Validation

package/dist/pipeline.d.ts

@@ -1,4 +1,4 @@
-import type { Selector } from './selector.js';
+import type { DatasetSelector } from './selector.js';
 import { Stage } from './stage.js';
 import type { Writer } from './writer/writer.js';
 import { type DistributionResolver } from './distribution/resolver.js';
@@ -6,7 +6,7 @@ import type { StageOutputResolver } from './stageOutputResolver.js';
 import type { ProgressReporter } from './progressReporter.js';
 export interface PipelineOptions {
     name: string;
-    selector: Selector;
+    datasetSelector: DatasetSelector;
     stages: Stage[];
     writer: Writer;
     distributionResolver: DistributionResolver;

package/dist/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;gBAE9B,OAAO,EAAE,eAAe;IAe9B,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YAcZ,cAAc;YA2Bd,QAAQ;YAgCR,QAAQ;YAoDR,eAAe;YAoCd,SAAS;CAUzB"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,eAAe,CAAC;IACjC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;gBAE9B,OAAO,EAAE,eAAe;IAe9B,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YAcZ,cAAc;YA2Bd,QAAQ;YAgCR,QAAQ;YAoDR,eAAe;YAoCd,SAAS;CAUzB"}

package/dist/pipeline.js

@@ -16,10 +16,10 @@ export class Pipeline {
         this.options = options;
     }
     async run() {
-        const { selector, reporter, name } = this.options;
+        const { datasetSelector, reporter, name } = this.options;
         const start = Date.now();
         reporter?.pipelineStart(name);
-        const datasets = await selector.select();
+        const datasets = await datasetSelector.select();
         for await (const dataset of datasets) {
             await this.processDataset(dataset);
         }

package/dist/selector.d.ts

@@ -3,10 +3,10 @@ import { Client, Paginator } from '@lde/dataset-registry-client';
 /**
  * Select {@link Dataset}s for processing in a pipeline.
  */
-export interface Selector {
+export interface DatasetSelector {
     select(): Promise<Paginator<Dataset>>;
 }
-export declare class ManualDatasetSelection implements Selector {
+export declare class ManualDatasetSelection implements DatasetSelector {
     private readonly datasets;
     constructor(datasets: Dataset[]);
     select(): Promise<Paginator<Dataset>>;
@@ -26,7 +26,7 @@ export declare class ManualDatasetSelection implements Selector {
  * @param string options.query Optional custom SPARQL query to select datasets.
  * @param object options.criteria Optional search criteria to select datasets.
  */
-export declare class RegistrySelector implements Selector {
+export declare class RegistrySelector implements DatasetSelector {
     private readonly registry;
     private readonly query?;
     private readonly criteria?;

package/dist/selector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../src/selector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;CACvC;AAED,qBAAa,sBAAuB,YAAW,QAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,OAAO,EAAE;IAE1C,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;CAG5C;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;gBAEvB,EACV,QAAQ,EACR,KAAK,EACL,QAAQ,GACT,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB;IAMK,MAAM;CAOb"}
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../src/selector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;CACvC;AAED,qBAAa,sBAAuB,YAAW,eAAe;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,OAAO,EAAE;IAE1C,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;CAG5C;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,YAAW,eAAe;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;gBAEvB,EACV,QAAQ,EACR,KAAK,EACL,QAAQ,GACT,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB;IAMK,MAAM;CAOb"}

package/dist/sparql/index.d.ts

@@ -1,5 +1,5 @@
 export { SparqlConstructExecutor, NotSupported, readQueryFile, type ExecuteOptions, type Executor, type SparqlConstructExecutorOptions, type QuadStream, type VariableBindings, } from './executor.js';
-export { SparqlSelector, type SparqlSelectorOptions } from './selector.js';
+export { SparqlItemSelector, type SparqlItemSelectorOptions, } 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,YAAY,EACZ,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,8BAA8B,EACnC,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AACvB,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sparql/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,8BAA8B,EACnC,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/sparql/index.js

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

package/dist/sparql/selector.d.ts

@@ -1,31 +1,30 @@
+import type { Distribution } from '@lde/dataset';
 import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
-import type { StageSelector } from '../stage.js';
+import type { ItemSelector } from '../stage.js';
 import type { VariableBindings } from './executor.js';
-export interface SparqlSelectorOptions {
+export interface SparqlItemSelectorOptions {
     /** SELECT query projecting at least one named variable. A LIMIT in the query sets the default page size. */
     query: string;
-    /** SPARQL endpoint URL. */
-    endpoint: URL;
     /** Results per page. Overrides any LIMIT in the query. @default 10 */
     pageSize?: number;
     /** Custom fetcher instance. */
     fetcher?: SparqlEndpointFetcher;
 }
 /**
- * {@link StageSelector} that pages through SPARQL SELECT results,
+ * {@link ItemSelector} that pages through SPARQL SELECT results,
  * yielding all projected variable bindings (NamedNode values only) per row.
  *
+ * The endpoint URL comes from the {@link Distribution} passed to {@link select}.
  * Pagination is an internal detail — consumers iterate binding rows directly.
  * If the query contains a LIMIT, it is used as the default page size
  * (can be overridden by the `pageSize` option). Pagination continues
  * until a page returns fewer results than the page size.
  */
-export declare class SparqlSelector implements StageSelector {
+export declare class SparqlItemSelector implements ItemSelector {
     private readonly parsed;
-    private readonly endpoint;
     private readonly pageSize;
     private readonly fetcher;
-    constructor(options: SparqlSelectorOptions);
-    [Symbol.asyncIterator](): AsyncIterableIterator<VariableBindings>;
+    constructor(options: SparqlItemSelectorOptions);
+    select(distribution: Distribution): 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,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"}
+{"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,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAKtD,MAAM,WAAW,yBAAyB;IACxC,4GAA4G;IAC5G,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;gBAEpC,OAAO,EAAE,yBAAyB;IAkBvC,MAAM,CACX,YAAY,EAAE,YAAY,GACzB,qBAAqB,CAAC,gBAAgB,CAAC;CAmC3C"}

package/dist/sparql/selector.js

@@ -3,17 +3,17 @@ import { Generator, Parser, } from 'sparqljs';
 const parser = new Parser();
 const generator = new Generator();
 /**
- * {@link StageSelector} that pages through SPARQL SELECT results,
+ * {@link ItemSelector} that pages through SPARQL SELECT results,
  * yielding all projected variable bindings (NamedNode values only) per row.
  *
+ * The endpoint URL comes from the {@link Distribution} passed to {@link select}.
  * Pagination is an internal detail — consumers iterate binding rows directly.
  * If the query contains a LIMIT, it is used as the default page size
  * (can be overridden by the `pageSize` option). Pagination continues
  * until a page returns fewer results than the page size.
  */
-export class SparqlSelector {
+export class SparqlItemSelector {
     parsed;
-    endpoint;
     pageSize;
     fetcher;
     constructor(options) {
@@ -26,17 +26,17 @@ export class SparqlSelector {
             throw new Error('Query must project at least one named variable (SELECT * is not supported)');
         }
         this.parsed = parsed;
-        this.endpoint = options.endpoint;
         this.pageSize = options.pageSize ?? parsed.limit ?? 10;
         this.fetcher = options.fetcher ?? new SparqlEndpointFetcher();
     }
-    async *[Symbol.asyncIterator]() {
+    async *select(distribution) {
+        const endpoint = distribution.accessUrl;
         let offset = 0;
         while (true) {
             this.parsed.limit = this.pageSize;
             this.parsed.offset = offset;
             const paginatedQuery = generator.stringify(this.parsed);
-            const stream = (await this.fetcher.fetchBindings(this.endpoint.toString(), paginatedQuery));
+            const stream = (await this.fetcher.fetchBindings(endpoint.toString(), paginatedQuery));
             let pageSize = 0;
             for await (const record of stream) {
                 const row = Object.fromEntries(Object.entries(record).filter(([, term]) => term.termType === 'NamedNode'));

package/dist/stage.d.ts

@@ -2,12 +2,10 @@ import { Dataset, Distribution } from '@lde/dataset';
 import type { Executor, VariableBindings } from './sparql/executor.js';
 import { NotSupported } from './sparql/executor.js';
 import type { Writer } from './writer/writer.js';
-/** A selector, or a factory that receives the runtime distribution. */
-export type StageSelectorInput = StageSelector | ((distribution: Distribution) => StageSelector);
 export interface StageOptions {
     name: string;
     executors: Executor | Executor[];
-    selector?: StageSelectorInput;
+    itemSelector?: ItemSelector;
     /** Maximum number of bindings per executor call. @default 10 */
     batchSize?: number;
     /** Maximum concurrent in-flight executor batches. @default 10 */
@@ -22,7 +20,7 @@ export declare class Stage {
     readonly name: string;
     readonly stages: readonly Stage[];
     private readonly executors;
-    private readonly selectorInput?;
+    private readonly itemSelector?;
     private readonly batchSize;
     private readonly maxConcurrency;
     constructor(options: StageOptions);
@@ -30,7 +28,8 @@ export declare class Stage {
     private runWithSelector;
     private executeAll;
 }
-/** Stage-level selector that yields variable bindings for use in executor queries. Pagination is an implementation detail. */
-export interface StageSelector extends AsyncIterable<VariableBindings> {
+/** Selects items (as variable bindings) for executors to process. Pagination is an implementation detail. */
+export interface ItemSelector {
+    select(distribution: Distribution): 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,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGjD,uEAAuE;AACvE,MAAM,MAAM,kBAAkB,GAC1B,aAAa,GACb,CAAC,CAAC,YAAY,EAAE,YAAY,KAAK,aAAa,CAAC,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAAC;IACjC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1E;AAED,qBAAa,KAAK;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,OAAO,EAAE,YAAY;IAW3B,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;YAuBjB,eAAe;YA+Gf,UAAU;CAqBzB;AAUD,8HAA8H;AAE9H,MAAM,WAAW,aAAc,SAAQ,aAAa,CAAC,gBAAgB,CAAC;CAAG"}
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGjD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAAC;IACjC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1E;AAED,qBAAa,KAAK;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,OAAO,EAAE,YAAY;IAW3B,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;YAmBjB,eAAe;YA+Gf,UAAU;CAqBzB;AAUD,6GAA6G;AAC7G,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,YAAY,EAAE,YAAY,GAAG,aAAa,CAAC,gBAAgB,CAAC,CAAC;CACrE"}

package/dist/stage.js

@@ -5,7 +5,7 @@ export class Stage {
     name;
     stages;
     executors;
-    selectorInput;
+    itemSelector;
     batchSize;
     maxConcurrency;
     constructor(options) {
@@ -14,16 +14,13 @@ export class Stage {
         this.executors = Array.isArray(options.executors)
             ? options.executors
             : [options.executors];
-        this.selectorInput = options.selector;
+        this.itemSelector = options.itemSelector;
         this.batchSize = options.batchSize ?? 10;
         this.maxConcurrency = options.maxConcurrency ?? 10;
     }
     async run(dataset, distribution, writer, options) {
-        if (this.selectorInput) {
-            const selector = typeof this.selectorInput === 'function'
-                ? this.selectorInput(distribution)
-                : this.selectorInput;
-            return this.runWithSelector(selector, dataset, distribution, writer, options);
+        if (this.itemSelector) {
+            return this.runWithSelector(this.itemSelector.select(distribution), dataset, distribution, writer, options);
         }
         const streams = await this.executeAll(dataset, distribution);
         if (streams instanceof NotSupported) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/pipeline",
-  "version": "0.6.26",
+  "version": "0.6.28",
   "repository": {
     "url": "https://github.com/ldengine/lde",
     "directory": "packages/pipeline"