@evolu/sqlite-wasm 2.2.4 → 3.53.4-build1

package/src/Memory.test.ts

@@ -0,0 +1,319 @@
+import { test } from "node:test";
+
+import {
+  assertEqual,
+  assertErr,
+  assertFalse,
+  assertOk,
+  assertTrue,
+} from "@evolu/common";
+import type { SqliteCExports } from "./CApi.ts";
+import {
+  allocCString,
+  allocWasm,
+  copyWasmBytes,
+  createSqliteScratch,
+  isInt32,
+  isSqliteInt64,
+  maxInt32,
+  maxSqliteInt64,
+  minSqliteInt64,
+  readCString,
+  readUtf8,
+  writeUtf8,
+  writeWasmBytes,
+} from "./Memory.ts";
+import type { CStringPtr, SqliteOwnedPtr, WasmPtr } from "./Pointer.ts";
+import type { SqliteWasmDep } from "./Wasm.ts";
+
+/**
+ * A fake {@link SqliteWasmDep} over a real `WebAssembly.Memory`, whose
+ * `sqlite3_malloc` returns NULL for 0 bytes, as SQLite's does, and for the
+ * lengths `mallocFails` accepts, and otherwise allocates 8-byte aligned memory
+ * after growing the memory by a page, so that every allocation detaches the
+ * previous heap views.
+ */
+const setupFakeSqliteWasm = ({
+  mallocFails = () => false,
+}: { mallocFails?: (byteLength: number) => boolean } = {}) => {
+  const memory = new WebAssembly.Memory({ initial: 1, maximum: 1000 });
+  const mallocCalls: Array<number> = [];
+  const freed: Array<number> = [];
+  let end = 8;
+
+  const sqlite3_malloc = (byteLength: number): SqliteOwnedPtr | 0 => {
+    mallocCalls.push(byteLength);
+    if (mallocFails(byteLength) || byteLength <= 0) return 0;
+    const ptr = Math.ceil(end / 8) * 8;
+    end = ptr + byteLength;
+    memory.grow(
+      Math.max(1, Math.ceil((end - memory.buffer.byteLength) / 65536)),
+    );
+    return ptr as SqliteOwnedPtr;
+  };
+  const sqlite3_free = (ptr: SqliteOwnedPtr | 0): void => {
+    freed.push(ptr);
+  };
+
+  const deps: SqliteWasmDep = {
+    sqliteWasm: {
+      exports: { sqlite3_malloc, sqlite3_free } as unknown as SqliteCExports,
+      functionTable: new WebAssembly.Table({ initial: 0, element: "anyfunc" }),
+      getHeapU8: () => new Uint8Array(memory.buffer),
+      getHeapDataView: () => new DataView(memory.buffer),
+      call: (fn) => fn(),
+      isBroken: () => false,
+    },
+  };
+  return { deps, mallocCalls, freed };
+};
+
+const utf8 = (value: string): Uint8Array<ArrayBuffer> =>
+  new TextEncoder().encode(value);
+
+test("maxInt32 is the largest C int", () => {
+  assertEqual(maxInt32, 2 ** 31 - 1);
+});
+
+test("isInt32 accepts exactly the integers a C int holds", () => {
+  for (const value of [0, 1, -1, maxInt32, -maxInt32 - 1, -0])
+    assertTrue(isInt32(value));
+  for (const value of [
+    maxInt32 + 1,
+    -maxInt32 - 2,
+    0.5,
+    2 ** 53,
+    Number.NaN,
+    Number.POSITIVE_INFINITY,
+    Number.NEGATIVE_INFINITY,
+  ])
+    assertFalse(isInt32(value));
+});
+
+test("isSqliteInt64 accepts exactly the integers from minSqliteInt64 to maxSqliteInt64", () => {
+  assertEqual(maxSqliteInt64, 2n ** 63n - 1n);
+  assertEqual(minSqliteInt64, -(2n ** 63n));
+  for (const value of [0n, -1n, maxSqliteInt64, minSqliteInt64])
+    assertTrue(isSqliteInt64(value));
+  for (const value of [maxSqliteInt64 + 1n, minSqliteInt64 - 1n, 2n ** 64n])
+    assertFalse(isSqliteInt64(value));
+});
+
+test("allocWasm allocates at least one byte, so a zero-length value keeps a non-NULL address", () => {
+  const { deps, mallocCalls } = setupFakeSqliteWasm();
+
+  const result = allocWasm(deps)(0);
+
+  assertOk(result);
+  assertTrue(result.value !== 0);
+  assertEqual(mallocCalls, [1]);
+});
+
+test("allocWasm fails with SqliteNoMem when sqlite3_malloc returns NULL", () => {
+  const { deps } = setupFakeSqliteWasm({ mallocFails: () => true });
+
+  assertErr(allocWasm(deps)(10), { type: "SqliteNoMem", byteLength: 10 });
+});
+
+test("allocWasm fails without calling sqlite3_malloc above maxInt32, which a C int would wrap", () => {
+  const { deps, mallocCalls } = setupFakeSqliteWasm();
+
+  assertErr(allocWasm(deps)(maxInt32 + 1), {
+    type: "SqliteNoMem",
+    byteLength: maxInt32 + 1,
+  });
+  assertEqual(mallocCalls, []);
+});
+
+test("allocWasm calls sqlite3_malloc for exactly maxInt32", () => {
+  const { deps, mallocCalls } = setupFakeSqliteWasm({
+    mallocFails: (byteLength) => byteLength === maxInt32,
+  });
+
+  assertErr(allocWasm(deps)(maxInt32), {
+    type: "SqliteNoMem",
+    byteLength: maxInt32,
+  });
+  assertEqual(mallocCalls, [maxInt32]);
+});
+
+test("allocCString copies a string into new memory as NUL-terminated UTF-8", () => {
+  const { deps, mallocCalls } = setupFakeSqliteWasm();
+  const value = "Žluťoučký kůň 🐴";
+
+  const result = allocCString(deps)(value);
+
+  assertOk(result);
+  const bytes = utf8(value);
+  assertEqual(mallocCalls, [bytes.length + 1]);
+  assertEqual(
+    deps.sqliteWasm
+      .getHeapU8()
+      .slice(result.value, result.value + bytes.length + 1),
+    Uint8Array.of(...bytes, 0),
+  );
+});
+
+test("allocCString fails with SqliteNoMem for the encoded length and its NUL", () => {
+  const { deps } = setupFakeSqliteWasm({ mallocFails: () => true });
+
+  assertErr(allocCString(deps)("kůň"), { type: "SqliteNoMem", byteLength: 6 });
+});
+
+test("writeUtf8 encodes into existing memory without a NUL and returns the byte length, cutting at a character boundary", () => {
+  const { deps } = setupFakeSqliteWasm();
+  const ptr = 64 as WasmPtr;
+  const heap = deps.sqliteWasm.getHeapU8();
+  heap.fill(0xff, ptr, ptr + 16);
+
+  assertEqual(writeUtf8(deps)("kůň🐴", ptr, 16), 9);
+  assertEqual(heap.slice(ptr, ptr + 10), Uint8Array.of(...utf8("kůň🐴"), 0xff));
+
+  heap.fill(0xff, ptr, ptr + 16);
+  assertEqual(writeUtf8(deps)("kůň🐴", ptr, 7), 5);
+  assertEqual(
+    heap.slice(ptr, ptr + 8),
+    Uint8Array.of(...utf8("kůň"), 0xff, 0xff, 0xff),
+  );
+});
+
+const byteOrderMark = Uint8Array.of(0xef, 0xbb, 0xbf);
+
+test("readCString decodes up to the NUL, keeping a leading byte order mark", () => {
+  const { deps } = setupFakeSqliteWasm();
+  const ptr = 64 as CStringPtr;
+  deps.sqliteWasm
+    .getHeapU8()
+    .set([...byteOrderMark, ...utf8("kůň"), 0, ...utf8("after")], ptr);
+
+  assertEqual(readCString(deps)(ptr), "\uFEFFkůň");
+});
+
+test("readUtf8 decodes a byte length, keeping a leading byte order mark and embedded NUL characters", () => {
+  const { deps } = setupFakeSqliteWasm();
+  const ptr = 64 as WasmPtr;
+  const bytes = Uint8Array.of(...byteOrderMark, ...utf8("a"), 0, ...utf8("ž"));
+  deps.sqliteWasm.getHeapU8().set([...bytes, ...utf8("after")], ptr);
+
+  assertEqual(readUtf8(deps)(ptr, bytes.length), "\uFEFFa\0ž");
+});
+
+test("copyWasmBytes copies bytes into their own ArrayBuffer", () => {
+  const { deps } = setupFakeSqliteWasm();
+  const ptr = 64 as WasmPtr;
+  const heap = deps.sqliteWasm.getHeapU8();
+  heap.set([1, 2, 3, 4], ptr);
+
+  const copy = copyWasmBytes(deps)(ptr, 3);
+  heap.fill(0, ptr, ptr + 4);
+
+  assertEqual(copy, Uint8Array.of(1, 2, 3));
+  assertEqual(copy.buffer.byteLength, 3);
+});
+
+test("writeWasmBytes copies bytes into wasm memory", () => {
+  const { deps } = setupFakeSqliteWasm();
+  const ptr = 64 as WasmPtr;
+
+  writeWasmBytes(deps)(ptr, Uint8Array.of(1, 2, 3));
+
+  assertEqual(
+    deps.sqliteWasm.getHeapU8().slice(ptr - 1, ptr + 4),
+    Uint8Array.of(0, 1, 2, 3, 0),
+  );
+});
+
+test("createSqliteScratch allocates 16 bytes, 8-byte aligned, for output parameters", () => {
+  const { deps, mallocCalls } = setupFakeSqliteWasm();
+
+  const result = createSqliteScratch(deps);
+
+  assertOk(result);
+  assertEqual(result.value.out % 8, 0);
+  assertEqual(mallocCalls, [16]);
+});
+
+test("SqliteScratch.reserve reuses its memory and doubles it when a value does not fit", () => {
+  const { deps, mallocCalls, freed } = setupFakeSqliteWasm();
+  const result = createSqliteScratch(deps);
+  assertOk(result);
+  const scratch = result.value;
+
+  const first = scratch.reserve(100);
+  assertOk(first);
+  assertEqual(scratch.reserve(100), first);
+  assertEqual(scratch.reserve(1), first);
+
+  const second = scratch.reserve(150);
+  assertOk(second);
+  assertEqual(freed, [first.value]);
+  assertEqual(scratch.reserve(200), second);
+
+  const third = scratch.reserve(1000);
+  assertOk(third);
+  assertEqual(freed, [first.value, second.value]);
+  assertEqual(mallocCalls, [16, 100, 200, 1000]);
+});
+
+test("SqliteScratch.reserve fails with SqliteNoMem and recovers once memory is available", () => {
+  let outOfMemory = false;
+  const { deps, freed } = setupFakeSqliteWasm({
+    mallocFails: () => outOfMemory,
+  });
+  const result = createSqliteScratch(deps);
+  assertOk(result);
+  const scratch = result.value;
+  assertOk(scratch.reserve(100));
+
+  outOfMemory = true;
+  assertErr(scratch.reserve(1000), { type: "SqliteNoMem", byteLength: 1000 });
+
+  outOfMemory = false;
+  const recovered = scratch.reserve(100);
+  assertOk(recovered);
+  assertFalse(freed.includes(recovered.value));
+});
+
+test("SqliteScratch.reserve falls back to the requested length when twice its capacity is unavailable, and a failure leaves it empty", () => {
+  const { deps, mallocCalls } = setupFakeSqliteWasm({
+    mallocFails: (byteLength) => byteLength > 1000,
+  });
+  const result = createSqliteScratch(deps);
+  assertOk(result);
+  const scratch = result.value;
+  assertOk(scratch.reserve(600));
+
+  mallocCalls.length = 0;
+  assertOk(scratch.reserve(700));
+  assertEqual(mallocCalls, [1200, 700]);
+
+  mallocCalls.length = 0;
+  assertErr(scratch.reserve(1001), { type: "SqliteNoMem", byteLength: 1001 });
+  assertEqual(mallocCalls, [1400, 1001]);
+
+  mallocCalls.length = 0;
+  // Not twice a capacity it no longer has.
+  assertOk(scratch.reserve(16));
+  assertEqual(mallocCalls, [16]);
+});
+
+test("disposing a SqliteScratch frees its memory", () => {
+  const { deps, freed } = setupFakeSqliteWasm();
+  const result = createSqliteScratch(deps);
+  assertOk(result);
+  const reserved = result.value.reserve(100);
+  assertOk(reserved);
+
+  result.value[Symbol.dispose]();
+
+  assertEqual(
+    freed.toSorted((a, b) => a - b),
+    [result.value.out, reserved.value].toSorted((a, b) => a - b),
+  );
+});
+
+test("createSqliteScratch fails with SqliteNoMem without memory", () => {
+  const { deps } = setupFakeSqliteWasm({ mallocFails: () => true });
+
+  assertErr(createSqliteScratch(deps), { type: "SqliteNoMem", byteLength: 16 });
+});

