lazy-sparql-result-reader 0.1.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ioannis Nezis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+<h1 align="center">
+  lazy-sparql-result-reader
+</h1>
+
+<div align="center">
+    <a href="https://www.npmjs.com/package/lazy-sparql-result-reader">
+        <img alt="npm" src="https://img.shields.io/npm/v/lazy-sparql-result-reader" />
+    </a>
+</div>
+
+A fast SPARQL results parser for JavaScript and TypeScript, compiled from Rust via WebAssembly.  
+It reads streamed SPARQL query results and calls a callback for each parsed batch of bindings.
+
+---
+
+## Features
+
+- Processes streaming SPARQL results efficiently.
+- Calls a JavaScript callback for each batch of parsed bindings.
+- Written in Rust for speed and reliability.
+- Fully compatible with TypeScript.
+
+---
+
+
+## Usage Example
+
+### 1. Install dependencies
+
+```bash
+npm install  lazy-sparql-result-reader vite @vitejs/plugin-wasm
+```
+
+### 2. Configure Vite for WASM
+
+Create or update vite.config.ts:
+
+```bash
+import { defineConfig } from 'vite';
+import wasm from '@vitejs/plugin-wasm';
+
+export default defineConfig({
+  plugins: [wasm()],
+});
+```
+
+This allows Vite to correctly load WebAssembly modules.
+
+### 3. Use the parser in your app
+
+```ts
+import init, { read } from "lazy-sparql-result-reader?init";
+
+// Initialize the WASM module
+await init();
+
+fetch("https://qlever.dev/api/wikidata", {
+  method: 'POST',
+  headers: {
+    "Accept": "application/sparql-results+json",
+    "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+  },
+  body: new URLSearchParams({
+    query: "SELECT * {?s ?p ?o} LIMIT 1000",
+  })
+})
+.then(async response => {
+  if (!response.ok) {
+    throw new Error(`SPARQL request failed: ${response.status}`);
+  }
+  const stream = response.body; // ReadableStream of the SPARQL JSON results
+  if (!stream) throw new Error("Response has no body stream");
+  // Parse the streamed results with the WASM parser
+  await read(stream, 100, (bindings) => {
+    console.log("Received batch of bindings:", bindings);
+  });
+})
+.catch((err) => {
+  console.error("Error fetching or parsing SPARQL results:", err);
+});
+```
+
+## Notes
+
+- The **first callback invocation** contains the **SPARQL head**, i.e., the variable names in the result set.
+- Subsequent callback invocations contain batches of bindings as they are parsed.
+- `batch_size` controls how many bindings are buffered before each callback.
+- Ensure your environment supports **ReadableStream** (modern browsers or Node.js >= 18).
+
+This setup allows your JS/TS application to process **streaming SPARQL results** efficiently,  
+with immediate access to the head and incremental batches of bindings.
+
+## License
+
+This project is licensed under the **MIT** License.
+
+You are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software, under the conditions of the MIT License.
+
+For full details, see the [LICENSE](./LICENSE) file.

package/lazy_sparql_result_reader.d.ts

@@ -11,12 +11,12 @@ export interface InitOutput {
   readonly wasm_bindgen__convert__closures_____invoke__h53040b977ccf16ad: (a: number, b: number, c: any) => void;
   readonly wasm_bindgen__closure__destroy__h9431bfc0c26898f5: (a: number, b: number) => void;
   readonly wasm_bindgen__convert__closures_____invoke__h0204f368625abfd5: (a: number, b: number, c: any, d: any) => void;
+  readonly __wbindgen_malloc: (a: number, b: number) => number;
+  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
   readonly __wbindgen_exn_store: (a: number) => void;
   readonly __externref_table_alloc: () => number;
   readonly __wbindgen_externrefs: WebAssembly.Table;
   readonly __wbindgen_free: (a: number, b: number, c: number) => void;
-  readonly __wbindgen_malloc: (a: number, b: number) => number;
-  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
   readonly __wbindgen_start: () => void;
 }
 

package/lazy_sparql_result_reader.js

@@ -10,6 +10,71 @@ const CLOSURE_DTORS = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(state => state.dtor(state.a, state.b));
 
