cloudflare-next-intl 0.8.6 → 0.8.8

package/README.md

@@ -74,6 +74,48 @@ export default nextConfig;
 If this alias is missing, any import from `cloudflare-next-intl` throws an
 error naming the missing `@intl-config` alias at startup.
 
+### 2b. Deploying to Cloudflare Workers: alias it in `wrangler.toml` too
+
+`wrangler deploy`/`wrangler dev` bundle the Worker with their own esbuild
+pass, separate from Next's webpack/Turbopack build — the `next.config`
+alias above doesn't apply to it. Without this, `wrangler deploy` fails with
+`Could not resolve "@intl-config"`. Path is relative to `wrangler.toml`.
+
+```toml
+# wrangler.toml
+[alias]
+"@intl-config" = "./src/i18n/intl_config.ts"
+```
+
+Put `[alias]` after all top-level scalar keys (`name`, `main`,
+`compatibility_date`, `compatibility_flags`, etc.) and before any other
+`[table]`/`[[array_of_tables]]` header — TOML assigns every key that follows
+a table header to that table until the next header, so an `[alias]` placed
+earlier silently swallows the keys meant for the top level.
+
+**In a monorepo, give every Worker its own alias target — never point two
+Workers' `[alias]` at the same shared config file.** Declaring `[alias]`
+makes Wrangler eagerly resolve and bundle whatever it points to, even if
+nothing in that Worker's own code imports `@intl-config`. If a second,
+smaller Worker (e.g. a cron/background worker) points its alias at the main
+app's config file, it inherits that file's whole import graph — every
+package the main app's config touches (Firebase, a DB client, `zod`, etc.)
+must then be a dependency of the small Worker too, or the build fails with
+`Could not resolve "<package>"` for packages that Worker never actually
+uses. Give it its own minimal file instead:
+
+```typescript
+// backend/src/i18n/intl_config.ts — deliberately minimal, not the main
+// app's config: aliasing it there would drag in every dependency that
+// config touches, even ones this Worker never imports.
+import { setIntlConfig } from "cloudflare-next-intl";
+
+export default setIntlConfig({
+    locales: ["en"],
+    defaultLocale: "en",
+});
+```
+
 ### 3. Wire up the middleware
 
 ```typescript
@@ -535,82 +577,60 @@ so arrays/`numeric`/timestamps/`bytea` decode the same way they do in
 connection-string mode. Not supported: multi-statement transactions (each
 call is its own PostgREST round-trip — see above).
 
-#### Supabase mode without `cfni_exec`
+#### Supabase mode and REST translation
 
-If you don't want to install `cfni_exec` at all, set `db.supabase.rawSql:
-false`. `withPublicDb`/`withUserDb` then throw immediately in Supabase mode
-instead of failing later against PostgREST, and you reach Postgres instead
-through a set of helpers that call `@supabase/supabase-js`'s `.from()`/`.rpc()`
-API directly — the same REST surface the Supabase client itself uses, no raw
-SQL involved:
+You write the exact same Drizzle code with `withPublicDb`/`withUserDb` in Supabase mode as in connection-string mode. Behind the scenes, the transport translates each statement into `@supabase/supabase-js` `.from()` PostgREST calls whenever possible:
 
 ```typescript
