cloudflare-next-intl 0.8.23 → 0.8.24

package/README.md

@@ -461,23 +461,21 @@ export default setIntlConfig({
   returning one (resolved on each connect). The function form is how you reach
   a value that isn't available at module scope — a Cloudflare Hyperdrive
   binding, or a secret store — as in the example above.
-- `disconnectAfterRequest` — whether the pooled client is closed once the
-  last in-flight `withPublicDb`/`withUserDb` call of the request
-  finishes. Defaults to `true` (one connection per request, released to
-  Hyperdrive immediately). Set `false` to keep the connection open for the
-  lifetime of the isolate — faster for a long-lived server, but it holds a
-  Hyperdrive connection slot between requests.
-- `authenticatedRole` — Postgres role `withUserDb` switches the shared
-  session to for the duration of your callback (`set role`, reset once it
-  settles — no transaction involved). Defaults to `'authenticated'` (the
-  Supabase RLS convention).
+- `disconnectAfterRequest` — **deprecated, ignored since 0.8.23.** Every
+  `withPublicDb`/`withUserDb` call now opens and closes its own client, so
+  there is no surviving connection to keep open. Hyperdrive pools the
+  server-side connection.
+- `authenticatedRole` — Postgres role `withUserDb` switches its
+  call-scoped session to for the duration of your callback (`set role`, no
+  transaction involved; the session is closed when the call ends). Defaults
+  to `'authenticated'` (the Supabase RLS convention).
 - `getUserId` — resolves the user id injected as
   `request.jwt.claims->>'sub'` inside `withUserDb`. Omit when
   `firebaseAuth` is configured — the uid then comes from this package's own
   `getAuthUser()` automatically. Provide it to use a different auth source
   (or when `firebaseAuth` is absent).
-- `disconnectTimeoutMs` — milliseconds `disconnectPostgres` waits for
-  `client.end()` before giving up. Defaults to `2000`.
+- `disconnectTimeoutMs` — **deprecated, ignored since 0.8.23.** Client
+  teardown is awaited or deferred to `ctx.waitUntil` without a timeout.
 
 #### Choosing a transport
 

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

@@ -1,13 +1,39 @@
-import { Client } from 'pg';
+import type { Client } from 'pg';
 import type { LocalePrefixMode, Locales, RoutingConfig } from '../types/types';
 export type DbConfig = RoutingConfig<Locales, LocalePrefixMode>;
 /**
- * ✅ ONE CLIENT PER QUERY & GUARANTEED DISCONNECT:
- * This single wrapper correctly leverages Cloudflare Hyperdrive by connecting securely,
- * running your logic safely in total isolation, and immediately releasing the socket.
+ * Runs `queryFn` on a Postgres client scoped to this single call: one
+ * `connect()`, your callback, then a guaranteed `end()`. Each call gets its own
+ * client, so concurrent renders in the same isolate can never share session
+ * state (role, `request.jwt.claims`, an open transaction) with each other.
+ * Hyperdrive pools the server-side connection behind this.
  */
 export declare function withDbClient<T>(config: DbConfig, queryFn: (client: Client) => Promise<T>): Promise<T>;
+/**
+ * No-op kept for backward compatibility. There is no cached connection state
+ * to reset now that every {@link withDbClient} call owns its client.
+ *
+ * @deprecated Connection state is per-call; this does nothing.
+ */
 export declare function resetConnectionState(): void;
+/**
+ * Runs `fn` directly. Kept for backward compatibility: session state can no
+ * longer leak between callers, so there is nothing left to serialize.
+ *
+ * @deprecated Clients are per-call now; no lock is needed.
+ */
 export declare function withSessionLock<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * Opens a Postgres client the caller owns and must close with
+ * {@link disconnectPostgres}. Prefer {@link withDbClient}, which closes the
+ * client for you even when the callback throws.
+ *
+ * @deprecated Use {@link withDbClient} instead.
+ */
 export declare function connectToPostgres(config: DbConfig): Promise<Client>;
-export declare function disconnectPostgres(config: DbConfig): void;
+/**
+ * Closes a client from {@link connectToPostgres}.
+ *
+ * @deprecated Use {@link withDbClient} instead.
+ */
+export declare function disconnectPostgres(client?: Client): Promise<void>;

package/dist/src/db/connection.js

@@ -1,9 +1,16 @@
-import { Client } from 'pg';
 import reportError from '../error_handling/report_error';
 import requireDbConfig from './require_config';
 import resolveConfigValue from './resolve_config_value';
-// Removed Global Singletons (no `client`, `connectionString`, `activeUsers`, `connectionPromise`)
-// Removed Custom Locks (no `serializeQueries`, no `sessionLock`)
+let pgModule;
+/**
+ * Loads `pg` lazily, so an app that never touches the Postgres transport never
+ * bundles it, and caches the module promise so concurrent callers share one
+ * resolution instead of racing separate `import()` calls.
+ */
+function loadPg() {
+    pgModule ?? (pgModule = import('pg'));
+    return pgModule;
+}
 async function resolveConnectionString(db) {
     const configured = await resolveConfigValue(db.connectionString);
     if (configured)
@@ -13,70 +20,99 @@ async function resolveConnectionString(db) {
         'Hyperdrive binding off `getCloudflareContext().env`).');
 }
 /**
- * ✅ ONE CLIENT PER QUERY & GUARANTEED DISCONNECT:
- * This single wrapper correctly leverages Cloudflare Hyperdrive by connecting securely,
- * running your logic safely in total isolation, and immediately releasing the socket.
+ * Runs `queryFn` on a Postgres client scoped to this single call: one
+ * `connect()`, your callback, then a guaranteed `end()`. Each call gets its own
+ * client, so concurrent renders in the same isolate can never share session
+ * state (role, `request.jwt.claims`, an open transaction) with each other.
+ * Hyperdrive pools the server-side connection behind this.
  */
 export async function withDbClient(config, queryFn) {
     const db = config.db;
     requireDbConfig(db);
     const connectionString = await resolveConnectionString(db);
-    // Creates an independent, stateless Client so concurrent Next.js renders don't lock each other up.
-    const client = new Client({ connectionString });
+    const { Client: PgClient } = await loadPg();
+    const client = new PgClient({ connectionString });
     let result;
+    let connected = false;
     try {
-        await client.connect();
-        // Pass this client independently straight into your callback to be executed
-        result = await queryFn(client);
-    }
-    catch (error) {
-        // Silently swallow Hyperdrive pool termination warnings that are passive/natural
-        const message = error?.message || '';
-        if (!/(connection terminated|connection closed|socket closed|unexpected eof)/i.test(message)) {
-            void reportError({ errorHandling: config.errorHandling, generate: config.generate }, { error, classOrMethodName: 'db.withDbClient.clientError' });
+        try {
+            await client.connect();
+            connected = true;
         }
-        throw error;
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error ?? '');
+            if (!/(connection terminated|connection closed|socket closed|unexpected eof)/i.test(message)) {
+                void reportError({ errorHandling: config.errorHandling, generate: config.generate }, { error, classOrMethodName: 'db.withDbClient.connectError' });
+            }
+            throw error;
+        }
+        result = await queryFn(client);
     }
     finally {
-        // GUARANTEED TEAR-DOWN
-        // Triggers `.end()` right when your data has finished being processed.
-        const endPromise = client.end();
+        const endPromise = connected ? client.end() : Promise.resolve();
         const getContext = config.generate?.getCloudflareContext;
         if (!getContext || db.disconnectAfterRequest === false) {
-            await endPromise.catch(() => { });
+            await endPromise.catch(() => undefined);
         }
         else {
             try {
                 const context = await getContext({ async: true });
                 if (typeof context?.ctx?.waitUntil === 'function') {
-                    context.ctx.waitUntil(endPromise.catch(() => { }));
+                    context.ctx.waitUntil(endPromise.catch(() => undefined));
                 }
                 else {
-                    await endPromise.catch(() => { });
+                    await endPromise.catch(() => undefined);
                 }
             }
             catch {
-                await endPromise.catch(() => { });
+                await endPromise.catch(() => undefined);
             }
         }
     }
     return result;
 }
-// -------------------------------------------------------------
-// ⚠️ STUBS TO CATCH OUTDATED USAGES ACROSS YOUR REPOSITORY ⚠️
-// I've kept these named exports intact so your IDE will flag 
-// where they exist so you know exactly what code to update next.
-// -------------------------------------------------------------
+/**
+ * No-op kept for backward compatibility. There is no cached connection state
+ * to reset now that every {@link withDbClient} call owns its client.
+ *
+ * @deprecated Connection state is per-call; this does nothing.
+ */
 export function resetConnectionState() {
-    // Obsolete - ignored
+    // no cached state to reset
 }
+/**
+ * Runs `fn` directly. Kept for backward compatibility: session state can no
+ * longer leak between callers, so there is nothing left to serialize.
+ *
+ * @deprecated Clients are per-call now; no lock is needed.
+ */
 export async function withSessionLock(fn) {
-    // Locks are no longer needed as clients are entirely isolated
     return await fn();
 }
+/**
+ * Opens a Postgres client the caller owns and must close with
+ * {@link disconnectPostgres}. Prefer {@link withDbClient}, which closes the
+ * client for you even when the callback throws.
+ *
+ * @deprecated Use {@link withDbClient} instead.
+ */
 export async function connectToPostgres(config) {
-    throw new Error('CRITICAL REFACTOR: Replace `connectToPostgres` with `withDbClient(config, async (client) => { ... })` for Cloudflare Hyperdrive.');
+    const db = config.db;
+    requireDbConfig(db);
+    const connectionString = await resolveConnectionString(db);
+    const { Client: PgClient } = await loadPg();
+    const client = new PgClient({ connectionString });
+    client.on('error', (error) => {
+        void reportError({ errorHandling: config.errorHandling, generate: config.generate }, { error, classOrMethodName: 'db.connectToPostgres.clientError' });
+    });
+    await client.connect();
+    return client;
 }
-export function disconnectPostgres(config) {
-    // Obsolete - disconnected natively in withDbClient now.
+/**
+ * Closes a client from {@link connectToPostgres}.
+ *
+ * @deprecated Use {@link withDbClient} instead.
+ */
+export async function disconnectPostgres(client) {
+    await client?.end().catch(() => undefined);
 }

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

@@ -15,15 +15,11 @@ export type DrizzleDb = NodePgDatabase<Record<string, never>>;
  */
 export declare function withPublicDb<T>(fn: (db: DrizzleDb) => Promise<T>): Promise<T>;
 /**
- * Runs a query as the **signed-in user**.
+ * Runs a query as the **signed-in user**, with `request.jwt.claims` and the
+ * authenticated role set on the session so RLS policies apply to their id.
  *
- * ✨ Uses Isolated Hyperdrive Networking Strategy: Overlapping connection problems
- * across Next.js isolate contexts previously occurred due to locking constraints on the identical
- * PostgreSQL singleton reference inside Serverless architecture.
- *
- * Moving directly to edge single-usage wrappers inherently closes all leakage scenarios because
- * `.connect() -> setup Roles & Session variables -> process logic -> .end()` exists per connection completely
- * unshared across external requests globally.
+ * The session lives on a client scoped to this call and closed when it ends,
+ * so the role and claims can never be observed by another caller.
  *
  * @param fn Receives the Drizzle handle
  * @param uid Overrides the user ID for authenticated calls

package/dist/src/db/context.js

@@ -1,6 +1,6 @@
 import config from '../config/intl_config';
 import requireDbConfig from './require_config';
-import { withDbClient } from './connection'; // ✨ REPLACED connection hooks
+import { withDbClient } from './connection';
 import resolveDbMode from './resolve_mode';
 import resolveSupabaseEndpoint from './supabase_config';
 import createSupabaseTransport from './supabase_transport';
@@ -73,9 +73,8 @@ async function postgresDb(drizzleHandle, rawClient) {
  * via an inline-parameterised `query()` call, wrapped in a real
  * `BEGIN`/`COMMIT` for atomicity, and returns `ExecResult[]`.
  *
- * ✨ Note: In the Edge context, atomicity natively holds fast!
- * Every parallel query has isolated clients supplied from `withDbClient`.
- * You don't have to lock this transaction block as overlapping sessions are eliminated entirely.
+ * The client is scoped to one `withDbClient` call, so no other caller can
+ * interleave statements into this transaction.
  */
 async function runPostgresTransaction(rawClient, build) {
     const queries = await build(buildOnlyDb());
@@ -91,7 +90,7 @@ async function runPostgresTransaction(rawClient, build) {
         return results;
     }
     catch (error) {
-        await rawClient.query('rollback').catch(() => { });
+        await rawClient.query('rollback').catch(() => undefined);
         throw error;
     }
 }
@@ -128,26 +127,19 @@ export async function withPublicDb(fn) {
         const { anonKey } = await resolveSupabaseEndpoint(resolved.supabase);
         return fn(await supabaseDb(resolved.supabase, anonKey));
     }
-    // ✨ Uses isolated clients. Clean setup internally handles 
-    // tear-down (`disconnectPostgres`) magically behind the scenes right on completion
     return await withDbClient(config, async (client) => {
         const { drizzle } = await import('drizzle-orm/node-postgres');
         const drizzleHandle = drizzle(client);
-        // Execute Drizzle proxy payload natively
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         return await fn(await postgresDb(drizzleHandle, client));
     });
 }
 /**
- * Runs a query as the **signed-in user**.
+ * Runs a query as the **signed-in user**, with `request.jwt.claims` and the
+ * authenticated role set on the session so RLS policies apply to their id.
  *
- * ✨ Uses Isolated Hyperdrive Networking Strategy: Overlapping connection problems
- * across Next.js isolate contexts previously occurred due to locking constraints on the identical
- * PostgreSQL singleton reference inside Serverless architecture.
- *
- * Moving directly to edge single-usage wrappers inherently closes all leakage scenarios because
- * `.connect() -> setup Roles & Session variables -> process logic -> .end()` exists per connection completely
- * unshared across external requests globally.
+ * The session lives on a client scoped to this call and closed when it ends,
+ * so the role and claims can never be observed by another caller.
  *
  * @param fn Receives the Drizzle handle
  * @param uid Overrides the user ID for authenticated calls
@@ -162,23 +154,13 @@ export async function withUserDb(fn, uid) {
     }
     const userId = await resolveUserId(uid);
     const role = db.authenticatedRole ?? DEFAULT_ROLE;
-    // ✨ Completely isolated setup per-render utilizing `.withDbClient()` Native block 
-    // Eliminates requiring our application `withSessionLock` since NextJS workers do not leak! 
     return await withDbClient(config, async (client) => {
         const rawClient = client;
         await rawClient.query(`select set_config('request.jwt.claims', $1, false)`, [JSON.stringify({ sub: userId })]);
         await rawClient.query(`set role "${role}"`);
         const { drizzle } = await import('drizzle-orm/node-postgres');
         const drizzleHandle = drizzle(client);
-        try {
-            return await fn(await postgresDb(drizzleHandle, rawClient));
-        }
-        finally {
-            // Because Hyperdrive is going to actively obliterate (`.end()`) 
-            // the connection upon scope exiting returning connection priorities automatically back up to cloudflare.
-            // Resetting is theoretically optional in stateless Cloudflare execution - but is provided as good habit/health standard here.
-            await rawClient.query('reset role').catch(() => { });
-        }
+        return await fn(await postgresDb(drizzleHandle, rawClient));
     });
 }
 /**

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

@@ -38,5 +38,5 @@
  */
 export { withPublicDb, withUserDb } from './context';
 export type { DrizzleDb, TransactionResult } from './context';
-export { connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';
+export { withDbClient, connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';
 export type { DbRoutingConfig } from '../types/types';

package/dist/src/db/index.js

@@ -37,4 +37,4 @@
  * the separate `cloudflare-next-intl/dbHelpers` entry point.
  */
 export { withPublicDb, withUserDb } from './context';
-export { connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';
+export { withDbClient, connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';

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

@@ -884,10 +884,12 @@ export interface DbRoutingConfig {
     /**
      * Whether the pooled client is closed once the last in-flight
      * `withPublicDb`/`withUserDb` call of the request finishes.
-     * Defaults to `true` (one connection per request, released to Hyperdrive
-     * immediately). Set `false` to keep the connection open for the lifetime
-     * of the isolate — faster for a long-lived server, but it holds a
-     * Hyperdrive connection slot between requests.
+     *
+     * @deprecated Ignored since 0.8.23. Every `withPublicDb`/`withUserDb` call
+     * now opens and closes its own client, so no connection survives a call to
+     * be kept open. `true` and `false` behave identically; the only difference
+     * is that `false` awaits the close instead of deferring it to
+     * `ctx.waitUntil`. Hyperdrive pools the server-side connection.
      */
     disconnectAfterRequest?: boolean;
     /**
@@ -902,7 +904,12 @@ export interface DbRoutingConfig {
      * to use a different auth source (or when `firebaseAuth` is absent).
      */
     getUserId?: () => Promise<string | null> | string | null;
-    /** Milliseconds `disconnectPostgres` waits for `client.end()` before giving up. Defaults to `2000`. */
+    /**
+     * Milliseconds `disconnectPostgres` waits for `client.end()` before giving up.
+     *
+     * @deprecated Ignored since 0.8.23. Client teardown is awaited or deferred
+     * to `ctx.waitUntil` without a timeout.
+     */
     disconnectTimeoutMs?: number;
     /**
      * Reaches Postgres through the Supabase Data API instead of a direct

package/llms.txt

@@ -53,11 +53,11 @@ Two transports, picked by which `db` fields are set — `pg`/`drizzle-orm`/`@sup
 
 - Direct Postgres (wins if configured): `db.connectionString` — Postgres connection string, or a sync/async function returning one (resolved on each connect). The function form is the way to read a value unavailable at module scope, e.g. a Cloudflare Hyperdrive binding: `connectionString: async () => (await getCloudflareContext({ async: true })).env.HYPERDRIVE.connectionString`. There is no separate `hyperdriveBinding` option.
 - Supabase Data API (used only when neither of the above is set): `db.supabase` — `{ url?, anonKey?, execFunction?, rawSql? }` where `url`/`anonKey` each accept a string or a sync/async function returning one, defaulting `url`/`anonKey` to `NEXT_PUBLIC_SUPABASE_URL`/`NEXT_PUBLIC_SUPABASE_ANON_KEY`. Statements are translated to PostgREST REST calls first; unsupported statements fall back to `supabase/cfni_exec.sql` (a `security invoker` SQL-exec function) in your database — `cfni-db-codegen`/`cfni-db-install-exec` can install it for you (see below). No multi-statement transactions — each statement in a `withUserDb` callback is its own round-trip; `.transaction()` throws instead of running non-atomically. `rawSql: false` disables `cfni_exec` fallback, throwing an informative error when a query cannot be served over REST.
-- `db.disconnectAfterRequest` — direct-Postgres mode only: closes the pooled client once the last in-flight `withPublicDb`/`withUserDb` call of the request finishes. Defaults to `true`; set `false` to keep the connection open for the isolate's lifetime (holds a Hyperdrive slot between requests).
+- `db.disconnectAfterRequest` — deprecated, ignored since 0.8.23. Each `withPublicDb`/`withUserDb` call opens and closes its own client; Hyperdrive pools the server-side connection.
 - `db.authenticatedRole` — direct-Postgres mode only: Postgres role assumed inside `withUserDb`'s transaction. Defaults to `'authenticated'` (Supabase RLS convention).
 - `db.getUserId` — direct-Postgres mode only: resolves the user id injected as `request.jwt.claims->>'sub'` in `withUserDb`. Omit when `firebaseAuth` is configured — the uid is then taken automatically from the signed-in Firebase user via this package's own `getAuthUser()`.
 - `db.getAccessToken` — Supabase mode only: resolves the JWT sent as `Authorization: Bearer` in `withUserDb`, which is what makes PostgREST resolve `authenticated` and apply RLS. Omit when `firebaseAuth` is configured — the signed-in user's Firebase ID token is used automatically.
-- `db.disconnectTimeoutMs` — direct-Postgres mode only: ms `disconnectPostgres` waits for `client.end()` before giving up. Defaults to `2000`.
+- `db.disconnectTimeoutMs` — deprecated, ignored since 0.8.23. Teardown is awaited or deferred to `ctx.waitUntil` without a timeout.
 - `withPublicDb(fn)` — anonymous role. Direct-Postgres mode: the request's pooled connection, no transaction, no role switch. Supabase mode: the anon key as the PostgREST bearer token. Either way, no user id is attached — RLS keyed on `auth.jwt()` denies access.
 - `withUserDb(fn, uid?)` — signed-in-user role. Direct-Postgres mode: a transaction with `set_config('request.jwt.claims', ...)` + `set local role`, `uid` resolution order explicit arg → `db.getUserId()` → Firebase auth uid → throws. Supabase mode: identity rides on the JWT from `db.getAccessToken`/Firebase instead (`uid` param is ignored), no transaction wraps the call.
 - `./dbHelpers` functions are plain Drizzle `sql`-building utilities with no config dependency — usable standalone.

package/package.json

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