cloudflare-next-intl 0.8.13 → 0.8.14

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

@@ -21,11 +21,15 @@ export declare function resetConnectionState(): void;
  * `disconnectPostgres` call, or the connection is never released.
  *
  * @param config Your routing config; `config.db` must be set.
+ * @param resolved A connection string already resolved by the caller (e.g.
+ * `resolveDbMode`, which has to call `db.connectionString` itself to decide
+ * the transport) — pass it to skip resolving `db.connectionString` a second
+ * time. Omit it to have this function resolve it itself, as before.
  * @returns The connected, shared client.
  * @throws If `db` is not set, or no connection string can be resolved from
  * `db.connectionString`.
  */
-export default function connectToPostgres(config: DbConfig): Promise<Client>;
+export default function connectToPostgres(config: DbConfig, resolved?: string | undefined): Promise<Client>;
 /**
  * Releases one caller's hold on the shared client, closing it once the last
  * holder of the request is done. Call it exactly once per

package/dist/src/db/connection.js

@@ -64,18 +64,22 @@ function serializeQueries(raw) {
  * `disconnectPostgres` call, or the connection is never released.
  *
  * @param config Your routing config; `config.db` must be set.
+ * @param resolved A connection string already resolved by the caller (e.g.
+ * `resolveDbMode`, which has to call `db.connectionString` itself to decide
+ * the transport) — pass it to skip resolving `db.connectionString` a second
+ * time. Omit it to have this function resolve it itself, as before.
  * @returns The connected, shared client.
  * @throws If `db` is not set, or no connection string can be resolved from
  * `db.connectionString`.
  */
