@proofkit/fmodata 0.1.0-alpha.0 → 0.1.0-alpha.10

package/src/client/query-builder.ts

@@ -4,7 +4,6 @@ import type {
   ExecutionContext,
   ExecutableBuilder,
   WithSystemFields,
-  ODataRecordMetadata,
   Result,
   InferSchemaType,
   ExecuteOptions,
@@ -15,9 +14,24 @@ import type { Filter } from "../filter-types";
 import type { TableOccurrence } from "./table-occurrence";
 import type { BaseTable } from "./base-table";
 import { validateListResponse, validateSingleResponse } from "../validation";
+import { RecordCountMismatchError } from "../errors";
 import { type FFetchOptions } from "@fetchkit/ffetch";
-import { z } from "zod/v4";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import {
+  transformFieldNamesArray,
+  transformFieldName,
+  transformOrderByField,
+  transformResponseFields,
+  getTableIdentifiers,
+} from "../transform";
+
+
+/**
+ * Default maximum number of records to return in a list query.
+ * This prevents stack overflow issues with large datasets while still
+ * allowing substantial data retrieval. Users can override with .top().
+ */
+const DEFAULT_TOP = 1000;
 
 // Helper type to extract navigation relation names from an occurrence
 type ExtractNavigationNames<
@@ -42,19 +56,19 @@ type FindNavigationTarget<
       ? Name extends keyof Nav
         ? ResolveNavigationItem<Nav[Name]>
         : TableOccurrence<
-            BaseTable<Record<string, z.ZodTypeAny>, any>,
+            BaseTable<Record<string, StandardSchemaV1>, any, any, any>,
             any,
             any,
             any
           >
       : TableOccurrence<
-          BaseTable<Record<string, z.ZodTypeAny>, any>,
+          BaseTable<Record<string, StandardSchemaV1>, any, any, any>,
           any,
           any,
           any
         >
     : TableOccurrence<
-        BaseTable<Record<string, z.ZodTypeAny>, any>,
+        BaseTable<Record<string, StandardSchemaV1>, any, any, any>,
         any,
         any,
         any
@@ -67,7 +81,7 @@ type GetTargetSchemaType<
 > = [FindNavigationTarget<O, Rel>] extends [
   TableOccurrence<infer BT, any, any, any>,
 ]
-  ? [BT] extends [BaseTable<infer S, any>]
+  ? [BT] extends [BaseTable<infer S, any, any, any>]
     ? [S] extends [Record<string, StandardSchemaV1>]
       ? InferSchemaType<S>
       : Record<string, any>
@@ -81,7 +95,38 @@ type ExpandConfig = {
 };
 
 // Type to represent expanded relations
-type ExpandedRelations = Record<string, { schema: any; selected: any }>;
+export type ExpandedRelations = Record<string, { schema: any; selected: any }>;
+
+export type QueryReturnType<
+  T extends Record<string, any>,
+  Selected extends keyof T,
+  SingleMode extends "exact" | "maybe" | false,
+  IsCount extends boolean,
+  Expands extends ExpandedRelations,
+> = IsCount extends true
+  ? number
+  : SingleMode extends "exact"
+    ? Pick<T, Selected> & {
+        [K in keyof Expands]: Pick<
+          Expands[K]["schema"],
+          Expands[K]["selected"]
+        >[];
+      }
+    : SingleMode extends "maybe"
+      ?
+          | (Pick<T, Selected> & {
+              [K in keyof Expands]: Pick<
+                Expands[K]["schema"],
+                Expands[K]["selected"]
+              >[];
+            })
+          | null
+      : (Pick<T, Selected> & {
+          [K in keyof Expands]: Pick<
+            Expands[K]["schema"],
+            Expands[K]["selected"]
+          >[];
+        })[];
 
 export class QueryBuilder<
   T extends Record<string, any>,
@@ -90,7 +135,11 @@ export class QueryBuilder<
   IsCount extends boolean = false,
   Occ extends TableOccurrence<any, any, any, any> | undefined = undefined,
   Expands extends ExpandedRelations = {},
-> {
+> implements
+    ExecutableBuilder<
+      QueryReturnType<T, Selected, SingleMode, IsCount, Expands>
+    >
+{
   private queryOptions: Partial<QueryOptions<T>> = {};
   private expandConfigs: ExpandConfig[] = [];
   private singleMode: SingleMode = false as SingleMode;
@@ -104,16 +153,36 @@ export class QueryBuilder<
   private navigateRelation?: string;
   private navigateSourceTableName?: string;
   private navigateBaseRelation?: string;
+  private databaseUseEntityIds: boolean;
+
   constructor(config: {
     occurrence?: Occ;
     tableName: string;
     databaseName: string;
     context: ExecutionContext;
+    databaseUseEntityIds?: boolean;
   }) {
     this.occurrence = config.occurrence;
     this.tableName = config.tableName;
     this.databaseName = config.databaseName;
     this.context = config.context;
+    this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;
+  }
+
+  /**
+   * Helper to merge database-level useEntityIds with per-request options
+   */
+  private mergeExecuteOptions(
+    options?: RequestInit & FFetchOptions & ExecuteOptions,
+  ): RequestInit & FFetchOptions & { useEntityIds?: boolean } {
+    // If useEntityIds is not set in options, use the database-level setting
+    return {
+      ...options,
+      useEntityIds:
+        options?.useEntityIds === undefined
+          ? this.databaseUseEntityIds
+          : options.useEntityIds,
+    };
   }
 
   /**
@@ -133,6 +202,31 @@ export class QueryBuilder<
     return rest as T;
   }
 
+  /**
+   * Gets the table ID (FMTID) if using entity IDs, otherwise returns the table name
+   * @param useEntityIds - Optional override for entity ID usage
+   */
+  private getTableId(useEntityIds?: boolean): string {
+    if (!this.occurrence) {
+      return this.tableName;
+    }
+
+    const contextDefault = this.context._getUseEntityIds?.() ?? false;
+    const shouldUseIds = useEntityIds ?? contextDefault;
+
+    if (shouldUseIds) {
+      const identifiers = getTableIdentifiers(this.occurrence);
+      if (!identifiers.id) {
+        throw new Error(
+          `useEntityIds is true but TableOccurrence "${identifiers.name}" does not have an fmtId defined`,
+        );
+      }
+      return identifiers.id;
+    }
+
+    return this.occurrence.getTableName();
+  }
+
   select<K extends keyof T>(
     ...fields: K[]
   ): QueryBuilder<T, K, SingleMode, IsCount, Occ, Expands> {
@@ -149,6 +243,7 @@ export class QueryBuilder<
       tableName: this.tableName,
       databaseName: this.databaseName,
       context: this.context,
+      databaseUseEntityIds: this.databaseUseEntityIds,
     });
     newBuilder.queryOptions = {
       ...this.queryOptions,
@@ -205,16 +300,21 @@ export class QueryBuilder<
     const andConditions: any[] = [];
 
     for (const [field, value] of Object.entries(filter)) {
+      // Transform field name to FMFID if using entity IDs
+      const fieldId = this.occurrence?.baseTable
+        ? transformFieldName(field, this.occurrence.baseTable)
+        : field;
+
       if (Array.isArray(value)) {
         // Array of operators - convert to AND conditions
         if (value.length === 1) {
           // Single operator in array - unwrap it
-          result[field] = value[0];
+          result[fieldId] = value[0];
         } else {
           // Multiple operators - combine with AND
           // Create separate conditions for each operator
           for (const op of value) {
-            andConditions.push({ [field]: op });
+            andConditions.push({ [fieldId]: op });
           }
         }
       } else if (
@@ -240,14 +340,14 @@ export class QueryBuilder<
 
         if (isOperatorObject) {
           // Single operator object - pass through
-          result[field] = value;
+          result[fieldId] = value;
         } else {
           // Regular object - might be nested filter, pass through
-          result[field] = value;
+          result[fieldId] = value;
         }
       } else {
         // Primitive value (shorthand) - pass through
-        result[field] = value;
+        result[fieldId] = value;
       }
     }
 
@@ -277,7 +377,21 @@ export class QueryBuilder<
   orderBy(
     orderBy: QueryOptions<T>["orderBy"],
   ): QueryBuilder<T, Selected, SingleMode, IsCount, Occ, Expands> {
-    this.queryOptions.orderBy = orderBy;
+    // Transform field names to FMFIDs if using entity IDs
+    if (this.occurrence?.baseTable && orderBy) {
+      if (Array.isArray(orderBy)) {
+        this.queryOptions.orderBy = orderBy.map((field) =>
+          transformOrderByField(String(field), this.occurrence!.baseTable),
+        );
+      } else {
+        this.queryOptions.orderBy = transformOrderByField(
+          String(orderBy),
+          this.occurrence.baseTable,
+        );
+      }
+    } else {
+      this.queryOptions.orderBy = orderBy;
+    }
     return this;
   }
 
@@ -297,13 +411,26 @@ export class QueryBuilder<
 
   /**
    * Formats select fields for use in query strings.
+   * - Transforms field names to FMFIDs if using entity IDs
    * - Wraps "id" fields in double quotes
    * - URL-encodes special characters but preserves spaces
    */
-  private formatSelectFields(select: QueryOptions<any>["select"]): string {
+  private formatSelectFields(
+    select: QueryOptions<any>["select"],
+    baseTable?: BaseTable<any, any, any, any>,
+  ): string {
     if (!select) return "";
     const selectFieldsArray = Array.isArray(select) ? select : [select];
-    return selectFieldsArray
+
+    // Transform to field IDs if using entity IDs
+    const transformedFields = baseTable
+      ? transformFieldNamesArray(
+          selectFieldsArray.map((f) => String(f)),
+          baseTable,
+        )
+      : selectFieldsArray.map((f) => String(f));
+
+    return transformedFields
       .map((field) => {
         if (field === "id") return `"id"`;
         const encodedField = encodeURIComponent(String(field));
@@ -335,6 +462,8 @@ export class QueryBuilder<
         relation: config.relation,
         targetSchema: targetSchema,
         targetOccurrence: targetOccurrence,
+        targetBaseTable: targetOccurrence?.baseTable,
+        occurrence: targetOccurrence, // Add occurrence for transformation
         selectedFields: selectedFields,
         nestedExpands: undefined, // TODO: Handle nested expands if needed
       };
@@ -344,6 +473,7 @@ export class QueryBuilder<
   /**
    * Builds OData expand query string from expand configurations.
    * Handles nested expands recursively.
+   * Transforms relation names to FMTIDs if using entity IDs.
    */
   private buildExpandString(configs: ExpandConfig[]): string {
     if (configs.length === 0) {
@@ -352,20 +482,35 @@ export class QueryBuilder<
 
     return configs
       .map((config) => {
+        // Get target occurrence for this relation
+        const targetOccurrence = this.occurrence?.navigation[config.relation];
+
+        // When using entity IDs, use the target table's FMTID in the expand parameter
+        // FileMaker expects FMTID in $expand when Prefer header is set
+        const relationName =
+          targetOccurrence && targetOccurrence.isUsingTableId()
+            ? targetOccurrence.getTableId()
+            : config.relation;
+
         if (!config.options || Object.keys(config.options).length === 0) {
           // Simple expand without options
-          return config.relation;
+          return relationName;
         }
 
         // Build query options for this expand
         const parts: string[] = [];
 
         if (config.options.select) {
-          const selectFields = this.formatSelectFields(config.options.select);
+          // Pass target base table for field transformation
+          const selectFields = this.formatSelectFields(
+            config.options.select,
+            targetOccurrence?.baseTable,
+          );
           parts.push(`$select=${selectFields}`);
         }
 
         if (config.options.filter) {
+          // Filter should already be transformed by the nested builder
           // Use odata-query to build filter string
           const filterQuery = buildQuery({ filter: config.options.filter });
           const filterMatch = filterQuery.match(/\$filter=([^&]+)/);
@@ -375,6 +520,7 @@ export class QueryBuilder<
         }
 
         if (config.options.orderBy) {
+          // OrderBy should already be transformed by the nested builder
           const orderByValue = Array.isArray(config.options.orderBy)
             ? config.options.orderBy.join(",")
             : config.options.orderBy;
@@ -398,10 +544,10 @@ export class QueryBuilder<
         }
 
         if (parts.length === 0) {
-          return config.relation;
+          return relationName;
         }
 
-        return `${config.relation}(${parts.join(";")})`;
+        return `${relationName}(${parts.join(";")})`;
       })
       .join(",");
   }
@@ -456,6 +602,7 @@ export class QueryBuilder<
         tableName: targetOccurrence?.name ?? (relation as string),
         databaseName: this.databaseName,
         context: this.context,
+        databaseUseEntityIds: this.databaseUseEntityIds,
       });
 
       // Cast to the expected type for the callback
@@ -517,6 +664,7 @@ export class QueryBuilder<
       tableName: this.tableName,
       databaseName: this.databaseName,
       context: this.context,
+      databaseUseEntityIds: this.databaseUseEntityIds,
     });
     newBuilder.queryOptions = { ...this.queryOptions };
     newBuilder.expandConfigs = [...this.expandConfigs];
@@ -544,6 +692,7 @@ export class QueryBuilder<
       tableName: this.tableName,
       databaseName: this.databaseName,
       context: this.context,
+      databaseUseEntityIds: this.databaseUseEntityIds,
     });
     newBuilder.queryOptions = { ...this.queryOptions };
     newBuilder.expandConfigs = [...this.expandConfigs];
@@ -571,6 +720,7 @@ export class QueryBuilder<
       tableName: this.tableName,
       databaseName: this.databaseName,
       context: this.context,
+      databaseUseEntityIds: this.databaseUseEntityIds,
     });
     newBuilder.queryOptions = { ...this.queryOptions, count: true };
     newBuilder.expandConfigs = [...this.expandConfigs];
