@xylex-group/athena 1.2.1 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `1.2.1`
+current version: `1.3.0`
 `@xylex-group/athena` is a database driver and API gateway SDK that lets you interact with SQL backends over HTTP through a fluent builder API. It ships a typed query builder for Node.js / server environments and a React hook for client-side use.
 
 ## Install
@@ -43,9 +43,94 @@ if (error) {
 }
 ```
 
-Every query resolves to `{ data, error, errorDetails?, status, count?, raw }`. `data` is `null` on error; `error` is `null` on success.
-
-For richer handling, inspect `errorDetails` (`code`, `status`, `endpoint`, `method`, `requestId`, etc.) or use `AthenaGatewayError` / `isAthenaGatewayError` from the package exports.
+Every query resolves to `{ data, error, errorDetails?, status, count?, raw }`. `data` is `null` on error; `error` is `null` on success.
+
+For richer handling, inspect `errorDetails` (`code`, `status`, `endpoint`, `method`, `requestId`, etc.) or use `AthenaGatewayError` / `isAthenaGatewayError` from the package exports.
+
+## Reliability helper APIs
+
+The SDK exports composable helpers to reduce repetitive route-handler logic.
+
+### Result unwrapping and success guards
+
+```ts
+import {
+  isOk,
+  unwrap,
+  unwrapRows,
+  unwrapOne,
+  requireSuccess,
+  requireAffected,
+} from "@xylex-group/athena";
+
+const result = await athena.from("users").select("id,name");
+
+if (isOk(result)) {
+  const rows = unwrapRows(result); // typed User[]
+  console.log(rows.length);
+}
+
+const one = await athena.from("users").eq("id", 1).single("id,name");
+const user = unwrapOne(one, { allowNull: true });
+
+const inserted = await athena
+  .from("users")
+  .insert({ name: "Alice" })
+  .select("id", { count: "exact" });
+
+requireSuccess(inserted, { table: "users", operation: "insert" });
+requireAffected(inserted, { min: 1 }, { table: "users", operation: "insert" });
+```
+
+`requireAffected` uses `result.count`; request it on writes with `{ count: "exact" }` when you need enforced postconditions.
+
+### Error normalization
+
+```ts
+import { normalizeAthenaError } from "@xylex-group/athena";
+
+const result = await athena.from("users").insert({ id: 1 }).select();
+if (result.error) {
+  const err = normalizeAthenaError(result, {
+    table: "users",
+    operation: "insert",
+  });
+  if (err.kind === "unique_violation") {
+    // deterministic conflict handling
+  }
+}
+```
+
+Normalized errors expose stable `kind` values (`unique_violation`, `validation`, `auth`, `rate_limit`, `transient`, etc.) plus operation metadata.
+
+### Numeric coercion
+
+```ts
+import { coerceInt, assertInt } from "@xylex-group/athena";
+
+const maybeCaseId = coerceInt(req.query.case_id, { min: 1 });
+if (maybeCaseId == null) throw new Error("Invalid case id");
+
+const caseId = assertInt(req.query.case_id, "case_id", { min: 1 });
+```
+
+### Retry helper
+
+```ts
+import { withRetry } from "@xylex-group/athena";
+
+const result = await withRetry(
+  {
+    retries: 3,
+    backoff: "exponential",
+    baseDelayMs: 100,
+    jitter: true,
+  },
+  () => athena.from("users").select("id,name"),
+);
+```
+
+By default, retries target transient/rate-limit failures; use `shouldRetry` for custom policies.
 
 ## Query builder
 
@@ -64,37 +149,37 @@ const { data } = await athena.from<User>("users").select("id, name");
 
 ### Filters
 
-Filters accumulate on the builder and are sent together when the query executes.
-
-```ts
-const { data } = await athena
+Filters accumulate on the builder and are sent together when the query executes.
+
+```ts
+const { data } = await athena
   .from("characters")
   .select("id, name")
-  .eq("active", true)           // column = value
-  .neq("role", "guest")         // column != value
-  .gt("level", 5)               // column > value
-  .gte("score", 100)            // column >= value
-  .lt("age", 30)                // column < value
+  .eq("active", true) // column = value
+  .neq("role", "guest") // column != value
+  .gt("level", 5) // column > value
+  .gte("score", 100) // column >= value
+  .lt("age", 30) // column < value
   .lte("created_at", "2024-01-01") // column <= value
-  .like("name", "Ali%")         // SQL LIKE (case-sensitive)
+  .like("name", "Ali%") // SQL LIKE (case-sensitive)
   .ilike("email", "%@example%") // SQL ILIKE (case-insensitive)
-  .is("deleted_at", null)       // IS NULL / IS TRUE etc.
-  .in("status", ["active", "pending"])    // IN (…)
-  .contains("tags", ["hero"])             // array contains value
+  .is("deleted_at", null) // IS NULL / IS TRUE etc.
+  .in("status", ["active", "pending"]) // IN (…)
+  .contains("tags", ["hero"]) // array contains value
   .containedBy("tags", ["hero", "villain"]) // array is subset of value
   .match({ role: "admin", active: true }) // multiple eq filters at once
-  .not("role", "eq", "banned")  // NOT col op val
-  .or("status.eq.active,status.eq.pending"); // OR expression
-```
-
-Canonical style for reads is to call `.select(...)` first, then apply filters:
-
-```ts
-const { data } = await athena
-  .from("instruments")
-  .select("name, section_id")
-  .eq("name", "violin");
-```
+  .not("role", "eq", "banned") // NOT col op val
+  .or("status.eq.active,status.eq.pending"); // OR expression
+```
+
+Canonical style for reads is to call `.select(...)` first, then apply filters:
+
+```ts
+const { data } = await athena
+  .from("instruments")
+  .select("name, section_id")
+  .eq("name", "violin");
+```
 
 ### Pagination
 
@@ -119,40 +204,47 @@ const { data: user } = await athena
 
 `maybeSingle` behaves identically — both return the first element of the result set.
 
-### RPC
-
-Use `athena.rpc(...)` for Postgres function calls. By default it calls `POST /gateway/rpc`, and with `{ get: true }` it uses the compatibility route `GET /rpc/{function_name}`.
-
-```ts
-const { data, count } = await athena
-  .rpc("list_users", { role: "admin" }, { count: "exact", schema: "public" })
-  .eq("active", true)
-  .order("created_at", { ascending: false })
-  .range(0, 24)
-  .select(["id", "email"]);
-
-const { data: firstUser } = await athena
-  .rpc<{ id: number; email: string }>("list_users", { role: "admin" })
-  .single("id,email");
-
-const { data: readOnlyUser } = await athena
-  .rpc<{ id: number; email: string }>("list_users", { role: "admin" }, { get: true, count: "planned", head: true })
-  .eq("id", 1)
-  .single("id,email");
-```
-
-RPC chain methods: `.eq()`, `.neq()`, `.gt()`, `.gte()`, `.lt()`, `.lte()`, `.like()`, `.ilike()`, `.is()`, `.in()`, `.order()`, `.limit()`, `.offset()`, `.range()`, `.select()`, `.single()`, `.maybeSingle()`.
-RPC options: `schema`, `count` (`"exact" | "planned" | "estimated"`), `head`, `get`.
-
-### Options
+### RPC
+
+Use `athena.rpc(...)` for Postgres function calls. By default it calls `POST /gateway/rpc`, and with `{ get: true }` it uses the compatibility route `GET /rpc/{function_name}`.
+
+```ts
+const { data, count } = await athena
+  .rpc("list_users", { role: "admin" }, { count: "exact", schema: "public" })
+  .eq("active", true)
+  .order("created_at", { ascending: false })
+  .range(0, 24)
+  .select(["id", "email"]);
+
+const { data: firstUser } = await athena
+  .rpc<{ id: number; email: string }>("list_users", { role: "admin" })
+  .single("id,email");
+
+const { data: readOnlyUser } = await athena
+  .rpc<{
+    id: number;
+    email: string;
+  }>(
+    "list_users",
+    { role: "admin" },
+    { get: true, count: "planned", head: true },
+  )
+  .eq("id", 1)
+  .single("id,email");
+```
+
+RPC chain methods: `.eq()`, `.neq()`, `.gt()`, `.gte()`, `.lt()`, `.lte()`, `.like()`, `.ilike()`, `.is()`, `.in()`, `.order()`, `.limit()`, `.offset()`, `.range()`, `.select()`, `.single()`, `.maybeSingle()`.
+RPC options: `schema`, `count` (`"exact" | "planned" | "estimated"`), `head`, `get`.
+
+### Options
 
 Pass options as the second argument to `.select()`:
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `count` | `"exact" \| "planned" \| "estimated"` | request a row count alongside the data |
-| `head` | `boolean` | return response headers only (no rows) |
-| `stripNulls` | `boolean` | strip null values from rows (default `true`) |
+| Option       | Type                                  | Description                                  |
+| ------------ | ------------------------------------- | -------------------------------------------- |
+| `count`      | `"exact" \| "planned" \| "estimated"` | request a row count alongside the data       |
+| `head`       | `boolean`                             | return response headers only (no rows)       |
+| `stripNulls` | `boolean`                             | strip null values from rows (default `true`) |
 
 ```ts
 const { data } = await athena
