@shapething/typed-sparql 0.1.4

package/README.md

@@ -0,0 +1,5 @@
+# Typed SPARQL
+
+A development toolkit that generates @rdf/js types for SPARQL queries.
+
+It provides a Vite plugin and a standalone CLI version.

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { Parser } from '@traqula/parser-sparql-1-2';
+import { SparqlTypesOptions } from './vite-plugin.ts';
+import type { Literal, NamedNode } from '@rdfjs/types';
+export { typedSparql } from './vite-plugin.ts';
+/**
+ * Finds .rq files in the given directory and all subdirectories, ignoring commonly excluded ones like node_modules and .git. Returns an array of file paths.
+ */
+export declare function findRqFiles(dir: string): string[];
+/**
+ * Pure function: parses a SPARQL query string and returns the `.rq.d.ts` file
+ * content, or `null` if no type declaration can be generated (non-SELECT
+ * queries, SELECT *, parse errors, empty projections).
+ */
+export declare function generateDts(query: string, options: SparqlTypesOptions, parser: Parser): string | null;
+/**
+ * Processes a .rq file, generating a corresponding TypeScript declaration file.
+ * @param rqPath - The path to the .rq file.
+ * @param options - Options for SPARQL type generation.
+ * @param parser - The SPARQL parser instance.
+ */
+export declare function processRqFile(rqPath: string, options: SparqlTypesOptions, parser: Parser): void;
+/**
+ * A helper type representing an RDF literal with a specific datatype IRI. This is used to provide more precise typings for variables that are known to be literals of a certain datatype, such as those narrowed via BOUND() or identified by user-defined function return types.
+ */
+export type LiteralWithDatatype<TDatatype extends string> = Literal & {
+    datatype: NamedNode<TDatatype>;
+};
+/**
+ * Expands a type so that IDEs display the concrete property names instead of
+ * a named alias. Useful for generated query-result interfaces.
+ */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+declare const __queryBrand: unique symbol;
+/**
+ * A SPARQL SELECT query string that carries its result row type as a phantom
+ * type parameter. At runtime this is just a plain string; the type parameter
+ * is erased and only exists for TypeScript inference.
+ *
+ * Generated automatically by the sparql-types Vite plugin for every .rq file.
+ */
+export type TypedQuery<TRow extends object> = string & {
+    readonly [__queryBrand]: TRow;
+};

package/dist/index.js