package/src/Memory.ts

@@ -0,0 +1,237 @@
+/**
+ * Standalone helpers for wasm memory: allocation, UTF-8, bytes, scratch memory,
+ * and integer ranges.
+ *
+ * Like the CApi functions, each helper that touches the instance takes
+ * {@link SqliteWasmDep} and returns the operation, so a database binds it once.
+ *
+ * Rules the helpers follow and their callers must too:
+ *
+ * - Allocate at least one byte. `sqlite3_malloc(0)` returns NULL, and binding a
+ *   NULL address binds SQL NULL, so an empty string or blob would silently
+ *   become NULL.
+ * - Take the heap view after allocating. Growing memory detaches the previous
+ *   `ArrayBuffer`, and writing to a detached view does nothing.
+ * - Decode by byte length with a decoder that keeps a leading byte order mark, so
+ *   text round-trips exactly, including embedded NUL characters. The default
+ *   `TextDecoder` strips it.
+ *
+ * @module
+ */
+
+import { disposable, err, ok, type Result, type Typed } from "@evolu/common";
+import type {
+  CStringPtr,
+  SqliteOwnedCStringPtr,
+  SqliteOwnedPtr,
+  WasmPtr,
+} from "./Pointer.ts";
+import type { SqliteWasmDep } from "./Wasm.ts";
+
+const utf8Encoder = /*#__PURE__*/ new TextEncoder();
+
+// Keeps a leading byte order mark, which the default decoder strips.
+const utf8Decoder = /*#__PURE__*/ new TextDecoder("utf-8", { ignoreBOM: true });
+
+/** `sqlite3_malloc` returned NULL. */
+export interface SqliteNoMemError extends Typed<"SqliteNoMem"> {
+  readonly byteLength: number;
+}
+
+/**
+ * Allocates at least one byte with `sqlite3_malloc`, so a zero-length value
+ * keeps a non-NULL address.
+ *
+ * A request above {@link maxInt32} fails without calling `sqlite3_malloc`, which
+ * takes a C int and would wrap it.
+ */
+export const allocWasm =
+  (deps: SqliteWasmDep) =>
+  (byteLength: number): Result<SqliteOwnedPtr, SqliteNoMemError> => {
+    const ptr =
+      byteLength > maxInt32
+        ? 0
+        : deps.sqliteWasm.exports.sqlite3_malloc(Math.max(1, byteLength));
+    return ptr === 0 ? err({ type: "SqliteNoMem", byteLength }) : ok(ptr);
+  };
+
+/**
+ * Copies a string into new memory as a NUL-terminated UTF-8 C string, which the
+ * caller frees with `sqlite3_free`.
+ *
+ * UTF-8 cannot encode a lone surrogate, which becomes U+FFFD, as with
+ * `TextEncoder`, so a caller that needs the exact text checks
+ * `String.prototype.isWellFormed` first.
+ */
+export const allocCString =
+  (deps: SqliteWasmDep) =>
+  (value: string): Result<SqliteOwnedCStringPtr, SqliteNoMemError> => {
+    const bytes = utf8Encoder.encode(value);
+    const allocated = allocWasm(deps)(bytes.length + 1);
+    if (!allocated.ok) return allocated;
+    const ptr = allocated.value as SqliteOwnedCStringPtr;
+    const heap = deps.sqliteWasm.getHeapU8();
+    heap.set(bytes, ptr);
+    heap[ptr + bytes.length] = 0;
+    return ok(ptr);
+  };
+
+/**
+ * Encodes a string as UTF-8 into existing memory and returns the byte length,
+ * without a NUL terminator.
+ *
+ * The memory needs up to three bytes per UTF-16 code unit; text that does not
+ * fit is cut at a character boundary, so reserve `value.length * 3` bytes. A
+ * lone surrogate becomes U+FFFD, as in {@link allocCString}.
+ */
+export const writeUtf8 =
+  (deps: SqliteWasmDep) =>
+  (value: string, ptr: WasmPtr, capacity: number): number =>
+    utf8Encoder.encodeInto(
+      value,
+      deps.sqliteWasm.getHeapU8().subarray(ptr, ptr + capacity),
+    ).written;
+
+/** Decodes a NUL-terminated C string, such as an error message or a column name. */
+export const readCString =
+  (deps: SqliteWasmDep) =>
+  (ptr: CStringPtr): string => {
+    const heap = deps.sqliteWasm.getHeapU8();
+    return utf8Decoder.decode(heap.subarray(ptr, heap.indexOf(0, ptr)));
+  };
+
+/**
+ * Decodes UTF-8 of a known byte length, such as a text column, keeping a
+ * leading byte order mark and embedded NUL characters.
+ */
+export const readUtf8 =
+  (deps: SqliteWasmDep) =>
+  (ptr: WasmPtr, byteLength: number): string =>
+    utf8Decoder.decode(
+      deps.sqliteWasm.getHeapU8().subarray(ptr, ptr + byteLength),
+    );
+
+/**
+ * Copies bytes out of wasm memory into a new `ArrayBuffer`, so the result can
+ * be transferred to another worker.
+ */
+export const copyWasmBytes =
+  (deps: SqliteWasmDep) =>
+  (ptr: WasmPtr, byteLength: number): Uint8Array<ArrayBuffer> =>
+    deps.sqliteWasm.getHeapU8().slice(ptr, ptr + byteLength);
+
+/** Copies bytes into wasm memory. */
+export const writeWasmBytes =
+  (deps: SqliteWasmDep) =>
+  (ptr: WasmPtr, bytes: Uint8Array): void => {
+    deps.sqliteWasm.getHeapU8().set(bytes, ptr);
+  };
+
+/**
+ * Reusable memory for output parameters and bind values, allocated once per
+ * database instead of once per call.
+ *
+ * A callback inside a call, such as a collation-needed callback or a trace
+ * callback, can run another call on the same database, which reuses this
+ * memory. The outer call is unaffected, because SQLite copies a value bound
+ * with SQLITE_TRANSIENT at once and writes an output parameter after the
+ * callbacks of the call. What SQLite reads or writes before a callback and the
+ * caller uses after it needs memory of its own: SQL, which SQLite parses in
+ * place and copies only after the parse, and the size `sqlite3_serialize`
+ * writes before it finalizes its query.
+ */
+export interface SqliteScratch extends Disposable {
+  /**
+   * Sixteen bytes, 8-byte aligned, for output parameters such as `ppDb`,
+   * `ppStmt` and `pzTail`.
+   */
+  readonly out: WasmPtr;
+
+  /**
+   * Returns memory of at least the given length, growing it when needed. The
+   * previous contents are not kept, and the address is valid until the next
+   * call. Growth doubles the capacity, so reallocations stay rare as values
+   * grow, or, when that much memory is not available, allocates the length
+   * alone. A failure leaves the scratch empty, so later calls are unaffected.
+   *
+   * Binding text or a blob from here with SQLITE_TRANSIENT is faster than
+   * allocating per value: SQLite copies into a buffer it reuses.
+   */
+  readonly reserve: (byteLength: number) => Result<WasmPtr, SqliteNoMemError>;
+}
+
+/** Creates a {@link SqliteScratch}. */
+export const createSqliteScratch = (
+  deps: SqliteWasmDep,
+): Result<SqliteScratch, SqliteNoMemError> => {
+  const out = allocWasm(deps)(16);
+  if (!out.ok) return out;
+
+  let buffer: SqliteOwnedPtr | null = null;
+  let capacity = 0;
+
+  using disposer = new DisposableStack();
+  disposer.defer(() => {
+    deps.sqliteWasm.exports.sqlite3_free(out.value);
+  });
+  disposer.defer(() => {
+    if (buffer != null) deps.sqliteWasm.exports.sqlite3_free(buffer);
+  });
+
+  return ok(
+    disposable<SqliteScratch>(
+      {
+        out: out.value,
+        reserve: (byteLength) => {
+          if (buffer != null) {
+            if (byteLength <= capacity) return ok(buffer);
+            // The contents need not be kept, so the old memory goes first.
+            deps.sqliteWasm.exports.sqlite3_free(buffer);
+            buffer = null;
+          }
+          // Twice the capacity keeps reallocations rare, but when it is not
+          // available, the requested length alone may still be.
+          let newCapacity = Math.max(byteLength, capacity * 2);
+          let allocated = allocWasm(deps)(newCapacity);
+          if (!allocated.ok && newCapacity > byteLength) {
+            newCapacity = byteLength;
+            allocated = allocWasm(deps)(newCapacity);
+          }
+          if (!allocated.ok) {
+            capacity = 0;
+            return allocated;
+          }
+          buffer = allocated.value;
+          capacity = newCapacity;
+          return ok(buffer);
+        },
+      },
+      disposer,
+    ),
+  );
+};
+
+/** The largest C int. */
+export const maxInt32 = 0x7fff_ffff;
+
+/**
+ * Whether a number is a 32-bit integer, which binds with `sqlite3_bind_int`
+ * without a BigInt.
+ */
+export const isInt32 = (value: number): boolean =>
+  Number.isInteger(value) && value >= -maxInt32 - 1 && value <= maxInt32;
+
+/** The largest SQLite INTEGER, 2^63 - 1. */
+export const maxSqliteInt64 = 2n ** 63n - 1n;
+
+/** The smallest SQLite INTEGER, -2^63. */
+export const minSqliteInt64 = -(2n ** 63n);
+
+/**
+ * Whether a bigint fits a SQLite INTEGER.
+ *
+ * The wasm boundary converts a bigint to i64 modulo 2^64 without an error, so
+ * anything passed to `sqlite3_bind_int64` must be checked first.
+ */
+export const isSqliteInt64 = (value: bigint): boolean =>
+  BigInt.asIntN(64, value) === value;

