@di-framework/pglite-component 6.0.9 → 6.0.12

package/dist/js/adapter.js

@@ -0,0 +1,514 @@
+/**
+ * `SqlDatabase` adapter for the `di-framework:pglite/database@0.2.0` WIT
+ * import: embedded PostgreSQL 17 bundled into a provider component. The guest
+ * exchanges `value` variants over one exclusive connection, so every call is
+ * serialized through an async mutex.
+ *
+ * Repositories and migrations write `?` placeholders; they are rewritten to
+ * PostgreSQL's `$1`, `$2`, ... (see {@link toPgPlaceholders}). Transactions use
+ * the provider's `begin`/`commit`/`rollback`, and nested `transaction()` calls
+ * open savepoints. Result values match the `wasmcloud:postgres` codec in
+ * `@di-framework/repo` (`pgScalar`): JSON is parsed, `timestamptz` becomes an ISO string with
+ * milliseconds, and an `int8` outside the safe integer range becomes a decimal
+ * string. A Postgres error keeps its SQLSTATE in `error.code`.
+ *
+ * Component bindings differ in how they surface `result<T, error>`: some
+ * return `{ tag: 'ok' | 'err', val }` records, others throw an error object
+ * carrying the variant as `payload`. Both shapes are normalized here.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { AsyncMutex, guardedStatements, isWasmResult, leaseGuard, SQL_DATABASE_BRAND, wasmBlobBytes, } from '@di-framework/repo';
+export const WASM_PGLITE_MODULE_ID = 'di-framework:pglite/database@0.2.0';
+/** Database root the provider selects when `open` receives an empty path. */
+export const WASM_PGLITE_DEFAULT_ROOT = '/data/pglite';
+/**
+ * A provider error. `code` is the SQLSTATE for `execution-failed` (for example
+ * `23505` for a unique violation). The message then starts with
+ * `PostgreSQL <code>`, the format `isUniqueViolation` from `@di-framework/repo` reads.
+ */
+export class WasmPgliteError extends Error {
+    tag;
+    detail;
+    code;
+    constructor(payload, cause) {
+        let detail;
+        let code;
+        if (typeof payload.val === 'string') {
+            detail = payload.val;
+        }
+        else if (typeof payload.val === 'object' && payload.val !== null) {
+            detail = payload.val.message;
+            code = payload.val.code || undefined;
+        }
+        super(wasmPgliteErrorMessage(payload.tag, code, detail), { cause });
+        this.name = 'WasmPgliteError';
+        this.tag = payload.tag;
+        this.detail = detail;
+        this.code = code;
+    }
+}
+function wasmPgliteErrorMessage(tag, code, detail) {
+    if (code)
+        return detail ? `PostgreSQL ${code} ${detail}` : `PostgreSQL ${code}`;
+    return detail ? `PGlite ${tag}: ${detail}` : `PGlite ${tag}`;
+}
+function isErrorPayload(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.tag === 'string' &&
+        value.tag !== 'ok');
+}
+/** Normalizes a thrown binding error or an `err` payload into an `Error`. */
+export function normalizeWasmPgliteError(error) {
+    if (error instanceof WasmPgliteError)
+        return error;
+    if (isErrorPayload(error))
+        return new WasmPgliteError(error);
+    if (typeof error === 'object' && error !== null) {
+        const payload = error.payload;
+        if (isErrorPayload(payload))
+            return new WasmPgliteError(payload, error);
+    }
+    if (typeof error === 'string')
+        return new WasmPgliteError({ tag: 'other', val: error });
+    return error instanceof Error ? error : new Error(String(error));
+}
+/** Unwraps `{ tag: 'ok' | 'err' }` records; passes bare values through. */
+export function unwrapWasmPgliteResult(value) {
+    if (isWasmResult(value)) {
+        if (value.tag === 'err')
+            throw normalizeWasmPgliteError(value.val);
+        return value.val;
+    }
+    return value;
+}
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
+/**
+ * Converts a bound JavaScript parameter into a `value` variant.
+ *
+ * - `bigint` in the safe integer range becomes `integer`; a larger one is sent
+ *   as `text` (OID 0), so PostgreSQL parses it for an `int8`/`numeric` column
+ *   without rounding through a double.
+ * - A `number` that is an integer outside the safe range throws a `TypeError`
+ *   (pass a `bigint` or string for `int8`); other non-safe numbers, including
+ *   NaN and Infinity, are `real` (`float8`).
+ * - `Date` becomes `timestamp` (RFC 3339 UTC); plain objects and arrays become
+ *   `json`. Arrays are not PostgreSQL arrays: pass a literal such as `'{a,b}'`.
+ */
+export function toWasmPgValue(value) {
+    if (value === null || value === undefined)
+        return { tag: 'null' };
+    switch (typeof value) {
+        case 'bigint':
+            // componentize-qjs lowers WIT s64 from JS numbers (f64), not BigInt (#153).
+            if (value >= MIN_SAFE && value <= MAX_SAFE) {
+                return { tag: 'integer', val: Number(value) };
+            }
+            return { tag: 'text', val: value.toString() };
+        case 'number':
+            if (Number.isSafeInteger(value)) {
+                return { tag: 'integer', val: value };
+            }
+            if (Number.isInteger(value)) {
+                // An integral double past 2^53 has already lost its low bits, and the
+                // column is most likely int8; sending float8 would fail or round silently.
+                throw new TypeError(`Cannot bind ${value} as a PostgreSQL parameter: it is an integer outside the safe range. Pass a bigint or a decimal string for int8 (or a string such as '1e300' for float8)`);
+            }
+            // Fractions, NaN and +/-Infinity are valid float8 values in PostgreSQL.
+            return { tag: 'real', val: value };
+        case 'boolean':
+            return { tag: 'boolean', val: value };
+        case 'string':
+            return { tag: 'text', val: value };
+        case 'object':
+            return toWasmPgObject(value);
+    }
+    throw new TypeError(`Cannot bind ${typeof value} as a PostgreSQL parameter; use null, number, bigint, boolean, string, Date, Uint8Array, or a JSON object`);
+}
+function toWasmPgObject(value) {
+    const bytes = wasmBlobBytes(value);
+    if (bytes)
+        return { tag: 'blob', val: bytes };
+    if (!(value instanceof Date))
+        return { tag: 'json', val: JSON.stringify(value) };
+    if (Number.isNaN(value.getTime())) {
+        throw new TypeError('Cannot bind an invalid Date as a PostgreSQL parameter');
+    }
+    return { tag: 'timestamp', val: value.toISOString() };
+}
+const RFC3339_UTC = /^(\d{4,}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d+))?Z$/;
+/**
+ * Formats a `timestamp` variant the way the `wasmcloud:postgres` codec does:
+ * `YYYY-MM-DDTHH:MM:SS.mmmZ`. Microseconds are truncated to milliseconds.
+ * `infinity`, `-infinity`, and BC dates are returned unchanged.
+ */
+export function pgliteTimestampIso(value) {
+    const match = RFC3339_UTC.exec(value);
+    if (!match)
+        return value;
+    const millis = (match[2] ?? '').padEnd(3, '0').slice(0, 3);
+    return `${match[1]}.${millis}Z`;
+}
+/** Converts a `value` variant into what the `wasmcloud:postgres` codec in `@di-framework/repo` returns. */
+export function fromWasmPgValue(value) {
+    switch (value.tag) {
+        case 'null':
+            return null;
+        case 'integer': {
+            if (typeof value.val === 'number')
+                return value.val;
+            return value.val >= MIN_SAFE && value.val <= MAX_SAFE
+                ? Number(value.val)
+                : value.val.toString();
+        }
+        case 'real':
+        case 'text':
+        case 'boolean':
+            return value.val;
+        case 'blob':
+            return value.val instanceof Uint8Array ? value.val : Uint8Array.from(value.val);
+        case 'json':
+            try {
+                return JSON.parse(value.val);
+            }
+            catch {
+                return value.val;
+            }
+        case 'timestamp':
+            return pgliteTimestampIso(value.val);
+        default:
+            throw new WasmPgliteError({
+                tag: 'value-conversion-failed',
+                val: `Unknown value tag ${String(value.tag)}`,
+            });
+    }
+}
+export function toWasmPgParams(params = []) {
+    return params.map((param) => toWasmPgValue(param));
+}
+export function fromWasmPgRow(row) {
+    const result = {};
+    for (const [column, value] of row) {
+        result[column] = fromWasmPgValue(value);
+    }
+    return result;
+}
+const IDENTIFIER_CHAR = /[\w$]/;
+const DOLLAR_TAG = /^\$(?:[A-Za-z_]\w*)?\$/;
+const POSITIONAL = /^\$\d+/;
+function skipQuoted(sql, start, quote, backslashes) {
+    let index = start + 1;
+    while (index < sql.length) {
+        const char = sql[index];
+        if (backslashes && char === '\\') {
+            index += 2;
+        }
+        else if (char === quote) {
+            if (sql[index + 1] !== quote)
+                return index + 1;
+            index += 2;
+        }
+        else {
+            index++;
+        }
+    }
+    return sql.length;
+}
+function skipBlockComment(sql, start) {
+    let depth = 0;
+    let index = start;
+    while (index < sql.length) {
+        if (sql.startsWith('/*', index)) {
+            depth++;
+            index += 2;
+        }
+        else if (sql.startsWith('*/', index)) {
+            depth--;
+            index += 2;
+            if (depth === 0)
+                return index;
+        }
+        else {
+            index++;
+        }
+    }
+    return sql.length;
+}
+function isEscapeString(sql, quote) {
+    const prefix = sql[quote - 1];
+    return (prefix === 'E' || prefix === 'e') && !IDENTIFIER_CHAR.test(sql[quote - 2] ?? '');
+}
+/**
+ * Rewrites `?` placeholders to `$1`, `$2`, ... in order.
+ *
+ * Skipped: `'...'` and `E'...'` strings, `"..."` identifiers, `$tag$...$tag$`
+ * dollar quotes, `--` and nested `/* *\/` comments, and the `?|` / `?&` jsonb
+ * operators. The bare jsonb `?` (key exists) operator cannot be told apart
+ * from a placeholder: write `jsonb_exists(col, ?)` instead. The adapter does
+ * not rewrite statements bound without parameters, so a literal `?` operator
+ * still works there. Mixing `?` with explicit `$n` placeholders throws.
+ */
+export function toPgPlaceholders(sql) {
+    let out = '';
+    let index = 0;
+    let count = 0;
+    let positional = false;
+    while (index < sql.length) {
+        let end = skippedTokenEnd(sql, index);
+        if (end === undefined && sql[index] === '$') {
+            const dollar = dollarTokenEnd(sql, index);
+            end = dollar.end;
+            positional ||= dollar.positional;
+        }
+        if (end === undefined && sql[index] === '?') {
+            out += `$${++count}`;
+            index++;
+            continue;
+        }
+        end ??= index + 1;
+        out += sql.slice(index, end);
+        index = end;
+    }
+    if (count > 0 && positional) {
+        throw new TypeError('Cannot mix ? placeholders with $n placeholders in one statement');
+    }
+    return out;
+}
+/** End of the string, identifier, comment, or `?|`/`?&` operator at `index`. */
+function skippedTokenEnd(sql, index) {
+    const char = sql[index];
+    const next = sql[index + 1];
+    if (char === "'")
+        return skipQuoted(sql, index, "'", isEscapeString(sql, index));
+    if (char === '"')
+        return skipQuoted(sql, index, '"', false);
+    if (char === '-' && next === '-') {
+        const newline = sql.indexOf('\n', index);
+        return newline < 0 ? sql.length : newline;
+    }
+    if (char === '/' && next === '*')
+        return skipBlockComment(sql, index);
+    if (char === '?' && (next === '|' || next === '&'))
+        return index + 2;
+    return undefined;
+}
+/** End of the `$tag$...$tag$` body or `$n` placeholder that starts at `index`. */
+function dollarTokenEnd(sql, index) {
+    if (IDENTIFIER_CHAR.test(sql[index - 1] ?? ''))
+        return { end: index + 1, positional: false };
+    const rest = sql.slice(index);
+    const tag = DOLLAR_TAG.exec(rest)?.[0];
+    if (tag) {
+        const close = sql.indexOf(tag, index + tag.length);
+        return { end: close < 0 ? sql.length : close + tag.length, positional: false };
+    }
+    const number = POSITIONAL.exec(rest)?.[0];
+    if (number)
+        return { end: index + number.length, positional: true };
+    return { end: index + 1, positional: false };
+}
+async function call(fn) {
+    try {
+        return unwrapWasmPgliteResult(await fn());
+    }
+    catch (error) {
+        throw normalizeWasmPgliteError(error);
+    }
+}
+function descendsFrom(scope, ancestor) {
+    for (let current = scope.parent; current; current = current.parent) {
+        if (current === ancestor)
+            return true;
+    }
+    return false;
+}
+/**
+ * Wraps an open WIT `connection` resource as a `SqlDatabase`.
+ *
+ * Every statement holds one mutex. `transaction(fn)` runs `begin` … `commit`
+ * and calls `rollback` when `fn` throws. Statements issued from inside `fn`,
+ * through the callback view or the outer handle, join the transaction; other
+ * tasks wait. A nested `transaction()` opens a savepoint: its failure rolls
+ * back to the savepoint, and its work commits only with the outer transaction.
+ * Sibling savepoints started concurrently run one at a time; a plain statement
+ * issued while a sibling savepoint is open joins that savepoint.
+ *
+ * Inside `fn`, prefer the callback view: while its transaction or savepoint is
+ * open it joins from any async context. The outer handle joins only from
+ * `fn`'s own async context (tracked with AsyncLocalStorage); from anywhere else
+ * it waits for the mutex, which deadlocks if `fn` awaits it.
+ *
+ * Sibling savepoints are queued on their parent. `transaction()` on a view,
+ * called from an async context outside an open sibling savepoint, waits for
+ * that sibling to finish; if the sibling awaits that call, it waits forever.
+ *
+ * Joining lasts only while a transaction is open. A savepoint view kept after
+ * its savepoint ends joins the nearest open ancestor, so its work commits or
+ * rolls back with that ancestor. Once the root transaction has ended, a
+ * retained view, like a timer scheduled inside `fn`, takes the mutex like any
+ * other caller.
+ */
+export function createSqlDatabaseFromWasmPgliteConnection(connection) {
+    const mutex = new AsyncMutex();
+    // The outer handle joins a running root transaction from its own async
+    // context for as long as that transaction's lease is active. The lease ends
+    // before COMMIT/ROLLBACK is issued (see `enter`), unlike `contextLock`, which
+    // would keep it until the holder returns.
+    const held = new AsyncLocalStorage();
+    const locked = (fn) => (held.getStore()?.active ? fn() : mutex.run(fn));
+    // Statements a transaction's callers issue concurrently reach the connection
+    // one at a time, even when the binding returns promises (see `leaseGuard`).
+    const wire = new AsyncMutex();
+    const invoke = (fn) => wire.run(() => call(fn));
+    const activeScope = new AsyncLocalStorage();
+    let savepoints = 0;
+    const bind = (sql, params) => {
+        const values = toWasmPgParams(params);
+        return { sql: values.length > 0 ? toPgPlaceholders(sql) : sql, values };
+    };
+    const calls = {
+        run: async (sql, params) => {
+            const bound = bind(sql, params);
+            const changes = await invoke(() => connection.run(bound.sql, bound.values));
+            return { changes: Number(changes ?? 0) };
+        },
+        query: async (sql, params) => {
+            const bound = bind(sql, params);
+            const rows = await invoke(() => connection.query(bound.sql, bound.values));
+            return rows.map((row) => fromWasmPgRow(row));
+        },
+        first: async (sql, params) => {
+            const bound = bind(sql, params);
+            const row = await invoke(() => connection.first(bound.sql, bound.values));
+            return row ? fromWasmPgRow(row) : null;
+        },
+        exec: async (sql) => {
+            await invoke(() => connection.exec(sql));
+        },
+    };
+    const statementsVia = (guard) => ({
+        [SQL_DATABASE_BRAND]: true,
+        ...guardedStatements(guard, calls),
+    });
+    /** The innermost transaction or savepoint of this context that is still open. */
+    const liveScope = () => {
+        let scope = activeScope.getStore();
+        while (scope && !scope.lease.active)
+            scope = scope.parent;
+        return scope;
+    };
+    const enter = async (scope, fn, open, close, undo) => {
+        try {
+            await invoke(open);
+            try {
+                const result = await activeScope.run(scope, () => fn(scope.view));
+                // End the lease before COMMIT / RELEASE is issued: a statement that
+                // arrives late waits for the mutex and runs after the transaction,
+                // instead of reaching the wire between the close and the end of the lease.
+                scope.lease.active = false;
+                await invoke(close);
+                return result;
+            }
+            catch (error) {
+                scope.lease.active = false;
+                try {
+                    await invoke(undo);
+                }
+                catch { }
+                throw error;
+            }
+        }
+        finally {
+            scope.lease.active = false;
+        }
+    };
+    const nest = (parent, fn) => {
+        const current = liveScope();
+        if (current && descendsFrom(current, parent))
+            return nest(current, fn);
+        return parent.children.run(() => {
+            const name = `di_sp_${++savepoints}`;
+            return enter(createScope(parent), fn, () => connection.savepoint(name), () => connection.releaseSavepoint(name), () => connection.rollbackToSavepoint(name));
+        });
+    };
+    // A view runs directly while its scope is open, from any async context: the
+    // scope's lease is cleared before the mutex is released. Once a savepoint has
+    // ended, its view falls back to the parent scope, which is still open and
+    // may be awaiting the caller; taking the root mutex there would deadlock. A
+    // root view, whose transaction holds that mutex, takes it like the outer handle.
+    const createScope = (parent, lease = { active: true }) => {
+        const guard = leaseGuard(lease, parent ? parent.guard : locked);
+        const scope = {
+            parent,
+            children: new AsyncMutex(),
+            lease,
+            guard,
+            view: {
+                ...statementsVia(guard),
+                // A view kept past its scope opens its transaction on the parent scope
+                // (or, for a root view, a fresh transaction).
+                transaction: (fn) => lease.active
+                    ? nest(scope, fn)
+                    : parent
+                        ? parent.view.transaction(fn)
+                        : database.transaction(fn),
+            },
+        };
+        return scope;
+    };
+    const database = {
+        ...statementsVia(locked),
+        transaction: async (fn) => {
+            const current = liveScope();
+            if (current)
+                return nest(current, fn);
+            return mutex.run(() => {
+                // The root scope's lease doubles as the outer handle's join lease.
+                const lease = { active: true };
+                return held.run(lease, () => enter(createScope(undefined, lease), fn, () => connection.begin(), () => connection.commit(), () => connection.rollback()));
+            });
+        },
+        close: () => locked(() => invoke(() => connection.close())),
+    };
+    return database;
+}
+let cachedModule;
+/**
+ * Imports `di-framework:pglite/database@0.2.0`, provided by the composed provider component.
+ *
+ * The module's types come from `wit.d.ts`, generated from `wit/world.wit`. The
+ * conversion below has no cast, so a WIT change that breaks the adapter's view
+ * of the interface fails the typecheck. The check covers method names, arity
+ * and result types, not the parameter variants (see the TODO on
+ * `WasmPgliteConnection`).
+ */
+export function loadWasmPgliteModule() {
+    cachedModule ??= import('di-framework:pglite/database@0.2.0')
+        .then((module) => module)
+        .catch((error) => {
+        cachedModule = undefined;
+        throw new Error(`The ${WASM_PGLITE_MODULE_ID} import is unavailable in this runtime; compose the component with the di-framework PGlite provider`, { cause: error });
+    });
+    return cachedModule;
+}
+/**
+ * Opens a persistent PGlite database root through the provider component and
+ * adapts it to `SqlDatabase`. `path` is the root directory inside a writable
+ * WASI preopen (for example `/data/identity`); an empty path selects
+ * {@link WASM_PGLITE_DEFAULT_ROOT}. The provider allows one open connection per
+ * component instance, so keep one handle and share it.
+ */
+export async function createWasmPgliteDatabase(path = '', options = {}) {
+    const { module: providedModule, loadModule, ...openOptions } = options;
+    const module = providedModule ?? (await (loadModule ?? loadWasmPgliteModule)());
+    const resolvedOpenOptions = {
+        ...(openOptions.database !== undefined ? { database: openOptions.database } : {}),
+        ...(openOptions.statementTimeoutMs !== undefined
+            ? { statementTimeoutMs: openOptions.statementTimeoutMs }
+            : {}),
+    };
+    const hasOptions = Object.keys(resolvedOpenOptions).length > 0;
+    const connection = await call(() => module.open(path, hasOptions ? resolvedOpenOptions : undefined));
+    return createSqlDatabaseFromWasmPgliteConnection(connection);
+}