-import { supabaseSelect, supabaseInsert, supabaseUpdate, supabaseDelete, supabaseUpsert, supabaseRpc } from "cloudflare-next-intl/db";
+import { withPublicDb, withUserDb } from "cloudflare-next-intl/db";
+import { eq, gte, desc } from "cloudflare-next-intl/dbHelpers";
+
+// Automatically translated to PostgREST REST calls:
+const rows = await withPublicDb((db) =>
+    db.select({ id: bonds.id, name: bonds.name, yield: bonds.yield })
+        .from(bonds)
+        .where(gte(bonds.yield, 5))
+        .orderBy(desc(bonds.yield))
+        .limit(10)
+);
+
+await withPublicDb((db) => db.insert(bonds).values({ name: "10Y", yield: 4.2 }));
+await withPublicDb((db) =>
+    db.insert(bonds)
+        .values({ id: 1, name: "10Y", yield: 4.5 })
+        .onConflictDoUpdate({ target: bonds.id, set: { yield: 4.5 } })
+);
+await withPublicDb((db) => db.update(bonds).set({ yield: 4.3 }).where(eq(bonds.id, 1)));
+await withPublicDb((db) => db.delete(bonds).where(eq(bonds.id, 1)));
+```
 
-const { rows } = await supabaseSelect("bonds", {
-    where: { active: true, yield: ["gte", 5] },
-    orderBy: { column: "yield", ascending: false },
-    limit: 10,
-});
+**Transport routing:**
+1. **REST translation first:** Single-table `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `on conflict`, and `returning` are mapped to `@supabase/supabase-js` `.from()` calls.
+2. **`cfni_exec` fallback:** Statements PostgREST cannot express (joins, CTEs, complex subqueries) fall back to the `cfni_exec` SQL-exec function.
+3. **`rawSql: false` mode:** If `db.supabase.rawSql: false` is configured (when `cfni_exec` is not installed), any statement requiring raw SQL throws an error explaining the limitation and how to resolve it.
+
+| Operation | REST API | `cfni_exec` fallback |
+| --- | --- | --- |
+| Single-table `SELECT` (projections, `count(*)`, `WHERE`, `ORDER BY`, `LIMIT`, `OFFSET`) | Supported | Used if untranslatable |
+| Single-table `INSERT` / `UPDATE` / `DELETE` | Supported | Used if untranslatable |
+| `ON CONFLICT DO NOTHING / UPDATE` | Supported | Supported |
+| `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 | Not supported | Not supported (Postgres connection only) |
+
+#### Enforcing single API via ESLint (`cloudflare-next-intl/dbEslint`)
+
+To prevent application code from bypassing the single `db` API with direct driver imports (`@supabase/supabase-js`, `pg`, `postgres`, or deep `dist/` paths), spread the shipped flat-config fragment in your `eslint.config.js`:
+
+```typescript
+import dbEslint from "cloudflare-next-intl/dbEslint";
 
