cloudflare-next-intl 0.7.8 → 0.8.0

package/dist/src/db/context.js

@@ -0,0 +1,125 @@
+import config from '../config/intl_config';
+import requireDbConfig from './require_config';
+import connectToPostgres, { disconnectPostgres } from './connection';
+import resolveDbMode from './resolve_mode';
+import resolveSupabaseEndpoint from './supabase_config';
+import createSupabaseTransport from './supabase_transport';
+import resolveAccessToken from './access_token';
+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.
+ */
+async function resolveUserId(uid) {
+    if (uid)
+        return uid;
+    const db = config.db;
+    requireDbConfig(db);
+    const fromConfig = await db.getUserId?.();
+    if (fromConfig)
+        return fromConfig;
+    if (config.firebaseAuth) {
+        const { getAuthUser } = await import('../firebase_auth/server/use_auth_user_server');
+        const { user } = await getAuthUser();
+        if (user?.uid)
+            return user.uid;
+    }
+    throw new Error('db: withUserDb could not resolve a user id. Pass one explicitly, set ' +
+        '`db.getUserId`, or configure `firebaseAuth` so the signed-in Firebase uid is used.');
+}
+/**
+ * Builds a Drizzle handle backed by PostgREST. `bearerToken` decides the role
+ * Postgres sees: the anon key for public access, a user JWT for `withUserDb`.
+ */
+async function supabaseDb(supabase, bearerToken) {
+    const { drizzle } = await import('drizzle-orm/pg-proxy');
+    return drizzle(createSupabaseTransport(supabase, bearerToken));
+}
+/**
+ * Runs a query as the **anonymous** role: no transaction, no role switch, no
+ * user identity attached. Use this for data any visitor may read.
+ *
+ * Because no user id is set, RLS policies that test `auth.jwt()->>'sub'` see
+ * no user and will deny access — reach for {@link withUserDb} whenever the
+ * rows depend on who is asking.
+ *
+ * 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.
+ *
+ * @param fn Receives the Drizzle handle; return whatever the caller needs.
+ * @returns Whatever `fn` resolves to.
+ * @throws If `db` is not set on your `RoutingConfig`, or the connection fails.
+ *
+ * @example
+ * const rows = await withPublicDb((db) => db.select().from(bonds).limit(10));
+ */
+export async function withPublicDb(fn) {
+    const db = config.db;
+    requireDbConfig(db);
+    if (resolveDbMode(db) === 'supabase') {
+        const supabase = db.supabase;
+        const { anonKey } = resolveSupabaseEndpoint(supabase);
+        return fn(await supabaseDb(supabase, anonKey));
+    }
+    const client = await connectToPostgres(config);
+    try {
+        const { drizzle } = await import('drizzle-orm/node-postgres');
+        return await fn(drizzle(client));
+    }
+    finally {
+        disconnectPostgres(config);
+    }
+}
+/**
+ * Runs a query as the **signed-in user**.
+ *
+ * In connection-string mode this runs inside a transaction where Postgres
+ * sees the resolved user id as `auth.jwt()->>'sub'` under
+ * `db.authenticatedRole`, so RLS policies behave exactly as they do for a
+ * 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.
+ *
+ * @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}.
+ * @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.
+ *
+ * @example
+ * const mine = await withUserDb((db) => db.select().from(orders));
+ */
+export async function withUserDb(fn, uid) {
+    const db = config.db;
+    requireDbConfig(db);
+    if (resolveDbMode(db) === 'supabase') {
+        const token = await resolveAccessToken(config);
+        return fn(await supabaseDb(db.supabase, token));
+    }
+    const userId = await resolveUserId(uid);
+    const client = await connectToPostgres(config);
+    const role = db.authenticatedRole ?? DEFAULT_ROLE;
+    try {
+        const { drizzle } = await import('drizzle-orm/node-postgres');
+        const { sql } = await import('drizzle-orm');
+        return await drizzle(client).transaction(async (transaction) => {
+            await transaction.execute(sql `select set_config('request.jwt.claims', ${JSON.stringify({ sub: userId })}, true)`);
+            await transaction.execute(sql `set local role ${sql.raw(role)}`);
+            return fn(transaction);
+        });
+    }
+    finally {
+        disconnectPostgres(config);
+    }
+}

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