package/dist/js/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `SqlDatabase` adapter for the `di-framework:pglite/database` WIT interface
+ * this package's component exports. Depends on `@di-framework/repo` as a peer.
+ */
+export * from './adapter.js';

package/dist/js/index.js

@@ -0,0 +1,5 @@
+/**
+ * `SqlDatabase` adapter for the `di-framework:pglite/database` WIT interface
+ * this package's component exports. Depends on `@di-framework/repo` as a peer.
+ */
+export * from './adapter.js';

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@di-framework/pglite-component",
-  "version": "6.0.9",
-  "private": false,
-  "description": "Embedded PostgreSQL component with persistent WASI storage and no TCP.",
+  "version": "6.0.12",
+  "type": "module",
+  "description": "Embedded PostgreSQL component with persistent WASI storage and no TCP, plus its SqlDatabase adapter for @di-framework/repo.",
   "license": "(MIT OR Apache-2.0)",
   "author": "@di-framework Contributors",
   "repository": {
@@ -14,15 +14,54 @@
     "url": "https://github.com/di-framework/platform/issues"
   },
   "homepage": "https://github.com/di-framework/platform",
+  "keywords": [
+    "postgresql",
+    "pglite",
+    "wasi",
+    "wit",
+    "webassembly",
+    "component-model",
+    "di-framework"
+  ],
+  "main": "./dist/js/index.js",
+  "types": "./dist/js/index.d.ts",
+  "module": "./dist/js/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/js/index.d.ts",
+      "bun": "./dist/js/index.js",
+      "import": "./dist/js/index.js",
+      "default": "./dist/js/index.js"
+    },
+    "./wasm": "./dist/di-framework-pglite.wasm",
+    "./wit": "./dist/di-framework-pglite.wit",
+    "./wit/*": "./wit/*",
+    "./package.json": "./package.json"
+  },
   "files": [
-    "dist",
+    "dist/js",
+    "dist/di-framework-pglite.wasm",
+    "dist/di-framework-pglite.wit",
+    "dist/BUILD-INFO.txt",
+    "dist/SHA256SUMS",
+    "dist/THIRD-PARTY-NOTICES.txt",
     "README.md",
-    "wit"
+    "wit",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
   ],
   "scripts": {
-    "build": "make build",
+    "build": "bun run build:adapter && make build",
+    "build:adapter": "bun scripts/wit-types.ts --check && rm -rf dist/js && bun x tsc -p tsconfig.build.json && bun ../../scripts/fix-esm-imports.ts dist/js",
+    "wit-types": "bun scripts/wit-types.ts",
     "test": "bun test",
     "smoke": "make smoke",
     "publish-asset": "make publish-asset"
+  },
+  "peerDependencies": {
+    "@di-framework/repo": "^6.1.0"
+  },
+  "devDependencies": {
+    "@di-framework/repo": "^6.1.0"
   }
 }

