@oxilite/d1 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# @oxilite/d1
+
+An Oxigraph-compatible SPARQL 1.1 store on a Cloudflare D1 database. The oxilite core runs as WebAssembly: SPARQL is compiled to SQL and sent to your `env.DB` binding, so every query is one D1 call and every update is one atomic batch.
+
+```ts
+import { D1Store } from "@oxilite/d1";
+import wasm from "@oxilite/d1/oxilite.wasm";
+
+export default {
+  async fetch(req: Request, env: { DB: D1Database }) {
+    const store = await D1Store.open(env.DB, { wasm, migrated: true });
+    const q = new URL(req.url).searchParams.get("query") ?? "SELECT * WHERE { ?s ?p ?o } LIMIT 10";
+    return new Response(await store.queryJson(q), { headers: { "content-type": "application/sparql-results+json" } });
+  },
+};
+```
+
+Create the schema as a migration with `npx oxilite-d1 schema > migrations/0001_oxilite.sql`. In Node (tests, Miniflare), import from `@oxilite/d1/node`.
+
+The API mirrors Oxigraph's JavaScript `Store` (`query`, `update`, `load`, `dump`, `add`, `delete`, `has`, `match`, `size`), asynchronously, plus `explain`, `bulkLoad`, `optimize`, `materialize` (OWL 2 RL) and query options for RDFS / OWL reasoning and full-text search. See the [oxilite repository](https://github.com/Volland/oxilite).

package/bin/oxilite-d1.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Usage: npx oxilite-d1 schema [--no-graph-index] > migrations/0001_oxilite.sql
+import { D1Store } from "../dist/node.js";
+
+const [command, ...args] = process.argv.slice(2);
+if (command === "schema") {
+  process.stdout.write(D1Store.schemaSql({ graphIndex: !args.includes("--no-graph-index") }));
+} else {
+  console.error("usage: oxilite-d1 schema [--no-graph-index]");
+  process.exit(1);
+}

package/dist/driver.d.ts

@@ -0,0 +1,102 @@
+import { type DumpOptions, type LoadData, type LoadOptions, type Quad, type QueryOptions, type QueryResult, type TermLike } from "@oxilite/common";
+/** The subset of the Cloudflare D1 binding API used by oxilite. */
+export interface D1PreparedStatementLike {
+    raw(): Promise<unknown[][]>;
+}
+export interface D1ResultLike {
+    results?: Record<string, unknown>[];
+    meta?: {
+        changes?: number;
+    };
+}
+export interface D1DatabaseLike {
+    prepare(sql: string): D1PreparedStatementLike;
+    batch(statements: D1PreparedStatementLike[]): Promise<D1ResultLike[]>;
+}
+/** The wasm engine API (generated by wasm-bindgen from crates/oxilite-wasm). */
+export interface WasmJob {
+    step(response?: string | null): string;
+    free?(): void;
+}
+export interface WasmEngine {
+    open(): WasmJob;
+    openExisting(): WasmJob;
+    optimize(): WasmJob;
+    query(sparql: string, options?: string | null): WasmJob;
+    queryJson(sparql: string): WasmJob;
+    explain(sparql: string): string;
+    update(sparql: string, baseIri?: string | null): WasmJob;
+    explainUpdate(sparql: string): string;
+    load(data: string, format: string, base?: string | null, graph?: string | null): WasmJob;
+    bulkLoad(data: string, format: string, base?: string | null, graph?: string | null): WasmJob;
+    add(quads: string): WasmJob;
+    delete(quads: string): WasmJob;
+    has(quad: string): WasmJob;
+    match(s?: string | null, p?: string | null, o?: string | null, g?: string | null): WasmJob;
+    size(): WasmJob;
+    dump(format: string, graph?: string | null): WasmJob;
+    clear(): WasmJob;
+    materialize(): WasmJob;
+    clearInferences(): WasmJob;
+    schemaSql(): string;
+}
+export type EngineConstructor = new (capabilities?: string | null, options?: string | null) => WasmEngine;
+/** A term hash collision (two different terms with the same 59-bit id). */
+export declare class OxiliteCollisionError extends Error {
+}
+export interface D1StoreOptions {
+    /** Create the optional graph index (default true); only used when the schema is created. */
+    graphIndex?: boolean;
+    /** The schema was applied by a migration: open without DDL. */
+    migrated?: boolean;
+    /** Create the FTS5 full-text index over string literals (for `oxl:textMatch`). */
+    textIndex?: boolean;
+}
+/** An oxilite RDF store on a Cloudflare D1 database. */
+export declare class D1Store {
+    readonly db: D1DatabaseLike;
+    private readonly engine;
+    private constructor();
+    static openWith(Engine: EngineConstructor, db: D1DatabaseLike, options?: D1StoreOptions): Promise<D1Store>;
+    private execute;
+    private run;
+    /** SPARQL query: `Map[]` for SELECT, `boolean` for ASK, `Quad[]` for CONSTRUCT/DESCRIBE, or a string with `results_format`. */
+    query(query: string, options?: QueryOptions): Promise<QueryResult>;
+    /** SPARQL query returning SPARQL 1.1 JSON results. */
+    queryJson(query: string): Promise<string>;
+    /** The SQL a query compiles to, with join orders and warnings. */
+    explain(query: string): string;
+    /** SPARQL update, applied atomically in one D1 batch. */
+    update(update: string, options?: {
+        base_iri?: string;
+    }): Promise<void>;
+    /** How an update runs (SQL per operation). */
+    explainUpdate(update: string): string;
+    /** Loads RDF atomically (one batch); use `bulkLoad` for large documents. */
+    load(data: LoadData, options: LoadOptions): Promise<void>;
+    /** Loads RDF in several batches (not atomic) and refreshes planner statistics. */
+    bulkLoad(data: LoadData, options: LoadOptions): Promise<void>;
+    /** Serializes the dataset or one graph. */
+    dump(options: DumpOptions): Promise<string>;
+    add(quad: TermLike): Promise<void>;
+    /** Inserts many quads atomically. */
+    addAll(quads: TermLike[]): Promise<void>;
+    delete(quad: TermLike): Promise<void>;
+    has(quad: TermLike): Promise<boolean>;
+    match(subject?: TermLike | null, predicate?: TermLike | null, object?: TermLike | null, graph?: TermLike | null): Promise<Quad[]>;
+    /** Number of quads. */
+    size(): Promise<number>;
+    /**
+     * Computes the OWL 2 RL closure into a separate inference table with SQL rules (one D1
+     * batch per round; not atomic as a whole). Query it with `include_inferred: true`.
+     * Returns the number of inferred triples.
+     */
+    materialize(): Promise<number>;
+    /** Removes every materialized inference. */
+    clearInferences(): Promise<void>;
+    /** Refreshes planner statistics (run after large imports). */
+    optimize(): Promise<void>;
+    clear(): Promise<void>;
+    /** The schema SQL of this store (for `wrangler d1 migrations`). */
+    schemaSql(): string;
+}

