Athena.js SDK API reference

import { createClient } from "@xylex-group/athena";

const athena = createClient(
  url: string,
  apiKey: string,
  options?: { client?: string; headers?: Record<string, string>; backend?: BackendConfig }
): AthenaSdkClient

interface AthenaSdkClient {
  from<Row = unknown>(table: string): TableQueryBuilder<Row>
  rpc<Row = unknown, Args extends Record<string, unknown> = Record<string, unknown>>(
    fn: string,
    args?: Args,
    options?: AthenaRpcCallOptions,
  ): RpcQueryBuilder<Row>
}

athena.from<Row = unknown>(table: string): TableQueryBuilder<Row>

const builder = athena.from<User>("users");

athena.rpc<Row = unknown, Args extends Record<string, unknown> = Record<string, unknown>>(
  fn: string,
  args?: Args,
  options?: AthenaRpcCallOptions,
): RpcQueryBuilder<Row>

const { data, count } = await athena
  .rpc("list_users", { role: "admin" }, { schema: "public", count: "exact" })
  .eq("active", true)
  .order("created_at", { ascending: false })
  .range(0, 24)
  .select(["id", "email"]);

const { data: country } = await athena
  .rpc("list_stored_countries")
  .eq("id", 1)
  .single();

.select<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): SelectChain<T>

const { data } = await athena.from("users").select();
const { data } = await athena.from("users").select("id, name");
const { data } = await athena.from("users").select(["id", "name"]);

.single<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<AthenaResult<T | null>>

.insert(values: Row, options?: AthenaGatewayCallOptions): MutationQuery<Row>
.insert(values: Row[], options?: AthenaGatewayCallOptions): MutationQuery<Row[]>

.update(values: Partial<Row>, options?: AthenaGatewayCallOptions): MutationQuery<Row[]>

.upsert(
  values: Row,
  options?: AthenaGatewayCallOptions & {
    updateBody?: Partial<Row>
    onConflict?: string | string[]
  },
): MutationQuery<Row>

.upsert(
  values: Row[],
  options?: AthenaGatewayCallOptions & {
    updateBody?: Partial<Row>
    onConflict?: string | string[]
  },
): MutationQuery<Row[]>

.delete(options?: AthenaGatewayCallOptions & { resourceId?: string }): MutationQuery<Row | null>

.order(column: string, options?: { ascending?: boolean }): Self

interface AthenaSortBy {
  field: string
  direction: "ascending" | "descending"
}

// SELECT * FROM rsf_messages WHERE room_id = $1 ORDER BY created_at DESC LIMIT 100
const { data } = await athena
  .from("rsf_messages")
  .eq("room_id", roomId)
  .select("*", { stripNulls: false })
  .order("created_at", { ascending: false })
  .limit(100);

// order also works before .select()
const { data: oldest } = await athena
  .from("events")
  .order("occurred_at")
  .limit(10)
  .select("id, occurred_at");

// order composes with .single() to get the most-recent / least-recent row
const { data: latest } = await athena
  .from("messages")
  .eq("room_id", roomId)
  .select("*")
  .order("created_at", { ascending: false })
  .single();

// rows 51..75
await athena.from("orders").select("id").limit(25).offset(50);

// range: offset = from, limit = to - from + 1
await athena.from("orders").select("id").range(50, 74); // same as above

// rows for page 3 at 25-per-page
await athena
  .from("orders")
  .select("id, total")
  .currentPage(3)
  .pageSize(25);

// include a total-pages hint if the gateway needs one for its response envelope
await athena
  .from("orders")
  .select("id, total")
  .currentPage(1)
  .pageSize(25)
  .totalPages(10);

// before .select()
await athena.from("users").currentPage(2).pageSize(50).select();

// after .select()
await athena.from("users").select().currentPage(2).pageSize(50);

await athena
  .from("queued_jobs")
  .update({ status: "claimed" })
  .eq("status", "ready")
  .order("priority", { ascending: false })
  .limit(10)
  .select("id");

