opentology 0.1.0

package/dist/lib/embedded-adapter.js

@@ -0,0 +1,202 @@
+import { DataFactory as N3DataFactory } from 'n3';
+import oxigraph from 'oxigraph';
+import { termToSparql, parseTurtle, extractPrefixes, serializeQuadsToTurtle, } from './sparql-utils.js';
+/**
+ * Convert an oxigraph WASM Term object to the SparqlResults binding format.
+ */
+function termToBinding(term) {
+    switch (term.termType) {
+        case 'NamedNode':
+            return { type: 'uri', value: term.value };
+        case 'BlankNode':
+            return { type: 'bnode', value: term.value };
+        case 'Literal': {
+            const entry = {
+                type: 'literal',
+                value: term.value,
+            };
+            if (term.datatype) {
+                entry.datatype = term.datatype.value;
+            }
+            return entry;
+        }
+        default:
+            return { type: 'uri', value: term.value };
+    }
+}
+/**
+ * Convert an oxigraph WASM Quad to an n3-compatible Quad for serialization.
+ */
+function wasmQuadToN3Quad(q) {
+    const subject = q.subject.termType === 'BlankNode'
+        ? N3DataFactory.blankNode(q.subject.value)
+        : N3DataFactory.namedNode(q.subject.value);
+    const predicate = N3DataFactory.namedNode(q.predicate.value);
+    let object;
+    if (q.object.termType === 'Literal') {
+        if (q.object.language) {
+            object = N3DataFactory.literal(q.object.value, q.object.language);
+        }
+        else if (q.object.datatype &&
+            q.object.datatype.value !== 'http://www.w3.org/2001/XMLSchema#string') {
+            object = N3DataFactory.literal(q.object.value, N3DataFactory.namedNode(q.object.datatype.value));
+        }
+        else {
+            object = N3DataFactory.literal(q.object.value);
+        }
+    }
+    else if (q.object.termType === 'BlankNode') {
+        object = N3DataFactory.blankNode(q.object.value);
+    }
+    else {
+        object = N3DataFactory.namedNode(q.object.value);
+    }
+    return N3DataFactory.quad(subject, predicate, object);
+}
+export class EmbeddedAdapter {
+    constructor() {
+        this.store = new oxigraph.Store();
+    }
+    /**
+     * Load Turtle data directly into a named graph.
+     */
+    loadTurtleIntoGraph(turtle, graphUri) {
+        this.store.load(turtle, {
+            format: 'text/turtle',
+            base_iri: 'http://example.org/',
+            to_graph_name: oxigraph.namedNode(graphUri),
+        });
+    }
+    async askQuery(query) {
+        const result = this.store.query(query);
+        return result === true;
+    }
+    async sparqlQuery(query) {
+        const rawResults = this.store.query(query);
+        // rawResults is an iterable of Map-like objects for SELECT queries
+        const bindings = [];
+        const varsSet = new Set();
+        for (const row of rawResults) {
+            const binding = {};
+            for (const [key, value] of row) {
+                varsSet.add(key);
+                if (value != null) {
+                    binding[key] = termToBinding(value);
+                }
+            }
+            bindings.push(binding);
+        }
+        return {
+            head: { vars: [...varsSet] },
+            results: { bindings },
+        };
+    }
+    async sparqlUpdate(update) {
+        this.store.update(update);
+    }
+    async constructQuery(query) {
+        const rawQuads = this.store.query(query);
+        const n3Quads = [];
+        for (const q of rawQuads) {
+            n3Quads.push(wasmQuadToN3Quad(q));
+        }
+        return serializeQuadsToTurtle(n3Quads);
+    }
+    async insertTurtle(graphUri, turtle) {
+        if (!turtle.trim()) {
+            return;
+        }
+        this.loadTurtleIntoGraph(turtle, graphUri);
+    }
+    async getGraphTripleCount(graphUri) {
+        const query = `SELECT (COUNT(*) AS ?count) WHERE { GRAPH <${graphUri}> { ?s ?p ?o } }`;
+        const results = await this.sparqlQuery(query);
+        const binding = results.results.bindings[0];
+        if (!binding || !binding['count']) {
+            return 0;
+        }
+        return parseInt(binding['count'].value, 10);
+    }
+    async exportGraph(graphUri) {
+        const quads = this.store.match(null, null, null, oxigraph.namedNode(graphUri));
+        const n3Quads = [];
+        for (const q of quads) {
+            n3Quads.push(wasmQuadToN3Quad(q));
+        }
+        return serializeQuadsToTurtle(n3Quads);
+    }
+    async dropGraph(graphUri) {
+        this.store.update(`DROP SILENT GRAPH <${graphUri}>`);
+    }
+    async deleteTriples(graphUri, options) {
+        if (options.turtle !== undefined) {
+            const quads = await parseTurtle(options.turtle);
+            if (quads.length === 0) {
+                return;
+            }
+            const tripleLines = quads
+                .map((q) => `  ${termToSparql(q.subject)} ${termToSparql(q.predicate)} ${termToSparql(q.object)} .`)
+                .join('\n');
+            const update = `DELETE DATA {\n  GRAPH <${graphUri}> {\n${tripleLines}\n  }\n}`;
+            this.store.update(update);
+        }
+        else if (options.where !== undefined) {
+            const update = `DELETE { GRAPH <${graphUri}> { ?s ?p ?o } } WHERE { GRAPH <${graphUri}> { ?s ?p ?o . ${options.where} } }`;
+            this.store.update(update);
+        }
+        else {
+            throw new Error('deleteTriples: either options.turtle or options.where must be provided');
+        }
+    }
+    async diffGraph(graphUri, localTurtle) {
+        const localQuads = await parseTurtle(localTurtle);
+        const localSet = new Set(localQuads.map((q) => `${termToSparql(q.subject)} ${termToSparql(q.predicate)} ${termToSparql(q.object)}`));
+        // Get remote quads from the store
+        const remoteRawQuads = this.store.match(null, null, null, oxigraph.namedNode(graphUri));
+        const remoteSet = new Set();
+        for (const q of remoteRawQuads) {
+            const n3q = wasmQuadToN3Quad(q);
+            remoteSet.add(`${termToSparql(n3q.subject)} ${termToSparql(n3q.predicate)} ${termToSparql(n3q.object)}`);
+        }
+        const added = [...localSet].filter((t) => !remoteSet.has(t));
+        const removed = [...remoteSet].filter((t) => !localSet.has(t));
+        const unchanged = [...localSet].filter((t) => remoteSet.has(t)).length;
+        return { added, removed, unchanged };
+    }
+    async getSchemaOverview(graphUri) {
+        const tripleCount = await this.getGraphTripleCount(graphUri);
+        const classResults = await this.sparqlQuery(`SELECT DISTINCT ?class WHERE { GRAPH <${graphUri}> { ?s a ?class } } ORDER BY ?class`);
+        const classes = classResults.results.bindings
+            .map((b) => b['class']?.value)
+            .filter((v) => v !== undefined);
+        const propResults = await this.sparqlQuery(`SELECT DISTINCT ?prop WHERE { GRAPH <${graphUri}> { ?s ?prop ?o } } ORDER BY ?prop`);
+        const properties = propResults.results.bindings
+            .map((b) => b['prop']?.value)
+            .filter((v) => v !== undefined);
+        const prefixes = extractPrefixes([...classes, ...properties]);
+        return { prefixes, classes, properties, tripleCount };
+    }
+    async getClassDetails(graphUri, classUri) {
+        const countResults = await this.sparqlQuery(`SELECT (COUNT(?s) as ?count) WHERE { GRAPH <${graphUri}> { ?s a <${classUri}> } }`);
+        const countBinding = countResults.results.bindings[0];
+        const instanceCount = countBinding?.['count']
+            ? parseInt(countBinding['count'].value, 10)
+            : 0;
+        const propResults = await this.sparqlQuery(`SELECT ?prop (COUNT(?prop) as ?count) WHERE { GRAPH <${graphUri}> { ?s a <${classUri}> . ?s ?prop ?o } } GROUP BY ?prop ORDER BY DESC(?count)`);
+        const properties = propResults.results.bindings
+            .filter((b) => b['prop'] && b['count'])
+            .map((b) => ({
+            property: b['prop'].value,
+            count: parseInt(b['count'].value, 10),
+        }));
+        const sampleResults = await this.sparqlQuery(`SELECT ?s ?p ?o WHERE { GRAPH <${graphUri}> { ?s a <${classUri}> . ?s ?p ?o } } LIMIT 5`);
+        const sampleTriples = sampleResults.results.bindings
+            .filter((b) => b['s'] && b['p'] && b['o'])
+            .map((b) => ({
+            s: b['s'].value,
+            p: b['p'].value,
+            o: b['o'].value,
+        }));
+        return { classUri, instanceCount, properties, sampleTriples };
+    }
+}

