quiverdb 0.6.1 → 0.9.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PSR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,29 +1,41 @@
 # quiverdb
 
-SQLite wrapper binding for Quiver via koffi FFI. Works with Node.js, Deno, and Bun.
+SQLite wrapper binding for Quiver via Bun FFI (`bun:ffi`).
 
 ## Requirements
 
-- Node.js >= 20, Deno >= 2.0, or Bun >= 1.0
-- `libquiver.dll` and `libquiver_c.dll` (or `.so`/`.dylib`) in system PATH
+- [Bun](https://bun.sh) >= 1.1
+- `libquiver.dll` and `libquiver_c.dll` (or `.so`/`.dylib`) accessible (see [Native Library Setup](#native-library-setup))
 
 ## Installation
 
 ```bash
-npm install quiverdb
+bun add quiverdb
 ```
 
-The native Quiver libraries must be compiled separately and available in your system PATH. See the Quiver project build instructions for details.
+The bundled native libraries ship inside the package, so no separate download
+step is required on supported platforms. To build the native libraries from
+source, see the Quiver project build instructions.
+
+```typescript
+import { Database } from "quiverdb";
+```
+
+Bun loads native code via FFI without any permission flags — unlike Deno, there
+is no `--allow-ffi`/`--allow-read`/`--allow-write` to pass.
 
 ## Native Library Setup
 
-This binding loads the Quiver C API library (`libquiver_c`) at runtime via koffi. The core library (`libquiver`) is a dependency that must also be loadable.
+The loader searches for native libraries in three tiers:
 
-Options for making the libraries available:
+1. **Bundled**: `libs/{os}-{arch}/` directory next to the binding source (shipped
+   inside the published package).
+2. **Dev mode**: Walks up directories looking for `build/bin/` (auto-discovered
+   during in-tree development against a local C++ build).
+3. **System PATH**: Falls back to loading by library name.
 
-1. Add the `build/bin/` directory to your system PATH
-2. Copy both libraries to a directory already in PATH
-3. Place both libraries alongside your application entry point
+Currently prebuilt binaries ship for `linux-x86_64` and `windows-x86_64`. On other
+platforms, build from source and point to `build/bin/` via tier 2.
 
 ## Quick Start
 
@@ -39,6 +51,12 @@ console.log(values); // [42]
 db.close();
 ```
 
+Run with:
+
+```bash
+bun run example.ts
+```
+
 ## API Methods
 
 ### Lifecycle
@@ -50,6 +68,7 @@ db.close();
 ### Create / Delete
 
 - `createElement(collection, data)` -- Create element, returns numeric ID
+- `updateElement(collection, id, data)` -- Update element by ID
 - `deleteElement(collection, id)` -- Delete element by ID
 
 ### Read (bulk)
@@ -57,22 +76,50 @@ db.close();
 - `readScalarIntegers(collection, attribute)` -- Read all integer scalars
 - `readScalarFloats(collection, attribute)` -- Read all float scalars
 - `readScalarStrings(collection, attribute)` -- Read all string scalars
+- `readVectorIntegers(collection, attribute)` -- Read all integer vectors
+- `readVectorFloats(collection, attribute)` -- Read all float vectors
+- `readVectorStrings(collection, attribute)` -- Read all string vectors
+- `readSetIntegers(collection, attribute)` -- Read all integer sets
+- `readSetFloats(collection, attribute)` -- Read all float sets
+- `readSetStrings(collection, attribute)` -- Read all string sets
 
 ### Read (by ID)
 
 - `readScalarIntegerById(collection, attribute, id)` -- Read integer or null
 - `readScalarFloatById(collection, attribute, id)` -- Read float or null
 - `readScalarStringById(collection, attribute, id)` -- Read string or null
+- `readVectorIntegersById(collection, attribute, id)` -- Read integer vector
+- `readVectorFloatsById(collection, attribute, id)` -- Read float vector
+- `readVectorStringsById(collection, attribute, id)` -- Read string vector
+- `readSetIntegersById(collection, attribute, id)` -- Read integer set
+- `readSetFloatsById(collection, attribute, id)` -- Read float set
+- `readSetStringsById(collection, attribute, id)` -- Read string set
 
 ### Read (IDs)
 
 - `readElementIds(collection)` -- Read all element IDs in a collection
 
+### Metadata
+
+- `getScalarMetadata(collection, attribute)` -- Get scalar attribute metadata
+- `getVectorMetadata(collection, attribute)` -- Get vector group metadata
+- `getSetMetadata(collection, attribute)` -- Get set group metadata
+- `getTimeSeriesMetadata(collection, attribute)` -- Get time series group metadata
+- `listScalarAttributes(collection)` -- List all scalar attributes
+- `listVectorGroups(collection)` -- List all vector groups
+- `listSetGroups(collection)` -- List all set groups
+- `listTimeSeriesGroups(collection)` -- List all time series groups
+
+### Time Series
+
+- `readTimeSeriesGroup(collection, group, id)` -- Read time series data for an element
+- `updateTimeSeriesGroup(collection, group, id, data)` -- Write time series data for an element
+
 ### Query
 
-- `queryString(sql, params?)` -- Query returning string or null
-- `queryInteger(sql, params?)` -- Query returning integer or null
-- `queryFloat(sql, params?)` -- Query returning float or null
+- `queryString(sql, parameters?)` -- Query returning string or null
+- `queryInteger(sql, parameters?)` -- Query returning integer or null
+- `queryFloat(sql, parameters?)` -- Query returning float or null
 
 Parameters are passed as an array of `number | string | null`.
 
@@ -83,6 +130,30 @@ Parameters are passed as an array of `number | string | null`.
 - `rollback()` -- Rollback current transaction
 - `inTransaction()` -- Check if transaction is active
 
+### CSV
+
+- `exportCsv(collection, group, filePath, options?)` -- Export collection group to CSV file
+- `importCsv(collection, group, filePath, options?)` -- Import CSV file into collection group
+
+### Composites
+
+- `readScalarsById(collection, id)` -- Read all scalar attributes for an element
+- `readVectorsById(collection, id)` -- Read all vector groups for an element
+- `readSetsById(collection, id)` -- Read all set groups for an element
+
+### Introspection
+
+- `describe()` -- Print schema info to stdout
+- `isHealthy()` -- Check database health
+- `path()` -- Get database file path
+- `currentVersion()` -- Get current schema version
+
+### Lua
+
+- `LuaRunner(db)` -- Create Lua script runner with database access
+- `run(script)` -- Execute a Lua script
+- `close()` -- Close the Lua runner
+
 ## Types
 
 Exported types available for TypeScript consumers:
@@ -93,16 +164,23 @@ Exported types available for TypeScript consumers:
 - `ElementData` -- `Record<string, Value | undefined>`
 - `QueryParam` -- `number | 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
 
 ## Development
 
 ```bash
-bun test         # Run all tests
-bun run typecheck # TypeScript type checking (tsc --noEmit)
-bun run lint     # Biome linting
-bun run format   # Biome formatting (auto-fix)
+bun install          # Install dev dependencies (@types/bun, biome)
+bun test test        # Run all tests
+bun run lint         # Biome linting
+bun run format       # Biome formatting (auto-fix)
 ```
 
+Tests discover the native library from a local `build/bin/` (tier 2). On Windows,
+prepend `build/bin` to `PATH` first (the `test/test.bat` helper does this for you).
+
 ## License
 
 MIT

package/mod.ts

@@ -0,0 +1,25 @@
+/**
+ * @module
+ * Quiver - SQLite wrapper with typed FFI bindings for Bun.
+ *
+ * @example
+ * ```ts
+ * import { Database } from "quiverdb";
+ *
+ * const db = Database.fromSchema("my.db", "schema.sql");
+ * db.close();
+ * ```
+ */
+
+export type {
+  ArrayValue,
+  CsvOptions,
+  ElementData,
+  GroupMetadata,
+  QueryParam,
+  ScalarMetadata,
+  ScalarValue,
+  TimeSeriesData,
+  Value,
+} from "./src/index.ts";
+export { Database, LuaRunner, QuiverError } from "./src/index.ts";

package/package.json

@@ -1,47 +1,34 @@
 {
   "name": "quiverdb",
-  "version": "0.6.1",
-  "description": "SQLite wrapper binding for Quiver via koffi FFI",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "files": [
-    "dist/"
-  ],
+  "version": "0.9.2",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/psrenergy/quiver",
+    "url": "git+https://github.com/psrenergy/quiver.git",
     "directory": "bindings/js"
   },
-  "keywords": [
-    "sqlite",
-    "database",
-    "ffi",
-    "node",
-    "deno",
-    "quiver"
+  "type": "module",
+  "exports": {
+    ".": "./mod.ts"
+  },
+  "types": "./mod.ts",
+  "files": [
+    "mod.ts",
+    "src/**/*.ts",
+    "libs/**",
+    "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
+    "test": "bun test test",
     "lint": "biome check",
     "format": "biome format --write"
   },
-  "dependencies": {
-    "koffi": "^2.9.0"
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
-    "@types/node": "^22.0.0",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.1"
+    "@types/bun": "latest"
   }
 }

package/src/composites.ts

@@ -0,0 +1,89 @@
+import { Database } from "./database.ts";
+
+Database.prototype.readScalarsById = function (
+  this: Database,
+  collection: string,
+  id: number,
+): Record<string, number | string | null> {
+  const attributes = this.listScalarAttributes(collection);
+  const result: Record<string, number | string | null> = {};
+
+  for (const attr of attributes) {
+    switch (attr.dataType) {
+      case 0: // INTEGER
+        result[attr.name] = this.readScalarIntegerById(collection, attr.name, id);
+        break;
+      case 1: // FLOAT
+        result[attr.name] = this.readScalarFloatById(collection, attr.name, id);
+        break;
+      case 2: // STRING
+      case 3: // 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}'`);
+    }
+  }
+
+  return result;
+};
+
+Database.prototype.readVectorsById = function (
+  this: Database,
+  collection: string,
+  id: number,
+): Record<string, number[] | string[]> {
+  const groups = this.listVectorGroups(collection);
+  const result: Record<string, number[] | string[]> = {};
+
+  for (const group of groups) {
+    for (const col of group.valueColumns) {
+      switch (col.dataType) {
+        case 0: // INTEGER
+          result[col.name] = this.readVectorIntegersById(collection, col.name, id);
+          break;
+        case 1: // FLOAT
+          result[col.name] = this.readVectorFloatsById(collection, col.name, id);
+          break;
+        case 2: // STRING
+        case 3: // 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}'`);
+      }
+    }
+  }
+
+  return result;
+};
+
+Database.prototype.readSetsById = function (
+  this: Database,
+  collection: string,
+  id: number,
+): Record<string, number[] | string[]> {
+  const groups = this.listSetGroups(collection);
+  const result: Record<string, number[] | string[]> = {};
+
+  for (const group of groups) {
+    for (const col of group.valueColumns) {
+      switch (col.dataType) {
+        case 0: // INTEGER
+          result[col.name] = this.readSetIntegersById(collection, col.name, id);
+          break;
+        case 1: // FLOAT
+          result[col.name] = this.readSetFloatsById(collection, col.name, id);
+          break;
+        case 2: // STRING
+        case 3: // 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}'`);
+      }
+    }
+  }
+
+  return result;
+};

package/src/create.ts

@@ -0,0 +1,152 @@
+import { ptr } from "bun:ffi";
+import { Database } from "./database.ts";
+import { check, QuiverError } from "./errors.ts";
+import {
+  allocNativeFloat64,
+  allocNativeInt64,
+  allocNativeStringArray,
+  allocPtrOut,
+  readPtrOut,
+  toCString,
+} from "./ffi-helpers.ts";
+import { getSymbols, type NativePointer } from "./loader.ts";
+import type { ElementData, Value } from "./types.ts";
+
+type Symbols = ReturnType<typeof getSymbols>;
+
+function setElementArray(
+  lib: Symbols,
+  elemPtr: NativePointer,
+  name: string,
+  values: unknown[],
+): void {
+  const nameBuf = toCString(name);
+
+  if (values.length === 0) {
+    check(lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, null, 0));
+    return;
+  }
+
+  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));
+    return;
+  }
+
+  if (typeof first === "number") {
+    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));
+    } else {
+      const arr = allocNativeFloat64(values as number[]);
+      check(lib.quiver_element_set_array_float(elemPtr, nameBuf.buf, arr.ptr, 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));
+    return;
+  }
+
+  throw new QuiverError(`Unsupported array element type for '${name}': ${typeof first}`);
+}
+
+function setElementField(lib: Symbols, elemPtr: NativePointer, name: string, value: Value): void {
+  const nameBuf = toCString(name);
+
+  if (value === null) {
+    check(lib.quiver_element_set_null(elemPtr, nameBuf.buf));
+    return;
+  }
+
+  if (typeof value === "bigint") {
+    check(lib.quiver_element_set_integer(elemPtr, nameBuf.buf, value));
+    return;
+  }
+
+  if (typeof value === "number") {
+    if (Number.isInteger(value)) {
+      check(lib.quiver_element_set_integer(elemPtr, nameBuf.buf, BigInt(value)));
+    } else {
+      check(lib.quiver_element_set_float(elemPtr, nameBuf.buf, value));
+    }
+    return;
+  }
+
+  if (typeof value === "string") {
+    const valBuf = toCString(value);
+    check(lib.quiver_element_set_string(elemPtr, nameBuf.buf, valBuf.buf));
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    setElementArray(lib, elemPtr, name, value);
+    return;
+  }
+
+  throw new QuiverError(`Unsupported value type for '${name}': ${typeof value}`);
+}
+
+Database.prototype.createElement = function (
+  this: Database,
+  collection: string,
+  data: ElementData,
+): number {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outElem = allocPtrOut();
+  check(lib.quiver_element_create(outElem.ptr));
+  const elemPtr = readPtrOut(outElem);
+
+  try {
+    for (const [key, value] of Object.entries(data)) {
+      if (value === undefined) continue;
+      setElementField(lib, elemPtr, key, value);
+    }
+
+    const outIdBuf = new Uint8Array(8);
+    const outIdPtr = ptr(outIdBuf);
+    const collBuf = toCString(collection);
+    check(lib.quiver_database_create_element(handle, collBuf.buf, elemPtr, outIdPtr));
+    return Number(new DataView(outIdBuf.buffer).getBigInt64(0, true));
+  } finally {
+    lib.quiver_element_destroy(elemPtr);
+  }
+};
+
+Database.prototype.updateElement = function (
+  this: Database,
+  collection: string,
+  id: number,
+  data: ElementData,
+): void {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outElem = allocPtrOut();
+  check(lib.quiver_element_create(outElem.ptr));
+  const elemPtr = readPtrOut(outElem);
+
+  try {
+    for (const [key, value] of Object.entries(data)) {
+      if (value === undefined) continue;
+      setElementField(lib, elemPtr, key, value);
+    }
+    const collBuf = toCString(collection);
+    check(lib.quiver_database_update_element(handle, collBuf.buf, BigInt(id), elemPtr));
+  } finally {
+    lib.quiver_element_destroy(elemPtr);
+  }
+};
+
+Database.prototype.deleteElement = function (this: Database, collection: string, id: number): void {
+  const lib = getSymbols();
+  const collBuf = toCString(collection);
+  check(lib.quiver_database_delete_element(this._handle, collBuf.buf, BigInt(id)));
+};

