@lde/pipeline-void 0.28.4 → 0.28.5

package/README.md

@@ -10,14 +10,16 @@ Returns all VoID stages in their recommended execution order. The ordering is op
 
 Accepts an optional `VoidStagesOptions` object:
 
-| Option           | Default | Description                                                           |
-| ---------------- | ------- | --------------------------------------------------------------------- |
-| `timeout`        | 60 000  | SPARQL query timeout in milliseconds                                  |
-| `batchSize`      | 10      | Maximum class bindings per executor call (per-class stages only)      |
-| `maxConcurrency` | 10      | Maximum concurrent in-flight executor batches (per-class stages only) |
-| `perClass`       | —       | Override per-class iteration for all five per-class stages            |
-| `uriSpaces`      | —       | When provided, includes the object URI space stage                    |
-| `vocabularies`   | —       | Additional vocabulary namespace URIs to detect beyond the built-in defaults |
+| Option           | Default | Description                                                                                                     |
+| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
+| `batchSize`      | 10      | Maximum class bindings per executor call (per-class stages only)                                                |
+| `maxConcurrency` | 10      | Maximum concurrent in-flight executor batches (per-class stages only)                                           |
+| `perClass`       | —       | Override per-class iteration for all five per-class stages                                                      |
+| `uriSpaces`      | —       | When provided, includes the object URI space stage                                                              |
+| `vocabularies`   | —       | Additional vocabulary namespace URIs to detect beyond the built-in defaults                                     |
+| `transforms`     | —       | Transforms to attach to bundled stages, keyed by `VOID_STAGE_NAMES` (see [Stage transforms](#stage-transforms)) |
+
+Per-request timeouts are configured at the `Pipeline` level via `PipelineOptions.timeout`, not per VoID stage.
 
 ```typescript
 import { voidStages } from '@lde/pipeline-void';
@@ -37,7 +39,7 @@ await new Pipeline({
 
 ### Individual stage factories
 
-Global and domain-specific factories accept `VoidStageOptions` (`timeout`) and return `Promise<Stage>`. Per-class factories accept `PerClassVoidStageOptions` (`timeout`, `batchSize`, `maxConcurrency`, `perClass`) — they default `perClass` to `true`; set it to `false` to run them as monolithic queries instead.
+Global and domain-specific factories accept `VoidStageOptions` (`transform`) and return `Promise<Stage>`. Per-class factories accept `PerClassVoidStageOptions` (`transform`, `batchSize`, `maxConcurrency`, `perClass`) — they default `perClass` to `true`; set it to `false` to run them as monolithic queries instead.
 
 #### Global stages (one CONSTRUCT query per dataset):
 
@@ -65,12 +67,40 @@ Global and domain-specific factories accept `VoidStageOptions` (`timeout`) and r
 
 #### Domain-specific stages:
 
-| Factory                  | Description                                                                                                                       |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| Factory                  | Description                                                                                                                                                                                                                       |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `detectVocabularies()`   | [`entity-properties.rq`](queries/entity-properties.rq) — Entity properties with automatic `void:vocabulary` detection. Accepts `DetectVocabulariesOptions` with an optional `vocabularies` array to extend the built-in defaults. |
-| `uriSpaces(uriSpaceMap)` | [`object-uri-space.rq`](queries/object-uri-space.rq) — Object URI namespace linksets, aggregated against a provided URI space map |
+| `uriSpaces(uriSpaceMap)` | [`object-uri-space.rq`](queries/object-uri-space.rq) — Object URI namespace linksets, aggregated against a provided URI space map                                                                                                 |
+
+## Stage transforms
+
+A VoID stage decorates its executor’s output with a `QuadTransform<ExecutorContext>` attached as data (see [@lde/pipeline](../pipeline)’s extension model and [ADR 2](../../docs/decisions/0002-unify-pipeline-extension-on-quad-transforms.md)). It runs once per executor call and may fire its own SPARQL queries against the `distribution` in scope — so write it to accept being called more than once: a global stage calls it once over the complete output, a per-class stage with batching enabled once per batch (one class at `batchSize: 1`).
+
+Two transform factories are built in:
 
-## Executor decorators
+- `withVocabularies(vocabularies?)` — passes through all quads and appends `void:vocabulary` triples for detected vocabulary namespace prefixes in `void:property` quads. The built-in defaults are exported as `defaultVocabularies` (sourced from `@zazuko/prefixes`); `detectVocabularies()` attaches it to the `entity-properties.rq` stage.
+- `withUriSpaces(uriSpaceMap)` — consumes `void:Linkset` quads, matches each `void:objectsTarget` against the configured URI space prefixes using `startsWith`, and aggregates triple counts per matched space. Emits `void:objectsTarget` pointing to the target dataset IRI (taken from the metadata quad subjects), not the raw prefix; unmatched linksets are discarded. `uriSpaces(uriSpaceMap)` attaches it to the `object-uri-space.rq` stage.
 
-- `VocabularyExecutor` — Wraps an executor; detects known vocabulary namespace prefixes in `void:property` quads and appends `void:vocabulary` triples. The built-in defaults are exported as `defaultVocabularies` (sourced from `@zazuko/prefixes`).
-- `UriSpaceExecutor` — Wraps an executor; consumes `void:Linkset` quads, matches each `void:objectsTarget` against configured URI space prefixes using `startsWith`, and aggregates triple counts per matched space. Emits `void:objectsTarget` pointing to the target dataset IRI (taken from the metadata quad subjects), not the raw prefix. Unmatched linksets are discarded.
+### Attaching your own transform
+
+Pass a `transform` to an individual factory, or route transforms through `voidStages` with the `transforms` map keyed by `VOID_STAGE_NAMES` — so you can decorate a stage you never construct. Where a stage already carries a built-in transform, your transform composes after it. An invalid stage name is a compile error.
+
+```typescript
+import { voidStages, VOID_STAGE_NAMES } from '@lde/pipeline-void';
+import type { ExecutorContext, QuadTransform } from '@lde/pipeline-void';
+
+const sampleSubjects: QuadTransform<ExecutorContext> = async function* (
+  quads,
+  { dataset, distribution },
+) {
+  yield* quads; // pass the stage’s subsets through unchanged …
+  // … then fire a sample SELECT against `distribution` and append measurements.
+};
+
+const stages = await voidStages({
+  batchSize: 1,
+  transforms: {
+    [VOID_STAGE_NAMES.subjectUriSpace]: sampleSubjects,
+  },
+});
+```

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { Stage, NotSupported } from '@lde/pipeline';
+export type { AttachedExecutor, ExecutorContext, QuadTransform, } from '@lde/pipeline';
 export * from './stage.js';
-export * from './vocabularyAnalyzer.js';
-export * from './uriSpaceExecutor.js';
+export * from './vocabularyTransform.js';
+export * from './uriSpaceTransform.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACpD,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
 export { Stage, NotSupported } from '@lde/pipeline';
 export * from './stage.js';
-export * from './vocabularyAnalyzer.js';
-export * from './uriSpaceExecutor.js';
+export * from './vocabularyTransform.js';
+export * from './uriSpaceTransform.js';

package/dist/stage.d.ts

@@ -1,5 +1,34 @@
-import { Stage } from '@lde/pipeline';
+import { Stage, type ExecutorContext, type QuadTransform } from '@lde/pipeline';
 import type { Quad } from '@rdfjs/types';
+/**
+ * Stable names for every VoID stage, equal to the underlying query filename.
+ *
+ * Consumers reference these constants – e.g. when routing a transform through
+ * {@link VoidStagesOptions.transforms} – instead of hard-coding `.rq`
+ * filenames, so internal query names never leak into consumer code.
+ */
+export declare const VOID_STAGE_NAMES: {
+    readonly subjects: "subjects.rq";
+    readonly properties: "properties.rq";
+    readonly objectLiterals: "object-literals.rq";
+    readonly objectUris: "object-uris.rq";
+    readonly datatypes: "datatypes.rq";
+    readonly triples: "triples.rq";
+    readonly classPartitions: "class-partition.rq";
+    readonly classPropertySubjects: "class-properties-subjects.rq";
+    readonly classPropertyObjects: "class-properties-objects.rq";
+    readonly perClassDatatypes: "class-property-datatypes.rq";
+    readonly perClassObjectClasses: "class-property-object-classes.rq";
+    readonly perClassLanguages: "class-property-languages.rq";
+    readonly licenses: "licenses.rq";
+    readonly vocabularies: "entity-properties.rq";
+    readonly subjectUriSpace: "subject-uri-space.rq";
+    readonly objectUriSpace: "object-uri-space.rq";
+};
+/** The name of a VoID stage. @see VOID_STAGE_NAMES */
+export type VoidStageName = (typeof VOID_STAGE_NAMES)[keyof typeof VOID_STAGE_NAMES];
+/** A transform, or transforms, decorating a VoID stage's executor output. */
+export type VoidStageTransform = QuadTransform<ExecutorContext> | QuadTransform<ExecutorContext>[];
 /**
  * Options for configuring VoID stage execution.
  *
@@ -9,6 +38,14 @@ import type { Quad } from '@rdfjs/types';
  * extend it as more knobs are added.
  */
 export interface VoidStageOptions {
+    /**
+     * Transform(s) decorating this stage's executor output before the stage
+     * merges executors. For a global stage the transform sees the executor's
+     * complete output; for a per-class stage it sees one batch – one class at
+     * `batchSize: 1`. Built-in transforms (e.g. {@link uriSpaces}) compose
+     * with these, built-in first.
+     */
+    transform?: VoidStageTransform;
 }
 /**
  * Options for per-class VoID stages that iterate over classes.
@@ -26,12 +63,25 @@ export interface PerClassVoidStageOptions extends VoidStageOptions {
 }
 /**
  * Options for the {@link voidStages} convenience function.
+ *
+ * The single-stage `transform` seam is intentionally absent here: a bundle
+ * spans many stages, so transforms are routed per stage via
+ * {@link VoidStagesOptions.transforms}.
  */
-export interface VoidStagesOptions extends PerClassVoidStageOptions {
+export interface VoidStagesOptions extends Omit<PerClassVoidStageOptions, 'transform'> {
     /** When provided, includes the object URI space stage using this map. */
     uriSpaces?: ReadonlyMap<string, readonly Quad[]>;
     /** Additional vocabulary namespace URIs to detect beyond the built-in defaults. */
     vocabularies?: readonly string[];
+    /**
+     * Transforms to attach to bundled stages, keyed by {@link VOID_STAGE_NAMES}.
+     *
+     * Each transform decorates the executor of the named stage – so a consumer
+     * can wrap a stage it never constructs. Where a stage already carries a
+     * built-in transform ({@link uriSpaces}, {@link detectVocabularies}), the
+     * consumer transform composes after it. An invalid key is a compile error.
+     */
+    transforms?: Partial<Record<VoidStageName, VoidStageTransform>>;
 }
 export declare function subjectUriSpaces(options?: VoidStageOptions): Promise<Stage>;
 export declare function classPartitions(options?: VoidStageOptions): Promise<Stage>;

package/dist/stage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EAMN,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAezC;;;;;;;GAOG;AAEH,MAAM,WAAW,gBAAgB;CAAG;AAEpC;;;;;GAKG;AACH,MAAM,WAAW,wBAAyB,SAAQ,gBAAgB;IAChE,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,wBAAwB;IACjE,yEAAyE;IACzE,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC;IACjD,mFAAmF;IACnF,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AA0DD,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CAE3E;AAED,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CAE1E;AAED,wBAAgB,mBAAmB,CACjC,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,KAAK,CAAC,CAEhB;AAED,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CAE1E;AAED,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CAE1E;AAED,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CAExE;AAED,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CAEvE;AAED,wBAAgB,qBAAqB,CACnC,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,KAAK,CAAC,CAKhB;AAED,wBAAgB,oBAAoB,CAClC,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,KAAK,CAAC,CAKhB;AAED,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CAEzE;AAED,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CAEzE;AAID,wBAAgB,qBAAqB,CACnC,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,KAAK,CAAC,CAKhB;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,KAAK,CAAC,CAKhB;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,KAAK,CAAC,CAKhB;AAID,wBAAgB,SAAS,CACvB,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC,EACjD,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,KAAK,CAAC,CAMhB;AAED,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IACjE,mFAAmF;IACnF,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,wBAAgB,kBAAkB,CAChC,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,KAAK,CAAC,CAWhB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,KAAK,EAAE,CAAC,CAgClB"}
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":"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"}

package/dist/stage.js

@@ -2,26 +2,54 @@ import { Stage, SparqlConstructExecutor, SparqlItemSelector, readQueryFile, } fr
 import { assertSafeIri } from '@lde/dataset';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { VocabularyExecutor, defaultVocabularies, } from './vocabularyAnalyzer.js';
-import { UriSpaceExecutor } from './uriSpaceExecutor.js';
+import { withVocabularies, defaultVocabularies, } from './vocabularyTransform.js';
+import { withUriSpaces } from './uriSpaceTransform.js';
 const queriesDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'queries');
+/**
+ * Stable names for every VoID stage, equal to the underlying query filename.
+ *
+ * Consumers reference these constants – e.g. when routing a transform through
+ * {@link VoidStagesOptions.transforms} – instead of hard-coding `.rq`
+ * filenames, so internal query names never leak into consumer code.
+ */
+export const VOID_STAGE_NAMES = {
+    subjects: 'subjects.rq',
+    properties: 'properties.rq',
+    objectLiterals: 'object-literals.rq',
+    objectUris: 'object-uris.rq',
+    datatypes: 'datatypes.rq',
+    triples: 'triples.rq',
+    classPartitions: 'class-partition.rq',
+    classPropertySubjects: 'class-properties-subjects.rq',
+    classPropertyObjects: 'class-properties-objects.rq',
+    perClassDatatypes: 'class-property-datatypes.rq',
+    perClassObjectClasses: 'class-property-object-classes.rq',
+    perClassLanguages: 'class-property-languages.rq',
+    licenses: 'licenses.rq',
+    vocabularies: 'entity-properties.rq',
+    subjectUriSpace: 'subject-uri-space.rq',
+    objectUriSpace: 'object-uri-space.rq',
+};
 async function createVoidStage(filename, options) {
     const query = await readQueryFile(resolve(queriesDir, filename));
-    const executor = options?.executor?.(query) ?? new SparqlConstructExecutor({ query });
-    if (options?.perClass) {
-        return new Stage({
-            name: filename,
-            itemSelector: classSelector(),
-            executors: executor,
-            batchSize: options?.batchSize,
-            maxConcurrency: options?.maxConcurrency,
-        });
-    }
+    const executor = {
+        executor: new SparqlConstructExecutor({ query }),
+        transform: options?.transform,
+    };
     return new Stage({
         name: filename,
         executors: executor,
+        itemSelector: options?.perClass ? classSelector() : undefined,
+        batchSize: options?.batchSize,
+        maxConcurrency: options?.maxConcurrency,
     });
 }
+/** Normalise a {@link VoidStageTransform} to an array. */
+function asTransforms(transform) {
+    if (transform === undefined)
+        return [];
+    return Array.isArray(transform) ? [...transform] : [transform];
+}
 function classSelector() {
     return {
         // Forward `options` so the Pipeline’s per-dataset TimeoutPolicy
@@ -48,76 +76,79 @@ function classSelector() {
 }
 // Global stages
 export function subjectUriSpaces(options) {
-    return createVoidStage('subject-uri-space.rq', options);
+    return createVoidStage(VOID_STAGE_NAMES.subjectUriSpace, options);
 }
 export function classPartitions(options) {
-    return createVoidStage('class-partition.rq', options);
+    return createVoidStage(VOID_STAGE_NAMES.classPartitions, options);
 }
 export function countObjectLiterals(options) {
-    return createVoidStage('object-literals.rq', options);
+    return createVoidStage(VOID_STAGE_NAMES.objectLiterals, options);
 }
 export function countObjectUris(options) {
-    return createVoidStage('object-uris.rq', options);
+    return createVoidStage(VOID_STAGE_NAMES.objectUris, options);
 }
 export function countProperties(options) {
-    return createVoidStage('properties.rq', options);
+    return createVoidStage(VOID_STAGE_NAMES.properties, options);
 }
 export function countSubjects(options) {
-    return createVoidStage('subjects.rq', options);
+    return createVoidStage(VOID_STAGE_NAMES.subjects, options);
 }
 export function countTriples(options) {
-    return createVoidStage('triples.rq', options);
+    return createVoidStage(VOID_STAGE_NAMES.triples, options);
 }
 export function classPropertySubjects(options) {
-    return createVoidStage('class-properties-subjects.rq', {
+    return createVoidStage(VOID_STAGE_NAMES.classPropertySubjects, {
         ...options,
         perClass: options?.perClass ?? true,
     });
 }
 export function classPropertyObjects(options) {
-    return createVoidStage('class-properties-objects.rq', {
+    return createVoidStage(VOID_STAGE_NAMES.classPropertyObjects, {
         ...options,
         perClass: options?.perClass ?? true,
     });
 }
 export function countDatatypes(options) {
-    return createVoidStage('datatypes.rq', options);
+    return createVoidStage(VOID_STAGE_NAMES.datatypes, options);
 }
 export function detectLicenses(options) {
-    return createVoidStage('licenses.rq', options);
+    return createVoidStage(VOID_STAGE_NAMES.licenses, options);
 }
 // Per-class stages
 export function perClassObjectClasses(options) {
-    return createVoidStage('class-property-object-classes.rq', {
+    return createVoidStage(VOID_STAGE_NAMES.perClassObjectClasses, {
         ...options,
         perClass: options?.perClass ?? true,
     });
 }
 export function perClassDatatypes(options) {
-    return createVoidStage('class-property-datatypes.rq', {
+    return createVoidStage(VOID_STAGE_NAMES.perClassDatatypes, {
         ...options,
         perClass: options?.perClass ?? true,
     });
 }
 export function perClassLanguages(options) {
-    return createVoidStage('class-property-languages.rq', {
+    return createVoidStage(VOID_STAGE_NAMES.perClassLanguages, {
         ...options,
         perClass: options?.perClass ?? true,
     });
 }
-// Domain-specific executor stages
+// Stages with a built-in transform
 export function uriSpaces(uriSpaceMap, options) {
-    return createVoidStage('object-uri-space.rq', {
-        ...options,
-        executor: (query) => new UriSpaceExecutor(new SparqlConstructExecutor({ query }), uriSpaceMap),
+    return createVoidStage(VOID_STAGE_NAMES.objectUriSpace, {
+        transform: [
+            withUriSpaces(uriSpaceMap),
+            ...asTransforms(options?.transform),
+        ],
     });
 }
 export function detectVocabularies(options) {
-    return createVoidStage('entity-properties.rq', {
-        ...options,
-        executor: (query) => new VocabularyExecutor(new SparqlConstructExecutor({ query }), options?.vocabularies
-            ? [...defaultVocabularies, ...options.vocabularies]
-            : undefined),
+    const { vocabularies, transform } = options ?? {};
+    const allVocabularies = vocabularies
+        ? [...defaultVocabularies, ...vocabularies]
+        : undefined;
+    return createVoidStage(VOID_STAGE_NAMES.vocabularies, {
+        transform: [withVocabularies(allVocabularies), ...asTransforms(transform)],
     });
 }
 /**
@@ -129,27 +160,37 @@ export function detectVocabularies(options) {
  * when the cache is cold.
  */
 export async function voidStages(options) {
-    const { uriSpaces: uriSpaceMap, vocabularies, ...stageOptions } = options ?? {};
+    const { uriSpaces: uriSpaceMap, vocabularies, transforms, ...stageOptions } = options ?? {};
+    // Merge the shared per-stage options with the transform routed to a stage.
+    const withTransform = (name) => ({
+        ...stageOptions,
+        transform: transforms?.[name],
+    });
     return Promise.all([
         // Global counting stages.
-        countSubjects(stageOptions),
-        countProperties(stageOptions),
-        countObjectLiterals(stageOptions),
-        countObjectUris(stageOptions),
-        countDatatypes(stageOptions),
-        countTriples(stageOptions),
+        countSubjects(withTransform(VOID_STAGE_NAMES.subjects)),
+        countProperties(withTransform(VOID_STAGE_NAMES.properties)),
+        countObjectLiterals(withTransform(VOID_STAGE_NAMES.objectLiterals)),
+        countObjectUris(withTransform(VOID_STAGE_NAMES.objectUris)),
+        countDatatypes(withTransform(VOID_STAGE_NAMES.datatypes)),
+        countTriples(withTransform(VOID_STAGE_NAMES.triples)),
         // Cache warming — must precede per-class stages.
-        classPartitions(stageOptions),
+        classPartitions(withTransform(VOID_STAGE_NAMES.classPartitions)),
         // Per-class stages.
-        classPropertySubjects(stageOptions),
-        classPropertyObjects(stageOptions),
-        perClassDatatypes(stageOptions),
-        perClassObjectClasses(stageOptions),
-        perClassLanguages(stageOptions),
+        classPropertySubjects(withTransform(VOID_STAGE_NAMES.classPropertySubjects)),
+        classPropertyObjects(withTransform(VOID_STAGE_NAMES.classPropertyObjects)),
+        perClassDatatypes(withTransform(VOID_STAGE_NAMES.perClassDatatypes)),
+        perClassObjectClasses(withTransform(VOID_STAGE_NAMES.perClassObjectClasses)),
+        perClassLanguages(withTransform(VOID_STAGE_NAMES.perClassLanguages)),
         // Other stages.
-        detectLicenses(stageOptions),
-        detectVocabularies({ ...stageOptions, vocabularies }),
-        subjectUriSpaces(stageOptions),
-        ...(uriSpaceMap ? [uriSpaces(uriSpaceMap, stageOptions)] : []),
+        detectLicenses(withTransform(VOID_STAGE_NAMES.licenses)),
+        detectVocabularies({
+            ...withTransform(VOID_STAGE_NAMES.vocabularies),
+            vocabularies,
+        }),
+        subjectUriSpaces(withTransform(VOID_STAGE_NAMES.subjectUriSpace)),
+        ...(uriSpaceMap
+            ? [uriSpaces(uriSpaceMap, withTransform(VOID_STAGE_NAMES.objectUriSpace))]
+            : []),
     ]);
 }

package/dist/uriSpaceTransform.d.ts

@@ -0,0 +1,17 @@
+import type { ExecutorContext, QuadTransform } from '@lde/pipeline';
+import type { Quad } from '@rdfjs/types';
+/**
+ * Creates a {@link QuadTransform} that consumes `void:Linkset` quads from a
+ * stage's executor output, matches each `void:objectsTarget` against the
+ * configured URI space prefixes using `startsWith`, and aggregates triple
+ * counts per matched space.
+ *
+ * Emitted `void:objectsTarget` values point to the target dataset IRI (taken
+ * from the metadata quad subjects), not the raw URI space prefix. Unmatched
+ * linksets are discarded.
+ *
+ * Attach it to the `object-uri-space.rq` stage's executor – directly via
+ * {@link uriSpaces} or through the `transforms` map of {@link voidStages}.
+ */
+export declare function withUriSpaces(uriSpaces: ReadonlyMap<string, readonly Quad[]>): QuadTransform<ExecutorContext>;
+//# sourceMappingURL=uriSpaceTransform.d.ts.map

package/dist/uriSpaceTransform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uriSpaceTransform.d.ts","sourceRoot":"","sources":["../src/uriSpaceTransform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAgBzC;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC,GAC9C,aAAa,CAAC,eAAe,CAAC,CAGhC"}

package/dist/{uriSpaceExecutor.js → uriSpaceTransform.js}

@@ -1,4 +1,3 @@
-import { NotSupported, } from '@lde/pipeline';
 import { DataFactory } from 'n3';
 const { namedNode, quad, literal, blankNode } = DataFactory;
 const RDF = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#';
@@ -11,30 +10,22 @@ const voidObjectsTarget = namedNode(`${VOID}objectsTarget`);
 const voidTriples = namedNode(`${VOID}triples`);
 const xsdInteger = namedNode(`${XSD}integer`);
 /**
- * Executor decorator that consumes `void:Linkset` quads from the inner executor,
- * matches each `void:objectsTarget` against configured URI space prefixes using
- * `startsWith`, and aggregates triple counts per matched space.
+ * Creates a {@link QuadTransform} that consumes `void:Linkset` quads from a
+ * stage's executor output, matches each `void:objectsTarget` against the
+ * configured URI space prefixes using `startsWith`, and aggregates triple
+ * counts per matched space.
  *
- * Emitted `void:objectsTarget` values point to the target dataset IRI (taken from
- * the metadata quad subjects), not the raw URI space prefix. Unmatched linksets
- * are discarded.
+ * Emitted `void:objectsTarget` values point to the target dataset IRI (taken
+ * from the metadata quad subjects), not the raw URI space prefix. Unmatched
+ * linksets are discarded.
+ *
+ * Attach it to the `object-uri-space.rq` stage's executor – directly via
+ * {@link uriSpaces} or through the `transforms` map of {@link voidStages}.
  */
-export class UriSpaceExecutor {
-    inner;
-    uriSpaces;
-    constructor(inner, uriSpaces) {
-        this.inner = inner;
-        this.uriSpaces = uriSpaces;
-    }
-    async execute(dataset, distribution, options) {
-        const result = await this.inner.execute(dataset, distribution, options);
-        if (result instanceof NotSupported) {
-            return result;
-        }
-        return withUriSpaces(result, dataset.iri.toString(), this.uriSpaces);
-    }
+export function withUriSpaces(uriSpaces) {
+    return (quads, { dataset }) => aggregateUriSpaces(quads, dataset.iri.toString(), uriSpaces);
 }
-async function* withUriSpaces(quads, datasetIri, uriSpaces) {
+async function* aggregateUriSpaces(quads, datasetIri, uriSpaces) {
     // Group inner quads by subject (each subject = one Linkset).
     const linksets = new Map();
     for await (const q of quads) {

package/dist/vocabularyTransform.d.ts

@@ -0,0 +1,17 @@
+import type { ExecutorContext, QuadTransform } from '@lde/pipeline';
+export declare const defaultVocabularies: readonly string[];
+/**
+ * Creates a {@link QuadTransform} that passes through all quads from a stage's
+ * executor output and appends `void:vocabulary` triples for detected
+ * vocabulary prefixes.
+ *
+ * Inspects quads with predicate `void:property` to detect known vocabulary
+ * namespace prefixes, then yields the corresponding `void:vocabulary` quads
+ * after the executor output has been consumed.
+ *
+ * Attach it to the `entity-properties.rq` stage's executor – directly via
+ * {@link detectVocabularies} or through the `transforms` map of
+ * {@link voidStages}.
+ */
+export declare function withVocabularies(vocabularies?: readonly string[]): QuadTransform<ExecutorContext>;
+//# sourceMappingURL=vocabularyTransform.d.ts.map

package/dist/vocabularyTransform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabularyTransform.d.ts","sourceRoot":"","sources":["../src/vocabularyTransform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAWpE,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAEhD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,GAAE,SAAS,MAAM,EAAwB,GACpD,aAAa,CAAC,eAAe,CAAC,CAGhC"}

package/dist/{vocabularyAnalyzer.js → vocabularyTransform.js}

@@ -1,4 +1,3 @@
-import { NotSupported, } from '@lde/pipeline';
 import prefixes from '@zazuko/prefixes';
 import { DataFactory } from 'n3';
 const { namedNode, quad } = DataFactory;
@@ -9,29 +8,22 @@ export const defaultVocabularies = [
     ...new Set(Object.values(prefixes)),
 ];
 /**
- * Executor decorator that passes through all quads from the inner executor
- * and appends `void:vocabulary` triples for detected vocabulary prefixes.
+ * Creates a {@link QuadTransform} that passes through all quads from a stage's
+ * executor output and appends `void:vocabulary` triples for detected
+ * vocabulary prefixes.
  *
  * Inspects quads with predicate `void:property` to detect known vocabulary
  * namespace prefixes, then yields the corresponding `void:vocabulary` quads
- * after all inner quads have been consumed.
+ * after the executor output has been consumed.
+ *
+ * Attach it to the `entity-properties.rq` stage's executor – directly via
+ * {@link detectVocabularies} or through the `transforms` map of
+ * {@link voidStages}.
  */
-export class VocabularyExecutor {
-    inner;
-    vocabularies;
-    constructor(inner, vocabularies = defaultVocabularies) {
-        this.inner = inner;
-        this.vocabularies = vocabularies;
-    }
-    async execute(dataset, distribution, options) {
-        const result = await this.inner.execute(dataset, distribution, options);
-        if (result instanceof NotSupported) {
-            return result;
-        }
-        return withVocabularies(result, dataset.iri.toString(), this.vocabularies);
-    }
+export function withVocabularies(vocabularies = defaultVocabularies) {
+    return (quads, { dataset }) => appendVocabularies(quads, dataset.iri.toString(), vocabularies);
 }
-async function* withVocabularies(quads, datasetIri, vocabularies) {
+async function* appendVocabularies(quads, datasetIri, vocabularies) {
     const detectedVocabularies = new Set();
     for await (const q of quads) {
         yield q;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/pipeline-void",
-  "version": "0.28.4",
+  "version": "0.28.5",
   "description": "VOiD (Vocabulary of Interlinked Datasets) statistical analysis for RDF datasets",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
@@ -33,6 +33,6 @@
   },
   "peerDependencies": {
     "@lde/dataset": "0.7.4",
-    "@lde/pipeline": "0.30.4"
+    "@lde/pipeline": "0.30.5"
   }
 }

package/dist/uriSpaceExecutor.d.ts

@@ -1,19 +0,0 @@
-import { Dataset, Distribution } from '@lde/dataset';
-import { NotSupported, type Executor, type ExecuteOptions } from '@lde/pipeline';
-import type { Quad } from '@rdfjs/types';
-/**
- * Executor decorator that consumes `void:Linkset` quads from the inner executor,
- * matches each `void:objectsTarget` against configured URI space prefixes using
- * `startsWith`, and aggregates triple counts per matched space.
- *
- * Emitted `void:objectsTarget` values point to the target dataset IRI (taken from
- * the metadata quad subjects), not the raw URI space prefix. Unmatched linksets
- * are discarded.
- */
-export declare class UriSpaceExecutor implements Executor {
-    private readonly inner;
-    private readonly uriSpaces;
-    constructor(inner: Executor, uriSpaces: ReadonlyMap<string, readonly Quad[]>);
-    execute(dataset: Dataset, distribution: Distribution, options?: ExecuteOptions): Promise<AsyncIterable<Quad> | NotSupported>;
-}
-//# sourceMappingURL=uriSpaceExecutor.d.ts.map

package/dist/uriSpaceExecutor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"uriSpaceExecutor.d.ts","sourceRoot":"","sources":["../src/uriSpaceExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EACL,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAgBzC;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAE7C,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,KAAK,EAAE,QAAQ,EACf,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC;IAG5D,OAAO,CACX,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC;CAO/C"}

package/dist/vocabularyAnalyzer.d.ts

@@ -1,19 +0,0 @@
-import { Dataset, Distribution } from '@lde/dataset';
-import { NotSupported, type Executor, type ExecuteOptions } from '@lde/pipeline';
-import type { Quad } from '@rdfjs/types';
-export declare const defaultVocabularies: readonly string[];
-/**
- * Executor decorator that passes through all quads from the inner executor
- * and appends `void:vocabulary` triples for detected vocabulary prefixes.
- *
- * Inspects quads with predicate `void:property` to detect known vocabulary
- * namespace prefixes, then yields the corresponding `void:vocabulary` quads
- * after all inner quads have been consumed.
- */
-export declare class VocabularyExecutor implements Executor {
-    private readonly inner;
-    private readonly vocabularies;
-    constructor(inner: Executor, vocabularies?: readonly string[]);
-    execute(dataset: Dataset, distribution: Distribution, options?: ExecuteOptions): Promise<AsyncIterable<Quad> | NotSupported>;
-}
-//# sourceMappingURL=vocabularyAnalyzer.d.ts.map

package/dist/vocabularyAnalyzer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"vocabularyAnalyzer.d.ts","sourceRoot":"","sources":["../src/vocabularyAnalyzer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EACL,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAUzC,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAEhD,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,kBAAmB,YAAW,QAAQ;IAE/C,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBADZ,KAAK,EAAE,QAAQ,EACf,YAAY,GAAE,SAAS,MAAM,EAAwB;IAGlE,OAAO,CACX,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC;CAO/C"}