cloudflare-next-intl 0.7.8 → 0.8.0

package/llms.txt

@@ -23,6 +23,8 @@ other subpath can be used.
 - `./localeStaticParams` — `generateStaticParams` helper for locale segments.
 - `./use` — `useLocale`/`useTranslations`; resolves to the RSC or client implementation automatically via the `react-server` export condition. Both throw `"... must be used within an IntlProvider"` if called outside one.
 - `./ThemeSwitcher` — optional light/dark toggle component.
+- `./db` — `withPublicDb(fn)` / `withUserDb(fn, uid?)` server-side Postgres/Drizzle context helpers (require `db` set on your `RoutingConfig`; direct Postgres or Supabase Data API, see below).
+- `./dbHelpers` — generic Drizzle SQL helper functions (`excluded`, `onConflictSet`, `ago`, `currentDate`, `windowCount`, `unnestLateral`, `ascNullsLast`, `alwaysTrue`, `lateral`, `aliasColumn`, `minOf`, `maxOf`, `roundReal`, `multiply`, `scalarFromCte`) for use with `./db`.
 
 ## `firebaseAuth*` subpaths (require `firebaseAuth` set on your `RoutingConfig`)
 
@@ -44,6 +46,38 @@ other subpath can be used.
 - `./cookieConsentAnalytics` — `CookieConsentAnalytics`: gates Cloudflare Web Analytics / Google Ads / Google Analytics / AdSense / Microsoft Clarity behind consent; rendered automatically by `IntlProvider` when `cookieConsent.secrets` or `getSecrets` is set (and `autoWireAnalytics !== false`). Never renders in local dev (`NODE_ENV === 'development'`) unless `cookieConsent.enableAnalyticsInDevMode` is `true`.
 - Country-based gating (`cookieConsent.getCountryCode` / `getCloudflareContext` + `gdprCountries`): resolved server-side by `IntlProvider` into a `requiresConsent` boolean passed to `CookieConsentProvider`. Neither getter set → gating off, consent always implicitly granted. `getCountryCode` (direct country resolver) takes precedence over `getCloudflareContext` (reads `cf.country`) when both are set. `getCloudflareContext` accepts `@opennextjs/cloudflare`'s `getCloudflareContext` function directly (its exact overloaded signature — `CookieConsentGetCloudflareContext`), called internally with `{ async: true }`. Unresolved country (or a `null` context) always requires consent (fail-safe). `./cookieConsent` also exports `defaultGdprCountries` (EU/EEA + UK + Switzerland).
 