@@ -0,0 +1,191 @@
+import e from "node:fs";
+import t from "node:path";
+import { Parser as n } from "@traqula/parser-sparql-1-2";
+//#region vite-plugin.ts
+function r(r = {}) {
+	let i = new n();
+	return {
+		name: "typed-sparql",
+		enforce: "pre",
+		buildStart() {
+			let e = t.resolve(process.cwd(), "src");
+			for (let t of g(e)) v(t, r, i), this.addWatchFile(t);
+		},
+		load(t) {
+			if (t.endsWith(".rq")) {
+				let n = e.readFileSync(t, "utf-8");
+				return `export default ${JSON.stringify(n)}\n`;
+			}
+		},
+		watchChange(e, { event: t }) {
+			e.endsWith(".rq") && t !== "delete" && v(e, r, i);
+		}
+	};
+}
+//#endregion
+//#region index.ts
+var i = /* @__PURE__ */ new Set(/* @__PURE__ */ "SELECT.WHERE.FILTER.OPTIONAL.GRAPH.BIND.UNION.MINUS.ORDER.LIMIT.OFFSET.GROUP.HAVING.AS.BY.ASC.DESC.FROM.NAMED.SERVICE.SILENT.VALUES.INSERT.DELETE.WITH.USING.LOAD.CLEAR.DROP.ADD.MOVE.COPY.CREATE.BASE.PREFIX.CONSTRUCT.DESCRIBE.ASK.NOT.IN.EXISTS.DISTINCT.REDUCED.SEPARATOR".split("."));
+function a(e) {
+	let t = /* @__PURE__ */ new Set();
+	for (let n of e.matchAll(/PREFIX\s+(\w*)\s*:/gi)) t.add(n[1]);
+	let n = /* @__PURE__ */ new Set();
+	for (let t of e.matchAll(/\b([a-zA-Z]\w*):[a-zA-Z_]/g)) i.has(t[1].toUpperCase()) || n.add(t[1]);
+	let r = [...n].filter((e) => !t.has(e));
+	return r.length ? `${r.map((e) => `PREFIX ${e}: <http://dummy/${e}/>`).join("\n")}\n${e}` : e;
+}
+function o(e) {
+	return e.prefix ? `${e.prefix}:${e.value}` : e.value;
+}
+var s = {
+	"http://www.w3.org/1999/02/22-rdf-syntax-ns#type": "NamedNode",
+	"rdf:type": "NamedNode",
+	"sh:targetClass": "NamedNode",
+	"sh:targetSubjectsOf": "NamedNode",
+	"sh:targetObjectsOf": "NamedNode",
+	"sh:class": "NamedNode",
+	"sh:datatype": "NamedNode",
+	"sh:nodeKind": "NamedNode"
+};
+function* c(e, t = !1) {
+	for (let n of e) t && n.type === "pattern" && n.subType === "optional" || (yield n, Array.isArray(n.patterns) && (yield* c(n.patterns, t)), n.type === "query" && Array.isArray(n.where?.patterns) && (yield* c(n.where.patterns, t)));
+}
+function l(e) {
+	let t = /* @__PURE__ */ new Set();
+	for (let n of c(e)) n.type === "pattern" && n.subType === "bind" && n.expression?.type === "expression" && n.expression.subType === "operation" && n.expression.operator === "bound" && t.add(n.variable.value);
+	return t;
+}
+function u(e) {
+	let t = /* @__PURE__ */ new Set();
+	for (let n of c(e)) n.type === "pattern" && n.subType === "graph" && n.name?.type === "term" && n.name.subType === "variable" && t.add(n.name.value);
+	return t;
+}
+function d(e) {
+	let t = /* @__PURE__ */ new Set();
+	for (let n of c(e)) if (n.type === "pattern" && n.subType === "bgp") for (let e of n.triples ?? []) {
+		let n = e.subject;
+		n?.type === "term" && n.subType === "variable" && t.add(n.value);
+	}
+	return t;
+}
+function f(e) {
+	let t = /* @__PURE__ */ new Set();
+	for (let n of c(e, !0)) {
+		if (n.type === "pattern" && n.subType === "graph" && n.name?.type === "term" && n.name.subType === "variable" && t.add(n.name.value), n.type === "pattern" && n.subType === "bgp") for (let e of n.triples ?? []) for (let n of [
+			e.subject,
+			e.predicate,
+			e.object
+		]) n?.type === "term" && n.subType === "variable" && t.add(n.value);
+		n.type === "pattern" && n.subType === "bind" && n.variable?.value && t.add(n.variable.value);
+	}
+	return t;
+}
+function p(e, t) {
+	let n = {
+		...s,
+		...t.predicateObjectTypes
+	}, r = /* @__PURE__ */ new Map();
+	for (let t of c(e)) if (t.type === "pattern" && t.subType === "bgp") for (let e of t.triples ?? []) {
+		let t = e.predicate;
+		if (t?.type === "term" && t.subType !== "variable") {
+			let i = n[o(t)];
+			if (i) {
+				let t = e.object;
+				t?.type === "term" && t.subType === "variable" && !r.has(t.value) && r.set(t.value, i);
+			}
+		}
+	}
+	return r;
+}
+function m(e, t, n, r) {
+	let i = /* @__PURE__ */ new Map();
+	for (let a of c(e)) if (a.type === "pattern" && a.subType === "bind") {
+		let e = a.variable?.value;
+		if (e && !n.has(e) && !i.has(e)) {
+			let o = h(a.expression, t, n, r);
+			o !== "NamedNode | BlankNode | Literal" && i.set(e, o);
+		}
+	}
+	return i;
+}
+function h(e, t, n, r) {
+	if (e.type === "term" && e.subType === "variable") {
+		let t = e.value;
+		return n.has(t) ? "LiteralWithDatatype<'http://www.w3.org/2001/XMLSchema#boolean'>" : r.get(t) ?? "NamedNode | BlankNode | Literal";
+	}
+	if (e.type === "expression" && e.subType === "functionCall") {
+		let n = o(e.function);
+		return t.functions?.[n] ?? "Term";
+	}
+	if (e.type === "expression" && e.subType === "aggregate") {
+		let t = e.expression?.[0];
+		return t?.type === "term" && t.subType === "variable" && n.has(t.value) ? "LiteralWithDatatype<'http://www.w3.org/2001/XMLSchema#boolean'>" : "Literal";
+	}
+	return "Term";
+}
+function g(n) {
+	let r = [];
+	try {
+		for (let i of e.readdirSync(n, { withFileTypes: !0 })) {
+			let e = t.join(n, i.name);
+			i.isDirectory() && ![
+				"node_modules",
+				".git",
+				"dist"
+			].includes(i.name) ? r.push(...g(e)) : i.isFile() && i.name.endsWith(".rq") && r.push(e);
+		}
+	} catch {}
+	return r;
+}
+function _(e, t, n) {
+	let r;
+	try {
+		r = n.parse(a(e));
+	} catch {
+		return null;
+	}
+	if (r.type !== "query" || r.subType !== "select") return null;
+	let i = r.where?.patterns ?? [], o = l(i), s = u(i), c = d(i), g = f(i), _ = p(i, t), v = /* @__PURE__ */ new Map();
+	for (let e of c) v.set(e, "NamedNode | BlankNode");
+	for (let [e, t] of _) v.set(e, t);
+	for (let e of s) v.set(e, "NamedNode");
+	let y = m(i, t, o, v), b = [];
+	for (let e of r.variables) {
+		if (e.type === "wildcard") return null;
+		if (e.type === "term" && e.subType === "variable") {
+			let t = s.has(e.value) ? "NamedNode" : o.has(e.value) ? "LiteralWithDatatype<'http://www.w3.org/2001/XMLSchema#boolean'>" : _.get(e.value) ?? (c.has(e.value) ? "NamedNode | BlankNode" : void 0) ?? y.get(e.value) ?? "NamedNode | BlankNode | Literal", n = !g.has(e.value);
+			b.push({
+				name: e.value,
+				tsType: t,
+				optional: n
+			});
+		} else e.type === "pattern" && e.subType === "bind" && b.push({
+			name: e.variable.value,
+			tsType: h(e.expression, t, o, v),
+			optional: !1
+		});
+	}
+	if (!b.length) return null;
+	let x = b.some((e) => e.tsType.includes("LiteralWithDatatype")), S = /* @__PURE__ */ new Set();
+	for (let { tsType: e } of b) e.includes("NamedNode") && S.add("NamedNode"), e.includes("BlankNode") && S.add("BlankNode"), e.includes("Literal") && S.add("Literal"), (e === "Term" || e.includes("| Term") || e.includes("Term |")) && S.add("Term");
+	x && (S.add("Literal"), S.add("NamedNode"));
+	let C = `import type { ${[...S].sort().join(", ")} } from '@rdfjs/types'`, w = ["Prettify", "TypedQuery"];
+	return x && w.push("LiteralWithDatatype"), `/* eslint-disable @typescript-eslint/no-unused-vars */\n${C}\n${`import type { ${w.sort().join(", ")} } from '@shapething/typed-sparql'`}\n\ninterface QueryResult {\n${b.map(({ name: e, tsType: t, optional: n }) => `  ${e}${n ? "?" : ""}: ${t}`).join("\n")}\n}\n\ndeclare const _default: TypedQuery<Prettify<QueryResult>>\nexport default _default\n`;
+}
+function v(t, n, r) {
+	let i;
+	try {
+		i = e.readFileSync(t, "utf-8");
+	} catch {
+		return;
+	}
+	let a;
+	try {
+		a = _(i, n, r);
+	} catch (e) {
+		console.warn(`[sparql-types] Failed to parse ${t}: ${e.message}`);
+		return;
+	}
+	a !== null && e.writeFileSync(`${t}.d.ts`, a, "utf-8");
+}
+//#endregion
+export { g as findRqFiles, _ as generateDts, v as processRqFile, r as typedSparql };

