@xylex-group/athena 1.4.0 → 1.4.1

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `1.4.0`
+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.
 
 ## Install
@@ -153,10 +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
-  .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
@@ -169,8 +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
-```
+  .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:
 

package/dist/{errors-CB-eJQ7x.d.cts → errors-DQerAaXC.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 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 };

package/dist/{errors-CB-eJQ7x.d.ts → errors-DQerAaXC.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 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 };

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,