quiverdb 0.9.5 → 0.9.7

package/mod.ts

@@ -22,4 +22,4 @@ export type {
   TimeSeriesData,
   Value,
 } from "./src/index.ts";
-export { Database, LuaRunner, QuiverError } from "./src/index.ts";
+export { Database, LUA_DB_API_REFERENCE, LuaRunner, QuiverError } from "./src/index.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quiverdb",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "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>;
@@ -159,7 +180,9 @@ export class Database {
   declare isHealthy: () => boolean;
   declare currentVersion: () => number;
   declare path: () => string;
-  declare describe: () => void;
+  declare describe: () => string;
+  declare describeCollection: (collection: string) => string;
+  declare summarizeCollection: (collection: string) => string;
 
   // --- Composite helpers (implemented in composites.ts) ---
   declare readScalarsById: (

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

@@ -11,7 +11,22 @@ import "./composites.ts";
 export type { CsvOptions } from "./csv.ts";
 export { Database } from "./database.ts";
 export { QuiverError } from "./errors.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, ElementData, QueryParam, ScalarValue, Value } from "./types.ts";
+export type {
+  ArrayValue,
+  DatabaseOptions,
+  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";

package/src/introspection.ts

@@ -1,33 +1,54 @@
-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, readPtrOut, toCString } 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);
 };
 
-Database.prototype.describe = function (this: Database): void {
+Database.prototype.describe = function (this: Database): string {
   const lib = getSymbols();
-  check(lib.quiver_database_describe(this._handle));
+  const out = allocPtrOut();
+  check(lib.quiver_database_describe(this._handle, out.buf));
+  const result = decodeStringFromBuf(out);
+  lib.quiver_database_free_string(readPtrOut(out));
+  return result;
+};
+
+Database.prototype.describeCollection = function (this: Database, collection: string): string {
+  const lib = getSymbols();
+  const collBuf = toCString(collection);
+  const out = allocPtrOut();
+  check(lib.quiver_database_describe_collection(this._handle, collBuf.buf, out.buf));
+  const result = decodeStringFromBuf(out);
+  lib.quiver_database_free_string(readPtrOut(out));
+  return result;
+};
+
+Database.prototype.summarizeCollection = function (this: Database, collection: string): string {
+  const lib = getSymbols();
+  const collBuf = toCString(collection);
+  const out = allocPtrOut();
+  check(lib.quiver_database_summarize_collection(this._handle, collBuf.buf, out.buf));
+  const result = decodeStringFromBuf(out);
+  lib.quiver_database_free_string(readPtrOut(out));
+  return result;
 };

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
@@ -42,7 +40,7 @@ const lifecycleSymbols = {
   quiver_database_is_healthy: { args: [P, P], returns: I32 },
   quiver_database_path: { args: [P, P], returns: I32 },
   quiver_database_current_version: { args: [P, P], returns: I32 },
-  quiver_database_describe: { args: [P], returns: I32 },
+  quiver_database_describe: { args: [P, P], returns: I32 },
 } as const;
 
 const elementSymbols = {
@@ -114,8 +112,15 @@ const metadataSymbols = {
   quiver_database_list_time_series_groups: { args: [P, BUF, P, P], returns: I32 },
 } as const;
 
+const describeSymbols = {
+  quiver_database_describe_collection: { args: [P, BUF, P], returns: I32 },
+  quiver_database_summarize_collection: { args: [P, BUF, P], returns: I32 },
+} as const;
+
 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 +154,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.
@@ -161,6 +165,7 @@ const allSymbols = {
   ...querySymbols,
   ...transactionSymbols,
   ...metadataSymbols,
+  ...describeSymbols,
   ...timeSeriesSymbols,
   ...csvSymbols,
   ...freeSymbols,
@@ -281,5 +286,3 @@ export function loadLibrary(): QuiverLib {
 export function getSymbols() {
   return loadLibrary().symbols;
 }
-
-export type Symbols = ReturnType<typeof getSymbols>;