package/dist/lib/http-adapter.d.ts

@@ -0,0 +1,41 @@
+import type { StoreAdapter, SparqlResults } from './store-adapter.js';
+export declare class HttpAdapter implements StoreAdapter {
+    private endpoint;
+    constructor(endpoint: string);
+    askQuery(query: string): Promise<boolean>;
+    sparqlQuery(query: string): Promise<SparqlResults>;
+    sparqlUpdate(update: string): Promise<void>;
+    constructQuery(query: string): Promise<string>;
+    insertTurtle(graphUri: string, turtle: string): Promise<void>;
+    getGraphTripleCount(graphUri: string): Promise<number>;
+    exportGraph(graphUri: string): Promise<string>;
+    dropGraph(graphUri: string): Promise<void>;
+    deleteTriples(graphUri: string, options: {
+        turtle?: string;
+        where?: string;
+    }): Promise<void>;
+    diffGraph(graphUri: string, localTurtle: string): Promise<{
+        added: string[];
+        removed: string[];
+        unchanged: number;
+    }>;
+    getSchemaOverview(graphUri: string): Promise<{
+        prefixes: Record<string, string>;
+        classes: string[];
+        properties: string[];
+        tripleCount: number;
+    }>;
+    getClassDetails(graphUri: string, classUri: string): Promise<{
+        classUri: string;
+        instanceCount: number;
+        properties: Array<{
+            property: string;
+            count: number;
+        }>;
+        sampleTriples: Array<{
+            s: string;
+            p: string;
+            o: string;
+        }>;
+    }>;
+}

