cloudflare-next-intl 0.8.4 → 0.8.6

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

@@ -14,6 +14,13 @@
  * 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.
+ *
  * Generic Drizzle SQL helpers (`excluded`, `onConflictSet`, `ago`, …) live in
  * the separate `cloudflare-next-intl/dbHelpers` entry point.
  */
@@ -21,3 +28,5 @@ 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,8 +14,16 @@
  * 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.
+ *
  * 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/inline_params.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Substitutes `$1`, `$2`, … placeholders in a generated statement with
+ * literal-encoded values, so a single-statement RPC call
+ * (`cfni_exec(statement, params default '[]')`) never needs to bind params
+ * itself — `EXECUTE ... USING` cannot bind more than one differently-typed
+ * value the way a real driver does.
+ *
+ * Placeholders inside single-quoted strings, `E'...'` escape strings,
+ * dollar-quoted bodies (`$$...$$` / `$tag$...$tag$`), double-quoted
+ * identifiers, and `--`/`/* *\/` comments are left untouched, so a literal
+ * `$1` typed by the user in a string never gets rewritten.
+ *
+ * @param statement The SQL text `drizzle-orm/pg-proxy` generated, with `$n` placeholders.
+ * @param params Positional parameter values, 1-indexed to match the placeholders.
+ * @returns The statement with every placeholder replaced by its literal.
+ * @throws If the statement references `$n` beyond `params.length`.
+ */
+export default function inlineParams(statement: string, params: unknown[]): string;

package/dist/src/db/inline_params.js

@@ -0,0 +1,118 @@
+import encodeParam from './encode_param';
+/**
+ * Substitutes `$1`, `$2`, … placeholders in a generated statement with
+ * literal-encoded values, so a single-statement RPC call
+ * (`cfni_exec(statement, params default '[]')`) never needs to bind params
+ * itself — `EXECUTE ... USING` cannot bind more than one differently-typed
+ * value the way a real driver does.
+ *
+ * Placeholders inside single-quoted strings, `E'...'` escape strings,
+ * dollar-quoted bodies (`$$...$$` / `$tag$...$tag$`), double-quoted
+ * identifiers, and `--`/`/* *\/` comments are left untouched, so a literal
+ * `$1` typed by the user in a string never gets rewritten.
+ *
+ * @param statement The SQL text `drizzle-orm/pg-proxy` generated, with `$n` placeholders.
+ * @param params Positional parameter values, 1-indexed to match the placeholders.
+ * @returns The statement with every placeholder replaced by its literal.
+ * @throws If the statement references `$n` beyond `params.length`.
+ */
+export default function inlineParams(statement, params) {
+    let result = '';
+    let i = 0;
+    const len = statement.length;
+    while (i < len) {
+        const ch = statement[i];
+        if (ch === '-' && statement[i + 1] === '-') {
+            const end = statement.indexOf('\n', i);
+            const stop = end === -1 ? len : end + 1;
+            result += statement.slice(i, stop);
+            i = stop;
+            continue;
+        }
+        if (ch === '/' && statement[i + 1] === '*') {
+            const end = statement.indexOf('*/', i + 2);
+            const stop = end === -1 ? len : end + 2;
+            result += statement.slice(i, stop);
+            i = stop;
+            continue;
+        }
+        if (ch === "'" || (ch === 'E' && statement[i + 1] === "'")) {
+            const start = ch === 'E' ? i + 1 : i;
+            const end = findStringEnd(statement, start + 1);
+            result += statement.slice(i, end);
+            i = end;
+            continue;
+        }
+        if (ch === '"') {
+            const end = findQuotedIdentifierEnd(statement, i + 1);
+            result += statement.slice(i, end);
+            i = end;
+            continue;
+        }
+        if (ch === '$' && /[0-9]/.test(statement[i + 1] ?? '')) {
+            let j = i + 1;
+            while (j < len && /[0-9]/.test(statement[j]))
+                j++;
+            const index = Number(statement.slice(i + 1, j));
+            if (index < 1 || index > params.length) {
+                throw new Error(`db: statement references $${index} but only ${params.length} param(s) were provided.`);
+            }
+            result += encodeParam(params[index - 1]);
+            i = j;
+            continue;
+        }
+        if (ch === '$') {
+            const tagEnd = findDollarQuoteEnd(statement, i);
+            result += statement.slice(i, tagEnd);
+            i = tagEnd;
+            continue;
+        }
+        result += ch;
+        i++;
+    }
+    return result;
+}
+function findStringEnd(statement, from) {
+    let i = from;
+    while (i < statement.length) {
+        if (statement[i] === "'") {
+            if (statement[i + 1] === "'") {
+                i += 2;
+                continue;
+            }
+            return i + 1;
+        }
+        if (statement[i] === '\\' && statement[i - 1] !== '\\') {
+            // Backslash escapes are only meaningful in E'' strings, but
+            // skipping the next char either way is harmless here since we
+            // are only looking for the terminating quote.
+            i += 2;
+            continue;
+        }
+        i++;
+    }
+    return statement.length;
+}
+function findQuotedIdentifierEnd(statement, from) {
+    let i = from;
+    while (i < statement.length) {
+        if (statement[i] === '"') {
+            if (statement[i + 1] === '"') {
+                i += 2;
+                continue;
+            }
+            return i + 1;
+        }
+        i++;
+    }
+    return statement.length;
+}
+function findDollarQuoteEnd(statement, from) {
+    const tagMatch = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(statement.slice(from));
+    if (!tagMatch)
+        return from + 1;
+    const tag = tagMatch[0];
+    const bodyStart = from + tag.length;
+    const closeIndex = statement.indexOf(tag, bodyStart);
+    return closeIndex === -1 ? statement.length : closeIndex + tag.length;
+}

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

