quiverdb 0.12.4 → 0.12.6

package/README.md

@@ -104,6 +104,8 @@ bun run example.ts
 - `readSetBooleansById(collection, attribute, id)` -- Read INTEGER-backed boolean set
 - `readSetFloatsById(collection, attribute, id)` -- Read float set
 - `readSetStringsById(collection, attribute, id)` -- Read string set
+- `readVectorGroupById(collection, group, id)` -- Read a whole vector group as rows (`null` for a SQL NULL cell)
+- `readSetGroupById(collection, group, id)` -- Read a whole set group as rows (`null` for a SQL NULL cell)
 
 ### Read (IDs)
 
@@ -133,8 +135,8 @@ bun run example.ts
 - `queryBoolean(sql, parameters?)` -- Query returning an INTEGER-backed boolean or null
 - `queryFloat(sql, parameters?)` -- Query returning float or null
 
-Parameters are passed as an array of `number | boolean | string | null` (a `boolean` binds as the
-INTEGER 1 or 0).
+Parameters are passed as an array of `number | bigint | boolean | string | null` (a `bigint` binds
+as an exact INTEGER, a `boolean` as the INTEGER 1 or 0).
 
 ### Transaction
 
@@ -180,12 +182,15 @@ Exported types available for TypeScript consumers:
 - `ArrayValue` -- `number[] | bigint[] | string[]`
 - `Value` -- `ScalarValue | ArrayValue`
 - `ElementData` -- `Record<string, Value | undefined>`
-- `QueryParam` -- `number | string | null`
+- `QueryParam` -- `number | bigint | boolean | string | null`
 - `QuiverError` -- Error class for all Quiver operations
 - `ScalarMetadata` -- Scalar attribute metadata
 - `GroupMetadata` -- Vector/set/time series group metadata
 - `TimeSeriesData` -- Time series column data
 - `CsvOptions` -- CSV import/export options
+- `DatabaseOptions` -- `{ readOnly?: boolean; consoleLevel?: number }` (a `LOG_LEVEL_*` constant)
+- `LOG_LEVEL_DEBUG | INFO | WARN | ERROR | OFF`, `DATA_TYPE_INTEGER | FLOAT | STRING | DATE_TIME | NULL`
+  -- constants for `DatabaseOptions.consoleLevel` and metadata `dataType`
 
 ## Development
 

package/mod.ts

