@thi.ng/column-store 0.12.0 → 0.13.1

package/README.md

@@ -337,6 +337,24 @@ for(let result of query) { ... }
 const results = [...query];
 ```
 
+Alternatively, queries can also be eagerly executed via
+[`.exec()`](https://docs.thi.ng/umbrella/column-store/classes/Query.html#exec).
+This will also include metadata alongside the results, useful for paging
+results.
+
+```ts
+// predefine query
+const query = table.query().or("name", ["alice", "bob"]).limit(10);
+
+const results = query.exec();
+// {
+//   results: [{...}, ...],
+//   total: 123,
+//   offset: 0,
+//   limit: 10
+// }
+```
+
 #### Optimized row iteration
 
 The query engine works by applying a number of [query
@@ -475,7 +493,7 @@ TODO
 
 ## Status
 
-**ALPHA** - bleeding edge / work-in-progress
+**BETA** - possibly breaking changes forthcoming
 
 [Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Bcolumn-store%5D+in%3Atitle)
 
@@ -505,7 +523,7 @@ For Node.js REPL:
 const cs = await import("@thi.ng/column-store");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 6.27 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 6.48 KB
 
 ## Dependencies
 

package/api.d.ts

@@ -192,6 +192,25 @@ export interface QueryTermOpSpec {
      */
     fn: QueryTermOp;
 }
+export interface QueryResult<T extends Row> {
+    /**
+     * Array of result rows (each incl. `__row` index)
+     */
+    results: RowWithMeta<T>[];
+    /**
+     * Total number of query results (might be more than in
+     * {@link QueryResult.results}).
+     */
+    total: number;
+    /**
+     * Page info. Configured result offset (via {@link Query.limit}).
+     */
+    offset: number;
+    /**
+     * Page info. Configured result limit (via {@link Query.limit}).
+     */
+    limit: number;
+}
 /**
  * Initial capacity for typedarray and vector columns
  *

package/internal/indexof.d.ts

@@ -11,5 +11,5 @@ export declare const __lastIndexOfTuple: (needle: ArrayLike<any> | null, values:
 /** @internal */
 export declare const __clamp: (x: number, a: number, b: number) => number;
 /** @internal */
-export declare const __clampRange: (max: number, start: number, end?: number) => number[];
+export declare const __clampRange: (max: number, start: number, end?: number) => [number, number];
 //# sourceMappingURL=indexof.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@thi.ng/column-store",
-	"version": "0.12.0",
+	"version": "0.13.1",
 	"description": "In-memory column store database with customizable column types, extensible query engine, bitfield indexing for query acceleration, JSON serialization with optional RLE compression",
 	"type": "module",
 	"module": "./index.js",
@@ -127,8 +127,8 @@
 		}
 	},
 	"thi.ng": {
-		"status": "alpha",
+		"status": "beta",
 		"year": 2025
 	},
-	"gitHead": "82ec7cc54d0e89dad89cde87fa36c444512d71d7\n"
+	"gitHead": "b3bcd5623ec78379cceebc6808d7c7b262dfc168\n"
 }

package/query.d.ts

@@ -1,5 +1,5 @@
 import type { Comparator, Predicate } from "@thi.ng/api";
-import type { ColumnID, QueryTerm, QueryTermOpSpec, Row, RowWithMeta } from "./api.js";
+import type { ColumnID, QueryResult, QueryTerm, QueryTermOpSpec, Row, RowWithMeta } from "./api.js";
 import type { Table } from "./table.js";
 export declare class Query<T extends Row> {
     readonly table: Table<T>;
@@ -36,6 +36,12 @@ export declare class Query<T extends Row> {
     matchRow(pred: Predicate<T>): this;
     valueRange(column: ColumnID<T>, start: any, end?: any): this;
     rowRange(start?: number, end?: number): this;
+    /**
+     * Eagerly executes query with current terms and returns results as array in
+     * an object including total number of results and selected paging details
+     * (i.e. offset & limit).
+     */
+    exec(): QueryResult<T>;
     [Symbol.iterator](): Generator<RowWithMeta<T>, void, unknown>;
 }
 export declare class QueryCtx<T extends Row> {
@@ -44,11 +50,13 @@ export declare class QueryCtx<T extends Row> {
     readonly size: number;
     bitmap?: Uint32Array;
     constructor(query: Query<T>);
+    exec(): this;
     /**
      * If a bitmap is already present, yield iterator of only currently selected
      * row IDs, otherwise yields row IDs in `[0,table.length)` range.
      */
     [Symbol.iterator](): Generator<number, void, unknown>;
+    rows(): Generator<RowWithMeta<T>, void, unknown>;
     clear(): void;
     makeMask(seed?: number | Uint32Array): Uint32Array<ArrayBuffer>;
     /**

package/query.js

@@ -103,42 +103,60 @@ class Query {
     this.terms.push({ type: "rowRange", value: { start, end } });
     return this;
   }
-  *[Symbol.iterator]() {
+  /**
+   * Eagerly executes query with current terms and returns results as array in
+   * an object including total number of results and selected paging details
+   * (i.e. offset & limit).
+   */
+  exec() {
     const { table, _limit, _offset } = this;
-    const ctx = new QueryCtx(this);
-    for (const term of this.terms) {
-      const op = QUERY_OPS[term.type];
-      let column;
-      if (term.column) {
-        column = ctx.table.columns[term.column];
-        if (!column) illegalArgs(`column: ${String(term.column)}`);
-      } else if (QUERY_OPS[term.type].mode !== "row") {
-        illegalArgs(
-          `query op: ${term.type} requires a column name given`
-        );
-      }
-      if (!op.fn(ctx, term, column)) return;
-    }
-    if (!ctx.bitmap) return;
+    const ctx = new QueryCtx(this).exec();
+    let rows = [];
+    const result = {
+      results: rows,
+      total: 0,
+      offset: _offset,
+      limit: _limit
+    };
+    if (!ctx.bitmap && this.terms.length) return result;
     if (this._cmp) {
-      const rows = [];
+      rows = [...ctx.rows()].sort(this._cmp);
+      result.total = rows.length;
+      result.results = rows.slice(
+        ...__clampRange(rows.length, _offset, _offset + _limit)
+      );
+    } else {
+      let n = 0;
+      const max = _offset + _limit;
       for (const i of ctx) {
-        rows.push(table.getRow(i, false, true));
-      }
-      rows.sort(this._cmp);
-      for (let i = this._offset, n2 = Math.min(rows.length, i + _limit); i < n2; i++) {
-        yield rows[i];
+        if (n >= _offset && n < max) {
+          rows.push(table.getRow(i, false, true));
+        }
+        n++;
       }
-      return;
+      result.total = n;
     }
-    let j = 0;
-    const n = _offset + _limit;
-    for (const i of ctx) {
-      if (j >= _offset) {
-        if (j >= n) return;
-        yield table.getRow(i, false, true);
+    return result;
+  }
+  *[Symbol.iterator]() {
+    const { table, _limit, _offset } = this;
+    const ctx = new QueryCtx(this).exec();
+    if (!ctx.bitmap && this.terms.length) return;
+    if (this._cmp) {
+      const rows = [...ctx.rows()].sort(this._cmp);
+      yield* rows.slice(
+        ...__clampRange(rows.length, _offset, _offset + _limit)
+      );
+    } else {
+      let j = 0;
+      const n = _offset + _limit;
+      for (const i of ctx) {
+        if (j >= _offset) {
+          if (j >= n) return;
+          yield table.getRow(i, false, true);
+        }
+        j++;
       }
-      j++;
     }
   }
 }
@@ -151,6 +169,22 @@ class QueryCtx {
   table;
   size;
   bitmap;
+  exec() {
+    for (const term of this.query.terms) {
+      const op = QUERY_OPS[term.type];
+      let column;
+      if (term.column) {
+        column = this.table.columns[term.column];
+        if (!column) illegalArgs(`column: ${String(term.column)}`);
+      } else if (QUERY_OPS[term.type].mode !== "row") {
+        illegalArgs(
+          `query op: ${term.type} requires a column name given`
+        );
+      }
+      if (!op.fn(this, term, column)) break;
+    }
+    return this;
+  }
   /**
    * If a bitmap is already present, yield iterator of only currently selected
    * row IDs, otherwise yields row IDs in `[0,table.length)` range.
@@ -163,6 +197,10 @@ class QueryCtx {
       for (let i = 0; i < n; i++) yield i;
     }
   }
+  *rows() {
+    const table = this.query.table;
+    for (const i of this) yield table.getRow(i, false, true);
+  }
   clear() {
     this.bitmap = void 0;
   }