@di-framework/bindings 6.0.7 → 6.0.8

package/README.md

@@ -46,6 +46,55 @@ connection and the selected database; multiple independently credentialed Postgr
 bindings are not supported by this QuickJS path yet. Guests initialize before the
 application, including bindings constructed at module startup.
 
+## Transaction semantics
+
+`wasmcloud:postgres@0.2.0` has `query` and `queryBatch`, and no transaction handle. Each call goes
+to whichever pooled connection is free. A named import (`user-database-query`) is served from a
+per-credential pool with no connection affinity, so a `BEGIN` in one call does not cover the next
+statement. A `COMMIT` can land on a connection that never saw the `BEGIN`, and that connection
+stays `idle in transaction`.
+
+Guests that use `@di-framework/repo` open the binding with `openPostgresDatabase` from
+`@di-framework/bindings/postgres`. The handle is an `AutocommitDatabase`. Every statement is its
+own transaction, and `transaction(fn)` runs `fn` on that same handle. The adapter never sends
+`BEGIN`, `COMMIT`, or `ROLLBACK`. `FOR UPDATE` and advisory locks last only for the statement
+that carries them.
+
+Keep an invariant in one statement:
+
+- a conditional `UPDATE … RETURNING`
+- a data-modifying CTE
+- `INSERT … SELECT … WHERE NOT EXISTS`
+
+`run` sets `changes` from the rows returned. The provider does not report a command tag, so a
+count is a `RETURNING` list. A `changes` value of `0` means no rows came back, which is what an
+`UPDATE` or `DELETE` without `RETURNING` reports even when Postgres modified rows.
+
+`exec` sends its script as one `queryBatch`. The host runs that string on one pooled client, and
+Postgres treats a multi-statement simple query as one implicit transaction.
+
+`atomicBatch` is for a write-only sequence that must commit or roll back together and that does
+not read between statements. It renders each parameter as a literal (quotes doubled, a negative
+number parenthesized so it cannot form a `--` comment) and submits that script as one
+`queryBatch`. The script has no `BEGIN` or `COMMIT`. Postgres runs a multi-statement simple
+query as one implicit transaction and rolls it back on error, returning the pooled client idle.
+wasmCloud v2.8.0 runs that string on one pooled client:
+`crates/wash-runtime/src/plugin/wasmcloud_postgres/async_p3.rs` checks out a single client in
+`query_batch` and calls `client.batch_execute` (`batch_with_client`, line 191).
+
+```ts
+import { openPostgresDatabase } from '@di-framework/bindings/postgres';
+
+const db = openPostgresDatabase(database);
+await db.atomicBatch([
+  { sql: 'INSERT INTO t (name, n) VALUES (?, ?)', params: ["o'brien", -1] },
+]);
+```
+
+`@di-framework/repo` is an optional peer of this package. The main `@di-framework/bindings` entry
+leaves it unloaded. Import `@di-framework/bindings/postgres` from a guest that depends on
+`@di-framework/repo`.
+
 Secret material is referenced, never inlined:
 
 ```ts

package/dist/postgres/adapter.d.ts

@@ -0,0 +1,69 @@
+import type { SqlDatabase } from '@di-framework/repo';
+import type { PostgresGuest } from '../bindings/postgres.js';
+import { type AtomicStatement } from './atomic-batch.js';
+/**
+ * `SqlDatabase` over `wasmcloud:postgres@0.2.0` where every statement is its own transaction.
+ *
+ * The binding has no connection or transaction handle, and a named import has no connection
+ * affinity: each `query` and `queryBatch` may run on any pooled connection. A `BEGIN` sent on
+ * one call does not cover the next. This handle never sends `BEGIN`, `COMMIT`, or `ROLLBACK`.
+ * `transaction(fn)` runs `fn` on this same handle. `FOR UPDATE` and advisory locks last only
+ * for their statement.
+ *
+ * Keep an invariant in one statement:
+ *
+ * - conditional `UPDATE … RETURNING`
+ * - a data-modifying CTE
+ * - `INSERT … SELECT … WHERE NOT EXISTS`
+ *
+ * `run` reports `changes` as the number of rows returned. The provider does not report a
+ * command tag, so a count comes from `RETURNING`.
+ *
+ * A multi-statement `exec` script is still one `queryBatch`. The host runs that string with
+ * `batch_execute` on a single pooled client, so Postgres treats it as one implicit transaction.
+ */
+export interface AutocommitDatabase extends SqlDatabase {
+    /**
+     * Writes `statements` as one transaction and returns no rows.
+     *
+     * Parameters are rendered as SQL literals and the text is submitted as a single
+     * `queryBatch` string. The string has no `BEGIN`, `COMMIT`, or `ROLLBACK`.
+     * Postgres treats that multi-statement simple query as one implicit transaction
+     * and rolls it back on error, so the pooled client returns idle. A quote is
+     * doubled. A negative number is parenthesized so it cannot form a `--` comment.
+     * Do not use this when a later statement must read an earlier one.
+     *
+     * The whole string runs on one pooled client. wasmCloud v2.8.0 (commit
+     * `5c4ec4a3d008b3f401d9e763515f434deebc9936`, the wash revision this platform
+     * pins) implements `query_batch` in
+     * `crates/wash-runtime/src/plugin/wasmcloud_postgres/async_p3.rs`. The default
+     * import checks out one client (`query_batch`, line 331) and `batch_with_client`
+     * (line 190) calls `client.batch_execute` with that string (line 191). The named
+     * import does the same (`query_batch`, line 407; `id.client()`, line 412;
+     * `batch_with_client`, line 416). `crates/provider-sqldb-postgres` is not in that
+     * tag. The invocation-lease patch does not split this string, so it still
+     * reaches one `batch_execute`.
+     */
+    atomicBatch(statements: readonly AtomicStatement[]): Promise<void>;
+}
+/**
+ * Opens `binding` as an {@link AutocommitDatabase}.
+ *
+ * `wasmcloud:postgres@0.2.0` has no connection or transaction handle: each `query` and
+ * `query-batch` call may run on any pooled connection of the host, so a `BEGIN` sent in one call
+ * does not cover the next. The guest therefore never opens a transaction. Every statement
+ * commits on its own, `transaction(fn)` runs `fn` on this same handle, and `FOR UPDATE` and
+ * advisory locks last only for their statement. Keep invariants in one statement (conditional
+ * `UPDATE … RETURNING`, data-modifying CTEs, `INSERT … SELECT … WHERE NOT EXISTS`). A
+ * multi-statement `exec` script still runs as one `query-batch`, which Postgres executes as one
+ * implicit transaction on one connection.
+ *
+ * `run`, `query`, and `first` call `query`. `exec` calls `queryBatch`. Failures keep a
+ * five-digit SQLSTATE on `error.code`.
+ */
+export declare function openPostgresDatabase(binding: PostgresGuest): AutocommitDatabase;
+/**
+ * {@link AutocommitDatabase.atomicBatch} for a `PostgresGuest` that is not wrapped
+ * as a `SqlDatabase`.
+ */
+export declare function atomicBatch(binding: PostgresGuest, statements: readonly AtomicStatement[]): Promise<void>;

package/dist/postgres/adapter.js

@@ -0,0 +1,77 @@
+import { assertBatch, postgresError, readRows } from '@di-framework/repo/postgres';
+import { renderAtomicBatch } from './atomic-batch.js';
+import { bindParams } from './bind-params.js';
+/**
+ * Opens `binding` as an {@link AutocommitDatabase}.
+ *
+ * `wasmcloud:postgres@0.2.0` has no connection or transaction handle: each `query` and
+ * `query-batch` call may run on any pooled connection of the host, so a `BEGIN` sent in one call
+ * does not cover the next. The guest therefore never opens a transaction. Every statement
+ * commits on its own, `transaction(fn)` runs `fn` on this same handle, and `FOR UPDATE` and
+ * advisory locks last only for their statement. Keep invariants in one statement (conditional
+ * `UPDATE … RETURNING`, data-modifying CTEs, `INSERT … SELECT … WHERE NOT EXISTS`). A
+ * multi-statement `exec` script still runs as one `query-batch`, which Postgres executes as one
+ * implicit transaction on one connection.
+ *
+ * `run`, `query`, and `first` call `query`. `exec` calls `queryBatch`. Failures keep a
+ * five-digit SQLSTATE on `error.code`.
+ */
+export function openPostgresDatabase(binding) {
+    const handle = {
+        async run(sql, params = []) {
+            const rows = await statements(binding, sql, params);
+            return { changes: rows.length };
+        },
+        async query(sql, params = []) {
+            return (await statements(binding, sql, params));
+        },
+        async first(sql, params = []) {
+            const rows = await statements(binding, sql, params);
+            return (rows[0] ?? null);
+        },
+        async exec(sql) {
+            await submitBatch(binding, sql);
+        },
+        transaction(fn) {
+            return fn(handle);
+        },
+        atomicBatch(statements) {
+            return submitAtomicBatch(binding, statements);
+        },
+    };
+    return handle;
+}
+/**
+ * {@link AutocommitDatabase.atomicBatch} for a `PostgresGuest` that is not wrapped
+ * as a `SqlDatabase`.
+ */
+export async function atomicBatch(binding, statements) {
+    await submitAtomicBatch(binding, statements);
+}
+async function submitAtomicBatch(binding, statements) {
+    await submitBatch(binding, renderAtomicBatch(statements));
+}
+async function statements(binding, sql, params) {
+    const bound = bindParams(sql, params);
+    try {
+        return await readRows(await binding.query(bound.text, bound.params));
+    }
+    catch (error) {
+        throw coded(error);
+    }
+}
+async function submitBatch(binding, sql) {
+    try {
+        assertBatch(await binding.queryBatch(sql));
+    }
+    catch (error) {
+        throw coded(error);
+    }
+}
+function coded(error) {
+    const wrapped = (error instanceof Error && error.message.startsWith('PostgreSQL') ? error : postgresError(error));
+    const code = /PostgreSQL (\d{5})/.exec(wrapped.message)?.[1];
+    if (code !== undefined)
+        wrapped.code = code;
+    return wrapped;
+}

package/dist/postgres/atomic-batch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One write statement inside {@link renderAtomicBatch}.
+ * `?` is a value placeholder. `queryBatch` takes no parameters, so each placeholder
+ * is rendered as a SQL literal before the batch is submitted.
+ */
+export type AtomicStatement = {
+    sql: string;
+    params?: readonly unknown[];
+};
+/**
+ * Renders `statements` as one multi-statement simple query.
+ *
+ * There is no `BEGIN` or `COMMIT`. Postgres runs the string as one implicit
+ * transaction and rolls it back on error, returning the pooled client idle.
+ * An explicit `BEGIN` whose `COMMIT` is skipped would leave that client
+ * `idle in transaction (aborted)`.
+ *
+ * Literals use standard SQL quotes (`standard_conforming_strings`): a quote is
+ * doubled, and a backslash is not an escape. A negative number is parenthesized
+ * so `x-?` with `-1` becomes `x-(-1)` and cannot form a `--` comment. Strings
+ * that match a UUID are quoted too; the hex pattern cannot close the quote.
+ */
+export declare function renderAtomicBatch(statements: readonly AtomicStatement[]): string;

package/dist/postgres/atomic-batch.js

@@ -0,0 +1,104 @@
+/**
+ * Renders `statements` as one multi-statement simple query.
+ *
+ * There is no `BEGIN` or `COMMIT`. Postgres runs the string as one implicit
+ * transaction and rolls it back on error, returning the pooled client idle.
+ * An explicit `BEGIN` whose `COMMIT` is skipped would leave that client
+ * `idle in transaction (aborted)`.
+ *
+ * Literals use standard SQL quotes (`standard_conforming_strings`): a quote is
+ * doubled, and a backslash is not an escape. A negative number is parenthesized
+ * so `x-?` with `-1` becomes `x-(-1)` and cannot form a `--` comment. Strings
+ * that match a UUID are quoted too; the hex pattern cannot close the quote.
+ */
+export function renderAtomicBatch(statements) {
+    if (statements.length === 0)
+        throw new Error('atomicBatch requires at least one statement');
+    const rendered = statements.map((statement) => renderStatement(statement.sql, statement.params ?? []));
+    // No BEGIN/COMMIT: a multi-statement simple query is one implicit transaction
+    // that Postgres rolls back on error without leaving the connection aborted.
+    return `${rendered.join(';\n')};`;
+}
+function renderStatement(sql, params) {
+    const body = sql
+        .trim()
+        .replace(/;+\s*$/u, '')
+        .trim();
+    if (body.length === 0)
+        throw new Error('atomicBatch statement is empty');
+    let index = 0;
+    const rendered = body.replaceAll('?', () => {
+        const value = params[index++];
+        return sqlLiteral(value);
+    });
+    if (index !== params.length) {
+        throw new Error(`SQL placeholder count ${index} does not match ${params.length} parameters`);
+    }
+    return rendered;
+}
+function sqlLiteral(value) {
+    if (value == null)
+        return 'NULL';
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'string')
+        return quote(value);
+    if (typeof value === 'bigint')
+        return integerLiteral(value);
+    if (typeof value === 'number')
+        return numberLiteral(value);
+    if (value instanceof Date)
+        return timestampLiteral(value);
+    if (value instanceof Uint8Array)
+        return byteaLiteral(value);
+    if (typeof value === 'object')
+        return jsonLiteral(value);
+    return unrenderable();
+}
+function quote(value) {
+    if (value.includes('\0'))
+        throw new Error('PostgreSQL text parameter contains a null byte');
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function integerLiteral(value) {
+    return value < 0n ? `(${value})` : `${value}`;
+}
+function numberLiteral(value) {
+    if (!Number.isFinite(value))
+        throw new Error('PostgreSQL parameter is not a finite number');
+    if (Number.isInteger(value)) {
+        if (!Number.isSafeInteger(value)) {
+            throw new Error('PostgreSQL int8 parameter is not an exact integer');
+        }
+        return integerLiteral(BigInt(value));
+    }
+    const text = String(value);
+    if (text.startsWith('-'))
+        return `(${text})`;
+    return text;
+}
+function timestampLiteral(value) {
+    if (Number.isNaN(value.getTime())) {
+        throw new Error('PostgreSQL timestamp-tz parameter has the wrong type');
+    }
+    return quote(value.toISOString());
+}
+function byteaLiteral(value) {
+    const hex = [...value].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+    return `decode('${hex}', 'hex')`;
+}
+function jsonLiteral(value) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch {
+        return unrenderable();
+    }
+    if (json === undefined)
+        return unrenderable();
+    return quote(json);
+}
+function unrenderable() {
+    throw new Error('PostgreSQL parameter cannot be rendered as a literal');
+}

package/dist/postgres/bind-params.d.ts

@@ -0,0 +1,17 @@
+import { type PgParameter } from '@di-framework/repo/postgres';
+/**
+ * Rewrites `@di-framework/repo` `?` placeholders for the wasmCloud Postgres binding.
+ *
+ * The host binds every parameter in binary as the type Postgres infers for its slot, and the
+ * guest never sees that type. A UUID string may fill a `uuid` column or a `varchar` one (the
+ * Spring Authorization Server tables), and its 16 binary bytes are invalid UTF-8 in a
+ * `varchar`. An integer may fill an `int4` slot or an `int8` one (`LIMIT`), and the widths
+ * differ. So UUID strings go inline as untyped literals and safe integers as numeric
+ * constants, which Postgres resolves from context. Neither can carry SQL: the UUID pattern
+ * admits only hex digits and dashes, and a negative integer is parenthesized so it cannot
+ * form a `--` comment.
+ */
+export declare function bindParams(sql: string, params?: readonly unknown[]): {
+    text: string;
+    params: PgParameter[];
+};

package/dist/postgres/bind-params.js

@@ -0,0 +1,44 @@
+import { pgValue } from '@di-framework/repo/postgres';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Rewrites `@di-framework/repo` `?` placeholders for the wasmCloud Postgres binding.
+ *
+ * The host binds every parameter in binary as the type Postgres infers for its slot, and the
+ * guest never sees that type. A UUID string may fill a `uuid` column or a `varchar` one (the
+ * Spring Authorization Server tables), and its 16 binary bytes are invalid UTF-8 in a
+ * `varchar`. An integer may fill an `int4` slot or an `int8` one (`LIMIT`), and the widths
+ * differ. So UUID strings go inline as untyped literals and safe integers as numeric
+ * constants, which Postgres resolves from context. Neither can carry SQL: the UUID pattern
+ * admits only hex digits and dashes, and a negative integer is parenthesized so it cannot
+ * form a `--` comment.
+ */
+export function bindParams(sql, params = []) {
+    if (params.length === 0)
+        return { text: sql, params: [] };
+    const bound = [];
+    let index = 0;
+    const text = sql.replaceAll('?', () => {
+        const value = params[index++];
+        const literal = inlineLiteral(value);
+        if (literal !== undefined)
+            return literal;
+        bound.push(pgValue(value));
+        return `$${bound.length}`;
+    });
+    if (index !== params.length) {
+        throw new Error(`SQL placeholder count ${index} does not match ${params.length} parameters`);
+    }
+    return { text, params: bound };
+}
+function inlineLiteral(value) {
+    if (typeof value === 'string')
+        return UUID.test(value) ? `'${value}'` : undefined;
+    const integer = typeof value === 'bigint'
+        ? value
+        : Number.isSafeInteger(value)
+            ? BigInt(value)
+            : undefined;
+    if (integer === undefined)
+        return undefined;
+    return integer < 0n ? `(${integer})` : `${integer}`;
+}

package/dist/postgres/index.d.ts

@@ -0,0 +1,3 @@
+export { type AutocommitDatabase, atomicBatch, openPostgresDatabase } from './adapter.js';
+export type { AtomicStatement } from './atomic-batch.js';
+export { bindParams } from './bind-params.js';

package/dist/postgres/index.js

@@ -0,0 +1,2 @@
+export { atomicBatch, openPostgresDatabase } from './adapter.js';
+export { bindParams } from './bind-params.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@di-framework/bindings",
-  "version": "6.0.7",
+  "version": "6.0.8",
   "description": "Native platform WIT service bindings for DI Framework applications.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -36,12 +36,24 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./postgres": {
+      "types": "./dist/postgres/index.d.ts",
+      "bun": "./dist/postgres/index.js",
+      "import": "./dist/postgres/index.js",
+      "default": "./dist/postgres/index.js"
+    },
     "./catalog.json": "./catalog.json"
   },
   "peerDependencies": {
     "@di-framework/core": "^5",
+    "@di-framework/repo": "^6.0.4",
     "typescript": "^5"
   },
+  "peerDependenciesMeta": {
+    "@di-framework/repo": {
+      "optional": true
+    }
+  },
   "files": [
     "dist",
     "catalog.json",
@@ -49,6 +61,7 @@
   ],
   "devDependencies": {
     "@di-framework/core": "^5",
+    "@di-framework/repo": "^6.0.4",
     "@types/bun": "latest"
   }
 }