quiverdb 0.12.5 → 0.12.6

package/README.md

@@ -135,8 +135,8 @@ bun run example.ts
 - `queryBoolean(sql, parameters?)` -- Query returning an INTEGER-backed boolean or null
 - `queryFloat(sql, parameters?)` -- Query returning float or null
 
-Parameters are passed as an array of `number | boolean | string | null` (a `boolean` binds as the
-INTEGER 1 or 0).
+Parameters are passed as an array of `number | bigint | boolean | string | null` (a `bigint` binds
+as an exact INTEGER, a `boolean` as the INTEGER 1 or 0).
 
 ### Transaction
 
@@ -182,12 +182,15 @@ Exported types available for TypeScript consumers:
 - `ArrayValue` -- `number[] | bigint[] | string[]`
 - `Value` -- `ScalarValue | ArrayValue`
 - `ElementData` -- `Record<string, Value | undefined>`
-- `QueryParam` -- `number | string | null`
+- `QueryParam` -- `number | bigint | boolean | 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
+- `DatabaseOptions` -- `{ readOnly?: boolean; consoleLevel?: number }` (a `LOG_LEVEL_*` constant)
+- `LOG_LEVEL_DEBUG | INFO | WARN | ERROR | OFF`, `DATA_TYPE_INTEGER | FLOAT | STRING | DATE_TIME | NULL`
+  -- constants for `DatabaseOptions.consoleLevel` and metadata `dataType`
 
 ## Development
 

package/mod.ts

@@ -11,16 +11,4 @@
  * ```
  */
 
-export type {
-  ArrayValue,
-  CsvOptions,
-  ElementData,
-  GroupColumns,
-  GroupMetadata,
-  QueryParam,
-  ScalarMetadata,
-  ScalarValue,
-  TimeSeriesData,
-  Value,
-} from "./src/index.ts";
-export { Database, LUA_DB_API_REFERENCE, LuaRunner, QuiverError } from "./src/index.ts";
+export * from "./src/index.ts";

package/package.json

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

package/src/create.ts

@@ -8,7 +8,7 @@ import {
   readPtrOut,
   toCString,
 } from "./ffi-helpers.ts";
-import { type GroupColumns, updateGroupColumns } from "./group-columns.ts";
+import { type GroupColumns, numericCells, updateGroupColumns } from "./group-columns.ts";
 import { getSymbols, type NativePointer } from "./loader.ts";
 import type { ElementData, Value } from "./types.ts";
 
@@ -17,6 +17,7 @@ type Symbols = ReturnType<typeof getSymbols>;
 function setElementArray(
   lib: Symbols,
   elemPtr: NativePointer,
+  caller: string,
   name: string,
   values: unknown[],
 ): void {
@@ -39,27 +40,18 @@ function setElementArray(
     );
   }
 