package/src/Pointer.ts

@@ -0,0 +1,121 @@
+/**
+ * Branded pointers into SQLite's wasm memory and function table.
+ *
+ * At runtime every pointer is a wasm32 address, a plain number. The brands keep
+ * C types apart, so a statement cannot be passed where a connection is
+ * expected, borrowed memory cannot be freed, and no JavaScript string converts
+ * to a C string implicitly. Only this package creates pointer values, from what
+ * the wasm returns.
+ *
+ * The loader caps memory at 2 GiB (32768 pages), so every address is a
+ * non-negative i32 and reads with `getUint32` need no `>>> 0`.
+ *
+ * @module
+ */
+
+import type { Brand } from "@evolu/common";
+import type {
+  SQLITE_STATIC,
+  SQLITE_TRANSIENT,
+  SQLITE_WASM_DEALLOC,
+} from "./Constants.ts";
+
+/** An address in the wasm heap. */
+export type WasmPtr = number & Brand<"WasmPtr">;
+
+/**
+ * The C NULL pointer.
+ *
+ * Functions that can return NULL include it in their result type, and a `=== 0`
+ * check narrows it away.
+ */
+export type NullPtr = 0;
+
+/**
+ * A NUL-terminated UTF-8 string.
+ *
+ * Returned C strings are borrowed from SQLite: copy them before the next call
+ * on the same object and never free them.
+ */
+export type CStringPtr = WasmPtr & Brand<"CString">;
+
+/**
+ * Memory allocated with `sqlite3_malloc`.
+ *
+ * The holder frees it with `sqlite3_free` or hands it to SQLite, for example as
+ * a bind value with {@link SQLITE_WASM_DEALLOC}.
+ */
+export type SqliteOwnedPtr = WasmPtr & Brand<"SqliteOwned">;
+
+/**
+ * A NUL-terminated UTF-8 string in memory allocated with `sqlite3_malloc`,
+ * which the holder frees with `sqlite3_free`.
+ */
+export type SqliteOwnedCStringPtr = SqliteOwnedPtr & CStringPtr;
+
+/** An open database connection, `sqlite3*`. */
+export type SqliteDbPtr = WasmPtr & Brand<"SqliteDb">;
+
+/** A prepared statement, `sqlite3_stmt*`. */
+export type SqliteStmtPtr = WasmPtr & Brand<"SqliteStmt">;
+
+/**
+ * A dynamically typed SQL value, `sqlite3_value*`, such as a column value or an
+ * argument of an application-defined function.
+ */
+export type SqliteValuePtr = WasmPtr & Brand<"SqliteValue">;
+
+/**
+ * A protected value copied with `sqlite3_value_dup`, which the holder frees
+ * with `sqlite3_value_free`.
+ *
+ * Column values, function arguments and the other values SQLite passes are
+ * borrowed, so `sqlite3_value_free` rejects them.
+ */
+export type SqliteOwnedValuePtr = SqliteValuePtr & Brand<"SqliteOwnedValue">;
+
+/** The context of an application-defined function call, `sqlite3_context*`. */
+export type SqliteContextPtr = WasmPtr & Brand<"SqliteContext">;
+
+/** A VFS struct, `sqlite3_vfs*`. */
+export type SqliteVfsPtr = WasmPtr & Brand<"SqliteVfs">;
+
+/**
+ * A file SQLite opened through a VFS, `sqlite3_file*`.
+ *
+ * SQLite allocates it with the VFS's `szOsFile` bytes before calling `xOpen`.
+ */
+export type SqliteFilePtr = WasmPtr & Brand<"SqliteFile">;
+
+/**
+ * A database filename SQLite created, `sqlite3_filename`, as `xOpen` receives
+ * it.
+ *
+ * SQLite stores the URI parameters after the name, where the `sqlite3_uri_*`
+ * functions read them, so no other C string can take its place.
+ */
+export type SqliteFilenamePtr = CStringPtr & Brand<"SqliteFilename">;
+
+/**
+ * The query planner's exchange with a virtual table's `xBestIndex`,
+ * `sqlite3_index_info*`.
+ */
+export type SqliteIndexInfoPtr = WasmPtr & Brand<"SqliteIndexInfo">;
+
+/**
+ * A C function pointer, which in wasm is an index into the function table, not
+ * a memory address.
+ */
+export type SqliteFunctionPtr = number & Brand<"SqliteFunctionPtr">;
+
+/**
+ * The destructor argument of `sqlite3_bind_text`, `sqlite3_bind_blob`,
+ * `sqlite3_result_text` and `sqlite3_result_blob`.
+ *
+ * {@link SQLITE_STATIC} promises the memory outlives the value,
+ * {@link SQLITE_TRANSIENT} makes SQLite copy it, and a function pointer such as
+ * {@link SQLITE_WASM_DEALLOC} hands it to SQLite, which frees it even when the
+ * call fails.
+ */
+export type SqliteDestructor =
+  typeof SQLITE_STATIC | typeof SQLITE_TRANSIENT | SqliteFunctionPtr;