cloudflare-next-intl 0.8.14 → 0.8.16

package/README.md

@@ -560,9 +560,8 @@ user's Firebase ID token is used automatically.
 
 - **Per-statement transactions in `withUserDb`/`withPublicDb`.** Each
   statement in one of their callbacks is its own round-trip, so it is its own
-  implicit transaction — `.transaction()` throws there instead of running
-  non-atomically. Reach for `withUserTransaction`/`withPublicTransaction`
-  (below) when you need more than one statement to succeed or fail together.
+  implicit transaction. Call `.transaction(...)` on the handle (below) when
+  you need more than one statement to succeed or fail together.
 - **Wider SQL surface.** `cfni_exec` runs statements your app generates, so any
   role that can execute it can run arbitrary SQL *within that role's own
   privileges* — a broader surface than PostgREST's normal verbs, though still
@@ -577,31 +576,36 @@ writable CTEs (`with x as (update ... returning ...) select ... from x`).
 Every value round-trips through Postgres' own text representation, not JSON,
 so arrays/`numeric`/timestamps/`bytea` decode the same way they do in
 connection-string mode. `withUserDb`/`withPublicDb` do not run multiple
-statements atomically (each call is its own PostgREST round-trip) — see
-[Multi-statement transactions](#multi-statement-transactions-withusertransaction-withpublictransaction)
-below for the API that does.
+statements atomically on their own (each call is its own PostgREST
+round-trip) — see [Multi-statement transactions](#multi-statement-transactions-dbtransaction)
+below for the `.transaction()` API that does.
 
-#### Multi-statement transactions (`withUserTransaction`/`withPublicTransaction`)
+#### Multi-statement transactions (`db.transaction()`)
 
-`withUserDb`/`withPublicDb` cannot provide atomicity across statements in
-Supabase mode — there is no shared session for `.transaction()` to open, so
-it throws there instead of silently running non-atomically. Reach for
-`withUserTransaction`/`withPublicTransaction` (also from
-`cloudflare-next-intl/db`) whenever a write needs more than one statement to
-succeed or fail together.
+Call `.transaction(...)` on the handle `withUserDb`/`withPublicDb` hand your
+callback whenever a write needs more than one statement to succeed or fail
+together — same method name in both transport modes.
 
-They take a `build` callback that **builds** queries instead of executing
-them — call `.toSQL()` on each Drizzle query and return the array, rather
-than `await`ing the query directly:
+In connection-string mode this is a real Drizzle transaction: `await
+db.transaction(async (tx) => { await tx.insert(...); await tx.update(...); })`,
+and a later statement may use an earlier one's result, exactly like plain
+Drizzle usage.
+
+In Supabase mode there is no shared session for `.transaction()` to open, so
+its callback instead **builds** queries rather than executing them — call
+`.toSQL()` on each Drizzle query and return the array, rather than `await`ing
+the query directly:
 
 ```typescript
-import { withUserTransaction } from "cloudflare-next-intl/db";
+import { withUserDb } from "cloudflare-next-intl/db";
 import { invitations, contractorAccessGrants } from "@/shared/db/generated/schema";
 
-const [invitationResult, grantResult] = await withUserTransaction((db) => [
-    db.insert(invitations).values({ email: "a@b.com" }).returning().toSQL(),
-    db.insert(contractorAccessGrants).values({ propertyId: 1 }).toSQL(),
-]);
+const [invitationResult, grantResult] = await withUserDb((db) =>
+    db.transaction((tx) => [
+        tx.insert(invitations).values({ email: "a@b.com" }).returning().toSQL(),
+        tx.insert(contractorAccessGrants).values({ propertyId: 1 }).toSQL(),
+    ]),
+);
 ```
 
 Every query in the array is rendered and sent to Postgres as **one**
@@ -617,14 +621,13 @@ whenever `cfni_exec` is: there is no separate config flag, and
 Each result is the same `{ rows, rowCount }` shape a single `cfni_exec` call
 returns — decode rows the same way you would from `db.execute(sql\`...\`)`.
 
-`await`ing a query directly inside `build` (instead of calling `.toSQL()`)
-throws immediately, naming the mistake, rather than hanging or silently
-running that one statement outside the batch with no atomicity.
-
-In connection-string mode, use `withUserDb`/`withPublicDb`'s own
-`.transaction()` instead — it already provides real atomicity there, so
-`withUserTransaction`/`withPublicTransaction` throw rather than duplicate
-that path.
+`await`ing a query directly inside the Supabase-mode `.transaction()`
+callback (instead of calling `.toSQL()`) throws immediately, naming the
+mistake, rather than hanging or silently running that one statement outside
+the batch with no atomicity. This also means, unlike connection-string mode,
+a later statement in a Supabase-mode `.transaction()` callback cannot read an
+earlier one's result — build every statement from arguments/closures you
+already have.
 
 #### Supabase mode and REST translation
 
@@ -666,8 +669,8 @@ await withPublicDb((db) => db.delete(bonds).where(eq(bonds.id, 1)));
 | `RETURNING` clauses | Supported | Supported |
 | Operators: `=`, `<>`, `!=`, `>`, `>=`, `<`, `<=`, `like`, `ilike`, `is [not] null`, `[not] in`, `is [not] distinct from`, `~`, `~*`, `@>`, `<@`, `&&`, `>>`, `<<`, `&>`, `&<`, `-|-`, `@@` | Supported | Supported |
 | Multi-table joins, CTEs, non-count aggregates, `GROUP BY`, `UNION`, `DISTINCT`, raw SQL | Not supported by REST | Supported |
-| Multi-statement transactions in `withUserDb`/`withPublicDb` | Not supported | Not supported (each call is its own round-trip) |
-| Multi-statement transactions via `withUserTransaction`/`withPublicTransaction` | N/A — batch-only API | Supported (`cfni_exec_batch`, one round-trip) |
+| Multi-statement transactions without calling `.transaction()` | Not supported | Not supported (each call is its own round-trip) |
+| Multi-statement transactions via `db.transaction()` | N/A — build-and-return API | Supported (`cfni_exec_batch`, one round-trip) |
 
 #### Enforcing single API via ESLint (`cloudflare-next-intl/dbEslint`)
 
@@ -682,9 +685,10 @@ export default [
 ];
 ```
 
-Four query wrappers, all from `cloudflare-next-intl/db`. Choose by who is
-allowed to see the rows, then by whether you need more than one statement to
-succeed or fail together:
+Two query wrappers, both from `cloudflare-next-intl/db`. Choose by who is
+allowed to see the rows; call `.transaction(...)` on the handle either one
+hands your callback when a write needs more than one statement to succeed or
+fail together (see [Multi-statement transactions](#multi-statement-transactions-dbtransaction) above):
 
 - `withPublicDb(fn)` — runs `fn` as the anonymous role: a pooled connection
   with no transaction/role switch in connection-string mode, or the anon key
@@ -701,13 +705,6 @@ succeed or fail together:
   the id comes from `db.getUserId()` if set, otherwise automatically from the
   signed-in Firebase user when `firebaseAuth` is configured — you rarely need
   to pass it explicitly.
-- `withPublicTransaction(build)` / `withUserTransaction(build)` — same role
-  split as above, but for a write that needs more than one statement to
-  succeed or fail together. See
-  [Multi-statement transactions](#multi-statement-transactions-withusertransaction-withpublictransaction)
-  above — `build` returns built (`.toSQL()`) queries rather than executing
-  them, and these two are currently Supabase-mode only (connection-string
-  mode already has real atomicity via `withUserDb`/`withPublicDb`).
 
 ```typescript
 // anywhere on the server
@@ -798,7 +795,7 @@ your project — `--rpc-dir` (defaulting inside `--ddl-dir`, so `rpcs` under
 always holding the current version of the function, without a manual
 copy-paste step. Since the file now ships both `cfni_exec` and
 `cfni_exec_batch` (see
-[Multi-statement transactions](#multi-statement-transactions-withusertransaction-withpublictransaction)
+[Multi-statement transactions](#multi-statement-transactions-dbtransaction)
 above), pass `--rpc-file-name=`/`--tests-file-name=` (or
 `CFNI_DB_RPC_FILE_NAME`/`CFNI_DB_TESTS_FILE_NAME`) if you'd rather install it
 under a name that reflects that, e.g. `cfni_exec_and_batch.sql`.

package/dist/src/db/context.d.ts

@@ -1,6 +1,4 @@
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
-import type { Query } from 'drizzle-orm';
-import type { ExecResult } from './supabase_transport';
 /**
  * The Drizzle handle passed to `withPublicDb`/`withUserDb` callbacks. Use it
  * exactly like a normal Drizzle database (`db.select().from(table)`); it is
@@ -18,7 +16,9 @@ export type DrizzleDb = NodePgDatabase<Record<string, never>>;
  * In connection-string mode the connection is taken from the request's
  * shared client and released when `fn` settles, even if it throws. In
  * Supabase mode there is no connection to release — each call is one
- * PostgREST round-trip authenticated as the anon key.
+ * PostgREST round-trip authenticated as the anon key. Either way, call
+ * `.transaction(...)` on the handle `fn` receives for atomicity across more
+ * than one statement — see the module doc for the shape that takes in each mode.
  *
  * @param fn Receives the Drizzle handle; return whatever the caller needs.
  * @returns Whatever `fn` resolves to.
@@ -37,13 +37,16 @@ export declare function withPublicDb<T>(fn: (db: DrizzleDb) => Promise<T>): Prom
  * PostgREST-issued call. In Supabase mode identity instead rides on the JWT
  * sent as `Authorization: Bearer` — PostgREST resolves the `authenticated`
  * role and populates `request.jwt.claims` itself, and each statement is its
- * own round-trip with no cross-statement transaction (the Postgres proxy
- * Drizzle uses in this mode cannot open one). Either way this is the wrapper
- * to use for anything user-owned.
+ * own round-trip with no cross-statement transaction unless you call
+ * `.transaction(...)` on the handle (the Postgres proxy Drizzle uses in this
+ * mode cannot open a real session, so that runs as one atomic
+ * `cfni_exec_batch` call instead — see the module doc). Either way this is
+ * the wrapper to use for anything user-owned.
  *
  * @param fn Receives the Drizzle handle. In connection-string mode it is
- * bound to a transaction; in Supabase mode it is not — do not rely on
- * multi-statement atomicity there.
+ * also bound to a transaction; in Supabase mode it is not, but its own
+ * `.transaction(...)` still provides atomicity across statements there
+ * (build-and-return shape, not a live session — see the module doc).
  * @param uid Connection-string mode only: overrides the user id. Omit it, or
  * pass `null`, in normal use — either way the id then comes from
  * `db.getUserId()` when set, otherwise from the signed-in Firebase user when
@@ -60,45 +63,5 @@ export declare function withPublicDb<T>(fn: (db: DrizzleDb) => Promise<T>): Prom
  * const mine = await withUserDb((db) => db.select().from(orders));
  */
 export declare function withUserDb<T>(fn: (db: DrizzleDb) => Promise<T>, uid?: string | null): Promise<T>;
-/** One statement's `{rows, rowCount}` result from a `withUserTransaction`/`withPublicTransaction` batch. */
+/** One statement's `{rows, rowCount}` result from a Supabase-mode `db.transaction()` batch. */
 export type { ExecResult as TransactionResult } from './supabase_transport';
-/**
- * Runs several statements atomically as the **anonymous** role.
- *
- * See {@link runTransaction} for the batching mechanism. `build` must not
- * execute its queries — return their `.toSQL()` form instead.
- *
- * @param build Returns the queries to run, in order.
- * @returns One `{rows, rowCount}` result per query, in the same order.
- * @throws If `db` is not set, if this isn't Supabase mode (connection-string
- * mode already has real transactions via `withPublicDb`), or if any
- * statement in the batch fails — the whole batch is then rolled back.
- *
- * @example
- * const [inserted] = await withPublicTransaction((db) => [
- *     db.insert(logEntries).values({ event: 'visit' }).toSQL(),
- * ]);
- */
-export declare function withPublicTransaction(build: (db: DrizzleDb) => Promise<Query[]> | Query[]): Promise<ExecResult[]>;
-/**
- * Runs several statements atomically as the **signed-in user**.
- *
- * See {@link runTransaction} for the batching mechanism and
- * {@link withUserDb} for how the caller's identity is resolved. In Supabase
- * mode this is the wrapper to reach for whenever a user-owned write needs
- * more than one statement to succeed or fail together — `withUserDb` alone
- * cannot provide that there.
- *
- * @param build Returns the queries to run, in order. Do not execute them —
- * call `.toSQL()` on each and return the array.
- * @returns One `{rows, rowCount}` result per query, in the same order.
- * @throws If `db` is not set, if no access token can be resolved, if this
- * isn't Supabase mode, or if any statement in the batch fails — the whole
- * batch is then rolled back.
- *
- * @example
- * const [invitation] = await withUserTransaction((db) => [
- *     db.insert(invitations).values({ email }).returning().toSQL(),
- * ]);
- */
-export declare function withUserTransaction(build: (db: DrizzleDb) => Promise<Query[]> | Query[]): Promise<ExecResult[]>;

package/dist/src/db/context.js

@@ -33,35 +33,38 @@ async function resolveUserId(uid) {
 /**
  * Builds a Drizzle handle backed by PostgREST. `bearerToken` decides the role
  * Postgres sees: the anon key for public access, a user JWT for `withUserDb`.
+ *
+ * `.transaction()` on this handle runs atomically via `cfni_exec_batch` (see
+ * {@link runTransaction}) — pg-proxy has no session to open a real
+ * transaction over, so every statement the callback returns is queued and
+ * sent as one PostgREST round trip instead. Because of that, the callback
+ * must *build* its queries (`.toSQL()`), not `await`/execute them — a later
+ * statement cannot read an earlier one's result the way it could inside a
+ * real session, unlike connection-string mode's `.transaction()`.
  */
 async function supabaseDb(supabase, bearerToken) {
     const { drizzle } = await import('drizzle-orm/pg-proxy');
     const db = drizzle(createSupabaseTransport(supabase, bearerToken));
     return Object.assign(db, {
-        // pg-proxy has no session to open a real transaction over — every
-        // statement is its own PostgREST round-trip — so failing loudly here
-        // beats silently running the callback non-atomically.
-        transaction() {
-            throw new Error('db: transactions are not available in Supabase mode. Each statement runs as its ' +
-                'own PostgREST round-trip with no shared session, so `.transaction()` cannot provide ' +
-                'atomicity. Use connection-string mode (`db.connectionString`) if you need it.');
+        transaction(build) {
+            return runTransaction(supabase, bearerToken, build);
         },
     });
 }
 /**
- * Builds a Drizzle handle with no working transport, for
- * `withUserTransaction`/`withPublicTransaction` callbacks in Supabase mode.
- * Query builders' `.toSQL()` never touches the session, so this is safe to
- * hand out purely for building statements — but `await`ing a query directly
- * (instead of collecting its `.toSQL()` output) throws immediately here
- * instead of hanging or silently running outside the batch.
+ * Builds a Drizzle handle with no working transport, for Supabase-mode
+ * `db.transaction(...)` callbacks. Query builders' `.toSQL()` never touches
+ * the session, so this is safe to hand out purely for building statements —
+ * but `await`ing a query directly (instead of collecting its `.toSQL()`
+ * output) throws immediately here instead of hanging or silently running
+ * outside the batch.
  */
 function buildOnlyDb() {
     const throwIfExecuted = () => {
         throw new Error('db: this Drizzle handle is for building statements only — call `.toSQL()` on each ' +
             'query and return the array, do not `await`/execute it directly. Awaiting a query ' +
-            'inside a withUserTransaction/withPublicTransaction callback runs it outside the ' +
-            'batch, with no atomicity, which is exactly what these wrappers exist to prevent.');
+            'inside a Supabase-mode db.transaction() callback runs it outside the batch, with no ' +
+            'atomicity, which is exactly what `.transaction()` exists to prevent.');
     };
     return new Proxy({}, { get: () => throwIfExecuted });
 }
@@ -76,7 +79,9 @@ function buildOnlyDb() {
  * In connection-string mode the connection is taken from the request's
  * shared client and released when `fn` settles, even if it throws. In
  * Supabase mode there is no connection to release — each call is one
- * PostgREST round-trip authenticated as the anon key.
+ * PostgREST round-trip authenticated as the anon key. Either way, call
+ * `.transaction(...)` on the handle `fn` receives for atomicity across more
+ * than one statement — see the module doc for the shape that takes in each mode.
  *
  * @param fn Receives the Drizzle handle; return whatever the caller needs.
  * @returns Whatever `fn` resolves to.
@@ -111,13 +116,16 @@ export async function withPublicDb(fn) {
  * PostgREST-issued call. In Supabase mode identity instead rides on the JWT
  * sent as `Authorization: Bearer` — PostgREST resolves the `authenticated`
  * role and populates `request.jwt.claims` itself, and each statement is its
- * own round-trip with no cross-statement transaction (the Postgres proxy
- * Drizzle uses in this mode cannot open one). Either way this is the wrapper
- * to use for anything user-owned.
+ * own round-trip with no cross-statement transaction unless you call
+ * `.transaction(...)` on the handle (the Postgres proxy Drizzle uses in this
+ * mode cannot open a real session, so that runs as one atomic
+ * `cfni_exec_batch` call instead — see the module doc). Either way this is
+ * the wrapper to use for anything user-owned.
  *
  * @param fn Receives the Drizzle handle. In connection-string mode it is
- * bound to a transaction; in Supabase mode it is not — do not rely on
- * multi-statement atomicity there.
+ * also bound to a transaction; in Supabase mode it is not, but its own
+ * `.transaction(...)` still provides atomicity across statements there
+ * (build-and-return shape, not a live session — see the module doc).
  * @param uid Connection-string mode only: overrides the user id. Omit it, or
  * pass `null`, in normal use — either way the id then comes from
  * `db.getUserId()` when set, otherwise from the signed-in Firebase user when
@@ -158,95 +166,28 @@ export async function withUserDb(fn, uid) {
     }
 }
 /**
- * Runs several statements atomically, whichever transport mode is active.
- *
- * `build` does not execute its queries — it **builds** them and returns the
- * array. Call `.toSQL()` on each Drizzle query instead of `await`ing it
- * (`await`ing throws immediately here; see {@link buildOnlyDb}). This is
- * only reachable in Supabase mode — connection-string mode already has real
- * atomicity through `withUserDb`/`withPublicDb`'s own `.transaction()`, so
- * `withUserTransaction`/`withPublicTransaction` throw there instead of
- * duplicating that path. In Supabase mode, where `.transaction()` cannot
- * open a session, every query is inlined and sent as one `cfni_exec_batch`
- * call: the Postgres function runs them in order inside a single plpgsql
- * call, which is itself an implicit transaction, so a failure on any
- * statement rolls back every statement before it.
+ * Runs several statements atomically over `cfni_exec_batch`, backing
+ * Supabase-mode `db.transaction()`. `build` does not execute its queries —
+ * it **builds** them and returns the array; call `.toSQL()` on each Drizzle
+ * query instead of `await`ing it (`await`ing throws immediately; see
+ * {@link buildOnlyDb}). Every query is inlined and sent as one round trip:
+ * the Postgres function runs them in order inside a single plpgsql call,
+ * which is itself an implicit transaction, so a failure on any statement
+ * rolls back every statement before it.
  *
- * @param db The already-resolved `db` config.
+ * @param supabase The `db.supabase` config block.
  * @param bearerToken The anon key or user JWT.
  * @param build Returns the queries to run, via `.toSQL()` — never executes them directly.
  * @returns One result per query, in the same order as `build`'s array.
+ * @throws If `db.supabase.rawSql` is `false` — `cfni_exec_batch` needs `cfni_exec`, which is disabled too.
  */
-async function requireSupabaseTransactionMode(db) {
-    const resolved = await resolveDbMode(db);
-    if (resolved.mode !== 'supabase') {
-        throw new Error('db: withUserTransaction/withPublicTransaction only run their Supabase-mode batch path ' +
-            'right now. In connection-string mode, use withUserDb/withPublicDb\'s own `.transaction()` ' +
-            '— it already provides real atomicity there.');
-    }
-    const supabase = resolved.supabase;
+async function runTransaction(supabase, bearerToken, build) {
     if (supabase.rawSql === false) {
-        throw new Error('db: withUserTransaction/withPublicTransaction need `cfni_exec_batch`, which runs through ' +
-            '`cfni_exec` — both are unavailable while `db.supabase.rawSql` is `false`. Install ' +
-            'cfni_exec.sql and drop `rawSql: false`, or use `db.connectionString` for a direct ' +
-            'Postgres connection instead.');
+        throw new Error('db: transaction() needs `cfni_exec_batch`, which runs through `cfni_exec` — both are ' +
+            'unavailable while `db.supabase.rawSql` is `false`. Install cfni_exec.sql and drop ' +
+            '`rawSql: false`, or use `db.connectionString` for a direct Postgres connection instead.');
     }
-    return supabase;
-}
-async function runTransaction(supabase, bearerToken, build) {
     const queries = await build(buildOnlyDb());
     const batchQueries = queries.map((query) => ({ sql: query.sql, params: query.params }));
     return runTransactionBatch(supabase, bearerToken, batchQueries);
 }
-/**
- * Runs several statements atomically as the **anonymous** role.
- *
- * See {@link runTransaction} for the batching mechanism. `build` must not
- * execute its queries — return their `.toSQL()` form instead.
- *
- * @param build Returns the queries to run, in order.
- * @returns One `{rows, rowCount}` result per query, in the same order.
- * @throws If `db` is not set, if this isn't Supabase mode (connection-string
- * mode already has real transactions via `withPublicDb`), or if any
- * statement in the batch fails — the whole batch is then rolled back.
- *
- * @example
- * const [inserted] = await withPublicTransaction((db) => [
- *     db.insert(logEntries).values({ event: 'visit' }).toSQL(),
- * ]);
- */
-export async function withPublicTransaction(build) {
-    const db = config.db;
-    requireDbConfig(db);
-    const supabase = await requireSupabaseTransactionMode(db);
-    const { anonKey } = await resolveSupabaseEndpoint(supabase);
-    return runTransaction(supabase, anonKey, build);
-}
-/**
- * Runs several statements atomically as the **signed-in user**.
- *
- * See {@link runTransaction} for the batching mechanism and
- * {@link withUserDb} for how the caller's identity is resolved. In Supabase
- * mode this is the wrapper to reach for whenever a user-owned write needs
- * more than one statement to succeed or fail together — `withUserDb` alone
- * cannot provide that there.
- *
- * @param build Returns the queries to run, in order. Do not execute them —
- * call `.toSQL()` on each and return the array.
- * @returns One `{rows, rowCount}` result per query, in the same order.
- * @throws If `db` is not set, if no access token can be resolved, if this
- * isn't Supabase mode, or if any statement in the batch fails — the whole
- * batch is then rolled back.
- *
- * @example
- * const [invitation] = await withUserTransaction((db) => [
- *     db.insert(invitations).values({ email }).returning().toSQL(),
- * ]);
- */
-export async function withUserTransaction(build) {
-    const db = config.db;
-    requireDbConfig(db);
-    const supabase = await requireSupabaseTransactionMode(db);
-    const token = await resolveAccessToken(config);
-    return runTransaction(supabase, token, build);
-}

package/dist/src/db/helpers.d.ts

@@ -37,8 +37,12 @@ export declare function excluded<T extends Table>(table: T): {
  */
 export declare function onConflictSet<T extends Table, K extends keyof T["_"]["columns"]>(table: T, fields: K[]): Record<string, SQL>;
 export type TimeUnit = "days" | "hours" | "minutes" | "months" | "years" | "weeks";
+/** General SQL helper returning `now()`. */
+export declare function now(): SQL;
 /** General SQL helper generating a timestamp expression relative to now (`now() - (N unit)::interval`). */
 export declare function ago(amount: number, unit: TimeUnit): SQL;
+/** General SQL helper generating a timestamp expression ahead of now (`now() + (N unit)::interval`). */
+export declare function fromNow(amount: number, unit: TimeUnit): SQL;
 /** General SQL helper returning `current_date`. */
 export declare function currentDate(): SQL;
 /** General SQL helper for window function `count(*) over ()`. */

package/dist/src/db/helpers.js

@@ -66,10 +66,18 @@ export function onConflictSet(table, fields) {
     }
     return setObj;
 }
+/** General SQL helper returning `now()`. */
+export function now() {
+    return sql `now()`;
+}
 /** General SQL helper generating a timestamp expression relative to now (`now() - (N unit)::interval`). */
 export function ago(amount, unit) {
     return sql `now() - (${amount} || ' ' || ${unit})::interval`;
 }
+/** General SQL helper generating a timestamp expression ahead of now (`now() + (N unit)::interval`). */
+export function fromNow(amount, unit) {
+    return sql `now() + (${amount} || ' ' || ${unit})::interval`;
+}
 /** General SQL helper returning `current_date`. */
 export function currentDate() {
     return sql `current_date`;

package/dist/src/db/index.d.ts

@@ -7,10 +7,17 @@
  * - {@link withPublicDb} — anonymous role, for data any visitor may read.
  * - {@link withUserDb} — the signed-in user, with RLS applied to their id.
  *
- * Need more than one statement to succeed or fail together?
- * - {@link withPublicTransaction} / {@link withUserTransaction} — build
- *   queries with `.toSQL()` instead of executing them; every statement then
- *   runs atomically, whichever transport mode is active.
+ * Need more than one statement to succeed or fail together? Call
+ * `db.transaction(...)` on the handle either wrapper hands your callback —
+ * same method name in both transport modes. In connection-string mode it is
+ * a real Drizzle transaction: `db.transaction(async (tx) => { await
+ * tx.insert(...); await tx.update(...); })`, and a later statement may use an
+ * earlier one's result. In Supabase mode there is no session to run that
+ * over, so the callback instead *builds* queries and returns them —
+ * `db.transaction((tx) => [tx.insert(...).values(...).toSQL(), tx.update(...).toSQL()])`
+ * — call `.toSQL()` on each instead of `await`ing it; every statement then
+ * runs atomically as one `cfni_exec_batch` call, but a later statement cannot
+ * read an earlier one's result there.
  *
  * Two transports reach Postgres behind that same Drizzle query API, chosen by
  * `resolveDbMode` from which `db` config fields are set: `connectionString`
@@ -23,14 +30,13 @@
  * statement is first translated into `@supabase/supabase-js` `.from()` calls;
  * anything PostgREST cannot express falls back to `cfni_exec`, and if
  * `db.supabase.rawSql` is `false` the call throws naming the construct that
- * needs raw SQL. `withPublicDb`/`withUserDb`'s `.transaction()` is never
- * available in Supabase mode — reach for `withPublicTransaction`/
- * `withUserTransaction` there instead.
+ * needs raw SQL — including `.transaction()`, which needs `cfni_exec_batch`
+ * from the same file.
  *
  * Generic Drizzle SQL helpers (`excluded`, `onConflictSet`, `ago`, …) live in
  * the separate `cloudflare-next-intl/dbHelpers` entry point.
  */
-export { withPublicDb, withUserDb, withPublicTransaction, withUserTransaction } from './context';
+export { withPublicDb, withUserDb } from './context';
 export type { DrizzleDb, TransactionResult } from './context';
 export { default as connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';
 export type { DbRoutingConfig } from '../types/types';

package/dist/src/db/index.js

@@ -7,10 +7,17 @@
  * - {@link withPublicDb} — anonymous role, for data any visitor may read.
  * - {@link withUserDb} — the signed-in user, with RLS applied to their id.
  *
- * Need more than one statement to succeed or fail together?
- * - {@link withPublicTransaction} / {@link withUserTransaction} — build
- *   queries with `.toSQL()` instead of executing them; every statement then
- *   runs atomically, whichever transport mode is active.
+ * Need more than one statement to succeed or fail together? Call
+ * `db.transaction(...)` on the handle either wrapper hands your callback —
+ * same method name in both transport modes. In connection-string mode it is
+ * a real Drizzle transaction: `db.transaction(async (tx) => { await
+ * tx.insert(...); await tx.update(...); })`, and a later statement may use an
+ * earlier one's result. In Supabase mode there is no session to run that
+ * over, so the callback instead *builds* queries and returns them —
+ * `db.transaction((tx) => [tx.insert(...).values(...).toSQL(), tx.update(...).toSQL()])`
+ * — call `.toSQL()` on each instead of `await`ing it; every statement then
+ * runs atomically as one `cfni_exec_batch` call, but a later statement cannot
+ * read an earlier one's result there.
  *
  * Two transports reach Postgres behind that same Drizzle query API, chosen by
  * `resolveDbMode` from which `db` config fields are set: `connectionString`
@@ -23,12 +30,11 @@
  * statement is first translated into `@supabase/supabase-js` `.from()` calls;
  * anything PostgREST cannot express falls back to `cfni_exec`, and if
  * `db.supabase.rawSql` is `false` the call throws naming the construct that
- * needs raw SQL. `withPublicDb`/`withUserDb`'s `.transaction()` is never
- * available in Supabase mode — reach for `withPublicTransaction`/
- * `withUserTransaction` there instead.
+ * needs raw SQL — including `.transaction()`, which needs `cfni_exec_batch`
+ * from the same file.
  *
  * Generic Drizzle SQL helpers (`excluded`, `onConflictSet`, `ago`, …) live in
  * the separate `cloudflare-next-intl/dbHelpers` entry point.
  */
-export { withPublicDb, withUserDb, withPublicTransaction, withUserTransaction } from './context';
+export { withPublicDb, withUserDb } from './context';
 export { default as connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';

package/dist/src/db/transaction_batch.d.ts

@@ -20,8 +20,8 @@ export interface BatchQuery {
  *
  * @param supabase The `db.supabase` config block.
  * @param bearerToken Token resolved as the caller's identity — the anon key
- * for {@link ../context.withPublicTransaction}, a user JWT for
- * {@link ../context.withUserTransaction}.
+ * for `withPublicDb`'s handle, a user JWT for `withUserDb`'s — see
+ * `context.ts`'s `runTransaction`, which backs both handles' `.transaction()`.
  * @param queries The statements to run, in order. An empty array is a no-op
  * that still makes the round trip, matching `cfni_exec_batch(array[]::text[])`.
  * @returns One `{rows, rowCount}` result per query, in the same order.

package/dist/src/db/transaction_batch.js

@@ -23,8 +23,8 @@ const BATCH_FUNCTION = 'cfni_exec_batch';
  *
  * @param supabase The `db.supabase` config block.
  * @param bearerToken Token resolved as the caller's identity — the anon key
- * for {@link ../context.withPublicTransaction}, a user JWT for
- * {@link ../context.withUserTransaction}.
+ * for `withPublicDb`'s handle, a user JWT for `withUserDb`'s — see
+ * `context.ts`'s `runTransaction`, which backs both handles' `.transaction()`.
  * @param queries The statements to run, in order. An empty array is a no-op
  * that still makes the round trip, matching `cfni_exec_batch(array[]::text[])`.
  * @returns One `{rows, rowCount}` result per query, in the same order.

package/dist/src/types/types.d.ts

@@ -862,11 +862,11 @@ export interface SupabaseDbConfig {
      * aggregates, CTEs, transactions — naming the construct that needs raw
      * SQL. Defaults to `true`.
      *
-     * Also gates `withUserTransaction`/`withPublicTransaction`: their
-     * `cfni_exec_batch` function ships in the same `supabase/cfni_exec.sql`
-     * file and needs `cfni_exec` itself to run each statement, so batching
-     * is on whenever this is (there is no separate flag for it) and throws
-     * the same install-or-use-`connectionString` error when this is `false`.
+     * Also gates Supabase-mode `db.transaction(...)`: its `cfni_exec_batch`
+     * function ships in the same `supabase/cfni_exec.sql` file and needs
+     * `cfni_exec` itself to run each statement, so batching is on whenever
+     * this is (there is no separate flag for it) and throws the same
+     * install-or-use-`connectionString` error when this is `false`.
      */
     rawSql?: boolean;
 }
@@ -916,9 +916,12 @@ export interface DbRoutingConfig {
      * live traffic. Requires the `cfni_exec` function from
      * `supabase/cfni_exec.sql` to be installed in your database.
      *
-     * No multi-statement transactions: unlike connection-string mode, each
-     * statement inside a `withUserDb` callback is its own round-trip. Do not
-     * rely on multi-statement atomicity in this mode.
+     * Each statement inside a plain `withUserDb` callback is its own
+     * round-trip — no shared session. Call `.transaction(...)` on the handle
+     * for atomicity across statements instead: it batches them into one
+     * `cfni_exec_batch` call, though (unlike connection-string mode) a later
+     * statement in the callback cannot read an earlier one's result — see
+     * the `db` entry point's module doc.
      */
     supabase?: SupabaseDbConfig;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cloudflare-next-intl",
-	"version": "0.8.14",
+	"version": "0.8.16",
 	"description": "Optimized Next Intl Package Special for App Router and Cloudflare",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",