quiverdb 0.6.1 → 0.9.2

package/src/lua-runner.ts

@@ -0,0 +1,48 @@
+import type { Database } from "./database.ts";
+import { check, QuiverError } from "./errors.ts";
+import { allocPtrOut, decodeStringFromBuf, readPtrOut, toCString } from "./ffi-helpers.ts";
+import type { NativePointer } from "./loader.ts";
+import { getSymbols } from "./loader.ts";
+
+export class LuaRunner {
+  private _ptr: NativePointer;
+  private _db: Database;
+  private _closed = false;
+
+  constructor(db: Database) {
+    this._db = db;
+    const lib = getSymbols();
+    const outRunner = allocPtrOut();
+    check(lib.quiver_lua_runner_new(db._handle, outRunner.ptr));
+    this._ptr = readPtrOut(outRunner);
+  }
+
+  run(script: string): void {
+    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);
+    }
+  }
+
+  close(): void {
+    if (this._closed) return;
+    const lib = getSymbols();
+    check(lib.quiver_lua_runner_free(this._ptr));
+    this._closed = true;
+  }
+
+  private ensureOpen(): void {
+    if (this._closed) {
+      throw new QuiverError("LuaRunner is closed");
+    }
+  }
+}

package/src/metadata.ts

@@ -0,0 +1,218 @@
+import { CString, type Pointer, ptr, read } from "bun:ffi";
+import { Database } from "./database.ts";
+import { check } from "./errors.ts";
+import {
+  allocPtrOut,
+  allocUint64Out,
+  readPtrOut,
+  readUint64Out,
+  toCString,
+} from "./ffi-helpers.ts";
+import { getSymbols, type NativePointer } from "./loader.ts";
+
+export interface ScalarMetadata {
+  name: string;
+  dataType: number;
+  notNull: boolean;
+  primaryKey: boolean;
+  defaultValue: string | null;
+  isForeignKey: boolean;
+  referencesCollection: string | null;
+  referencesColumn: string | null;
+}
+
+export interface GroupMetadata {
+  groupName: string;
+  dimensionColumn: string | null;
+  valueColumns: ScalarMetadata[];
+}
+
+const SCALAR_METADATA_SIZE = 56;
+const GROUP_METADATA_SIZE = 32;
+
+function readNullableString(base: Pointer, offset: number): string | null {
+  const p = read.ptr(base, offset);
+  if (p === 0) return null;
+  return new CString(p as Pointer).toString();
+}
+
+function readScalarMetadataAt(base: Pointer, byteOffset: number): ScalarMetadata {
+  const namePtr = read.ptr(base, byteOffset + 0);
+  return {
+    name: namePtr === 0 ? "" : new CString(namePtr as Pointer).toString(),
+    dataType: read.i32(base, byteOffset + 8),
+    notNull: read.i32(base, byteOffset + 12) !== 0,
+    primaryKey: read.i32(base, byteOffset + 16) !== 0,
+    defaultValue: readNullableString(base, byteOffset + 24),
+    isForeignKey: read.i32(base, byteOffset + 32) !== 0,
+    referencesCollection: readNullableString(base, byteOffset + 40),
+    referencesColumn: readNullableString(base, byteOffset + 48),
+  };
+}
+
+function readGroupMetadataAt(base: Pointer, byteOffset: number): GroupMetadata {
+  const groupNamePtr = read.ptr(base, byteOffset + 0);
+  const dimColPtr = read.ptr(base, byteOffset + 8);
+  const valueColumnsPtr = read.ptr(base, byteOffset + 16);
+  const valueColumnCount = Number(read.u64(base, byteOffset + 24));
+
+  const valueColumns: ScalarMetadata[] = new Array(valueColumnCount);
+  if (valueColumnsPtr !== 0 && valueColumnCount > 0) {
+    for (let i = 0; i < valueColumnCount; i++) {
+      valueColumns[i] = readScalarMetadataAt(valueColumnsPtr as Pointer, i * SCALAR_METADATA_SIZE);
+    }
+  }
+
+  return {
+    groupName: groupNamePtr === 0 ? "" : new CString(groupNamePtr as Pointer).toString(),
+    dimensionColumn: dimColPtr === 0 ? null : new CString(dimColPtr as Pointer).toString(),
+    valueColumns,
+  };
+}
+
+Database.prototype.getScalarMetadata = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+): ScalarMetadata {
+  const lib = getSymbols();
+  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);
+  return result;
+};
+
+Database.prototype.getVectorMetadata = function (
+  this: Database,
+  collection: string,
+  groupName: string,
+): GroupMetadata {
+  const lib = getSymbols();
+  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);
+  return result;
+};
+
+Database.prototype.getSetMetadata = function (
+  this: Database,
+  collection: string,
+  groupName: string,
+): GroupMetadata {
+  const lib = getSymbols();
+  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);
+  return result;
+};
+
+Database.prototype.getTimeSeriesMetadata = function (
+  this: Database,
+  collection: string,
+  groupName: string,
+): GroupMetadata {
+  const lib = getSymbols();
+  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),
+  );
+  const result = readGroupMetadataAt(outPtr, 0);
+  lib.quiver_database_free_group_metadata(outPtr);
+  return result;
+};
+
+function listMetadata<T>(
+  lib: ReturnType<typeof getSymbols>,
+  handle: NativePointer,
+  fn: string,
+  collection: string,
+  structSize: number,
+  reader: (base: Pointer, offset: number) => T,
+  freeFn: string,
+): 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));
+  const count = readUint64Out(outCount);
+  if (count === 0) return [];
+  const arrPtr = readPtrOut(outArray);
+  const result: T[] = new Array(count);
+  for (let i = 0; i < count; i++) {
+    result[i] = reader(arrPtr as Pointer, i * structSize);
+  }
+  (lib as Record<string, Function>)[freeFn](arrPtr, BigInt(count));
+  return result;
+}
+
+Database.prototype.listScalarAttributes = function (
+  this: Database,
+  collection: string,
+): ScalarMetadata[] {
+  return listMetadata(
+    getSymbols(),
+    this._handle,
+    "quiver_database_list_scalar_attributes",
+    collection,
+    SCALAR_METADATA_SIZE,
+    readScalarMetadataAt,
+    "quiver_database_free_scalar_metadata_array",
+  );
+};
+
+Database.prototype.listVectorGroups = function (
+  this: Database,
+  collection: string,
+): GroupMetadata[] {
+  return listMetadata(
+    getSymbols(),
+    this._handle,
+    "quiver_database_list_vector_groups",
+    collection,
+    GROUP_METADATA_SIZE,
+    readGroupMetadataAt,
+    "quiver_database_free_group_metadata_array",
+  );
+};
+
+Database.prototype.listSetGroups = function (this: Database, collection: string): GroupMetadata[] {
+  return listMetadata(
+    getSymbols(),
+    this._handle,
+    "quiver_database_list_set_groups",
+    collection,
+    GROUP_METADATA_SIZE,
+    readGroupMetadataAt,
+    "quiver_database_free_group_metadata_array",
+  );
+};
+
+Database.prototype.listTimeSeriesGroups = function (
+  this: Database,
+  collection: string,
+): GroupMetadata[] {
+  return listMetadata(
+    getSymbols(),
+    this._handle,
+    "quiver_database_list_time_series_groups",
+    collection,
+    GROUP_METADATA_SIZE,
+    readGroupMetadataAt,
+    "quiver_database_free_group_metadata_array",
+  );
+};

