quiverdb 0.10.2 → 0.10.3

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quiverdb",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "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) ---

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,7 +51,7 @@ 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.      |
+| \`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
@@ -59,15 +60,21 @@ attributes, time-series rows, and query parameters. A skipped positional query p
 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 +83,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 +141,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 +227,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 +269,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.
 
 ---
 

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/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 = {