@xylex-group/athena 3.3.0 → 3.5.1

package/dist/cloudflare.d.ts

@@ -0,0 +1,368 @@
+import { ah as AthenaClientCapabilities, dE as D1DatabaseLike, dF as D1ResultLike, dG as AthenaGatewayClient, ag as AthenaClient, dH as R2BucketLike, aA as AthenaRequestContext, aB as AthenaRequestContextProvider, A as AthenaAuthConfig, dI as CloudflareR2StorageModule, ak as AthenaClientWithR2Storage, di as AthenaExecutionMode, al as AthenaDbConfig, g as AthenaChatConfig, aV as AthenaStorageConfig, a as AthenaBillingConfig, dJ as AthenaDiagnosticsMode, dq as AthenaQueryTraceOptions, dj as AthenaExecutionPrefer, ds as AthenaResolvedExecutionMode, ai as AthenaClientConfig } from './v3-client-OAai_JNs.js';
+export { dK as ATHENA_EXECUTION_MODE_ENV_KEY, dL as ATHENA_EXECUTION_PREFER_ENV_KEY, dM as AthenaDbCapabilities, dN as AthenaStorageCapabilities, dO as CloudflareR2GetObjectResult, dP as CloudflareR2ListObjectsInput, dQ as CloudflareR2ListObjectsResult, dR as CloudflareR2ObjectStorage, dS as CloudflareR2PutBody, dT as CloudflareR2PutObjectInput, dU as ResolveAthenaExecutionModeInput, dV as createCloudflareR2StorageModule, dC as resolveAthenaExecutionMode } from './v3-client-OAai_JNs.js';
+import { u as AthenaFetchPayload, v as AthenaDeletePayload, w as AthenaInsertPayload, x as AthenaUpdatePayload, o as BackendConfig, p as BackendType } from './types-B2RZPivM.js';
+import { r as AthenaClientModelsInput } from './types-S-bTMPiM.js';
+import './types-BVKpQmfY.js';
+import './module-C_ab-MM1.js';
+
+declare function createGatewayCapabilities(options?: {
+    engine?: AthenaClientCapabilities['db']['engine'];
+    authRemote?: boolean;
+    /** When false/undefined, storage flags match an unconfigured storage namespace. */
+    storageConfigured?: boolean;
+    storageCatalogs?: boolean;
+    storageBackups?: boolean;
+}): AthenaClientCapabilities;
+declare function createCloudflareEdgeCapabilities(options: {
+    hasR2: boolean;
+    /** Hybrid remote Athena root enables remote object storage without an R2 binding. */
+    hasRemoteStorage?: boolean;
+    authRemote: boolean;
+    findManyAst?: boolean;
+}): AthenaClientCapabilities;
+
+/**
+ * Pure D1 execution helpers shared by edge-local SDK transport and (later)
+ * apps/cloudflare-d1-proxy.
+ */
+
+type D1RunnerSessionInput = {
+    bookmark?: string | null;
+    sessionMode?: string | null;
+};
+type D1QueryInput = D1RunnerSessionInput & {
+    query: string;
+    params?: unknown[];
+};
+type D1BatchStatementInput = {
+    query: string;
+    params?: unknown[];
+};
+type D1BatchInput = D1RunnerSessionInput & {
+    statements: D1BatchStatementInput[];
+};
+type D1RunnerQuerySuccess = {
+    ok: true;
+    rows: unknown[];
+    columns: string[];
+    durationMs?: number;
+    count: number;
+    bookmark: string | null;
+    meta: Record<string, unknown>;
+    statementCount?: number;
+};
+type D1RunnerQueryFailure = {
+    ok: false;
+    error: string;
+    message: string;
+};
+type D1RunnerQueryResult = D1RunnerQuerySuccess | D1RunnerQueryFailure;
+type D1RunnerBatchSuccess = {
+    ok: true;
+    results: D1ResultLike<unknown>[];
+    bookmark: string | null;
+};
+type D1RunnerBatchResult = D1RunnerBatchSuccess | D1RunnerQueryFailure;
+/**
+ * True when `keyword` appears as a SQL keyword outside string/identifier literals
+ * and comments (case-insensitive). Used so `RETURNING` inside string values does
+ * not force the all() result path.
+ */
+declare function sqlContainsKeywordOutsideLiterals(sql: string, keyword: string): boolean;
+/**
+ * First bare SQL keyword outside leading comments / whitespace / literals.
+ * Used so `-- note\nSELECT …` still classifies as row-producing.
+ */
+declare function sqlFirstKeywordOutsideLiterals(sql: string): string | null;
+/**
+ * Whether a prepared statement is expected to return a result set via all().
+ * Leading comments, CTE terminal statements, and RETURNING (outside literals)
+ * are handled.
+ */
+declare function statementExpectsResultRows(sql: string): boolean;
+/**
+ * Split SQL into statements without treating `;` inside string literals,
+ * quoted identifiers, comments, or SQLite trigger bodies as separators.
+ *
+ * Trigger DDL (`CREATE TRIGGER ... BEGIN ...; ...; END`) keeps the body as one
+ * statement. Nested `CASE ... END` inside the body does not close the trigger.
+ * Bare transaction `BEGIN` / `BEGIN TRANSACTION` is not treated as a body opener.
+ */
+declare function splitSqlStatements(query: string): string[];
+/**
+ * Detect multiple SQL statements without treating `;` inside string literals,
+ * quoted identifiers, comments, or trigger bodies as separators.
+ */
+declare function isMultiStatement(query: string): boolean;
+/**
+ * Execute a single query (or multi-statement `exec`) against a D1 binding.
+ */
+declare function executeD1Query(db: D1DatabaseLike, input: D1QueryInput): Promise<D1RunnerQueryResult>;
+/**
+ * Execute a batch of prepared statements against a D1 binding.
+ */
+declare function executeD1Batch(db: D1DatabaseLike, input: D1BatchInput): Promise<D1RunnerBatchResult>;
+
+/**
+ * L1 D1/SQLite SQL compiler for flat gateway payloads.
+ * Aligned with gateway D1 matrix: flat select/insert/update/delete + upsert.
+ */
+
+type D1CompiledStatement = {
+    sql: string;
+    params: unknown[];
+};
+/**
+ * One or more statements. Sparse multi-row inserts without NULL-coercion expand
+ * into a batch of single-row inserts (SQLite rejects `DEFAULT` in VALUES tuples).
+ */
+type D1CompiledSql = D1CompiledStatement & {
+    statements?: D1CompiledStatement[];
+};
+/** Optional compile-time options for D1 SQL compilation. */
+type D1CompileOptions = {
+    /**
+     * Proven single-column unique identity for bounded UPDATE/DELETE (from
+     * PRAGMA table_info / unique indexes, or an explicit caller override).
+     * Required for limit/offset/page bounded mutations.
+     */
+    identityColumn?: string;
+};
+declare class D1SqlCompileError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Compile flat gateway fetch to SQLite SELECT.
+ * When `head: true`, compiles a COUNT(*) query (no row body).
+ */
+declare function compileD1Fetch(payload: AthenaFetchPayload): D1CompiledSql;
+/**
+ * COUNT(*) for the same filters as a fetch (used for head and exact totals).
+ */
+declare function compileD1Count(payload: AthenaFetchPayload): D1CompiledSql;
+declare function extractAthenaCount(rows: unknown[]): number;
+
+/**
+ * Compile insert / upsert for D1.
+ *
+ * SQLite does not allow `DEFAULT` inside multi-row VALUES tuples. Sparse multi-row
+ * inserts without `default_to_null` become a batch of single-row inserts so omitted
+ * columns keep true DB defaults.
+ */
+declare function compileD1Insert(payload: AthenaInsertPayload): D1CompiledSql;
+/**
+ * Compile update with required filters.
+ * Pagination / sort bounds use a unique-identity IN (subquery) so only one page is updated.
+ */
+declare function compileD1Update(payload: AthenaUpdatePayload, options?: D1CompileOptions): D1CompiledSql;
+/**
+ * Compile delete with required filters.
+ *
+ * `payload.resource_id` alone (no column filter) maps to `id = ?` for the common
+ * Athena PK path. Explicit `.eq('resource_id', …)` / other filters are preserved
+ * so tables with a real `resource_id` column are not rewritten to `id`.
+ */
+declare function compileD1Delete(payload: AthenaDeletePayload, options?: D1CompileOptions): D1CompiledSql;
+
+/**
+ * Strip Postgres cast suffixes and normalize a few operators so UUID equality
+ * plans like `"id"::text = '…'::text` execute on D1.
+ * String/identifier literals are left unchanged.
+ */
+declare function rewritePostgresSqlForSqlite(sql: string): string;
+
+type CloudflareD1TransportOptions = {
+    d1: D1DatabaseLike;
+    /** Default D1 session mode when headers omit session mode. */
+    defaultSessionMode?: string | null;
+};
+/**
+ * Resolve a single-column unique identity for bounded mutations from live D1
+ * schema (PRAGMA table_info + index_list). Prefer PRIMARY KEY; else a single-
+ * column UNIQUE index. Multi-column keys are rejected as unsafe for IN-subquery.
+ */
+declare function resolveD1BoundedIdentityColumn(d1: D1DatabaseLike, tableName: string, session?: {
+    bookmark?: string | null;
+    sessionMode?: string | null;
+}): Promise<string>;
+/**
+ * Gateway-shaped transport that executes against a Worker D1 binding.
+ */
+declare function createCloudflareD1GatewayTransport(options: CloudflareD1TransportOptions): AthenaGatewayClient;
+
+/**
+ * Edge-only client façade over {@link createClient}.
+ * Prefer `createClient({ db: { d1 }, storage: { r2 } })` for new code (ADR 0001).
+ * This helper maps the historical top-level `d1` / `r2` shape onto that spine.
+ */
+
+interface CloudflareAthenaClientConfig<TModels extends AthenaClientModelsInput | undefined = undefined> {
+    /** D1 database binding (e.g. env.DB). */
+    d1: D1DatabaseLike;
+    /** Optional R2 bucket binding for L3a object I/O. */
+    r2?: R2BucketLike;
+    /** Object key prefix for R2. */
+    storagePrefix?: string;
+    /** Default D1 session mode (`first-unconstrained`, `first-primary`, …). */
+    sessionMode?: string | null;
+    /**
+     * Optional unified / remote Athena URL for hybrid services (auth, billing).
+     * Not required for pure D1/R2 local mode.
+     */
+    url?: string | null;
+    /**
+     * API key for remote hybrid services.
+     * Pure edge-local mode gets a local sentinel via {@link createClient} when omitted.
+     * Hybrid configs (`url` set) must not pre-fill that sentinel — leave unset so
+     * `createClient` / resolveCore can read `ATHENA_API_KEY` (etc.) from `env`.
+     */
+    key?: string | null;
+    client?: string | null;
+    models?: TModels;
+    headers?: Record<string, string>;
+    context?: AthenaRequestContext | AthenaRequestContextProvider;
+    auth?: AthenaAuthConfig;
+    env?: Record<string, string | undefined>;
+    retryReads?: boolean;
+    debugAst?: boolean;
+    findManyAst?: boolean;
+    traceQueries?: boolean;
+}
+type CloudflareAthenaClientConfigWithR2<TModels extends AthenaClientModelsInput | undefined = undefined> = CloudflareAthenaClientConfig<TModels> & {
+    r2: R2BucketLike;
+};
+type CloudflareAthenaClient<TModels extends AthenaClientModelsInput | undefined = undefined> = AthenaClient<TModels> & {
+    readonly capabilities: AthenaClientCapabilities;
+};
+/** Edge client with L3a R2 object methods typed on `storage`. */
+type CloudflareAthenaClientWithR2<TModels extends AthenaClientModelsInput | undefined = undefined> = Omit<CloudflareAthenaClient<TModels>, 'storage' | 'withContext'> & {
+    readonly storage: CloudflareR2StorageModule;
+    withContext(context: AthenaRequestContext): CloudflareAthenaClientWithR2<TModels>;
+};
+/**
+ * Create an Athena client that executes DB operations against a D1 binding
+ * (and optional R2 for object storage) inside a Cloudflare Worker.
+ *
+ * Thin façade over {@link createClient}:
+ * ```ts
+ * createClient({
+ *   db: { d1: env.DB, sessionMode },
+ *   storage: { r2: env.FILES, prefix: storagePrefix },
+ *   url, key, ...
+ * })
+ * ```
+ *
+ * To switch between edge and gateway at runtime, prefer {@link createAthenaRuntime}.
+ */
+declare function createCloudflareClient<const TModels extends AthenaClientModelsInput | undefined = undefined>(config: CloudflareAthenaClientConfigWithR2<TModels>): CloudflareAthenaClientWithR2<TModels>;
+declare function createCloudflareClient<const TModels extends AthenaClientModelsInput | undefined = undefined>(config: CloudflareAthenaClientConfig<TModels>): CloudflareAthenaClient<TModels>;
+
+/**
+ * Switchable Athena runtime façades over {@link createClient}.
+ *
+ * Prefer `createClient({ db: { d1 }, storage: { r2 }, mode, prefer, url, key })` directly.
+ * These helpers only map Worker/top-level shapes onto that single constructor.
+ *
+ * @see docs/cloudflare-edge-local.md
+ * @see ADR 0015 / 0016 / 0019
+ */
+
+interface AthenaRuntimeConfig<TModels extends AthenaClientModelsInput | undefined = undefined> {
+    /**
+     * `gateway` — HTTP to athena_rs (server).
+     * `edge` — D1/R2 bindings in-process.
+     * `auto` — edge when `d1` is set, else gateway when `url` / env URL is set.
+     * Default: `auto` (overridable via `ATHENA_EXECUTION_MODE`).
+     */
+    mode?: AthenaExecutionMode | string | null;
+    d1?: D1DatabaseLike | null;
+    r2?: R2BucketLike | null;
+    storagePrefix?: string;
+    sessionMode?: string | null;
+    url?: string | null;
+    key?: string | null;
+    client?: string | null;
+    backend?: BackendConfig | BackendType;
+    headers?: Record<string, string>;
+    models?: TModels;
+    env?: Record<string, string | undefined>;
+    context?: AthenaRequestContext | AthenaRequestContextProvider;
+    db?: AthenaDbConfig;
+    auth?: AthenaAuthConfig;
+    chat?: AthenaChatConfig;
+    storage?: AthenaStorageConfig;
+    billing?: AthenaBillingConfig;
+    retryReads?: boolean;
+    diagnostics?: AthenaDiagnosticsMode;
+    traceQueries?: boolean | AthenaQueryTraceOptions;
+    debugAst?: boolean;
+    findManyAst?: boolean;
+    gatewayTransport?: AthenaGatewayClient;
+    /**
+     * When `mode` is `auto` and both D1 and gateway URL are set, which wins.
+     * Default `edge`. Also readable from env `ATHENA_EXECUTION_PREFER`.
+     */
+    prefer?: AthenaExecutionPrefer | string | null;
+}
+type AthenaRuntimeClient<TModels extends AthenaClientModelsInput | undefined = undefined> = AthenaClient<TModels> | AthenaClientWithR2Storage<TModels>;
+interface AthenaRuntimeResult<TModels extends AthenaClientModelsInput | undefined = undefined, TClient extends AthenaRuntimeClient<TModels> = AthenaRuntimeClient<TModels>> {
+    mode: AthenaResolvedExecutionMode;
+    client: TClient;
+    capabilities: TClient["capabilities"];
+}
+type AthenaRuntimeConfigWithR2<TModels extends AthenaClientModelsInput | undefined = undefined> = AthenaRuntimeConfig<TModels> & {
+    r2: R2BucketLike;
+};
+/**
+ * Canonical Worker / Pages `env` bindings recognized by {@link createAthenaFromWorkerEnv}.
+ * Gateway URL keys align with {@link resolveAthenaExecutionMode} / createClient env resolution.
+ */
+interface AthenaWorkerEnv {
+    DB?: D1DatabaseLike | null;
+    FILES?: R2BucketLike | null;
+    ATHENA_URL?: string;
+    /** Alias for gateway/DB HTTP base (same keys as createClient env). */
+    ATHENA_DB_URL?: string;
+    ATHENA_GATEWAY_URL?: string;
+    NEXT_PUBLIC_ATHENA_URL?: string;
+    NEXT_PUBLIC_ATHENA_DB_API_URL?: string;
+    ATHENA_API_KEY?: string;
+    /** Same aliases as createClient / resolveCore `ENV_KEY_KEYS`. */
+    NEXT_PUBLIC_ATHENA_API_KEY?: string;
+    ATHENA_GATEWAY_API_KEY?: string;
+    X_API_KEY?: string;
+    ATHENA_AUTH_URL?: string;
+    ATHENA_CLIENT?: string;
+    ATHENA_EXECUTION_MODE?: string;
+    ATHENA_EXECUTION_PREFER?: string;
+    [key: string]: unknown;
+}
+/** Map runtime/Worker shape → {@link AthenaClientConfig} (single constructor input). */
+declare function toCreateClientConfig<TModels extends AthenaClientModelsInput | undefined>(config: AthenaRuntimeConfig<TModels>): AthenaClientConfig<TModels>;
+/**
+ * Create an Athena client for either gateway or edge execution.
+ * Thin façade: always materializes via {@link createClient}.
+ */
+declare function createAthenaRuntime<const TModels extends AthenaClientModelsInput | undefined = undefined>(config: AthenaRuntimeConfigWithR2<TModels> & {
+    mode?: "edge" | "auto" | string | null;
+}): AthenaRuntimeResult<TModels, AthenaClientWithR2Storage<TModels>>;
+declare function createAthenaRuntime<const TModels extends AthenaClientModelsInput | undefined = undefined>(config: AthenaRuntimeConfig<TModels>): AthenaRuntimeResult<TModels>;
+declare function createAthenaRuntimeClient<const TModels extends AthenaClientModelsInput | undefined = undefined>(config: AthenaRuntimeConfigWithR2<TModels> & {
+    mode?: "edge" | "auto" | string | null;
+}): AthenaClientWithR2Storage<TModels>;
+declare function createAthenaRuntimeClient<const TModels extends AthenaClientModelsInput | undefined = undefined>(config: AthenaRuntimeConfig<TModels>): AthenaRuntimeClient<TModels>;
+type CreateAthenaFromWorkerEnvOptions<TModels extends AthenaClientModelsInput | undefined = undefined> = Omit<AthenaRuntimeConfig<TModels>, "d1" | "r2" | "url" | "key" | "env" | "auth" | "client"> & {
+    d1Binding?: string;
+    r2Binding?: string;
+    storagePrefix?: string;
+    auth?: AthenaAuthConfig;
+    client?: string | null;
+    models?: TModels;
+};
+/**
+ * One-call Worker setup: map standard `env` bindings, then {@link createClient}.
+ */
+declare function createAthenaFromWorkerEnv<const TModels extends AthenaClientModelsInput | undefined = undefined>(workerEnv: AthenaWorkerEnv, options?: CreateAthenaFromWorkerEnvOptions<TModels>): AthenaRuntimeResult<TModels>;
+
+export { AthenaClientCapabilities, AthenaExecutionMode, AthenaExecutionPrefer, AthenaResolvedExecutionMode, type AthenaRuntimeClient, type AthenaRuntimeConfig, type AthenaRuntimeConfigWithR2, type AthenaRuntimeResult, type AthenaWorkerEnv, type CloudflareAthenaClient, type CloudflareAthenaClientConfig, type CloudflareAthenaClientConfigWithR2, type CloudflareAthenaClientWithR2, CloudflareR2StorageModule, type CreateAthenaFromWorkerEnvOptions, D1DatabaseLike, D1SqlCompileError, R2BucketLike, compileD1Count, compileD1Delete, compileD1Fetch, compileD1Insert, compileD1Update, createAthenaFromWorkerEnv, createAthenaRuntime, createAthenaRuntimeClient, createCloudflareClient, createCloudflareD1GatewayTransport, createCloudflareEdgeCapabilities, createGatewayCapabilities, executeD1Batch, executeD1Query, extractAthenaCount, isMultiStatement, resolveD1BoundedIdentityColumn, rewritePostgresSqlForSqlite, splitSqlStatements, sqlContainsKeywordOutsideLiterals, sqlFirstKeywordOutsideLiterals, statementExpectsResultRows, toCreateClientConfig };