@xylex-group/athena 2.3.0 → 2.4.0

package/dist/cli/index.cjs

@@ -499,6 +499,7 @@ function classifyKind(status, code, message) {
   if (status === 404 || hasNotFoundPattern) return "not_found";
   if (status === 401 || status === 403 || hasAuthPattern) return "auth";
   if (status === 429 || hasRateLimitPattern) return "rate_limit";
+  if (code === "INVALID_URL") return "validation";
   if (status === 400 || status === 422 || hasValidationPattern) return "validation";
   if (code === "NETWORK_ERROR" || status === 0 || status !== void 0 && status >= 500 || hasTransientPattern) {
     return "transient";
@@ -506,6 +507,9 @@ function classifyKind(status, code, message) {
   return "unknown";
 }
 function toAthenaErrorCode(kind, status, gatewayCode) {
+  if (gatewayCode === "INVALID_URL") {
+    return AthenaErrorCode.ValidationFailed;
+  }
   if (gatewayCode === "NETWORK_ERROR" || kind === "transient" && status === 0) {
     return AthenaErrorCode.NetworkUnavailable;
   }
@@ -1359,8 +1363,74 @@ function generateArtifactsFromSnapshot(snapshot, config) {
   return new ArtifactComposer(snapshot, normalizedConfig).compose();
 }
 
+// src/gateway/url.ts
+var ATHENA_DEFAULT_BASE_URL = "https://athena-db.com";
+function describeReceivedValue(value) {
+  if (value === void 0) return "undefined";
+  if (value === null) return "null";
+  if (typeof value === "string") {
+    return value.trim().length > 0 ? JSON.stringify(value) : "an empty string";
+  }
+  return `${typeof value} ${JSON.stringify(value)}`;
+}
+function invalidBaseUrlError(message, hint) {
+  return new AthenaGatewayError({
+    code: "INVALID_URL",
+    message,
+    status: 0,
+    hint
+  });
+}
+function normalizeAthenaGatewayBaseUrl(input, options = {}) {
+  const label = options.label ?? "Athena gateway base URL";
+  const candidate = input ?? options.defaultBaseUrl;
+  if (candidate === void 0 || candidate === null) {
+    throw invalidBaseUrlError(
+      `${label} must be a non-empty absolute http(s) URL. Received ${describeReceivedValue(input)}.`,
+      'Set ATHENA_URL (or pass createClient(url, ...)) to a full URL such as "https://mirror3.athena-db.com".'
+    );
+  }
+  const trimmed = candidate.trim();
+  if (!trimmed) {
+    throw invalidBaseUrlError(
+      `${label} must be a non-empty absolute http(s) URL. Received ${describeReceivedValue(candidate)}.`,
+      'Set ATHENA_URL (or pass createClient(url, ...)) to a full URL such as "https://mirror3.athena-db.com".'
+    );
+  }
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw invalidBaseUrlError(
+      `${label} must be a valid absolute http(s) URL. Received ${describeReceivedValue(candidate)}.`,
+      'Use a full URL including the protocol, for example "https://mirror3.athena-db.com".'
+    );
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw invalidBaseUrlError(
+      `${label} must use http or https. Received ${JSON.stringify(trimmed)}.`,
+      'Use an Athena gateway URL such as "https://mirror3.athena-db.com".'
+    );
+  }
+  if (parsed.search || parsed.hash) {
+    throw invalidBaseUrlError(
+      `${label} must not include query parameters or hash fragments. Received ${JSON.stringify(trimmed)}.`,
+      'Pass only the base URL. Endpoint paths such as "/gateway/fetch" are appended by the SDK.'
+    );
+  }
+  return parsed.toString().replace(/\/+$/, "");
+}
+function buildAthenaGatewayUrl(baseUrl, path) {
+  if (!path.startsWith("/")) {
+    throw invalidBaseUrlError(
+      `Athena gateway path must start with "/". Received ${JSON.stringify(path)}.`,
+      'Use a leading slash such as "/gateway/fetch" or "/".'
+    );
+  }
+  return `${baseUrl}${path}`;
+}
+
 // src/gateway/client.ts
-var DEFAULT_BASE_URL = "https://athena-db.com";
 var DEFAULT_CLIENT = "railway_direct";
 var FALLBACK_SDK_VERSION = "1.3.0";
 var SDK_NAME = "xylex-group/athena";
@@ -1557,9 +1627,168 @@ function buildHeaders(config, options) {
   });
   return headers;
 }