+## `db*` subpaths (require `db` set on your `RoutingConfig`)
+
+Two transports, picked by which `db` fields are set — `pg`/`drizzle-orm`/`@supabase/supabase-js` ship as dependencies and load via dynamic `import()`, so nothing bundles unless a `db` export is called.
+
+- Direct Postgres (wins if configured): `db.connectionString` — Postgres connection string; when omitted, resolved from the Hyperdrive binding named by `db.hyperdriveBinding` (default `'HYPERDRIVE'`) via `generate.getCloudflareContext`. An explicit `connectionString` always wins (enables local dev / build-time evaluation).
+- Supabase Data API (used only when neither of the above is set): `db.supabase` — `{ url?, anonKey?, execFunction? }`, defaulting `url`/`anonKey` to `NEXT_PUBLIC_SUPABASE_URL`/`NEXT_PUBLIC_SUPABASE_ANON_KEY`. Requires installing `supabase/cfni_exec.sql` (a `security invoker` SQL-exec function) in your database. No multi-statement transactions — each statement in a `withUserDb` callback is its own round-trip.
+- `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.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`.
+- `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.
+
+```typescript
+// src/i18n/intl_config.ts
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+
+export default setIntlConfig({
+    locales: ["en", "uk"] as const,
+    defaultLocale: "en",
+    generate: { getCloudflareContext },
+    db: { hyperdriveBinding: "HYPERDRIVE" },
+});
+
+// anywhere on the server
+import { withPublicDb } from "cloudflare-next-intl/db";
+
+const rows = await withPublicDb((db) => db.select().from(bonds).limit(10));
+```
+
 ## Conventions
 
 - Every exported function/component has a JSDoc comment with an `@example` where usage isn't obvious from the signature alone.
@@ -56,3 +90,4 @@ other subpath can be used.
 - Missing `firebaseAuth` on `RoutingConfig` throws immediately from any `firebaseAuth*` export, naming the missing config field.
 - `useLocale`/`useTranslations` (from `./use`) and `useAuthUser` (from `./useFirebaseAuthUser`) resolve to a Server- or Client-Component implementation automatically via the `react-server` export condition — always import from the subpath, never from an internal file path.
 - No unified `useFirebaseAuthUser` re-export inside `cloudflare-next-intl/firebaseAuth`'s barrel — that barrel can't replicate the `react-server` condition split, so import `cloudflare-next-intl/useFirebaseAuthUser` directly for the hook.
+- Missing `db` on `RoutingConfig` throws immediately from `withPublicDb`/`withUserDb`, naming the missing config field. `pg`, `drizzle-orm`, and `@supabase/supabase-js` ship as dependencies and load via dynamic `import()` — nothing to install yourself, and nothing bundles unless a `db` export is called.

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.7.8",
+  "version": "0.8.0",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
-
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "sideEffects": false,
+  "bin": {
+    "cfni-db-codegen": "bin/db_codegen.mjs"
+  },
   "files": [
     "dist",
+    "bin",
+    "supabase",
     "LICENSE",
     "README.md",
     "llms.txt"
@@ -172,6 +176,14 @@
     "./createServerErrorAction": {
       "types": "./dist/src/error_handling/create_server_error_action.d.ts",
       "import": "./dist/src/error_handling/create_server_error_action.js"
+    },
+    "./db": {
+      "types": "./dist/src/db/index.d.ts",
+      "import": "./dist/src/db/index.js"
+    },
+    "./dbHelpers": {
+      "types": "./dist/src/db/helpers.d.ts",
+      "import": "./dist/src/db/helpers.js"
     }
   },
   "scripts": {
@@ -216,8 +228,11 @@
   "homepage": "https://github.com/demian-ilnytskyi/cloudflare-next-intl#readme",
   "dependencies": {
     "@microsoft/clarity": "^1.0.2",
+    "@supabase/supabase-js": "^2.112.3",
+    "drizzle-orm": "^0.45.2",
     "firebase": "^12.17.0",
-    "jose": "^6.2.8"
+    "jose": "^6.2.8",
+    "pg": "^8.23.0"
   },
   "peerDependencies": {
     "next": ">=12.0.0",
@@ -236,16 +251,18 @@
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^20.14.5",
+    "@types/pg": "^8.23.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitest/coverage-v8": "^3.2.7",
+    "drizzle-kit": "^0.31.10",
     "eslint": "^9.28.0",
     "eslint-config-next": "15.3.3",
     "eslint-config-prettier": "^10.1.2",
     "jsdom": "^29.1.1",
     "next": "^15.3.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
     "tsup": "^8.5.1",
     "typescript": "^5.5.3",
     "typescript-eslint": "^8.33.1",

package/supabase/cfni_exec.sql

@@ -0,0 +1,34 @@
+-- Executes a statement generated by cloudflare-next-intl's `db` module and
+-- returns its rows as positional JSON arrays, which is the shape
+-- drizzle-orm/pg-proxy maps result columns from.
+--
+-- SECURITY INVOKER is load-bearing: the statement runs with the privileges of
+-- the caller (anon or authenticated, per the request's JWT), so row-level
+-- security still applies exactly as it does over the REST API. Do not change
+-- this to SECURITY DEFINER, and do not add a role parameter — either would
+-- turn this into a privilege-escalation primitive.
+create or replace function public.cfni_exec(statement text, params jsonb default '[]'::jsonb)
+returns json
+language plpgsql
+security invoker
+as $$
+declare
+    result json;
+    args text[];
+begin
+    select coalesce(array_agg(value #>> '{}' order by ordinality), '{}')
+      into args
+      from jsonb_array_elements(params) with ordinality as t(value, ordinality);
+
+    execute format('select coalesce(json_agg(json_build_array(r.*)), ''[]''::json) from (%s) r', statement)
+       into result
+      using args;
+
+    return result;
+end;
+$$;
+
+revoke all on function public.cfni_exec(text, jsonb) from public;
+grant execute on function public.cfni_exec(text, jsonb) to authenticated;
+-- Grant to anon only if your app calls withPublicDb:
+grant execute on function public.cfni_exec(text, jsonb) to anon;