@xylex-group/athena 1.4.1 → 1.5.0

package/README.md

@@ -1,7 +1,7 @@
 # athena-js
 
-current version: `1.4.1`
-`@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.
+current version: `1.5.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 plus Athena-native React hooks for client-side use.
 
 ## Install
 
@@ -13,7 +13,7 @@ pnpm add @xylex-group/athena
 yarn add @xylex-group/athena
 ```
 
-React peer dependency is optional — only needed if you use `useAthenaGateway`.
+React peer dependency is optional — only needed if you use `@xylex-group/athena/react` hooks.
 
 ```bash
 npm install react  # React >=17 required for the hook
@@ -153,12 +153,12 @@ 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
-  .eqUuid("session_id", "550e8400-e29b-41d4-a716-446655440000") // explicit UUID cast
-  .eqCast("session_id", "550e8400-e29b-41d4-a716-446655440000", "uuid") // explicit cast type
-  .neq("role", "guest") // column != value
+  .from("characters")
+  .select("id, name")
+  .eq("active", true) // column = value
+  .eqUuid("session_id", "550e8400-e29b-41d4-a716-446655440000") // explicit UUID cast
+  .eqCast("session_id", "550e8400-e29b-41d4-a716-446655440000", "uuid") // explicit cast type
+  .neq("role", "guest") // column != value
   .gt("level", 5) // column > value
   .gte("score", 100) // column >= value
   .lt("age", 30) // column < value
@@ -171,10 +171,10 @@ const { data } = await athena
   .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
-```
-
-`eq()` now auto-detects UUID-like values on identifier columns (for example `id`, `*_id`, `*uuid*`) and uses a safe typed comparison path so UUID columns no longer require app-side manual `::uuid` / `::text` casts.
+  .or("status.eq.active,status.eq.pending"); // OR expression
+```
+
+`eq()` now auto-detects UUID-like values on identifier columns (for example `id`, `*_id`, `*uuid*`) and uses a safe typed comparison path so UUID columns no longer require app-side manual `::uuid` / `::text` casts.
 
 Canonical style for reads is to call `.select(...)` first, then apply filters:
 
@@ -412,11 +412,102 @@ mutation.finally(() => …);
 
 The request fires only once regardless of how many times you call `.then()` or await the object.
 
-## React hook
+## React hooks
 
 ```tsx
 "use client";
 
+import {
+  AthenaQueryClientProvider,
+  createAthenaQueryClient,
+  useAthenaGateway,
+  useMutation,
+  useQuery,
+} from "@xylex-group/athena/react";
+import { createClient } from "@xylex-group/athena";
+
+const queryClient = createAthenaQueryClient({
+  cache: { mode: "none" }, // default: no persistent data cache, inflight dedupe only
+});
+
+const athena = createClient(
+  process.env.NEXT_PUBLIC_ATHENA_URL!,
+  process.env.NEXT_PUBLIC_ATHENA_API_KEY!,
+);
+
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+};
+
+type CreateProductInput = {
+  name: string;
+  price: number;
+};
+
+function ProductsInner() {
+  const products = useQuery<Product[]>({
+    queryKey: ["products"],
+    queryFn: () =>
+      athena.from("products").select("id,name,price").limit(50),
+  });
+
+  const createProduct = useMutation<CreateProductInput, Product>({
+    mutationFn: (input) =>
+      athena.from("products").insert(input).select("id,name,price").single(),
+    onSuccess: () => {
+      void products.refetch();
+    },
+  });
+
+  if (products.isLoading) return <div>Loading...</div>;
+  if (products.error) return <div>{products.error.message}</div>;
+
+  return (
+    <div>
+      <button
+        onClick={() => {
+          createProduct.mutate({ name: "New product", price: 99 });
+        }}
+      >
+        Add Product
+      </button>
+      {products.data?.map((product) => (
+        <div key={product.id}>
+          {product.name} - {product.price}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export function Products() {
+  return (
+    <AthenaQueryClientProvider client={queryClient}>
+      <ProductsInner />
+    </AthenaQueryClientProvider>
+  );
+}
+```
+
+Available React APIs:
+
+- `useAthenaGateway`: low-level gateway hook (`fetchGateway`, `insertGateway`, `updateGateway`, `deleteGateway`, `rpcGateway`) with request/response logging.
+- `createAthenaQueryClient` + `AthenaQueryClientProvider`: Athena query runtime boundary for scoped state and subscriptions.
+- `useQuery`: lightweight read lifecycle hook (`status`, `isFetching`, `refetch`, `reset`) with normalized Athena error/result handling.
+- `useMutation`: lightweight write lifecycle hook (`mutate`, `mutateAsync`, `reset`) with manual refetch/invalidation flow.
+
+By design this is not a cache-heavy React Query clone:
+
+- No TanStack/React Query dependency.
+- No persistent data cache by default (`cache.mode = "none"`).
+- Inflight dedupe for identical query keys is enabled.
+- Manual `refetch()` after mutations is the default invalidation strategy.
+
+`useAthenaGateway` example:
+
+```tsx
 import { useAthenaGateway } from "@xylex-group/athena/react";
 import { useEffect } from "react";
 
@@ -427,7 +518,7 @@ export function UsersPanel() {
   });
 
   useEffect(() => {
-    fetchGateway({
+    void fetchGateway({
       table_name: "users",
       columns: ["id", "email"],
       limit: 25,
@@ -441,9 +532,7 @@ export function UsersPanel() {
 }
 ```
 