-await supabaseInsert("bonds", { name: "10Y", yield: 4.2 });
-await supabaseUpsert("bonds", { id: 1, yield: 4.5 }, { onConflict: "id" });
-await supabaseUpdate("bonds", { yield: 4.3 }, { where: { id: 1 } });
-await supabaseDelete("bonds", { where: { id: 1 } });
-
-// Anything a plain select/insert/update/delete/upsert can't express (joins,
-// aggregates, custom logic) — write a Postgres function, `grant execute` to
-// `anon`/`authenticated`, and call it by name. No cfni_exec needed for this
-// either, since PostgREST always supports calling a named function you own.
-const total = await supabaseRpc("total_yield", { bond_ids: [1, 2, 3] });
-```
-
-Each has a `*AsUser` counterpart (`supabaseSelectAsUser`,
-`supabaseInsertAsUser`, `supabaseUpsertAsUser`, `supabaseUpdateAsUser`,
-`supabaseDeleteAsUser`, `supabaseRpcAsUser`) that authenticates as the
-signed-in user instead of anon — same token resolution as `withUserDb`
-(`db.getAccessToken`, or the signed-in Firebase user's ID token), so RLS
-applies the same way.
-
-`supabaseSelect`/`supabaseSelectAsUser` accept:
-
-- `columns` — PostgREST column-list syntax. Defaults to `'*'`. Supports an
-  embedded resource for a foreign-key join in one round-trip, e.g.
-  `'*, author(name)'`.
-- `where` — filters, ANDed together. A bare value (`{ id: 5 }`) is shorthand
-  for `eq`; use `{ column: [operator, value] }` for any other operator —
-  `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `likeAllOf`, `likeAnyOf`, `ilike`,
-  `ilikeAllOf`, `ilikeAnyOf`, `regexMatch`, `regexIMatch`, `is`,
-  `isDistinct`, `in`, `contains`, `containedBy`, `overlaps`, `rangeGt`,
-  `rangeGte`, `rangeLt`, `rangeLte`, or `rangeAdjacent` — or
-  `{ column: ['not', operator, value] }` to negate any of them. This is the
-  complete operator set `@supabase/supabase-js`'s `.from()` builder exposes
-  (it *is* a `postgrest-js` builder — there's no separate, larger "Supabase
-  client" query surface on top of it).
-- `match` — shorthand for several `eq` filters at once (`{ status: 'active',
-  archived: false }`). ANDed with `where`.
-- `or` — a raw PostgREST `or()` filter string (e.g.
-  `'age.gt.18,status.eq.active'`) for filters spanning multiple columns in
-  one clause; ANDed with `where`/`match`.
-- `textSearch` — `{ column, query, type?, config? }` for full-text search via
-  PostgREST's `@@` operators.
-- `orderBy` — one `{ column, ascending?, nullsFirst? }`, or an array for
-  multiple `order by` clauses.
-- `limit` / `range` — row limit, or a `[from, to]` PostgREST pagination range.
-- `single` / `maybeSingle` — resolve to one row (erroring if there isn't
-  exactly one), or one row or `null` (erroring if there's more than one).
-- `count` — also return the total matching row count (`'exact'`, `'planned'`,
-  or `'estimated'`).
-
-`supabaseUpdate`/`supabaseDelete` (and their `*AsUser` forms) accept `where`/
-`match`/`or` the same way, and require at least one of them — an unfiltered
-update/delete would otherwise touch every row.
-
-This mode trades capability for not needing `cfni_exec`: everything the
-Supabase JS client itself can express against a single table (including an
-embedded-resource join) works; multi-table joins beyond that, aggregates,
-window functions, and raw SQL of any kind do not — those need `cfni_exec`, or
-a Postgres function called via `supabaseRpc`.
+export default [
+    ...dbEslint,
+    // your other configs...
+];
+```
 
 Two query wrappers, both from `cloudflare-next-intl/db`. Choose by who is
 allowed to see the rows:
@@ -786,6 +806,16 @@ untested:
   55432:5432 postgres:15`), so it never runs — and never needs a database —
   during a normal `npm test`.
 
+## AI Agent Setup & Conventions
+
+When using AI coding assistants (Claude Code, Cursor, Copilot, Antigravity) with `cloudflare-next-intl`:
+
+- **One Database API**: Always use `withPublicDb` or `withUserDb` from `cloudflare-next-intl/db`. Never import `@supabase/supabase-js`, `pg`, or `postgres` in application code.
+- **Drizzle Schema & Helpers**: Always import schema definitions from `cloudflare-next-intl/dbSchema` (`pgTable`, `text`, `timestamp`, `uuid`, etc.) and query operators from `cloudflare-next-intl/dbHelpers` (`eq`, `and`, `or`, `inArray`, `count`, etc.).
+- **Lint Enforcement**: Spread `...dbEslint` from `cloudflare-next-intl/dbEslint` in `eslint.config.js` to catch accidental driver imports.
+- **Reference Document**: Direct AI tools to `llms.txt` in this package for concise rules and subpath exports.
+
 ## License
 
 MIT
+

package/dist/src/db/context.js

@@ -27,19 +27,11 @@ async function resolveUserId(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.');
 }
-function requireRawSql(supabase) {
-    if (supabase.rawSql === false) {
-        throw new Error('db: withPublicDb/withUserDb need `cfni_exec` to run SQL in Supabase mode, but ' +
-            '`db.supabase.rawSql` is set to `false`. Use `supabaseSelect`/`supabaseInsert`/' +
-            '`supabaseUpdate`/`supabaseDelete` instead, which call the Supabase REST API directly.');
-    }
-}
 /**
  * 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) {
-    requireRawSql(supabase);
     const { drizzle } = await import('drizzle-orm/pg-proxy');
     const db = drizzle(createSupabaseTransport(supabase, bearerToken));
     return Object.assign(db, {

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

@@ -0,0 +1,21 @@
+/**
+ * A flat-config fragment consumers can spread into their `eslint.config.*` to
+ * keep application code on the single `db` API.
+ *
+ * The runtime already refuses to give out a raw client, but an import of
+ * `@supabase/supabase-js` or a deep `dist/` path is how that guarantee gets
+ * bypassed in practice, so it is worth failing at lint time where the fix is
+ * cheap.
+ */
+declare const dbEslintConfig: {
+    rules: {
+        'no-restricted-imports': (string | {
+            paths: {
+                name: string;
+                message: string;
+            }[];
+            patterns: string[];
+        })[];
+    };
+}[];
+export default dbEslintConfig;

package/dist/src/db/eslint_config.js

@@ -0,0 +1,29 @@
+const MESSAGE = 'Query the database through `withPublicDb`/`withUserDb` from cloudflare-next-intl/db. ' +
+    'The package picks the transport (direct Postgres, cfni_exec, or PostgREST) for you.';
+/**
+ * A flat-config fragment consumers can spread into their `eslint.config.*` to
+ * keep application code on the single `db` API.
+ *
+ * The runtime already refuses to give out a raw client, but an import of
+ * `@supabase/supabase-js` or a deep `dist/` path is how that guarantee gets
+ * bypassed in practice, so it is worth failing at lint time where the fix is
+ * cheap.
+ */
+const dbEslintConfig = [
+    {
+        rules: {
+            'no-restricted-imports': [
+                'error',
+                {
+                    paths: [
+                        { name: '@supabase/supabase-js', message: MESSAGE },
+                        { name: 'pg', message: MESSAGE },
+                        { name: 'postgres', message: MESSAGE },
+                    ],
+                    patterns: ['cloudflare-next-intl/dist/*'],
+                },
+            ],
+        },
+    },
+];
+export default dbEslintConfig;

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

@@ -14,12 +14,11 @@
  * load through dynamic `import()` inside these functions, so an app that
  * never calls a `db` export never bundles any of them.
  *
- * When `db.supabase.rawSql` is `false` (or `cfni_exec` can't be installed),
- * `withPublicDb`/`withUserDb` throw instead of running in Supabase mode; use
- * `supabaseSelect`/`supabaseInsert`/`supabaseUpsert`/`supabaseUpdate`/
- * `supabaseDelete`/`supabaseRpc` (and their `*AsUser` counterparts) instead —
- * they call `@supabase/supabase-js`'s `.from()`/`.rpc()` API directly, no
- * `cfni_exec`, no raw SQL, only what PostgREST's REST API itself supports.
+ * You write the same Drizzle code either way. In Supabase mode each generated
+ * 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. `.transaction()` is never available in Supabase mode.
  *
  * Generic Drizzle SQL helpers (`excluded`, `onConflictSet`, `ago`, …) live in
  * the separate `cloudflare-next-intl/dbHelpers` entry point.
@@ -28,5 +27,3 @@ export { withPublicDb, withUserDb } from './context';
 export type { DrizzleDb } from './context';
 export { default as connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';
 export type { DbRoutingConfig } from '../types/types';
-export { supabaseSelect, supabaseSelectAsUser, supabaseInsert, supabaseInsertAsUser, supabaseUpsert, supabaseUpsertAsUser, supabaseUpdate, supabaseUpdateAsUser, supabaseDelete, supabaseDeleteAsUser, supabaseRpc, supabaseRpcAsUser, } from './supabase_rest';
-export type { SupabaseWhere, SupabaseFilterOperator, SupabaseFilterValue, SupabaseOrderBy, SupabaseTextSearch, SupabaseSelectOptions, SupabaseMutationOptions, SupabaseUpsertOptions, SupabaseResult, } from './supabase_rest';

package/dist/src/db/index.js

@@ -14,16 +14,14 @@
  * load through dynamic `import()` inside these functions, so an app that
  * never calls a `db` export never bundles any of them.
  *
- * When `db.supabase.rawSql` is `false` (or `cfni_exec` can't be installed),
- * `withPublicDb`/`withUserDb` throw instead of running in Supabase mode; use
- * `supabaseSelect`/`supabaseInsert`/`supabaseUpsert`/`supabaseUpdate`/
- * `supabaseDelete`/`supabaseRpc` (and their `*AsUser` counterparts) instead —
- * they call `@supabase/supabase-js`'s `.from()`/`.rpc()` API directly, no
- * `cfni_exec`, no raw SQL, only what PostgREST's REST API itself supports.
+ * You write the same Drizzle code either way. In Supabase mode each generated
+ * 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. `.transaction()` is never available in Supabase mode.
  *
  * 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';
-export { supabaseSelect, supabaseSelectAsUser, supabaseInsert, supabaseInsertAsUser, supabaseUpsert, supabaseUpsertAsUser, supabaseUpdate, supabaseUpdateAsUser, supabaseDelete, supabaseDeleteAsUser, supabaseRpc, supabaseRpcAsUser, } from './supabase_rest';

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

@@ -0,0 +1,76 @@
+import { type SqlValue, type WhereNode } from './parse_where';
+/** One selected/returned column, with its output name when aliased. */
+export interface Projection {
+    column: string;
+    alias?: string;
+}
+/** One `order by` term. */
+export interface OrderBy {
+    column: string;
+    ascending: boolean;
+    nullsFirst?: boolean;
+}
+/** A single-table `select` reduced to what PostgREST can express. */
+export interface ParsedSelect {
+    kind: 'select';
+    table: string;
+    projection: Projection[] | 'all' | 'count';
+    where?: WhereNode;
+    orderBy: OrderBy[];
+    limit?: SqlValue;
+    offset?: SqlValue;
+}
+/** The `excluded.<column>` reference an upsert's `do update set` may use. */
+export interface ExcludedRef {
+    kind: 'excluded';
+    column: string;
+}
+/** A parsed `on conflict` clause. */
+export type OnConflict = {
+    columns: string[];
+    action: 'nothing';
+} | {
+    columns: string[];
+    action: 'update';
+    set: Record<string, SqlValue | ExcludedRef>;
+};
+/** A single-table `insert`, optionally an upsert, optionally `returning`. */
+export interface ParsedInsert {
+    kind: 'insert';
+    table: string;
+    columns: string[];
+    rows: SqlValue[][];
+    onConflict?: OnConflict;
+    returning?: Projection[] | 'all';
+}
+/** A single-table `update`. */
+export interface ParsedUpdate {
+    kind: 'update';
+    table: string;
+    set: Record<string, SqlValue>;
+    where?: WhereNode;
+    returning?: Projection[] | 'all';
+}
+/** A single-table `delete`. */
+export interface ParsedDelete {
+    kind: 'delete';
+    table: string;
+    where?: WhereNode;
+    returning?: Projection[] | 'all';
+}
+/** Any statement the REST executor knows how to run. */
+export type ParsedStatement = ParsedSelect | ParsedInsert | ParsedUpdate | ParsedDelete;
+/**
+ * Parses a generated statement into the smallest description the REST
+ * executor needs, rejecting anything PostgREST's single-table API cannot do.
+ *
+ * The parser is deliberately strict: a statement it does not fully understand
+ * must raise rather than translate approximately, because the transport reads
+ * a raise as "send this to `cfni_exec` instead" and a wrong translation would
+ * silently return wrong rows.
+ *
+ * @param sql The generated statement text, `$n` placeholders included.
+ * @returns The parsed statement.
+ * @throws {UnsupportedSqlError} If the statement is outside the supported subset.
+ */
+export default function parseStatement(sql: string): ParsedStatement;