package/src/query.ts

@@ -0,0 +1,160 @@
+import { ptr } from "bun:ffi";
+import { Database } from "./database.ts";
+import { check, QuiverError } from "./errors.ts";
+import {
+  allocNativeFloat64,
+  allocNativeInt64,
+  allocNativeString,
+  allocPtrOut,
+  decodeStringFromBuf,
+  nativeAddress,
+  readPtrOut,
+  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;
+
+function marshalParams(parameters: QueryParam[]): {
+  types: Allocation;
+  values: Allocation;
+  _keepalive: Allocation[];
+} {
+  const n = parameters.length;
+  const typesBuf = new Uint8Array(n * 4);
+  const typesDv = new DataView(typesBuf.buffer);
+  const valuesBuf = new Uint8Array(n * 8);
+  const valuesDv = new DataView(valuesBuf.buffer);
+  const keepalive: Allocation[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const p = parameters[i];
+    if (p === null) {
+      typesDv.setInt32(i * 4, DATA_TYPE_NULL, true);
+      valuesDv.setBigInt64(i * 8, 0n, true);
+    } else if (typeof p === "number") {
+      if (Number.isInteger(p)) {
+        typesDv.setInt32(i * 4, DATA_TYPE_INTEGER, true);
+        const native = allocNativeInt64([p]);
+        keepalive.push(native);
+        valuesDv.setBigInt64(i * 8, nativeAddress(native.ptr), true);
+      } else {
+        typesDv.setInt32(i * 4, DATA_TYPE_FLOAT, true);
+        const native = allocNativeFloat64([p]);
+        keepalive.push(native);
+        valuesDv.setBigInt64(i * 8, nativeAddress(native.ptr), true);
+      }
+    } else if (typeof p === "string") {
+      typesDv.setInt32(i * 4, DATA_TYPE_STRING, true);
+      const native = allocNativeString(p);
+      keepalive.push(native);
+      valuesDv.setBigInt64(i * 8, nativeAddress(native.ptr), true);
+    } else {
+      throw new QuiverError(`Unsupported query parameter type at index ${i}: ${typeof p}`);
+    }
+  }
+
+  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 };
+}
+
+Database.prototype.queryString = function (
+  this: Database,
+  sql: string,
+  parameters?: QueryParam[],
+): string | null {
+  const lib = getSymbols();
+  const sqlBuf = toCString(sql);
+  const outValue = allocPtrOut();
+  const outHasValue = new Uint8Array(4);
+
+  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));
+  }
+
+  if (new DataView(outHasValue.buffer).getInt32(0, true) === 0) return null;
+  const result = decodeStringFromBuf(outValue);
+  lib.quiver_database_free_string(readPtrOut(outValue));
+  return result;
+};
+
+Database.prototype.queryInteger = function (
+  this: Database,
+  sql: string,
+  parameters?: QueryParam[],
+): number | null {
+  const lib = getSymbols();
+  const sqlBuf = toCString(sql);
+  const outValue = new Uint8Array(8);
+  const outHasValue = new Uint8Array(4);
+
+  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));
+  }
+
+  if (new DataView(outHasValue.buffer).getInt32(0, true) === 0) return null;
+  return Number(new DataView(outValue.buffer).getBigInt64(0, true));
+};
+
+Database.prototype.queryFloat = function (
+  this: Database,
+  sql: string,
+  parameters?: QueryParam[],
+): number | null {
+  const lib = getSymbols();
+  const sqlBuf = toCString(sql);
+  const outValue = new Uint8Array(8);
+  const outHasValue = new Uint8Array(4);
+
+  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));
+  }
+
+  if (new DataView(outHasValue.buffer).getInt32(0, true) === 0) return null;
+  return new DataView(outValue.buffer).getFloat64(0, true);
+};