-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`.
+`useAthenaGateway` config options mirror the client options: `baseUrl`, `apiKey`, `headers`, `userId`, `organizationId`, `publishEvent`.
 
 ## User context headers
 

package/dist/{errors-DQerAaXC.d.cts → errors-C4GJaFI_.d.cts}

@@ -220,4 +220,4 @@ declare class AthenaGatewayError extends Error {
 }
 declare function isAthenaGatewayError(error: unknown): error is AthenaGatewayError;
 
-export { type AthenaConditionValue as A, type BackendConfig as B, type BackendType as a, type AthenaConditionCastType as b, type AthenaConditionArrayValue as c, type AthenaConditionOperator as d, type AthenaGatewayCallOptions as e, type AthenaGatewayErrorDetails as f, type AthenaRpcCallOptions as g, AthenaGatewayError as h, type AthenaGatewayErrorCode as i, type AthenaRpcFilter as j, type AthenaRpcFilterOperator as k, type AthenaRpcOrder as l, type AthenaRpcPayload as m, Backend as n, isAthenaGatewayError as o, type AthenaGatewayHookConfig as p, type AthenaGatewayHookResult as q, type AthenaDeletePayload as r, type AthenaFetchPayload as s, type AthenaGatewayResponse as t, type AthenaInsertPayload as u, type AthenaUpdatePayload as v };
+export { type AthenaGatewayCallOptions as A, type BackendConfig as B, type AthenaConditionValue as a, type AthenaConditionCastType as b, type AthenaConditionArrayValue as c, type AthenaConditionOperator as d, type AthenaGatewayErrorDetails as e, type AthenaRpcCallOptions as f, type BackendType as g, Backend as h, AthenaGatewayError as i, isAthenaGatewayError as j, type AthenaRpcFilter as k, type AthenaRpcFilterOperator as l, type AthenaRpcOrder as m, type AthenaRpcPayload as n, type AthenaGatewayErrorCode as o, type AthenaGatewayHookConfig as p, type AthenaGatewayHookResult as q, type AthenaFetchPayload as r, type AthenaInsertPayload as s, type AthenaUpdatePayload as t, type AthenaDeletePayload as u, type AthenaGatewayResponse as v };

package/dist/{errors-DQerAaXC.d.ts → errors-C4GJaFI_.d.ts}

@@ -220,4 +220,4 @@ declare class AthenaGatewayError extends Error {
 }
 declare function isAthenaGatewayError(error: unknown): error is AthenaGatewayError;
 
-export { type AthenaConditionValue as A, type BackendConfig as B, type BackendType as a, type AthenaConditionCastType as b, type AthenaConditionArrayValue as c, type AthenaConditionOperator as d, type AthenaGatewayCallOptions as e, type AthenaGatewayErrorDetails as f, type AthenaRpcCallOptions as g, AthenaGatewayError as h, type AthenaGatewayErrorCode as i, type AthenaRpcFilter as j, type AthenaRpcFilterOperator as k, type AthenaRpcOrder as l, type AthenaRpcPayload as m, Backend as n, isAthenaGatewayError as o, type AthenaGatewayHookConfig as p, type AthenaGatewayHookResult as q, type AthenaDeletePayload as r, type AthenaFetchPayload as s, type AthenaGatewayResponse as t, type AthenaInsertPayload as u, type AthenaUpdatePayload as v };
+export { type AthenaGatewayCallOptions as A, type BackendConfig as B, type AthenaConditionValue as a, type AthenaConditionCastType as b, type AthenaConditionArrayValue as c, type AthenaConditionOperator as d, type AthenaGatewayErrorDetails as e, type AthenaRpcCallOptions as f, type BackendType as g, Backend as h, AthenaGatewayError as i, isAthenaGatewayError as j, type AthenaRpcFilter as k, type AthenaRpcFilterOperator as l, type AthenaRpcOrder as m, type AthenaRpcPayload as n, type AthenaGatewayErrorCode as o, type AthenaGatewayHookConfig as p, type AthenaGatewayHookResult as q, type AthenaFetchPayload as r, type AthenaInsertPayload as s, type AthenaUpdatePayload as t, type AthenaDeletePayload as u, type AthenaGatewayResponse as v };

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { B as BackendConfig, a as BackendType, A as AthenaConditionValue, b as AthenaConditionCastType, c as AthenaConditionArrayValue, d as AthenaConditionOperator, e as AthenaGatewayCallOptions, f as AthenaGatewayErrorDetails, g as AthenaRpcCallOptions } from './errors-DQerAaXC.cjs';
-export { h as AthenaGatewayError, i as AthenaGatewayErrorCode, j as AthenaRpcFilter, k as AthenaRpcFilterOperator, l as AthenaRpcOrder, m as AthenaRpcPayload, n as Backend, o as isAthenaGatewayError } from './errors-DQerAaXC.cjs';
+import { A as AthenaGatewayCallOptions, a as AthenaConditionValue, b as AthenaConditionCastType, c as AthenaConditionArrayValue, d as AthenaConditionOperator, e as AthenaGatewayErrorDetails, f as AthenaRpcCallOptions, B as BackendConfig, g as BackendType } from './errors-C4GJaFI_.cjs';
+export { i as AthenaGatewayError, o as AthenaGatewayErrorCode, k as AthenaRpcFilter, l as AthenaRpcFilterOperator, m as AthenaRpcOrder, n as AthenaRpcPayload, h as Backend, j as isAthenaGatewayError } from './errors-C4GJaFI_.cjs';
 
 interface AthenaResult<T> {
     data: T | null;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BackendConfig, a as BackendType, A as AthenaConditionValue, b as AthenaConditionCastType, c as AthenaConditionArrayValue, d as AthenaConditionOperator, e as AthenaGatewayCallOptions, f as AthenaGatewayErrorDetails, g as AthenaRpcCallOptions } from './errors-DQerAaXC.js';
-export { h as AthenaGatewayError, i as AthenaGatewayErrorCode, j as AthenaRpcFilter, k as AthenaRpcFilterOperator, l as AthenaRpcOrder, m as AthenaRpcPayload, n as Backend, o as isAthenaGatewayError } from './errors-DQerAaXC.js';
+import { A as AthenaGatewayCallOptions, a as AthenaConditionValue, b as AthenaConditionCastType, c as AthenaConditionArrayValue, d as AthenaConditionOperator, e as AthenaGatewayErrorDetails, f as AthenaRpcCallOptions, B as BackendConfig, g as BackendType } from './errors-C4GJaFI_.js';
+export { i as AthenaGatewayError, o as AthenaGatewayErrorCode, k as AthenaRpcFilter, l as AthenaRpcFilterOperator, m as AthenaRpcOrder, n as AthenaRpcPayload, h as Backend, j as isAthenaGatewayError } from './errors-C4GJaFI_.js';
 
 interface AthenaResult<T> {
     data: T | null;