package/dist/lib/http-adapter.js

@@ -0,0 +1,169 @@
+import { termToSparql, parseTurtle, extractPrefixes, serializeQuadsToTurtle, } from './sparql-utils.js';
+export class HttpAdapter {
+    constructor(endpoint) {
+        this.endpoint = endpoint;
+    }
+    async askQuery(query) {
+        const url = `${this.endpoint}/query`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/sparql-query',
+                Accept: 'application/sparql-results+json',
+            },
+            body: query,
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`ASK query failed (${response.status} ${response.statusText})${body ? `: ${body}` : ''}`);
+        }
+        const json = await response.json();
+        return json.boolean === true;
+    }
+    async sparqlQuery(query) {
+        const url = `${this.endpoint}/query`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/sparql-query',
+                Accept: 'application/sparql-results+json',
+            },
+            body: query,
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`SPARQL query failed (${response.status} ${response.statusText})${body ? `: ${body}` : ''}`);
+        }
+        return response.json();
+    }
+    async sparqlUpdate(update) {
+        const url = `${this.endpoint}/update`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/sparql-update',
+            },
+            body: update,
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`SPARQL update failed (${response.status} ${response.statusText})${body ? `: ${body}` : ''}`);
+        }
+    }
+    async constructQuery(query) {
+        const response = await fetch(`${this.endpoint}/query`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/sparql-query',
+                Accept: 'text/turtle',
+            },
+            body: query,
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`SPARQL CONSTRUCT query failed (${response.status} ${response.statusText})${body ? `: ${body}` : ''}`);
+        }
+        return response.text();
+    }
+    async insertTurtle(graphUri, turtle) {
+        const quads = await parseTurtle(turtle);
+        if (quads.length === 0) {
+            return;
+        }
+        const tripleLines = quads
+            .map((q) => `  ${termToSparql(q.subject)} ${termToSparql(q.predicate)} ${termToSparql(q.object)} .`)
+            .join('\n');
+        const update = `INSERT DATA {\n  GRAPH <${graphUri}> {\n${tripleLines}\n  }\n}`;
+        await this.sparqlUpdate(update);
+    }
+    async getGraphTripleCount(graphUri) {
+        const query = `SELECT (COUNT(*) AS ?count) WHERE { GRAPH <${graphUri}> { ?s ?p ?o } }`;
+        const results = await this.sparqlQuery(query);
+        const binding = results.results.bindings[0];
+        if (!binding || !binding['count']) {
+            return 0;
+        }
+        return parseInt(binding['count'].value, 10);
+    }
+    async exportGraph(graphUri) {
+        const query = `CONSTRUCT { ?s ?p ?o } WHERE { GRAPH <${graphUri}> { ?s ?p ?o } }`;
+        const turtleText = await this.constructQuery(query);
+        // Re-serialize through n3 to ensure consistent formatting
+        const quads = await parseTurtle(turtleText);
+        return serializeQuadsToTurtle(quads);
+    }
+    async dropGraph(graphUri) {
+        await this.sparqlUpdate(`DROP SILENT GRAPH <${graphUri}>`);
+    }
+    async deleteTriples(graphUri, options) {
+        if (options.turtle !== undefined) {
+            const quads = await parseTurtle(options.turtle);
+            if (quads.length === 0) {
+                return;
+            }
+            const tripleLines = quads
+                .map((q) => `  ${termToSparql(q.subject)} ${termToSparql(q.predicate)} ${termToSparql(q.object)} .`)
+                .join('\n');
+            const update = `DELETE DATA {\n  GRAPH <${graphUri}> {\n${tripleLines}\n  }\n}`;
+            await this.sparqlUpdate(update);
+        }
+        else if (options.where !== undefined) {
+            const update = `DELETE { GRAPH <${graphUri}> { ?s ?p ?o } } WHERE { GRAPH <${graphUri}> { ?s ?p ?o . ${options.where} } }`;
+            await this.sparqlUpdate(update);
+        }
+        else {
+            throw new Error('deleteTriples: either options.turtle or options.where must be provided');
+        }
+    }
+    async diffGraph(graphUri, localTurtle) {
+        const localQuads = await parseTurtle(localTurtle);
+        const localSet = new Set(localQuads.map((q) => `${termToSparql(q.subject)} ${termToSparql(q.predicate)} ${termToSparql(q.object)}`));
+        // Fetch remote quads via CONSTRUCT
+        const query = `CONSTRUCT { ?s ?p ?o } WHERE { GRAPH <${graphUri}> { ?s ?p ?o } }`;
+        const remoteTurtle = await this.constructQuery(query);
+        const remoteQuads = remoteTurtle.trim()
+            ? await parseTurtle(remoteTurtle)
+            : [];
+        const remoteSet = new Set(remoteQuads.map((q) => `${termToSparql(q.subject)} ${termToSparql(q.predicate)} ${termToSparql(q.object)}`));
+        const added = [...localSet].filter((t) => !remoteSet.has(t));
+        const removed = [...remoteSet].filter((t) => !localSet.has(t));
+        const unchanged = [...localSet].filter((t) => remoteSet.has(t)).length;
+        return { added, removed, unchanged };
+    }
+    async getSchemaOverview(graphUri) {
+        const tripleCount = await this.getGraphTripleCount(graphUri);
+        const classResults = await this.sparqlQuery(`SELECT DISTINCT ?class WHERE { GRAPH <${graphUri}> { ?s a ?class } } ORDER BY ?class`);
+        const classes = classResults.results.bindings
+            .map((b) => b['class']?.value)
+            .filter((v) => v !== undefined);
+        const propResults = await this.sparqlQuery(`SELECT DISTINCT ?prop WHERE { GRAPH <${graphUri}> { ?s ?prop ?o } } ORDER BY ?prop`);
+        const properties = propResults.results.bindings
+            .map((b) => b['prop']?.value)
+            .filter((v) => v !== undefined);
+        const prefixes = extractPrefixes([...classes, ...properties]);
+        return { prefixes, classes, properties, tripleCount };
+    }
+    async getClassDetails(graphUri, classUri) {
+        const countResults = await this.sparqlQuery(`SELECT (COUNT(?s) as ?count) WHERE { GRAPH <${graphUri}> { ?s a <${classUri}> } }`);
+        const countBinding = countResults.results.bindings[0];
+        const instanceCount = countBinding?.['count']
+            ? parseInt(countBinding['count'].value, 10)
+            : 0;
+        const propResults = await this.sparqlQuery(`SELECT ?prop (COUNT(?prop) as ?count) WHERE { GRAPH <${graphUri}> { ?s a <${classUri}> . ?s ?prop ?o } } GROUP BY ?prop ORDER BY DESC(?count)`);
+        const properties = propResults.results.bindings
+            .filter((b) => b['prop'] && b['count'])
+            .map((b) => ({
+            property: b['prop'].value,
+            count: parseInt(b['count'].value, 10),
+        }));
+        const sampleResults = await this.sparqlQuery(`SELECT ?s ?p ?o WHERE { GRAPH <${graphUri}> { ?s a <${classUri}> . ?s ?p ?o } } LIMIT 5`);
+        const sampleTriples = sampleResults.results.bindings
+            .filter((b) => b['s'] && b['p'] && b['o'])
+            .map((b) => ({
+            s: b['s'].value,
+            p: b['p'].value,
+            o: b['o'].value,
+        }));
+        return { classUri, instanceCount, properties, sampleTriples };
+    }
+}