-  if (typeof first === "bigint") {
-    const arr = allocNativeInt64(values as bigint[]);
-    check(lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.buf, values.length, null));
-    return;
-  }
-
-  if (typeof first === "boolean") {
-    const arr = allocNativeInt64((values as boolean[]).map((v) => (v ? 1 : 0)));
-    check(lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.buf, values.length, null));
-    return;
-  }
-
-  if (typeof first === "number") {
-    const allIntegers = (values as number[]).every((v) => Number.isInteger(v));
-    if (allIntegers) {
-      const arr = allocNativeInt64(values as number[]);
+  if (typeof first === "number" || typeof first === "boolean" || typeof first === "bigint") {
+    // The null check above leaves no null cell, so the cast only narrows.
+    const cells = numericCells(caller, name, values) as (number | bigint)[];
+    if (cells.every((v) => typeof v === "bigint" || Number.isInteger(v))) {
+      const arr = allocNativeInt64(cells);
       check(
         lib.quiver_element_set_array_integer(elemPtr, nameBuf.buf, arr.buf, values.length, null),
       );
     } else {
-      const arr = allocNativeFloat64(values as number[]);
+      // A fractional cell makes the array FLOAT; a bigint cell then follows the int-for-REAL rule
+      // through Number(), exact up to 2^53 like any JS number.
+      const arr = allocNativeFloat64(cells.map(Number));
       check(lib.quiver_element_set_array_float(elemPtr, nameBuf.buf, arr.buf, values.length, null));
     }
     return;
@@ -76,7 +68,13 @@ function setElementArray(
   throw new QuiverError(`Unsupported array element type for '${name}': ${typeof first}`);
 }
 
-function setElementField(lib: Symbols, elemPtr: NativePointer, name: string, value: Value): void {
+function setElementField(
+  lib: Symbols,
+  elemPtr: NativePointer,
+  caller: string,
+  name: string,
+  value: Value,
+): void {
   const nameBuf = toCString(name);
 
   if (value === null) {
@@ -110,7 +108,7 @@ function setElementField(lib: Symbols, elemPtr: NativePointer, name: string, val
   }
 
   if (Array.isArray(value)) {
-    setElementArray(lib, elemPtr, name, value);
+    setElementArray(lib, elemPtr, caller, name, value);
     return;
   }
 
@@ -132,7 +130,7 @@ Database.prototype.createElement = function (
   try {
     for (const [key, value] of Object.entries(data)) {
       if (value === undefined) continue;
-      setElementField(lib, elemPtr, key, value);
+      setElementField(lib, elemPtr, "createElement", key, value);
     }
 
     const outIdBuf = new Uint8Array(8);
@@ -160,7 +158,7 @@ Database.prototype.updateElement = function (
   try {
     for (const [key, value] of Object.entries(data)) {
       if (value === undefined) continue;
-      setElementField(lib, elemPtr, key, value);
+      setElementField(lib, elemPtr, "updateElement", key, value);
     }
     const collBuf = toCString(collection);
     check(lib.quiver_database_update_element(handle, collBuf.buf, BigInt(id), elemPtr));
@@ -186,7 +184,7 @@ Database.prototype.updateElementByLabel = function (
   try {
     for (const [key, value] of Object.entries(data)) {
       if (value === undefined) continue;
-      setElementField(lib, elemPtr, key, value);
+      setElementField(lib, elemPtr, "updateElementByLabel", key, value);
     }
     const collBuf = toCString(collection);
     const labelBuf = toCString(label);

package/src/group-columns.ts

@@ -24,12 +24,16 @@ import {
   DATA_TYPE_STRING,
 } from "./types.ts";
 
-/** Column-oriented group payload: one array of cells per column name, `null` for SQL NULL. */
-export type GroupColumns = Record<string, (number | string | boolean | null)[]>;
+/**
+ * Column-oriented group payload: one array of cells per column name, `null` for SQL NULL. A
+ * `bigint` cell is written as an exact int64 (like createElement); a `boolean` as INTEGER 1/0.
+ */
+export type GroupColumns = Record<string, (number | bigint | string | boolean | null)[]>;
 
 /**
  * Column-oriented group read result: one array of cells per column name, `null` for SQL NULL.
- * The read-side twin of GroupColumns; no reader produces a boolean, so it admits none.
+ * The read-side twin of GroupColumns; no reader produces a boolean or a bigint, so it admits
+ * neither.
  */
 export type TimeSeriesData = Record<string, (number | string | null)[]>;
 
@@ -51,6 +55,34 @@ type ColumnUpdateFn = (
   rowCount: bigint,
 ) => number;
 
+/**
+ * Check and normalize the cells of a numeric column: one whose first non-null cell is a number, a
+ * bigint or a boolean. Shared by updateGroupColumns and setElementArray (create.ts) so the group
+ * writers and the element arrays agree on every cell. String columns are never passed here.
+ *
+ * - A boolean becomes INTEGER 1/0, since SQLite has no boolean type. Per cell, because mapping the
+ *   whole column from a leading boolean truthiness-mapped the rest and rewrote [true, 5] as
+ *   [1, 1]. Before the INTEGER/FLOAT choice, because Number.isInteger(true) is false.
+ * - A bigint stays a bigint, so an INTEGER column keeps it exact; the caller maps it through
+ *   Number() only if the column turns out FLOAT.
+ * - Any other non-null cell throws, naming the column and the cell. It would fail
+ *   Number.isInteger, tag the column FLOAT and reach DataView.setFloat64, which converts it with no
+ *   error: "abc" to NaN, which SQLite stores as NULL, and "2" to 2.
+ */
+export function numericCells(
+  caller: string,
+  name: string,
+  values: readonly unknown[],
+): (number | bigint | null)[] {
+  return values.map((v, r) => {
+    if (v === null || typeof v === "number" || typeof v === "bigint") return v;
+    if (typeof v === "boolean") return v ? 1 : 0;
+    throw new QuiverError(
+      `Cannot ${caller}: numeric column '${name}' has unsupported value type ${typeof v} in cell ${r}`,
+    );
+  });
+}
+
 /**
  * Marshal a column-oriented payload and forward it to one of the columnar group update C
  * functions. Shared by updateTimeSeriesGroup / updateVectorGroup / updateSetGroup and their
@@ -114,16 +146,7 @@ export function updateGroupColumns(
   const maskPtrs: (Pointer | null)[] = [];
 
   for (let c = 0; c < columnCount; c++) {
-    const [colName, rawValues] = entries[c];
-    // SQLite has no boolean type: a boolean is INTEGER 1/0, as in setElementField and
-    // marshalParams. Normalizing per cell before the dispatch (rather than adding a boolean
-    // branch after it) is what makes a mixed [true, 5] column write 1 and 5 instead of
-    // truthiness-mapping every cell, and matches Python's per-cell `int(v)`. A string column is
-    // left alone so normalizing cannot change what a mixed ['a', true] column already wrote.
-    const isStringColumn = typeof rawValues.find((v) => v !== null) === "string";
-    const values = isStringColumn
-      ? rawValues
-      : rawValues.map((v) => (typeof v === "boolean" ? (v ? 1 : 0) : v));
+    const [colName, values] = entries[c];
     const first = values.find((v) => v !== null);
 
     // Mask via direct indexing — never a DataView, to avoid the documented
@@ -141,23 +164,29 @@ export function updateGroupColumns(
       keepalive.push(p);
       dataPtrs.push(p.ptr);
     } else if (typeof first === "string") {
+      // Not checked by numericCells: a mixed ['a', true] column still writes what it always wrote.
       typesDv.setInt32(c * 4, DATA_TYPE_STRING, true);
       const { table, keepalive: strPtrs } = allocNativeStringArray(
         values.map((v) => (v === null ? null : (v as string))),
       );
       keepalive.push(table, ...strPtrs);
       dataPtrs.push(table.ptr);
-    } else if (typeof first === "number") {
-      const nonNull = values.filter((v) => v !== null) as number[];
-      const sanitized = values.map((v) => (v === null ? 0 : (v as number)));
-      if (nonNull.every((v) => Number.isInteger(v))) {
+    } else if (
+      typeof first === "number" ||
+      typeof first === "boolean" ||
+      typeof first === "bigint"
+    ) {
+      const cells = numericCells(caller, colName, values);
+      if (cells.every((v) => v === null || typeof v === "bigint" || Number.isInteger(v))) {
         typesDv.setInt32(c * 4, DATA_TYPE_INTEGER, true);
-        const p = allocNativeInt64(sanitized);
+        const p = allocNativeInt64(cells.map((v) => v ?? 0));
         keepalive.push(p);
         dataPtrs.push(p.ptr);
       } else {
+        // A fractional cell makes the column FLOAT; a bigint cell then follows the int-for-REAL
+        // rule through Number(), exact up to 2^53 like any JS number.
         typesDv.setInt32(c * 4, DATA_TYPE_FLOAT, true);
-        const p = allocNativeFloat64(sanitized);
+        const p = allocNativeFloat64(cells.map((v) => (v === null ? 0 : Number(v))));
         keepalive.push(p);
         dataPtrs.push(p.ptr);
       }

package/src/index.ts

@@ -24,6 +24,11 @@ export type {
   Value,
 } from "./types.ts";
 export {
+  DATA_TYPE_DATE_TIME,
+  DATA_TYPE_FLOAT,
+  DATA_TYPE_INTEGER,
+  DATA_TYPE_NULL,
+  DATA_TYPE_STRING,
   LOG_LEVEL_DEBUG,
   LOG_LEVEL_ERROR,
   LOG_LEVEL_INFO,

package/src/query.ts

@@ -50,6 +50,11 @@ function marshalParams(parameters?: QueryParam[]): {
       const native = allocNativeInt64([p ? 1 : 0]);
       keepalive.push(native);
       valuesDv.setBigInt64(i * 8, nativeAddress(native.ptr), true);
+    } else if (typeof p === "bigint") {
+      typesDv.setInt32(i * 4, DATA_TYPE_INTEGER, true);
+      const native = allocNativeInt64([p]);
+      keepalive.push(native);
+      valuesDv.setBigInt64(i * 8, nativeAddress(native.ptr), true);
     } else if (typeof p === "number") {
       if (Number.isInteger(p)) {
         typesDv.setInt32(i * 4, DATA_TYPE_INTEGER, true);

package/src/types.ts

@@ -26,7 +26,8 @@ export type ScalarValue = number | bigint | boolean | string | null;
 export type ArrayValue = number[] | bigint[] | boolean[] | string[];
 export type Value = ScalarValue | ArrayValue;
 export type ElementData = Record<string, Value | undefined>;
-export type QueryParam = number | boolean | string | null;
+/** A `bigint` binds as an exact INTEGER; a `boolean` as INTEGER 1/0. */
+export type QueryParam = number | bigint | boolean | string | null;
 
 /** Native memory allocation result. Callers MUST hold `buf` in scope to prevent GC. */
 export type Allocation = {