@lde/pipeline-void 0.2.16 → 0.2.17

package/README.md

@@ -2,19 +2,17 @@
 
 VOiD (Vocabulary of Interlinked Datasets) statistical analysis for RDF datasets.
 
-## Analyzers
+## Query stages
 
-- **SparqlQueryAnalyzer** — Execute SPARQL CONSTRUCT queries with template substitution
+- `createQueryStage(filename, distribution)` — Create a `Stage` from a SPARQL CONSTRUCT query file
+- `createDatatypeStage(distribution)` — Per-class datatype partitions
+- `createLanguageStage(distribution)` — Per-class language tags
+- `createObjectClassStage(distribution)` — Per-class object class partitions
 
-## Per-class stages
+## Streaming transformers
 
-Factory functions that create `Stage` instances for per-class analysis.
-Each stage first selects classes from the endpoint, then runs a CONSTRUCT query
-with `?class` bound via VALUES:
-
-- `createDatatypeStage` — per-class datatype partitions
-- `createLanguageStage` — per-class language tags
-- `createObjectClassStage` — per-class object class partitions
+- `withVocabularies(quads, datasetIri)` — Detect and append `void:vocabulary` triples
+- `withProvenance(quads, iri, startedAt, endedAt)` — Append PROV-O provenance metadata
 
 ## SPARQL Queries
 
@@ -43,23 +41,30 @@ Generic VOiD analysis queries included:
 
 ```typescript
 import {
-  SparqlQueryAnalyzer,
-  Success,
+  createQueryStage,
   createDatatypeStage,
+  withVocabularies,
+  withProvenance,
 } from '@lde/pipeline-void';
 import { Distribution } from '@lde/dataset';
 
-// Simple CONSTRUCT query analyzer
-const analyzer = await SparqlQueryAnalyzer.fromFile('triples.rq');
-const result = await analyzer.execute(dataset);
-if (result instanceof Success) {
-  // result.data contains the VOiD statistics as RDF
-}
-
-// Per-class stage (streaming)
 const distribution = Distribution.sparql(new URL('http://example.com/sparql'));
-const stage = await createDatatypeStage(distribution);
+
+// Simple CONSTRUCT query stage
+const stage = await createQueryStage('triples.rq', distribution);
 const quads = await stage.run(dataset, distribution);
+
+// Per-class stage (streaming)
+const datatypeStage = await createDatatypeStage(distribution);
+const datatypeQuads = await datatypeStage.run(dataset, distribution);
+
+// Enrich with vocabulary detection and provenance
+const enriched = withProvenance(
+  withVocabularies(quads, dataset.iri.toString()),
+  dataset.iri.toString(),
+  startedAt,
+  endedAt
+);
 ```
 
 ## Validation

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-export { Stage } from '@lde/pipeline';
-export { type Analyzer, BaseAnalyzer, Success, Failure, NotSupported, } from '@lde/pipeline/analyzer';
+export { Stage, NotSupported } from '@lde/pipeline';
 export * from './sparqlQueryAnalyzer.js';
 export * from './perClassAnalyzer.js';
 export * from './vocabularyAnalyzer.js';

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,MAAM,eAAe,CAAC;AACtC,OAAO,EACL,KAAK,QAAQ,EACb,YAAY,EACZ,OAAO,EACP,OAAO,EACP,YAAY,GACb,MAAM,wBAAwB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iBAAiB,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,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,5 +1,4 @@
-export { Stage } from '@lde/pipeline';
-export { BaseAnalyzer, Success, Failure, NotSupported, } from '@lde/pipeline/analyzer';
+export { Stage, NotSupported } from '@lde/pipeline';
 export * from './sparqlQueryAnalyzer.js';
 export * from './perClassAnalyzer.js';
 export * from './vocabularyAnalyzer.js';

package/dist/provenance.d.ts

