quiverdb 0.10.2 → 0.10.4

package/README.md

@@ -64,6 +64,7 @@ bun run example.ts
 
 - `Database.fromSchema(dbPath, schemaPath)` -- Create database from SQL schema file
 - `Database.fromMigrations(dbPath, migrationsPath)` -- Create database from migrations directory
+- `Database.validateMigrations(migrationsPath)` -- Validate a migrations directory (every `up.sql`, then every `down.sql`, ending with no table left behind) in-memory; throws on failure
 - `close()` -- Close the database connection
 
 ### Create / Delete
@@ -77,24 +78,30 @@ bun run example.ts
 ### Read (bulk)
 
 - `readScalarIntegers(collection, attribute)` -- Read all integer scalars
+- `readScalarBooleans(collection, attribute)` -- Read INTEGER-backed boolean scalars
 - `readScalarFloats(collection, attribute)` -- Read all float scalars
 - `readScalarStrings(collection, attribute)` -- Read all string scalars
 - `readVectorIntegers(collection, attribute)` -- Read all integer vectors
+- `readVectorBooleans(collection, attribute)` -- Read INTEGER-backed boolean vectors
 - `readVectorFloats(collection, attribute)` -- Read all float vectors
 - `readVectorStrings(collection, attribute)` -- Read all string vectors
 - `readSetIntegers(collection, attribute)` -- Read all integer sets
+- `readSetBooleans(collection, attribute)` -- Read INTEGER-backed boolean 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
+- `readScalarBooleanById(collection, attribute, id)` -- Read INTEGER-backed boolean 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
+- `readVectorBooleansById(collection, attribute, id)` -- Read INTEGER-backed boolean vector
 - `readVectorFloatsById(collection, attribute, id)` -- Read float vector
 - `readVectorStringsById(collection, attribute, id)` -- Read string vector
 - `readSetIntegersById(collection, attribute, id)` -- Read integer set
+- `readSetBooleansById(collection, attribute, id)` -- Read INTEGER-backed boolean set
 - `readSetFloatsById(collection, attribute, id)` -- Read float set
 - `readSetStringsById(collection, attribute, id)` -- Read string set
 
@@ -123,9 +130,11 @@ bun run example.ts
 
 - `queryString(sql, parameters?)` -- Query returning string or null
 - `queryInteger(sql, parameters?)` -- Query returning integer or null
+- `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 | string | null`.
+Parameters are passed as an array of `number | boolean | string | null` (a `boolean` binds as the
+INTEGER 1 or 0).
 
 ### Transaction
 

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.2",
+  "version": "0.10.4",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/boolean.ts

@@ -0,0 +1,20 @@
+export function integerToBoolean(value: number, collection?: string, attribute?: string): boolean;
+export function integerToBoolean(value: null, collection?: string, attribute?: string): null;
+export function integerToBoolean(
+  value: number | null,
+  collection?: string,
+  attribute?: string,
+): boolean | null;
+export function integerToBoolean(
+  value: number | null,
+  collection?: string,
+  attribute?: string,
+): boolean | null {
+  if (value === null) return null;
+  if (value === 0) return false;
+  if (value === 1) return true;
+  const source = collection ? ` in '${collection}.${attribute}'` : "";
+  // A RangeError, not a QuiverError: the message is crafted here, not read from
+  // quiver_get_last_error — these readers are a binding-only convenience.
+  throw new RangeError(`Cannot convert integer ${value} to boolean${source}: expected 0 or 1`);
+}

package/src/create.ts