package/wit/world.wit

@@ -1,4 +1,4 @@
-package di-framework:pglite@0.1.0;
+package di-framework:pglite@0.2.0;
 
 /// Types shared by the `database` interface.
 ///
@@ -25,9 +25,11 @@ interface types {
     open-failed(string),
     /// The connection has been closed with `close` and cannot be used again.
     closed,
-    /// The statement could not be prepared or executed: syntax error, unknown
-    /// table or column. Only single statements are accepted by `run`/`query`/`first`
-    /// (unlike `exec`, which allows `;`-separated batches like the SQLite provider).
+    /// The SQL was rejected before execution. Causes: a syntax error (42601),
+    /// an undeterminable parameter type (42P18), a bad savepoint name, a NUL
+    /// byte in the SQL, or more than one statement passed to `run`/`query`/
+    /// `first` (the server reports that as a syntax error; unlike `exec`,
+    /// which allows `;`-separated batches like the SQLite provider).
     invalid-sql(string),
     /// Wrong number of parameters or a value that could not be bound.
     /// Parameters bind positionally to `$1`, `$2`, ... (not `?`/`?NNN`).
@@ -50,6 +52,23 @@ interface types {
   /// A dynamically-typed value, used for parameters and results.
   /// Identical to the SQLite provider plus `boolean`: Postgres has a native
   /// boolean type and the text encoding (`t`/`f`) is lossy without it.
+  /// `json` and `timestamp` are new in 0.2.0 for PostgreSQL-specific types.
+  ///
+  /// Results (session is `DateStyle=ISO`, `TimeZone=UTC`):
+  /// - `bool` -> `boolean`; `int2`/`int4`/`int8` -> `integer` (`int8` too);
+  ///   `float4`/`float8` -> `real`; `bytea` -> `blob`.
+  /// - `json` and `jsonb` -> `json` (JSON text).
+  /// - `timestamptz` -> `timestamp`, RFC 3339 in UTC (`2024-01-15T10:30:00Z`,
+  ///   fractional seconds kept). `infinity` and `-infinity` are returned as
+  ///   those literals.
+  /// - `timestamp` (no zone) and `date` -> `text` (`2024-01-15 10:30:00`,
+  ///   `2024-01-15`).
+  /// - `uuid` and `numeric` -> `text`; arrays -> `text` as PostgreSQL array
+  ///   literals (`{a,b}`); all other types -> `text`.
+  ///
+  /// Parameters: `text`, `json` and `timestamp` are sent with unknown type
+  /// (OID 0) so PostgreSQL infers the type from context; a parameter with no
+  /// context (`SELECT $1 IS NULL`) needs a cast.
   variant value {
     null,
     integer(s64),
@@ -57,6 +76,8 @@ interface types {
     text(string),
     blob(list<u8>),
     boolean(bool),
+    json(string),
+    timestamp(string),
   }
 
   /// A result row: `(column-name, value)` pairs in column order.