@@ -1,18 +1,14 @@
-import type { DatasetCore } from '@rdfjs/types';
+import type { Quad } from '@rdfjs/types';
 /**
- * Add PROV-O provenance metadata to a dataset.
+ * Streaming transformer that passes through all quads and appends
+ * PROV-O provenance metadata.
  *
- * Adds:
+ * Appended quads:
  * - `<iri> a prov:Entity`
  * - `<iri> prov:wasGeneratedBy _:activity`
  * - `_:activity a prov:Activity`
  * - `_:activity prov:startedAtTime "..."^^xsd:dateTime`
  * - `_:activity prov:endedAtTime "..."^^xsd:dateTime`
- *
- * @param data The dataset to add provenance to
- * @param iri The IRI of the entity
- * @param startedAt Start time of the activity
- * @param endedAt End time of the activity
  */
-export declare function withProvenance(data: DatasetCore, iri: string, startedAt: Date, endedAt: Date): DatasetCore;
+export declare function withProvenance(quads: AsyncIterable<Quad>, iri: string, startedAt: Date, endedAt: Date): AsyncIterable<Quad>;
 //# sourceMappingURL=provenance.d.ts.map

package/dist/provenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAiBhD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,IAAI,EACf,OAAO,EAAE,IAAI,GACZ,WAAW,CAwBb"}
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAiBzC;;;;;;;;;;GAUG;AACH,wBAAuB,cAAc,CACnC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,EAC1B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,IAAI,EACf,OAAO,EAAE,IAAI,GACZ,aAAa,CAAC,IAAI,CAAC,CAqBrB"}

package/dist/provenance.js

@@ -1,4 +1,4 @@
-import { DataFactory, Store } from 'n3';
+import { DataFactory } from 'n3';
 const { namedNode, literal, blankNode, quad } = DataFactory;
 const RDF_TYPE = namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type');
 const PROV_ENTITY = namedNode('http://www.w3.org/ns/prov#Entity');