@@ -0,0 +1,57 @@
+import { type SQL, type Table } from 'drizzle-orm';
+/**
+ * Type-safe helper returning `excluded.<db_column_name>` SQL expressions for a Drizzle table.
+ *
+ * Restricts property access at compile time to valid table schema keys (camelCase),
+ * and validates at runtime by throwing a descriptive error if an unknown property is accessed.
+ *
+ * @example
+ * set: {
+ *   inflation: excluded(inflation).inflation,
+ *   yearInflation: excluded(inflation).yearInflation,
+ *   updatedAt: sql`now()`,
+ * }
+ */
+export declare function excluded<T extends Table>(table: T): {
+    [K in keyof T["_"]["columns"]]: SQL;
+};
+/**
+ * Builds a runtime and compile-time validated `set` object for `onConflictDoUpdate`.
+ *
+ * Only permits valid column keys of the target table. Automatically maps
+ * property keys to database column names and appends `updatedAt: sql\`now()\``
+ * if the column exists on the table.
+ *
+ * @example
+ * .onConflictDoUpdate({
+ *   target: inflation.date,
+ *   set: onConflictSet(inflation, ["inflation", "yearInflation"]),
+ * })
+ */
+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 generating a timestamp expression relative to now (`now() - (N unit)::interval`). */
+export declare function ago(amount: number, unit: TimeUnit): SQL;
+/** General SQL helper returning `current_date`. */
+export declare function currentDate(): SQL;
+/** General SQL helper for window function `count(*) over ()`. */
+export declare function windowCount(): SQL<number>;
+/** Helper generating `lateral unnest(...) as alias(alias)`. */
+export declare function unnestLateral(column: unknown, alias: string): SQL;
+/** Helper generating `column asc nulls last`. */
+export declare function ascNullsLast(column: unknown): SQL;
+/** General SQL literal `true`, for lateral joins and empty predicate lists. */
+export declare function alwaysTrue(): SQL;
+/** Wraps an expression as `lateral (<inner>) <alias>`. */
+export declare function lateral(inner: SQL, alias: string): SQL;
+/** References `<alias>.<column>` of a derived table / lateral subquery. */
+export declare function aliasColumn<T = unknown>(alias: string, column: string): SQL<T>;
+/** General aggregate helpers over an arbitrary expression. */
+export declare function minOf<T = unknown>(expression: unknown): SQL<T>;
+export declare function maxOf<T = unknown>(expression: unknown): SQL<T>;
+/** Rounds an expression to `digits` decimals, returning `real`. */
+export declare function roundReal(expression: unknown, digits: number): SQL<number>;
+/** Multiplies an expression by a factor. */
+export declare function multiply(expression: unknown, factor: number): SQL<number>;
+/** Wraps an expression as a scalar subquery over a named CTE: `(select <expr> from <cte>)`. */
+export declare function scalarFromCte<T = unknown>(cte: string, expression: unknown): SQL<T>;

package/dist/src/db/helpers.js

