@xylex-group/athena 1.7.0 → 1.9.0

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `1.7.0`
+current version: `1.9.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
@@ -390,11 +390,23 @@ const { data: user } = await athena
   .single();
 ```
 
-`maybeSingle` behaves identically — both return the first element of the result set.
-
-### RPC
-
-Use `athena.rpc(...)` for Postgres function calls. By default it calls `POST /gateway/rpc`, and with `{ get: true }` it uses the compatibility route `GET /rpc/{function_name}`.
+`maybeSingle` behaves identically — both return the first element of the result set.
+
+### Table schema targeting
+
+Use `schema` in table call options to qualify unqualified table names:
+
+```ts
+const { data } = await athena
+  .from("users")
+  .select("id,email", { schema: "public" });
+```
+
+This resolves the table target to `public.users`.
+
+### RPC
+
+Use `athena.rpc(...)` for Postgres function calls. By default it calls `POST /gateway/rpc`, and with `{ get: true }` it uses the compatibility route `GET /rpc/{function_name}`.
 
 ```ts
 const { data, count } = await athena
@@ -428,11 +440,12 @@ RPC options: `schema`, `count` (`"exact" | "planned" | "estimated"`), `head`, `g
 
 Pass options as the second argument to `.select()`:
 
-| Option       | Type                                  | Description                                  |
-| ------------ | ------------------------------------- | -------------------------------------------- |
-| `count`      | `"exact" \| "planned" \| "estimated"` | request a row count alongside the data       |
-| `head`       | `boolean`                             | return response headers only (no rows)       |
-| `stripNulls` | `boolean`                             | strip null values from rows (default `true`) |
+| Option       | Type                                  | Description                                  |
+| ------------ | ------------------------------------- | -------------------------------------------- |
+| `schema`     | `string`                              | qualify unqualified table names for table calls |
+| `count`      | `"exact" \| "planned" \| "estimated"` | request a row count alongside the data       |
+| `head`       | `boolean`                             | return response headers only (no rows)       |
+| `stripNulls` | `boolean`                             | strip null values from rows (default `true`) |
 
 ```ts
 const { data } = await athena

package/dist/cli/index.cjs

@@ -1231,6 +1231,12 @@ function mergeOptions(...options) {
     return { ...acc, ...next };
   }, void 0);
 }
+function asAthenaJsonObject(value) {
+  return value;
+}
+function asAthenaJsonObjectArray(values) {
+  return values;
+}
 function createMutationQuery(executor, defaultColumns = DEFAULT_COLUMNS) {
   let selectedColumns = defaultColumns === null ? void 0 : defaultColumns;
   let selectedOptions;
@@ -1319,6 +1325,22 @@ function buildSelectColumnsClause(columns) {
   }
   return quoteSelectColumnsExpression(columns);
 }
+function resolveTableNameForCall(tableName, schema) {
+  if (!schema) return tableName;
+  const normalizedSchema = schema.trim();
+  if (!normalizedSchema) {
+    throw new Error("schema option must be a non-empty string");
+  }
+  if (tableName.includes(".")) {
+    if (tableName.startsWith(`${normalizedSchema}.`)) {
+      return tableName;
+    }
+    throw new Error(
+      `schema option "${normalizedSchema}" conflicts with schema-qualified table "${tableName}"`
+    );
+  }
+  return `${normalizedSchema}.${tableName}`;
+}
 function conditionToSqlClause(condition) {
   if (!condition.column) return null;
   const column = withCast(quoteQualifiedIdentifier(condition.column), condition.column_cast);
@@ -1398,23 +1420,27 @@ function buildTypedSelectQuery(input) {
 function createFilterMethods(state, addCondition, self) {
   return {
     eq(column, value) {
-      if (shouldUseUuidTextComparison(column, value)) {
-        addCondition("eq", column, value, { columnCast: "text" });
+      const columnName = String(column);
+      if (shouldUseUuidTextComparison(columnName, value)) {
+        addCondition("eq", columnName, value, { columnCast: "text" });
       } else {
-        addCondition("eq", column, value);
+        addCondition("eq", columnName, value);
       }
       return self;
     },
     eqCast(column, value, cast) {
-      addCondition("eq", column, value, { valueCast: cast });
+      addCondition("eq", String(column), value, { valueCast: cast });
       return self;
     },
     eqUuid(column, value) {
-      addCondition("eq", column, value, { valueCast: "uuid" });
+      addCondition("eq", String(column), value, { valueCast: "uuid" });
       return self;
     },
     match(filters) {
       Object.entries(filters).forEach(([column, value]) => {
+        if (value === void 0) {
+          return;
+        }
         if (shouldUseUuidTextComparison(column, value)) {
           addCondition("eq", column, value, { columnCast: "text" });
         } else {
@@ -1450,60 +1476,61 @@ function createFilterMethods(state, addCondition, self) {
     },
     order(column, options) {
       state.order = {
-        field: column,
+        field: String(column),
         direction: options?.ascending === false ? "descending" : "ascending"
       };
       return self;
     },
     gt(column, value) {
-      addCondition("gt", column, value);
+      addCondition("gt", String(column), value);
       return self;
     },
     gte(column, value) {
-      addCondition("gte", column, value);
+      addCondition("gte", String(column), value);
       return self;
     },
     lt(column, value) {
-      addCondition("lt", column, value);
+      addCondition("lt", String(column), value);
       return self;
     },
     lte(column, value) {
-      addCondition("lte", column, value);
+      addCondition("lte", String(column), value);
       return self;
     },
     neq(column, value) {
-      addCondition("neq", column, value);
+      addCondition("neq", String(column), value);
       return self;
     },
     like(column, value) {
-      addCondition("like", column, value);
+      addCondition("like", String(column), value);
       return self;
     },
     ilike(column, value) {
-      addCondition("ilike", column, value);
+      addCondition("ilike", String(column), value);
       return self;
     },
     is(column, value) {
-      addCondition("is", column, value);
+      addCondition("is", String(column), value);
       return self;
     },
     in(column, values) {
-      addCondition("in", column, values);
+      addCondition("in", String(column), values);
       return self;
     },
     contains(column, values) {
-      addCondition("contains", column, values);
+      addCondition("contains", String(column), values);
       return self;
     },
     containedBy(column, values) {
-      addCondition("containedBy", column, values);
+      addCondition("containedBy", String(column), values);
       return self;
     },
     not(columnOrExpression, operator, value) {
+      const expression = String(columnOrExpression);
       if (operator != null && value !== void 0) {
-        addCondition("not", void 0, `${columnOrExpression}.${operator}.${stringifyFilterValue(value)}`);
+        addCondition("not", void 0, `${expression}.${operator}.${stringifyFilterValue(value)}`);
       } else {
-        addCondition("not", void 0, columnOrExpression);
+        addCondition("not", void 0, expression);
       }
       return self;
     },
@@ -1673,15 +1700,20 @@ function createTableBuilder(tableName, client) {
     state.conditions.push(condition);
   };
   const builder = {};
-  const filterMethods = createFilterMethods(state, addCondition, builder);
+  const filterMethods = createFilterMethods(
+    state,
+    addCondition,
+    builder
+  );
   const runSelect = async (columns = DEFAULT_COLUMNS, options) => {
+    const resolvedTableName = resolveTableNameForCall(tableName, options?.schema);
     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,
+        tableName: resolvedTableName,
         columns,
         conditions,
         limit: state.limit,
@@ -1696,7 +1728,7 @@ function createTableBuilder(tableName, client) {
       }
     }
     const payload = {
-      table_name: tableName,
+      table_name: resolvedTableName,
       columns,
       conditions,
       limit: state.limit,
@@ -1753,9 +1785,10 @@ function createTableBuilder(tableName, client) {
       if (Array.isArray(values)) {
         const executeInsertMany = async (columns, selectOptions) => {
           const mergedOptions = mergeOptions(options, selectOptions);
+          const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
           const payload = {
-            table_name: tableName,
-            insert_body: values
+            table_name: resolvedTableName,
+            insert_body: asAthenaJsonObjectArray(values)
           };
           if (columns) payload.columns = columns;
           if (mergedOptions?.count) payload.count = mergedOptions.count;
@@ -1770,9 +1803,10 @@ function createTableBuilder(tableName, client) {
       }
       const executeInsertOne = async (columns, selectOptions) => {
         const mergedOptions = mergeOptions(options, selectOptions);
+        const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
-          table_name: tableName,
-          insert_body: values
+          table_name: resolvedTableName,
+          insert_body: asAthenaJsonObject(values)
         };
         if (columns) payload.columns = columns;
         if (mergedOptions?.count) payload.count = mergedOptions.count;
@@ -1789,10 +1823,11 @@ function createTableBuilder(tableName, client) {
       if (Array.isArray(values)) {
         const executeUpsertMany = async (columns, selectOptions) => {
           const mergedOptions = mergeOptions(options, selectOptions);
+          const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
           const payload = {
-            table_name: tableName,
-            insert_body: values,
-            update_body: options?.updateBody ? options.updateBody : void 0
+            table_name: resolvedTableName,
+            insert_body: asAthenaJsonObjectArray(values),
+            update_body: options?.updateBody ? asAthenaJsonObject(options.updateBody) : void 0
           };
           if (columns) payload.columns = columns;
           if (options?.onConflict) payload.on_conflict = options.onConflict;
@@ -1808,10 +1843,11 @@ function createTableBuilder(tableName, client) {
       }
       const executeUpsertOne = async (columns, selectOptions) => {
         const mergedOptions = mergeOptions(options, selectOptions);
+        const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
-          table_name: tableName,
-          insert_body: values,
-          update_body: options?.updateBody ? options.updateBody : void 0
+          table_name: resolvedTableName,
+          insert_body: asAthenaJsonObject(values),
+          update_body: options?.updateBody ? asAthenaJsonObject(options.updateBody) : void 0
         };
         if (columns) payload.columns = columns;
         if (options?.onConflict) payload.on_conflict = options.onConflict;
@@ -1829,9 +1865,10 @@ function createTableBuilder(tableName, client) {
       const executeUpdate = async (columns, selectOptions) => {
         const filters = state.conditions.length ? [...state.conditions] : void 0;
         const mergedOptions = mergeOptions(options, selectOptions);
+        const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
-          table_name: tableName,
-          set: values,
+          table_name: resolvedTableName,
+          set: asAthenaJsonObject(values),
           conditions: filters,
           strip_nulls: mergedOptions?.stripNulls ?? true
         };
@@ -1857,8 +1894,9 @@ function createTableBuilder(tableName, client) {
       }
       const executeDelete = async (columns, selectOptions) => {
         const mergedOptions = mergeOptions(options, selectOptions);
+        const resolvedTableName = resolveTableNameForCall(tableName, mergedOptions?.schema);
         const payload = {
-          table_name: tableName,
+          table_name: resolvedTableName,
           resource_id: resourceId,
           conditions: filters
         };