package/dist/driver.js

@@ -0,0 +1,161 @@
+// The D1 driver: runs the oxilite core's SQL requests on a Cloudflare D1 binding.
+//
+// The core (WebAssembly) never touches the database. Each operation is a job: the driver
+// feeds it the response of every request it asks for, until it is done. Atomic requests
+// become one `db.batch()` — D1's only transaction.
+import { loadDataToString, outputToResult, toJson, } from "@oxilite/common";
+/** A term hash collision (two different terms with the same 59-bit id). */
+export class OxiliteCollisionError extends Error {
+}
+function mapError(e) {
+    const message = e instanceof Error ? e.message : String(e);
+    if (message.includes("oxilite: term hash collision"))
+        return new OxiliteCollisionError(message);
+    if (message.includes("graph_does_not_exist"))
+        return new Error("the graph does not exist");
+    if (message.includes("graph_already_exists"))
+        return new Error("the graph already exists");
+    if (message.includes("computed_value_not_storable")) {
+        return new Error("an update template stores a computed non-integer value, which cannot be done on D1");
+    }
+    return e instanceof Error ? e : new Error(message);
+}
+/** An oxilite RDF store on a Cloudflare D1 database. */
+export class D1Store {
+    db;
+    engine;
+    constructor(db, engine) {
+        this.db = db;
+        this.engine = engine;
+    }
+    static async openWith(Engine, db, options = {}) {
+        const engine = new Engine(null, JSON.stringify({ graphIndex: options.graphIndex ?? true, textIndex: options.textIndex ?? false }));
+        const store = new D1Store(db, engine);
+        await store.run(options.migrated ? engine.openExisting() : engine.open());
+        return store;
+    }
+    async execute(req) {
+        try {
+            if (req.statements.length === 0)
+                return [];
+            if (req.mode === "read" && req.statements.length === 1) {
+                const rows = await this.db.prepare(req.statements[0].sql).raw();
+                return [{ rows, changes: 0 }];
+            }
+            const results = await this.db.batch(req.statements.map((s) => this.db.prepare(s.sql)));
+            return results.map((r) => ({
+                rows: (r.results ?? []).map((row) => Object.values(row)),
+                changes: r.meta?.changes ?? 0,
+            }));
+        }
+        catch (e) {
+            throw mapError(e);
+        }
+    }
+    async run(job) {
+        try {
+            let response = null;
+            for (;;) {
+                const step = JSON.parse(job.step(response));
+                if (step.done !== undefined)
+                    return step.done;
+                response = JSON.stringify(await this.execute(step.execute));
+            }
+        }
+        finally {
+            job.free?.();
+        }
+    }
+    /** SPARQL query: `Map[]` for SELECT, `boolean` for ASK, `Quad[]` for CONSTRUCT/DESCRIBE, or a string with `results_format`. */
+    async query(query, options = {}) {
+        const js = {
+            ...options,
+            default_graph: options.default_graph
+                ? Array.isArray(options.default_graph)
+                    ? options.default_graph.map(toJson)
+                    : toJson(options.default_graph)
+                : undefined,
+            named_graphs: options.named_graphs?.map(toJson),
+        };
+        return outputToResult(await this.run(this.engine.query(query, JSON.stringify(js))));
+    }
+    /** SPARQL query returning SPARQL 1.1 JSON results. */
+    async queryJson(query) {
+        const out = await this.run(this.engine.queryJson(query));
+        return out.value;
+    }
+    /** The SQL a query compiles to, with join orders and warnings. */
+    explain(query) {
+        return this.engine.explain(query);
+    }
+    /** SPARQL update, applied atomically in one D1 batch. */
+    async update(update, options = {}) {
+        await this.run(this.engine.update(update, options.base_iri ?? null));
+    }
+    /** How an update runs (SQL per operation). */
+    explainUpdate(update) {
+        return this.engine.explainUpdate(update);
+    }
+    /** Loads RDF atomically (one batch); use `bulkLoad` for large documents. */
+    async load(data, options) {
+        const graph = options.to_graph_name ? JSON.stringify(toJson(options.to_graph_name)) : null;
+        const text = loadDataToString(data);
+        const job = options.no_transaction
+            ? this.engine.bulkLoad(text, options.format, options.base_iri ?? null, graph)
+            : this.engine.load(text, options.format, options.base_iri ?? null, graph);
+        await this.run(job);
+    }
+    /** Loads RDF in several batches (not atomic) and refreshes planner statistics. */
+    async bulkLoad(data, options) {
+        await this.load(data, { ...options, no_transaction: true });
+    }
+    /** Serializes the dataset or one graph. */
+    async dump(options) {
+        const graph = options.from_graph_name ? JSON.stringify(toJson(options.from_graph_name)) : null;
+        return (await this.run(this.engine.dump(options.format, graph))).value;
+    }
+    async add(quad) {
+        await this.run(this.engine.add(JSON.stringify([toJson(quad)])));
+    }
+    /** Inserts many quads atomically. */
+    async addAll(quads) {
+        await this.run(this.engine.add(JSON.stringify(quads.map(toJson))));
+    }
+    async delete(quad) {
+        await this.run(this.engine.delete(JSON.stringify([toJson(quad)])));
+    }
+    async has(quad) {
+        return (await this.run(this.engine.has(JSON.stringify(toJson(quad))))).value;
+    }
+    async match(subject, predicate, object, graph) {
+        const j = (t) => (t ? JSON.stringify(toJson(t)) : null);
+        return outputToResult(await this.run(this.engine.match(j(subject), j(predicate), j(object), j(graph))));
+    }
+    /** Number of quads. */
+    async size() {
+        return (await this.run(this.engine.size())).value;
+    }
+    /**
+     * Computes the OWL 2 RL closure into a separate inference table with SQL rules (one D1
+     * batch per round; not atomic as a whole). Query it with `include_inferred: true`.
+     * Returns the number of inferred triples.
+     */
+    async materialize() {
+        return (await this.run(this.engine.materialize())).value;
+    }
+    /** Removes every materialized inference. */
+    async clearInferences() {
+        await this.run(this.engine.clearInferences());
+    }
+    /** Refreshes planner statistics (run after large imports). */
+    async optimize() {
+        await this.run(this.engine.optimize());
+    }
+    async clear() {
+        await this.run(this.engine.clear());
+    }
+    /** The schema SQL of this store (for `wrangler d1 migrations`). */
+    schemaSql() {
+        return this.engine.schemaSql();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { D1Store as Base, type D1DatabaseLike, type D1StoreOptions } from "./driver.js";
+export * from "@oxilite/common";
+export { OxiliteCollisionError, type D1DatabaseLike, type D1StoreOptions } from "./driver.js";
+/** Initializes the WebAssembly core (a `WebAssembly.Module`, bytes, or a URL/Response). */
+export declare function initOxilite(wasm?: WebAssembly.Module | BufferSource | Response | URL | string): Promise<void>;
+export declare class D1Store {
+    /** Opens (and, unless `migrated`, creates) the oxilite schema on a D1 binding. */
+    static open(db: D1DatabaseLike, options?: D1StoreOptions & {
+        wasm?: WebAssembly.Module | BufferSource | Response | URL | string;
+    }): Promise<Base>;
+    /** The schema as SQL (for `wrangler d1 migrations`). */
+    static schemaSql(options?: {
+        graphIndex?: boolean;
+        wasm?: WebAssembly.Module | BufferSource;
+    }): Promise<string>;
+}

package/dist/index.js

@@ -0,0 +1,35 @@
+// @oxilite/d1 for Cloudflare Workers (and other WebAssembly hosts).
+//
+// In a Worker, import the wasm module and pass it once:
+//   import wasm from "@oxilite/d1/oxilite.wasm";
+//   const store = await D1Store.open(env.DB, { wasm });
+import init, { Engine, initSync } from "../wasm/web/oxilite_wasm.js";
+import { D1Store as Base } from "./driver.js";
+export * from "@oxilite/common";
+export { OxiliteCollisionError } from "./driver.js";
+let ready = false;
+/** Initializes the WebAssembly core (a `WebAssembly.Module`, bytes, or a URL/Response). */
+export async function initOxilite(wasm) {
+    if (ready)
+        return;
+    if (wasm instanceof WebAssembly.Module || ArrayBuffer.isView(wasm) || wasm instanceof ArrayBuffer) {
+        initSync({ module: wasm });
+    }
+    else {
+        await init(wasm === undefined ? undefined : { module_or_path: wasm });
+    }
+    ready = true;
+}
+export class D1Store {
+    /** Opens (and, unless `migrated`, creates) the oxilite schema on a D1 binding. */
+    static async open(db, options = {}) {
+        await initOxilite(options.wasm);
+        return Base.openWith(Engine, db, options);
+    }
+    /** The schema as SQL (for `wrangler d1 migrations`). */
+    static async schemaSql(options = {}) {
+        await initOxilite(options.wasm);
+        const e = new Engine(null, JSON.stringify({ graphIndex: options.graphIndex ?? true }));
+        return e.schemaSql();
+    }
+}

package/dist/node.d.ts

@@ -0,0 +1,9 @@
+import { D1Store as Base, type D1DatabaseLike, type D1StoreOptions } from "./driver.js";
+export * from "@oxilite/common";
+export { OxiliteCollisionError, type D1DatabaseLike, type D1StoreOptions } from "./driver.js";
+export declare class D1Store {
+    static open(db: D1DatabaseLike, options?: D1StoreOptions): Promise<Base>;
+    static schemaSql(options?: {
+        graphIndex?: boolean;
+    }): string;
+}

package/dist/node.js

@@ -0,0 +1,15 @@
+// @oxilite/d1 for Node.js (tests, scripts, Miniflare): the WebAssembly core loads itself.
+import { createRequire } from "node:module";
+import { D1Store as Base } from "./driver.js";
+export * from "@oxilite/common";
+export { OxiliteCollisionError } from "./driver.js";
+const require = createRequire(import.meta.url);
+const { Engine } = require("../wasm/node/oxilite_wasm.js");
+export class D1Store {
+    static async open(db, options = {}) {
+        return Base.openWith(Engine, db, options);
+    }
+    static schemaSql(options = {}) {
+        return new Engine(null, JSON.stringify({ graphIndex: options.graphIndex ?? true })).schemaSql();
+    }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@oxilite/d1",
+  "version": "0.1.0",
+  "description": "oxilite on Cloudflare D1: an Oxigraph-compatible SPARQL store running on a D1 binding",
+  "license": "MIT OR Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/node.js",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./oxilite.wasm": "./wasm/web/oxilite_wasm_bg.wasm"
+  },
+  "bin": {
+    "oxilite-d1": "bin/oxilite-d1.mjs"
+  },
+  "files": [
+    "dist",
+    "wasm",
+    "bin"
+  ],
+  "scripts": {
+    "build:wasm": "cargo build -p oxilite-wasm --target wasm32-unknown-unknown --profile wasm-release && wasm-bindgen --target nodejs --out-dir wasm/node ../../target/wasm32-unknown-unknown/wasm-release/oxilite_wasm.wasm && wasm-bindgen --target web --out-dir wasm/web ../../target/wasm32-unknown-unknown/wasm-release/oxilite_wasm.wasm && echo {\\\"type\\\":\\\"commonjs\\\"} > wasm/node/package.json",
+    "build": "tsc -p .",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@oxilite/common": "0.1.0"
+  },
+  "devDependencies": {
+    "miniflare": "^4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Volland/oxilite.git",
+    "directory": "packages/d1"
+  },
+  "homepage": "https://github.com/Volland/oxilite#readme",
+  "bugs": "https://github.com/Volland/oxilite/issues",
+  "author": "Volodymyr Pavlyshyn",
+  "keywords": [
+    "rdf",
+    "sparql",
+    "sqlite",
+    "oxigraph",
+    "rdfjs",
+    "cloudflare",
+    "d1",
+    "workers"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/wasm/node/oxilite_wasm.d.ts

@@ -0,0 +1,113 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * The oxilite engine for one database.
+ */
+export class Engine {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Inserts quads (JSON array of RDF/JS quads) atomically.
+     */
+    add(quads: string): Job;
+    /**
+     * Loads a document in several batches (not atomic), then refreshes statistics.
+     */
+    bulkLoad(data: string, format_name: string, base?: string | null, graph?: string | null): Job;
+    /**
+     * Removes every materialized inference.
+     */
+    clearInferences(): Job;
+    /**
+     * Removes everything.
+     */
+    clear(): Job;
+    /**
+     * Removes quads (JSON array of RDF/JS quads) atomically.
+     */
+    delete(quads: string): Job;
+    /**
+     * Serializes the dataset (or one graph, JSON graph term) in an RDF format.
+     */
+    dump(format_name: string, graph?: string | null): Job;
+    /**
+     * How an update would run (SQL per operation).
+     */
+    explainUpdate(sparql: string): string;
+    /**
+     * The SQL a query compiles to, with the planner's notes.
+     */
+    explain(sparql: string): string;
+    /**
+     * Does the store contain a quad (JSON RDF/JS quad)?
+     */
+    has(quad: string): Job;
+    /**
+     * Loads a document atomically (one batch). `graph` is a JSON graph term.
+     */
+    load(data: string, format_name: string, base?: string | null, graph?: string | null): Job;
+    /**
+     * Quads matching a pattern; each argument is a JSON term or null.
+     */
+    match(subject?: string | null, predicate?: string | null, object?: string | null, graph?: string | null): Job;
+    /**
+     * Computes the OWL 2 RL closure into the inference table (one batch per rule round);
+     * the result is `{"kind": "number"}`, the number of inferred triples.
+     */
+    materialize(): Job;
+    /**
+     * `capabilities` (JSON, optional) defaults to Cloudflare D1's; `options` (JSON,
+     * optional) are the store options, e.g. `{"graphIndex": false}`.
+     */
+    constructor(capabilities?: string | null, options?: string | null);
+    /**
+     * Loads planner statistics only (schema applied by a migration).
+     */
+    openExisting(): Job;
+    /**
+     * Creates the schema if needed and loads planner statistics.
+     */
+    open(): Job;
+    /**
+     * Recomputes planner statistics.
+     */
+    optimize(): Job;
+    /**
+     * A SPARQL query whose result is SPARQL 1.1 JSON results (`{"kind": "text", "value"}`).
+     */
+    queryJson(sparql: string): Job;
+    /**
+     * A SPARQL query. `options` (JSON) uses Oxigraph's JS names: `base_iri`,
+     * `use_default_graph_as_union`, `default_graph`, `named_graphs`, `results_format`. The
+     * result is `oxilite_core::json::output_to_json`, or `{"kind": "text"}` when a
+     * `results_format` is given.
+     */
+    query(sparql: string, options?: string | null): Job;
+    /**
+     * The schema as a SQL script (for `wrangler d1 migrations`).
+     */
+    schemaSql(): string;
+    /**
+     * Number of quads.
+     */
+    size(): Job;
+    /**
+     * A SPARQL update, applied as one atomic request (one D1 batch).
+     */
+    update(sparql: string, base_iri?: string | null): Job;
+}
+
+/**
+ * A resumable operation (see the crate documentation).
+ */
+export class Job {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Advances the job: `response` is the JSON response to the previous request (or null).
+     * Returns `{"execute": request}` or `{"done": value}` as JSON.
+     */
+    step(response?: string | null): string;
+}