quiverdb 0.9.10 → 0.9.12

package/package.json

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

package/src/database.ts

@@ -88,9 +88,9 @@ export class Database {
   declare deleteElement: (collection: string, id: number) => void;
 
   // --- Reads (implemented in read.ts) ---
-  declare readScalarIntegers: (collection: string, attribute: string) => number[];
-  declare readScalarFloats: (collection: string, attribute: string) => number[];
-  declare readScalarStrings: (collection: string, attribute: string) => string[];
+  declare readScalarIntegers: (collection: string, attribute: string) => (number | null)[];
+  declare readScalarFloats: (collection: string, attribute: string) => (number | null)[];
+  declare readScalarStrings: (collection: string, attribute: string) => (string | null)[];
   declare readScalarIntegerById: (
     collection: string,
     attribute: string,
@@ -151,7 +151,7 @@ export class Database {
     id: number,
     data: TimeSeriesData,
   ) => void;
-  declare addTimeSeriesRow: (
+  declare upsertTimeSeriesRow: (
     collection: string,
     group: string,
     id: number,

package/src/loader.ts

@@ -62,8 +62,8 @@ const crudSymbols = {
 } as const;
 
 const readSymbols = {
-  quiver_database_read_scalar_integers: { args: [P, BUF, BUF, P, P], returns: I32 },
-  quiver_database_read_scalar_floats: { args: [P, BUF, BUF, P, P], returns: I32 },
+  quiver_database_read_scalar_integers: { args: [P, BUF, BUF, P, P, P], returns: I32 },
+  quiver_database_read_scalar_floats: { args: [P, BUF, BUF, P, P, P], returns: I32 },
   quiver_database_read_scalar_strings: { args: [P, BUF, BUF, P, P], returns: I32 },
   quiver_database_read_scalar_integer_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
   quiver_database_read_scalar_float_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
@@ -123,7 +123,10 @@ const timeSeriesSymbols = {
     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_upsert_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, P, USIZE, USIZE],
     returns: I32,
@@ -144,6 +147,7 @@ const csvSymbols = {
 const freeSymbols = {
   quiver_database_free_integer_array: { args: [P], returns: I32 },
   quiver_database_free_float_array: { args: [P], returns: I32 },
+  quiver_database_free_mask: { args: [P], returns: I32 },
   quiver_database_free_string_array: { args: [P, USIZE], returns: I32 },
   quiver_database_free_string: { args: [P], returns: I32 },
   quiver_database_free_integer_vectors: { args: [P, P, USIZE], returns: I32 },

package/src/lua-api.ts

@@ -166,7 +166,7 @@ Notes:
   \`{ x = nil }\` is identical to \`{}\`; an update/create table that ends up with no attributes
   **throws** (\`element must have at least one attribute\`). To leave a column unchanged, omit the
   key — you cannot set a scalar to NULL via the element table. (\`nil\` → NULL is only accepted by
-  \`add_time_series_row\` and \`update_time_series_files\`.)
+  \`upsert_time_series_row\` and \`update_time_series_files\`.)
 
 ---
 
@@ -274,7 +274,7 @@ db:update_time_series_group("Items", "data", id, ts)   -- write the whole group
 \`\`\`
 
 **DO NOT pass an array of row tables** (\`{ { date_time = ..., value = ... }, ... }\`) — that is the
-\`add_time_series_row\` shape, not this one. Doing so raises
+\`upsert_time_series_row\` shape, not this one. Doing so raises
 \`stack index -1, expected string, received number\` (the integer array indices 1, 2, 3 are not
 column names). Each value of the top-level table must be an **array**, not a scalar.
 
@@ -293,13 +293,13 @@ column names). Each value of the top-level table must be an **array**, not a sca
 - Integer values are accepted for REAL columns (converted on insert). Booleans, functions, and
   other unsupported Lua types throw \`column '...' has unsupported Lua type\`.
 
-### Append/upsert a single row (\`add_time_series_row\` — ROW-oriented, the one exception)
+### Append/upsert a single row (\`upsert_time_series_row\` — ROW-oriented, the one exception)
 
 Unlike the column-oriented group update above, this takes **one row table of scalars** (dimension
 column + value column(s)), and upserts that single row:
 
 \`\`\`lua
-db:add_time_series_row("Items", "data", id, {
+db:upsert_time_series_row("Items", "data", id, {
     date_time = "2024-01-04T00:00:00",
     value     = 40.0,
 })

package/src/read.ts

@@ -1,3 +1,4 @@
+import { CString, type Pointer, toArrayBuffer } from "bun:ffi";
 import { Database } from "./database.ts";
 import { check } from "./errors.ts";
 import {
@@ -21,11 +22,12 @@ Database.prototype.readScalarIntegers = function (
   this: Database,
   collection: string,
   attribute: string,
-): number[] {
+): (number | null)[] {
   const lib = getSymbols();
   const collBuf = toCString(collection);
   const attrBuf = toCString(attribute);
   const outValues = allocPtrOut();
+  const outMask = allocPtrOut();
   const outCount = allocUint64Out();
   check(
     lib.quiver_database_read_scalar_integers(
@@ -33,14 +35,20 @@ Database.prototype.readScalarIntegers = function (
       collBuf.buf,
       attrBuf.buf,
       outValues.buf,
+      outMask.buf,
       outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
   if (count === 0) return [];
   const arrPtr = readPtrOut(outValues);
-  const result = decodeInt64Array(arrPtr, count);
+  const maskPtr = readPtrOut(outMask);
+  const vals = decodeInt64Array(arrPtr, count);
+  // mask[i] === 0 means SQL NULL; gate to null (never Number(placeholder)).
+  const mask = new Uint8Array(toArrayBuffer(maskPtr as Pointer, 0, count));
+  const result = vals.map((v, i) => (mask[i] ? v : null));
   lib.quiver_database_free_integer_array(arrPtr);
+  lib.quiver_database_free_mask(maskPtr);
   return result;
 };
 
@@ -48,11 +56,12 @@ Database.prototype.readScalarFloats = function (
   this: Database,
   collection: string,
   attribute: string,
-): number[] {
+): (number | null)[] {
   const lib = getSymbols();
   const collBuf = toCString(collection);
   const attrBuf = toCString(attribute);
   const outValues = allocPtrOut();
+  const outMask = allocPtrOut();
   const outCount = allocUint64Out();
   check(
     lib.quiver_database_read_scalar_floats(
@@ -60,14 +69,19 @@ Database.prototype.readScalarFloats = function (
       collBuf.buf,
       attrBuf.buf,
       outValues.buf,
+      outMask.buf,
       outCount.buf,
     ),
   );
   const count = readUint64Out(outCount);
   if (count === 0) return [];
   const arrPtr = readPtrOut(outValues);
-  const result = decodeFloat64Array(arrPtr, count);
+  const maskPtr = readPtrOut(outMask);
+  const vals = decodeFloat64Array(arrPtr, count);
+  const mask = new Uint8Array(toArrayBuffer(maskPtr as Pointer, 0, count));
+  const result = vals.map((v, i) => (mask[i] ? v : null));
   lib.quiver_database_free_float_array(arrPtr);
+  lib.quiver_database_free_mask(maskPtr);
   return result;
 };
 
@@ -75,7 +89,7 @@ Database.prototype.readScalarStrings = function (
   this: Database,
   collection: string,
   attribute: string,
-): string[] {
+): (string | null)[] {
   const lib = getSymbols();
   const collBuf = toCString(collection);
   const attrBuf = toCString(attribute);
@@ -93,7 +107,11 @@ Database.prototype.readScalarStrings = function (
   const count = readUint64Out(outCount);
   if (count === 0) return [];
   const arrPtr = readPtrOut(outValues);
-  const result = decodeStringArray(arrPtr, count);
+  // A NULL string is a NULL char* entry: decode the (null-guarded) pointer array and map
+  // NULL -> null (decodeStringArray would construct "" from a NULL pointer instead).
+  const result = decodePtrArray(arrPtr, count).map((p) =>
+    p === null ? null : new CString(p).toString(),
+  );
   lib.quiver_database_free_string_array(arrPtr, BigInt(count));
   return result;
 };

package/src/time-series.ts

@@ -318,7 +318,7 @@ Database.prototype.updateTimeSeriesGroup = function (
   );
 };
 
-Database.prototype.addTimeSeriesRow = function (
+Database.prototype.upsertTimeSeriesRow = function (
   this: Database,
   collection: string,
   group: string,
@@ -366,7 +366,7 @@ Database.prototype.addTimeSeriesRow = function (
   keepalive.push(dataTable);
 
   check(
-    lib.quiver_database_add_time_series_row(
+    lib.quiver_database_upsert_time_series_row(
       this._handle,
       collBuf.buf,
       grpBuf.buf,