package/src/csv.ts

@@ -0,0 +1,118 @@
+import { ptr } from "bun:ffi";
+import { Database } from "./database.ts";
+import { check } from "./errors.ts";
+import {
+  allocNativeInt64,
+  allocNativeString,
+  allocNativeStringArray,
+  nativeAddress,
+  toCString,
+} from "./ffi-helpers.ts";
+import { getSymbols } from "./loader.ts";
+import type { Allocation } from "./types.ts";
+
+export interface CsvOptions {
+  dateTimeFormat?: string;
+  enumLabels?: Record<string, Record<string, Record<string, number>>>;
+}
+
+/**
+ * Build the 56-byte quiver_csv_options_t struct as an Allocation.
+ * Returns [structAllocation, keepalive] where keepalive prevents GC of native allocations.
+ */
+function buildCsvOptionsBuffer(options?: CsvOptions): [Allocation, Allocation[]] {
+  const buf = new Uint8Array(56);
+  const dv = new DataView(buf.buffer);
+  const keepalive: Allocation[] = [];
+
+  const dtfStr = allocNativeString(options?.dateTimeFormat ?? "");
+  keepalive.push(dtfStr);
+  dv.setBigUint64(0, nativeAddress(dtfStr.ptr), true);
+
+  if (!options?.enumLabels || Object.keys(options.enumLabels).length === 0) {
+    return [{ ptr: ptr(buf), buf }, keepalive];
+  }
+
+  const groupAttrNames: string[] = [];
+  const groupLocaleNames: string[] = [];
+  const groupEntryCounts: number[] = [];
+  const allLabels: string[] = [];
+  const allValues: number[] = [];
+
+  for (const [attrName, locales] of Object.entries(options.enumLabels)) {
+    for (const [localeName, entries] of Object.entries(locales)) {
+      groupAttrNames.push(attrName);
+      groupLocaleNames.push(localeName);
+      groupEntryCounts.push(Object.keys(entries).length);
+      for (const [label, value] of Object.entries(entries)) {
+        allLabels.push(label);
+        allValues.push(value);
+      }
+    }
+  }
+
+  const groupCount = groupAttrNames.length;
+
+  const { table: attrTable, keepalive: attrPtrs } = allocNativeStringArray(groupAttrNames);
+  keepalive.push(attrTable, ...attrPtrs);
+
+  const { table: localeTable, keepalive: localePtrs } = allocNativeStringArray(groupLocaleNames);
+  keepalive.push(localeTable, ...localePtrs);
+
+  const entryCountsBuf = new Uint8Array(groupCount * 8);
+  const entryCountsDv = new DataView(entryCountsBuf.buffer);
+  for (let i = 0; i < groupCount; i++) {
+    entryCountsDv.setBigUint64(i * 8, BigInt(groupEntryCounts[i]), true);
+  }
+  const entryCounts: Allocation = { ptr: ptr(entryCountsBuf), buf: entryCountsBuf };
+  keepalive.push(entryCounts);
+
+  const { table: labelsTable, keepalive: labelPtrs } = allocNativeStringArray(allLabels);
+  keepalive.push(labelsTable, ...labelPtrs);
+
+  const valuesArr = allocNativeInt64(allValues);
+  keepalive.push(valuesArr);
+
+  dv.setBigUint64(8, nativeAddress(attrTable.ptr), true);
+  dv.setBigUint64(16, nativeAddress(localeTable.ptr), true);
+  dv.setBigUint64(24, nativeAddress(entryCounts.ptr), true);
+  dv.setBigUint64(32, nativeAddress(labelsTable.ptr), true);
+  dv.setBigUint64(40, nativeAddress(valuesArr.ptr), true);
+  dv.setBigUint64(48, BigInt(groupCount), true);
+
+  return [{ ptr: ptr(buf), buf }, keepalive];
+}
+
+Database.prototype.exportCsv = function (
+  this: Database,
+  collection: string,
+  group: string,
+  filePath: string,
+  options?: CsvOptions,
+): void {
+  const lib = getSymbols();
+  const collBuf = toCString(collection);
+  const grpBuf = toCString(group);
+  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),
+  );
+};
+
+Database.prototype.importCsv = function (
+  this: Database,
+  collection: string,
+  group: string,
+  filePath: string,
+  options?: CsvOptions,
+): void {
+  const lib = getSymbols();
+  const collBuf = toCString(collection);
+  const grpBuf = toCString(group);
+  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),
+  );
+};