quiverdb 0.10.3 → 0.10.4

package/mod.ts

@@ -15,6 +15,7 @@ export type {
   ArrayValue,
   CsvOptions,
   ElementData,
+  GroupColumns,
   GroupMetadata,
   QueryParam,
   ScalarMetadata,

package/package.json

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

package/src/database.ts

@@ -192,13 +192,13 @@ export class Database {
     collection: string,
     group: string,
     id: number,
-    data: TimeSeriesData,
+    data: GroupColumns,
   ) => void;
   declare updateTimeSeriesGroupByLabel: (
     collection: string,
     group: string,
     label: string,
-    data: TimeSeriesData,
+    data: GroupColumns,
   ) => void;
   declare updateVectorGroup: (
     collection: string,
@@ -228,13 +228,13 @@ export class Database {
     collection: string,
     group: string,
     id: number,
-    row: Record<string, number | bigint | string>,
+    row: Record<string, number | bigint | string | boolean>,
   ) => void;
   declare upsertTimeSeriesRowByLabel: (
     collection: string,
     group: string,
     label: string,
-    row: Record<string, number | bigint | string>,
+    row: Record<string, number | bigint | string | boolean>,
   ) => void;
   declare hasTimeSeriesFiles: (collection: string) => boolean;
   declare listTimeSeriesFilesColumns: (collection: string) => string[];

package/src/group-columns.ts

@@ -11,7 +11,7 @@ import type { NativePointer } from "./loader.ts";
 import { DATA_TYPE_FLOAT, DATA_TYPE_INTEGER, DATA_TYPE_STRING, type Allocation } 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 | null)[]>;
+export type GroupColumns = Record<string, (number | string | boolean | null)[]>;
 
 /**
  * The parallel-array signature every columnar group update C function shares
@@ -94,7 +94,16 @@ export function updateGroupColumns(
   const maskPtrs: (Pointer | null)[] = [];
 
   for (let c = 0; c < columnCount; c++) {
-    const [colName, values] = entries[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 first = values.find((v) => v !== null);
 
     // Mask via direct indexing — never a DataView, to avoid the documented

package/src/lua-api.ts

@@ -51,13 +51,25 @@ Lua values map to Quiver column values as follows:
 | integer            | INTEGER      | Also accepted for REAL columns (coerced to real). |
 | number (float)     | REAL         | A float is rejected for an INTEGER column.     |
 | string             | TEXT         | Also used for \`date_time\` columns (ISO 8601).  |
+| boolean            | INTEGER 1/0  | SQLite has no boolean type; \`true\` writes 1, \`false\` 0. |
 | \`nil\`              | NULL         | In query params, file paths, ts rows, relations.|
 | table (1-indexed)  | array        | Used for vectors/sets and column-oriented data.|
 
-**Unsupported types throw.** Passing a boolean, a function, or a nested table where a scalar is
-expected raises an error rather than silently dropping the value. This applies to element
-attributes, time-series rows, and query parameters. A skipped positional query parameter would
-shift every later parameter and bind NULL to the trailing placeholder, so this is rejected loudly.
+A boolean is accepted **wherever an integer is** — element scalars and arrays, query parameters,
+the group writers, and \`upsert_time_series_row\` — so it also reaches a REAL column through the
+usual int-for-REAL coercion. Reading is the asymmetric half: there are no boolean readers in Lua
+(unlike Julia/Dart/Python/JS), so a stored flag comes back as \`0\`/\`1\` from
+\`read_scalar_integers\`. Compare against 0 rather than truth-testing —
+\`read_scalar_integers(c, a)[i] == 1\` — because in Lua a \`nil\` from a NULL cell is *not* equal to
+0 and \`nil ~= 0\` evaluates to \`true\`.
+
+The one place a boolean is deliberately refused is \`db:update_relation\`, where the argument is a
+target label and only \`nil\` (or omitting it) may clear the relation.
+
+**Unsupported types throw.** Passing a function or a nested table where a scalar is expected raises
+an error rather than silently dropping the value. This applies to element attributes, time-series
+rows, and query parameters. A skipped positional query parameter would shift every later parameter
+and bind NULL to the trailing placeholder, so this is rejected loudly.
 
 Dates are plain strings in ISO 8601 format: \`YYYY-MM-DDTHH:MM:SS\`. (Lua keeps a string-based
 datetime surface — there are no DateTime wrapper helpers, unlike Julia/Dart/Python.) The time part
@@ -368,6 +380,13 @@ db:read_element_by_id(collection, id)            -- scalars + vectors + sets mer
 \`read_element_by_id\` merges every scalar, vector, and set for the element into a single table.
 Scalar attributes with no value come back as \`nil\`.
 
+**Group columns are returned densely, with NULL cells dropped.** \`read_vectors_by_id\` and
+\`read_sets_by_id\` read each column independently, and a column read skips its NULL cells — so two
+columns of the same group are **not** positionally aligned with each other whenever one is
+nullable (e.g. an \`ON DELETE SET NULL\` relation). Do not zip them into rows. There is no
+row-aligned group read in Lua; if you need per-row alignment across a nullable group, do that read
+in the host binding instead.
+
 ---
 
 ## Time series
@@ -681,7 +700,9 @@ and \`unit\` default to \`""\`; \`labels\`, \`dimensions\`, \`dimension_sizes\`,
 
 ## What Lua does *not* expose
 
-DateTime wrapper helpers (Lua uses ISO 8601 strings) and \`_by_id\` single-scalar variants (use the
-composite by-id readers or the bulk readers instead). Everything else the native binding exposes —
-CRUD, reads, time series, metadata, query, CSV, and the binary/expression subsystems — is
-documented above and callable.`;
+DateTime wrapper helpers (Lua uses ISO 8601 strings), boolean *reader* helpers (a stored flag reads
+back as \`0\`/\`1\` — writing a boolean is supported), \`_by_id\` single-scalar variants (use the
+composite by-id readers or the bulk readers instead), and the row-aligned whole-group readers the
+other bindings have (hence the null-dropping caveat under composite by-id reads). Everything else
+the native binding exposes — CRUD, reads, time series, metadata, query, CSV, and the
+binary/expression subsystems — is documented above and callable.`;

package/src/time-series.ts

@@ -17,7 +17,7 @@ import {
   readUint64Out,
   toCString,
 } from "./ffi-helpers.ts";
-import { updateGroupColumns } from "./group-columns.ts";
+import { type GroupColumns, updateGroupColumns } from "./group-columns.ts";
 import { getSymbols, type NativePointer } from "./loader.ts";
 import {
   type Allocation,
@@ -187,7 +187,7 @@ Database.prototype.updateTimeSeriesGroup = function (
   collection: string,
   group: string,
   id: number,
-  data: TimeSeriesData,
+  data: GroupColumns,
 ): void {
   updateGroupColumns(
     this._handle,
@@ -206,7 +206,7 @@ Database.prototype.updateTimeSeriesGroupByLabel = function (
   collection: string,
   group: string,
   label: string,
-  data: TimeSeriesData,
+  data: GroupColumns,
 ): void {
   updateGroupColumns(
     this._handle,
@@ -242,11 +242,12 @@ type UpsertRowFn = (
  */
 function upsertRowColumns(
   handle: NativePointer,
+  caller: string,
   upsert: UpsertRowFn,
   collection: string,
   group: string,
   key: number | string,
-  row: Record<string, number | bigint | string>,
+  row: Record<string, number | bigint | string | boolean>,
 ): void {
   const collBuf = toCString(collection);
   const grpBuf = toCString(group);
@@ -264,7 +265,11 @@ function upsertRowColumns(
   const dataPtrs: (Pointer | null)[] = [];
 
   for (let c = 0; c < columnCount; c++) {
-    const value = entries[c][1];
+    const [colName, raw] = entries[c];
+    // SQLite has no boolean type: a boolean is INTEGER 1/0. Normalized here rather than tested in
+    // the INTEGER condition below, because Number.isInteger(true) is false — a boolean otherwise
+    // reaches allocNativeFloat64 and lands in the column as FLOAT 1.0, silently the wrong type.
+    const value = typeof raw === "boolean" ? (raw ? 1 : 0) : raw;
     if (typeof value === "string") {
       typesDv.setInt32(c * 4, DATA_TYPE_STRING, true);
       const { table, keepalive: strPtrs } = allocNativeStringArray([value]);
@@ -275,11 +280,17 @@ function upsertRowColumns(
       const p = allocNativeInt64([value]);
       keepalive.push(p);
       dataPtrs.push(p.ptr);
-    } else {
+    } else if (typeof value === "number") {
       typesDv.setInt32(c * 4, DATA_TYPE_FLOAT, true);
-      const p = allocNativeFloat64([value as number]);
+      const p = allocNativeFloat64([value]);
       keepalive.push(p);
       dataPtrs.push(p.ptr);
+    } else {
+      // Mirrors updateGroupColumns: never let null/undefined/an object fall through to the FLOAT
+      // branch, where Number(null) is 0 and anything else is NaN — both written with no error.
+      throw new QuiverError(
+        `Cannot ${caller}: column '${colName}' has unsupported value type ${typeof value}`,
+      );
     }
   }
 
@@ -307,10 +318,11 @@ Database.prototype.upsertTimeSeriesRow = function (
   collection: string,
   group: string,
   id: number,
-  row: Record<string, number | bigint | string>,
+  row: Record<string, number | bigint | string | boolean>,
 ): void {
   upsertRowColumns(
     this._handle,
+    "upsertTimeSeriesRow",
     getSymbols().quiver_database_upsert_time_series_row,
     collection,
     group,
@@ -325,10 +337,11 @@ Database.prototype.upsertTimeSeriesRowByLabel = function (
   collection: string,
   group: string,
   label: string,
-  row: Record<string, number | bigint | string>,
+  row: Record<string, number | bigint | string | boolean>,
 ): void {
   upsertRowColumns(
     this._handle,
+    "upsertTimeSeriesRowByLabel",
     getSymbols().quiver_database_upsert_time_series_row_by_label,
     collection,
     group,