@xylex-group/athena 3.0.2 → 3.1.0

package/dist/react.d.cts

@@ -1,6 +1,7 @@
 import { u as AthenaGatewayHookConfig, v as AthenaGatewayHookResult } from './types-Bltx6iL6.cjs';
 export { w as AthenaDeletePayload, x as AthenaFetchPayload, a as AthenaGatewayCallOptions, d as AthenaGatewayErrorCode, e as AthenaGatewayErrorDetails, s as AthenaGatewayResponse, y as AthenaInsertPayload, f as AthenaJsonArray, g as AthenaJsonObject, h as AthenaJsonPrimitive, i as AthenaJsonValue, j as AthenaRpcCallOptions, k as AthenaRpcFilter, l as AthenaRpcFilterOperator, m as AthenaRpcOrder, n as AthenaRpcPayload, z as AthenaUpdatePayload } from './types-Bltx6iL6.cjs';
-export { A as AthenaGatewayError, M as ModelFormAdapter, a as ModelFormDefaults, b as ModelFormNullishMode, c as ModelFormValues, T as ToModelFormDefaultsOptions, d as ToModelPayloadOptions, e as createModelFormAdapter, i as isAthenaGatewayError, t as toModelFormDefaults, f as toModelPayload } from './model-form-oOAJUVd4.cjs';
+import { a as AthenaReadQueryClient, c as AthenaReadQueryDefinition, e as AthenaReadQueryExecutionResult, i as AthenaReadQueryFlatRow } from './model-form-BhWWsA-7.cjs';
+export { A as AthenaGatewayError, M as ModelFormAdapter, D as ModelFormDefaults, E as ModelFormNullishMode, G as ModelFormValues, T as ToModelFormDefaultsOptions, H as ToModelPayloadOptions, _ as createModelFormAdapter, a3 as isAthenaGatewayError, a6 as toModelFormDefaults, a7 as toModelPayload } from './model-form-BhWWsA-7.cjs';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { aE as AthenaAuthFetchCompatibleInput, E as AthenaAuthCallOptions, ad as AthenaAuthSessionResponse, R as AthenaAuthErrorDetails, aa as AthenaAuthResult } from './types-AOY-GLu8.cjs';
@@ -240,6 +241,70 @@ declare function useQuery<TQueryFnData, TData = TQueryFnData>(options: UseQueryO
 
 declare function useMutation<TVariables, TMutationFnData, TData = TMutationFnData>(options: UseMutationOptions<TVariables, TMutationFnData, TData>): UseMutationResult<TVariables, TData>;
 
+interface UseAthenaReadQueryOptions {
+    /**
+     * v3 Athena client (`createClient(...)` or a `withContext` / session-scoped view).
+     * Required for fetches when `enabled` is true.
+     */
+    client?: AthenaReadQueryClient | null;
+    /** Portable definition (expression columns + aliases). */
+    query: AthenaReadQueryDefinition;
+    /** 1-based page (default 1). */
+    page?: number;
+    /** Page size (default 10). */
+    pageSize?: number;
+    enabled?: boolean;
+    /** Full cache key; when set, overrides the default key composition. */
+    queryKey?: QueryKey;
+    /** Prepended to the default key when `queryKey` is omitted. */
+    queryKeyPrefix?: QueryKey;
+    refetchOnMount?: boolean;
+    refetchOnWindowFocus?: boolean;
+    refetchOnReconnect?: boolean;
+    retry?: number | false;
+}
+interface UseAthenaReadQueryResult {
+    data: AthenaReadQueryExecutionResult | undefined;
+    rows: AthenaReadQueryFlatRow[];
+    totalItems: number;
+    debugAst: AthenaReadQueryExecutionResult['debugAst'];
+    page: number;
+    pageSize: number;
+    error: AthenaQueryError | null;
+    isLoading: boolean;
+    isFetching: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    status: QueryStatus;
+    refetch: () => Promise<unknown>;
+    reset: () => void;
+}
+/**
+ * Athena-native React hook for {@link AthenaReadQueryDefinition} page reads.
+ *
+ * Uses `@xylex-group/athena/react` `useQuery` + `AthenaQueryClient` (not TanStack).
+ * Does **not** construct clients, open a data proxy, or manage table UI pagination.
+ *
+ * For HeroUI tables / TanStack / `dataProxy`, use auth-ui `useAthenaQuery` instead.
+ *
+ * @example
+ * ```tsx
+ * const athena = createClient({ url, key })
+ * // under AthenaQueryClientProvider
+ * const { rows, totalItems, isLoading } = useAthenaReadQuery({
+ *   client: athena,
+ *   page: 1,
+ *   pageSize: 20,
+ *   query: {
+ *     table: 'orders',
+ *     countColumn: 'id',
+ *     columns: [{ column: 'id', key: 'id' }],
+ *   },
+ * })
+ * ```
+ */
+declare function useAthenaReadQuery({ client, query, page, pageSize, enabled, queryKey, queryKeyPrefix, refetchOnMount, refetchOnWindowFocus, refetchOnReconnect, retry, }: UseAthenaReadQueryOptions): UseAthenaReadQueryResult;
+
 interface UseSessionOptions {
     enabled?: boolean;
     refetchOnMount?: boolean;
@@ -364,4 +429,4 @@ interface UseStorageFileDeleteResult {
 }
 declare function useStorageFileDelete(options: UseStorageFileDeleteOptions): UseStorageFileDeleteResult;
 
-export { type AthenaCacheMode, type AthenaCachePolicy, AthenaGatewayHookConfig, AthenaGatewayHookResult, type AthenaMutationDefaults, type AthenaMutationEvent, type AthenaMutationRequestLog, type AthenaMutationResultData, type AthenaMutationState, AthenaQueryClient, type AthenaQueryClientConfig, AthenaQueryClientProvider, type AthenaQueryDefaults, type AthenaQueryError, type AthenaQueryEvent, type AthenaQueryRequestLog, type AthenaQueryResult, type AthenaQueryState, type AthenaResponseLike, type AthenaRetryCount, type AthenaRetryDelay, type AthenaRuntimeBaseEvent, type AthenaRuntimeEvent, type AthenaRuntimeEventType, type AthenaStateAdapter, type AthenaUnsubscribe, type QueryKey, type QueryStatus, type UseAthenaSessionClientOptions, type UseAthenaSessionClientResult, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseQueryResult, type UseSessionAuthClient, type UseSessionOptions, type UseSessionResult, type UseStorageFileDeleteOptions, type UseStorageFileDeleteResult, type UseStorageFilesOptions, type UseStorageFilesResult, type UseStorageUploadInput, type UseStorageUploadOptions, type UseStorageUploadResult, attachStateAdapter, createAthenaQueryClient, useAthenaGateway, useAthenaQueryClient, useAthenaSessionClient, useMutation, useQuery, useSession, useStorageFileDelete, useStorageFiles, useStorageUpload };
+export { type AthenaCacheMode, type AthenaCachePolicy, AthenaGatewayHookConfig, AthenaGatewayHookResult, type AthenaMutationDefaults, type AthenaMutationEvent, type AthenaMutationRequestLog, type AthenaMutationResultData, type AthenaMutationState, AthenaQueryClient, type AthenaQueryClientConfig, AthenaQueryClientProvider, type AthenaQueryDefaults, type AthenaQueryError, type AthenaQueryEvent, type AthenaQueryRequestLog, type AthenaQueryResult, type AthenaQueryState, type AthenaResponseLike, type AthenaRetryCount, type AthenaRetryDelay, type AthenaRuntimeBaseEvent, type AthenaRuntimeEvent, type AthenaRuntimeEventType, type AthenaStateAdapter, type AthenaUnsubscribe, type QueryKey, type QueryStatus, type UseAthenaReadQueryOptions, type UseAthenaReadQueryResult, type UseAthenaSessionClientOptions, type UseAthenaSessionClientResult, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseQueryResult, type UseSessionAuthClient, type UseSessionOptions, type UseSessionResult, type UseStorageFileDeleteOptions, type UseStorageFileDeleteResult, type UseStorageFilesOptions, type UseStorageFilesResult, type UseStorageUploadInput, type UseStorageUploadOptions, type UseStorageUploadResult, attachStateAdapter, createAthenaQueryClient, useAthenaGateway, useAthenaQueryClient, useAthenaReadQuery, useAthenaSessionClient, useMutation, useQuery, useSession, useStorageFileDelete, useStorageFiles, useStorageUpload };

package/dist/react.d.ts

@@ -1,6 +1,7 @@
 import { u as AthenaGatewayHookConfig, v as AthenaGatewayHookResult } from './types-Bltx6iL6.js';
 export { w as AthenaDeletePayload, x as AthenaFetchPayload, a as AthenaGatewayCallOptions, d as AthenaGatewayErrorCode, e as AthenaGatewayErrorDetails, s as AthenaGatewayResponse, y as AthenaInsertPayload, f as AthenaJsonArray, g as AthenaJsonObject, h as AthenaJsonPrimitive, i as AthenaJsonValue, j as AthenaRpcCallOptions, k as AthenaRpcFilter, l as AthenaRpcFilterOperator, m as AthenaRpcOrder, n as AthenaRpcPayload, z as AthenaUpdatePayload } from './types-Bltx6iL6.js';
-export { A as AthenaGatewayError, M as ModelFormAdapter, a as ModelFormDefaults, b as ModelFormNullishMode, c as ModelFormValues, T as ToModelFormDefaultsOptions, d as ToModelPayloadOptions, e as createModelFormAdapter, i as isAthenaGatewayError, t as toModelFormDefaults, f as toModelPayload } from './model-form-Dh0sisdL.js';
+import { a as AthenaReadQueryClient, c as AthenaReadQueryDefinition, e as AthenaReadQueryExecutionResult, i as AthenaReadQueryFlatRow } from './model-form-BbdzJ9Uh.js';
+export { A as AthenaGatewayError, M as ModelFormAdapter, D as ModelFormDefaults, E as ModelFormNullishMode, G as ModelFormValues, T as ToModelFormDefaultsOptions, H as ToModelPayloadOptions, _ as createModelFormAdapter, a3 as isAthenaGatewayError, a6 as toModelFormDefaults, a7 as toModelPayload } from './model-form-BbdzJ9Uh.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { aE as AthenaAuthFetchCompatibleInput, E as AthenaAuthCallOptions, ad as AthenaAuthSessionResponse, R as AthenaAuthErrorDetails, aa as AthenaAuthResult } from './types-AOY-GLu8.js';
@@ -240,6 +241,70 @@ declare function useQuery<TQueryFnData, TData = TQueryFnData>(options: UseQueryO
 
 declare function useMutation<TVariables, TMutationFnData, TData = TMutationFnData>(options: UseMutationOptions<TVariables, TMutationFnData, TData>): UseMutationResult<TVariables, TData>;
 
+interface UseAthenaReadQueryOptions {
+    /**
+     * v3 Athena client (`createClient(...)` or a `withContext` / session-scoped view).
+     * Required for fetches when `enabled` is true.
+     */
+    client?: AthenaReadQueryClient | null;
+    /** Portable definition (expression columns + aliases). */
+    query: AthenaReadQueryDefinition;
+    /** 1-based page (default 1). */
+    page?: number;
+    /** Page size (default 10). */
+    pageSize?: number;
+    enabled?: boolean;
+    /** Full cache key; when set, overrides the default key composition. */
+    queryKey?: QueryKey;
+    /** Prepended to the default key when `queryKey` is omitted. */
+    queryKeyPrefix?: QueryKey;
+    refetchOnMount?: boolean;
+    refetchOnWindowFocus?: boolean;
+    refetchOnReconnect?: boolean;
+    retry?: number | false;
+}
+interface UseAthenaReadQueryResult {
+    data: AthenaReadQueryExecutionResult | undefined;
+    rows: AthenaReadQueryFlatRow[];
+    totalItems: number;
+    debugAst: AthenaReadQueryExecutionResult['debugAst'];
+    page: number;
+    pageSize: number;
+    error: AthenaQueryError | null;
+    isLoading: boolean;
+    isFetching: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    status: QueryStatus;
+    refetch: () => Promise<unknown>;
+    reset: () => void;
+}
+/**
+ * Athena-native React hook for {@link AthenaReadQueryDefinition} page reads.
+ *
+ * Uses `@xylex-group/athena/react` `useQuery` + `AthenaQueryClient` (not TanStack).
+ * Does **not** construct clients, open a data proxy, or manage table UI pagination.
+ *
+ * For HeroUI tables / TanStack / `dataProxy`, use auth-ui `useAthenaQuery` instead.
+ *
+ * @example
+ * ```tsx
+ * const athena = createClient({ url, key })
+ * // under AthenaQueryClientProvider
+ * const { rows, totalItems, isLoading } = useAthenaReadQuery({
+ *   client: athena,
+ *   page: 1,
+ *   pageSize: 20,
+ *   query: {
+ *     table: 'orders',
+ *     countColumn: 'id',
+ *     columns: [{ column: 'id', key: 'id' }],
+ *   },
+ * })
+ * ```
+ */
+declare function useAthenaReadQuery({ client, query, page, pageSize, enabled, queryKey, queryKeyPrefix, refetchOnMount, refetchOnWindowFocus, refetchOnReconnect, retry, }: UseAthenaReadQueryOptions): UseAthenaReadQueryResult;
+
 interface UseSessionOptions {
     enabled?: boolean;
     refetchOnMount?: boolean;
@@ -364,4 +429,4 @@ interface UseStorageFileDeleteResult {
 }
 declare function useStorageFileDelete(options: UseStorageFileDeleteOptions): UseStorageFileDeleteResult;
 
-export { type AthenaCacheMode, type AthenaCachePolicy, AthenaGatewayHookConfig, AthenaGatewayHookResult, type AthenaMutationDefaults, type AthenaMutationEvent, type AthenaMutationRequestLog, type AthenaMutationResultData, type AthenaMutationState, AthenaQueryClient, type AthenaQueryClientConfig, AthenaQueryClientProvider, type AthenaQueryDefaults, type AthenaQueryError, type AthenaQueryEvent, type AthenaQueryRequestLog, type AthenaQueryResult, type AthenaQueryState, type AthenaResponseLike, type AthenaRetryCount, type AthenaRetryDelay, type AthenaRuntimeBaseEvent, type AthenaRuntimeEvent, type AthenaRuntimeEventType, type AthenaStateAdapter, type AthenaUnsubscribe, type QueryKey, type QueryStatus, type UseAthenaSessionClientOptions, type UseAthenaSessionClientResult, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseQueryResult, type UseSessionAuthClient, type UseSessionOptions, type UseSessionResult, type UseStorageFileDeleteOptions, type UseStorageFileDeleteResult, type UseStorageFilesOptions, type UseStorageFilesResult, type UseStorageUploadInput, type UseStorageUploadOptions, type UseStorageUploadResult, attachStateAdapter, createAthenaQueryClient, useAthenaGateway, useAthenaQueryClient, useAthenaSessionClient, useMutation, useQuery, useSession, useStorageFileDelete, useStorageFiles, useStorageUpload };
+export { type AthenaCacheMode, type AthenaCachePolicy, AthenaGatewayHookConfig, AthenaGatewayHookResult, type AthenaMutationDefaults, type AthenaMutationEvent, type AthenaMutationRequestLog, type AthenaMutationResultData, type AthenaMutationState, AthenaQueryClient, type AthenaQueryClientConfig, AthenaQueryClientProvider, type AthenaQueryDefaults, type AthenaQueryError, type AthenaQueryEvent, type AthenaQueryRequestLog, type AthenaQueryResult, type AthenaQueryState, type AthenaResponseLike, type AthenaRetryCount, type AthenaRetryDelay, type AthenaRuntimeBaseEvent, type AthenaRuntimeEvent, type AthenaRuntimeEventType, type AthenaStateAdapter, type AthenaUnsubscribe, type QueryKey, type QueryStatus, type UseAthenaReadQueryOptions, type UseAthenaReadQueryResult, type UseAthenaSessionClientOptions, type UseAthenaSessionClientResult, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseQueryResult, type UseSessionAuthClient, type UseSessionOptions, type UseSessionResult, type UseStorageFileDeleteOptions, type UseStorageFileDeleteResult, type UseStorageFilesOptions, type UseStorageFilesResult, type UseStorageUploadInput, type UseStorageUploadOptions, type UseStorageUploadResult, attachStateAdapter, createAthenaQueryClient, useAthenaGateway, useAthenaQueryClient, useAthenaReadQuery, useAthenaSessionClient, useMutation, useQuery, useSession, useStorageFileDelete, useStorageFiles, useStorageUpload };

package/dist/react.js

@@ -392,7 +392,7 @@ function buildAthenaRequestHeaders(input) {
 
 // package.json
 var package_default = {
-  version: "3.0.2"
+  version: "3.1.0"
 };
 
 // src/sdk-version.ts
@@ -1976,6 +1976,402 @@ function useMutation(options) {
     lastRequest: snapshot.lastRequest
   };
 }
+
+// src/query-debug-ast.ts
+var ATHENA_DEBUG_AST_KEY = "__athenaDebugAst";
+function getAthenaDebugAst(value) {
+  if (!value || typeof value !== "object" && typeof value !== "function") {
+    return null;
+  }
+  return value[ATHENA_DEBUG_AST_KEY] ?? null;
+}
+
+// src/query/read-query.ts
+function normalizeAthenaReadQueryOrderBy(orderBy) {
+  if (!orderBy) {
+    return [];
+  }
+  const list = Array.isArray(orderBy) ? orderBy : [orderBy];
+  return list.filter(
+    (entry) => entry && typeof entry.column === "string" && entry.column.trim().length > 0
+  );
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function flattenAthenaRowValue(row, column) {
+  if (!column.relation) {
+    return row[column.column];
+  }
+  const relationValue = row[column.relation.name];
+  if (Array.isArray(relationValue)) {
+    return relationValue.map((entry) => isRecord3(entry) ? entry[column.column] : void 0).filter((entry) => entry !== void 0);
+  }
+  if (isRecord3(relationValue)) {
+    return relationValue[column.column];
+  }
+  return void 0;
+}
+function resolveFlatRowKey(row, index, preferredKey) {
+  const preferredValue = preferredKey && preferredKey in row ? row[preferredKey] : void 0;
+  if (preferredValue !== void 0 && preferredValue !== null && `${preferredValue}`.trim().length > 0) {
+    return String(preferredValue);
+  }
+  for (const [key, value] of Object.entries(row)) {
+    if (key === "__rowKey") {
+      continue;
+    }
+    if (value === void 0 || value === null) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      if (value.length > 0) {
+        return `${key}-${value.join("-")}`;
+      }
+      continue;
+    }
+    const nextValue = String(value).trim();
+    if (nextValue.length > 0) {
+      return nextValue;
+    }
+  }
+  return `row-${index + 1}`;
+}
+function flattenAthenaReadQueryRows(rows, columns, preferredKey) {
+  return rows.map((entry, index) => {
+    const sourceRow = isRecord3(entry) ? entry : {};
+    const flatRow = columns.reduce(
+      (currentRow, column) => {
+        currentRow[column.key] = flattenAthenaRowValue(sourceRow, column);
+        return currentRow;
+      },
+      { __rowKey: "" }
+    );
+    flatRow.__rowKey = resolveFlatRowKey(flatRow, index, preferredKey);
+    return flatRow;
+  });
+}
+function buildAthenaReadQuerySelectString(columns) {
+  const baseColumns = columns.filter((column) => !column.relation).map((column) => column.column);
+  const relationGroups = /* @__PURE__ */ new Map();
+  for (const column of columns) {
+    if (!column.relation) {
+      continue;
+    }
+    const groupKey = [
+      column.relation.name,
+      column.relation.schema ?? "",
+      column.relation.table
+    ].join(":");
+    const existingGroup = relationGroups.get(groupKey);
+    if (existingGroup) {
+      if (!existingGroup.columns.includes(column.column)) {
+        existingGroup.columns.push(column.column);
+      }
+      continue;
+    }
+    relationGroups.set(groupKey, {
+      columns: [column.column],
+      relation: column.relation
+    });
+  }
+  const relationColumns = [...relationGroups.values()].map(
+    ({ columns: relationColumns2, relation }) => {
+      const relationTarget = relation.schema ? `${relation.schema}.${relation.table}` : relation.table;
+      return `${relation.name}:${relationTarget}(${relationColumns2.join(",")})`;
+    }
+  );
+  return [...baseColumns, ...relationColumns].join(",");
+}
+function buildAthenaReadQueryFindManySelect(columns) {
+  const select = {};
+  for (const column of columns) {
+    if (!column.relation) {
+      select[column.column] = true;
+      continue;
+    }
+    const existingRelation = select[column.relation.name];
+    if (existingRelation && existingRelation !== true && isRecord3(existingRelation.select)) {
+      existingRelation.select[column.column] = true;
+      continue;
+    }
+    select[column.relation.name] = {
+      ...column.relation.schema ? { schema: column.relation.schema } : {},
+      select: {
+        [column.column]: true
+      }
+    };
+  }
+  return select;
+}
+function buildAthenaReadQueryFindManyWhere(filters) {
+  if (!filters?.length) {
+    return;
+  }
+  return filters.reduce(
+    (where, filter) => {
+      const operator = filter.operator ?? "eq";
+      where[filter.column] = operator === "eq" ? filter.value : { [operator]: filter.value };
+      return where;
+    },
+    {}
+  );
+}
+function buildAthenaReadQueryFindManyOrderBy(orderBy) {
+  const normalized = normalizeAthenaReadQueryOrderBy(orderBy);
+  if (normalized.length === 0) {
+    return;
+  }
+  if (normalized.length === 1) {
+    const primary = normalized[0];
+    if (!primary) {
+      return;
+    }
+    return {
+      ascending: primary.direction !== "desc",
+      column: primary.column
+    };
+  }
+  return Object.fromEntries(
+    normalized.map((entry) => [
+      entry.column,
+      entry.direction === "desc" ? "desc" : "asc"
+    ])
+  );
+}
+function applyAthenaReadQueryFilters(queryBuilder, filters) {
+  if (!filters?.length) {
+    return queryBuilder;
+  }
+  return filters.reduce((currentBuilder, filter) => {
+    const operator = filter.operator ?? "eq";
+    const builderMethod = currentBuilder[operator];
+    if (typeof builderMethod !== "function") {
+      return currentBuilder;
+    }
+    return builderMethod.call(currentBuilder, filter.column, filter.value);
+  }, queryBuilder);
+}
+function applyAthenaReadQuerySelectOrder(queryBuilder, orderBy) {
+  const normalized = normalizeAthenaReadQueryOrderBy(orderBy);
+  if (normalized.length === 0) {
+    return queryBuilder;
+  }
+  return normalized.reduce(
+    (builder, entry) => builder.order(entry.column, {
+      ascending: entry.direction !== "desc"
+    }),
+    queryBuilder
+  );
+}
+function applyAthenaReadQuerySelectLimit(queryBuilder, limit) {
+  if (!limit || limit < 1) {
+    return queryBuilder;
+  }
+  return queryBuilder.limit(limit);
+}
+function clampAthenaReadQueryTotalItems(totalItems, limit) {
+  if (!limit || limit < 1) {
+    return totalItems;
+  }
+  return Math.min(totalItems, limit);
+}
+function resolveCountValue(...candidates) {
+  for (const candidate of candidates) {
+    if (typeof candidate === "number" && Number.isFinite(candidate)) {
+      return Math.max(0, Math.trunc(candidate));
+    }
+  }
+  return 0;
+}
+function resolveTotalItemsFromPage({
+  countCandidates,
+  limit,
+  page,
+  pageSize,
+  rowCount
+}) {
+  const exactCount = resolveCountValue(...countCandidates);
+  if (exactCount > 0) {
+    return clampAthenaReadQueryTotalItems(exactCount, limit);
+  }
+  if (rowCount > 0) {
+    const base = (page - 1) * pageSize + rowCount;
+    const synthetic = rowCount >= pageSize ? base + 1 : base;
+    return clampAthenaReadQueryTotalItems(synthetic, limit);
+  }
+  return clampAthenaReadQueryTotalItems(exactCount, limit);
+}
+async function executeAthenaReadQuery({
+  client,
+  page,
+  pageSize,
+  query
+}) {
+  const db = client.db;
+  const baseBuilder = db.from(query.table, {
+    schema: query.schema
+  });
+  const countBuilder = applyAthenaReadQueryFilters(
+    db.from(query.table, { schema: query.schema }),
+    query.filters
+  );
+  const countResult = await countBuilder.select(query.countColumn, {
+    count: "exact",
+    head: true
+  });
+  if ((query.mode ?? "findMany") === "select") {
+    const selectBuilder = applyAthenaReadQuerySelectLimit(
+      applyAthenaReadQuerySelectOrder(
+        applyAthenaReadQueryFilters(baseBuilder, query.filters),
+        query.orderBy
+      ),
+      query.limit
+    );
+    const result2 = await selectBuilder.currentPage(page).pageSize(pageSize).select(buildAthenaReadQuerySelectString(query.columns), {
+      count: "exact"
+    });
+    const rows2 = flattenAthenaReadQueryRows(
+      Array.isArray(result2.data) ? result2.data : [],
+      query.columns,
+      query.rowKey
+    );
+    return {
+      debugAst: getAthenaDebugAst(result2) ?? void 0,
+      rows: rows2,
+      totalItems: resolveTotalItemsFromPage({
+        countCandidates: [countResult.count, result2.count],
+        limit: query.limit,
+        page,
+        pageSize,
+        rowCount: rows2.length
+      })
+    };
+  }
+  const findManyOrderBy = buildAthenaReadQueryFindManyOrderBy(query.orderBy);
+  const findManyOptions = {
+    ...query.limit ? { limit: query.limit } : {},
+    ...findManyOrderBy ? { orderBy: findManyOrderBy } : {},
+    select: buildAthenaReadQueryFindManySelect(query.columns),
+    ...query.filters?.length ? { where: buildAthenaReadQueryFindManyWhere(query.filters) } : {}
+  };
+  const result = await baseBuilder.currentPage(page).pageSize(pageSize).findMany(findManyOptions);
+  const rows = flattenAthenaReadQueryRows(
+    Array.isArray(result.data) ? result.data : [],
+    query.columns,
+    query.rowKey
+  );
+  return {
+    debugAst: getAthenaDebugAst(result) ?? void 0,
+    rows,
+    totalItems: resolveTotalItemsFromPage({
+      countCandidates: [countResult.count, result.count],
+      limit: query.limit,
+      page,
+      pageSize,
+      rowCount: rows.length
+    })
+  };
+}
+
+// src/react/use-athena-read-query.ts
+var DEFAULT_PAGE = 1;
+var DEFAULT_PAGE_SIZE = 10;
+function isReadQueryRunnable(query) {
+  return query.table.trim().length > 0 && query.columns.length > 0 && query.countColumn.trim().length > 0;
+}
+function useAthenaReadQuery({
+  client,
+  query,
+  page = DEFAULT_PAGE,
+  pageSize = DEFAULT_PAGE_SIZE,
+  enabled = true,
+  queryKey,
+  queryKeyPrefix,
+  refetchOnMount,
+  refetchOnWindowFocus,
+  refetchOnReconnect,
+  retry
+}) {
+  const resolvedPage = page > 0 ? Math.trunc(page) : DEFAULT_PAGE;
+  const resolvedPageSize = pageSize > 0 ? Math.trunc(pageSize) : DEFAULT_PAGE_SIZE;
+  const queryEnabled = enabled && !!client && isReadQueryRunnable(query);
+  const defaultQueryKey = useMemo(
+    () => [
+      "athena",
+      "read-query",
+      query.mode ?? "findMany",
+      query.table,
+      query.schema,
+      query.columns,
+      query.filters,
+      query.limit,
+      query.orderBy,
+      query.rowKey,
+      query.countColumn,
+      resolvedPage,
+      resolvedPageSize
+    ],
+    [
+      query.columns,
+      query.countColumn,
+      query.filters,
+      query.limit,
+      query.mode,
+      query.orderBy,
+      query.rowKey,
+      query.schema,
+      query.table,
+      resolvedPage,
+      resolvedPageSize
+    ]
+  );
+  const resolvedQueryKey = useMemo(() => {
+    if (queryKey !== void 0) {
+      return queryKey;
+    }
+    if (queryKeyPrefix !== void 0) {
+      const prefix = Array.isArray(queryKeyPrefix) ? queryKeyPrefix : [queryKeyPrefix];
+      return [...prefix, ...defaultQueryKey];
+    }
+    return defaultQueryKey;
+  }, [defaultQueryKey, queryKey, queryKeyPrefix]);
+  const result = useQuery({
+    enabled: queryEnabled,
+    queryKey: resolvedQueryKey,
+    queryFn: async () => {
+      if (!client) {
+        throw new Error("Athena client is required to run the read query.");
+      }
+      return executeAthenaReadQuery({
+        client,
+        page: resolvedPage,
+        pageSize: resolvedPageSize,
+        query
+      });
+    },
+    refetchOnMount,
+    refetchOnWindowFocus,
+    refetchOnReconnect,
+    retry
+  });
+  return {
+    data: result.data,
+    rows: result.data?.rows ?? [],
+    totalItems: result.data?.totalItems ?? 0,
+    debugAst: result.data?.debugAst,
+    page: resolvedPage,
+    pageSize: resolvedPageSize,
+    error: result.error,
+    isLoading: result.isLoading,
+    isFetching: result.isFetching,
+    isSuccess: result.isSuccess,
+    isError: result.isError,
+    status: result.status,
+    refetch: result.refetch,
+    reset: result.reset
+  };
+}
 function resolveGetSession(authClient) {
   if ("getSession" in authClient && typeof authClient.getSession === "function") {
     return authClient.getSession;
@@ -2270,7 +2666,7 @@ function resolveNullishValue(mode) {
   if (mode === "null") return null;
   return "";
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function isNullableColumn(model, key) {
@@ -2279,7 +2675,7 @@ function isNullableColumn(model, key) {
 }
 function toModelFormDefaults(model, values, options) {
   const source = values;
-  if (!isRecord3(source)) {
+  if (!isRecord4(source)) {
     return {};
   }
   const mode = options?.nullishMode ?? "empty-string";
@@ -2325,6 +2721,6 @@ function createModelFormAdapter(model) {
   };
 }
 
-export { AthenaGatewayError, AthenaQueryClient, AthenaQueryClientProvider, attachStateAdapter, createAthenaQueryClient, createModelFormAdapter, isAthenaGatewayError, toModelFormDefaults, toModelPayload, useAthenaGateway, useAthenaQueryClient, useAthenaSessionClient, useMutation, useQuery, useSession, useStorageFileDelete, useStorageFiles, useStorageUpload };
+export { AthenaGatewayError, AthenaQueryClient, AthenaQueryClientProvider, attachStateAdapter, createAthenaQueryClient, createModelFormAdapter, isAthenaGatewayError, toModelFormDefaults, toModelPayload, useAthenaGateway, useAthenaQueryClient, useAthenaReadQuery, useAthenaSessionClient, useMutation, useQuery, useSession, useStorageFileDelete, useStorageFiles, useStorageUpload };
 //# sourceMappingURL=react.js.map
 //# sourceMappingURL=react.js.map