+function toInvalidUrlResponse(error, endpoint, method) {
+  const message = error instanceof Error ? error.message : String(error);
+  const gatewayError = error instanceof AthenaGatewayError ? error : new AthenaGatewayError({
+    code: "INVALID_URL",
+    message,
+    status: 0,
+    endpoint,
+    method,
+    cause: message,
+    hint: "Set ATHENA_URL to a full http(s) URL before running queries."
+  });
+  return {
+    ok: false,
+    status: 0,
+    statusText: null,
+    data: null,
+    error: gatewayError.message,
+    errorDetails: detailsFromError(
+      new AthenaGatewayError({
+        code: gatewayError.code,
+        message: gatewayError.message,
+        status: gatewayError.status,
+        endpoint,
+        method,
+        requestId: gatewayError.requestId,
+        hint: gatewayError.hint,
+        cause: gatewayError.causeDetail
+      })
+    ),
+    raw: null
+  };
+}
+function resolveGatewayBaseUrl(input) {
+  return normalizeAthenaGatewayBaseUrl(input, {
+    defaultBaseUrl: ATHENA_DEFAULT_BASE_URL
+  });
+}
+function resolveProbePath(path) {
+  if (!path) return "/";
+  if (!path.startsWith("/")) {
+    throw new AthenaGatewayError({
+      code: "INVALID_URL",
+      message: `Athena gateway probe path must start with "/". Received ${JSON.stringify(path)}.`,
+      status: 0,
+      hint: 'Use a leading slash such as "/" or "/health".'
+    });
+  }
+  return path;
+}
+function mergeConnectionHeaders(baseHeaders, headers) {
+  const merged = {
+    ...baseHeaders,
+    ...headers ?? {}
+  };
+  if (!merged["X-Athena-Sdk"] && !merged["x-athena-sdk"]) {
+    merged["X-Athena-Sdk"] = SDK_HEADER_VALUE;
+  }
+  return merged;
+}
+async function performConnectionCheck(baseUrl, requestHeaders, options) {
+  const path = resolveProbePath(options?.path);
+  const url = buildAthenaGatewayUrl(baseUrl, path);
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: mergeConnectionHeaders(requestHeaders, options?.headers),
+      signal: options?.signal
+    });
+    const rawText = await response.text();
+    const requestId = resolveRequestId(response.headers);
+    const parsedBody = parseResponseBody(
+      rawText ?? "",
+      response.headers.get("content-type")
+    );
+    if (parsedBody.parseFailed) {
+      const invalidJsonError = new AthenaGatewayError({
+        code: "INVALID_JSON",
+        message: "Gateway probe returned malformed JSON",
+        status: response.status,
+        method: "GET",
+        requestId,
+        hint: "Verify the gateway response body is valid JSON.",
+        cause: rawText.slice(0, 300)
+      });
+      return {
+        ok: false,
+        reachable: true,
+        status: response.status,
+        statusText: resolveStatusText(response, parsedBody.parsed),
+        baseUrl,
+        url,
+        error: invalidJsonError.message,
+        errorDetails: detailsFromError(invalidJsonError),
+        raw: parsedBody.parsed
+      };
+    }
+    const parsed = parsedBody.parsed;
+    if (!response.ok) {
+      const httpError = new AthenaGatewayError({
+        code: "HTTP_ERROR",
+        message: resolveErrorMessage(
+          parsed,
+          `Athena gateway GET ${path} failed with status ${response.status}`
+        ),
+        status: response.status,
+        method: "GET",
+        requestId,
+        hint: resolveErrorHint(parsed)
+      });
+      return {
+        ok: false,
+        reachable: true,
+        status: response.status,
+        statusText: resolveStatusText(response, parsed),
+        baseUrl,
+        url,
+        error: httpError.message,
+        errorDetails: detailsFromError(httpError),
+        raw: parsed
+      };
+    }
+    return {
+      ok: true,
+      reachable: true,
+      status: response.status,
+      statusText: resolveStatusText(response, parsed),
+      baseUrl,
+      url,
+      error: void 0,
+      errorDetails: null,
+      raw: parsed
+    };
+  } catch (callError) {
+    const message = callError instanceof Error ? callError.message : String(callError);
+    const networkError = new AthenaGatewayError({
+      code: "NETWORK_ERROR",
+      message: `Network error while probing Athena gateway ${url}: ${message}`,
+      method: "GET",
+      cause: message,
+      hint: "Check gateway URL, DNS, and network reachability."
+    });
+    return {
+      ok: false,
+      reachable: false,
+      status: 0,
+      statusText: null,
+      baseUrl,
+      url,
+      error: networkError.message,
+      errorDetails: detailsFromError(networkError),
+      raw: null
+    };
+  }
+}
 async function callAthena(config, endpoint, method, payload, options) {
-  const baseUrl = (options?.baseUrl ?? config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
-  const url = `${baseUrl}${endpoint}`;
+  let baseUrl;
+  try {
+    baseUrl = resolveGatewayBaseUrl(options?.baseUrl ?? config.baseUrl);
+  } catch (error) {
+    return toInvalidUrlResponse(error, endpoint, method);
+  }
+  const url = buildAthenaGatewayUrl(baseUrl, endpoint);
   const headers = buildHeaders(config, options);
   try {
     const requestInit = {
@@ -1656,32 +1885,44 @@ async function callAthena(config, endpoint, method, payload, options) {
   }
 }
 function createAthenaGatewayClient(config = {}) {
+  const normalizedBaseUrl = resolveGatewayBaseUrl(config.baseUrl);
+  const normalizedConfig = {
+    ...config,
+    baseUrl: normalizedBaseUrl
+  };
   return {
-    baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, ""),
+    baseUrl: normalizedBaseUrl,
     buildHeaders(options) {
-      return buildHeaders(config, options);
+      return buildHeaders(normalizedConfig, options);
+    },
+    verifyConnection(options) {
+      return performConnectionCheck(
+        normalizedBaseUrl,
+        buildHeaders(normalizedConfig),
+        options
+      );
     },
     fetchGateway(payload, options) {
-      return callAthena(config, "/gateway/fetch", "POST", payload, options);
+      return callAthena(normalizedConfig, "/gateway/fetch", "POST", payload, options);
     },
     insertGateway(payload, options) {
-      return callAthena(config, "/gateway/insert", "PUT", payload, options);
+      return callAthena(normalizedConfig, "/gateway/insert", "PUT", payload, options);
     },
     updateGateway(payload, options) {
-      return callAthena(config, "/gateway/update", "POST", payload, options);
+      return callAthena(normalizedConfig, "/gateway/update", "POST", payload, options);
     },
     deleteGateway(payload, options) {
-      return callAthena(config, "/gateway/delete", "DELETE", payload, options);
+      return callAthena(normalizedConfig, "/gateway/delete", "DELETE", payload, options);
     },
     rpcGateway(payload, options) {
       if (options?.get) {
         const endpoint = buildRpcGetEndpoint(payload);
-        return callAthena(config, endpoint, "GET", null, options);
+        return callAthena(normalizedConfig, endpoint, "GET", null, options);
       }
-      return callAthena(config, "/gateway/rpc", "POST", payload, options);
+      return callAthena(normalizedConfig, "/gateway/rpc", "POST", payload, options);
     },
     queryGateway(payload, options) {
-      return callAthena(config, "/gateway/query", "POST", payload, options);
+      return callAthena(normalizedConfig, "/gateway/query", "POST", payload, options);
     }
   };
 }
@@ -3086,8 +3327,8 @@ function createAuthClient(config = {}) {
 // src/db/module.ts
 function createDbModule(input) {
   const db = {
-    from(table) {
-      return input.from(table);
+    from(table, options) {
+      return input.from(table, options);
     },
     select(table, columns, options) {
       return input.from(table).select(columns, options);
@@ -3192,7 +3433,19 @@ function buildGatewayCondition(operator, column, value) {
 function compileRelationToken(key, node) {
   const nested = compileSelectShape(node.select);
   const propertyKey = normalizeIdentifier(key, "select relation key");
-  const relationToken = normalizeIdentifier(node.via ?? propertyKey, "select relation token");
+  if (node.schema && node.via) {
+    throw new Error(
+      `findMany relation "${propertyKey}" cannot combine schema and via yet; use schema with the relation key, or use via without schema`
+    );
+  }
+  const relationTokenBase = normalizeIdentifier(node.via ?? propertyKey, "select relation token");
+  if (node.schema && relationTokenBase.includes(".")) {
+    throw new Error(
+      `findMany relation "${propertyKey}" already resolves to a qualified relation token; do not also set schema`
+    );
+  }
+  const relationSchema = node.schema?.trim();
+  const relationToken = relationSchema ? `${normalizeIdentifier(relationSchema, "select relation schema")}.${relationTokenBase}` : relationTokenBase;
   const alias = node.as?.trim() || (relationToken !== propertyKey ? propertyKey : "");
   const prefix = alias ? `${alias}:` : "";
   return `${prefix}${relationToken}(${nested})`;
@@ -3221,6 +3474,23 @@ function compileSelectShape(select) {
   }
   return tokens.join(",");
 }
+function selectShapeUsesRelationSchema(select) {
+  if (!isRecord5(select)) {
+    return false;
+  }
+  for (const rawValue of Object.values(select)) {
+    if (!isRelationSelectNode(rawValue)) {
+      continue;
+    }
+    if (typeof rawValue.schema === "string" && rawValue.schema.trim().length > 0) {
+      return true;
+    }
+    if (selectShapeUsesRelationSchema(rawValue.select)) {
+      return true;
+    }
+  }
+  return false;
+}
 function compileColumnWhere(column, input) {
   const normalizedColumn = normalizeIdentifier(column, "where column");
   if (!isRecord5(input)) {
@@ -3357,6 +3627,258 @@ function compileOrderBy(orderBy) {
   };
 }
 
+// src/gateway/structured-select.ts
+var IDENTIFIER_SEGMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isIdentifierPath(value) {
+  const segments = value.split(".").map((segment) => segment.trim());
+  return segments.length > 1 && segments.every((segment) => IDENTIFIER_SEGMENT_PATTERN.test(segment));
+}
+function extractRelationHead(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) return "";
+  const aliasIndex = trimmed.indexOf(":");
+  const withoutAlias = aliasIndex >= 0 ? trimmed.slice(aliasIndex + 1).trim() : trimmed;
+  const modifierIndex = withoutAlias.indexOf("!");
+  return (modifierIndex >= 0 ? withoutAlias.slice(0, modifierIndex) : withoutAlias).trim();
+}
+function hasSchemaQualifiedRelationToken(select) {
+  let singleQuoted = false;
+  let doubleQuoted = false;
+  let tokenStart = 0;
+  for (let index = 0; index < select.length; index += 1) {
+    const char = select[index];
+    const next = index + 1 < select.length ? select[index + 1] : "";
+    if (singleQuoted) {
+      if (char === "'" && next === "'") {
+        index += 1;
+        continue;
+      }
+      if (char === "'") {
+        singleQuoted = false;
+      }
+      continue;
+    }
+    if (doubleQuoted) {
+      if (char === '"' && next === '"') {
+        index += 1;
+        continue;
+      }
+      if (char === '"') {
+        doubleQuoted = false;
+      }
+      continue;
+    }
+    if (char === "'") {
+      singleQuoted = true;
+      continue;
+    }
+    if (char === '"') {
+      doubleQuoted = true;
+      continue;
+    }
+    if (char === "(") {
+      const relationHead = extractRelationHead(select.slice(tokenStart, index));
+      if (isIdentifierPath(relationHead)) {
+        return true;
+      }
+      tokenStart = index + 1;
+      continue;
+    }
+    if (char === "," || char === ")") {
+      tokenStart = index + 1;
+    }
+  }
+  return false;
+}
+function toStructuredSelectString(columns) {
+  return Array.isArray(columns) ? columns.join(",") : columns;
+}
+function buildStructuredWhere(conditions) {
+  if (!conditions?.length) return void 0;
+  const where = {};
+  for (const condition of conditions) {
+    if (!condition.column) {
+      return null;
+    }
+    if (condition.column_cast !== void 0 || condition.value_cast !== void 0) {
+      return null;
+    }
+    const operand = condition.value;
+    const operator = condition.operator;
+    if (operator === "eq") {
+      if (operand === void 0) return null;
+    } else if (operator === "neq" || operator === "gt" || operator === "lt") {
+      if (operand === void 0) return null;
+    } else if (operator === "in") {
+      if (!Array.isArray(operand)) return null;
+    } else {
+      return null;
+    }
+    const existing = where[condition.column];
+    if (existing !== void 0 && (typeof existing !== "object" || existing === null || Array.isArray(existing))) {
+      return null;
+    }
+    const next = existing ?? {};
+    if (Object.prototype.hasOwnProperty.call(next, operator)) {
+      return null;
+    }
+    next[operator] = operand;
+    where[condition.column] = next;
+  }
+  return where;
+}
+function buildStructuredOrderBy(order) {
+  if (!order?.field) return void 0;
+  return {
+    [order.field]: order.direction === "descending" ? "desc" : "asc"
+  };
+}
+function buildStructuredSelectTransport(input) {
+  const select = toStructuredSelectString(input.columns).trim();
+  if (!select || select === "*") {
+    return null;
+  }
+  if (!hasSchemaQualifiedRelationToken(select)) {
+    return null;
+  }
+  if (input.count !== void 0 || input.head !== void 0) {
+    return {
+      error: "Schema-qualified nested select strings require structured select transport, which does not support count/head options in athena-js yet."
+    };
+  }
+  const where = buildStructuredWhere(input.conditions);
+  if (where === null) {
+    return {
+      error: "Schema-qualified nested select strings only support eq, neq, gt, lt, and in filters in athena-js structured select transport."
+    };
+  }
+  return {
+    select,
+    payload: {
+      table_name: input.tableName,
+      select,
+      where,
+      orderBy: buildStructuredOrderBy(input.order),
+      limit: input.limit,
+      offset: input.offset,
+      strip_nulls: input.stripNulls
+    }
+  };
+}
+
+// src/query-transport.ts
+function canUseFindManyAstTransport(state) {
+  return state.conditions.length === 0 && state.offset === void 0 && state.currentPage === void 0 && state.pageSize === void 0 && state.totalPages === void 0;
+}
+function toFindManyAstOrder(order) {
+  if (!order) {
+    return void 0;
+  }
+  return {
+    column: order.field,
+    ascending: order.direction !== "descending"
+  };
+}
+function resolvePagination(input) {
+  let limit = input.limit;
+  let offset = input.offset;
+  if (limit === void 0 && input.pageSize !== void 0) {
+    limit = Math.max(0, Math.trunc(input.pageSize));
+  }
+  if (offset === void 0 && input.pageSize !== void 0 && input.currentPage !== void 0 && input.currentPage > 0) {
+    offset = (Math.trunc(input.currentPage) - 1) * Math.max(0, Math.trunc(input.pageSize));
+  }
+  return { limit, offset };
+}
+function hasTypedEqualityComparison(conditions) {
+  return conditions?.some(
+    (condition) => condition.operator === "eq" && (condition.value_cast !== void 0 || condition.column_cast !== void 0)
+  ) ?? false;
+}
+function createSelectTransportPlan(input) {
+  const conditions = input.state.conditions.length ? input.state.conditions.map((condition) => ({ ...condition })) : void 0;
+  if (hasTypedEqualityComparison(conditions) && !input.options?.head && !input.options?.count && conditions) {
+    const query = input.buildTypedSelectQuery({
+      tableName: input.tableName,
+      columns: input.columns,
+      conditions,
+      limit: input.state.limit,
+      offset: input.state.offset,
+      currentPage: input.state.currentPage,
+      pageSize: input.state.pageSize,
+      order: input.state.order
+    });
+    if (query) {
+      return {
+        kind: "query",
+        query,
+        payload: { query }
+      };
+    }
+  }
+  const pagination = resolvePagination({
+    limit: input.state.limit,
+    offset: input.state.offset,
+    currentPage: input.state.currentPage,
+    pageSize: input.state.pageSize
+  });
+  const stripNulls = input.options?.stripNulls ?? true;
+  const structuredSelectTransport = buildStructuredSelectTransport({
+    tableName: input.tableName,
+    columns: input.columns,
+    conditions,
+    limit: pagination.limit,
+    offset: pagination.offset,
+    order: input.state.order,
+    stripNulls,
+    count: input.options?.count,
+    head: input.options?.head
+  });
+  if (structuredSelectTransport && "error" in structuredSelectTransport) {
+    throw new Error(structuredSelectTransport.error);
+  }
+  if (structuredSelectTransport) {
+    const { payload, select } = structuredSelectTransport;
+    return {
+      kind: "fetch",
+      payload,
+      debug: {
+        columns: select,
+        conditions,
+        limit: pagination.limit,
+        offset: pagination.offset,
+        order: input.state.order
+      }
+    };
+  }
+  return {
+    kind: "fetch",
+    payload: {
+      table_name: input.tableName,
+      columns: input.columns,
+      conditions,
+      limit: input.state.limit,
+      offset: input.state.offset,
+      current_page: input.state.currentPage,
+      page_size: input.state.pageSize,
+      total_pages: input.state.totalPages,
+      sort_by: input.state.order,
+      strip_nulls: stripNulls,
+      count: input.options?.count,
+      head: input.options?.head
+    },
+    debug: {
+      columns: input.columns,
+      conditions,
+      limit: input.state.limit,
+      offset: input.state.offset,
+      currentPage: input.state.currentPage,
+      pageSize: input.state.pageSize,
+      order: input.state.order
+    }
+  };
+}
+
 // src/client.ts
 var DEFAULT_COLUMNS = "*";
 var SAFE_CAST_PATTERN = /^[a-z_][a-z0-9_]*(?:\[\])?$/i;
@@ -3371,18 +3893,6 @@ var QUERY_TRACE_STACK_SKIP_PATTERNS = [
   "node:internal",
   "internal/process"
 ];
-function canUseFindManyAstTransport(state) {
-  return state.conditions.length === 0 && state.offset === void 0 && state.currentPage === void 0 && state.pageSize === void 0 && state.totalPages === void 0;
-}
-function toFindManyAstOrder(order) {
-  if (!order) {
-    return void 0;
-  }
-  return {
-    column: order.field,
-    ascending: order.direction !== "descending"
-  };
-}
 function formatResult(response) {
   const result = {
     data: response.data ?? null,
@@ -3928,17 +4438,6 @@ function conditionToDebugSqlClause(condition) {
       return `TRUE /* unsupported condition: ${rawCondition} */`;
   }
 }
-function resolvePagination(input) {
-  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;
-  }
-  return { limit, offset };
-}
 function appendOrderLimitOffset(sqlParts, order, limit, offset) {
   if (order?.field) {
     const direction = order.direction === "descending" ? "DESC" : "ASC";
@@ -4442,64 +4941,34 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
   );
   const runSelect = async (columns = DEFAULT_COLUMNS, options, executionState = snapshotState(), callsite) => {
     const resolvedTableName = resolveTableNameForCall(tableName, options?.schema);
-    const conditions = executionState.conditions.length ? executionState.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: resolvedTableName,
-        columns,
-        conditions,
-        limit: executionState.limit,
-        offset: executionState.offset,
-        currentPage: executionState.currentPage,
-        pageSize: executionState.pageSize,
-        order: executionState.order
-      });
-      if (query) {
-        const payload2 = { query };
-        return executeWithQueryTrace(
-          tracer,
-          {
-            operation: "select",
-            endpoint: "/gateway/query",
-            table: resolvedTableName,
-            sql: query,
-            payload: payload2,
-            options
-          },
-          async () => {
-            const queryResponse = await client.queryGateway(payload2, options);
-            return formatGatewayResult(queryResponse, { table: resolvedTableName, operation: "select" });
-          },
-          callsite
-        );
-      }
-    }
-    const payload = {
-      table_name: resolvedTableName,
+    const plan = createSelectTransportPlan({
+      tableName: resolvedTableName,
       columns,
-      conditions,
-      limit: executionState.limit,
-      offset: executionState.offset,
-      current_page: executionState.currentPage,
-      page_size: executionState.pageSize,
-      total_pages: executionState.totalPages,
-      sort_by: executionState.order,
-      strip_nulls: options?.stripNulls ?? true,
-      count: options?.count,
-      head: options?.head
-    };
+      state: executionState,
+      options,
+      buildTypedSelectQuery
+    });
+    if (plan.kind === "query") {
+      return executeWithQueryTrace(
+        tracer,
+        {
+          operation: "select",
+          endpoint: "/gateway/query",
+          table: resolvedTableName,
+          sql: plan.query,
+          payload: plan.payload,
+          options
+        },
+        async () => {
+          const queryResponse = await client.queryGateway(plan.payload, options);
+          return formatGatewayResult(queryResponse, { table: resolvedTableName, operation: "select" });
+        },
+        callsite
+      );
+    }
     const sql = buildDebugSelectQuery({
       tableName: resolvedTableName,
-      columns,
-      conditions,
-      limit: executionState.limit,
-      offset: executionState.offset,
-      currentPage: executionState.currentPage,
-      pageSize: executionState.pageSize,
-      order: executionState.order
+      ...plan.debug
     });
     return executeWithQueryTrace(
       tracer,
@@ -4508,11 +4977,11 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
         endpoint: "/gateway/fetch",
         table: resolvedTableName,
         sql,
-        payload,
+        payload: plan.payload,
         options
       },
       async () => {
-        const response = await client.fetchGateway(payload, options);
+        const response = await client.fetchGateway(plan.payload, options);
         return formatGatewayResult(response, { table: resolvedTableName, operation: "select" });
       },
       callsite
@@ -4585,7 +5054,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
       if (options.limit !== void 0) {
         executionState.limit = options.limit;
       }
-      if (experimental?.findManyAst && canUseFindManyAstTransport(baseState)) {
+      if (experimental?.findManyAst && canUseFindManyAstTransport(baseState) && !selectShapeUsesRelationSchema(options.select)) {
         const resolvedTableName = resolveTableNameForCall(tableName, void 0);
         const payload = {
           table_name: resolvedTableName,
@@ -4907,7 +5376,13 @@ function createClientFromConfig(config) {
   const formatGatewayResult = createResultFormatter();
   const queryTracer = createQueryTracer(config.experimental);
   const auth = createAuthClient(config.auth);
-  const from = (table) => createTableBuilder(table, gateway, formatGatewayResult, queryTracer, config.experimental);
+  const from = (table, options) => createTableBuilder(
+    resolveTableNameForCall(table, options?.schema),
+    gateway,
+    formatGatewayResult,
+    queryTracer,
+    config.experimental
+  );
   const rpc = (fn, args, options) => {
     const normalizedFn = fn.trim();
     if (!normalizedFn) {
@@ -4930,6 +5405,7 @@ function createClientFromConfig(config) {
     db,
     rpc,
     query,
+    verifyConnection: gateway.verifyConnection,
     auth: auth.auth
   };
 }