package/dist/vite-plugin.d.ts

@@ -0,0 +1,49 @@
+import type { Plugin } from 'vite';
+/**
+ * Options for the `sparqlTypes` Vite plugin, allowing users to customize the TypeScript types generated for SPARQL queries based on function return types and predicate-object patterns. This enables more precise typings for query results, improving type safety and developer experience when working with SPARQL queries in a TypeScript codebase.
+ */
+export interface SparqlTypesOptions {
+    /**
+     * Map from function IRI or prefixed name to its TypeScript return type string.
+     *
+     * Keys can be:
+     *   - A prefixed name:  `"sta:label"`
+     *   - A full IRI:       `"http://example.org/ns/label"`
+     *
+     * Values are TypeScript type expressions inserted verbatim, e.g.
+     *   `"Literal"`, `"NamedNode"`, `"NamedNode | Literal"`.
+     *
+     * When a function is not listed, `Term` is used as the fallback type.
+     *
+     * @example
+     * sparqlTypes({
+     *   functions: {
+     *     'sta:label': 'Literal',
+     *     'sta:icon':  'Literal',
+     *   },
+     * })
+     */
+    functions?: Record<string, string>;
+    /**
+     * Additional predicate → object TypeScript type rules, merged on top of the
+     * built-in SHACL/RDF rules.
+     *
+     * Keys can be prefixed names or full IRIs (same format as `functions`).
+     * Values are TypeScript type expressions inserted verbatim.
+     *
+     * @example
+     * sparqlTypes({
+     *   predicateObjectTypes: {
+     *     'owl:sameAs': 'NamedNode',
+     *   },
+     * })
+     */
+    predicateObjectTypes?: Record<string, string>;
+}
+/**
+ * A Vite plugin that processes SPARQL query files (.rq) and generates corresponding TypeScript types.
+ * This allows for type-safe usage of SPARQL queries in a TypeScript codebase.
+ * @param options - Options for customizing the generated TypeScript types.
+ * @returns A Vite plugin instance.
+ */
+export declare function typedSparql(options?: SparqlTypesOptions): Plugin;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@shapething/typed-sparql",
+  "version": "0.1.4",
+  "description": "",
+  "license": "GPL-3.0-only",
+  "author": "",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@traqula/parser-sparql-1-2": "^1.0.7"
+  },
+  "devDependencies": {
+    "@rdfjs/types": "^2.0.1",
+    "@types/node": "^22.15.29",
+    "vite": "^8.0.8",
+    "vite-tsconfig-paths": "^6.1.1",
+    "vitest": "^4.1.4"
+  }
+}