quiverdb 0.9.5 → 0.9.6

package/package.json

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

package/src/composites.ts

@@ -1,4 +1,11 @@
 import { Database } from "./database.ts";
+import { QuiverError } from "./errors.ts";
+import {
+  DATA_TYPE_DATE_TIME,
+  DATA_TYPE_FLOAT,
+  DATA_TYPE_INTEGER,
+  DATA_TYPE_STRING,
+} from "./types.ts";
 
 Database.prototype.readScalarsById = function (
   this: Database,
@@ -10,18 +17,18 @@ Database.prototype.readScalarsById = function (
 
   for (const attr of attributes) {
     switch (attr.dataType) {
-      case 0: // INTEGER
+      case DATA_TYPE_INTEGER:
         result[attr.name] = this.readScalarIntegerById(collection, attr.name, id);
         break;
-      case 1: // FLOAT
+      case DATA_TYPE_FLOAT:
         result[attr.name] = this.readScalarFloatById(collection, attr.name, id);
         break;
-      case 2: // STRING
-      case 3: // DATE_TIME
+      case DATA_TYPE_STRING:
+      case DATA_TYPE_DATE_TIME:
         result[attr.name] = this.readScalarStringById(collection, attr.name, id);
         break;
       default:
-        throw new Error(`Unknown data type ${attr.dataType} for attribute '${attr.name}'`);
+        throw new QuiverError(`Unknown data type ${attr.dataType} for attribute '${attr.name}'`);
     }
   }
 
@@ -39,18 +46,18 @@ Database.prototype.readVectorsById = function (
   for (const group of groups) {
     for (const col of group.valueColumns) {
       switch (col.dataType) {
-        case 0: // INTEGER
+        case DATA_TYPE_INTEGER:
           result[col.name] = this.readVectorIntegersById(collection, col.name, id);
           break;
-        case 1: // FLOAT
+        case DATA_TYPE_FLOAT:
           result[col.name] = this.readVectorFloatsById(collection, col.name, id);
           break;
-        case 2: // STRING
-        case 3: // DATE_TIME
+        case DATA_TYPE_STRING:
+        case DATA_TYPE_DATE_TIME:
           result[col.name] = this.readVectorStringsById(collection, col.name, id);
           break;
         default:
-          throw new Error(`Unknown data type ${col.dataType} for column '${col.name}'`);
+          throw new QuiverError(`Unknown data type ${col.dataType} for column '${col.name}'`);
       }
     }
   }
@@ -69,18 +76,18 @@ Database.prototype.readSetsById = function (
   for (const group of groups) {
     for (const col of group.valueColumns) {
       switch (col.dataType) {
-        case 0: // INTEGER
+        case DATA_TYPE_INTEGER:
           result[col.name] = this.readSetIntegersById(collection, col.name, id);
           break;
-        case 1: // FLOAT
+        case DATA_TYPE_FLOAT:
           result[col.name] = this.readSetFloatsById(collection, col.name, id);
           break;
-        case 2: // STRING
-        case 3: // DATE_TIME
+        case DATA_TYPE_STRING:
+        case DATA_TYPE_DATE_TIME:
           result[col.name] = this.readSetStringsById(collection, col.name, id);
           break;
         default:
-          throw new Error(`Unknown data type ${col.dataType} for column '${col.name}'`);
+          throw new QuiverError(`Unknown data type ${col.dataType} for column '${col.name}'`);
       }
     }
   }

package/src/create.ts

@@ -1,4 +1,3 @@
-import { ptr } from "bun:ffi";
 import { Database } from "./database.ts";
 import { check, QuiverError } from "./errors.ts";
 import {
@@ -30,8 +29,8 @@ function setElementArray(
   const first = values[0];
 
   if (typeof first === "bigint") {
-    const arr = allocNativeInt64((values as bigint[]).map(Number));
-    check(lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.ptr, values.length));
+    const arr = allocNativeInt64(values as bigint[]);
+    check(lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.buf, values.length));
     return;
   }
 
@@ -39,17 +38,17 @@ function setElementArray(
     const allIntegers = (values as number[]).every((v) => Number.isInteger(v));
     if (allIntegers) {
       const arr = allocNativeInt64(values as number[]);
-      check(lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.ptr, values.length));
+      check(lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.buf, values.length));
     } else {
       const arr = allocNativeFloat64(values as number[]);
-      check(lib.quiver_element_set_array_float(elemPtr, nameBuf.buf, arr.ptr, values.length));
+      check(lib.quiver_element_set_array_float(elemPtr, nameBuf.buf, arr.buf, values.length));
     }
     return;
   }
 
   if (typeof first === "string") {
     const { table, keepalive: _keepalive } = allocNativeStringArray(values as string[]);
-    check(lib.quiver_element_set_array_string(elemPtr, nameBuf.buf, table.ptr, values.length));
+    check(lib.quiver_element_set_array_string(elemPtr, nameBuf.buf, table.buf, values.length));
     return;
   }
 
@@ -101,7 +100,7 @@ Database.prototype.createElement = function (
   const handle = this._handle;
 
   const outElem = allocPtrOut();
-  check(lib.quiver_element_create(outElem.ptr));
+  check(lib.quiver_element_create(outElem.buf));
   const elemPtr = readPtrOut(outElem);
 
   try {
@@ -111,9 +110,8 @@ Database.prototype.createElement = function (
     }
 
     const outIdBuf = new Uint8Array(8);
-    const outIdPtr = ptr(outIdBuf);
     const collBuf = toCString(collection);
-    check(lib.quiver_database_create_element(handle, collBuf.buf, elemPtr, outIdPtr));
+    check(lib.quiver_database_create_element(handle, collBuf.buf, elemPtr, outIdBuf));
     return Number(new DataView(outIdBuf.buffer).getBigInt64(0, true));
   } finally {
     lib.quiver_element_destroy(elemPtr);
@@ -130,7 +128,7 @@ Database.prototype.updateElement = function (
   const handle = this._handle;
 
   const outElem = allocPtrOut();
-  check(lib.quiver_element_create(outElem.ptr));
+  check(lib.quiver_element_create(outElem.buf));
   const elemPtr = readPtrOut(outElem);
 
   try {

package/src/csv.ts

@@ -96,7 +96,7 @@ Database.prototype.exportCsv = function (
   const pathBuf = toCString(filePath);
   const [optsBuf, _keepalive] = buildCsvOptionsBuffer(options);
   check(
-    lib.quiver_database_export_csv(this._handle, collBuf.buf, grpBuf.buf, pathBuf.buf, optsBuf.ptr),
+    lib.quiver_database_export_csv(this._handle, collBuf.buf, grpBuf.buf, pathBuf.buf, optsBuf.buf),
   );
 };
 
@@ -113,6 +113,6 @@ Database.prototype.importCsv = function (
   const pathBuf = toCString(filePath);
   const [optsBuf, _keepalive] = buildCsvOptionsBuffer(options);
   check(
-    lib.quiver_database_import_csv(this._handle, collBuf.buf, grpBuf.buf, pathBuf.buf, optsBuf.ptr),
+    lib.quiver_database_import_csv(this._handle, collBuf.buf, grpBuf.buf, pathBuf.buf, optsBuf.buf),
   );
 };

package/src/database.ts

@@ -5,7 +5,7 @@ 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 { ElementData, QueryParam } from "./types.ts";
+import type { DatabaseOptions, ElementData, QueryParam } from "./types.ts";
 
 export class Database {
   private _ptr: NativePointer;
@@ -15,41 +15,50 @@ export class Database {
     this._ptr = nativePtr;
   }
 
-  static fromSchema(dbPath: string, schemaPath: string): Database {
+  static fromSchema(dbPath: string, schemaPath: string, options?: DatabaseOptions): Database {
     const lib = getSymbols();
-    const options = makeDefaultOptions();
+    const optionsBuf = makeDefaultOptions(options);
     const outDb = allocPtrOut();
     const dbPathBuf = toCString(dbPath);
     const schemaPathBuf = toCString(schemaPath);
 
     check(
-      lib.quiver_database_from_schema(dbPathBuf.buf, schemaPathBuf.buf, options.buf, outDb.ptr),
+      lib.quiver_database_from_schema(dbPathBuf.buf, schemaPathBuf.buf, optionsBuf.buf, outDb.buf),
     );
 
     return new Database(readPtrOut(outDb));
   }
 
-  static fromMigrations(dbPath: string, migrationsPath: string): Database {
+  static fromMigrations(
+    dbPath: string,
+    migrationsPath: string,
+    options?: DatabaseOptions,
+  ): Database {
     const lib = getSymbols();
-    const options = makeDefaultOptions();
+    const optionsBuf = makeDefaultOptions(options);
     const outDb = allocPtrOut();
     const dbPathBuf = toCString(dbPath);
     const migrPathBuf = toCString(migrationsPath);
 
     check(
-      lib.quiver_database_from_migrations(dbPathBuf.buf, migrPathBuf.buf, options.buf, outDb.ptr),
+      lib.quiver_database_from_migrations(
+        dbPathBuf.buf,
+        migrPathBuf.buf,
+        optionsBuf.buf,
+        outDb.buf,
+      ),
     );
 
     return new Database(readPtrOut(outDb));
   }
 
-  static open(dbPath: string): Database {
+  static open(dbPath: string, options?: DatabaseOptions): Database {
     const lib = getSymbols();
-    const options = makeDefaultOptions();
+    const optionsBuf = makeDefaultOptions(options);
     const outDb = allocPtrOut();
     const dbPathBuf = toCString(dbPath);
 
-    check(lib.quiver_database_open(dbPathBuf.buf, options.buf, outDb.ptr));
+    check(lib.quiver_database_open(dbPathBuf.buf, optionsBuf.buf, outDb.buf));
 
     return new Database(readPtrOut(outDb));
   }
@@ -130,12 +139,24 @@ export class Database {
 
   // --- Time series (implemented in time-series.ts) ---
   declare readTimeSeriesGroup: (collection: string, group: string, id: number) => TimeSeriesData;
+  declare readTimeSeriesRow: (
+    collection: string,
+    group: string,
+    attribute: string,
+    dateTime: string,
+  ) => (number | string | null)[];
   declare updateTimeSeriesGroup: (
     collection: string,
     group: string,
     id: number,
     data: TimeSeriesData,
   ) => void;
+  declare addTimeSeriesRow: (
+    collection: string,
+    group: string,
+    id: number,
+    row: Record<string, number | bigint | string>,
+  ) => void;
   declare hasTimeSeriesFiles: (collection: string) => boolean;
   declare listTimeSeriesFilesColumns: (collection: string) => string[];
   declare readTimeSeriesFiles: (collection: string) => Record<string, string | null>;

package/src/ffi-helpers.ts

@@ -1,5 +1,5 @@
 import { CString, type Pointer, ptr, read, toArrayBuffer } from "bun:ffi";
-import type { Allocation } from "./types.ts";
+import { type Allocation, type DatabaseOptions, LOG_LEVEL_INFO } from "./types.ts";
 
 const encoder = new TextEncoder();
 
@@ -7,11 +7,11 @@ const encoder = new TextEncoder();
  * Construct the 8-byte quiver_database_options_t struct as an Allocation.
  * Layout: offset 0 = int32 read_only (default 0), offset 4 = int32 console_level (default 1 = QUIVER_LOG_INFO).
  */
-export function makeDefaultOptions(): Allocation {
+export function makeDefaultOptions(options?: DatabaseOptions): Allocation {
   const buf = new Uint8Array(8);
   const dv = new DataView(buf.buffer);
-  dv.setInt32(0, 0, true); // read_only = false
-  dv.setInt32(4, 1, true); // console_level = QUIVER_LOG_INFO
+  dv.setInt32(0, options?.readOnly ? 1 : 0, true);
+  dv.setInt32(4, options?.consoleLevel ?? LOG_LEVEL_INFO, true);
   return { ptr: ptr(buf), buf };
 }
 
@@ -102,7 +102,7 @@ export function toCString(str: string): Allocation {
 }
 
 /** Allocate native memory for an array of int64 values. */
-export function allocNativeInt64(values: number[]): Allocation {
+export function allocNativeInt64(values: (number | bigint)[]): Allocation {
   const buf = new Uint8Array(values.length * 8);
   const dv = new DataView(buf.buffer);
   for (let i = 0; i < values.length; i++) {

package/src/index.ts

@@ -14,4 +14,18 @@ export { QuiverError } from "./errors.ts";
 export { LuaRunner } from "./lua-runner.ts";
 export type { GroupMetadata, ScalarMetadata } from "./metadata.ts";
 export type { TimeSeriesData } from "./time-series.ts";
-export type { ArrayValue, ElementData, QueryParam, ScalarValue, Value } from "./types.ts";
+export {
+  LOG_LEVEL_DEBUG,
+  LOG_LEVEL_ERROR,
+  LOG_LEVEL_INFO,
+  LOG_LEVEL_OFF,
+  LOG_LEVEL_WARN,
+} from "./types.ts";
+export type {
+  ArrayValue,
+  DatabaseOptions,
+  ElementData,
+  QueryParam,
+  ScalarValue,
+  Value,
+} from "./types.ts";

package/src/introspection.ts

@@ -1,29 +1,26 @@
-import { ptr } from "bun:ffi";
 import { Database } from "./database.ts";
 import { check } from "./errors.ts";
-import { allocPtrOut, decodeStringFromBuf, toCString } from "./ffi-helpers.ts";
+import { allocPtrOut, decodeStringFromBuf } from "./ffi-helpers.ts";
 import { getSymbols } from "./loader.ts";
 
 Database.prototype.isHealthy = function (this: Database): boolean {
   const lib = getSymbols();
   const outBuf = new Uint8Array(4);
-  const outPtr = ptr(outBuf);
-  check(lib.quiver_database_is_healthy(this._handle, outPtr));
+  check(lib.quiver_database_is_healthy(this._handle, outBuf));
   return new DataView(outBuf.buffer).getInt32(0, true) !== 0;
 };
 
 Database.prototype.currentVersion = function (this: Database): number {
   const lib = getSymbols();
   const outBuf = new Uint8Array(8);
-  const outPtr = ptr(outBuf);
-  check(lib.quiver_database_current_version(this._handle, outPtr));
+  check(lib.quiver_database_current_version(this._handle, outBuf));
   return Number(new DataView(outBuf.buffer).getBigInt64(0, true));
 };
 
 Database.prototype.path = function (this: Database): string {
   const lib = getSymbols();
   const outPath = allocPtrOut();
-  check(lib.quiver_database_path(this._handle, outPath.ptr));
+  check(lib.quiver_database_path(this._handle, outPath.buf));
   return decodeStringFromBuf(outPath);
 };
 

package/src/loader.ts

@@ -13,7 +13,6 @@ const I32 = "i32" as const;
 const I64 = "i64" as const;
 const USIZE = "usize" as const;
 const F64 = "f64" as const;
-const V = "void" as const;
 
 // Platform constants. `suffix` from bun:ffi is the platform-correct shared
 // library extension ("dll" | "dylib" | "so").
@@ -30,7 +29,6 @@ export type NativePointer = Pointer | null;
 const lifecycleSymbols = {
   quiver_version: { args: [], returns: P },
   quiver_get_last_error: { args: [], returns: P },
-  quiver_clear_last_error: { args: [], returns: V },
   // quiver_database_options_default is intentionally omitted: it returns a
   // struct by value, which Bun FFI does not support (oven-sh/bun#6139). It was
   // never called -- makeDefaultOptions() in ffi-helpers.ts builds the options
@@ -116,6 +114,8 @@ const metadataSymbols = {
 
 const timeSeriesSymbols = {
   quiver_database_read_time_series_group: { args: [P, BUF, BUF, I64, 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_add_time_series_row: { args: [P, BUF, BUF, I64, P, P, P, USIZE], returns: I32 },
   quiver_database_update_time_series_group: {
     args: [P, BUF, BUF, I64, P, P, P, USIZE, USIZE],
     returns: I32,
@@ -149,7 +149,6 @@ const luaSymbols = {
   quiver_lua_runner_new: { args: [P, P], returns: I32 },
   quiver_lua_runner_free: { args: [P], returns: I32 },
   quiver_lua_runner_run: { args: [P, BUF], returns: I32 },
-  quiver_lua_runner_get_error: { args: [P, P], returns: I32 },
 } as const;
 
 // Combined symbol map for dlopen.
@@ -281,5 +280,3 @@ export function loadLibrary(): QuiverLib {
 export function getSymbols() {
   return loadLibrary().symbols;
 }
-
-export type Symbols = ReturnType<typeof getSymbols>;

package/src/lua-runner.ts

@@ -1,6 +1,6 @@
 import type { Database } from "./database.ts";
 import { check, QuiverError } from "./errors.ts";
-import { allocPtrOut, decodeStringFromBuf, readPtrOut, toCString } from "./ffi-helpers.ts";
+import { allocPtrOut, readPtrOut, toCString } from "./ffi-helpers.ts";
 import type { NativePointer } from "./loader.ts";
 import { getSymbols } from "./loader.ts";
 
@@ -13,7 +13,7 @@ export class LuaRunner {
     this._db = db;
     const lib = getSymbols();
     const outRunner = allocPtrOut();
-    check(lib.quiver_lua_runner_new(db._handle, outRunner.ptr));
+    check(lib.quiver_lua_runner_new(db._handle, outRunner.buf));
     this._ptr = readPtrOut(outRunner);
   }
 
@@ -21,16 +21,7 @@ export class LuaRunner {
     this.ensureOpen();
     const lib = getSymbols();
     const scriptBuf = toCString(script);
-    const err = lib.quiver_lua_runner_run(this._ptr, scriptBuf.buf);
-    if (err !== 0) {
-      const outError = allocPtrOut();
-      const getErr = lib.quiver_lua_runner_get_error(this._ptr, outError.ptr);
-      if (getErr === 0 && readPtrOut(outError)) {
-        const msg = decodeStringFromBuf(outError);
-        if (msg) throw new QuiverError(msg);
-      }
-      check(err);
-    }
+    check(lib.quiver_lua_runner_run(this._ptr, scriptBuf.buf));
   }
 
   close(): void {

package/src/metadata.ts

@@ -79,10 +79,9 @@ Database.prototype.getScalarMetadata = function (
   const collBuf = toCString(collection);
   const attrBuf = toCString(attribute);
   const outBuf = new Uint8Array(SCALAR_METADATA_SIZE);
-  const outPtr = ptr(outBuf);
-  check(lib.quiver_database_get_scalar_metadata(this._handle, collBuf.buf, attrBuf.buf, outPtr));
-  const result = readScalarMetadataAt(outPtr, 0);
-  lib.quiver_database_free_scalar_metadata(outPtr);
+  check(lib.quiver_database_get_scalar_metadata(this._handle, collBuf.buf, attrBuf.buf, outBuf));
+  const result = readScalarMetadataAt(ptr(outBuf), 0);
+  lib.quiver_database_free_scalar_metadata(outBuf);
   return result;
 };
 
@@ -95,10 +94,9 @@ Database.prototype.getVectorMetadata = function (
   const collBuf = toCString(collection);
   const groupBuf = toCString(groupName);
   const outBuf = new Uint8Array(GROUP_METADATA_SIZE);
-  const outPtr = ptr(outBuf);
-  check(lib.quiver_database_get_vector_metadata(this._handle, collBuf.buf, groupBuf.buf, outPtr));
-  const result = readGroupMetadataAt(outPtr, 0);
-  lib.quiver_database_free_group_metadata(outPtr);
+  check(lib.quiver_database_get_vector_metadata(this._handle, collBuf.buf, groupBuf.buf, outBuf));
+  const result = readGroupMetadataAt(ptr(outBuf), 0);
+  lib.quiver_database_free_group_metadata(outBuf);
   return result;
 };
 
@@ -111,10 +109,9 @@ Database.prototype.getSetMetadata = function (
   const collBuf = toCString(collection);
   const groupBuf = toCString(groupName);
   const outBuf = new Uint8Array(GROUP_METADATA_SIZE);
-  const outPtr = ptr(outBuf);
-  check(lib.quiver_database_get_set_metadata(this._handle, collBuf.buf, groupBuf.buf, outPtr));
-  const result = readGroupMetadataAt(outPtr, 0);
-  lib.quiver_database_free_group_metadata(outPtr);
+  check(lib.quiver_database_get_set_metadata(this._handle, collBuf.buf, groupBuf.buf, outBuf));
+  const result = readGroupMetadataAt(ptr(outBuf), 0);
+  lib.quiver_database_free_group_metadata(outBuf);
   return result;
 };
 
@@ -127,12 +124,11 @@ Database.prototype.getTimeSeriesMetadata = function (
   const collBuf = toCString(collection);
   const groupBuf = toCString(groupName);
   const outBuf = new Uint8Array(GROUP_METADATA_SIZE);
-  const outPtr = ptr(outBuf);
   check(
-    lib.quiver_database_get_time_series_metadata(this._handle, collBuf.buf, groupBuf.buf, outPtr),
+    lib.quiver_database_get_time_series_metadata(this._handle, collBuf.buf, groupBuf.buf, outBuf),
   );
-  const result = readGroupMetadataAt(outPtr, 0);
-  lib.quiver_database_free_group_metadata(outPtr);
+  const result = readGroupMetadataAt(ptr(outBuf), 0);
+  lib.quiver_database_free_group_metadata(outBuf);
   return result;
 };
 
@@ -148,7 +144,7 @@ function listMetadata<T>(
   const collBuf = toCString(collection);
   const outArray = allocPtrOut();
   const outCount = allocUint64Out();
-  check((lib as Record<string, Function>)[fn](handle, collBuf.buf, outArray.ptr, outCount.ptr));
+  check((lib as Record<string, Function>)[fn](handle, collBuf.buf, outArray.buf, outCount.buf));
   const count = readUint64Out(outCount);
   if (count === 0) return [];
   const arrPtr = readPtrOut(outArray);

package/src/query.ts

@@ -12,12 +12,14 @@ import {
   toCString,
 } from "./ffi-helpers.ts";
 import { getSymbols } from "./loader.ts";
-import type { Allocation, QueryParam } from "./types.ts";
-
-const DATA_TYPE_INTEGER = 0;
-const DATA_TYPE_FLOAT = 1;
-const DATA_TYPE_STRING = 2;
-const DATA_TYPE_NULL = 4;
+import {
+  type Allocation,
+  DATA_TYPE_FLOAT,
+  DATA_TYPE_INTEGER,
+  DATA_TYPE_NULL,
+  DATA_TYPE_STRING,
+  type QueryParam,
+} from "./types.ts";
 
 function marshalParams(parameters: QueryParam[]): {
   types: Allocation;

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;