const b = athena.from("users");
b.eq("active", true).limit(10);
// ...some condition you decide you need a fresh query
await b.reset().eq("role", "admin").select("id");

interface MutationQuery<Result> extends PromiseLike<AthenaResult<Result>> {
  select(columns?, options?): Promise<AthenaResult<Result>>
  returning(columns?, options?): Promise<AthenaResult<Result>>
  single(columns?, options?): Promise<AthenaResult<MutationSingleResult<Result>>>
  maybeSingle(columns?, options?): Promise<AthenaResult<MutationSingleResult<Result>>>
  then(onfulfilled?, onrejected?): Promise<…>
  catch(onrejected?): Promise<…>
  finally(onfinally?): Promise<…>
}

interface RpcQueryBuilder<Row> extends PromiseLike<AthenaResult<Row[]>> {
  eq(column, value): RpcQueryBuilder<Row>
  neq(column, value): RpcQueryBuilder<Row>
  gt(column, value): RpcQueryBuilder<Row>
  gte(column, value): RpcQueryBuilder<Row>
  lt(column, value): RpcQueryBuilder<Row>
  lte(column, value): RpcQueryBuilder<Row>
  like(column, value): RpcQueryBuilder<Row>
  ilike(column, value): RpcQueryBuilder<Row>
  is(column, value): RpcQueryBuilder<Row>
  in(column, values): RpcQueryBuilder<Row>
  order(column, options?: { ascending?: boolean }): RpcQueryBuilder<Row>
  limit(count): RpcQueryBuilder<Row>
  offset(count): RpcQueryBuilder<Row>
  range(from, to): RpcQueryBuilder<Row>
  select(columns?: string | string[], options?: AthenaRpcCallOptions): Promise<AthenaResult<Row[]>>
  single(columns?: string | string[], options?: AthenaRpcCallOptions): Promise<AthenaResult<Row | null>>
  maybeSingle(columns?: string | string[], options?: AthenaRpcCallOptions): Promise<AthenaResult<Row | null>>
}

pnpm typecheck  # compile-time type compatibility assertions
pnpm check:all  # lint + typecheck + test + build

interface AthenaResult<T> {
  data: T | null      // response payload, null on error
  error: string | null // error message, null on success
  errorDetails?: AthenaGatewayErrorDetails | null // structured gateway failure metadata
  status: number       // HTTP status code
  count?: number | null // optional exact count (RPC / count-enabled calls)
  raw: unknown         // unprocessed response body
}

isOk<T>(result: AthenaResult<T>): boolean

unwrapRows<T>(
  result: AthenaResult<T[] | T | null>,
  options?: { context?: AthenaOperationContext; allowNull?: boolean },
): T[]

unwrap<T>(result: AthenaResult<T | null>): T
unwrap<T>(result: AthenaResult<T | null>, options: { allowNull: true }): T | null

unwrapOne<T>(result: AthenaResult<T[] | T | null>): T
unwrapOne<T>(
  result: AthenaResult<T[] | T | null>,
  options: { allowNull: true; requireExactlyOne?: boolean },
): T | null

requireSuccess<T>(
  result: AthenaResult<T>,
  context?: AthenaOperationContext,
): AthenaResult<T>

requireAffected<T>(
  result: AthenaResult<T>,
  options?: { min?: number },
  context?: AthenaOperationContext,
): number

type AthenaErrorKind =
  | "unique_violation"
  | "not_found"
  | "validation"
  | "auth"
  | "rate_limit"
  | "transient"
  | "unknown"

type NormalizedAthenaError = {
  kind: AthenaErrorKind
  status?: number
  constraint?: string
  table?: string
  operation?: string
  message: string
  raw: unknown
}

normalizeAthenaError(
  resultOrError: unknown,
  context?: AthenaOperationContext,
): NormalizedAthenaError

coerceInt(
  value: unknown,
  options?: { strictBigInt?: boolean; min?: number; max?: number },
): number | null

assertInt(
  value: unknown,
  label?: string,
  options?: { strictBigInt?: boolean; min?: number; max?: number },
): number