@@ -35,6 +35,12 @@ function setElementArray(
     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) {
@@ -73,6 +79,11 @@ function setElementField(lib: Symbols, elemPtr: NativePointer, name: string, val
     return;
   }
 
+  if (typeof value === "boolean") {
+    check(lib.quiver_element_set_integer(elemPtr, nameBuf.buf, value ? 1n : 0n));
+    return;
+  }
+
   if (typeof value === "number") {
     if (Number.isInteger(value)) {
       check(lib.quiver_element_set_integer(elemPtr, nameBuf.buf, BigInt(value)));
@@ -175,6 +186,53 @@ Database.prototype.updateElementByLabel = function (
   }
 };
 
+/**
+ * Points one scalar foreign-key relation at the element labeled `targetLabel`; `null` clears it.
+ * The column is derived as `collectionTo.toLowerCase() + "_" + relationType`.
+ */
+Database.prototype.updateRelation = function (
+  this: Database,
+  collectionFrom: string,
+  collectionTo: string,
+  relationType: string,
+  id: number,
+  targetLabel: string | null,
+): void {
+  const lib = getSymbols();
+  check(
+    lib.quiver_database_update_relation(
+      this._handle,
+      toCString(collectionFrom).buf,
+      toCString(collectionTo).buf,
+      toCString(relationType).buf,
+      BigInt(id),
+      targetLabel === null ? null : toCString(targetLabel).buf,
+    ),
+  );
+};
+
+/** Label-addressed counterpart of updateRelation. */
+Database.prototype.updateRelationByLabel = function (
+  this: Database,
+  collectionFrom: string,
+  collectionTo: string,
+  relationType: string,
+  label: string,
+  targetLabel: string | null,
+): void {
+  const lib = getSymbols();
+  check(
+    lib.quiver_database_update_relation_by_label(
+      this._handle,
+      toCString(collectionFrom).buf,
+      toCString(collectionTo).buf,
+      toCString(relationType).buf,
+      toCString(label).buf,
+      targetLabel === null ? null : toCString(targetLabel).buf,
+    ),
+  );
+};
+
 Database.prototype.deleteElement = function (this: Database, collection: string, id: number): void {
   const lib = getSymbols();
   const collBuf = toCString(collection);

package/src/database.ts

@@ -64,6 +64,17 @@ export class Database {
     return new Database(readPtrOut(outDb));
   }
 
+  /**
+   * Applies every migration's up.sql in order, then every down.sql in reverse.
+   * Throws on failure, including a round trip that leaves any table behind.
+   */
+  static validateMigrations(migrationsPath: string): void {
+    const lib = getSymbols();
+    const migrPathBuf = toCString(migrationsPath);
+
+    check(lib.quiver_database_validate_migrations(migrPathBuf.buf));
+  }
+
   close(): void {
     if (this._closed) return;
     const lib = getSymbols();
@@ -89,9 +100,24 @@ export class Database {
   declare updateElementByLabel: (collection: string, label: string, data: ElementData) => void;
   declare deleteElement: (collection: string, id: number) => void;
   declare deleteElementByLabel: (collection: string, label: string) => void;
+  declare updateRelation: (
+    collectionFrom: string,
+    collectionTo: string,
+    relationType: string,
+    id: number,
+    targetLabel: string | null,
+  ) => void;
+  declare updateRelationByLabel: (
+    collectionFrom: string,
+    collectionTo: string,
+    relationType: string,
+    label: string,
+    targetLabel: string | null,
+  ) => void;
 
   // --- Reads (implemented in read.ts) ---
   declare readScalarIntegers: (collection: string, attribute: string) => (number | null)[];
+  declare readScalarBooleans: (collection: string, attribute: string) => (boolean | null)[];
   declare readScalarFloats: (collection: string, attribute: string) => (number | null)[];
   declare readScalarStrings: (collection: string, attribute: string) => (string | null)[];
   declare readScalarIntegerById: (
@@ -99,6 +125,11 @@ export class Database {
     attribute: string,
     id: number,
   ) => number | null;
+  declare readScalarBooleanById: (
+    collection: string,
+    attribute: string,
+    id: number,
+  ) => boolean | null;
   declare readScalarFloatById: (collection: string, attribute: string, id: number) => number | null;
   declare readScalarStringById: (
     collection: string,
@@ -108,21 +139,26 @@ export class Database {
   declare readElementIds: (collection: string) => number[];
   declare numberOfElements: (collection: string) => number;
   declare readVectorIntegers: (collection: string, attribute: string) => number[][];
+  declare readVectorBooleans: (collection: string, attribute: string) => boolean[][];
   declare readVectorFloats: (collection: string, attribute: string) => number[][];
   declare readVectorStrings: (collection: string, attribute: string) => string[][];
   declare readVectorIntegersById: (collection: string, attribute: string, id: number) => number[];
+  declare readVectorBooleansById: (collection: string, attribute: string, id: number) => boolean[];
   declare readVectorFloatsById: (collection: string, attribute: string, id: number) => number[];
   declare readVectorStringsById: (collection: string, attribute: string, id: number) => string[];
   declare readSetIntegers: (collection: string, attribute: string) => number[][];
+  declare readSetBooleans: (collection: string, attribute: string) => boolean[][];
   declare readSetFloats: (collection: string, attribute: string) => number[][];
   declare readSetStrings: (collection: string, attribute: string) => string[][];
   declare readSetIntegersById: (collection: string, attribute: string, id: number) => number[];
+  declare readSetBooleansById: (collection: string, attribute: string, id: number) => boolean[];
   declare readSetFloatsById: (collection: string, attribute: string, id: number) => number[];
   declare readSetStringsById: (collection: string, attribute: string, id: number) => string[];
 
   // --- Queries (implemented in query.ts) ---
   declare queryString: (sql: string, parameters?: QueryParam[]) => string | null;
   declare queryInteger: (sql: string, parameters?: QueryParam[]) => number | null;
+  declare queryBoolean: (sql: string, parameters?: QueryParam[]) => boolean | null;
   declare queryFloat: (sql: string, parameters?: QueryParam[]) => number | null;
 
   // --- Transactions (implemented in transaction.ts) ---
@@ -156,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,
@@ -192,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/loader.ts

@@ -35,6 +35,7 @@ const lifecycleSymbols = {
   // struct in JS.
   quiver_database_from_schema: { args: [BUF, BUF, BUF, P], returns: I32 },
   quiver_database_from_migrations: { args: [BUF, BUF, BUF, P], returns: I32 },
+  quiver_database_validate_migrations: { args: [BUF], returns: I32 },
   quiver_database_open: { args: [BUF, BUF, P], returns: I32 },
   quiver_database_close: { args: [P], returns: I32 },
   quiver_database_is_healthy: { args: [P, P], returns: I32 },
@@ -61,6 +62,8 @@ const crudSymbols = {
   quiver_database_update_element_by_label: { args: [P, BUF, BUF, P], returns: I32 },
   quiver_database_delete_element: { args: [P, BUF, I64], returns: I32 },
   quiver_database_delete_element_by_label: { args: [P, BUF, BUF], returns: I32 },
+  quiver_database_update_relation: { args: [P, BUF, BUF, BUF, I64, BUF], returns: I32 },
+  quiver_database_update_relation_by_label: { args: [P, BUF, BUF, BUF, BUF, BUF], returns: I32 },
 } as const;
 
 const readSymbols = {

package/src/lua-api.ts

@@ -10,8 +10,9 @@
 // and whether the prose is semantically true.
 //
 // NOTE: the binary/expression subsystems are bound in the native binding and documented below.
-// File-touching operations (db:open_file, db:bin_to_csv, db:csv_to_bin, expr:save) are sandboxed
-// to the database file's directory; the pure-metadata builders stay under the quiver.* global.
+// File-touching operations (db:open_file, db:bin_to_csv, db:csv_to_bin, db:validate_migrations,
+// expr:save) are sandboxed to the database file's directory; the pure-metadata builders stay under
+// the quiver.* global.
 //
 // FORMAT CONVENTION: every db: method appears at least once as the literal token
 // `db:<snake_case_name>`, and every quiver.* function as `quiver.<name>`, so coverage is greppable
@@ -50,24 +51,42 @@ 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).  |
-| \`nil\`              | NULL         | In query params, file paths, and ts rows.      |
+| 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.)
+datetime surface — there are no DateTime wrapper helpers, unlike Julia/Dart/Python.) The time part
+is optional, so \`"2024-01-15"\` is also valid, and a space may replace the \`T\`. Every field is
+fixed-width and zero-padded. Anything shorter or malformed — \`"2005"\`, \`"2005-01"\`,
+\`"2024-02-31"\`, \`"2024-1-5"\`, \`"2024-01-15T10:30"\` — is **rejected when you write it**, not
+silently stored. The value is stored exactly as written; a date-only value is not padded to
+midnight.
 
 ---
 
 ## Critical rules
 
 - **Type coercion.** An integer is accepted for a REAL column (coerced to real on insert); a float
-  is rejected for an INTEGER column. Other type mismatches raise a validation error and roll the
-  whole script back.
+  is rejected for an INTEGER column. A string bound to a \`date_*\` column must parse as ISO 8601
+  (\`YYYY-MM-DD\`, optionally \`THH:MM:SS\` or \` HH:MM:SS\`). Other type mismatches raise a
+  validation error and roll the whole script back.
 - **Errors abort the script.** Any error thrown by a \`db:\` call stops the script and surfaces as
   \`Failed to run Lua script: <message>\`. Validation failures roll back whatever the current
   transaction covered.
@@ -76,16 +95,16 @@ datetime surface — there are no DateTime wrapper helpers, unlike Julia/Dart/Py
   and \`dofile\`/\`loadfile\` are removed (string-form \`load\` stays available). Integer division is
   the Lua 5.4 \`//\` operator — a language operator, unrelated to \`math\`.
 - **Filesystem sandbox.** Every file-touching operation (\`db:export_csv\`, \`db:import_csv\`,
-  \`db:open_file\`, \`db:bin_to_csv\`, \`db:csv_to_bin\`, \`expr:save\`) resolves relative paths against
-  the directory containing the database file and rejects anything outside it (subdirectories are
-  fine; \`..\` escapes and outside absolute paths throw \`Cannot <op>: path '...' escapes the
+  \`db:open_file\`, \`db:bin_to_csv\`, \`db:csv_to_bin\`, \`db:validate_migrations\`, \`expr:save\`) resolves
+  relative paths against the directory containing the database file and rejects anything outside it
+  (subdirectories are fine; \`..\` escapes and outside absolute paths throw \`Cannot <op>: path '...' escapes the
   database directory ...\`). On an in-memory database these operations throw
   \`Cannot <op>: database is in-memory, file operations are unavailable\`.
 - **Output.** A script can \`return\` one value and the host receives it as JSON — prefer this over
   \`print()\` when you need structured data back (\`print()\` still works and is captured). Only the
   **first** returned value is encoded. Arrays are 1-indexed (iterate with \`ipairs\`); reading a NULL
   yields \`nil\`, writing \`nil\` stores NULL where NULL is accepted (query params, ts rows, file
-  columns — but NOT element scalar attributes; see CRUD).
+  columns, relation targets — but NOT element scalar attributes; see CRUD).
 
   \`\`\`lua
   return { ids = db:read_element_ids("Collection"), total = 3 }
@@ -134,10 +153,15 @@ db:describe()                      -- string: whole-DB text report (returns it,
 db:describe_collection(collection) -- string: one collection's structure (text report)
 db:summarize_collection(collection)-- string: per-scalar null/non-null counts, low-cardinality
                                    --         integer value distributions, per-group sizes
+db:validate_migrations(path)       -- validate a migrations dir (up then down) in-memory; no return
 \`\`\`
 
 All three \`describe*\`/\`summarize*\` methods **return** a string — \`print()\` it to see it.
 
+\`db:validate_migrations(path)\` applies every \`up.sql\` in version order, then every \`down.sql\` in
+reverse, against a throwaway in-memory database — nothing in \`db\` itself is touched. The round trip
+must end with an empty database; leftover tables are named in the error.
+
 ---
 
 ## Transactions
@@ -215,6 +239,9 @@ db:update_element(collection, id, element_table)
 db:update_element_by_label(collection, label, element_table)  -- same update, addressed by label
 db:delete_element(collection, id)
 db:delete_element_by_label(collection, label)             -- same delete, addressed by label
+
+db:update_relation(collection_from, collection_to, relation_type, id, target_label)
+db:update_relation_by_label(collection_from, collection_to, relation_type, label, target_label)
 \`\`\`
 
 The element table holds scalar attributes as \`key = value\`, and vector/set attributes as
@@ -254,7 +281,18 @@ Notes:
   **throws** (\`...must have at least one scalar attribute\` on create, \`...at least one attribute
   to update\` on update). 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
-  \`upsert_time_series_row\` and \`update_time_series_files\`.)
+  \`upsert_time_series_row\`, \`update_time_series_files\` and \`update_relation\`.)
+- **\`update_relation\` points one scalar foreign-key relation at another element**, named by the
+  target's label. The column is derived from the naming convention —
+  \`lowercase(collection_to) .. "_" .. relation_type\`, so
+  \`db:update_relation("Child", "Parent", "id", id, "Parent A")\` writes \`Child.parent_id\`. A
+  \`nil\` or omitted \`target_label\` clears the relation; anything that is not a string throws
+  (\`target_label has unsupported Lua type\`). The derived column must exist and be a
+  foreign key to \`collection_to\`, otherwise \`Cannot update_relation: ...\`. The write delegates
+  to \`update_element\`, so a missing id reports that method's error;
+  \`update_relation_by_label\` takes a label in place of the id, with
+  \`update_element_by_label\`'s resolution and miss semantics. A relation living in a vector, set
+  or time-series group is a list of targets — use that group's writer instead.
 
 ---
 
@@ -342,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
@@ -655,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/query.ts

@@ -1,4 +1,5 @@
 import { ptr } from "bun:ffi";
+import { integerToBoolean } from "./boolean.ts";
 import { Database } from "./database.ts";
 import { check, QuiverError } from "./errors.ts";
 import {
@@ -38,6 +39,11 @@ function marshalParams(parameters: QueryParam[]): {
     if (p === null) {
       typesDv.setInt32(i * 4, DATA_TYPE_NULL, true);
       valuesDv.setBigInt64(i * 8, 0n, true);
+    } else if (typeof p === "boolean") {
+      typesDv.setInt32(i * 4, DATA_TYPE_INTEGER, true);
+      const native = allocNativeInt64([p ? 1 : 0]);
+      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);
@@ -130,6 +136,14 @@ Database.prototype.queryInteger = function (
   return Number(new DataView(outValue.buffer).getBigInt64(0, true));
 };
 
+Database.prototype.queryBoolean = function (
+  this: Database,
+  sql: string,
+  parameters?: QueryParam[],
+): boolean | null {
+  return integerToBoolean(this.queryInteger(sql, parameters));
+};
+
 Database.prototype.queryFloat = function (
   this: Database,
   sql: string,

package/src/read.ts

@@ -1,4 +1,5 @@
 import { CString, type Pointer, toArrayBuffer } from "bun:ffi";
+import { integerToBoolean } from "./boolean.ts";
 import { Database } from "./database.ts";
 import { check } from "./errors.ts";
 import {
@@ -52,6 +53,16 @@ Database.prototype.readScalarIntegers = function (
   return result;
 };
 
+Database.prototype.readScalarBooleans = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+): (boolean | null)[] {
+  return this.readScalarIntegers(collection, attribute).map((value) =>
+    integerToBoolean(value, collection, attribute),
+  );
+};
+
 Database.prototype.readScalarFloats = function (
   this: Database,
   collection: string,
@@ -143,6 +154,19 @@ Database.prototype.readScalarIntegerById = function (
   return Number(new DataView(outValBuf.buffer).getBigInt64(0, true));
 };
 
+Database.prototype.readScalarBooleanById = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+  id: number,
+): boolean | null {
+  return integerToBoolean(
+    this.readScalarIntegerById(collection, attribute, id),
+    collection,
+    attribute,
+  );
+};
+
 Database.prototype.readScalarFloatById = function (
   this: Database,
   collection: string,
@@ -342,6 +366,19 @@ Database.prototype.readVectorIntegers = function (
     attribute,
   );
 };
+/**
+ * NULL cells are dropped and only elements that own rows are returned, so the result is not
+ * positionally aligned with `readElementIds` (unlike `readScalarBooleans`).
+ */
+Database.prototype.readVectorBooleans = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+): boolean[][] {
+  return this.readVectorIntegers(collection, attribute).map((values) =>
+    values.map((value) => integerToBoolean(value, collection, attribute)),
+  );
+};
 Database.prototype.readVectorFloats = function (
   this: Database,
   collection: string,
@@ -381,6 +418,16 @@ Database.prototype.readSetIntegers = function (
     attribute,
   );
 };
+/** Same alignment caveat as `readVectorBooleans`: NULL cells dropped, only ids that own rows. */
+Database.prototype.readSetBooleans = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+): boolean[][] {
+  return this.readSetIntegers(collection, attribute).map((values) =>
+    values.map((value) => integerToBoolean(value, collection, attribute)),
+  );
+};
 Database.prototype.readSetFloats = function (
   this: Database,
   collection: string,
@@ -515,6 +562,16 @@ Database.prototype.readVectorIntegersById = function (
     id,
   );
 };
+Database.prototype.readVectorBooleansById = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+  id: number,
+): boolean[] {
+  return this.readVectorIntegersById(collection, attribute, id).map((value) =>
+    integerToBoolean(value, collection, attribute),
+  );
+};
 Database.prototype.readVectorFloatsById = function (
   this: Database,
   collection: string,
@@ -560,6 +617,16 @@ Database.prototype.readSetIntegersById = function (
     id,
   );
 };
+Database.prototype.readSetBooleansById = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+  id: number,
+): boolean[] {
+  return this.readSetIntegersById(collection, attribute, id).map((value) =>
+    integerToBoolean(value, collection, attribute),
+  );
+};
 Database.prototype.readSetFloatsById = function (
   this: Database,
   collection: string,

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,

package/src/types.ts

@@ -21,11 +21,12 @@ export type DatabaseOptions = {
   consoleLevel?: number;
 };
 
-export type ScalarValue = number | bigint | string | null;
-export type ArrayValue = number[] | bigint[] | string[];
+/** A `boolean` is stored as the INTEGER 1 or 0 (see `readScalarBooleans` for the read side). */
+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 | string | null;
+export type QueryParam = number | boolean | string | null;
 
 /** Native memory allocation result. Callers MUST hold `buf` in scope to prevent GC. */
 export type Allocation = {