@@ -622,240 +772,180 @@ export class QueryBuilder<
               >[]
     >
   > {
-    try {
-      // Build query without expand (we'll add it manually)
-      const queryOptionsWithoutExpand = { ...this.queryOptions };
-      delete queryOptionsWithoutExpand.expand;
-
-      // Format select fields before building query
-      if (queryOptionsWithoutExpand.select) {
-        queryOptionsWithoutExpand.select = this.formatSelectFields(
-          queryOptionsWithoutExpand.select,
-        ) as any;
-      }
+    // Build query without expand (we'll add it manually)
+    const queryOptionsWithoutExpand = { ...this.queryOptions };
+    delete queryOptionsWithoutExpand.expand;
 
-      let queryString = buildQuery(queryOptionsWithoutExpand);
+    const mergedOptions = this.mergeExecuteOptions(options);
 
-      // Build custom expand string
-      const expandString = this.buildExpandString(this.expandConfigs);
-      if (expandString) {
-        const separator = queryString.includes("?") ? "&" : "?";
-        queryString = `${queryString}${separator}$expand=${expandString}`;
-      }
+    // Format select fields before building query
+    if (queryOptionsWithoutExpand.select) {
+      queryOptionsWithoutExpand.select = this.formatSelectFields(
+        queryOptionsWithoutExpand.select,
+        this.occurrence?.baseTable,
+      ) as any;
+    }
 
-      // Handle navigation from RecordBuilder
-      if (
-        this.isNavigate &&
-        this.navigateRecordId &&
-        this.navigateRelation &&
-        this.navigateSourceTableName
-      ) {
-        let url: string;
-        if (this.navigateBaseRelation) {
-          // Navigation from a navigated EntitySet: /sourceTable/baseRelation('recordId')/relation
-          url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateBaseRelation}('${this.navigateRecordId}')/${this.navigateRelation}${queryString}`;
-        } else {
-          // Normal navigation: /sourceTable('recordId')/relation
-          url = `/${this.databaseName}/${this.navigateSourceTableName}('${this.navigateRecordId}')/${this.navigateRelation}${queryString}`;
-        }
-        const response = await this.context._makeRequest(url, options);
+    let queryString = buildQuery(queryOptionsWithoutExpand);
 
-        // Skip validation if requested
-        if (options?.skipValidation === true) {
-          const resp = response as any;
-          if (this.singleMode !== false) {
-            const records = resp.value ?? [resp];
-            const count = Array.isArray(records) ? records.length : 1;
+    // Build custom expand string
+    const expandString = this.buildExpandString(this.expandConfigs);
+    if (expandString) {
+      const separator = queryString.includes("?") ? "&" : "?";
+      queryString = `${queryString}${separator}$expand=${expandString}`;
+    }
 
-            if (count > 1) {
-              return {
-                data: undefined,
-                error: new Error(
-                  `Expected ${this.singleMode === "exact" ? "exactly one" : "at most one"} record, but received ${count}`,
-                ),
-              };
-            }
+    // Handle navigation from RecordBuilder
+    if (
+      this.isNavigate &&
+      this.navigateRecordId &&
+      this.navigateRelation &&
+      this.navigateSourceTableName
+    ) {
+      let url: string;
+      if (this.navigateBaseRelation) {
+        // Navigation from a navigated EntitySet: /sourceTable/baseRelation('recordId')/relation
+        url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateBaseRelation}('${this.navigateRecordId}')/${this.navigateRelation}${queryString}`;
+      } else {
+        // Normal navigation: /sourceTable('recordId')/relation
+        url = `/${this.databaseName}/${this.navigateSourceTableName}('${this.navigateRecordId}')/${this.navigateRelation}${queryString}`;
+      }
+      const result = await this.context._makeRequest(url, mergedOptions);
 
-            if (count === 0) {
-              if (this.singleMode === "exact") {
-                return {
-                  data: undefined,
-                  error: new Error(
-                    "Expected exactly one record, but received none",
-                  ),
-                };
-              }
-              return { data: null as any, error: undefined };
-            }
+      if (result.error) {
+        return { data: undefined, error: result.error };
+      }
 
-            const record = Array.isArray(records) ? records[0] : records;
-            const stripped = this.stripODataAnnotationsIfNeeded(
-              record,
-              options,
-            );
-            return { data: stripped as any, error: undefined };
-          } else {
-            const records = resp.value ?? [];
-            const stripped = records.map((record: any) =>
-              this.stripODataAnnotationsIfNeeded(record, options),
-            );
-            return { data: stripped as any, error: undefined };
-          }
-        }
+      let response = result.data;
 