package/dist/lib/oxigraph.d.ts

@@ -0,0 +1,62 @@
+export interface SparqlResults {
+    head: {
+        vars: string[];
+    };
+    results: {
+        bindings: Array<Record<string, {
+            type: string;
+            value: string;
+            datatype?: string;
+        }>>;
+    };
+}
+export declare function sparqlQuery(endpoint: string, query: string): Promise<SparqlResults>;
+export declare function sparqlUpdate(endpoint: string, update: string): Promise<void>;
+export declare function insertTurtle(endpoint: string, graphUri: string, turtle: string): Promise<void>;
+export declare function getGraphTripleCount(endpoint: string, graphUri: string): Promise<number>;
+/**
+ * Returns true if the query already manages its own graph scoping.
+ * Matches GRAPH, FROM NAMED, or FROM < (case-insensitive).
+ */
+export declare function hasGraphScope(sparql: string): boolean;
+/**
+ * Wraps the WHERE body of a SPARQL SELECT/CONSTRUCT/ASK/DESCRIBE query so
+ * that all triple patterns are scoped to `graphUri`.
+ *
+ * Handles:
+ *   SELECT ... WHERE { ... }          → standard form
+ *   SELECT ... { ... }               → shorthand (no WHERE keyword)
+ *
+ * Returns null if the outermost `{ ... }` block cannot be located safely.
+ */
+export declare function autoScopeQuery(sparql: string, graphUri: string): string | null;
+export declare function dropGraph(endpoint: string, graphUri: string): Promise<void>;
+export declare function deleteTriples(endpoint: string, graphUri: string, options: {
+    turtle?: string;
+    where?: string;
+}): Promise<void>;
+export declare function getSchemaOverview(endpoint: string, graphUri: string): Promise<{
+    prefixes: Record<string, string>;
+    classes: string[];
+    properties: string[];
+    tripleCount: number;
+}>;
+export declare function getClassDetails(endpoint: string, graphUri: string, classUri: string): Promise<{
+    classUri: string;
+    instanceCount: number;
+    properties: Array<{
+        property: string;
+        count: number;
+    }>;
+    sampleTriples: Array<{
+        s: string;
+        p: string;
+        o: string;
+    }>;
+}>;
+export declare function diffGraph(endpoint: string, graphUri: string, localTurtle: string): Promise<{
+    added: string[];
+    removed: string[];
+    unchanged: number;
+}>;
+export declare function exportGraph(endpoint: string, graphUri: string): Promise<string>;