+function debugString(val) {
+    // primitive types
+    const type = typeof val;
+    if (type == 'number' || type == 'boolean' || val == null) {
+        return  `${val}`;
+    }
+    if (type == 'string') {
+        return `"${val}"`;
+    }
+    if (type == 'symbol') {
+        const description = val.description;
+        if (description == null) {
+            return 'Symbol';
+        } else {
+            return `Symbol(${description})`;
+        }
+    }
+    if (type == 'function') {
+        const name = val.name;
+        if (typeof name == 'string' && name.length > 0) {
+            return `Function(${name})`;
+        } else {
+            return 'Function';
+        }
+    }
+    // objects
+    if (Array.isArray(val)) {
+        const length = val.length;
+        let debug = '[';
+        if (length > 0) {
+            debug += debugString(val[0]);
+        }
+        for(let i = 1; i < length; i++) {
+            debug += ', ' + debugString(val[i]);
+        }
+        debug += ']';
+        return debug;
+    }
+    // Test for built-in
+    const builtInMatches = /\[object ([^\]]+)\]/.exec(toString.call(val));
+    let className;
+    if (builtInMatches && builtInMatches.length > 1) {
+        className = builtInMatches[1];
+    } else {
+        // Failed to match the standard '[object ClassName]'
+        return toString.call(val);
+    }
+    if (className == 'Object') {
+        // we're a user defined class or Object
+        // JSON.stringify avoids problems with cycles, and is generally much
+        // easier than looping through ownProperties of `val`.
+        try {
+            return 'Object(' + JSON.stringify(val) + ')';
+        } catch (_) {
+            return 'Object';
+        }
+    }
+    // errors
+    if (val instanceof Error) {
+        return `${val.name}: ${val.message}\n${val.stack}`;
+    }
+    // TODO we could test for more things here, like `Set`s and `Map`s.
+    return className;
+}
+
 function getArrayU8FromWasm0(ptr, len) {
     ptr = ptr >>> 0;
     return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
@@ -201,11 +266,22 @@ function __wbg_get_imports() {
         const ret = Error(getStringFromWasm0(arg0, arg1));
         return ret;
     };
+    imports.wbg.__wbg_Number_2d1dcfcf4ec51736 = function(arg0) {
+        const ret = Number(arg0);
+        return ret;
+    };
     imports.wbg.__wbg___wbindgen_boolean_get_dea25b33882b895b = function(arg0) {
         const v = arg0;
         const ret = typeof(v) === 'boolean' ? v : undefined;
         return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
     };
+    imports.wbg.__wbg___wbindgen_debug_string_adfb662ae34724b6 = function(arg0, arg1) {
+        const ret = debugString(arg1);
+        const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+        getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+    };
     imports.wbg.__wbg___wbindgen_is_function_8d400b8b1af978cd = function(arg0) {
         const ret = typeof(arg0) === 'function';
         return ret;
@@ -379,8 +455,8 @@ function __wbg_get_imports() {
         const ret = getStringFromWasm0(arg0, arg1);
         return ret;
     };
-    imports.wbg.__wbindgen_cast_d2d0cc24b1b6ed59 = function(arg0, arg1) {
-        // Cast intrinsic for `Closure(Closure { dtor_idx: 42, function: Function { arguments: [Externref], shim_idx: 43, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+    imports.wbg.__wbindgen_cast_27d8f2a9ce018ee0 = function(arg0, arg1) {
+        // Cast intrinsic for `Closure(Closure { dtor_idx: 43, function: Function { arguments: [Externref], shim_idx: 44, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
         const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h9431bfc0c26898f5, wasm_bindgen__convert__closures_____invoke__h53040b977ccf16ad);
         return ret;
     };

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "lazy-sparql-result-reader",
   "type": "module",
-  "version": "0.1.0",
+  "description": "A lazy sparql result reader",
+  "version": "1.0.1",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IoannisNezis/Lazy-SPARQL-result-reader"
+  },
   "files": [
     "lazy_sparql_result_reader_bg.wasm",
     "lazy_sparql_result_reader.js",