@lde/pipeline 0.28.13 → 0.29.0

package/README.md

@@ -74,7 +74,10 @@ Selects resources from the distribution and fans out executor calls per batch of
 
 ```typescript
 interface ItemSelector {
-  select(distribution: Distribution, batchSize?: number): AsyncIterable<VariableBindings>;
+  select(
+    distribution: Distribution,
+    batchSize?: number,
+  ): AsyncIterable<VariableBindings>;
 }
 ```
 
@@ -86,6 +89,25 @@ new SparqlItemSelector({
 });
 ```
 
+#### Capping total results with `maxResults`
+
+By default, `SparqlItemSelector` paginates through **all** matching rows: any `LIMIT` clause in the query is interpreted as the page size, then it walks pages with `OFFSET` until the source is exhausted. To cap the total bindings yielded across all pages — for sampling, testing, prototyping, or just safety — set `maxResults`:
+
+```typescript
+new SparqlItemSelector({
+  query: 'SELECT DISTINCT ?s WHERE { ?s a <http://example.com/Class> }',
+  maxResults: 50,
+});
+```
+
+When `maxResults` is set:
+
+- Pagination stops as soon as `maxResults` bindings have been yielded — no wasted page request after the cap is hit.
+- The last (partial) page's `LIMIT` is shrunk to the remaining cap so the endpoint doesn't over-fetch on the remainder (e.g. with `maxResults: 85` and `pageSize: 10`, the 9th page request is `LIMIT 5`, not `LIMIT 10`).
+- The first page uses the configured page size as-is; `maxResults` and page size stay orthogonal. If `maxResults < pageSize`, the first page may return a few rows that aren't yielded.
+- `maxResults: 0` is a valid no-op; the selector yields nothing without issuing any SPARQL request.
+- `maxResults` is independent of any `LIMIT` clause in the query, which still controls page size when the cap is larger than one page.
+
 For dynamic queries that depend on the distribution, implement `ItemSelector` directly:
 
 ```typescript