-export default async function connectToPostgres(config) {
+export default async function connectToPostgres(config, resolved) {
     const db = config.db;
     requireDbConfig(db);
     await disconnectionPromise;
     if (connectingPromise === null) {
         connectingPromise = (async () => {
             try {
-                connectionString ?? (connectionString = await resolveConnectionString(db));
+                connectionString ?? (connectionString = resolved ?? await resolveConnectionString(db));
                 const { Client } = await import('pg');
                 const created = serializeQueries(new Client({ connectionString }));
                 client = created;

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

@@ -44,11 +44,14 @@ export declare function withPublicDb<T>(fn: (db: DrizzleDb) => Promise<T>): Prom
  * @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.
- * @param uid Connection-string mode only: overrides the user id. Omit it in
- * normal use — the id then comes from `db.getUserId()` when set, otherwise
- * from the signed-in Firebase user when `firebaseAuth` is configured.
- * Ignored in Supabase mode, which resolves identity via `db.getAccessToken`/
- * Firebase instead — see {@link resolveAccessToken}.
+ * @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
+ * `firebaseAuth` is configured. `null` is accepted alongside `undefined` so a
+ * caller's own lookup (which may itself come back empty) can be passed
+ * straight through without an extra check. Ignored in Supabase mode, which
+ * resolves identity via `db.getAccessToken`/Firebase instead — see
+ * {@link resolveAccessToken}.
  * @returns Whatever `fn` resolves to.
  * @throws If `db` is not set on your `RoutingConfig`, if no user id/access
  * token can be resolved, or the connection fails.
@@ -56,7 +59,7 @@ export declare function withPublicDb<T>(fn: (db: DrizzleDb) => Promise<T>): Prom
  * @example
  * const mine = await withUserDb((db) => db.select().from(orders));
  */
-export declare function withUserDb<T>(fn: (db: DrizzleDb) => Promise<T>, uid?: string): Promise<T>;
+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. */
 export type { ExecResult as TransactionResult } from './supabase_transport';
 /**

package/dist/src/db/context.js

@@ -9,7 +9,9 @@ import runTransactionBatch from './transaction_batch';
 const DEFAULT_ROLE = 'authenticated';
 /**
  * Resolves the user id for `withUserDb`, trying, in order: the explicit `uid`
- * argument, `db.getUserId()`, then the signed-in Firebase user.
+ * argument, `db.getUserId()`, then the signed-in Firebase user. `uid` may be
+ * `null` (as well as omitted) to mean "skip this source, try the next one" —
+ * useful when the caller's own uid lookup can itself come back empty.
  */
 async function resolveUserId(uid) {
     if (uid)
@@ -86,12 +88,12 @@ function buildOnlyDb() {
 export async function withPublicDb(fn) {
     const db = config.db;
     requireDbConfig(db);
-    if (resolveDbMode(db) === 'supabase') {
-        const supabase = db.supabase;
-        const { anonKey } = await resolveSupabaseEndpoint(supabase);
-        return fn(await supabaseDb(supabase, anonKey));
+    const resolved = await resolveDbMode(db);
+    if (resolved.mode === 'supabase') {
+        const { anonKey } = await resolveSupabaseEndpoint(resolved.supabase);
+        return fn(await supabaseDb(resolved.supabase, anonKey));
     }
-    const client = await connectToPostgres(config);
+    const client = await connectToPostgres(config, resolved.connectionString);
     try {
         const { drizzle } = await import('drizzle-orm/node-postgres');
         return await fn(drizzle(client));
@@ -116,11 +118,14 @@ export async function withPublicDb(fn) {
  * @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.
- * @param uid Connection-string mode only: overrides the user id. Omit it in
- * normal use — the id then comes from `db.getUserId()` when set, otherwise
- * from the signed-in Firebase user when `firebaseAuth` is configured.
- * Ignored in Supabase mode, which resolves identity via `db.getAccessToken`/
- * Firebase instead — see {@link resolveAccessToken}.
+ * @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
+ * `firebaseAuth` is configured. `null` is accepted alongside `undefined` so a
+ * caller's own lookup (which may itself come back empty) can be passed
+ * straight through without an extra check. Ignored in Supabase mode, which
+ * resolves identity via `db.getAccessToken`/Firebase instead — see
+ * {@link resolveAccessToken}.
  * @returns Whatever `fn` resolves to.
  * @throws If `db` is not set on your `RoutingConfig`, if no user id/access
  * token can be resolved, or the connection fails.
@@ -131,12 +136,13 @@ export async function withPublicDb(fn) {
 export async function withUserDb(fn, uid) {
     const db = config.db;
     requireDbConfig(db);
-    if (resolveDbMode(db) === 'supabase') {
+    const resolved = await resolveDbMode(db);
+    if (resolved.mode === 'supabase') {
         const token = await resolveAccessToken(config);
-        return fn(await supabaseDb(db.supabase, token));
+        return fn(await supabaseDb(resolved.supabase, token));
     }
     const userId = await resolveUserId(uid);
-    const client = await connectToPostgres(config);
+    const client = await connectToPostgres(config, resolved.connectionString);
     const role = db.authenticatedRole ?? DEFAULT_ROLE;
     try {
         const { drizzle } = await import('drizzle-orm/node-postgres');
@@ -171,13 +177,14 @@ export async function withUserDb(fn, uid) {
  * @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.
  */
-function requireSupabaseTransactionMode(db) {
-    if (resolveDbMode(db) !== 'supabase') {
+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 = db.supabase;
+    const supabase = resolved.supabase;
     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 ' +
@@ -211,7 +218,7 @@ async function runTransaction(supabase, bearerToken, build) {
 export async function withPublicTransaction(build) {
     const db = config.db;
     requireDbConfig(db);
-    const supabase = requireSupabaseTransactionMode(db);
+    const supabase = await requireSupabaseTransactionMode(db);
     const { anonKey } = await resolveSupabaseEndpoint(supabase);
     return runTransaction(supabase, anonKey, build);
 }
@@ -239,7 +246,7 @@ export async function withPublicTransaction(build) {
 export async function withUserTransaction(build) {
     const db = config.db;
     requireDbConfig(db);
-    const supabase = requireSupabaseTransactionMode(db);
+    const supabase = await requireSupabaseTransactionMode(db);
     const token = await resolveAccessToken(config);
     return runTransaction(supabase, token, build);
 }

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

@@ -1,9 +1,12 @@
-import type { ConfigValue } from '../types/types';
+import type { FallibleConfigValue } from '../types/types';
 /**
  * Resolves a config value that may have been supplied directly or as a
- * sync/async function.
+ * sync/async function. A resolver may return `null` to mean "nothing here —
+ * fall through to whatever the caller checks next" — callers already treat
+ * that the same as `undefined` wherever they use `??`/truthiness on the
+ * result, so this passes it through rather than coercing it away.
  *
  * @param value The configured value or resolver.
- * @returns The resolved value, or `undefined` when nothing was configured.
+ * @returns The resolved value, or `null`/`undefined` when nothing was configured.
  */
-export default function resolveConfigValue<T>(value: ConfigValue<T | undefined> | undefined): Promise<T | undefined>;
+export default function resolveConfigValue<T>(value: FallibleConfigValue<T> | undefined): Promise<T | null | undefined>;

package/dist/src/db/resolve_config_value.js

@@ -1,9 +1,12 @@
 /**
  * Resolves a config value that may have been supplied directly or as a
- * sync/async function.
+ * sync/async function. A resolver may return `null` to mean "nothing here —
+ * fall through to whatever the caller checks next" — callers already treat
+ * that the same as `undefined` wherever they use `??`/truthiness on the
+ * result, so this passes it through rather than coercing it away.
  *
  * @param value The configured value or resolver.
- * @returns The resolved value, or `undefined` when nothing was configured.
+ * @returns The resolved value, or `null`/`undefined` when nothing was configured.
  */
 export default async function resolveConfigValue(value) {
     return typeof value === 'function' ? value() : value;

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

@@ -1,17 +1,37 @@
-import type { DbRoutingConfig } from '../types/types';
+import type { DbRoutingConfig, SupabaseDbConfig } from '../types/types';
 /** Which transport the `db` exports use for a given config. */
 export type DbMode = 'postgres' | 'supabase';
+/**
+ * The resolved transport for a `db` config, carrying whatever
+ * {@link resolveDbMode} already resolved to decide it — so a caller that
+ * picks `'postgres'` already has the connection string in hand and never
+ * needs to call a function-based `db.connectionString` a second time.
+ */
+export type ResolvedDbMode = {
+    mode: 'postgres';
+    connectionString: string | undefined;
+} | {
+    mode: 'supabase';
+    supabase: SupabaseDbConfig;
+};
 /**
  * Decides how to reach the database from the shape of the `db` config.
  *
- * Direct Postgres wins whenever it is configured, so adding a `supabase`
- * block to an existing config never silently reroutes live traffic. With
- * neither set the result is still `'postgres'`, which lets
- * `connectToPostgres` raise its existing, more specific error about the
- * missing connection string.
+ * Direct Postgres wins whenever it resolves to a real connection string, so
+ * adding a `supabase` block to an existing config never silently reroutes
+ * live traffic. `connectionString` given as a function is actually called
+ * (and awaited) here — not just checked for presence — so a resolver that
+ * comes back `null`/`undefined` (its own source having nothing right now)
+ * falls through to `supabase` instead of locking in `'postgres'` mode and
+ * failing later in `connectToPostgres` with no `supabase` fallback tried.
+ * With neither resolving to anything, the result is still `'postgres'`
+ * (with an `undefined` connection string), which lets `connectToPostgres`
+ * raise its existing, more specific error about the missing connection
+ * string — it is never asked to resolve `db.connectionString` itself, so a
+ * resolver given as a function runs exactly once per call here, not twice.
  *
  * @param db The `db` field off your routing config.
- * @returns `'postgres'` for direct connection-string access, `'supabase'`
- * for PostgREST access.
+ * @returns The resolved mode, plus whichever of `connectionString`/`supabase`
+ * that mode needs.
  */
-export default function resolveDbMode(db: DbRoutingConfig): DbMode;
+export default function resolveDbMode(db: DbRoutingConfig): Promise<ResolvedDbMode>;

package/dist/src/db/resolve_mode.js

@@ -1,18 +1,29 @@
+import resolveConfigValue from './resolve_config_value';
 /**
  * Decides how to reach the database from the shape of the `db` config.
  *
- * Direct Postgres wins whenever it is configured, so adding a `supabase`
- * block to an existing config never silently reroutes live traffic. With
- * neither set the result is still `'postgres'`, which lets
- * `connectToPostgres` raise its existing, more specific error about the
- * missing connection string.
+ * Direct Postgres wins whenever it resolves to a real connection string, so
+ * adding a `supabase` block to an existing config never silently reroutes
+ * live traffic. `connectionString` given as a function is actually called
+ * (and awaited) here — not just checked for presence — so a resolver that
+ * comes back `null`/`undefined` (its own source having nothing right now)
+ * falls through to `supabase` instead of locking in `'postgres'` mode and
+ * failing later in `connectToPostgres` with no `supabase` fallback tried.
+ * With neither resolving to anything, the result is still `'postgres'`
+ * (with an `undefined` connection string), which lets `connectToPostgres`
+ * raise its existing, more specific error about the missing connection
+ * string — it is never asked to resolve `db.connectionString` itself, so a
+ * resolver given as a function runs exactly once per call here, not twice.
  *
  * @param db The `db` field off your routing config.
- * @returns `'postgres'` for direct connection-string access, `'supabase'`
- * for PostgREST access.
+ * @returns The resolved mode, plus whichever of `connectionString`/`supabase`
+ * that mode needs.
  */
-export default function resolveDbMode(db) {
-    if (db.connectionString)
-        return 'postgres';
-    return db.supabase ? 'supabase' : 'postgres';
+export default async function resolveDbMode(db) {
+    const connectionString = await resolveConfigValue(db.connectionString);
+    if (connectionString)
+        return { mode: 'postgres', connectionString };
+    if (db.supabase)
+        return { mode: 'supabase', supabase: db.supabase };
+    return { mode: 'postgres', connectionString: undefined };
 }

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

@@ -824,20 +824,31 @@ export interface IntlSitemap {
  * the config object is first created.
  */
 export type ConfigValue<T> = T | (() => T | Promise<T>);
+/**
+ * A {@link ConfigValue} whose function form may also return `null` to mean
+ * "this source has nothing — fall through to the next one" (an env var
+ * default, or another resolver), the same way `getUserId`/`getAccessToken`
+ * already do. `undefined` means the same thing; both are treated
+ * identically by every resolver that reads one of these.
+ */
+export type FallibleConfigValue<T> = ConfigValue<T | null | undefined>;
 export interface SupabaseDbConfig {
     /**
      * Supabase project URL, e.g. `https://abc.supabase.co`. Defaults to
      * `process.env.NEXT_PUBLIC_SUPABASE_URL`. May be a function (sync or
-     * async) resolved on each use.
+     * async) resolved on each use — return `null`/`undefined` from it to
+     * fall through to the environment variable instead of erroring.
      */
-    url?: ConfigValue<string | undefined>;
+    url?: FallibleConfigValue<string>;
     /**
      * Supabase anon (publishable) key. Defaults to
      * `process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY`. This is the only key the
      * `db` module ever needs — never put a service-role key here. May be a
-     * function (sync or async) resolved on each use.
+     * function (sync or async) resolved on each use — return
+     * `null`/`undefined` from it to fall through to the environment variable
+     * instead of erroring.
      */
-    anonKey?: ConfigValue<string | undefined>;
+    anonKey?: FallibleConfigValue<string>;
     /**
      * Name of the Postgres function that runs the generated SQL. Defaults to
      * `'cfni_exec'` — the function shipped in `supabase/cfni_exec.sql`.
@@ -865,9 +876,11 @@ export interface DbRoutingConfig {
      * resolved on each connect. The function form is how you reach a value that
      * isn't available at module scope — e.g. a Cloudflare Hyperdrive binding:
      * `connectionString: async () => (await getCloudflareContext({ async: true
-     * })).env.HYPERDRIVE.connectionString`.
+     * })).env.HYPERDRIVE.connectionString`. Return `null`/`undefined` from it
+     * when there is nothing to give — both surface the same "could not
+     * resolve a Postgres connection string" error as leaving this unset.
      */
-    connectionString?: ConfigValue<string | undefined>;
+    connectionString?: FallibleConfigValue<string>;
     /**
      * Whether the pooled client is closed once the last in-flight
      * `withPublicDb`/`withUserDb` call of the request finishes.

package/package.json

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