@@ -0,0 +1,112 @@
+import { getTableColumns, getTableName, sql } from 'drizzle-orm';
+/**
+ * Type-safe helper returning `excluded.<db_column_name>` SQL expressions for a Drizzle table.
+ *
+ * Restricts property access at compile time to valid table schema keys (camelCase),
+ * and validates at runtime by throwing a descriptive error if an unknown property is accessed.
+ *
+ * @example
+ * set: {
+ *   inflation: excluded(inflation).inflation,
+ *   yearInflation: excluded(inflation).yearInflation,
+ *   updatedAt: sql`now()`,
+ * }
+ */
+export function excluded(table) {
+    const cols = getTableColumns(table);
+    const tableName = getTableName(table);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return new Proxy({}, {
+        get(_, prop) {
+            const col = cols[prop];
+            if (!col) {
+                throw new Error(`[Drizzle Error] Column "${prop}" does not exist on table "${tableName}". ` +
+                    `Valid columns: ${Object.keys(cols).join(", ")}`);
+            }
+            return sql.raw(`excluded.${col.name}`);
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    });
+}
+/**
+ * Builds a runtime and compile-time validated `set` object for `onConflictDoUpdate`.
+ *
+ * Only permits valid column keys of the target table. Automatically maps
+ * property keys to database column names and appends `updatedAt: sql\`now()\``
+ * if the column exists on the table.
+ *
+ * @example
+ * .onConflictDoUpdate({
+ *   target: inflation.date,
+ *   set: onConflictSet(inflation, ["inflation", "yearInflation"]),
+ * })
+ */
+export function onConflictSet(table, fields) {
+    const cols = getTableColumns(table);
+    const tableName = getTableName(table);
+    const setObj = {};
+    for (const field of fields) {
+        const key = String(field);
+        const col = cols[key];
+        if (!col) {
+            throw new Error(`[Drizzle Error] Column "${key}" does not exist on table "${tableName}". ` +
+                `Valid columns: ${Object.keys(cols).join(", ")}`);
+        }
+        setObj[key] = sql.raw(`excluded.${col.name}`);
+    }
+    if ("updatedAt" in cols) {
+        setObj.updatedAt = sql `now()`;
+    }
+    return setObj;
+}
+/** 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 returning `current_date`. */
+export function currentDate() {
+    return sql `current_date`;
+}
+/** General SQL helper for window function `count(*) over ()`. */
+export function windowCount() {
+    return sql `count(*) over ()`.mapWith(Number);
+}
+/** Helper generating `lateral unnest(...) as alias(alias)`. */
+export function unnestLateral(column, alias) {
+    return sql `lateral unnest(${column}) as ${sql.raw(alias)}(${sql.raw(alias)})`;
+}
+/** Helper generating `column asc nulls last`. */
+export function ascNullsLast(column) {
+    return sql `${column} asc nulls last`;
+}
+/** General SQL literal `true`, for lateral joins and empty predicate lists. */
+export function alwaysTrue() {
+    return sql `true`;
+}
+/** Wraps an expression as `lateral (<inner>) <alias>`. */
+export function lateral(inner, alias) {
+    return sql `lateral (${inner}) ${sql.raw(alias)}`;
+}
+/** References `<alias>.<column>` of a derived table / lateral subquery. */
+export function aliasColumn(alias, column) {
+    return sql.raw(`${alias}.${column}`);
+}
+/** General aggregate helpers over an arbitrary expression. */
+export function minOf(expression) {
+    return sql `min(${expression})`;
+}
+export function maxOf(expression) {
+    return sql `max(${expression})`;
+}
+/** Rounds an expression to `digits` decimals, returning `real`. */
+export function roundReal(expression, digits) {
+    return sql `round((${expression})::numeric, ${digits})::real`;
+}
+/** Multiplies an expression by a factor. */
+export function multiply(expression, factor) {
+    return sql `${expression} * ${factor}`;
+}
+/** Wraps an expression as a scalar subquery over a named CTE: `(select <expr> from <cte>)`. */
+export function scalarFromCte(cte, expression) {
+    return sql `(select ${expression} from ${sql.raw(cte)})`;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Optional Postgres/Drizzle data-access layer, reached from
+ * `cloudflare-next-intl/db`. Enable it by setting `db` on your `RoutingConfig`;
+ * every export here throws a descriptive error if that config is missing.
+ *
+ * Pick a wrapper by who is allowed to see the rows:
+ * - {@link withPublicDb} — anonymous role, for data any visitor may read.
+ * - {@link withUserDb} — the signed-in user, with RLS applied to their id.
+ *
+ * Two transports reach Postgres behind that same Drizzle query API, chosen by
+ * `resolveDbMode` from which `db` config fields are set: `connectionString`/
+ * `hyperdriveBinding` for a direct connection (wins if both are configured),
+ * or `supabase` for the Supabase Data API when only a project URL and anon
+ * key are available. `pg`, `drizzle-orm`, and `@supabase/supabase-js` all
+ * load through dynamic `import()` inside these functions, so an app that
+ * never calls a `db` export never bundles any of them.
+ *
+ * Generic Drizzle SQL helpers (`excluded`, `onConflictSet`, `ago`, …) live in
+ * the separate `cloudflare-next-intl/dbHelpers` entry point.
+ */
+export { withPublicDb, withUserDb } from './context';
+export type { DrizzleDb } from './context';
+export { default as connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';
+export type { DbRoutingConfig } from '../types/types';

package/dist/src/db/index.js

@@ -0,0 +1,22 @@
+/**
+ * Optional Postgres/Drizzle data-access layer, reached from
+ * `cloudflare-next-intl/db`. Enable it by setting `db` on your `RoutingConfig`;
+ * every export here throws a descriptive error if that config is missing.
+ *
+ * Pick a wrapper by who is allowed to see the rows:
+ * - {@link withPublicDb} — anonymous role, for data any visitor may read.
+ * - {@link withUserDb} — the signed-in user, with RLS applied to their id.
+ *
+ * Two transports reach Postgres behind that same Drizzle query API, chosen by
+ * `resolveDbMode` from which `db` config fields are set: `connectionString`/
+ * `hyperdriveBinding` for a direct connection (wins if both are configured),
+ * or `supabase` for the Supabase Data API when only a project URL and anon
+ * key are available. `pg`, `drizzle-orm`, and `@supabase/supabase-js` all
+ * load through dynamic `import()` inside these functions, so an app that
+ * never calls a `db` export never bundles any of them.
+ *
+ * Generic Drizzle SQL helpers (`excluded`, `onConflictSet`, `ago`, …) live in
+ * the separate `cloudflare-next-intl/dbHelpers` entry point.
+ */
+export { withPublicDb, withUserDb } from './context';
+export { default as connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';

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

@@ -0,0 +1,15 @@
+import type { DbRoutingConfig } from '../types/types';
+/**
+ * Asserts that the optional `db` config is present, narrowing it from
+ * `DbRoutingConfig | undefined` to `DbRoutingConfig` for the rest of the
+ * caller's scope.
+ *
+ * Every `db` export calls this before touching `pg`/`drizzle-orm`. It throws
+ * rather than silently no-op'ing, so a consumer who calls e.g. `withPublicDb()`
+ * without setting `db` on their `RoutingConfig` gets an immediate, actionable
+ * error instead of a confusing failed query.
+ *
+ * @param db The `db` field off your routing config.
+ * @throws If `db` is undefined.
+ */
+export default function requireDbConfig(db: DbRoutingConfig | undefined): asserts db is DbRoutingConfig;

package/dist/src/db/require_config.js

@@ -0,0 +1,20 @@
+/**
+ * Asserts that the optional `db` config is present, narrowing it from
+ * `DbRoutingConfig | undefined` to `DbRoutingConfig` for the rest of the
+ * caller's scope.
+ *
+ * Every `db` export calls this before touching `pg`/`drizzle-orm`. It throws
+ * rather than silently no-op'ing, so a consumer who calls e.g. `withPublicDb()`
+ * without setting `db` on their `RoutingConfig` gets an immediate, actionable
+ * error instead of a confusing failed query.
+ *
+ * @param db The `db` field off your routing config.
+ * @throws If `db` is undefined.
+ */
+export default function requireDbConfig(db) {
+    if (!db) {
+        throw new Error('db: `db` is not set on your RoutingConfig. Add a `db` object ' +
+            '(connectionString or hyperdriveBinding) to the config passed to ' +
+            '`setIntlConfig` before using any db export.');
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { DbRoutingConfig } from '../types/types';
+/** Which transport the `db` exports use for a given config. */
+export type DbMode = 'postgres' | 'supabase';
+/**
+ * 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 Hyperdrive binding.
+ *
+ * @param db The `db` field off your routing config.
+ * @returns `'postgres'` for connection-string/Hyperdrive access, `'supabase'`
+ * for PostgREST access.
+ */
+export default function resolveDbMode(db: DbRoutingConfig): DbMode;

package/dist/src/db/resolve_mode.js

@@ -0,0 +1,18 @@
+/**
+ * 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 Hyperdrive binding.
+ *
+ * @param db The `db` field off your routing config.
+ * @returns `'postgres'` for connection-string/Hyperdrive access, `'supabase'`
+ * for PostgREST access.
+ */
+export default function resolveDbMode(db) {
+    if (db.connectionString || db.hyperdriveBinding)
+        return 'postgres';
+    return db.supabase ? 'supabase' : 'postgres';
+}

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

@@ -0,0 +1,18 @@
+import type { SupabaseDbConfig } from '../types/types';
+/** The Supabase project URL and anon key the transport builds a client from. */
+export interface ResolvedSupabaseEndpoint {
+    /** Project URL, trailing slashes stripped. */
+    url: string;
+    /** Anon key, sent as both `apikey` and the public-mode bearer token. */
+    anonKey: string;
+}
+/**
+ * Resolves the Supabase project URL and anon key, preferring explicit config
+ * over the `NEXT_PUBLIC_SUPABASE_URL`/`NEXT_PUBLIC_SUPABASE_ANON_KEY`
+ * environment variables.
+ *
+ * @param supabase The `db.supabase` config block.
+ * @returns The project URL and anon key to build a Supabase client from.
+ * @throws If neither config nor environment supplies a URL or an anon key.
+ */
+export default function resolveSupabaseEndpoint(supabase: SupabaseDbConfig): ResolvedSupabaseEndpoint;

package/dist/src/db/supabase_config.js

@@ -0,0 +1,22 @@
+/**
+ * Resolves the Supabase project URL and anon key, preferring explicit config
+ * over the `NEXT_PUBLIC_SUPABASE_URL`/`NEXT_PUBLIC_SUPABASE_ANON_KEY`
+ * environment variables.
+ *
+ * @param supabase The `db.supabase` config block.
+ * @returns The project URL and anon key to build a Supabase client from.
+ * @throws If neither config nor environment supplies a URL or an anon key.
+ */
+export default function resolveSupabaseEndpoint(supabase) {
+    const url = supabase.url ?? process.env.NEXT_PUBLIC_SUPABASE_URL;
+    if (!url) {
+        throw new Error('db: could not resolve a Supabase project URL. Set `db.supabase.url` ' +
+            'or the NEXT_PUBLIC_SUPABASE_URL environment variable.');
+    }
+    const anonKey = supabase.anonKey ?? process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
+    if (!anonKey) {
+        throw new Error('db: could not resolve a Supabase anon key. Set `db.supabase.anonKey` ' +
+            'or the NEXT_PUBLIC_SUPABASE_ANON_KEY environment variable.');
+    }
+    return { url: url.replace(/\/+$/, ''), anonKey };
+}

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

@@ -0,0 +1,29 @@
+import type { SupabaseDbConfig } from '../types/types';
+/**
+ * The executor shape `drizzle-orm/pg-proxy` calls with each generated
+ * statement. Declared structurally so this file never imports `drizzle-orm`.
+ */
+export type SupabaseRemoteCallback = (sql: string, params: unknown[], method: 'all' | 'execute') => Promise<{
+    rows: unknown[];
+}>;
+/**
+ * Builds the transport Drizzle uses in Supabase mode: every generated
+ * statement is sent through `@supabase/supabase-js`'s `.rpc()` to the
+ * `cfni_exec` function over PostgREST.
+ *
+ * `bearerToken` decides who Postgres thinks is calling — the anon key for
+ * public reads, a user's JWT for `withUserDb` — delivered through the
+ * client's `accessToken` option (the same mechanism a signed-in Supabase
+ * session would use), so RLS is enforced by the database rather than by
+ * anything in this package. The client is created once and reused for every
+ * statement this transport is asked to run.
+ *
+ * Rows come back as positional arrays because `pg-proxy` maps result columns
+ * by index; `cfni_exec` is what guarantees that shape.
+ *
+ * @param supabase The `db.supabase` config block.
+ * @param bearerToken Token resolved as the caller's identity — the anon key,
+ * or a per-request user JWT.
+ * @returns A callback suitable for `drizzle-orm/pg-proxy`'s `drizzle()`.
+ */
+export default function createSupabaseTransport(supabase: SupabaseDbConfig, bearerToken: string): SupabaseRemoteCallback;

package/dist/src/db/supabase_transport.js

@@ -0,0 +1,49 @@
+import resolveSupabaseEndpoint from './supabase_config';
+const DEFAULT_EXEC_FUNCTION = 'cfni_exec';
+/**
+ * Builds the transport Drizzle uses in Supabase mode: every generated
+ * statement is sent through `@supabase/supabase-js`'s `.rpc()` to the
+ * `cfni_exec` function over PostgREST.
+ *
+ * `bearerToken` decides who Postgres thinks is calling — the anon key for
+ * public reads, a user's JWT for `withUserDb` — delivered through the
+ * client's `accessToken` option (the same mechanism a signed-in Supabase
+ * session would use), so RLS is enforced by the database rather than by
+ * anything in this package. The client is created once and reused for every
+ * statement this transport is asked to run.
+ *
+ * Rows come back as positional arrays because `pg-proxy` maps result columns
+ * by index; `cfni_exec` is what guarantees that shape.
+ *
+ * @param supabase The `db.supabase` config block.
+ * @param bearerToken Token resolved as the caller's identity — the anon key,
+ * or a per-request user JWT.
+ * @returns A callback suitable for `drizzle-orm/pg-proxy`'s `drizzle()`.
+ */
+export default function createSupabaseTransport(supabase, bearerToken) {
+    const { url, anonKey } = resolveSupabaseEndpoint(supabase);
+    const execFunction = supabase.execFunction ?? DEFAULT_EXEC_FUNCTION;
+    let clientPromise = null;
+    async function getClient() {
+        clientPromise ?? (clientPromise = (async () => {
+            const { createClient } = await import('@supabase/supabase-js');
+            return createClient(url, anonKey, { accessToken: async () => bearerToken });
+        })());
+        return clientPromise;
+    }
+    return async (sql, params) => {
+        const client = await getClient();
+        const { data, error } = await client.rpc(execFunction, { statement: sql, params });
+        if (error)
+            throw new Error(describeFailure(error, execFunction));
+        return { rows: Array.isArray(data) ? data : [] };
+    };
+}
+function describeFailure(error, execFunction) {
+    // PGRST202 is PostgREST's "no such function" — by far the most likely
+    // first-run failure, so point at the install step instead of the raw code.
+    if (error.code === 'PGRST202') {
+        return `db: Supabase rejected the query — ${error.message}. Install the ${execFunction} function from supabase/cfni_exec.sql in your database.`;
+    }
+    return `db: Supabase rejected the query — ${error.message}.`;
+}

package/dist/src/index.d.ts

@@ -4,3 +4,4 @@ export * from './server';
 export * from './client';
 export * from './theme_switcher';
 export * from './types';
+export * from './db';

package/dist/src/index.js

@@ -4,3 +4,4 @@ export * from './server';
 export * from './client';
 export * from './theme_switcher';
 export * from './types';
+export * from './db';

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

@@ -85,6 +85,14 @@ export interface RoutingConfig<AppLocales extends Locales, AppLocalePrefixMode e
      * if this field is missing at call time rather than silently no-op'ing.
      */
     firebaseAuth?: FirebaseAuthRoutingConfig;
+    /**
+     * Configures the optional `db` submodule (Postgres/Drizzle access over a
+     * Cloudflare Hyperdrive or plain connection string). Omit entirely to keep
+     * it fully disabled — no file in this package imports `pg`/`drizzle-orm`
+     * unless a `db` export is actually called, and every such export throws a
+     * clear error if this field is missing at call time.
+     */
+    db?: DbRoutingConfig;
     /**
      * Configures the optional `cookie_consent` submodule (cookie-consent +
      * privacy-policy-update banners). Omit entirely to keep it disabled —
@@ -809,3 +817,86 @@ export interface IntlSitemap {
     lastModified: Date | string | undefined;
     videos?: Videos[] | undefined;
 }
+export interface SupabaseDbConfig {
+    /**
+     * Supabase project URL, e.g. `https://abc.supabase.co`. Defaults to
+     * `process.env.NEXT_PUBLIC_SUPABASE_URL`.
+     */
+    url?: 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.
+     */
+    anonKey?: string;
+    /**
+     * Name of the Postgres function that runs the generated SQL. Defaults to
+     * `'cfni_exec'` — the function shipped in `supabase/cfni_exec.sql`.
+     */
+    execFunction?: string;
+}
+export interface DbRoutingConfig {
+    /**
+     * Postgres connection string. Omit to resolve it from the Cloudflare
+     * Hyperdrive binding named by `hyperdriveBinding` instead (the normal
+     * production setup); a value here always wins over the binding, which is
+     * what makes local dev / build-time evaluation work.
+     */
+    connectionString?: string;
+    /**
+     * Name of the Hyperdrive binding on `env` whose `connectionString` is used
+     * when `connectionString` is not set. Defaults to `'HYPERDRIVE'`. Requires
+     * `generate.getCloudflareContext` to be configured.
+     */
+    hyperdriveBinding?: string;
+    /**
+     * 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.
+     */
+    disconnectAfterRequest?: boolean;
+    /**
+     * Postgres role assumed inside `withUserDb`'s transaction. Defaults
+     * to `'authenticated'` (the Supabase RLS convention).
+     */
+    authenticatedRole?: string;
+    /**
+     * 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).
+     */
+    getUserId?: () => Promise<string | null> | string | null;
+    /** Milliseconds `disconnectPostgres` waits for `client.end()` before giving up. Defaults to `2000`. */
+    disconnectTimeoutMs?: number;
+    /**
+     * Reaches Postgres through the Supabase Data API instead of a direct
+     * connection, using only your project URL and anon key. Set this when you
+     * have no Postgres password to give the package — `withPublicDb` and
+     * `withUserDb` behave the same either way, so switching is a config change
+     * with no app-code change.
+     *
+     * Ignored when `connectionString` or `hyperdriveBinding` is set: a direct
+     * connection always wins, so adding this block cannot silently reroute
+     * 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.
+     */
+    supabase?: SupabaseDbConfig;
+    /**
+     * Resolves the JWT sent as `Authorization: Bearer` for `withUserDb` in
+     * Supabase mode, which is what makes PostgREST resolve the caller as
+     * `authenticated` and apply RLS. Omit when `firebaseAuth` is configured —
+     * the signed-in user's Firebase ID token is then used automatically.
+     *
+     * Unused in connection-string mode, which identifies the user with
+     * `getUserId` and `set_config` instead.
+     */
+    getAccessToken?: () => Promise<string | null> | string | null;
+}