@@ -218,6 +240,10 @@ new Stage({
 
 `Validator` is an interface, so you can implement your own validation strategy. See [@lde/pipeline-shacl-validator](../pipeline-shacl-validator) for the SHACL implementation.
 
+#### Per-dataset reporting
+
+After all stages for a dataset have run, the pipeline calls `validator.report(dataset)` once for each distinct validator attached to any stage and emits a `datasetValidated(dataset, report)` event on the reporter. The call happens **regardless of whether any stage actually invoked `validate()`** — for SHACL that means a dataset whose stages produced no input typically reports `quadsValidated: 0` and `conforms: true` (the SHACL vacuous-truth default). Consumers that want to distinguish ‘not tested’ from ‘tested and passed’ can read `quadsValidated`.
+
 ### Writer
 
 Writes generated quads to a destination:

package/dist/pipeline.d.ts

@@ -35,6 +35,8 @@ export declare class Pipeline {
     constructor(options: PipelineOptions);
     run(): Promise<void>;
     private processDataset;
+    private reportValidators;
+    private collectStages;
     /**
      * Run a stage with reporting and return whether it was supported.
      * Returns `true` if the stage produced results, `false` if NotSupported.

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,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,4BAA4B,CAAC;AAQpC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAE/B,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,aAAa,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,eAAe,CAAC;IACjC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,EAAE;QACT,mBAAmB,EAAE,mBAAmB,CAAC;QACzC,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAgFD,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAuB;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAmB;gBAEjC,OAAO,EAAE,eAAe;IAgC9B,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YAoBZ,cAAc;IAkE5B;;;OAGG;YACW,QAAQ;IA6CtB,2EAA2E;YAC7D,eAAe;YAcf,QAAQ;YAmDP,SAAS;CAczB"}
+{"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,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,4BAA4B,CAAC;AAQpC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAG/B,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,aAAa,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,eAAe,CAAC;IACjC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,EAAE;QACT,mBAAmB,EAAE,mBAAmB,CAAC;QACzC,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAgFD,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAuB;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAmB;gBAEjC,OAAO,EAAE,eAAe;IAgC9B,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YAoBZ,cAAc;YAmEd,gBAAgB;IAW9B,OAAO,CAAE,aAAa;IAOtB;;;OAGG;YACW,QAAQ;IAwCtB,2EAA2E;YAC7D,eAAe;YAcf,QAAQ;YAmDP,SAAS;CAczB"}

package/dist/pipeline.js

@@ -163,12 +163,31 @@ export class Pipeline {
             await this.distributionResolver.cleanup?.();
         }
         await this.writer.flush?.(dataset);
+        await this.reportValidators(dataset);
         const datasetMemory = process.memoryUsage();
         this.reporter?.datasetComplete?.(dataset, {
             memoryUsageBytes: datasetMemory.rss,
             heapUsedBytes: datasetMemory.heapUsed,
         });
     }
+    async reportValidators(dataset) {
+        const validators = new Set();
+        for (const stage of this.collectStages(this.stages)) {
+            if (stage.validator)
+                validators.add(stage.validator);
+        }
+        for (const validator of validators) {
+            const report = await validator.report(dataset);
+            this.reporter?.datasetValidated?.(dataset, report);
+        }
+    }
+    *collectStages(stages) {
+        for (const stage of stages) {
+            yield stage;
+            if (stage.stages.length > 0)
+                yield* this.collectStages(stage.stages);
+        }
+    }
     /**
      * Run a stage with reporting and return whether it was supported.
      * Returns `true` if the stage produced results, `false` if NotSupported.
@@ -200,10 +219,6 @@ export class Pipeline {
             quadsGenerated,
             duration: Date.now() - stageStart,
         });
-        if (stage.validator) {
-            const report = await stage.validator.report(dataset);
-            this.reporter?.stageValidated?.(stage.name, report);
-        }
         return true;
     }
     /** Run a stage in chained mode, throwing if the stage is not supported. */

package/dist/progressReporter.d.ts

@@ -32,9 +32,17 @@ export interface ProgressReporter {
         duration: number;
     }): void;
     stageFailed?(stage: string, error: Error): void;
-    /** Called after a stage completes if it has a validator. */
-    stageValidated?(stage: string, report: ValidationReport): void;
     stageSkipped?(stage: string, reason: string): void;
+    /**
+     * Called once per (dataset, validator) pair after all stages for a dataset
+     * have run. Fires regardless of whether any stage actually invoked
+     * `validate()` — the report reflects the validator’s accumulated state.
+     * When no stage produced data, the report typically carries
+     * `quadsValidated: 0` and `conforms: true` (the SHACL vacuous-truth
+     * default); consumers that want to distinguish ‘not tested’ from ‘tested
+     * and passed’ can read `quadsValidated`.
+     */
+    datasetValidated?(dataset: Dataset, report: ValidationReport): void;
     datasetComplete?(dataset: Dataset, result: {
         memoryUsageBytes: number;
         heapUsedBytes: number;

package/dist/progressReporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"progressReporter.d.ts","sourceRoot":"","sources":["../src/progressReporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,YAAY,CAAC;IAC3B,IAAI,EAAE,QAAQ,GAAG,WAAW,GAAG,eAAe,CAAC;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,gBAAgB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACzD,YAAY,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACtC,8DAA8D;IAC9D,kBAAkB,CAAC,CAAC,MAAM,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAC9D,6CAA6C;IAC7C,aAAa,CAAC,IAAI,IAAI,CAAC;IACvB,kDAAkD;IAClD,YAAY,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/D,oBAAoB,CAAC,CACnB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,YAAY,EAC1B,YAAY,CAAC,EAAE,YAAY,EAC3B,cAAc,CAAC,EAAE,MAAM,EACvB,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI,CAAC;IACR,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,aAAa,CAAC,CAAC,MAAM,EAAE;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI,CAAC;IACT,aAAa,CAAC,CACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE;QACN,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;KAClB,GACA,IAAI,CAAC;IACR,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAChD,4DAA4D;IAC5D,cAAc,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC/D,YAAY,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD,eAAe,CAAC,CACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAC1D,IAAI,CAAC;IACR,cAAc,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,gBAAgB,CAAC,CAAC,MAAM,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI,CAAC;CACV"}
+{"version":3,"file":"progressReporter.d.ts","sourceRoot":"","sources":["../src/progressReporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,YAAY,CAAC;IAC3B,IAAI,EAAE,QAAQ,GAAG,WAAW,GAAG,eAAe,CAAC;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,gBAAgB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACzD,YAAY,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACtC,8DAA8D;IAC9D,kBAAkB,CAAC,CAAC,MAAM,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAC9D,6CAA6C;IAC7C,aAAa,CAAC,IAAI,IAAI,CAAC;IACvB,kDAAkD;IAClD,YAAY,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/D,oBAAoB,CAAC,CACnB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,YAAY,EAC1B,YAAY,CAAC,EAAE,YAAY,EAC3B,cAAc,CAAC,EAAE,MAAM,EACvB,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI,CAAC;IACR,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,aAAa,CAAC,CAAC,MAAM,EAAE;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI,CAAC;IACT,aAAa,CAAC,CACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE;QACN,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;KAClB,GACA,IAAI,CAAC;IACR,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAChD,YAAY,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACpE,eAAe,CAAC,CACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAC1D,IAAI,CAAC;IACR,cAAc,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,gBAAgB,CAAC,CAAC,MAAM,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI,CAAC;CACV"}

package/dist/sparql/selector.d.ts

@@ -8,8 +8,19 @@ export interface SparqlItemSelectorOptions {
      *
      * A `LIMIT` clause in the query overrides the stage's `batchSize` as the
      * page size — use this when the SPARQL endpoint enforces a result limit.
+     * It does **not** cap the total number of bindings the selector yields;
+     * pagination continues with `OFFSET` until the source is exhausted. Use
+     * {@link maxResults} to cap the total.
      */
     query: string;
+    /**
+     * Maximum number of bindings the selector yields across all pages.
+     * Use this for sampling — “give me at most N items, don’t walk the full
+     * source”. Independent of {@link query}’s `LIMIT`, which controls page
+     * size. Pagination stops as soon as `maxResults` bindings have been
+     * yielded.
+     */
+    maxResults?: number;
     /** Custom fetcher instance. */
     fetcher?: SparqlEndpointFetcher;
 }
@@ -24,10 +35,17 @@ export interface SparqlItemSelectorOptions {
  * 1. A `LIMIT` clause in the selector query (for endpoints with hard result limits)
  * 2. The stage's {@link StageOptions.batchSize} (passed via {@link select})
  * 3. A default of 10
+ *
+ * {@link SparqlItemSelectorOptions.maxResults} is independent of page size:
+ * it caps the *total* bindings yielded across pages without changing how
+ * the first page is requested. The last (partial) page’s `LIMIT` is
+ * shrunk to whatever’s left of the cap so the endpoint doesn’t over-fetch
+ * on the remainder.
  */
 export declare class SparqlItemSelector implements ItemSelector {
     private readonly parsed;
     private readonly queryLimit?;
+    private readonly maxResults?;
     private readonly fetcher;
     constructor(options: SparqlItemSelectorOptions);
     select(distribution: Distribution, batchSize?: number): AsyncIterableIterator<VariableBindings>;

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,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAMtD,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;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,OAAO,CAAwB;gBAEpC,OAAO,EAAE,yBAAyB;IAkBvC,MAAM,CACX,YAAY,EAAE,YAAY,EAC1B,SAAS,CAAC,EAAE,MAAM,GACjB,qBAAqB,CAAC,gBAAgB,CAAC;CAuC3C"}
+{"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;AAMtD,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,OAAO,CAAwB;gBAEpC,OAAO,EAAE,yBAAyB;IAmBvC,MAAM,CACX,YAAY,EAAE,YAAY,EAC1B,SAAS,CAAC,EAAE,MAAM,GACjB,qBAAqB,CAAC,gBAAgB,CAAC;CAyD3C"}

package/dist/sparql/selector.js

@@ -16,10 +16,17 @@ const F = new AstFactory();
  * 1. A `LIMIT` clause in the selector query (for endpoints with hard result limits)
  * 2. The stage's {@link StageOptions.batchSize} (passed via {@link select})
  * 3. A default of 10
+ *
+ * {@link SparqlItemSelectorOptions.maxResults} is independent of page size:
+ * it caps the *total* bindings yielded across pages without changing how
+ * the first page is requested. The last (partial) page’s `LIMIT` is
+ * shrunk to whatever’s left of the cap so the endpoint doesn’t over-fetch
+ * on the remainder.
  */
 export class SparqlItemSelector {
     parsed;
     queryLimit;
+    maxResults;
     fetcher;
     constructor(options) {
         const parsed = parser.parse(options.query);
@@ -32,13 +39,24 @@ export class SparqlItemSelector {
         }
         this.parsed = parsed;
         this.queryLimit = this.parsed.solutionModifiers.limitOffset?.limit;
+        this.maxResults = options.maxResults;
         this.fetcher = options.fetcher ?? new SparqlEndpointFetcher();
     }
     async *select(distribution, batchSize) {
-        const effectivePageSize = this.queryLimit ?? batchSize ?? 10;
+        if (this.maxResults === 0)
+            return;
+        const basePageSize = this.queryLimit ?? batchSize ?? 10;
         const endpoint = distribution.accessUrl;
         let offset = 0;
+        let totalYielded = 0;
         while (true) {
+            const remaining = this.maxResults !== undefined
+                ? this.maxResults - totalYielded
+                : Infinity;
+            // The first page uses the configured page size as-is — keeps page-size
+            // and total-cap orthogonal. Subsequent pages clamp to `remaining` so
+            // the last (partial) page doesn’t over-fetch.
+            const effectivePageSize = offset === 0 ? basePageSize : Math.min(basePageSize, remaining);
             this.parsed.solutionModifiers.limitOffset = F.solutionModifierLimitOffset(effectivePageSize, offset, F.gen());
             const paginatedQuery = generator.generate(this.parsed);
             const stream = (await this.fetcher.fetchBindings(endpoint.toString(), paginatedQuery));
@@ -48,6 +66,11 @@ export class SparqlItemSelector {
                 if (Object.keys(row).length > 0) {
                     yield row;
                     count++;
+                    totalYielded++;
+                    if (this.maxResults !== undefined &&
+                        totalYielded >= this.maxResults) {
+                        return;
+                    }
                 }
             }
             if (count === 0 || count < effectivePageSize) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/pipeline",
-  "version": "0.28.13",
+  "version": "0.29.0",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
     "directory": "packages/pipeline"
@@ -30,12 +30,12 @@
     "@lde/sparql-importer": "0.6.1",
     "@lde/sparql-server": "0.4.11",
     "@rdfjs/types": "^2.0.1",
-    "@traqula/generator-sparql-1-1": "^1.0.7",
-    "@traqula/parser-sparql-1-1": "^1.0.4",
-    "@traqula/rules-sparql-1-1": "^1.0.4",
+    "@traqula/generator-sparql-1-1": "^1.1.1",
+    "@traqula/parser-sparql-1-1": "^1.1.1",
+    "@traqula/rules-sparql-1-1": "^1.1.0",
     "fetch-sparql-endpoint": "^7.1.0",
     "filenamify-url": "^4.0.0",
-    "is-network-error": "^1.3.1",
+    "is-network-error": "^1.3.2",
     "n3": "^2.0.1",
     "p-retry": "^8.0.0",
     "rdf-string": "^2.0.1",