@@ -11,16 +11,4 @@
  * ```
  */
 
-export type {
-  ArrayValue,
-  CsvOptions,
-  ElementData,
-  GroupColumns,
-  GroupMetadata,
-  QueryParam,
-  ScalarMetadata,
-  ScalarValue,
-  TimeSeriesData,
-  Value,
-} from "./src/index.ts";
-export { Database, LUA_DB_API_REFERENCE, LuaRunner, QuiverError } from "./src/index.ts";
+export * from "./src/index.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quiverdb",
-  "version": "0.12.4",
+  "version": "0.12.6",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/create.ts

@@ -8,7 +8,7 @@ import {
   readPtrOut,
   toCString,
 } from "./ffi-helpers.ts";
-import { type GroupColumns, updateGroupColumns } from "./group-columns.ts";
+import { type GroupColumns, numericCells, updateGroupColumns } from "./group-columns.ts";
 import { getSymbols, type NativePointer } from "./loader.ts";
 import type { ElementData, Value } from "./types.ts";
 
@@ -17,6 +17,7 @@ type Symbols = ReturnType<typeof getSymbols>;
 function setElementArray(
   lib: Symbols,
   elemPtr: NativePointer,
+  caller: string,
   name: string,
   values: unknown[],
 ): void {
@@ -29,36 +30,28 @@ function setElementArray(
 
   const first = values[0];
 
-  // A vector/set read returns a NULL cell as null. The element surface is non-null (NULL cells go
-  // through updateVectorGroup / updateSetGroup), and the numeric setters below would store a null
-  // as 0 / false. A string array keeps its NULL-pointer path, which the C setter reads as NULL.
-  if (typeof first !== "string" && values.some((v) => v === null || v === undefined)) {
+  // A vector/set/time-series read returns a NULL cell as null. The element surface is non-null
+  // (NULL cells go through the group writers), whatever the cell's position or the array's type:
+  // the numeric setters below would store a null as 0 / false, and a string array would store an
+  // `undefined` as the text "undefined". `includes`, not `some`: it also sees a sparse array's holes.
+  if (values.includes(null) || values.includes(undefined)) {
     throw new QuiverError(
-      `Unsupported null cell in array '${name}': write NULL cells with updateVectorGroup or updateSetGroup`,
+      `Unsupported null cell in array '${name}': write NULL cells with updateVectorGroup, updateSetGroup or updateTimeSeriesGroup`,
     );
   }
 
-  if (typeof first === "bigint") {
-    const arr = allocNativeInt64(values as bigint[]);
-    check(lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.buf, values.length, null));
-    return;
-  }
-
-  if (typeof first === "boolean") {
-    const arr = allocNativeInt64((values as boolean[]).map((v) => (v ? 1 : 0)));
-    check(lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.buf, values.length, null));
-    return;
-  }
-
-  if (typeof first === "number") {
-    const allIntegers = (values as number[]).every((v) => Number.isInteger(v));
-    if (allIntegers) {
-      const arr = allocNativeInt64(values as number[]);
+  if (typeof first === "number" || typeof first === "boolean" || typeof first === "bigint") {
+    // The null check above leaves no null cell, so the cast only narrows.
+    const cells = numericCells(caller, name, values) as (number | bigint)[];
+    if (cells.every((v) => typeof v === "bigint" || Number.isInteger(v))) {
+      const arr = allocNativeInt64(cells);
       check(
         lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.buf, values.length, null),
       );
     } else {
-      const arr = allocNativeFloat64(values as number[]);
+      // A fractional cell makes the array FLOAT; a bigint cell then follows the int-for-REAL rule
+      // through Number(), exact up to 2^53 like any JS number.
+      const arr = allocNativeFloat64(cells.map(Number));
       check(lib.quiver_element_set_array_float(elemPtr, nameBuf.buf, arr.buf, values.length, null));
     }
     return;
@@ -75,7 +68,13 @@ function setElementArray(
   throw new QuiverError(`Unsupported array element type for '${name}': ${typeof first}`);
 }
 
-function setElementField(lib: Symbols, elemPtr: NativePointer, name: string, value: Value): void {
+function setElementField(
+  lib: Symbols,
+  elemPtr: NativePointer,
+  caller: string,
+  name: string,
+  value: Value,
+): void {
   const nameBuf = toCString(name);
 
   if (value === null) {
@@ -109,7 +108,7 @@ function setElementField(lib: Symbols, elemPtr: NativePointer, name: string, val
   }
 
   if (Array.isArray(value)) {
-    setElementArray(lib, elemPtr, name, value);
+    setElementArray(lib, elemPtr, caller, name, value);
     return;
   }
 
@@ -131,7 +130,7 @@ Database.prototype.createElement = function (
   try {
     for (const [key, value] of Object.entries(data)) {
       if (value === undefined) continue;
-      setElementField(lib, elemPtr, key, value);
+      setElementField(lib, elemPtr, "createElement", key, value);
     }
 
     const outIdBuf = new Uint8Array(8);
@@ -159,7 +158,7 @@ Database.prototype.updateElement = function (
   try {
     for (const [key, value] of Object.entries(data)) {
       if (value === undefined) continue;
-      setElementField(lib, elemPtr, key, value);
+      setElementField(lib, elemPtr, "updateElement", key, value);
     }
     const collBuf = toCString(collection);
     check(lib.quiver_database_update_element(handle, collBuf.buf, BigInt(id), elemPtr));
@@ -185,7 +184,7 @@ Database.prototype.updateElementByLabel = function (
   try {
     for (const [key, value] of Object.entries(data)) {
       if (value === undefined) continue;
-      setElementField(lib, elemPtr, key, value);
+      setElementField(lib, elemPtr, "updateElementByLabel", key, value);
     }
     const collBuf = toCString(collection);
     const labelBuf = toCString(label);

package/src/database.ts

@@ -1,11 +1,10 @@
 import type { CsvOptions } from "./csv.ts";
 import { check, QuiverError } from "./errors.ts";
 import { allocPtrOut, makeDefaultOptions, readPtrOut, toCString } from "./ffi-helpers.ts";
-import type { GroupColumns } from "./group-columns.ts";
+import type { GroupColumns, TimeSeriesData } from "./group-columns.ts";
 import type { NativePointer } from "./loader.ts";
 import { getSymbols } from "./loader.ts";
 import type { GroupMetadata, ScalarMetadata } from "./metadata.ts";
-import type { TimeSeriesData } from "./time-series.ts";
 import type { DatabaseOptions, ElementData, QueryParam } from "./types.ts";
 
 export class Database {
@@ -186,6 +185,16 @@ export class Database {
     attribute: string,
     id: number,
   ) => (string | null)[];
+  declare readVectorGroupById: (
+    collection: string,
+    group: string,
+    id: number,
+  ) => Record<string, number | string | null>[];
+  declare readSetGroupById: (
+    collection: string,
+    group: string,
+    id: number,
+  ) => Record<string, number | string | null>[];
 
   // --- Queries (implemented in query.ts) ---
   declare queryString: (sql: string, parameters?: QueryParam[]) => string | null;

package/src/group-columns.ts

@@ -1,17 +1,41 @@
-import { type Pointer, ptr } from "bun:ffi";
+import { CString, type Pointer, ptr, read, toArrayBuffer } from "bun:ffi";
 import { check, QuiverError } from "./errors.ts";
 import {
   allocNativeFloat64,
   allocNativeInt64,
   allocNativePtrTable,
   allocNativeStringArray,
+  allocPtrOut,
+  allocUint64Out,
+  decodeFloat64Array,
+  decodeInt64Array,
+  decodePtrArray,
+  decodeStringArray,
+  readPtrOut,
+  readUint64Out,
   toCString,
 } from "./ffi-helpers.ts";
-import type { NativePointer } from "./loader.ts";
-import { DATA_TYPE_FLOAT, DATA_TYPE_INTEGER, DATA_TYPE_STRING, type Allocation } from "./types.ts";
+import { getSymbols, type NativePointer } from "./loader.ts";
+import {
+  type Allocation,
+  DATA_TYPE_DATE_TIME,
+  DATA_TYPE_FLOAT,
+  DATA_TYPE_INTEGER,
+  DATA_TYPE_STRING,
+} from "./types.ts";
+
+/**
+ * Column-oriented group payload: one array of cells per column name, `null` for SQL NULL. A
+ * `bigint` cell is written as an exact int64 (like createElement); a `boolean` as INTEGER 1/0.
+ */
+export type GroupColumns = Record<string, (number | bigint | string | boolean | null)[]>;
 
-/** Column-oriented group payload: one array of cells per column name, `null` for SQL NULL. */
-export type GroupColumns = Record<string, (number | string | boolean | null)[]>;
+/**
+ * Column-oriented group read result: one array of cells per column name, `null` for SQL NULL.
+ * The read-side twin of GroupColumns; no reader produces a boolean or a bigint, so it admits
+ * neither.
+ */
+export type TimeSeriesData = Record<string, (number | string | null)[]>;
 
 /**
  * The parallel-array signature every columnar group update C function shares
@@ -31,6 +55,34 @@ type ColumnUpdateFn = (
   rowCount: bigint,
 ) => number;
 
+/**
+ * Check and normalize the cells of a numeric column: one whose first non-null cell is a number, a
+ * bigint or a boolean. Shared by updateGroupColumns and setElementArray (create.ts) so the group
+ * writers and the element arrays agree on every cell. String columns are never passed here.
+ *
+ * - A boolean becomes INTEGER 1/0, since SQLite has no boolean type. Per cell, because mapping the
+ *   whole column from a leading boolean truthiness-mapped the rest and rewrote [true, 5] as
+ *   [1, 1]. Before the INTEGER/FLOAT choice, because Number.isInteger(true) is false.
+ * - A bigint stays a bigint, so an INTEGER column keeps it exact; the caller maps it through
+ *   Number() only if the column turns out FLOAT.
+ * - Any other non-null cell throws, naming the column and the cell. It would fail
+ *   Number.isInteger, tag the column FLOAT and reach DataView.setFloat64, which converts it with no
+ *   error: "abc" to NaN, which SQLite stores as NULL, and "2" to 2.
+ */
+export function numericCells(
+  caller: string,
+  name: string,
+  values: readonly unknown[],
+): (number | bigint | null)[] {
+  return values.map((v, r) => {
+    if (v === null || typeof v === "number" || typeof v === "bigint") return v;
+    if (typeof v === "boolean") return v ? 1 : 0;
+    throw new QuiverError(
+      `Cannot ${caller}: numeric column '${name}' has unsupported value type ${typeof v} in cell ${r}`,
+    );
+  });
+}
+
 /**
  * Marshal a column-oriented payload and forward it to one of the columnar group update C
  * functions. Shared by updateTimeSeriesGroup / updateVectorGroup / updateSetGroup and their
@@ -94,16 +146,7 @@ export function updateGroupColumns(
   const maskPtrs: (Pointer | null)[] = [];
 
   for (let c = 0; c < columnCount; c++) {
-    const [colName, rawValues] = entries[c];
-    // SQLite has no boolean type: a boolean is INTEGER 1/0, as in setElementField and
-    // marshalParams. Normalizing per cell before the dispatch (rather than adding a boolean
-    // branch after it) is what makes a mixed [true, 5] column write 1 and 5 instead of
-    // truthiness-mapping every cell, and matches Python's per-cell `int(v)`. A string column is
-    // left alone so normalizing cannot change what a mixed ['a', true] column already wrote.
-    const isStringColumn = typeof rawValues.find((v) => v !== null) === "string";
-    const values = isStringColumn
-      ? rawValues
-      : rawValues.map((v) => (typeof v === "boolean" ? (v ? 1 : 0) : v));
+    const [colName, values] = entries[c];
     const first = values.find((v) => v !== null);
 
     // Mask via direct indexing — never a DataView, to avoid the documented
@@ -121,23 +164,29 @@ export function updateGroupColumns(
       keepalive.push(p);
       dataPtrs.push(p.ptr);
     } else if (typeof first === "string") {
+      // Not checked by numericCells: a mixed ['a', true] column still writes what it always wrote.
       typesDv.setInt32(c * 4, DATA_TYPE_STRING, true);
       const { table, keepalive: strPtrs } = allocNativeStringArray(
         values.map((v) => (v === null ? null : (v as string))),
       );
       keepalive.push(table, ...strPtrs);
       dataPtrs.push(table.ptr);
-    } else if (typeof first === "number") {
-      const nonNull = values.filter((v) => v !== null) as number[];
-      const sanitized = values.map((v) => (v === null ? 0 : (v as number)));
-      if (nonNull.every((v) => Number.isInteger(v))) {
+    } else if (
+      typeof first === "number" ||
+      typeof first === "boolean" ||
+      typeof first === "bigint"
+    ) {
+      const cells = numericCells(caller, colName, values);
+      if (cells.every((v) => v === null || typeof v === "bigint" || Number.isInteger(v))) {
         typesDv.setInt32(c * 4, DATA_TYPE_INTEGER, true);
-        const p = allocNativeInt64(sanitized);
+        const p = allocNativeInt64(cells.map((v) => v ?? 0));
         keepalive.push(p);
         dataPtrs.push(p.ptr);
       } else {
+        // A fractional cell makes the column FLOAT; a bigint cell then follows the int-for-REAL
+        // rule through Number(), exact up to 2^53 like any JS number.
         typesDv.setInt32(c * 4, DATA_TYPE_FLOAT, true);
-        const p = allocNativeFloat64(sanitized);
+        const p = allocNativeFloat64(cells.map((v) => (v === null ? 0 : Number(v))));
         keepalive.push(p);
         dataPtrs.push(p.ptr);
       }
@@ -170,3 +219,123 @@ export function updateGroupColumns(
     ),
   );
 }
+
+/**
+ * The out-parameter signature every columnar group read C function shares
+ * (quiver_database_read_time_series_group, quiver_database_read_{vector,set}_group_by_id).
+ */
+type ColumnReadFn = (
+  db: NativePointer,
+  collection: Uint8Array,
+  group: Uint8Array,
+  id: bigint,
+  names: Uint8Array,
+  types: Uint8Array,
+  data: Uint8Array,
+  masks: Uint8Array,
+  columnCount: Uint8Array,
+  rowCount: Uint8Array,
+) => number;
+
+/**
+ * Call one of the columnar group read C functions, decode its typed arrays + per-cell mask into
+ * columns, and free the C result. The read-side twin of updateGroupColumns, shared by
+ * readTimeSeriesGroup (which returns the columns) and readVectorGroupById / readSetGroupById
+ * (which transpose them into rows). A masked cell is `null`; DATE_TIME cells stay ISO 8601 strings.
+ */
+export function readGroupColumns(
+  handle: NativePointer,
+  readGroup: ColumnReadFn,
+  collection: string,
+  group: string,
+  id: number,
+): TimeSeriesData {
+  const collBuf = toCString(collection);
+  const grpBuf = toCString(group);
+  const outNames = allocPtrOut();
+  const outTypes = allocPtrOut();
+  const outData = allocPtrOut();
+  const outHasValue = allocPtrOut();
+  const outColCount = allocUint64Out();
+  const outRowCount = allocUint64Out();
+
+  check(
+    readGroup(
+      handle,
+      collBuf.buf,
+      grpBuf.buf,
+      BigInt(id),
+      outNames.buf,
+      outTypes.buf,
+      outData.buf,
+      outHasValue.buf,
+      outColCount.buf,
+      outRowCount.buf,
+    ),
+  );
+
+  const colCount = readUint64Out(outColCount);
+  const rowCount = readUint64Out(outRowCount);
+  if (colCount === 0) return {};
+
+  const namesPtr = readPtrOut(outNames);
+  const typesPtr = readPtrOut(outTypes);
+  const dataPtr = readPtrOut(outData);
+  const hasValuePtr = readPtrOut(outHasValue);
+
+  try {
+    const colNames = decodeStringArray(namesPtr, colCount);
+    const typesAb = toArrayBuffer(typesPtr as Pointer, 0, colCount * 4);
+    const types = Array.from(new Int32Array(typesAb));
+    const dataPtrs = decodePtrArray(dataPtr, colCount);
+    const maskPtrs = decodePtrArray(hasValuePtr, colCount);
+
+    // Per-cell NULL mask: mask[r] === 0 means SQL NULL, surfaced as JS null. A time series'
+    // dimension column's mask is always all 1, so it stays dense.
+    const result: TimeSeriesData = {};
+    for (let c = 0; c < colCount; c++) {
+      const colName = colNames[c];
+      const maskPtr = maskPtrs[c];
+      const mask = maskPtr ? new Uint8Array(toArrayBuffer(maskPtr as Pointer, 0, rowCount)) : null;
+      switch (types[c]) {
+        case DATA_TYPE_INTEGER: {
+          const vals = decodeInt64Array(dataPtrs[c], rowCount);
+          result[colName] = mask ? vals.map((v, r) => (mask[r] ? v : null)) : vals;
+          break;
+        }
+        case DATA_TYPE_FLOAT: {
+          const vals = decodeFloat64Array(dataPtrs[c], rowCount);
+          result[colName] = mask ? vals.map((v, r) => (mask[r] ? v : null)) : vals;
+          break;
+        }
+        case DATA_TYPE_STRING:
+        case DATA_TYPE_DATE_TIME: {
+          // Read pointer-by-pointer, not with decodeStringArray, which turns a NULL char* into "":
+          // a masked-out or NULL cell must come back as null.
+          const base = dataPtrs[c];
+          const col: (string | null)[] = new Array(rowCount);
+          for (let r = 0; r < rowCount; r++) {
+            if (mask && !mask[r]) {
+              col[r] = null;
+              continue;
+            }
+            const strPtr = base ? read.ptr(base as Pointer, r * 8) : 0;
+            col[r] = strPtr === 0 ? null : new CString(strPtr as Pointer).toString();
+          }
+          result[colName] = col;
+          break;
+        }
+      }
+    }
+    return result;
+  } finally {
+    getSymbols().quiver_database_free_time_series_data(
+      namesPtr,
+      typesPtr,
+      dataPtr,
+      hasValuePtr,
+      BigInt(colCount),
+      BigInt(rowCount),
+    );
+  }
+}

package/src/index.ts

@@ -11,11 +11,10 @@ import "./composites.ts";
 export type { CsvOptions } from "./csv.ts";
 export { Database } from "./database.ts";
 export { QuiverError } from "./errors.ts";
-export type { GroupColumns } from "./group-columns.ts";
+export type { GroupColumns, TimeSeriesData } from "./group-columns.ts";
 export { LUA_DB_API_REFERENCE } from "./lua-api.ts";
 export { LuaRunner } from "./lua-runner.ts";
 export type { GroupMetadata, ScalarMetadata } from "./metadata.ts";
-export type { TimeSeriesData } from "./time-series.ts";
 export type {
   ArrayValue,
   DatabaseOptions,
@@ -25,6 +24,11 @@ export type {
   Value,
 } from "./types.ts";
 export {
+  DATA_TYPE_DATE_TIME,
+  DATA_TYPE_FLOAT,
+  DATA_TYPE_INTEGER,
+  DATA_TYPE_NULL,
+  DATA_TYPE_STRING,
   LOG_LEVEL_DEBUG,
   LOG_LEVEL_ERROR,
   LOG_LEVEL_INFO,

package/src/loader.ts

@@ -85,17 +85,22 @@ const readSymbols = {
   quiver_database_read_set_integers_by_id: { args: [P, BUF, BUF, I64, P, P, P], returns: I32 },
   quiver_database_read_set_floats_by_id: { args: [P, BUF, BUF, I64, P, P, P], returns: I32 },
   quiver_database_read_set_strings_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
+  quiver_database_read_vector_group_by_id: {
+    args: [P, BUF, BUF, I64, P, P, P, P, P, P],
+    returns: I32,
+  },
+  quiver_database_read_set_group_by_id: {
+    args: [P, BUF, BUF, I64, P, P, P, P, P, P],
+    returns: I32,
+  },
   quiver_database_read_element_ids: { args: [P, BUF, P, P], returns: I32 },
   quiver_database_number_of_elements: { args: [P, BUF, P], returns: I32 },
 } as const;
 
 const querySymbols = {
-  quiver_database_query_string: { args: [P, BUF, P, P], returns: I32 },
-  quiver_database_query_integer: { args: [P, BUF, P, P], returns: I32 },
-  quiver_database_query_float: { args: [P, BUF, P, P], returns: I32 },
-  quiver_database_query_string_params: { args: [P, BUF, P, P, USIZE, P, P], returns: I32 },
-  quiver_database_query_integer_params: { args: [P, BUF, P, P, USIZE, P, P], returns: I32 },
-  quiver_database_query_float_params: { args: [P, BUF, P, P, USIZE, P, P], returns: I32 },
+  quiver_database_query_string: { args: [P, BUF, P, P, USIZE, P, P], returns: I32 },
+  quiver_database_query_integer: { args: [P, BUF, P, P, USIZE, P, P], returns: I32 },
+  quiver_database_query_float: { args: [P, BUF, P, P, USIZE, P, P], returns: I32 },
 } as const;
 
 const transactionSymbols = {
@@ -131,7 +136,7 @@ const timeSeriesSymbols = {
     args: [P, BUF, BUF, I64, P, P, P, P, P, P],
     returns: I32,
   },
-  quiver_database_read_time_series_row: { args: [P, BUF, BUF, BUF, BUF, P, P, P], returns: I32 },
+  quiver_database_read_time_series_row: { args: [P, BUF, BUF, BUF, BUF, P, P, P, P], returns: I32 },
   quiver_database_upsert_time_series_row: {
     args: [P, BUF, BUF, I64, P, P, P, USIZE],
     returns: I32,

package/src/lua-api.ts

@@ -399,7 +399,10 @@ Scalar attributes with no value come back as \`nil\`.
 
 **Group columns keep NULL cells as \`nil\` holes**, so cell *i* of every column of one group is
 the same row. Zipping them needs the row count: \`#\` of a \`NOT NULL\` column of the group.
-There is no row-shaped group read in Lua.
+There is no row-shaped group read in Lua. The result is keyed by column name, so when two vector
+(or two set) groups share a column name, which a foreign key may, that name appears once and is
+read from the group it resolves to (the one named after it, else the one whose table name sorts
+first) — do not zip it with the other group's columns.
 
 ---
 

package/src/query.ts

@@ -1,4 +1,3 @@
-import { ptr } from "bun:ffi";
 import { integerToBoolean } from "./boolean.ts";
 import { Database } from "./database.ts";
 import { check, QuiverError } from "./errors.ts";
@@ -22,11 +21,18 @@ import {
   type QueryParam,
 } from "./types.ts";
 
-function marshalParams(parameters: QueryParam[]): {
-  types: Allocation;
-  values: Allocation;
+// Marshals query parameters into the C API's parallel type/value arrays. No parameters (omitted or
+// empty) marshal to NULL pointers with a count of 0: the C API reads neither array then, and a
+// zero-length TypedArray has no pointer in Bun (ptr() of one returns a TypeError).
+function marshalParams(parameters?: QueryParam[]): {
+  types: Uint8Array | null;
+  values: Uint8Array | null;
+  count: bigint;
   _keepalive: Allocation[];
 } {
+  if (!parameters || parameters.length === 0)
+    return { types: null, values: null, count: 0n, _keepalive: [] };
+
   const n = parameters.length;
   const typesBuf = new Uint8Array(n * 4);
   const typesDv = new DataView(typesBuf.buffer);
@@ -44,6 +50,11 @@ function marshalParams(parameters: QueryParam[]): {
       const native = allocNativeInt64([p ? 1 : 0]);
       keepalive.push(native);
       valuesDv.setBigInt64(i * 8, nativeAddress(native.ptr), true);
+    } else if (typeof p === "bigint") {
+      typesDv.setInt32(i * 4, DATA_TYPE_INTEGER, true);
+      const native = allocNativeInt64([p]);
+      keepalive.push(native);
+      valuesDv.setBigInt64(i * 8, nativeAddress(native.ptr), true);
     } else if (typeof p === "number") {
       if (Number.isInteger(p)) {
         typesDv.setInt32(i * 4, DATA_TYPE_INTEGER, true);
@@ -66,10 +77,7 @@ function marshalParams(parameters: QueryParam[]): {
     }
   }
 
-  const types: Allocation = { ptr: ptr(typesBuf), buf: typesBuf };
-  const values: Allocation = { ptr: ptr(valuesBuf), buf: valuesBuf };
-  keepalive.push(types, values);
-  return { types, values, _keepalive: keepalive };
+  return { types: typesBuf, values: valuesBuf, count: BigInt(n), _keepalive: keepalive };
 }
 
 Database.prototype.queryString = function (
@@ -81,23 +89,19 @@ Database.prototype.queryString = function (
   const sqlBuf = toCString(sql);
   const outValue = allocPtrOut();
   const outHasValue = new Uint8Array(4);
+  const params = marshalParams(parameters);
 
-  if (parameters && parameters.length > 0) {
-    const m = marshalParams(parameters);
-    check(
-      lib.quiver_database_query_string_params(
-        this._handle,
-        sqlBuf.buf,
-        m.types.buf,
-        m.values.buf,
-        BigInt(parameters.length),
-        outValue.buf,
-        outHasValue,
-      ),
-    );
-  } else {
-    check(lib.quiver_database_query_string(this._handle, sqlBuf.buf, outValue.buf, outHasValue));
-  }
+  check(
+    lib.quiver_database_query_string(
+      this._handle,
+      sqlBuf.buf,
+      params.types,
+      params.values,
+      params.count,
+      outValue.buf,
+      outHasValue,
+    ),
+  );
 
   if (new DataView(outHasValue.buffer).getInt32(0, true) === 0) return null;
   const result = decodeStringFromBuf(outValue);
@@ -114,23 +118,19 @@ Database.prototype.queryInteger = function (
   const sqlBuf = toCString(sql);
   const outValue = new Uint8Array(8);
   const outHasValue = new Uint8Array(4);
+  const params = marshalParams(parameters);
 
-  if (parameters && parameters.length > 0) {
-    const m = marshalParams(parameters);
-    check(
-      lib.quiver_database_query_integer_params(
-        this._handle,
-        sqlBuf.buf,
-        m.types.buf,
-        m.values.buf,
-        BigInt(parameters.length),
-        outValue,
-        outHasValue,
-      ),
-    );
-  } else {
-    check(lib.quiver_database_query_integer(this._handle, sqlBuf.buf, outValue, outHasValue));
-  }
+  check(
+    lib.quiver_database_query_integer(
+      this._handle,
+      sqlBuf.buf,
+      params.types,
+      params.values,
+      params.count,
+      outValue,
+      outHasValue,
+    ),
+  );
 
   if (new DataView(outHasValue.buffer).getInt32(0, true) === 0) return null;
   return Number(new DataView(outValue.buffer).getBigInt64(0, true));
@@ -153,23 +153,19 @@ Database.prototype.queryFloat = function (
   const sqlBuf = toCString(sql);
   const outValue = new Uint8Array(8);
   const outHasValue = new Uint8Array(4);
+  const params = marshalParams(parameters);
 
-  if (parameters && parameters.length > 0) {
-    const m = marshalParams(parameters);
-    check(
-      lib.quiver_database_query_float_params(
-        this._handle,
-        sqlBuf.buf,
-        m.types.buf,
-        m.values.buf,
-        BigInt(parameters.length),
-        outValue,
-        outHasValue,
-      ),
-    );
-  } else {
-    check(lib.quiver_database_query_float(this._handle, sqlBuf.buf, outValue, outHasValue));
-  }
+  check(
+    lib.quiver_database_query_float(
+      this._handle,
+      sqlBuf.buf,
+      params.types,
+      params.values,
+      params.count,
+      outValue,
+      outHasValue,
+    ),
+  );
 
   if (new DataView(outHasValue.buffer).getInt32(0, true) === 0) return null;
   return new DataView(outValue.buffer).getFloat64(0, true);

package/src/read.ts

@@ -14,6 +14,7 @@ import {
   readUint64Out,
   toCString,
 } from "./ffi-helpers.ts";
+import { readGroupColumns, type TimeSeriesData } from "./group-columns.ts";
 import { getSymbols, type NativePointer } from "./loader.ts";
 
 // --- Scalar array reads ---
@@ -698,3 +699,58 @@ Database.prototype.readSetStringsById = function (
     id,
   );
 };
+
+// --- Whole-group reads ---
+
+/** One record per row, from decoded columns that all share one length. */
+function columnsToRows(columns: TimeSeriesData): Record<string, number | string | null>[] {
+  const names = Object.keys(columns);
+  if (names.length === 0) return [];
+  return columns[names[0]].map((_, r) =>
+    Object.fromEntries(names.map((name) => [name, columns[name][r]])),
+  );
+}
+
+/**
+ * Read an element's vector group as one record per row, in vector_index order. One native read of
+ * the named group's own table: a SQL NULL cell is `null` in its row, and a column name another
+ * group shares still reads this group (a per-column reader resolves the name). DATE_TIME cells
+ * stay ISO 8601 strings.
+ */
+Database.prototype.readVectorGroupById = function (
+  this: Database,
+  collection: string,
+  group: string,
+  id: number,
+): Record<string, number | string | null>[] {
+  return columnsToRows(
+    readGroupColumns(
+      this._handle,
+      getSymbols().quiver_database_read_vector_group_by_id,
+      collection,
+      group,
+      id,
+    ),
+  );
+};
+
+/**
+ * Set-group counterpart of readVectorGroupById. Row order is consistent across every reader of
+ * the group, otherwise unspecified.
+ */
+Database.prototype.readSetGroupById = function (
+  this: Database,
+  collection: string,
+  group: string,
+  id: number,
+): Record<string, number | string | null>[] {
+  return columnsToRows(
+    readGroupColumns(
+      this._handle,
+      getSymbols().quiver_database_read_set_group_by_id,
+      collection,
+      group,
+      id,
+    ),
+  );
+};

package/src/time-series.ts

@@ -11,23 +11,19 @@ import {
   allocUint64Out,
   decodeFloat64Array,
   decodeInt64Array,
-  decodePtrArray,
   decodeStringArray,
   readPtrOut,
   readUint64Out,
   toCString,
 } from "./ffi-helpers.ts";
-import { type GroupColumns, updateGroupColumns } from "./group-columns.ts";
-import { getSymbols, type NativePointer } from "./loader.ts";
 import {
-  type Allocation,
-  DATA_TYPE_DATE_TIME,
-  DATA_TYPE_FLOAT,
-  DATA_TYPE_INTEGER,
-  DATA_TYPE_STRING,
-} from "./types.ts";
-
-export type TimeSeriesData = Record<string, (number | string | null)[]>;
+  type GroupColumns,
+  readGroupColumns,
+  type TimeSeriesData,
+  updateGroupColumns,
+} from "./group-columns.ts";
+import { getSymbols, type NativePointer } from "./loader.ts";
+import { type Allocation, DATA_TYPE_FLOAT, DATA_TYPE_INTEGER, DATA_TYPE_STRING } from "./types.ts";
 
 Database.prototype.readTimeSeriesGroup = function (
   this: Database,
@@ -35,93 +31,13 @@ Database.prototype.readTimeSeriesGroup = function (
   group: string,
   id: number,
 ): TimeSeriesData {
-  const lib = getSymbols();
-  const collBuf = toCString(collection);
-  const grpBuf = toCString(group);
-  const outNames = allocPtrOut();
-  const outTypes = allocPtrOut();
-  const outData = allocPtrOut();
-  const outHasValue = allocPtrOut();
-  const outColCount = allocUint64Out();
-  const outRowCount = allocUint64Out();
-
-  check(
-    lib.quiver_database_read_time_series_group(
-      this._handle,
-      collBuf.buf,
-      grpBuf.buf,
-      BigInt(id),
-      outNames.buf,
-      outTypes.buf,
-      outData.buf,
-      outHasValue.buf,
-      outColCount.buf,
-      outRowCount.buf,
-    ),
-  );
-
-  const colCount = readUint64Out(outColCount);
-  const rowCount = readUint64Out(outRowCount);
-  if (colCount === 0) return {};
-
-  const namesPtr = readPtrOut(outNames);
-  const typesPtr = readPtrOut(outTypes);
-  const dataPtr = readPtrOut(outData);
-  const hasValuePtr = readPtrOut(outHasValue);
-
-  const colNames = decodeStringArray(namesPtr, colCount);
-  const typesAb = toArrayBuffer(typesPtr as Pointer, 0, colCount * 4);
-  const types = Array.from(new Int32Array(typesAb));
-  const dataPtrs = decodePtrArray(dataPtr, colCount);
-  const maskPtrs = decodePtrArray(hasValuePtr, colCount);
-
-  // Per-cell NULL mask: mask[r] === 0 means SQL NULL, surfaced as JS null. The
-  // dimension column's mask is always all 1, so it stays dense.
-  const result: TimeSeriesData = {};
-  for (let c = 0; c < colCount; c++) {
-    const colName = colNames[c];
-    const maskPtr = maskPtrs[c];
-    const mask = maskPtr ? new Uint8Array(toArrayBuffer(maskPtr as Pointer, 0, rowCount)) : null;
-    switch (types[c]) {
-      case DATA_TYPE_INTEGER: {
-        const vals = decodeInt64Array(dataPtrs[c], rowCount);
-        result[colName] = mask ? vals.map((v, r) => (mask[r] ? v : null)) : vals;
-        break;
-      }
-      case DATA_TYPE_FLOAT: {
-        const vals = decodeFloat64Array(dataPtrs[c], rowCount);
-        result[colName] = mask ? vals.map((v, r) => (mask[r] ? v : null)) : vals;
-        break;
-      }
-      case DATA_TYPE_STRING:
-      case DATA_TYPE_DATE_TIME: {
-        // Read pointer-by-pointer (not decodeStringArray): a masked-out cell is a
-        // NULL char* that CString cannot construct from.
-        const base = dataPtrs[c];
-        const col: (string | null)[] = new Array(rowCount);
-        for (let r = 0; r < rowCount; r++) {
-          if (mask && !mask[r]) {
-            col[r] = null;
-            continue;
-          }
-          const strPtr = base ? read.ptr(base as Pointer, r * 8) : 0;
-          col[r] = strPtr === 0 ? null : new CString(strPtr as Pointer).toString();
-        }
-        result[colName] = col;
-        break;
-      }
-    }
-  }
-
-  lib.quiver_database_free_time_series_data(
-    namesPtr,
-    typesPtr,
-    dataPtr,
-    hasValuePtr,
-    BigInt(colCount),
-    BigInt(rowCount),
+  return readGroupColumns(
+    this._handle,
+    getSymbols().quiver_database_read_time_series_group,
+    collection,
+    group,
+    id,
   );
-  return result;
 };
 
 Database.prototype.readTimeSeriesRow = function (
@@ -138,6 +54,7 @@ Database.prototype.readTimeSeriesRow = function (
   const dtBuf = toCString(dateTime);
   const outDataType = new Uint8Array(4);
   const outValues = allocPtrOut();
+  const outMask = allocPtrOut();
   const outCount = allocUint64Out();
 
   check(
@@ -149,6 +66,7 @@ Database.prototype.readTimeSeriesRow = function (
       dtBuf.buf,
       outDataType,
       outValues.buf,
+      outMask.buf,
       outCount.buf,
     ),
   );
@@ -157,26 +75,33 @@ Database.prototype.readTimeSeriesRow = function (
   const valuesPtr = readPtrOut(outValues);
   if (count === 0 || !valuesPtr) return [];
 
+  // mask[i] === 0: no data at or before dateTime; the data slot is a placeholder, never read.
+  const maskPtr = readPtrOut(outMask);
+  const mask = new Uint8Array(toArrayBuffer(maskPtr as Pointer, 0, count));
   const dataType = new DataView(outDataType.buffer).getInt32(0, true);
   switch (dataType) {
     case DATA_TYPE_INTEGER: {
-      const result = decodeInt64Array(valuesPtr, count);
+      const result = decodeInt64Array(valuesPtr, count).map((v, i) => (mask[i] ? v : null));
       lib.quiver_database_free_integer_array(valuesPtr);
+      lib.quiver_database_free_mask(maskPtr);
       return result;
     }
     case DATA_TYPE_FLOAT: {
-      const result = decodeFloat64Array(valuesPtr, count);
+      const result = decodeFloat64Array(valuesPtr, count).map((v, i) => (mask[i] ? v : null));
       lib.quiver_database_free_float_array(valuesPtr);
+      lib.quiver_database_free_mask(maskPtr);
       return result;
     }
     default: {
-      // STRING or DATE_TIME; NULL entries mark elements with no data
+      // STRING or DATE_TIME; never build a CString from a masked-out (NULL) pointer
       const result: (string | null)[] = new Array(count);
       for (let i = 0; i < count; i++) {
-        const strPtr = read.ptr(valuesPtr as Pointer, i * 8);
-        result[i] = strPtr === 0 ? null : new CString(strPtr as Pointer).toString();
+        result[i] = mask[i]
+          ? new CString(read.ptr(valuesPtr as Pointer, i * 8) as Pointer).toString()
+          : null;
       }
       lib.quiver_database_free_string_array(valuesPtr, BigInt(count));
+      lib.quiver_database_free_mask(maskPtr);
       return result;
     }
   }
@@ -426,7 +351,12 @@ Database.prototype.updateTimeSeriesFiles = function (
   const lib = getSymbols();
   const collBuf = toCString(collection);
   const entries = Object.entries(data);
-  if (entries.length === 0) return;
+  // An empty map still reaches the core, which validates the collection and its files table
+  // before the no-op. null tables, never zero-length buffers (same as updateGroupColumns).
+  if (entries.length === 0) {
+    check(lib.quiver_database_update_time_series_files(this._handle, collBuf.buf, null, null, 0n));
+    return;
+  }
   const keepalive: Allocation[] = [];
 
   const colNames = entries.map(([name]) => name);

package/src/types.ts

@@ -26,7 +26,8 @@ export type ScalarValue = number | bigint | boolean | string | null;
 export type ArrayValue = number[] | bigint[] | boolean[] | string[];
 export type Value = ScalarValue | ArrayValue;
 export type ElementData = Record<string, Value | undefined>;
-export type QueryParam = number | boolean | string | null;
+/** A `bigint` binds as an exact INTEGER; a `boolean` as INTEGER 1/0. */
+export type QueryParam = number | bigint | boolean | string | null;
 
 /** Native memory allocation result. Callers MUST hold `buf` in scope to prevent GC. */
 export type Allocation = {