-        // Get schema from occurrence if available
-        const schema = this.occurrence?.baseTable?.schema;
-        const selectedFields = this.queryOptions.select as
-          | (keyof T)[]
-          | undefined;
+      // Transform response field IDs back to names if using entity IDs
+      // Only transform if useEntityIds resolves to true (respects per-request override)
+      const shouldUseIds = mergedOptions.useEntityIds ?? false;
+
+      if (this.occurrence?.baseTable && shouldUseIds) {
         const expandValidationConfigs = this.buildExpandValidationConfigs(
           this.expandConfigs,
         );
-
-        if (this.singleMode !== false) {
-          const validation = await validateSingleResponse<T>(
-            response,
-            schema,
-            selectedFields,
-            expandValidationConfigs,
-            this.singleMode,
-          );
-          if (!validation.valid) {
-            return { data: undefined, error: validation.error };
-          }
-          const stripped = validation.data
-            ? this.stripODataAnnotationsIfNeeded(validation.data, options)
-            : null;
-          return { data: stripped as any, error: undefined };
-        } else {
-          const validation = await validateListResponse<T>(
-            response,
-            schema,
-            selectedFields,
-            expandValidationConfigs,
-          );
-          if (!validation.valid) {
-            return { data: undefined, error: validation.error };
-          }
-          const stripped = validation.data.map((record) =>
-            this.stripODataAnnotationsIfNeeded(record, options),
-          );
-          return { data: stripped as any, error: undefined };
-        }
+        response = transformResponseFields(
+          response,
+          this.occurrence.baseTable,
+          expandValidationConfigs,
+        );
       }
 
