quiverdb 0.9.5 → 0.9.7

package/src/read.ts

@@ -1,4 +1,3 @@
-import { ptr } from "bun:ffi";
 import { Database } from "./database.ts";
 import { check } from "./errors.ts";
 import {
@@ -33,8 +32,8 @@ Database.prototype.readScalarIntegers = function (
       this._handle,
       collBuf.buf,
       attrBuf.buf,
-      outValues.ptr,
-      outCount.ptr,
+      outValues.buf,
+      outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
@@ -60,8 +59,8 @@ Database.prototype.readScalarFloats = function (
       this._handle,
       collBuf.buf,
       attrBuf.buf,
-      outValues.ptr,
-      outCount.ptr,
+      outValues.buf,
+      outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
@@ -87,8 +86,8 @@ Database.prototype.readScalarStrings = function (
       this._handle,
       collBuf.buf,
       attrBuf.buf,
-      outValues.ptr,
-      outCount.ptr,
+      outValues.buf,
+      outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
@@ -111,17 +110,15 @@ Database.prototype.readScalarIntegerById = function (
   const collBuf = toCString(collection);
   const attrBuf = toCString(attribute);
   const outValBuf = new Uint8Array(8);
-  const outValPtr = ptr(outValBuf);
   const outHasBuf = new Uint8Array(4);
-  const outHasPtr = ptr(outHasBuf);
   check(
     lib.quiver_database_read_scalar_integer_by_id(
       this._handle,
       collBuf.buf,
       attrBuf.buf,
       BigInt(id),
-      outValPtr,
-      outHasPtr,
+      outValBuf,
+      outHasBuf,
     ),
   );
   if (new DataView(outHasBuf.buffer).getInt32(0, true) === 0) return null;
@@ -138,17 +135,15 @@ Database.prototype.readScalarFloatById = function (
   const collBuf = toCString(collection);
   const attrBuf = toCString(attribute);
   const outValBuf = new Uint8Array(8);
-  const outValPtr = ptr(outValBuf);
   const outHasBuf = new Uint8Array(4);
-  const outHasPtr = ptr(outHasBuf);
   check(
     lib.quiver_database_read_scalar_float_by_id(
       this._handle,
       collBuf.buf,
       attrBuf.buf,
       BigInt(id),
-      outValPtr,
-      outHasPtr,
+      outValBuf,
+      outHasBuf,
     ),
   );
   if (new DataView(outHasBuf.buffer).getInt32(0, true) === 0) return null;
@@ -166,15 +161,14 @@ Database.prototype.readScalarStringById = function (
   const attrBuf = toCString(attribute);
   const outValue = allocPtrOut();
   const outHasBuf = new Uint8Array(4);
-  const outHasPtr = ptr(outHasBuf);
   check(
     lib.quiver_database_read_scalar_string_by_id(
       this._handle,
       collBuf.buf,
       attrBuf.buf,
       BigInt(id),
-      outValue.ptr,
-      outHasPtr,
+      outValue.buf,
+      outHasBuf,
     ),
   );
   if (new DataView(outHasBuf.buffer).getInt32(0, true) === 0) return null;
@@ -190,7 +184,7 @@ Database.prototype.readElementIds = function (this: Database, collection: string
   const collBuf = toCString(collection);
   const outIds = allocPtrOut();
   const outCount = allocUint64Out();
-  check(lib.quiver_database_read_element_ids(this._handle, collBuf.buf, outIds.ptr, outCount.ptr));
+  check(lib.quiver_database_read_element_ids(this._handle, collBuf.buf, outIds.buf, outCount.buf));
   const count = readUint64Out(outCount);
   if (count === 0) return [];
   const arrPtr = readPtrOut(outIds);
@@ -218,9 +212,9 @@ function readBulkIntegers(
       handle,
       collBuf.buf,
       attrBuf.buf,
-      outVectors.ptr,
-      outSizes.ptr,
-      outCount.ptr,
+      outVectors.buf,
+      outSizes.buf,
+      outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
@@ -254,9 +248,9 @@ function readBulkFloats(
       handle,
       collBuf.buf,
       attrBuf.buf,
-      outVectors.ptr,
-      outSizes.ptr,
-      outCount.ptr,
+      outVectors.buf,
+      outSizes.buf,
+      outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
@@ -290,9 +284,9 @@ function readBulkStrings(
       handle,
       collBuf.buf,
       attrBuf.buf,
-      outVectors.ptr,
-      outSizes.ptr,
-      outCount.ptr,
+      outVectors.buf,
+      outSizes.buf,
+      outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
@@ -408,8 +402,8 @@ function readByIdIntegers(
       collBuf.buf,
       attrBuf.buf,
       BigInt(id),
-      outValues.ptr,
-      outCount.ptr,
+      outValues.buf,
+      outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
@@ -438,8 +432,8 @@ function readByIdFloats(
       collBuf.buf,
       attrBuf.buf,
       BigInt(id),
-      outValues.ptr,
-      outCount.ptr,
+      outValues.buf,
+      outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
@@ -468,8 +462,8 @@ function readByIdStrings(
       collBuf.buf,
       attrBuf.buf,
       BigInt(id),
-      outValues.ptr,
-      outCount.ptr,
+      outValues.buf,
+      outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);

package/src/time-series.ts

@@ -1,6 +1,6 @@
 import { CString, type Pointer, ptr, read, toArrayBuffer } from "bun:ffi";
 import { Database } from "./database.ts";
-import { check } from "./errors.ts";
+import { check, QuiverError } from "./errors.ts";
 import {
   allocNativeFloat64,
   allocNativeInt64,
@@ -18,15 +18,16 @@ import {
   toCString,
 } from "./ffi-helpers.ts";
 import { getSymbols } from "./loader.ts";
-import type { Allocation } from "./types.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)[]>;
 
-const DATA_TYPE_INTEGER = 0;
-const DATA_TYPE_FLOAT = 1;
-const DATA_TYPE_STRING = 2;
-const DATA_TYPE_DATE_TIME = 3;
-
 Database.prototype.readTimeSeriesGroup = function (
   this: Database,
   collection: string,
@@ -48,11 +49,11 @@ Database.prototype.readTimeSeriesGroup = function (
       collBuf.buf,
       grpBuf.buf,
       BigInt(id),
-      outNames.ptr,
-      outTypes.ptr,
-      outData.ptr,
-      outColCount.ptr,
-      outRowCount.ptr,
+      outNames.buf,
+      outTypes.buf,
+      outData.buf,
+      outColCount.buf,
+      outRowCount.buf,
     ),
   );
 
@@ -96,6 +97,64 @@ Database.prototype.readTimeSeriesGroup = function (
   return result;
 };
 
+Database.prototype.readTimeSeriesRow = function (
+  this: Database,
+  collection: string,
+  group: string,
+  attribute: string,
+  dateTime: string,
+): (number | string | null)[] {
+  const lib = getSymbols();
+  const collBuf = toCString(collection);
+  const grpBuf = toCString(group);
+  const attrBuf = toCString(attribute);
+  const dtBuf = toCString(dateTime);
+  const outDataType = new Uint8Array(4);
+  const outValues = allocPtrOut();
+  const outCount = allocUint64Out();
+
+  check(
+    lib.quiver_database_read_time_series_row(
+      this._handle,
+      collBuf.buf,
+      grpBuf.buf,
+      attrBuf.buf,
+      dtBuf.buf,
+      outDataType,
+      outValues.buf,
+      outCount.buf,
+    ),
+  );
+
+  const count = readUint64Out(outCount);
+  const valuesPtr = readPtrOut(outValues);
+  if (count === 0 || !valuesPtr) return [];
+
+  const dataType = new DataView(outDataType.buffer).getInt32(0, true);
+  switch (dataType) {
+    case DATA_TYPE_INTEGER: {
+      const result = decodeInt64Array(valuesPtr, count);
+      lib.quiver_database_free_integer_array(valuesPtr);
+      return result;
+    }
+    case DATA_TYPE_FLOAT: {
+      const result = decodeFloat64Array(valuesPtr, count);
+      lib.quiver_database_free_float_array(valuesPtr);
+      return result;
+    }
+    default: {
+      // STRING or DATE_TIME; NULL entries mark elements with no data
+      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();
+      }
+      lib.quiver_database_free_string_array(valuesPtr, BigInt(count));
+      return result;
+    }
+  }
+};
+
 Database.prototype.updateTimeSeriesGroup = function (
   this: Database,
   collection: string,
@@ -127,6 +186,26 @@ Database.prototype.updateTimeSeriesGroup = function (
 
   const columnCount = entries.length;
   const rowCount = entries[0][1].length;
+
+  // Validate before marshalling: a jagged column would desync the parallel
+  // arrays the C API reads against row_count, and a zero-length column (with
+  // columns present) would otherwise marshal a null data pointer that the C API
+  // dereferences. Named-but-empty columns are a caller mistake -- pass {} to
+  // clear the group instead.
+  for (const [name, values] of entries) {
+    if (values.length !== rowCount) {
+      throw new QuiverError(
+        `Cannot updateTimeSeriesGroup: column '${name}' has length ${values.length} but expected ${rowCount}`,
+      );
+    }
+  }
+  if (rowCount === 0) {
+    const names = entries.map(([name]) => name).join(", ");
+    throw new QuiverError(
+      `Cannot updateTimeSeriesGroup: columns [${names}] contain no rows; pass {} to clear the group`,
+    );
+  }
+
   const keepalive: Allocation[] = [];
 
   // Build column names as native string array
@@ -142,10 +221,7 @@ Database.prototype.updateTimeSeriesGroup = function (
   for (let c = 0; c < columnCount; c++) {
     const values = entries[c][1];
 
-    if (values.length === 0) {
-      typesDv.setInt32(c * 4, DATA_TYPE_STRING, true);
-      dataPtrs.push(null);
-    } else if (typeof values[0] === "string") {
+    if (typeof values[0] === "string") {
       typesDv.setInt32(c * 4, DATA_TYPE_STRING, true);
       const { table, keepalive: strPtrs } = allocNativeStringArray(values as string[]);
       keepalive.push(table, ...strPtrs);
@@ -177,15 +253,76 @@ Database.prototype.updateTimeSeriesGroup = function (
       collBuf.buf,
       grpBuf.buf,
       BigInt(id),
-      namesTable.ptr,
-      typesAlloc.ptr,
-      dataTable.ptr,
+      namesTable.buf,
+      typesAlloc.buf,
+      dataTable.buf,
       BigInt(columnCount),
       BigInt(rowCount),
     ),
   );
 };
 
+Database.prototype.addTimeSeriesRow = function (
+  this: Database,
+  collection: string,
+  group: string,
+  id: number,
+  row: Record<string, number | bigint | string>,
+): void {
+  const lib = getSymbols();
+  const collBuf = toCString(collection);
+  const grpBuf = toCString(group);
+  const entries = Object.entries(row);
+  const columnCount = entries.length;
+  const keepalive: Allocation[] = [];
+
+  const colNames = entries.map(([name]) => name);
+  const { table: namesTable, keepalive: namesPtrs } = allocNativeStringArray(colNames);
+  keepalive.push(namesTable, ...namesPtrs);
+
+  const typesBuf = new Uint8Array(columnCount * 4);
+  const typesDv = new DataView(typesBuf.buffer);
+  const dataPtrs: (Pointer | null)[] = [];
+
+  for (let c = 0; c < columnCount; c++) {
+    const value = entries[c][1];
+    if (typeof value === "string") {
+      typesDv.setInt32(c * 4, DATA_TYPE_STRING, true);
+      const { table, keepalive: strPtrs } = allocNativeStringArray([value]);
+      keepalive.push(table, ...strPtrs);
+      dataPtrs.push(table.ptr);
+    } else if (typeof value === "bigint" || Number.isInteger(value)) {
+      typesDv.setInt32(c * 4, DATA_TYPE_INTEGER, true);
+      const p = allocNativeInt64([value]);
+      keepalive.push(p);
+      dataPtrs.push(p.ptr);
+    } else {
+      typesDv.setInt32(c * 4, DATA_TYPE_FLOAT, true);
+      const p = allocNativeFloat64([value as number]);
+      keepalive.push(p);
+      dataPtrs.push(p.ptr);
+    }
+  }
+
+  const typesAlloc: Allocation = { ptr: ptr(typesBuf), buf: typesBuf };
+  keepalive.push(typesAlloc);
+  const dataTable = allocNativePtrTable(dataPtrs);
+  keepalive.push(dataTable);
+
+  check(
+    lib.quiver_database_add_time_series_row(
+      this._handle,
+      collBuf.buf,
+      grpBuf.buf,
+      BigInt(id),
+      namesTable.buf,
+      typesAlloc.buf,
+      dataTable.buf,
+      BigInt(columnCount),
+    ),
+  );
+};
+
 Database.prototype.hasTimeSeriesFiles = function (this: Database, collection: string): boolean {
   const lib = getSymbols();
   const collBuf = toCString(collection);
@@ -206,8 +343,8 @@ Database.prototype.listTimeSeriesFilesColumns = function (
     lib.quiver_database_list_time_series_files_columns(
       this._handle,
       collBuf.buf,
-      outColumns.ptr,
-      outCount.ptr,
+      outColumns.buf,
+      outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
@@ -231,9 +368,9 @@ Database.prototype.readTimeSeriesFiles = function (
     lib.quiver_database_read_time_series_files(
       this._handle,
       collBuf.buf,
-      outColumns.ptr,
-      outPaths.ptr,
-      outCount.ptr,
+      outColumns.buf,
+      outPaths.buf,
+      outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
@@ -283,8 +420,8 @@ Database.prototype.updateTimeSeriesFiles = function (
     lib.quiver_database_update_time_series_files(
       this._handle,
       collBuf.buf,
-      colsTable.ptr,
-      pathsTable.ptr,
+      colsTable.buf,
+      pathsTable.buf,
       BigInt(entries.length),
     ),
   );

package/src/transaction.ts

@@ -1,4 +1,3 @@
-import { ptr } from "bun:ffi";
 import { Database } from "./database.ts";
 import { check } from "./errors.ts";
 import { getSymbols } from "./loader.ts";
@@ -21,7 +20,6 @@ Database.prototype.rollback = function (this: Database): void {
 Database.prototype.inTransaction = function (this: Database): boolean {
   const lib = getSymbols();
   const outBuf = new Uint8Array(4);
-  const outPtr = ptr(outBuf);
-  check(lib.quiver_database_in_transaction(this._handle, outPtr));
+  check(lib.quiver_database_in_transaction(this._handle, outBuf));
   return new DataView(outBuf.buffer).getInt32(0, true) !== 0;
 };

package/src/types.ts

@@ -1,5 +1,26 @@
 import type { Pointer } from "bun:ffi";
 
+// Mirrors quiver_data_type_t in the C API
+export const DATA_TYPE_INTEGER = 0;
+export const DATA_TYPE_FLOAT = 1;
+export const DATA_TYPE_STRING = 2;
+export const DATA_TYPE_DATE_TIME = 3;
+export const DATA_TYPE_NULL = 4;
+
+// Mirrors quiver_log_level_t in the C API
+export const LOG_LEVEL_DEBUG = 0;
+export const LOG_LEVEL_INFO = 1;
+export const LOG_LEVEL_WARN = 2;
+export const LOG_LEVEL_ERROR = 3;
+export const LOG_LEVEL_OFF = 4;
+
+/** Options for opening or creating a database. */
+export type DatabaseOptions = {
+  readOnly?: boolean;
+  /** A LOG_LEVEL_* constant; defaults to LOG_LEVEL_INFO. */
+  consoleLevel?: number;
+};
+
 export type ScalarValue = number | bigint | string | null;
 export type ArrayValue = number[] | bigint[] | string[];
 export type Value = ScalarValue | ArrayValue;