@blackcatinformatics/purrdf 0.4.3 → 0.5.0

package/README.md

@@ -73,7 +73,7 @@ const names = engine.select(
   reparsed,
   "SELECT ?message WHERE { <https://ex/s> <https://ex/says> ?message }",
 );
-console.log(names.rows[0].message.value);
+console.log(names.rows.take(0)?.message.value);
 ```
 
 ## API surface
@@ -95,7 +95,9 @@ console.log(names.rows[0].message.value);
 - `QueryEngine` — a reusable SPARQL execution context with a native plan cache,
   typed `select` / `ask` / `construct` / `describe` helpers, atomic `update`,
   and `queryRaw` serialization for SPARQL Results JSON/XML/CSV/TSV plus graph
-  formats. `Dataset.query(...)` remains as the compatibility raw-string helper.
+  formats. SELECT `rows` are a single-owner iterable; use `take(index)`,
+  `toArray()`, or iteration, and call `free()` when abandoning unconsumed rows.
+  `Dataset.query(...)` remains as the compatibility raw-string helper.
 - `shaclValidateToSarif(shapesTtl, dataNt)` / `shaclEntail(shapesTtl, dataNt)` — SHACL
   validation to a SARIF 2.1.0 report and SHACL-AF `sh:rule` entailment to N-Triples.
 - `Sink`, `datasetToStream`, `streamToDataset` — the async RDF/JS

package/index.d.ts

@@ -63,10 +63,26 @@ export interface QueryRawOptions extends QueryOptions {
 
 export type QueryBindingRow = Record<string, RdfTerm | undefined>;
 
+export interface QueryBindingRows extends IterableIterator<QueryBindingRow> {
+  /** Total row count, including rows already consumed. */
+  readonly length: number;
+  /** Rows not yet consumed. */
+  readonly remaining: number;
+  /** Move one row out by result index. Each index can be consumed once. */
+  take(index: number): QueryBindingRow | undefined;
+  /** Materialize all remaining rows and exhaust the stream. */
+  toArray(): QueryBindingRow[];
+  /** Release unconsumed wasm result storage. */
+  free(): void;
+}
+
 export interface SelectResult {
   readonly kind: "select";
   readonly variables: string[];
-  readonly rows: QueryBindingRow[];
+  readonly rowCount: number;
+  readonly rows: QueryBindingRows;
+  /** Release unconsumed wasm result storage. */
+  free(): void;
 }
 
 export interface AskResult {

package/index.mjs

@@ -70,21 +70,63 @@ function visualizationOptionsJson(options) {
 
 function selectResultToObject(raw) {
   const variables = raw.variables;
-  const rawRows = raw.rows;
-  try {
-    const rows = rawRows.map((row) => {
+  const length = raw.rowCount;
+  let closed = false;
+
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    raw.free?.();
+  };
+  if (length === 0) close();
+  const materialize = (row) => {
+    try {
       const out = Object.create(null);
-      for (const variable of variables) {
-        const value = row.get(variable);
+      for (let index = 0; index < variables.length; index += 1) {
+        const variable = variables[index];
+        const value = row.takeValue(index);
         if (value !== undefined) out[variable] = value;
       }
       return out;
-    });
-    return { kind: "select", variables, rows };
-  } finally {
-    for (const row of rawRows) row.free?.();
-    raw.free?.();
-  }
+    } finally {
+      row.free?.();
+      if (raw.remaining === 0) close();
+    }
+  };
+  const rows = {
+    get length() {
+      return length;
+    },
+    get remaining() {
+      return closed ? 0 : raw.remaining;
+    },
+    take(index) {
+      if (closed) return undefined;
+      const row = raw.takeRow(index);
+      return row === undefined ? undefined : materialize(row);
+    },
+    next() {
+      if (closed) return { done: true, value: undefined };
+      const row = raw.nextRow();
+      if (row === undefined) {
+        close();
+        return { done: true, value: undefined };
+      }
+      return { done: false, value: materialize(row) };
+    },
+    return() {
+      close();
+      return { done: true, value: undefined };
+    },
+    toArray() {
+      return Array.from(this);
+    },
+    free: close,
+    [Symbol.iterator]() {
+      return this;
+    },
+  };
+  return { kind: "select", variables, rowCount: length, rows, free: close };
 }
 
 function queryResultToObject(raw) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackcatinformatics/purrdf",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "A wasm32, in-memory RDF 1.2 engine with an idiomatic RDF/JS (DataFactory/Dataset/Stream) API. Quoted-triple terms and directional literals included.",
   "type": "module",
   "license": "MIT OR Apache-2.0",

package/pkg/purrdf_wasm.d.ts

@@ -282,14 +282,26 @@ export class SelectResult {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Move the next unconsumed row out of the result.
+     */
+    nextRow(): SelectRow | undefined;
+    /**
+     * Move a row out by result index. Each row can be consumed once.
+     */
+    takeRow(index: number): SelectRow | undefined;
     /**
      * The result discriminator.
      */
     readonly kind: string;
     /**
-     * SELECT rows, one object-like row per solution.
+     * Number of rows that have not yet been consumed.
      */
-    readonly rows: SelectRow[];
+    readonly remaining: number;
+    /**
+     * Total number of SELECT rows, including rows already consumed.
+     */
+    readonly rowCount: number;
     /**
      * Projected variables, in SELECT projection order.
      */
@@ -307,6 +319,11 @@ export class SelectRow {
      * Return the bound term for a variable name, or `undefined` for unbound/absent.
      */
     get(variable: string): Term | undefined;
+    /**
+     * Move one value out by projection index, or return `undefined` when the
+     * cell is unbound, absent, or was already consumed.
+     */
+    takeValue(index: number): Term | undefined;
     /**
      * Variables projected by this row, in SELECT projection order.
      */
@@ -474,9 +491,13 @@ export interface InitOutput {
     readonly queryresult_takeDataset: (a: number) => number;
     readonly queryresult_takeSelect: (a: number) => number;
     readonly selectresult_kind: (a: number, b: number) => void;
-    readonly selectresult_rows: (a: number, b: number) => void;
+    readonly selectresult_nextRow: (a: number) => number;
+    readonly selectresult_remaining: (a: number) => number;
+    readonly selectresult_row_count: (a: number) => number;
+    readonly selectresult_takeRow: (a: number, b: number) => number;
     readonly selectresult_variables: (a: number, b: number) => void;
     readonly selectrow_get: (a: number, b: number, c: number) => number;
+    readonly selectrow_takeValue: (a: number, b: number) => number;
     readonly selectrow_variables: (a: number, b: number) => void;
     readonly shaclEntail: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly shaclValidateToSarif: (a: number, b: number, c: number, d: number, e: number) => void;

package/pkg/purrdf_wasm.js

@@ -1112,21 +1112,37 @@ export class SelectResult {
         }
     }
     /**
-     * SELECT rows, one object-like row per solution.
-     * @returns {SelectRow[]}
+     * Move the next unconsumed row out of the result.
+     * @returns {SelectRow | undefined}
      */
-    get rows() {
-        try {
-            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            wasm.selectresult_rows(retptr, this.__wbg_ptr);
-            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
-            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
-            var v1 = getArrayJsValueFromWasm0(r0, r1).slice();
-            wasm.__wbindgen_export3(r0, r1 * 4, 4);
-            return v1;
-        } finally {
-            wasm.__wbindgen_add_to_stack_pointer(16);
-        }
+    nextRow() {
+        const ret = wasm.selectresult_nextRow(this.__wbg_ptr);
+        return ret === 0 ? undefined : SelectRow.__wrap(ret);
+    }
+    /**
+     * Number of rows that have not yet been consumed.
+     * @returns {number}
+     */
+    get remaining() {
+        const ret = wasm.selectresult_remaining(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Total number of SELECT rows, including rows already consumed.
+     * @returns {number}
+     */
+    get rowCount() {
+        const ret = wasm.selectresult_row_count(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Move a row out by result index. Each row can be consumed once.
+     * @param {number} index
+     * @returns {SelectRow | undefined}
+     */
+    takeRow(index) {
+        const ret = wasm.selectresult_takeRow(this.__wbg_ptr, index);
+        return ret === 0 ? undefined : SelectRow.__wrap(ret);
     }
     /**
      * Projected variables, in SELECT projection order.
@@ -1179,6 +1195,16 @@ export class SelectRow {
         const ret = wasm.selectrow_get(this.__wbg_ptr, ptr0, len0);
         return ret === 0 ? undefined : Term.__wrap(ret);
     }
+    /**
+     * Move one value out by projection index, or return `undefined` when the
+     * cell is unbound, absent, or was already consumed.
+     * @param {number} index
+     * @returns {Term | undefined}
+     */
+    takeValue(index) {
+        const ret = wasm.selectrow_takeValue(this.__wbg_ptr, index);
+        return ret === 0 ? undefined : Term.__wrap(ret);
+    }
     /**
      * Variables projected by this row, in SELECT projection order.
      * @returns {string[]}
@@ -1544,10 +1570,6 @@ function __wbg_get_imports() {
             const ret = Math.random();
             return ret;
         },
-        __wbg_selectrow_new: function(arg0) {
-            const ret = SelectRow.__wrap(arg0);
-            return addHeapObject(ret);
-        },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);

package/pkg/purrdf_wasm_bg.wasm.d.ts

@@ -57,9 +57,13 @@ export const queryresult_kind: (a: number, b: number) => void;
 export const queryresult_takeDataset: (a: number) => number;
 export const queryresult_takeSelect: (a: number) => number;
 export const selectresult_kind: (a: number, b: number) => void;
-export const selectresult_rows: (a: number, b: number) => void;
+export const selectresult_nextRow: (a: number) => number;
+export const selectresult_remaining: (a: number) => number;
+export const selectresult_row_count: (a: number) => number;
+export const selectresult_takeRow: (a: number, b: number) => number;
 export const selectresult_variables: (a: number, b: number) => void;
 export const selectrow_get: (a: number, b: number, c: number) => number;
+export const selectrow_takeValue: (a: number, b: number) => number;
 export const selectrow_variables: (a: number, b: number) => void;
 export const shaclEntail: (a: number, b: number, c: number, d: number, e: number) => void;
 export const shaclValidateToSarif: (a: number, b: number, c: number, d: number, e: number) => void;