withRetry<T>(
  config: {
    retries: number
    baseDelayMs?: number
    maxDelayMs?: number
    backoff?: "linear" | "exponential" | ((attempt: number, error: unknown) => number)
    jitter?: boolean | number
    shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>
  },
  fn: () => Promise<T>,
): Promise<T>

type AthenaOperationContext = {
  table?: string
  operation?: string
  identity?: string | Record<string, unknown>
}

import { useAthenaGateway } from "@xylex-group/athena/react";

const result = useAthenaGateway(config?: AthenaGatewayHookConfig): AthenaGatewayHookResult

type AthenaSortDirection = "ascending" | "descending"

interface AthenaSortBy {
  field: string
  direction: AthenaSortDirection
}

interface AthenaFetchPayload {
  table_name?: string
  view_name?: string
  columns?: string[] | string
  conditions?: AthenaGatewayCondition[]
  limit?: number
  offset?: number
  current_page?: number
  page_size?: number
  total_pages?: number
  strip_nulls?: boolean
  group_by?: string
  time_granularity?: "day" | "hour" | "minute"
  aggregation_column?: string
  aggregation_strategy?: "cumulative_sum"
  aggregation_dedup?: boolean
  sort_by?: AthenaSortBy
}

interface AthenaInsertPayload {
  table_name: string
  insert_body: Record<string, unknown> | Record<string, unknown>[]
  update_body?: Record<string, unknown>   // used for upsert
  columns?: string[] | string
  count?: AthenaCountOption
  head?: boolean
  default_to_null?: boolean
  on_conflict?: string | string[]
}

interface AthenaUpdatePayload extends AthenaFetchPayload {
  update_body?: Record<string, unknown>
}

interface AthenaDeletePayload {
  table_name: string
  resource_id?: string
  columns?: string[] | string
  conditions?: AthenaGatewayCondition[]
  sort_by?: AthenaSortBy
  current_page?: number
  page_size?: number
  total_pages?: number
}

interface AthenaRpcPayload {
  function: string
  schema?: string
  args?: Record<string, unknown>
  select?: string
  filters?: AthenaRpcFilter[]
  count?: "exact" | "planned" | "estimated"
  head?: boolean
  limit?: number
  offset?: number
  order?: AthenaRpcOrder
}

type AthenaRpcFilterOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike" | "is" | "in"

interface AthenaRpcFilter {
  column: string
  operator: AthenaRpcFilterOperator
  value?: string | number | boolean | null | Array<string | number | boolean | null>
}

interface AthenaRpcOrder {
  column: string
  ascending?: boolean
}

interface AthenaGatewayCondition {
  column?: string
  operator: AthenaConditionOperator
  value?: string | number | boolean | null | Array<string | number | boolean | null>
}

interface AthenaGatewayResponse<T = unknown> {
  ok: boolean        // true when HTTP status is 2xx
  status: number     // HTTP status code
  data: T | null     // parsed response body, null on error
  count?: number | null // optional count (RPC exact count)
  error?: string     // error message extracted from the response
  errorDetails?: AthenaGatewayErrorDetails | null // structured gateway failure details
  raw: unknown       // unprocessed parsed body
}

type AthenaGatewayErrorCode = "NETWORK_ERROR" | "HTTP_ERROR" | "INVALID_JSON" | "UNKNOWN_ERROR"

interface AthenaGatewayErrorDetails {
  code: AthenaGatewayErrorCode
  message: string
  status: number
  endpoint?: "/gateway/fetch" | "/gateway/insert" | "/gateway/update" | "/gateway/delete" | "/gateway/rpc"
  method?: "POST" | "PUT" | "DELETE"
  requestId?: string
  hint?: string
  cause?: string
}

interface AthenaGatewayCallLog {
  endpoint: "/gateway/fetch" | "/gateway/insert" | "/gateway/update" | "/gateway/delete" | "/gateway/rpc"
  method: "POST" | "PUT" | "DELETE"
  payload: unknown
  headers: Record<string, string>
  timestamp: string  // ISO 8601
}