@@ -178,9 +270,9 @@ const { data } = await athena
   .insert([{ name: "Frodo" }, { name: "Sam" }])
   .select();
 
-// Type inference differs by payload shape:
-// - insert(one) => AthenaResult<Row>
-// - insert(many) => AthenaResult<Row[]>
+// Type inference differs by payload shape:
+// - insert(one) => AthenaResult<Row>
+// - insert(many) => AthenaResult<Row[]>
 ```
 
 ### Update
@@ -206,18 +298,18 @@ const { data } = await athena
   )
   .select();
 
-// Type inference differs by payload shape:
-// - upsert(one) => AthenaResult<Row>
-// - upsert(many) => AthenaResult<Row[]>
+// Type inference differs by payload shape:
+// - upsert(one) => AthenaResult<Row>
+// - upsert(many) => AthenaResult<Row[]>
 ```
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `onConflict` | `string \| string[]` | column(s) that determine a conflict |
-| `updateBody` | `object` | fields to apply when a conflict occurs |
-| `defaultToNull` | `boolean` | write explicit `null` for missing fields |
-| `count` | `"exact" \| "planned" \| "estimated"` | request a row count |
-| `head` | `boolean` | return headers only |
+| Option          | Type                                  | Description                              |
+| --------------- | ------------------------------------- | ---------------------------------------- |
+| `onConflict`    | `string \| string[]`                  | column(s) that determine a conflict      |
+| `updateBody`    | `object`                              | fields to apply when a conflict occurs   |
+| `defaultToNull` | `boolean`                             | write explicit `null` for missing fields |
+| `count`         | `"exact" \| "planned" \| "estimated"` | request a row count                      |
+| `head`          | `boolean`                             | return headers only                      |
 
 ### Delete
 