-      // Handle navigation from EntitySet (without record ID)
-      if (
-        this.isNavigate &&
-        !this.navigateRecordId &&
-        this.navigateRelation &&
-        this.navigateSourceTableName
-      ) {
-        const response = await this.context._makeRequest(
-          `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}${queryString}`,
-          options,
-        );
+      // Skip validation if requested
+      if (options?.skipValidation === true) {
+        const resp = response as any;
+        if (this.singleMode !== false) {
+          const records = resp.value ?? [resp];
+          const count = Array.isArray(records) ? records.length : 1;
 
-        // Skip validation if requested
-        if (options?.skipValidation === true) {
-          const resp = response as any;
-          if (this.singleMode !== false) {
-            const records = resp.value ?? [resp];
-            const count = Array.isArray(records) ? records.length : 1;
+          if (count > 1) {
+            return {
+              data: undefined,
+              error: new RecordCountMismatchError(
+                this.singleMode === "exact" ? "one" : "at-most-one",
+                count,
+              ),
+            };
+          }
 
-            if (count > 1) {
+          if (count === 0) {
+            if (this.singleMode === "exact") {
               return {
                 data: undefined,
-                error: new Error(
-                  `Expected ${this.singleMode === "exact" ? "exactly one" : "at most one"} record, but received ${count}`,
-                ),
+                error: new RecordCountMismatchError("one", 0),
               };
             }
-
-            if (count === 0) {
-              if (this.singleMode === "exact") {
-                return {
-                  data: undefined,
-                  error: new Error(
-                    "Expected exactly one record, but received none",
-                  ),
-                };
-              }
-              return { data: null as any, error: undefined };
-            }
-
-            const record = Array.isArray(records) ? records[0] : records;
-            const stripped = this.stripODataAnnotationsIfNeeded(
-              record,
-              options,
-            );
-            return { data: stripped as any, error: undefined };
-          } else {
-            const records = resp.value ?? [];
-            const stripped = records.map((record: any) =>
-              this.stripODataAnnotationsIfNeeded(record, options),
-            );
-            return { data: stripped as any, error: undefined };
+            return { data: null as any, error: undefined };
           }
-        }
 
-        // Get schema from occurrence if available
-        const schema = this.occurrence?.baseTable?.schema;
-        const selectedFields = this.queryOptions.select as
-          | (keyof T)[]
-          | undefined;
-        const expandValidationConfigs = this.buildExpandValidationConfigs(
-          this.expandConfigs,
-        );
-
-        if (this.singleMode !== false) {
-          const validation = await validateSingleResponse<T>(
-            response,
-            schema,
-            selectedFields,
-            expandValidationConfigs,
-            this.singleMode,
-          );
-          if (!validation.valid) {
-            return { data: undefined, error: validation.error };
-          }
-          const stripped = validation.data
-            ? this.stripODataAnnotationsIfNeeded(validation.data, options)
-            : null;
+          const record = Array.isArray(records) ? records[0] : records;
+          const stripped = this.stripODataAnnotationsIfNeeded(record, options);
           return { data: stripped as any, error: undefined };
         } else {
-          const validation = await validateListResponse<T>(
-            response,
-            schema,
-            selectedFields,
-            expandValidationConfigs,
-          );
-          if (!validation.valid) {
-            return { data: undefined, error: validation.error };
-          }
-          const stripped = validation.data.map((record) =>
+          const records = resp.value ?? [];
+          const stripped = records.map((record: any) =>
             this.stripODataAnnotationsIfNeeded(record, options),
           );
           return { data: stripped as any, error: undefined };
         }
       }
 
-      // Handle $count endpoint
-      if (this.isCountMode) {
-        const result = await this.context._makeRequest(
-          `/${this.databaseName}/${this.tableName}/$count${queryString}`,
-          options,
+      // Get schema from occurrence if available
+      const schema = this.occurrence?.baseTable?.schema;
+      const selectedFields = this.queryOptions.select as
+        | (keyof T)[]
+        | undefined;
+      const expandValidationConfigs = this.buildExpandValidationConfigs(
+        this.expandConfigs,
+      );
+
+      if (this.singleMode !== false) {
+        const validation = await validateSingleResponse<T>(
+          response,
+          schema,
+          selectedFields,
+          expandValidationConfigs,
+          this.singleMode,
+        );
+        if (!validation.valid) {
+          return { data: undefined, error: validation.error };
+        }
+        const stripped = validation.data
+          ? this.stripODataAnnotationsIfNeeded(validation.data, options)
+          : null;
+        return { data: stripped as any, error: undefined };
+      } else {
+        const validation = await validateListResponse<T>(
+          response,
+          schema,
+          selectedFields,
+          expandValidationConfigs,
         );
-        // OData returns count as a string, convert to number
-        const count = typeof result === "string" ? Number(result) : result;
-        return { data: count as number, error: undefined } as any;
+        if (!validation.valid) {
+          return { data: undefined, error: validation.error };
+        }
+        const stripped = validation.data.map((record) =>
+          this.stripODataAnnotationsIfNeeded(record, options),
+        );
+        return { data: stripped as any, error: undefined };
       }
+    }
 
-      const response = await this.context._makeRequest(
-        `/${this.databaseName}/${this.tableName}${queryString}`,
-        options,
+    // Handle navigation from EntitySet (without record ID)
+    if (
+      this.isNavigate &&
+      !this.navigateRecordId &&
+      this.navigateRelation &&
+      this.navigateSourceTableName
+    ) {
+      const result = await this.context._makeRequest(
+        `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}${queryString}`,
+        mergedOptions,
       );
 
+      if (result.error) {
+        return { data: undefined, error: result.error };
+      }
+
+      let response = result.data;
+
+      // Transform response field IDs back to names if using entity IDs
+      // Only transform if useEntityIds resolves to true (respects per-request override)
+      const shouldUseIds = mergedOptions.useEntityIds ?? false;
+
+      if (this.occurrence?.baseTable && shouldUseIds) {
+        const expandValidationConfigs = this.buildExpandValidationConfigs(
+          this.expandConfigs,
+        );
+        response = transformResponseFields(
+          response,
+          this.occurrence.baseTable,
+          expandValidationConfigs,
+        );
+      }
+
       // Skip validation if requested
       if (options?.skipValidation === true) {
         const resp = response as any;
@@ -866,8 +956,9 @@ export class QueryBuilder<
           if (count > 1) {
             return {
               data: undefined,
-              error: new Error(
-                `Expected ${this.singleMode === "exact" ? "exactly one" : "at most one"} record, but received ${count}`,
+              error: new RecordCountMismatchError(
+                this.singleMode === "exact" ? "one" : "at-most-one",
+                count,
               ),
             };
           }
@@ -876,9 +967,7 @@ export class QueryBuilder<
             if (this.singleMode === "exact") {
               return {
                 data: undefined,
-                error: new Error(
-                  "Expected exactly one record, but received none",
-                ),
+                error: new RecordCountMismatchError("one", 0),
               };
             }
             return { data: null as any, error: undefined };
@@ -888,7 +977,6 @@ export class QueryBuilder<
           const stripped = this.stripODataAnnotationsIfNeeded(record, options);
           return { data: stripped as any, error: undefined };
         } else {
-          // Handle list response structure
           const records = resp.value ?? [];
           const stripped = records.map((record: any) =>
             this.stripODataAnnotationsIfNeeded(record, options),
@@ -920,10 +1008,7 @@ export class QueryBuilder<
         const stripped = validation.data
           ? this.stripODataAnnotationsIfNeeded(validation.data, options)
           : null;
-        return {
-          data: stripped as any,
-          error: undefined,
-        };
+        return { data: stripped as any, error: undefined };
       } else {
         const validation = await validateListResponse<T>(
           response,
@@ -937,15 +1022,136 @@ export class QueryBuilder<
         const stripped = validation.data.map((record) =>
           this.stripODataAnnotationsIfNeeded(record, options),
         );
-        return {
-          data: stripped as any,
-          error: undefined,
-        };
+        return { data: stripped as any, error: undefined };
+      }
+    }
+
+    // Handle $count endpoint
+    if (this.isCountMode) {
+      const tableId = this.getTableId(mergedOptions.useEntityIds);
+      const result = await this.context._makeRequest(
+        `/${this.databaseName}/${tableId}/$count${queryString}`,
+        mergedOptions,
+      );
+
+      if (result.error) {
+        return { data: undefined, error: result.error };
       }
-    } catch (error) {
+
+      // OData returns count as a string, convert to number
+      const count =
+        typeof result.data === "string" ? Number(result.data) : result.data;
+      return { data: count as number, error: undefined } as any;
+    }
+
+    const tableId = this.getTableId(mergedOptions.useEntityIds);
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/${tableId}${queryString}`,
+      mergedOptions,
+    );
+
+    if (result.error) {
+      return { data: undefined, error: result.error };
+    }
+
+    let response = result.data;
+
+    // Transform response field IDs back to names if using entity IDs
+    // Only transform if useEntityIds resolves to true (respects per-request override)
+    const shouldUseIds = mergedOptions.useEntityIds ?? false;
+
+    if (this.occurrence?.baseTable && shouldUseIds) {
+      const expandValidationConfigs = this.buildExpandValidationConfigs(
+        this.expandConfigs,
+      );
+      response = transformResponseFields(
+        response,
+        this.occurrence.baseTable,
+        expandValidationConfigs,
+      );
+    }
+
+    // Skip validation if requested
+    if (options?.skipValidation === true) {
+      const resp = response as any;
+      if (this.singleMode !== false) {
+        const records = resp.value ?? [resp];
+        const count = Array.isArray(records) ? records.length : 1;
+
+        if (count > 1) {
+          return {
+            data: undefined,
+            error: new RecordCountMismatchError(
+              this.singleMode === "exact" ? "one" : "at-most-one",
+              count,
+            ),
+          };
+        }
+
+        if (count === 0) {
+          if (this.singleMode === "exact") {
+            return {
+              data: undefined,
+              error: new RecordCountMismatchError("one", 0),
+            };
+          }
+          return { data: null as any, error: undefined };
+        }
+
+        const record = Array.isArray(records) ? records[0] : records;
+        const stripped = this.stripODataAnnotationsIfNeeded(record, options);
+        return { data: stripped as any, error: undefined };
+      } else {
+        // Handle list response structure
+        const records = resp.value ?? [];
+        const stripped = records.map((record: any) =>
+          this.stripODataAnnotationsIfNeeded(record, options),
+        );
+        return { data: stripped as any, error: undefined };
+      }
+    }
+
+    // Get schema from occurrence if available
+    const schema = this.occurrence?.baseTable?.schema;
+    const selectedFields = this.queryOptions.select as (keyof T)[] | undefined;
+    const expandValidationConfigs = this.buildExpandValidationConfigs(
+      this.expandConfigs,
+    );
+
+    if (this.singleMode !== false) {
+      const validation = await validateSingleResponse<T>(
+        response,
+        schema,
+        selectedFields,
+        expandValidationConfigs,
+        this.singleMode,
+      );
+      if (!validation.valid) {
+        return { data: undefined, error: validation.error };
+      }
+      const stripped = validation.data
+        ? this.stripODataAnnotationsIfNeeded(validation.data, options)
+        : null;
       return {
-        data: undefined,
-        error: error instanceof Error ? error : new Error(String(error)),
+        data: stripped as any,
+        error: undefined,
+      };
+    } else {
+      const validation = await validateListResponse<T>(
+        response,
+        schema,
+        selectedFields,
+        expandValidationConfigs,
+      );
+      if (!validation.valid) {
+        return { data: undefined, error: validation.error };
+      }
+      const stripped = validation.data.map((record) =>
+        this.stripODataAnnotationsIfNeeded(record, options),
+      );
+      return {
+        data: stripped as any,
+        error: undefined,
       };
     }
   }
@@ -960,6 +1166,7 @@ export class QueryBuilder<
     if (queryOptionsWithoutExpand.select) {
       queryOptionsWithoutExpand.select = this.formatSelectFields(
         queryOptionsWithoutExpand.select,
+        this.occurrence?.baseTable,
       ) as any;
     }
 
@@ -1026,6 +1233,7 @@ export class QueryBuilder<
     if (queryOptionsWithoutExpand.select) {
       queryOptionsWithoutExpand.select = this.formatSelectFields(
         queryOptionsWithoutExpand.select,
+        this.occurrence?.baseTable,
       ) as any;
     }
 
@@ -1073,4 +1281,175 @@ export class QueryBuilder<
       url,
     };
   }
+
+  toRequest(baseUrl: string): Request {
+    const config = this.getRequestConfig();
+    const fullUrl = `${baseUrl}${config.url}`;
+
+    return new Request(fullUrl, {
+      method: config.method,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+    });
+  }
+
+  async processResponse(
+    response: Response,
+    options?: ExecuteOptions,
+  ): Promise<
+    Result<QueryReturnType<T, Selected, SingleMode, IsCount, Expands>>
+  > {
+    // Handle 204 No Content (shouldn't happen for queries, but handle it gracefully)
+    if (response.status === 204) {
+      // Return empty list for list queries, null for single queries
+      if (this.singleMode !== false) {
+        if (this.singleMode === "maybe") {
+          return { data: null as any, error: undefined };
+        }
+        return {
+          data: undefined,
+          error: new RecordCountMismatchError("one", 0),
+        };
+      }
+      return { data: [] as any, error: undefined };
+    }
+
+    // Parse the response body
+    let rawData;
+    try {
+      rawData = await response.json();
+    } catch (err) {
+      // Check if it's an empty body error (common with 204 responses)
+      if (err instanceof SyntaxError && response.status === 204) {
+        // Handled above, but just in case
+        return { data: [] as any, error: undefined };
+      }
+      return {
+        data: undefined,
+        error: {
+          name: "ResponseParseError",
+          message: `Failed to parse response JSON: ${err instanceof Error ? err.message : "Unknown error"}`,
+          timestamp: new Date(),
+        } as any,
+      };
+    }
+
+    if (!rawData) {
+      return {
+        data: undefined,
+        error: {
+          name: "ResponseError",
+          message: "Response body was empty or null",
+          timestamp: new Date(),
+        } as any,
+      };
+    }
+
+    // Transform response field IDs back to names if using entity IDs
+    // Only transform if useEntityIds resolves to true (respects per-request override)
+    const shouldUseIds = options?.useEntityIds ?? this.databaseUseEntityIds;
+
+    let transformedData = rawData;
+    if (this.occurrence?.baseTable && shouldUseIds) {
+      const expandValidationConfigs = this.buildExpandValidationConfigs(
+        this.expandConfigs,
+      );
+      transformedData = transformResponseFields(
+        rawData,
+        this.occurrence.baseTable,
+        expandValidationConfigs,
+      );
+    }
+
+    // Skip validation if requested
+    if (options?.skipValidation === true) {
+      const resp = transformedData as any;
+      if (this.singleMode !== false) {
+        const records = resp.value ?? [resp];
+        const count = Array.isArray(records) ? records.length : 1;
+
+        if (count > 1) {
+          return {
+            data: undefined,
+            error: new RecordCountMismatchError(
+              this.singleMode === "exact" ? "one" : "at-most-one",
+              count,
+            ),
+          };
+        }
+
+        if (count === 0) {
+          if (this.singleMode === "exact") {
+            return {
+              data: undefined,
+              error: new RecordCountMismatchError("one", 0),
+            };
+          }
+          return { data: null as any, error: undefined };
+        }
+
+        const record = Array.isArray(records) ? records[0] : records;
+        const stripped = this.stripODataAnnotationsIfNeeded(record, options);
+        return { data: stripped as any, error: undefined };
+      } else {
+        // Handle list response structure
+        const records = resp.value ?? [];
+        const stripped = records.map((record: any) =>
+          this.stripODataAnnotationsIfNeeded(record, options),
+        );
+        return { data: stripped as any, error: undefined };
+      }
+    }
+
+    // Get schema from occurrence if available
+    const schema = this.occurrence?.baseTable?.schema;
+    const selectedFields = this.queryOptions.select as (keyof T)[] | undefined;
+    const expandValidationConfigs = this.buildExpandValidationConfigs(
+      this.expandConfigs,
+    );
+
+    if (this.singleMode !== false) {
+      // Single mode (one() or oneOrNull())
+      const validation = await validateSingleResponse<T>(
+        transformedData,
+        schema,
+        selectedFields,
+        expandValidationConfigs,
+        this.singleMode,
+      );
+
+      if (!validation.valid) {
+        return { data: undefined, error: validation.error };
+      }
+
+      if (validation.data === null) {
+        return { data: null as any, error: undefined };
+      }
+
+      const stripped = this.stripODataAnnotationsIfNeeded(
+        validation.data,
+        options,
+      );
+      return { data: stripped as any, error: undefined };
+    }
+
+    // List mode
+    const validation = await validateListResponse<T>(
+      transformedData,
+      schema,
+      selectedFields,
+      expandValidationConfigs,
+    );
+
+    if (!validation.valid) {
+      return { data: undefined, error: validation.error };
+    }
+
+    const stripped = validation.data.map((record) =>
+      this.stripODataAnnotationsIfNeeded(record, options),
+    );
+    return { data: stripped as any, error: undefined };
+  }
 }