@xylex-group/athena 1.2.0 → 1.3.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { B as BackendConfig, a as BackendType, A as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator, d as AthenaGatewayCallOptions, e as AthenaGatewayErrorDetails, f as AthenaRpcCallOptions } from './errors-DKNcLa5O.cjs';
-export { g as AthenaGatewayError, h as AthenaGatewayErrorCode, i as AthenaRpcFilter, j as AthenaRpcFilterOperator, k as AthenaRpcOrder, l as AthenaRpcPayload, m as Backend, n as isAthenaGatewayError } from './errors-DKNcLa5O.cjs';
+import { B as BackendConfig, a as BackendType, A as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator, d as AthenaGatewayCallOptions, e as AthenaGatewayErrorDetails, f as AthenaRpcCallOptions } from './errors-DHmpYG46.cjs';
+export { g as AthenaGatewayError, h as AthenaGatewayErrorCode, i as AthenaRpcFilter, j as AthenaRpcFilterOperator, k as AthenaRpcOrder, l as AthenaRpcPayload, m as Backend, n as isAthenaGatewayError } from './errors-DHmpYG46.cjs';
 
 interface AthenaResult<T> {
     data: T | null;
@@ -123,4 +123,118 @@ declare class AthenaClient {
 /** Create client (convenience wrapper; use AthenaClient.builder() for full control) */
 declare function createClient(url: string, apiKey: string, options?: Pick<AthenaGatewayCallOptions, 'client' | 'headers' | 'backend'>): AthenaSdkClient;
 
-export { AthenaClient, AthenaGatewayCallOptions, AthenaGatewayErrorDetails, type AthenaResult, AthenaRpcCallOptions, type AthenaSdkClient, BackendConfig, BackendType, type RpcOrderOptions, type RpcQueryBuilder, type TableQueryBuilder, createClient };
+type AthenaErrorKind = 'unique_violation' | 'not_found' | 'validation' | 'auth' | 'rate_limit' | 'transient' | 'unknown';
+interface AthenaOperationContext {
+    table?: string;
+    operation?: string;
+    identity?: string | Record<string, unknown>;
+}
+interface NormalizedAthenaError {
+    kind: AthenaErrorKind;
+    status?: number;
+    constraint?: string;
+    table?: string;
+    operation?: string;
+    message: string;
+    raw: unknown;
+}
+interface UnwrapOptions {
+    allowNull?: boolean;
+    context?: AthenaOperationContext;
+}
+interface UnwrapOneOptions extends UnwrapOptions {
+    requireExactlyOne?: boolean;
+}
+interface IntCoercionOptions {
+    strictBigInt?: boolean;
+    min?: number;
+    max?: number;
+}
+type RetryBackoffStrategy = 'linear' | 'exponential' | ((attempt: number, error: unknown) => number);
+interface RetryConfig {
+    retries: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    backoff?: RetryBackoffStrategy;
+    jitter?: boolean | number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
+}
+interface RequireAffectedOptions {
+    min?: number;
+}
+/**
+ * Returns `true` when a result is successful (`2xx` status and no `error`).
+ */
+declare function isOk<T>(result: AthenaResult<T>): boolean;
+/**
+ * Normalizes any Athena failure shape into a stable, typed error envelope.
+ *
+ * Accepts `AthenaResult`, `AthenaGatewayError`, native `Error`, or unknown values.
+ * Optional `context` can override inferred table/operation metadata for clearer diagnostics.
+ */
+declare function normalizeAthenaError(resultOrError: unknown, context?: AthenaOperationContext): NormalizedAthenaError;
+/**
+ * Unwraps a successful result into a row array.
+ *
+ * - Throws on failed results.
+ * - Converts `null` data to an empty array.
+ * - Wraps scalar data in a single-element array.
+ */
+declare function unwrapRows<T>(result: AthenaResult<T[] | T | null>, options?: UnwrapOptions): T[];
+/**
+ * Unwraps successful result data from `AthenaResult<T | null>`.
+ *
+ * By default, `null` data throws. Pass `{ allowNull: true }` to permit nullable payloads.
+ */
+declare function unwrap<T>(result: AthenaResult<T | null>, options: UnwrapOptions & {
+    allowNull: true;
+}): T | null;
+declare function unwrap<T>(result: AthenaResult<T | null>, options?: UnwrapOptions): T;
+/**
+ * Unwraps the first row from a successful result that may contain arrays/scalars/null.
+ *
+ * - Throws on failed results.
+ * - Throws when no row exists unless `allowNull: true` is provided.
+ * - Optionally enforces exact cardinality via `requireExactlyOne`.
+ */
+declare function unwrapOne<T>(result: AthenaResult<T[] | T | null>, options: UnwrapOneOptions & {
+    allowNull: true;
+}): T | null;
+declare function unwrapOne<T>(result: AthenaResult<T[] | T | null>, options?: UnwrapOneOptions): T;
+/**
+ * Asserts that an Athena result is successful.
+ *
+ * Returns the original result for fluent composition and throws `AthenaGatewayError` on failure.
+ */
+declare function requireSuccess<T>(result: AthenaResult<T>, context?: AthenaOperationContext): AthenaResult<T>;
+/**
+ * Enforces mutation postconditions based on `result.count`.
+ *
+ * - Validates success first.
+ * - Requires a non-null count in the response.
+ * - Validates `count >= min` (default: `1`).
+ *
+ * Useful for guaranteeing that critical writes actually affected rows.
+ */
+declare function requireAffected<T>(result: AthenaResult<T>, options?: RequireAffectedOptions, context?: AthenaOperationContext): number;
+/**
+ * Safely coerces `unknown` values into finite integers.
+ *
+ * Returns `null` when coercion fails or bounds/strict bigint checks are violated.
+ */
+declare function coerceInt(value: unknown, options?: IntCoercionOptions): number | null;
+/**
+ * Strict integer assertion wrapper around `coerceInt`.
+ *
+ * Throws a `TypeError` with the provided label when coercion fails.
+ */
+declare function assertInt(value: unknown, label?: string, options?: IntCoercionOptions): number;
+/**
+ * Retries an async operation with configurable backoff and retry policy.
+ *
+ * `retries` represents additional attempts after the first failure.
+ * By default, transient and rate-limit errors are retried.
+ */
+declare function withRetry<T>(config: RetryConfig, fn: () => Promise<T>): Promise<T>;
+
+export { AthenaClient, type AthenaErrorKind, AthenaGatewayCallOptions, AthenaGatewayErrorDetails, type AthenaOperationContext, type AthenaResult, AthenaRpcCallOptions, type AthenaSdkClient, BackendConfig, BackendType, type IntCoercionOptions, type NormalizedAthenaError, type RequireAffectedOptions, type RetryBackoffStrategy, type RetryConfig, type RpcOrderOptions, type RpcQueryBuilder, type TableQueryBuilder, type UnwrapOneOptions, type UnwrapOptions, assertInt, coerceInt, createClient, isOk, normalizeAthenaError, requireAffected, requireSuccess, unwrap, unwrapOne, unwrapRows, withRetry };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BackendConfig, a as BackendType, A as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator, d as AthenaGatewayCallOptions, e as AthenaGatewayErrorDetails, f as AthenaRpcCallOptions } from './errors-DKNcLa5O.js';
-export { g as AthenaGatewayError, h as AthenaGatewayErrorCode, i as AthenaRpcFilter, j as AthenaRpcFilterOperator, k as AthenaRpcOrder, l as AthenaRpcPayload, m as Backend, n as isAthenaGatewayError } from './errors-DKNcLa5O.js';
+import { B as BackendConfig, a as BackendType, A as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator, d as AthenaGatewayCallOptions, e as AthenaGatewayErrorDetails, f as AthenaRpcCallOptions } from './errors-DHmpYG46.js';
+export { g as AthenaGatewayError, h as AthenaGatewayErrorCode, i as AthenaRpcFilter, j as AthenaRpcFilterOperator, k as AthenaRpcOrder, l as AthenaRpcPayload, m as Backend, n as isAthenaGatewayError } from './errors-DHmpYG46.js';
 
 interface AthenaResult<T> {
     data: T | null;
@@ -123,4 +123,118 @@ declare class AthenaClient {
 /** Create client (convenience wrapper; use AthenaClient.builder() for full control) */
 declare function createClient(url: string, apiKey: string, options?: Pick<AthenaGatewayCallOptions, 'client' | 'headers' | 'backend'>): AthenaSdkClient;
 
-export { AthenaClient, AthenaGatewayCallOptions, AthenaGatewayErrorDetails, type AthenaResult, AthenaRpcCallOptions, type AthenaSdkClient, BackendConfig, BackendType, type RpcOrderOptions, type RpcQueryBuilder, type TableQueryBuilder, createClient };
+type AthenaErrorKind = 'unique_violation' | 'not_found' | 'validation' | 'auth' | 'rate_limit' | 'transient' | 'unknown';
+interface AthenaOperationContext {
+    table?: string;
+    operation?: string;
+    identity?: string | Record<string, unknown>;
+}
+interface NormalizedAthenaError {
+    kind: AthenaErrorKind;
+    status?: number;
+    constraint?: string;
+    table?: string;
+    operation?: string;
+    message: string;
+    raw: unknown;
+}
+interface UnwrapOptions {
+    allowNull?: boolean;
+    context?: AthenaOperationContext;
+}
+interface UnwrapOneOptions extends UnwrapOptions {
+    requireExactlyOne?: boolean;
+}
+interface IntCoercionOptions {
+    strictBigInt?: boolean;
+    min?: number;
+    max?: number;
+}
+type RetryBackoffStrategy = 'linear' | 'exponential' | ((attempt: number, error: unknown) => number);
+interface RetryConfig {
+    retries: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    backoff?: RetryBackoffStrategy;
+    jitter?: boolean | number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
+}
+interface RequireAffectedOptions {
+    min?: number;
+}
+/**
+ * Returns `true` when a result is successful (`2xx` status and no `error`).
+ */
+declare function isOk<T>(result: AthenaResult<T>): boolean;
+/**
+ * Normalizes any Athena failure shape into a stable, typed error envelope.
+ *
+ * Accepts `AthenaResult`, `AthenaGatewayError`, native `Error`, or unknown values.
+ * Optional `context` can override inferred table/operation metadata for clearer diagnostics.
+ */
+declare function normalizeAthenaError(resultOrError: unknown, context?: AthenaOperationContext): NormalizedAthenaError;
+/**
+ * Unwraps a successful result into a row array.
+ *
+ * - Throws on failed results.
+ * - Converts `null` data to an empty array.
+ * - Wraps scalar data in a single-element array.
+ */
+declare function unwrapRows<T>(result: AthenaResult<T[] | T | null>, options?: UnwrapOptions): T[];
+/**
+ * Unwraps successful result data from `AthenaResult<T | null>`.
+ *
+ * By default, `null` data throws. Pass `{ allowNull: true }` to permit nullable payloads.
+ */
+declare function unwrap<T>(result: AthenaResult<T | null>, options: UnwrapOptions & {
+    allowNull: true;
+}): T | null;
+declare function unwrap<T>(result: AthenaResult<T | null>, options?: UnwrapOptions): T;
+/**
+ * Unwraps the first row from a successful result that may contain arrays/scalars/null.
+ *
+ * - Throws on failed results.
+ * - Throws when no row exists unless `allowNull: true` is provided.
+ * - Optionally enforces exact cardinality via `requireExactlyOne`.
+ */
+declare function unwrapOne<T>(result: AthenaResult<T[] | T | null>, options: UnwrapOneOptions & {
+    allowNull: true;
+}): T | null;
+declare function unwrapOne<T>(result: AthenaResult<T[] | T | null>, options?: UnwrapOneOptions): T;
+/**
+ * Asserts that an Athena result is successful.
+ *
+ * Returns the original result for fluent composition and throws `AthenaGatewayError` on failure.
+ */
+declare function requireSuccess<T>(result: AthenaResult<T>, context?: AthenaOperationContext): AthenaResult<T>;
+/**
+ * Enforces mutation postconditions based on `result.count`.
+ *
+ * - Validates success first.
+ * - Requires a non-null count in the response.
+ * - Validates `count >= min` (default: `1`).
+ *
+ * Useful for guaranteeing that critical writes actually affected rows.
+ */
+declare function requireAffected<T>(result: AthenaResult<T>, options?: RequireAffectedOptions, context?: AthenaOperationContext): number;
+/**
+ * Safely coerces `unknown` values into finite integers.
+ *
+ * Returns `null` when coercion fails or bounds/strict bigint checks are violated.
+ */
+declare function coerceInt(value: unknown, options?: IntCoercionOptions): number | null;
+/**
+ * Strict integer assertion wrapper around `coerceInt`.
+ *
+ * Throws a `TypeError` with the provided label when coercion fails.
+ */
+declare function assertInt(value: unknown, label?: string, options?: IntCoercionOptions): number;
+/**
+ * Retries an async operation with configurable backoff and retry policy.
+ *
+ * `retries` represents additional attempts after the first failure.
+ * By default, transient and rate-limit errors are retried.
+ */
+declare function withRetry<T>(config: RetryConfig, fn: () => Promise<T>): Promise<T>;
+
+export { AthenaClient, type AthenaErrorKind, AthenaGatewayCallOptions, AthenaGatewayErrorDetails, type AthenaOperationContext, type AthenaResult, AthenaRpcCallOptions, type AthenaSdkClient, BackendConfig, BackendType, type IntCoercionOptions, type NormalizedAthenaError, type RequireAffectedOptions, type RetryBackoffStrategy, type RetryConfig, type RpcOrderOptions, type RpcQueryBuilder, type TableQueryBuilder, type UnwrapOneOptions, type UnwrapOptions, assertInt, coerceInt, createClient, isOk, normalizeAthenaError, requireAffected, requireSuccess, unwrap, unwrapOne, unwrapRows, withRetry };

package/dist/index.js

@@ -389,7 +389,7 @@ function mergeOptions(...options) {
   }, void 0);
 }
 function createMutationQuery(executor, defaultColumns = DEFAULT_COLUMNS) {
-  let selectedColumns = defaultColumns;
+  let selectedColumns = defaultColumns === null ? void 0 : defaultColumns;
   let selectedOptions;
   let promise = null;
   const run = (columns, options) => {
@@ -800,15 +800,15 @@ function createTableBuilder(tableName, client) {
         const mergedOptions = mergeOptions(options, selectOptions);
         const payload = {
           table_name: tableName,
-          update_body: values,
+          set: values,
           conditions: filters,
-          columns,
           strip_nulls: mergedOptions?.stripNulls ?? true
         };
+        if (columns) payload.columns = columns;
         const response = await client.updateGateway(payload, mergedOptions);
         return formatResult(response);
       };
-      const mutation = createMutationQuery(executeUpdate);
+      const mutation = createMutationQuery(executeUpdate, null);
       const updateChain = {};
       const filterMethods2 = createFilterMethods(state, addCondition, updateChain);
       Object.assign(updateChain, filterMethods2, mutation);
@@ -825,13 +825,13 @@ function createTableBuilder(tableName, client) {
         const payload = {
           table_name: tableName,
           resource_id: resourceId,
-          conditions: filters,
-          columns
+          conditions: filters
         };
+        if (columns) payload.columns = columns;
         const response = await client.deleteGateway(payload, mergedOptions);
         return formatResult(response);
       };
-      return createMutationQuery(executeDelete);
+      return createMutationQuery(executeDelete, null);
     },
     async single(columns, options) {
       const response = await builder.select(columns, options);
@@ -962,6 +962,320 @@ var Backend = {
   ScyllaDB: { type: "scylladb" }
 };
 
-export { AthenaClient, AthenaGatewayError, Backend, createClient, isAthenaGatewayError };
+// src/auxiliaries.ts
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function safeStringify(value) {
+  try {
+    const serialized = JSON.stringify(value);
+    return serialized ?? String(value);
+  } catch {
+    return "[unserializable]";
+  }
+}
+function contextHint(context) {
+  if (!context?.identity) return void 0;
+  const identity = typeof context.identity === "string" ? context.identity : safeStringify(context.identity);
+  return `Identity: ${identity}`;
+}
+function isAthenaResultLike(value) {
+  return isRecord2(value) && "status" in value && "error" in value && "data" in value && typeof value.status === "number";
+}
+function operationFromDetails(details) {
+  if (!details?.endpoint) return void 0;
+  if (details.endpoint === "/gateway/fetch" || details.endpoint === "/gateway/query") return "select";
+  if (details.endpoint === "/gateway/insert") return "insert";
+  if (details.endpoint === "/gateway/update") return "update";
+  if (details.endpoint === "/gateway/delete") return "delete";
+  if (details.endpoint === "/gateway/rpc" || details.endpoint.startsWith("/rpc/")) return "rpc";
+  return void 0;
+}
+function matchRegex(input, patterns) {
+  for (const pattern of patterns) {
+    const match = pattern.exec(input);
+    if (match?.[1]) return match[1];
+  }
+  return void 0;
+}
+function extractConstraint(message) {
+  return matchRegex(message, [
+    /unique constraint\s+["'`]([^"'`]+)["'`]/i,
+    /constraint\s+["'`]([^"'`]+)["'`]/i
+  ]);
+}
+function extractTable(message) {
+  return matchRegex(message, [
+    /(?:table|relation)\s+["'`]([^"'`]+)["'`]/i,
+    /on\s+table\s+([a-zA-Z0-9_.]+)/i
+  ]);
+}
+function classifyKind(status, code, message) {
+  const lower = message.toLowerCase();
+  const hasUniquePattern = lower.includes("unique constraint") || lower.includes("duplicate key") || lower.includes("already exists") || lower.includes("duplicate");
+  const hasNotFoundPattern = lower.includes("not found") || lower.includes("no rows");
+  const hasValidationPattern = lower.includes("validation") || lower.includes("invalid") || lower.includes("malformed");
+  const hasAuthPattern = lower.includes("unauthorized") || lower.includes("forbidden") || lower.includes("auth");
+  const hasRateLimitPattern = lower.includes("rate limit") || lower.includes("too many requests");
+  const hasTransientPattern = lower.includes("timeout") || lower.includes("temporar") || lower.includes("connection reset") || lower.includes("socket") || lower.includes("deadlock");
+  if (status === 409 || hasUniquePattern) return "unique_violation";
+  if (status === 404 || hasNotFoundPattern) return "not_found";
+  if (status === 401 || status === 403 || hasAuthPattern) return "auth";
+  if (status === 429 || hasRateLimitPattern) return "rate_limit";
+  if (status === 400 || status === 422 || hasValidationPattern) return "validation";
+  if (code === "NETWORK_ERROR" || status === 0 || status !== void 0 && status >= 500 || hasTransientPattern) {
+    return "transient";
+  }
+  return "unknown";
+}
+function toGatewayCode(kind, status) {
+  if (kind === "transient" && (status === 0 || status === void 0)) return "NETWORK_ERROR";
+  if (kind === "validation") return "INVALID_JSON";
+  if (status !== void 0 && status >= 400) return "HTTP_ERROR";
+  return "UNKNOWN_ERROR";
+}
+function toAthenaGatewayError(source, fallbackMessage, context) {
+  if (isAthenaGatewayError(source)) {
+    return source;
+  }
+  if (isAthenaResultLike(source) && source.errorDetails) {
+    return new AthenaGatewayError({
+      code: source.errorDetails.code,
+      message: source.error ?? source.errorDetails.message,
+      status: source.status,
+      endpoint: source.errorDetails.endpoint,
+      method: source.errorDetails.method,
+      requestId: source.errorDetails.requestId,
+      hint: source.errorDetails.hint,
+      cause: source.errorDetails.cause
+    });
+  }
+  const normalized = normalizeAthenaError(source, context);
+  const message = isAthenaResultLike(source) && source.error == null && source.errorDetails == null ? fallbackMessage : normalized.message || fallbackMessage;
+  return new AthenaGatewayError({
+    code: toGatewayCode(normalized.kind, normalized.status),
+    message,
+    status: normalized.status ?? 0,
+    hint: normalized.constraint != null ? `Constraint: ${normalized.constraint}` : contextHint(context),
+    cause: typeof normalized.raw === "string" ? normalized.raw : safeStringify(normalized.raw)
+  });
+}
+function isOk(result) {
+  return result.error == null && result.status >= 200 && result.status < 300;
+}
+function normalizeAthenaError(resultOrError, context) {
+  if (isAthenaResultLike(resultOrError)) {
+    const details = resultOrError.errorDetails;
+    const message2 = resultOrError.error ?? details?.message ?? `Athena ${context?.operation ?? operationFromDetails(details) ?? "request"} failed`;
+    const operation = context?.operation ?? operationFromDetails(details);
+    const table = context?.table ?? extractTable(message2);
+    const constraint = extractConstraint(message2);
+    const kind = classifyKind(resultOrError.status, details?.code, message2);
+    return {
+      kind,
+      status: resultOrError.status,
+      constraint,
+      table,
+      operation,
+      message: message2,
+      raw: resultOrError.raw
+    };
+  }
+  if (isAthenaGatewayError(resultOrError)) {
+    const details = resultOrError.toDetails();
+    const operation = context?.operation ?? operationFromDetails(details);
+    const table = context?.table ?? extractTable(resultOrError.message);
+    const constraint = extractConstraint(resultOrError.message);
+    const kind = classifyKind(resultOrError.status, resultOrError.code, resultOrError.message);
+    return {
+      kind,
+      status: resultOrError.status,
+      constraint,
+      table,
+      operation,
+      message: resultOrError.message,
+      raw: resultOrError
+    };
+  }
+  if (resultOrError instanceof Error) {
+    const maybeStatus = isRecord2(resultOrError) && typeof resultOrError.status === "number" ? resultOrError.status : void 0;
+    return {
+      kind: classifyKind(maybeStatus, void 0, resultOrError.message),
+      status: maybeStatus,
+      constraint: extractConstraint(resultOrError.message),
+      table: context?.table ?? extractTable(resultOrError.message),
+      operation: context?.operation,
+      message: resultOrError.message,
+      raw: resultOrError
+    };
+  }
+  const message = typeof resultOrError === "string" ? resultOrError : "Unknown Athena error";
+  return {
+    kind: classifyKind(void 0, void 0, message),
+    status: void 0,
+    constraint: extractConstraint(message),
+    table: context?.table ?? extractTable(message),
+    operation: context?.operation,
+    message,
+    raw: resultOrError
+  };
+}
+function unwrapRows(result, options) {
+  if (!isOk(result)) {
+    throw toAthenaGatewayError(result, "Athena request failed", options?.context);
+  }
+  if (result.data == null) return [];
+  return Array.isArray(result.data) ? result.data : [result.data];
+}
+function unwrap(result, options) {
+  if (!isOk(result)) {
+    throw toAthenaGatewayError(result, "Athena request failed", options?.context);
+  }
+  if (result.data == null && !options?.allowNull) {
+    throw toAthenaGatewayError(result, "Expected data but received null", options?.context);
+  }
+  return result.data;
+}
+function unwrapOne(result, options) {
+  const rows = unwrapRows(result, options);
+  if (!rows.length) {
+    if (options?.allowNull) return null;
+    throw toAthenaGatewayError(result, "Expected one row but received none", options?.context);
+  }
+  if (options?.requireExactlyOne && rows.length !== 1) {
+    throw toAthenaGatewayError(
+      result,
+      `Expected exactly one row but received ${rows.length}`,
+      options.context
+    );
+  }
+  return rows[0];
+}
+function requireSuccess(result, context) {
+  if (!isOk(result)) {
+    throw toAthenaGatewayError(
+      result,
+      `Athena ${context?.operation ?? "request"} failed`,
+      context
+    );
+  }
+  return result;
+}
+function requireAffected(result, options, context) {
+  requireSuccess(result, context);
+  const minimum = options?.min ?? 1;
+  const count = result.count;
+  if (count == null) {
+    throw new AthenaGatewayError({
+      code: "UNKNOWN_ERROR",
+      status: result.status,
+      message: "Expected affected row count but response.count is missing",
+      hint: 'Set call option { count: "exact" } for mutation postcondition checks.',
+      cause: safeStringify(result.raw)
+    });
+  }
+  if (count < minimum) {
+    throw new AthenaGatewayError({
+      code: "UNKNOWN_ERROR",
+      status: result.status,
+      message: `Expected at least ${minimum} affected rows but received ${count}`,
+      hint: contextHint(context),
+      cause: safeStringify(result.raw)
+    });
+  }
+  return count;
+}
+function applyBounds(value, options) {
+  if (options?.min !== void 0 && value < options.min) return null;
+  if (options?.max !== void 0 && value > options.max) return null;
+  return value;
+}
+function parseIntegerString(value) {
+  const normalized = value.trim();
+  if (!/^[-+]?\d+$/.test(normalized)) return null;
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) return null;
+  return parsed;
+}
+function coerceInt(value, options) {
+  if (value == null) return null;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) return null;
+    return applyBounds(value, options);
+  }
+  if (typeof value === "string") {
+    const parsed = parseIntegerString(value);
+    if (parsed == null) return null;
+    return applyBounds(parsed, options);
+  }
+  if (typeof value === "bigint") {
+    if (options?.strictBigInt) {
+      if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(Number.MIN_SAFE_INTEGER)) {
+        return null;
+      }
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) return null;
+    return applyBounds(parsed, options);
+  }
+  return null;
+}
+function assertInt(value, label = "value", options) {
+  const parsed = coerceInt(value, options);
+  if (parsed == null) {
+    throw new TypeError(`${label} must be a finite integer`);
+  }
+  return parsed;
+}
+function defaultShouldRetry(error) {
+  const normalized = normalizeAthenaError(error);
+  return normalized.kind === "transient" || normalized.kind === "rate_limit";
+}
+function computeDelayMs(attempt, error, config) {
+  const baseDelay = config.baseDelayMs;
+  const rawDelay = typeof config.backoff === "function" ? config.backoff(attempt, error) : config.backoff === "linear" ? baseDelay * attempt : baseDelay * Math.pow(2, attempt - 1);
+  const safeDelay = Number.isFinite(rawDelay) ? Math.max(0, rawDelay) : 0;
+  const clamped = Math.min(config.maxDelayMs, safeDelay);
+  const jitterFactor = typeof config.jitter === "number" ? Math.max(0, Math.min(1, config.jitter)) : config.jitter ? 0.2 : 0;
+  if (!jitterFactor) return clamped;
+  const deviation = clamped * jitterFactor;
+  const offset = (Math.random() * 2 - 1) * deviation;
+  return Math.max(0, clamped + offset);
+}
+function sleep(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function withRetry(config, fn) {
+  const retries = Math.max(0, Math.trunc(config.retries));
+  const shouldRetry = config.shouldRetry ?? defaultShouldRetry;
+  const resolvedConfig = {
+    baseDelayMs: config.baseDelayMs ?? 100,
+    maxDelayMs: config.maxDelayMs ?? 1e4,
+    backoff: config.backoff ?? "exponential",
+    jitter: config.jitter ?? false
+  };
+  for (let attempts = 0; attempts <= retries; attempts += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempts >= retries) {
+        throw error;
+      }
+      const currentAttempt = attempts + 1;
+      const retry = await shouldRetry(error, currentAttempt);
+      if (!retry) {
+        throw error;
+      }
+      const delay = computeDelayMs(currentAttempt, error, resolvedConfig);
+      await sleep(delay);
+    }
+  }
+  throw new Error("withRetry reached an unexpected state");
+}
+
+export { AthenaClient, AthenaGatewayError, Backend, assertInt, coerceInt, createClient, isAthenaGatewayError, isOk, normalizeAthenaError, requireAffected, requireSuccess, unwrap, unwrapOne, unwrapRows, withRetry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map