@@ -286,7 +378,7 @@ export function UsersPanel() {
 }
 ```
 
-The hook returns `fetchGateway`, `insertGateway`, `updateGateway`, `deleteGateway`, `rpcGateway`, `isLoading`, `error`, `lastRequest`, `lastResponse`, and `baseUrl`.
+The hook returns `fetchGateway`, `insertGateway`, `updateGateway`, `deleteGateway`, `rpcGateway`, `isLoading`, `error`, `lastRequest`, `lastResponse`, and `baseUrl`.
 
 Hook config options mirror the client options: `baseUrl`, `apiKey`, `headers`, `userId`, `organizationId`, `publishEvent`.
 
@@ -295,24 +387,32 @@ Hook config options mirror the client options: `baseUrl`, `apiKey`, `headers`, `
 Pass user and tenant context to every request without repeating it on each call:
 
 ```ts
-const athena = createClient("https://athena-db.com", process.env.ATHENA_API_KEY, {
-  headers: {
-    "X-User-Id": currentUser.id,
-    "X-Organization-Id": currentUser.organizationId ?? "",
+const athena = createClient(
+  "https://athena-db.com",
+  process.env.ATHENA_API_KEY,
+  {
+    headers: {
+      "X-User-Id": currentUser.id,
+      "X-Organization-Id": currentUser.organizationId ?? "",
+    },
   },
-});
+);
 ```
 
-Or pass per-call via options. The Athena server interprets `url` and `key` based on the configured backend type.
+Or pass per-call via options. The Athena server interprets `url` and `key` based on the configured backend type.
 
 ## Custom headers
 
 ```ts
-const athena = createClient("https://athena-db.com", process.env.ATHENA_API_KEY, {
-  headers: {
-    "X-Custom-Header": "value",
+const athena = createClient(
+  "https://athena-db.com",
+  process.env.ATHENA_API_KEY,
+  {
+    headers: {
+      "X-Custom-Header": "value",
+    },
   },
-});
+);
 ```
 
 Per-call headers are merged with the client-level headers, with per-call values winning on conflict.
@@ -329,7 +429,10 @@ interface User {
   active: boolean;
 }
 
-const { data } = await athena.from<User>("users").select("id, name").eq("active", true);
+const { data } = await athena
+  .from<User>("users")
+  .select("id, name")
+  .eq("active", true);
 // data is User[] | null
 ```
 

package/dist/index.cjs

@@ -964,10 +964,334 @@ var Backend = {
   ScyllaDB: { type: "scylladb" }
 };
 
+// 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");
+}
+
 exports.AthenaClient = AthenaClient;
 exports.AthenaGatewayError = AthenaGatewayError;
 exports.Backend = Backend;
+exports.assertInt = assertInt;
+exports.coerceInt = coerceInt;
 exports.createClient = createClient;
 exports.isAthenaGatewayError = isAthenaGatewayError;
+exports.isOk = isOk;
+exports.normalizeAthenaError = normalizeAthenaError;
+exports.requireAffected = requireAffected;
+exports.requireSuccess = requireSuccess;
+exports.unwrap = unwrap;
+exports.unwrapOne = unwrapOne;
+exports.unwrapRows = unwrapRows;
+exports.withRetry = withRetry;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map