@@ -8,28 +8,25 @@ const PROV_STARTED_AT_TIME = namedNode('http://www.w3.org/ns/prov#startedAtTime'
 const PROV_ENDED_AT_TIME = namedNode('http://www.w3.org/ns/prov#endedAtTime');
 const XSD_DATE_TIME = namedNode('http://www.w3.org/2001/XMLSchema#dateTime');
 /**
- * Add PROV-O provenance metadata to a dataset.
+ * Streaming transformer that passes through all quads and appends
+ * PROV-O provenance metadata.
  *
- * Adds:
+ * Appended quads:
  * - `<iri> a prov:Entity`
  * - `<iri> prov:wasGeneratedBy _:activity`
  * - `_:activity a prov:Activity`
  * - `_:activity prov:startedAtTime "..."^^xsd:dateTime`
  * - `_:activity prov:endedAtTime "..."^^xsd:dateTime`
- *
- * @param data The dataset to add provenance to
- * @param iri The IRI of the entity
- * @param startedAt Start time of the activity
- * @param endedAt End time of the activity
  */
-export function withProvenance(data, iri, startedAt, endedAt) {
-    const store = new Store([...data]);
+export async function* withProvenance(quads, iri, startedAt, endedAt) {
+    for await (const q of quads) {
+        yield q;
+    }
     const subject = namedNode(iri);
     const activity = blankNode();
-    store.addQuad(quad(subject, RDF_TYPE, PROV_ENTITY));
-    store.addQuad(quad(subject, PROV_WAS_GENERATED_BY, activity));
-    store.addQuad(quad(activity, RDF_TYPE, PROV_ACTIVITY));
-    store.addQuad(quad(activity, PROV_STARTED_AT_TIME, literal(startedAt.toISOString(), XSD_DATE_TIME)));
-    store.addQuad(quad(activity, PROV_ENDED_AT_TIME, literal(endedAt.toISOString(), XSD_DATE_TIME)));
-    return store;
+    yield quad(subject, RDF_TYPE, PROV_ENTITY);
+    yield quad(subject, PROV_WAS_GENERATED_BY, activity);
+    yield quad(activity, RDF_TYPE, PROV_ACTIVITY);
+    yield quad(activity, PROV_STARTED_AT_TIME, literal(startedAt.toISOString(), XSD_DATE_TIME));
+    yield quad(activity, PROV_ENDED_AT_TIME, literal(endedAt.toISOString(), XSD_DATE_TIME));
 }

package/dist/sparqlQueryAnalyzer.d.ts

@@ -1,39 +1,10 @@
-import { Dataset } from '@lde/dataset';
-import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
-import { BaseAnalyzer, Success, Failure, NotSupported } from '@lde/pipeline/analyzer';
-export interface SparqlQueryAnalyzerOptions {
-    /**
-     * Timeout for SPARQL queries in milliseconds.
-     * @default 300000 (5 minutes)
-     */
-    timeout?: number;
-    /**
-     * Custom SparqlEndpointFetcher instance.
-     */
-    fetcher?: SparqlEndpointFetcher;
-}
+import { Distribution } from '@lde/dataset';
+import { Stage } from '@lde/pipeline';
 /**
- * Analyzer that executes a SPARQL CONSTRUCT query against a dataset's SPARQL endpoint.
+ * Create a Stage that executes a SPARQL CONSTRUCT query from the queries directory.
  *
- * Supports legacy template substitution:
- * - `#subjectFilter#` — replaced with the dataset's subject filter (if any)
- * - `#namedGraph#` — replaced with `FROM <graph>` clause if the distribution has a named graph
- * - `?dataset` — replaced with the dataset IRI
- *
- * This class wraps the SparqlConstructExecutor from @lde/pipeline.
+ * Pre-processes `#subjectFilter#` before the query is parsed as SPARQL;
+ * `?dataset` and `FROM <graph>` are handled at the AST level by the executor.
  */
-export declare class SparqlQueryAnalyzer extends BaseAnalyzer {
-    readonly name: string;
-    private readonly query;
-    private readonly fetcher;
-    constructor(name: string, query: string, options?: SparqlQueryAnalyzerOptions);
-    /**
-     * Create an analyzer from a query file in the queries directory.
-     *
-     * @param filename Query filename (e.g., 'triples.rq')
-     * @param options Optional analyzer options
-     */
-    static fromFile(filename: string, options?: SparqlQueryAnalyzerOptions): Promise<SparqlQueryAnalyzer>;
-    execute(dataset: Dataset): Promise<Success | Failure | NotSupported>;
-}
+export declare function createQueryStage(filename: string, distribution: Distribution): Promise<Stage>;
 //# sourceMappingURL=sparqlQueryAnalyzer.d.ts.map

package/dist/sparqlQueryAnalyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sparqlQueryAnalyzer.d.ts","sourceRoot":"","sources":["../src/sparqlQueryAnalyzer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAOvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,OAAO,EACL,YAAY,EACZ,OAAO,EACP,OAAO,EACP,YAAY,EACb,MAAM,wBAAwB,CAAC;AAIhC,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;aAKjC,IAAI,EAAE,MAAM;IAJ9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;gBAG9B,IAAI,EAAE,MAAM,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,0BAA0B;IAWtC;;;;;OAKG;WACiB,QAAQ,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,mBAAmB,CAAC;IAKlB,OAAO,CAClB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,GAAG,OAAO,GAAG,YAAY,CAAC;CA2B7C"}
+{"version":3,"file":"sparqlQueryAnalyzer.d.ts","sourceRoot":"","sources":["../src/sparqlQueryAnalyzer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,KAAK,EAA0C,MAAM,eAAe,CAAC;AAM9E;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,KAAK,CAAC,CAShB"}

package/dist/sparqlQueryAnalyzer.js

@@ -1,61 +1,17 @@
-import { SparqlConstructExecutor, substituteQueryTemplates, collect, readQueryFile, } from '@lde/pipeline';
-import { SparqlEndpointFetcher } from 'fetch-sparql-endpoint';
+import { Stage, SparqlConstructExecutor, readQueryFile } from '@lde/pipeline';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { BaseAnalyzer, Success, Failure, NotSupported, } from '@lde/pipeline/analyzer';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /**
- * Analyzer that executes a SPARQL CONSTRUCT query against a dataset's SPARQL endpoint.
+ * Create a Stage that executes a SPARQL CONSTRUCT query from the queries directory.
  *
- * Supports legacy template substitution:
- * - `#subjectFilter#` — replaced with the dataset's subject filter (if any)
- * - `#namedGraph#` — replaced with `FROM <graph>` clause if the distribution has a named graph
- * - `?dataset` — replaced with the dataset IRI
- *
- * This class wraps the SparqlConstructExecutor from @lde/pipeline.
+ * Pre-processes `#subjectFilter#` before the query is parsed as SPARQL;
+ * `?dataset` and `FROM <graph>` are handled at the AST level by the executor.
  */
-export class SparqlQueryAnalyzer extends BaseAnalyzer {
-    name;
-    query;
-    fetcher;
-    constructor(name, query, options) {
-        super();
-        this.name = name;
-        this.query = query;
-        this.fetcher =
-            options?.fetcher ??
-                new SparqlEndpointFetcher({
-                    timeout: options?.timeout ?? 300_000,
-                });
-    }
-    /**
-     * Create an analyzer from a query file in the queries directory.
-     *
-     * @param filename Query filename (e.g., 'triples.rq')
-     * @param options Optional analyzer options
-     */
-    static async fromFile(filename, options) {
-        const query = await readQueryFile(resolve(__dirname, 'queries', filename));
-        return new SparqlQueryAnalyzer(filename, query, options);
-    }
-    async execute(dataset) {
-        const sparqlDistribution = dataset.getSparqlDistribution();
-        if (sparqlDistribution === null) {
-            return new NotSupported('No SPARQL distribution available');
-        }
-        try {
-            const substituted = substituteQueryTemplates(this.query, sparqlDistribution, dataset);
-            const executor = new SparqlConstructExecutor({
-                query: substituted,
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                fetcher: this.fetcher,
-            });
-            const stream = await executor.execute(dataset, sparqlDistribution);
-            const store = await collect(stream);
-            return new Success(store);
-        }
-        catch (e) {
-            return new Failure(sparqlDistribution.accessUrl ?? new URL('unknown://'), e instanceof Error ? e.message : undefined);
-        }
-    }
+export async function createQueryStage(filename, distribution) {
+    const rawQuery = await readQueryFile(resolve(__dirname, 'queries', filename));
+    const subjectFilter = distribution.subjectFilter ?? '';
+    const query = rawQuery.replace('#subjectFilter#', subjectFilter);
+    const executor = new SparqlConstructExecutor({ query });
+    return new Stage({ name: filename, executors: executor });
 }

package/dist/vocabularyAnalyzer.d.ts

@@ -1,17 +1,11 @@
-import { Dataset } from '@lde/dataset';
-import { type Analyzer, Success, type Failure, type NotSupported } from '@lde/pipeline/analyzer';
+import type { Quad } from '@rdfjs/types';
 /**
- * Decorator analyzer that enriches results with `void:vocabulary` triples.
+ * Streaming transformer that passes through all quads and appends
+ * `void:vocabulary` triples for detected vocabulary prefixes.
  *
- * Wraps another analyzer, runs it, then inspects `void:property` triples
- * to detect known vocabulary prefixes and add corresponding `void:vocabulary`
- * triples to the result.
+ * Inspects quads with predicate `void:property` to detect known vocabulary
+ * namespace prefixes, then yields the corresponding `void:vocabulary` quads
+ * after all input quads have been consumed.
  */
-export declare class VocabularyAnalyzer implements Analyzer {
-    private readonly inner;
-    readonly name: string;
-    constructor(inner: Analyzer);
-    execute(dataset: Dataset): Promise<Success | Failure | NotSupported>;
-    finish(): Promise<void>;
-}
+export declare function withVocabularies(quads: AsyncIterable<Quad>, datasetIri: string): AsyncIterable<Quad>;
 //# sourceMappingURL=vocabularyAnalyzer.d.ts.map

package/dist/vocabularyAnalyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vocabularyAnalyzer.d.ts","sourceRoot":"","sources":["../src/vocabularyAnalyzer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EACL,KAAK,QAAQ,EACb,OAAO,EACP,KAAK,OAAO,EACZ,KAAK,YAAY,EAClB,MAAM,wBAAwB,CAAC;AAiChC;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,QAAQ;IAGrC,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEA,KAAK,EAAE,QAAQ;IAI/B,OAAO,CAClB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,GAAG,OAAO,GAAG,YAAY,CAAC;IAU/B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAGrC"}
+{"version":3,"file":"vocabularyAnalyzer.d.ts","sourceRoot":"","sources":["../src/vocabularyAnalyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAkCzC;;;;;;;GAOG;AACH,wBAAuB,gBAAgB,CACrC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,EAC1B,UAAU,EAAE,MAAM,GACjB,aAAa,CAAC,IAAI,CAAC,CAqBrB"}

package/dist/vocabularyAnalyzer.js

@@ -1,5 +1,4 @@
-import { DataFactory, Store } from 'n3';
-import { Success, } from '@lde/pipeline/analyzer';
+import { DataFactory } from 'n3';
 const { namedNode, quad } = DataFactory;
 const VOID = 'http://rdfs.org/ns/void#';
 const voidProperty = namedNode(`${VOID}property`);
@@ -29,47 +28,29 @@ const vocabularyPrefixes = new Map([
     ['http://xmlns.com/foaf/0.1/', 'http://xmlns.com/foaf/0.1/'],
 ]);
 /**
- * Decorator analyzer that enriches results with `void:vocabulary` triples.
+ * Streaming transformer that passes through all quads and appends
+ * `void:vocabulary` triples for detected vocabulary prefixes.
  *
- * Wraps another analyzer, runs it, then inspects `void:property` triples
- * to detect known vocabulary prefixes and add corresponding `void:vocabulary`
- * triples to the result.
+ * Inspects quads with predicate `void:property` to detect known vocabulary
+ * namespace prefixes, then yields the corresponding `void:vocabulary` quads
+ * after all input quads have been consumed.
  */
-export class VocabularyAnalyzer {
-    inner;
-    name;
-    constructor(inner) {
-        this.inner = inner;
-        this.name = inner.name;
-    }
-    async execute(dataset) {
-        const result = await this.inner.execute(dataset);
-        if (!(result instanceof Success)) {
-            return result;
-        }
-        const enriched = addVocabularyTriples(result.data, dataset.iri.toString());
-        return new Success(enriched);
-    }
-    async finish() {
-        await this.inner.finish?.();
-    }
-}
-function addVocabularyTriples(data, datasetIri) {
-    const store = new Store([...data]);
-    const datasetNode = namedNode(datasetIri);
-    // Collect unique vocabulary URIs from void:property triples.
+export async function* withVocabularies(quads, datasetIri) {
     const detectedVocabularies = new Set();
-    for (const q of store.match(null, voidProperty, null)) {
-        const propertyUri = q.object.value;
-        for (const [prefix, vocabUri] of vocabularyPrefixes) {
-            if (propertyUri.startsWith(prefix)) {
-                detectedVocabularies.add(vocabUri);
-                break;
+    for await (const q of quads) {
+        yield q;
+        if (q.predicate.equals(voidProperty)) {
+            const propertyUri = q.object.value;
+            for (const [prefix, vocabUri] of vocabularyPrefixes) {
+                if (propertyUri.startsWith(prefix)) {
+                    detectedVocabularies.add(vocabUri);
+                    break;
+                }
             }
         }
     }
+    const datasetNode = namedNode(datasetIri);
     for (const vocabUri of detectedVocabularies) {
-        store.addQuad(quad(datasetNode, voidVocabulary, namedNode(vocabUri)));
+        yield quad(datasetNode, voidVocabulary, namedNode(vocabUri));
     }
-    return store;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/pipeline-void",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "description": "VOiD (Vocabulary of Interlinked Datasets) statistical analysis for RDF datasets",
   "repository": {
     "url": "https://github.com/ldengine/lde",
@@ -27,7 +27,6 @@
     "@lde/dataset": "0.6.8",
     "@lde/pipeline": "0.6.15",
     "@rdfjs/types": "^2.0.1",
-    "fetch-sparql-endpoint": "^6.0.0",
     "n3": "^1.17.0",
     "tslib": "^2.3.0"
   }