@@ -0,0 +1,24 @@
+export interface InstallExecFile {
+    /** Absolute path to the file this package ships (e.g. `supabase/cfni_exec.sql`). */
+    sourcePath: string;
+    /** Absolute path to copy it to in the consuming project. */
+    targetPath: string;
+}
+export interface InstallExecOutcome {
+    targetPath: string;
+    action: 'created' | 'updated' | 'unchanged' | 'skipped-differs' | 'skipped-missing-source';
+    message: string;
+}
+/**
+ * Copies one packaged SQL file (`cfni_exec.sql` itself, or its pgTAP test
+ * file) to a target path in the consuming project, creating the target
+ * directory if needed.
+ *
+ * When the target already exists with different content, this skips the
+ * write and reports `'skipped-differs'` rather than overwriting a possibly
+ * customized file — pass `force: true` to overwrite anyway.
+ *
+ * @param file Source (this package's copy) and target (the project's copy) paths.
+ * @param force Overwrite an existing, differing target instead of skipping it.
+ */
+export declare function installExecFile(file: InstallExecFile, force: boolean): InstallExecOutcome;

package/dist/src/db/install_exec.js

@@ -0,0 +1,42 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Copies one packaged SQL file (`cfni_exec.sql` itself, or its pgTAP test
+ * file) to a target path in the consuming project, creating the target
+ * directory if needed.
+ *
+ * When the target already exists with different content, this skips the
+ * write and reports `'skipped-differs'` rather than overwriting a possibly
+ * customized file — pass `force: true` to overwrite anyway.
+ *
+ * @param file Source (this package's copy) and target (the project's copy) paths.
+ * @param force Overwrite an existing, differing target instead of skipping it.
+ */
+export function installExecFile(file, force) {
+    if (!existsSync(file.sourcePath)) {
+        return {
+            targetPath: file.targetPath,
+            action: 'skipped-missing-source',
+            message: `source file not found at ${file.sourcePath}`,
+        };
+    }
+    const sourceContent = readFileSync(file.sourcePath, 'utf-8');
+    if (existsSync(file.targetPath)) {
+        const targetContent = readFileSync(file.targetPath, 'utf-8');
+        if (targetContent === sourceContent) {
+            return { targetPath: file.targetPath, action: 'unchanged', message: 'already up to date' };
+        }
+        if (!force) {
+            return {
+                targetPath: file.targetPath,
+                action: 'skipped-differs',
+                message: `${file.targetPath} already exists with different content — pass --force to overwrite`,
+            };
+        }
+        writeFileSync(file.targetPath, sourceContent);
+        return { targetPath: file.targetPath, action: 'updated', message: 'overwritten with --force' };
+    }
+    mkdirSync(dirname(file.targetPath), { recursive: true });
+    writeFileSync(file.targetPath, sourceContent);
+    return { targetPath: file.targetPath, action: 'created', message: 'created' };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Parses one row of Postgres' composite-literal text format —
+ * `(field1,field2,...)`, comma-separated, each field either bare or
+ * `"…"`-quoted with doubled `""` for an embedded quote, and an empty bare
+ * field meaning `NULL` — into a positional array of field strings (or
+ * `null`).
+ *
+ * `cfni_exec.sql` casts every returned row with `r::text` to get this
+ * format, because it stays correct even with duplicate column names (a
+ * common shape after `select a.*, b.*`), unlike `row_to_json`, which keys
+ * fields by name and both collapses duplicates and re-encodes nested types
+ * like arrays as JSON instead of pg's own text form.
+ *
+ * @param literal A single row's `(...)`-wrapped composite-literal text.
+ * @returns The row's fields, in column order, `null` for a bare empty field.
+ */
+export default function parseComposite(literal: string): (string | null)[];

package/dist/src/db/parse_composite.js

@@ -0,0 +1,60 @@
+/**
+ * Parses one row of Postgres' composite-literal text format —
+ * `(field1,field2,...)`, comma-separated, each field either bare or
+ * `"…"`-quoted with doubled `""` for an embedded quote, and an empty bare
+ * field meaning `NULL` — into a positional array of field strings (or
+ * `null`).
+ *
+ * `cfni_exec.sql` casts every returned row with `r::text` to get this
+ * format, because it stays correct even with duplicate column names (a
+ * common shape after `select a.*, b.*`), unlike `row_to_json`, which keys
+ * fields by name and both collapses duplicates and re-encodes nested types
+ * like arrays as JSON instead of pg's own text form.
+ *
+ * @param literal A single row's `(...)`-wrapped composite-literal text.
+ * @returns The row's fields, in column order, `null` for a bare empty field.
+ */
+export default function parseComposite(literal) {
+    const fields = [];
+    let i = 1; // skip leading '('
+    const len = literal.length - 1; // index of the trailing ')'
+    // A single field, e.g. `()`, has no fields at all — every other case
+    // has at least one comma-delimited field, including a final empty one
+    // (a trailing comma right before the closing paren).
+    if (len === i)
+        return fields;
+    while (true) {
+        if (literal[i] === '"') {
+            let value = '';
+            i++;
+            while (i < len) {
+                if (literal[i] === '"') {
+                    if (literal[i + 1] === '"') {
+                        value += '"';
+                        i += 2;
+                        continue;
+                    }
+                    break;
+                }
+                value += literal[i];
+                i++;
+            }
+            i++; // closing quote
+            fields.push(value);
+        }
+        else {
+            let value = '';
+            while (i < len && literal[i] !== ',') {
+                value += literal[i];
+                i++;
+            }
+            fields.push(value === '' ? null : value);
+        }
+        if (literal[i] === ',') {
+            i++;
+            continue;
+        }
+        break;
+    }
+    return fields;
+}

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

@@ -0,0 +1,24 @@
+export type RawSqlResolution = {
+    status: 'true' | 'false';
+    reason: string;
+} | {
+    status: 'unknown';
+    reason: string;
+};
+/**
+ * Locates the project's intl config file (via the `@intl-config` alias
+ * declared in `next.config.*`) and looks for a literal `rawSql: true|false`
+ * inside it, without executing the file — codegen has no TypeScript loader
+ * and this must not run arbitrary user code.
+ *
+ * Only handles the common case: `rawSql` written as a literal boolean in
+ * the config source. A value computed from a variable, function call, or
+ * spread is not detected — callers should treat `'unknown'` as "assume
+ * `true`, but warn", matching `withPublicDb`/`withUserDb`'s own default.
+ *
+ * @param cwd Project root to search from (where `next.config.*` is expected).
+ * @returns Whether `rawSql` was found `true`/`false`, or `'unknown'` with a
+ * human-readable reason (no next.config found, no alias, no db.supabase
+ * block, or the value isn't a literal boolean).
+ */
+export default function resolveRawSql(cwd: string): RawSqlResolution;

package/dist/src/db/resolve_raw_sql.js

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+const NEXT_CONFIG_FILE_NAMES = ['next.config.ts', 'next.config.mts', 'next.config.js', 'next.config.mjs'];
+const ALIAS_PATTERN = /['"]@intl-config['"]\s*:\s*(?:path\.resolve\([^,]*,\s*)?['"]([^'"]+)['"]/;
+const RAW_SQL_PATTERN = /rawSql\s*:\s*(true|false)/;
+/**
+ * Locates the project's intl config file (via the `@intl-config` alias
+ * declared in `next.config.*`) and looks for a literal `rawSql: true|false`
+ * inside it, without executing the file — codegen has no TypeScript loader
+ * and this must not run arbitrary user code.
+ *
+ * Only handles the common case: `rawSql` written as a literal boolean in
+ * the config source. A value computed from a variable, function call, or
+ * spread is not detected — callers should treat `'unknown'` as "assume
+ * `true`, but warn", matching `withPublicDb`/`withUserDb`'s own default.
+ *
+ * @param cwd Project root to search from (where `next.config.*` is expected).
+ * @returns Whether `rawSql` was found `true`/`false`, or `'unknown'` with a
+ * human-readable reason (no next.config found, no alias, no db.supabase
+ * block, or the value isn't a literal boolean).
+ */
+export default function resolveRawSql(cwd) {
+    const nextConfigPath = NEXT_CONFIG_FILE_NAMES.map((name) => join(cwd, name)).find((path) => existsSync(path));
+    if (!nextConfigPath) {
+        return { status: 'unknown', reason: `no next.config.* found in ${cwd}` };
+    }
+    const nextConfigSource = readFileSync(nextConfigPath, 'utf-8');
+    const aliasMatch = ALIAS_PATTERN.exec(nextConfigSource);
+    if (!aliasMatch) {
+        return { status: 'unknown', reason: `no "@intl-config" alias found in ${nextConfigPath}` };
+    }
+    const aliasTarget = aliasMatch[1];
+    const configPath = resolveConfigFile(isAbsolute(aliasTarget) ? aliasTarget : resolve(dirname(nextConfigPath), aliasTarget));
+    if (!configPath) {
+        return { status: 'unknown', reason: `"@intl-config" points at ${aliasTarget}, but no matching file was found` };
+    }
+    const configSource = readFileSync(configPath, 'utf-8');
+    const rawSqlMatch = RAW_SQL_PATTERN.exec(configSource);
+    if (!rawSqlMatch) {
+        return { status: 'unknown', reason: `no literal "rawSql: true|false" found in ${configPath}` };
+    }
+    return {
+        status: rawSqlMatch[1] === 'true' ? 'true' : 'false',
+        reason: `found "rawSql: ${rawSqlMatch[1]}" in ${configPath}`,
+    };
+}
+const CONFIG_EXTENSIONS = ['', '.ts', '.tsx', '.mts', '.js', '.jsx', '.mjs'];
+function resolveConfigFile(basePath) {
+    for (const extension of CONFIG_EXTENSIONS) {
+        const candidate = `${basePath}${extension}`;
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}

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

@@ -0,0 +1,9 @@
+import { pgTable, pgSchema, pgEnum, pgPolicy, pgView, pgMaterializedView, index, uniqueIndex, unique, primaryKey, foreignKey, check, bigint, bigserial, integer, serial, smallint, smallserial, real, doublePrecision, numeric, boolean, text, varchar, char, uuid, date, time, timestamp, interval, json, jsonb, inet, cidr, macaddr, customType } from 'drizzle-orm/pg-core';
+import { sql } from 'drizzle-orm';
+/**
+ * Named re-exports of the `drizzle-orm/pg-core` schema builders used by
+ * generated Drizzle models, so codegen output can import from this package
+ * instead of taking a direct `drizzle-orm` dependency. Explicit named exports
+ * (never `export *`) keep the re-export surface tree-shakeable.
+ */
+export { pgTable, pgSchema, pgEnum, pgPolicy, pgView, pgMaterializedView, index, uniqueIndex, unique, primaryKey, foreignKey, check, bigint, bigserial, integer, serial, smallint, smallserial, real, doublePrecision, numeric, boolean, text, varchar, char, uuid, date, time, timestamp, interval, json, jsonb, inet, cidr, macaddr, customType, sql, };

package/dist/src/db/schema.js

@@ -0,0 +1,9 @@
+import { pgTable, pgSchema, pgEnum, pgPolicy, pgView, pgMaterializedView, index, uniqueIndex, unique, primaryKey, foreignKey, check, bigint, bigserial, integer, serial, smallint, smallserial, real, doublePrecision, numeric, boolean, text, varchar, char, uuid, date, time, timestamp, interval, json, jsonb, inet, cidr, macaddr, customType, } from 'drizzle-orm/pg-core';
+import { sql } from 'drizzle-orm';
+/**
+ * Named re-exports of the `drizzle-orm/pg-core` schema builders used by
+ * generated Drizzle models, so codegen output can import from this package
+ * instead of taking a direct `drizzle-orm` dependency. Explicit named exports
+ * (never `export *`) keep the re-export surface tree-shakeable.
+ */
+export { pgTable, pgSchema, pgEnum, pgPolicy, pgView, pgMaterializedView, index, uniqueIndex, unique, primaryKey, foreignKey, check, bigint, bigserial, integer, serial, smallint, smallserial, real, doublePrecision, numeric, boolean, text, varchar, char, uuid, date, time, timestamp, interval, json, jsonb, inet, cidr, macaddr, customType, sql, };

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

@@ -0,0 +1,178 @@
+/**
+ * One filter's operator and value, e.g. `{ age: ['gt', 18] }`. The bare-value
+ * form `{ id: 5 }` (see {@link SupabaseWhere}) is shorthand for `['eq', 5]`.
+ * `['not', operator, value]` negates any operator (`['not', 'eq', 5]` is
+ * `column <> 5` via PostgREST's `not.eq.5`).
+ *
+ * This is the complete operator set `@supabase/supabase-js`'s query builder
+ * exposes for `.from(table)` — there's no separate "Supabase client" query
+ * layer on top of `postgrest-js`; `supabase.from()` returns a `postgrest-js`
+ * builder directly, so this list is also the ceiling for what `supabase-js`
+ * itself can express against a single table. What's still out of reach:
+ * joins/embedded resources (pass a nested `columns` string instead — that's
+ * plain PostgREST syntax, not a filter), and anything needing more than one
+ * table in a single round-trip. Those need `cfni_exec`/`withPublicDb`/
+ * `withUserDb`, or a Postgres function called via {@link supabaseRpc}.
+ */
+export type SupabaseFilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'likeAllOf' | 'likeAnyOf' | 'ilike' | 'ilikeAllOf' | 'ilikeAnyOf' | 'regexMatch' | 'regexIMatch' | 'is' | 'isDistinct' | 'in' | 'contains' | 'containedBy' | 'overlaps' | 'rangeGt' | 'rangeGte' | 'rangeLt' | 'rangeLte' | 'rangeAdjacent';
+export type SupabaseFilterValue = unknown | [SupabaseFilterOperator, unknown] | ['not', SupabaseFilterOperator, unknown];
+/** Equality (or `[operator, value]`) filters, ANDed together column by column. */
+export type SupabaseWhere = Record<string, SupabaseFilterValue>;
+export interface SupabaseTextSearch {
+    column: string;
+    query: string;
+    type?: 'plain' | 'phrase' | 'websearch';
+    config?: string;
+}
+export interface SupabaseOrderBy {
+    column: string;
+    ascending?: boolean;
+    nullsFirst?: boolean;
+}
+export interface SupabaseSelectOptions {
+    /** Column list, PostgREST syntax (e.g. `'id,name'`, or `'*, related(*)'` for an embedded resource). Defaults to `'*'`. */
+    columns?: string;
+    /** Filters, ANDed together — see {@link SupabaseWhere}. */
+    where?: SupabaseWhere;
+    /** Shorthand for several `eq` filters at once — PostgREST's `.match()`. ANDed with `where`. */
+    match?: Record<string, unknown>;
+    /** A raw PostgREST `or()` filter string (e.g. `'age.gt.18,status.eq.active'`), for filters spanning multiple columns. ANDed with `where`/`match`. */
+    or?: string | {
+        filters: string;
+        referencedTable?: string;
+    };
+    /** Full-text search via PostgREST's `@@` operators. */
+    textSearch?: SupabaseTextSearch;
+    /** One or more `order by` clauses, applied in array order. */
+    orderBy?: SupabaseOrderBy | SupabaseOrderBy[];
+    /** Maximum rows to return. */
+    limit?: number;
+    /** Zero-indexed, inclusive `[from, to]` row range — PostgREST pagination. */
+    range?: [number, number];
+    /** Resolve to the single matching row instead of an array; errors if there isn't exactly one. */
+    single?: boolean;
+    /** Resolve to the single matching row, or `null` if there are none; errors if there's more than one. */
+    maybeSingle?: boolean;
+    /** Also return the total matching row count (`'exact'`, `'planned'`, or `'estimated'`). */
+    count?: 'exact' | 'planned' | 'estimated';
+}
+export interface SupabaseMutationOptions {
+    /** Filters, ANDed together — see {@link SupabaseWhere}. At least one of `where`/`match`/`or` is required for update/delete. */
+    where?: SupabaseWhere;
+    /** Shorthand for several `eq` filters at once. ANDed with `where`. */
+    match?: Record<string, unknown>;
+    /** A raw PostgREST `or()` filter string, for filters spanning multiple columns. ANDed with `where`/`match`. */
+    or?: string | {
+        filters: string;
+        referencedTable?: string;
+    };
+}
+export interface SupabaseUpsertOptions {
+    /** Column(s) forming the conflict target, comma-separated. Defaults to the table's primary key. */
+    onConflict?: string;
+    /** Skip (rather than update) rows that already exist. Defaults to `false`. */
+    ignoreDuplicates?: boolean;
+}
+export interface SupabaseResult<T> {
+    rows: T[];
+    /** Present only when `count` was requested on a select. */
+    count: number | null;
+}
+/**
+ * Selects rows from `table` through the Supabase REST API
+ * (`@supabase/supabase-js`'s `.from(table).select()`), as the **anonymous**
+ * role — no `cfni_exec`, no raw SQL, only what PostgREST's REST API itself
+ * supports: a column list, filters (equality or a named operator), one or
+ * more `order by` clauses, `limit`/`range` pagination, `single`/`maybeSingle`,
+ * and an optional row count.
+ *
+ * Reach for this — or {@link supabaseSelectAsUser} — instead of
+ * `withPublicDb`/`withUserDb` when `db.supabase.rawSql` is `false`, or
+ * whenever a query is simple enough that avoiding `cfni_exec` entirely is
+ * preferable. Cross-table joins/aggregates spanning more than an embedded
+ * resource (`columns: '*, related(*)'`) still need `withPublicDb`/
+ * `withUserDb`, or a Postgres function called via {@link supabaseRpc}.
+ *
+ * @param table Table (or view) name.
+ * @param options Column list, filters, ordering, pagination, count.
+ * @returns The matching rows, and the total count when `options.count` is set.
+ * @throws If `db`/`db.supabase` is not set, or PostgREST rejects the request.
+ */
+export declare function supabaseSelect<T = Record<string, unknown>>(table: string, options?: SupabaseSelectOptions): Promise<SupabaseResult<T>>;
+/**
+ * Same as {@link supabaseSelect}, but authenticated as the **signed-in
+ * user**: the bearer token comes from `db.getAccessToken`, or the signed-in
+ * Firebase user's ID token when `firebaseAuth` is configured — see
+ * {@link resolveAccessToken}. PostgREST resolves the caller as
+ * `authenticated` and RLS applies exactly as it would for `withUserDb`.
+ */
+export declare function supabaseSelectAsUser<T = Record<string, unknown>>(table: string, options?: SupabaseSelectOptions): Promise<SupabaseResult<T>>;
+/**
+ * Inserts one or more rows into `table` through the Supabase REST API, as
+ * the **anonymous** role. See {@link supabaseSelect} for when to use this
+ * over `withPublicDb`.
+ *
+ * @param table Table name.
+ * @param values A single row, or an array of rows, to insert.
+ * @returns The inserted row(s) as returned by PostgREST.
+ */
+export declare function supabaseInsert<T = Record<string, unknown>>(table: string, values: Record<string, unknown> | Record<string, unknown>[]): Promise<T[]>;
+/** Same as {@link supabaseInsert}, authenticated as the signed-in user — see {@link supabaseSelectAsUser}. */
+export declare function supabaseInsertAsUser<T = Record<string, unknown>>(table: string, values: Record<string, unknown> | Record<string, unknown>[]): Promise<T[]>;
+/**
+ * Inserts one or more rows into `table`, or updates them on a conflict —
+ * PostgREST's `upsert`, i.e. `insert ... on conflict (...) do update`. As
+ * the **anonymous** role.
+ *
+ * @param table Table name.
+ * @param values A single row, or an array of rows, to upsert.
+ * @param options `onConflict` (defaults to the table's primary key) and
+ * `ignoreDuplicates` (skip instead of update on conflict).
+ * @returns The upserted row(s) as returned by PostgREST.
+ */
+export declare function supabaseUpsert<T = Record<string, unknown>>(table: string, values: Record<string, unknown> | Record<string, unknown>[], options?: SupabaseUpsertOptions): Promise<T[]>;
+/** Same as {@link supabaseUpsert}, authenticated as the signed-in user — see {@link supabaseSelectAsUser}. */
+export declare function supabaseUpsertAsUser<T = Record<string, unknown>>(table: string, values: Record<string, unknown> | Record<string, unknown>[], options?: SupabaseUpsertOptions): Promise<T[]>;
+/**
+ * Updates rows in `table` matching `options.where` through the Supabase
+ * REST API, as the **anonymous** role. See {@link supabaseSelect} for when
+ * to use this over `withPublicDb`.
+ *
+ * @param table Table name.
+ * @param values Columns to set.
+ * @param options `where` — filters selecting which rows to update; required,
+ * since an unfiltered update would touch every row.
+ * @returns The updated rows as returned by PostgREST.
+ */
+export declare function supabaseUpdate<T = Record<string, unknown>>(table: string, values: Record<string, unknown>, options: SupabaseMutationOptions): Promise<T[]>;
+/** Same as {@link supabaseUpdate}, authenticated as the signed-in user — see {@link supabaseSelectAsUser}. */
+export declare function supabaseUpdateAsUser<T = Record<string, unknown>>(table: string, values: Record<string, unknown>, options: SupabaseMutationOptions): Promise<T[]>;
+/**
+ * Deletes rows in `table` matching `options.where` through the Supabase REST
+ * API, as the **anonymous** role. See {@link supabaseSelect} for when to
+ * use this over `withPublicDb`.
+ *
+ * @param table Table name.
+ * @param options `where` — filters selecting which rows to delete; required,
+ * since an unfiltered delete would remove every row.
+ * @returns The deleted rows as returned by PostgREST.
+ */
+export declare function supabaseDelete<T = Record<string, unknown>>(table: string, options: SupabaseMutationOptions): Promise<T[]>;
+/** Same as {@link supabaseDelete}, authenticated as the signed-in user — see {@link supabaseSelectAsUser}. */
+export declare function supabaseDeleteAsUser<T = Record<string, unknown>>(table: string, options: SupabaseMutationOptions): Promise<T[]>;
+/**
+ * Calls a Postgres function through PostgREST's `.rpc()` — the same
+ * mechanism `cfni_exec` itself uses, but for a function you define yourself.
+ * This is how to run anything the `select`/`insert`/`upsert`/`update`/
+ * `delete` helpers above can't express (joins, aggregates, custom logic)
+ * without needing `cfni_exec`/raw SQL: write a regular Postgres function,
+ * `grant execute` to `anon`/`authenticated`, and call it by name.
+ *
+ * As the **anonymous** role.
+ *
+ * @param fn Function name.
+ * @param args Named arguments, matching the function's parameter names.
+ */
+export declare function supabaseRpc<T = unknown>(fn: string, args?: Record<string, unknown>): Promise<T>;
+/** Same as {@link supabaseRpc}, authenticated as the signed-in user — see {@link supabaseSelectAsUser}. */
+export declare function supabaseRpcAsUser<T = unknown>(fn: string, args?: Record<string, unknown>): Promise<T>;