@xylex-group/athena 1.4.0 → 1.5.0

package/README.md

@@ -1,7 +1,7 @@
 # athena-js
 
-current version: `1.4.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.
+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
@@ -156,6 +156,8 @@ 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
   .gt("level", 5) // column > value
   .gte("score", 100) // column >= value
@@ -172,6 +174,8 @@ const { data } = await athena
   .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:
 
 ```ts
@@ -408,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";
 
@@ -423,7 +518,7 @@ export function UsersPanel() {
   });
 
   useEffect(() => {
-    fetchGateway({
+    void fetchGateway({
       table_name: "users",
       columns: ["id", "email"],
       limit: 25,
@@ -437,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-CB-eJQ7x.d.cts → errors-C4GJaFI_.d.cts}

@@ -8,14 +8,29 @@ type AthenaGatewayEndpointPath = '/gateway/fetch' | '/gateway/insert' | '/gatewa
 type AthenaCountOption = 'exact' | 'planned' | 'estimated';
 type AthenaConditionValue = string | number | boolean | null;
 type AthenaConditionArrayValue = Array<AthenaConditionValue>;
+type AthenaConditionCastType = string;
 type AthenaConditionOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'is' | 'in' | 'contains' | 'containedBy' | 'not' | 'or';
 interface AthenaGatewayCondition {
     column?: string;
     operator: AthenaConditionOperator;
     value?: AthenaConditionValue | AthenaConditionArrayValue | string;
+    /**
+     * Optional explicit cast for `value` (for example `"uuid"`).
+     * Older gateways ignore unknown fields; newer gateways may use this hint.
+     */
+    value_cast?: AthenaConditionCastType;
+    /**
+     * Optional explicit cast for `column` (for example `"text"`).
+     * Used by SDK SQL fallback for typed comparisons.
+     */
+    column_cast?: AthenaConditionCastType;
     /** Back-compat shape expected by older gateway implementations */
     eq_column?: string;
     eq_value?: AthenaConditionValue | AthenaConditionArrayValue | string;
+    /** Optional cast hint aligned with legacy eq_* fields */
+    eq_value_cast?: AthenaConditionCastType;
+    /** Optional cast hint aligned with legacy eq_* fields */
+    eq_column_cast?: AthenaConditionCastType;
 }
 type AthenaSortDirection = 'ascending' | 'descending';
 interface AthenaSortBy {
@@ -205,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 AthenaConditionArrayValue as b, type AthenaConditionOperator as c, type AthenaGatewayCallOptions as d, type AthenaGatewayErrorDetails as e, type AthenaRpcCallOptions as f, AthenaGatewayError as g, type AthenaGatewayErrorCode as h, type AthenaRpcFilter as i, type AthenaRpcFilterOperator as j, type AthenaRpcOrder as k, type AthenaRpcPayload as l, Backend as m, isAthenaGatewayError as n, type AthenaGatewayHookConfig as o, type AthenaGatewayHookResult as p, type AthenaDeletePayload as q, type AthenaFetchPayload as r, type AthenaGatewayResponse as s, type AthenaInsertPayload as t, type AthenaUpdatePayload as u };
+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-CB-eJQ7x.d.ts → errors-C4GJaFI_.d.ts}

@@ -8,14 +8,29 @@ type AthenaGatewayEndpointPath = '/gateway/fetch' | '/gateway/insert' | '/gatewa
 type AthenaCountOption = 'exact' | 'planned' | 'estimated';
 type AthenaConditionValue = string | number | boolean | null;
 type AthenaConditionArrayValue = Array<AthenaConditionValue>;
+type AthenaConditionCastType = string;
 type AthenaConditionOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'is' | 'in' | 'contains' | 'containedBy' | 'not' | 'or';
 interface AthenaGatewayCondition {
     column?: string;
     operator: AthenaConditionOperator;
     value?: AthenaConditionValue | AthenaConditionArrayValue | string;
+    /**
+     * Optional explicit cast for `value` (for example `"uuid"`).
+     * Older gateways ignore unknown fields; newer gateways may use this hint.
+     */
+    value_cast?: AthenaConditionCastType;
+    /**
+     * Optional explicit cast for `column` (for example `"text"`).
+     * Used by SDK SQL fallback for typed comparisons.
+     */
+    column_cast?: AthenaConditionCastType;
     /** Back-compat shape expected by older gateway implementations */
     eq_column?: string;
     eq_value?: AthenaConditionValue | AthenaConditionArrayValue | string;
+    /** Optional cast hint aligned with legacy eq_* fields */
+    eq_value_cast?: AthenaConditionCastType;
+    /** Optional cast hint aligned with legacy eq_* fields */
+    eq_column_cast?: AthenaConditionCastType;
 }
 type AthenaSortDirection = 'ascending' | 'descending';
 interface AthenaSortBy {
@@ -205,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 AthenaConditionArrayValue as b, type AthenaConditionOperator as c, type AthenaGatewayCallOptions as d, type AthenaGatewayErrorDetails as e, type AthenaRpcCallOptions as f, AthenaGatewayError as g, type AthenaGatewayErrorCode as h, type AthenaRpcFilter as i, type AthenaRpcFilterOperator as j, type AthenaRpcOrder as k, type AthenaRpcPayload as l, Backend as m, isAthenaGatewayError as n, type AthenaGatewayHookConfig as o, type AthenaGatewayHookResult as p, type AthenaDeletePayload as q, type AthenaFetchPayload as r, type AthenaGatewayResponse as s, type AthenaInsertPayload as t, type AthenaUpdatePayload as u };
+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.cjs

@@ -368,6 +368,8 @@ function createAthenaGatewayClient(config = {}) {
 
 // src/client.ts
 var DEFAULT_COLUMNS = "*";
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var SAFE_CAST_PATTERN = /^[a-z_][a-z0-9_]*(?:\[\])?$/i;
 function formatResult(response) {
   const result = {
     data: response.data ?? null,
@@ -448,14 +450,149 @@ function stringifyFilterValue(value) {
   }
   return String(value);
 }
+function isUuidString(value) {
+  return UUID_PATTERN.test(value.trim());
+}
+function isUuidIdentifierColumn(column) {
+  return column === "id" || /(?:^|_)uuid(?:_|$)/i.test(column) || /_id$/i.test(column);
+}
+function shouldUseUuidTextComparison(column, value) {
+  return typeof value === "string" && isUuidString(value) && isUuidIdentifierColumn(column);
+}
+function normalizeCast(cast) {
+  const normalized = cast.trim().toLowerCase();
+  if (!SAFE_CAST_PATTERN.test(normalized)) {
+    throw new Error(`Invalid cast type "${cast}"`);
+  }
+  return normalized;
+}
+function escapeSqlStringLiteral(value) {
+  return value.replace(/'/g, "''");
+}
+function quoteIdentifier(identifier) {
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+function quoteQualifiedIdentifier(identifier) {
+  return identifier.split(".").map((segment) => quoteIdentifier(segment)).join(".");
+}
+function toSqlLiteral(value) {
+  if (value === null) return "NULL";
+  if (typeof value === "number") return Number.isFinite(value) ? String(value) : "NULL";
+  if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+  return `'${escapeSqlStringLiteral(value)}'`;
+}
+function withCast(expression, cast) {
+  if (!cast) return expression;
+  return `${expression}::${normalizeCast(cast)}`;
+}
+function buildSelectColumnsClause(columns) {
+  if (Array.isArray(columns)) {
+    return columns.map((column) => quoteQualifiedIdentifier(column)).join(", ");
+  }
+  return columns;
+}
+function conditionToSqlClause(condition) {
+  if (!condition.column) return null;
+  const column = withCast(quoteQualifiedIdentifier(condition.column), condition.column_cast);
+  const value = condition.value;
+  const sqlOperator = {
+    eq: "=",
+    neq: "!=",
+    gt: ">",
+    gte: ">=",
+    lt: "<",
+    lte: "<=",
+    like: "LIKE",
+    ilike: "ILIKE"
+  };
+  switch (condition.operator) {
+    case "eq":
+    case "neq":
+    case "gt":
+    case "gte":
+    case "lt":
+    case "lte":
+    case "like":
+    case "ilike": {
+      if (Array.isArray(value) || value === void 0) return null;
+      const rhs = withCast(toSqlLiteral(value), condition.value_cast);
+      return `${column} ${sqlOperator[condition.operator]} ${rhs}`;
+    }
+    case "is": {
+      if (value === null) return `${column} IS NULL`;
+      if (value === true) return `${column} IS TRUE`;
+      if (value === false) return `${column} IS FALSE`;
+      return null;
+    }
+    case "in": {
+      if (!Array.isArray(value)) return null;
+      if (value.length === 0) return "FALSE";
+      const values = value.map((item) => withCast(toSqlLiteral(item), condition.value_cast));
+      return `${column} IN (${values.join(", ")})`;
+    }
+    default:
+      return null;
+  }
+}
+function buildTypedSelectQuery(input) {
+  const whereClauses = [];
+  for (const condition of input.conditions) {
+    const clause = conditionToSqlClause(condition);
+    if (!clause) return null;
+    whereClauses.push(clause);
+  }
+  let limit = input.limit;
+  let offset = input.offset;
+  if (limit === void 0 && input.pageSize !== void 0) {
+    limit = input.pageSize;
+  }
+  if (offset === void 0 && input.pageSize !== void 0 && input.currentPage !== void 0 && input.currentPage > 0) {
+    offset = (input.currentPage - 1) * input.pageSize;
+  }
+  const sqlParts = [
+    `SELECT ${buildSelectColumnsClause(input.columns)} FROM ${quoteQualifiedIdentifier(input.tableName)}`
+  ];
+  if (whereClauses.length > 0) {
+    sqlParts.push(`WHERE ${whereClauses.join(" AND ")}`);
+  }
+  if (input.order?.field) {
+    const direction = input.order.direction === "descending" ? "DESC" : "ASC";
+    sqlParts.push(`ORDER BY ${quoteQualifiedIdentifier(input.order.field)} ${direction}`);
+  }
+  if (limit !== void 0) {
+    sqlParts.push(`LIMIT ${Math.max(0, Math.trunc(limit))}`);
+  }
+  if (offset !== void 0) {
+    sqlParts.push(`OFFSET ${Math.max(0, Math.trunc(offset))}`);
+  }
+  return `${sqlParts.join(" ")};`;
+}
 function createFilterMethods(state, addCondition, self) {
   return {
     eq(column, value) {
-      addCondition("eq", column, value);
+      if (shouldUseUuidTextComparison(column, value)) {
+        addCondition("eq", column, value, { columnCast: "text" });
+      } else {
+        addCondition("eq", column, value);
+      }
+      return self;
+    },
+    eqCast(column, value, cast) {
+      addCondition("eq", column, value, { valueCast: cast });
+      return self;
+    },
+    eqUuid(column, value) {
+      addCondition("eq", column, value, { valueCast: "uuid" });
       return self;
     },
     match(filters) {
-      Object.entries(filters).forEach(([column, value]) => addCondition("eq", column, value));
+      Object.entries(filters).forEach(([column, value]) => {
+        if (shouldUseUuidTextComparison(column, value)) {
+          addCondition("eq", column, value, { columnCast: "text" });
+        } else {
+          addCondition("eq", column, value);
+        }
+      });
       return self;
     },
     range(from, to) {
@@ -679,7 +816,7 @@ function createTableBuilder(tableName, client) {
   const state = {
     conditions: []
   };
-  const addCondition = (operator, column, value) => {
+  const addCondition = (operator, column, value, hints) => {
     const condition = { operator };
     if (column) {
       condition.column = column;
@@ -693,15 +830,47 @@ function createTableBuilder(tableName, client) {
         condition.eq_value = value;
       }
     }
+    if (hints?.valueCast) {
+      condition.value_cast = hints.valueCast;
+      if (operator === "eq") {
+        condition.eq_value_cast = hints.valueCast;
+      }
+    }
+    if (hints?.columnCast) {
+      condition.column_cast = hints.columnCast;
+      if (operator === "eq") {
+        condition.eq_column_cast = hints.columnCast;
+      }
+    }
     state.conditions.push(condition);
   };
   const builder = {};
   const filterMethods = createFilterMethods(state, addCondition, builder);
   const runSelect = async (columns = DEFAULT_COLUMNS, options) => {
+    const conditions = state.conditions.length ? state.conditions.map((condition) => ({ ...condition })) : void 0;
+    const hasTypedEqualityComparison = conditions?.some(
+      (condition) => condition.operator === "eq" && (condition.value_cast !== void 0 || condition.column_cast !== void 0)
+    ) ?? false;
+    if (hasTypedEqualityComparison && !options?.head && !options?.count && conditions) {
+      const query = buildTypedSelectQuery({
+        tableName,
+        columns,
+        conditions,
+        limit: state.limit,
+        offset: state.offset,
+        currentPage: state.currentPage,
+        pageSize: state.pageSize,
+        order: state.order
+      });
+      if (query) {
+        const queryResponse = await client.queryGateway({ query }, options);
+        return formatResult(queryResponse);
+      }
+    }
     const payload = {
       table_name: tableName,
       columns,
-      conditions: state.conditions.length ? [...state.conditions] : void 0,
+      conditions,
       limit: state.limit,
       offset: state.offset,
       current_page: state.currentPage,