@proofkit/fmodata 0.1.0-alpha.8 → 0.1.0-beta.23

package/src/client/record-builder.ts

@@ -1,104 +1,163 @@
+/** biome-ignore-all lint/complexity/noBannedTypes: Empty object type represents no expands by default */
+import type { FFetchOptions } from "@fetchkit/ffetch";
+import { createLogger, type InternalLogger } from "../logger";
+import type { Column } from "../orm/column";
+import type { ExtractTableName, FMTable, InferSchemaOutputFromFMTable, ValidExpandTarget } from "../orm/table";
+import { getNavigationPaths, getTableName } from "../orm/table";
 import type {
-  ExecutionContext,
+  ConditionallyWithODataAnnotations,
+  ConditionallyWithSpecialColumns,
   ExecutableBuilder,
-  Result,
-  ODataRecordMetadata,
-  ODataFieldResponse,
-  InferSchemaType,
+  ExecuteMethodOptions,
   ExecuteOptions,
+  ExecutionContext,
+  NormalizeIncludeSpecialColumns,
+  ODataFieldResponse,
+  Result,
 } from "../types";
-import type { TableOccurrence } from "./table-occurrence";
-import type { BaseTable } from "./base-table";
-import { transformTableName, transformResponseFields, getTableIdentifiers } from "../transform";
+import {
+  buildSelectExpandQueryString,
+  createODataRequest,
+  ExpandBuilder,
+  type ExpandConfig,
+  type ExpandedRelations,
+  getSchemaFromTable,
+  mergeExecuteOptions,
+  processODataResponse,
+  processSelectWithRenames,
+  resolveTableId,
+} from "./builders/index";
+import { parseErrorResponse } from "./error-parser";
+import type { ResolveExpandedRelations, SystemColumnsFromOption, SystemColumnsOption } from "./query/types";
 import { QueryBuilder } from "./query-builder";
-import { validateSingleResponse } from "../validation";
-import { type FFetchOptions } from "@fetchkit/ffetch";
-import { StandardSchemaV1 } from "@standard-schema/spec";
-// import type { z } from "zod/v4";
-
-// Helper type to extract schema from a TableOccurrence
-type ExtractSchemaFromOccurrence<O> =
-  O extends TableOccurrence<infer BT, any, any, any>
-    ? BT extends BaseTable<infer S, any, any, any>
-      ? S
-      : never
-    : never;
-
-// Helper type to extract navigation relation names from an occurrence
-type ExtractNavigationNames<
-  O extends TableOccurrence<any, any, any, any> | undefined,
-> =
-  O extends TableOccurrence<any, any, infer Nav, any>
-    ? Nav extends Record<string, any>
-      ? keyof Nav
-      : never
-    : never;
-
-// Helper type to resolve a navigation item (handles both direct and lazy-loaded)
-type ResolveNavigationItem<T> = T extends () => infer R ? R : T;
-
-// Helper type to find target occurrence by relation name
-type FindNavigationTarget<
-  O extends TableOccurrence<any, any, any, any> | undefined,
-  Name extends string,
-> =
-  O extends TableOccurrence<any, any, infer Nav, any>
-    ? Name extends keyof Nav
-      ? ResolveNavigationItem<Nav[Name]>
-      : never
-    : never;
+import { safeJsonParse } from "./sanitize-json";
+
+/**
+ * Extract the value type from a Column.
+ * This uses the phantom type stored in Column to get the actual value type.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer
+type ExtractColumnType<C> = C extends Column<infer T, any> ? T : never;
+
+/**
+ * Map a select object to its return type.
+ * For each key in the select object, extract the type from the corresponding Column.
+ */
+type MapSelectToReturnType<
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+  TSelect extends Record<string, Column<any, any, any, any>>,
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any schema shape
+  _TSchema extends Record<string, any>,
+> = {
+  [K in keyof TSelect]: ExtractColumnType<TSelect[K]>;
+};
+
+// Return type for RecordBuilder execute
+export type RecordReturnType<
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any schema shape
+  Schema extends Record<string, any>,
+  IsSingleField extends boolean,
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+  FieldColumn extends Column<any, any, any, any> | undefined,
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration, accepts any FMTable
+  Selected extends keyof Schema | Record<string, Column<any, any, ExtractTableName<FMTable<any, any>>>>,
+  Expands extends ExpandedRelations,
+  SystemCols extends SystemColumnsOption | undefined = undefined,
+> = IsSingleField extends true
+  ? // biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer
+    FieldColumn extends Column<infer TOutput, any, any, any>
+    ? TOutput
+    : never
+  : // Use tuple wrapping [Selected] extends [...] to prevent distribution over unions
+    // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+    [Selected] extends [Record<string, Column<any, any, any, any>>]
+    ? MapSelectToReturnType<Selected, Schema> & ResolveExpandedRelations<Expands> & SystemColumnsFromOption<SystemCols>
+    : // Use tuple wrapping to prevent distribution over union of keys
+      [Selected] extends [keyof Schema]
+      ? Pick<Schema, Selected> & ResolveExpandedRelations<Expands> & SystemColumnsFromOption<SystemCols>
+      : never;
 
 export class RecordBuilder<
-  T extends Record<string, any>,
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration, default allows untyped tables
+  Occ extends FMTable<any, any> = FMTable<any, any>,
   IsSingleField extends boolean = false,
-  FieldKey extends keyof T = keyof T,
-  Occ extends TableOccurrence<any, any, any, any> | undefined =
-    | TableOccurrence<any, any, any, any>
-    | undefined,
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+  FieldColumn extends Column<any, any, any, any> | undefined = undefined,
+  Selected extends
+    | keyof InferSchemaOutputFromFMTable<NonNullable<Occ>>
+    // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+    | Record<string, Column<any, any, ExtractTableName<NonNullable<Occ>>>> = keyof InferSchemaOutputFromFMTable<
+    NonNullable<Occ>
+  >,
+  Expands extends ExpandedRelations = {},
+  DatabaseIncludeSpecialColumns extends boolean = false,
+  SystemCols extends SystemColumnsOption | undefined = undefined,
 > implements
     ExecutableBuilder<
-      IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata
+      RecordReturnType<
+        InferSchemaOutputFromFMTable<NonNullable<Occ>>,
+        IsSingleField,
+        FieldColumn,
+        Selected,
+        Expands,
+        SystemCols
+      >
     >
 {
-  private occurrence?: Occ;
-  private tableName: string;
-  private databaseName: string;
-  private context: ExecutionContext;
-  private recordId: string | number;
-  private operation?: "getSingleField" | "navigate";
-  private operationParam?: string;
-  private isNavigateFromEntitySet?: boolean;
-  private navigateRelation?: string;
-  private navigateSourceTableName?: string;
-
-  private databaseUseEntityIds: boolean;
+  private readonly table: Occ;
+  private readonly databaseName: string;
+  private readonly context: ExecutionContext;
+  private readonly recordId: string | number;
+  private readonly operation?: "getSingleField" | "navigate";
+  private readonly operationParam?: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+  private readonly operationColumn?: Column<any, any, any, any>;
+  private readonly isNavigateFromEntitySet?: boolean;
+  private readonly navigateRelation?: string;
+  private readonly navigateSourceTableName?: string;
+
+  private readonly databaseUseEntityIds: boolean;
+  private readonly databaseIncludeSpecialColumns: boolean;
+
+  // Properties for select/expand support
+  private readonly selectedFields?: string[];
+  private readonly expandConfigs: ExpandConfig[] = [];
+  // Mapping from field names to output keys (for renamed fields in select)
+  private readonly fieldMapping?: Record<string, string>;
+  // System columns requested via select() second argument
+  private readonly systemColumns?: SystemColumnsOption;
+
+  private readonly logger: InternalLogger;
 
   constructor(config: {
-    occurrence?: Occ;
-    tableName: string;
+    occurrence: Occ;
     databaseName: string;
     context: ExecutionContext;
     recordId: string | number;
     databaseUseEntityIds?: boolean;
+    databaseIncludeSpecialColumns?: boolean;
   }) {
-    this.occurrence = config.occurrence;
-    this.tableName = config.tableName;
+    this.table = config.occurrence;
     this.databaseName = config.databaseName;
     this.context = config.context;
     this.recordId = config.recordId;
     this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;
+    this.databaseIncludeSpecialColumns = config.databaseIncludeSpecialColumns ?? false;
+    this.logger = config.context?._getLogger?.() ?? createLogger();
   }
 
   /**
-   * Helper to merge database-level useEntityIds with per-request options
+   * Helper to merge database-level useEntityIds and includeSpecialColumns 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
+  private mergeExecuteOptions(options?: RequestInit & FFetchOptions & ExecuteOptions): RequestInit &
+    FFetchOptions & {
+      useEntityIds?: boolean;
+      includeSpecialColumns?: boolean;
+    } {
+    const merged = mergeExecuteOptions(options, this.databaseUseEntityIds);
     return {
-      ...options,
-      useEntityIds: options?.useEntityIds ?? this.databaseUseEntityIds,
+      ...merged,
+      includeSpecialColumns: options?.includeSpecialColumns ?? this.databaseIncludeSpecialColumns,
     };
   }
 
@@ -107,114 +166,376 @@ export class RecordBuilder<
    * @param useEntityIds - Optional override for entity ID usage
    */
   private getTableId(useEntityIds?: boolean): string {
-    if (!this.occurrence) {
-      return this.tableName;
+    if (!this.table) {
+      throw new Error("Table occurrence is required");
     }
+    return resolveTableId(this.table, getTableName(this.table), this.context, useEntityIds);
+  }
 
-    const contextDefault = this.context._getUseEntityIds?.() ?? false;
-    const shouldUseIds = useEntityIds ?? contextDefault;
+  /**
+   * Creates a new RecordBuilder with modified configuration.
+   * Used by select() to create new instances.
+   */
+  private cloneWithChanges<
+    NewSelected extends
+      | keyof InferSchemaOutputFromFMTable<NonNullable<Occ>>
+      // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+      | Record<string, Column<any, any, ExtractTableName<NonNullable<Occ>>>> = Selected,
+    NewSystemCols extends SystemColumnsOption | undefined = SystemCols,
+  >(changes: {
+    selectedFields?: string[];
+    fieldMapping?: Record<string, string>;
+    systemColumns?: NewSystemCols;
+  }): RecordBuilder<Occ, false, FieldColumn, NewSelected, Expands, DatabaseIncludeSpecialColumns, NewSystemCols> {
+    const newBuilder = new RecordBuilder<
+      Occ,
+      false,
+      FieldColumn,
+      NewSelected,
+      Expands,
+      DatabaseIncludeSpecialColumns,
+      NewSystemCols
+    >({
+      occurrence: this.table,
+      databaseName: this.databaseName,
+      context: this.context,
+      recordId: this.recordId,
+      databaseUseEntityIds: this.databaseUseEntityIds,
+      databaseIncludeSpecialColumns: this.databaseIncludeSpecialColumns,
+    });
+    // Use type assertion to allow assignment to readonly properties on new instance
+
+    // biome-ignore lint/suspicious/noExplicitAny: Mutation of readonly properties for builder pattern
+    const mutableBuilder = newBuilder as any;
+    mutableBuilder.selectedFields = changes.selectedFields ?? this.selectedFields;
+    mutableBuilder.fieldMapping = changes.fieldMapping ?? this.fieldMapping;
+    mutableBuilder.systemColumns = changes.systemColumns !== undefined ? changes.systemColumns : this.systemColumns;
+    mutableBuilder.expandConfigs = [...this.expandConfigs];
+    // Preserve navigation context
+    mutableBuilder.isNavigateFromEntitySet = this.isNavigateFromEntitySet;
+    mutableBuilder.navigateRelation = this.navigateRelation;
+    mutableBuilder.navigateSourceTableName = this.navigateSourceTableName;
+    mutableBuilder.operationColumn = this.operationColumn;
+    return newBuilder;
+  }
 
-    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;
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+  getSingleField<TColumn extends Column<any, any, ExtractTableName<NonNullable<Occ>>, any>>(
+    column: TColumn,
+  ): RecordBuilder<
+    Occ,
+    true,
+    TColumn,
+    keyof InferSchemaOutputFromFMTable<NonNullable<Occ>>,
+    {},
+    DatabaseIncludeSpecialColumns
+  > {
+    // Runtime validation: ensure column is from the correct table
+    const tableName = getTableName(this.table);
+    if (!column.isFromTable(tableName)) {
+      throw new Error(`Column ${column.toString()} is not from table ${tableName}`);
     }
 
-    return this.occurrence.getTableName();
-  }
-
-  getSingleField<K extends keyof T>(field: K): RecordBuilder<T, true, K, Occ> {
-    const newBuilder = new RecordBuilder<T, true, K, Occ>({
-      occurrence: this.occurrence,
-      tableName: this.tableName,
+    const newBuilder = new RecordBuilder<
+      Occ,
+      true,
+      TColumn,
+      keyof InferSchemaOutputFromFMTable<NonNullable<Occ>>,
+      {},
+      DatabaseIncludeSpecialColumns
+    >({
+      occurrence: this.table,
       databaseName: this.databaseName,
       context: this.context,
       recordId: this.recordId,
+      databaseUseEntityIds: this.databaseUseEntityIds,
+      databaseIncludeSpecialColumns: this.databaseIncludeSpecialColumns,
     });
-    newBuilder.operation = "getSingleField";
-    newBuilder.operationParam = field.toString();
+    // Use type assertion to allow assignment to readonly properties on new instance
+
+    // biome-ignore lint/suspicious/noExplicitAny: Mutation of readonly properties for builder pattern
+    const mutableBuilder = newBuilder as any;
+    mutableBuilder.operation = "getSingleField";
+    mutableBuilder.operationColumn = column;
+    mutableBuilder.operationParam = column.getFieldIdentifier(this.databaseUseEntityIds);
     // Preserve navigation context
-    newBuilder.isNavigateFromEntitySet = this.isNavigateFromEntitySet;
-    newBuilder.navigateRelation = this.navigateRelation;
-    newBuilder.navigateSourceTableName = this.navigateSourceTableName;
+    mutableBuilder.isNavigateFromEntitySet = this.isNavigateFromEntitySet;
+    mutableBuilder.navigateRelation = this.navigateRelation;
+    mutableBuilder.navigateSourceTableName = this.navigateSourceTableName;
     return newBuilder;
   }
 
-  // Overload for valid relation names - returns typed QueryBuilder
-  navigate<RelationName extends ExtractNavigationNames<Occ>>(
-    relationName: RelationName,
+  /**
+   * Select fields using column references.
+   * Allows renaming fields by using different keys in the object.
+   * Container fields cannot be selected and will cause a type error.
+   *
+   * @example
+   * db.from(contacts).get("uuid").select({
+   *   name: contacts.name,
+   *   userEmail: contacts.email  // renamed!
+   * })
+   *
+   * @example
+   * // Include system columns (ROWID, ROWMODID) when using select()
+   * db.from(contacts).get("uuid").select(
+   *   { name: contacts.name },
+   *   { ROWID: true, ROWMODID: true }
+   * )
+   *
+   * @param fields - Object mapping output keys to column references (container fields excluded)
+   * @param systemColumns - Optional object to request system columns (ROWID, ROWMODID)
+   * @returns RecordBuilder with updated selected fields
+   */
+  select<
+    // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+    TSelect extends Record<string, Column<any, any, ExtractTableName<Occ>, false>>,
+    TSystemCols extends SystemColumnsOption = {},
+  >(
+    fields: TSelect,
+    systemColumns?: TSystemCols,
+  ): RecordBuilder<Occ, false, FieldColumn, TSelect, Expands, DatabaseIncludeSpecialColumns, TSystemCols> {
+    const tableName = getTableName(this.table);
+    const { selectedFields, fieldMapping } = processSelectWithRenames(fields, tableName, this.logger);
+
+    // Add system columns to selectedFields if requested
+    const finalSelectedFields = [...selectedFields];
+    if (systemColumns?.ROWID) {
+      finalSelectedFields.push("ROWID");
+    }
+    if (systemColumns?.ROWMODID) {
+      finalSelectedFields.push("ROWMODID");
+    }
+
+    return this.cloneWithChanges({
+      selectedFields: finalSelectedFields,
+      fieldMapping: Object.keys(fieldMapping).length > 0 ? fieldMapping : undefined,
+      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic type parameter
+      systemColumns: systemColumns as any,
+      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for complex generic return type
+    }) as any;
+  }
+
+  /**
+   * Expand a navigation property to include related records.
+   * Supports nested select, filter, orderBy, and expand operations.
+   *
+   * @example
+   * ```typescript
+   * // Simple expand with FMTable object
+   * const contact = await db.from(contacts).get("uuid").expand(users).execute();
+   *
+   * // Expand with select
+   * const contact = await db.from(contacts).get("uuid")
+   *   .expand(users, b => b.select({ username: users.username, email: users.email }))
+   *   .execute();
+   * ```
+   */
+  expand<
+    // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+    TargetTable extends FMTable<any, any>,
+    TSelected extends
+      | keyof InferSchemaOutputFromFMTable<TargetTable>
+      | Record<
+          string,
+          // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+          Column<any, any, ExtractTableName<TargetTable>>
+        > = keyof InferSchemaOutputFromFMTable<TargetTable>,
+    TNestedExpands extends ExpandedRelations = {},
+  >(
+    targetTable: ValidExpandTarget<Occ, TargetTable>,
+    callback?: (
+      builder: QueryBuilder<TargetTable, keyof InferSchemaOutputFromFMTable<TargetTable>, false, false, {}>,
+      // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any QueryBuilder configuration
+    ) => QueryBuilder<TargetTable, TSelected, any, any, TNestedExpands>,
+  ): RecordBuilder<
+    Occ,
+    false,
+    FieldColumn,
+    Selected,
+    Expands & {
+      [K in ExtractTableName<TargetTable>]: {
+        schema: InferSchemaOutputFromFMTable<TargetTable>;
+        selected: TSelected;
+        nested: TNestedExpands;
+      };
+    },
+    DatabaseIncludeSpecialColumns,
+    SystemCols
+  > {
+    // Create new builder with updated types
+    // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any ExpandedRelations
+    const newBuilder = new RecordBuilder<Occ, false, FieldColumn, Selected, any, DatabaseIncludeSpecialColumns>({
+      occurrence: this.table,
+      databaseName: this.databaseName,
+      context: this.context,
+      recordId: this.recordId,
+      databaseUseEntityIds: this.databaseUseEntityIds,
+      databaseIncludeSpecialColumns: this.databaseIncludeSpecialColumns,
+    });
+
+    // Use type assertion to allow assignment to readonly properties on new instance
+    // biome-ignore lint/suspicious/noExplicitAny: Mutation of readonly properties for builder pattern
+    const mutableBuilder = newBuilder as any;
+    // Copy existing state
+    mutableBuilder.selectedFields = this.selectedFields;
+    mutableBuilder.fieldMapping = this.fieldMapping;
+    mutableBuilder.systemColumns = this.systemColumns;
+    mutableBuilder.expandConfigs = [...this.expandConfigs];
+    mutableBuilder.isNavigateFromEntitySet = this.isNavigateFromEntitySet;
+    mutableBuilder.navigateRelation = this.navigateRelation;
+    mutableBuilder.navigateSourceTableName = this.navigateSourceTableName;
+    mutableBuilder.operationColumn = this.operationColumn;
+
+    // Use ExpandBuilder.processExpand to handle the expand logic
+    const expandBuilder = new ExpandBuilder(this.databaseUseEntityIds, this.logger);
+    type TargetBuilder = QueryBuilder<TargetTable, keyof InferSchemaOutputFromFMTable<TargetTable>, false, false, {}>;
+    const expandConfig = expandBuilder.processExpand<TargetTable, TargetBuilder>(
+      targetTable,
+      this.table ?? undefined,
+      callback as ((builder: TargetBuilder) => TargetBuilder) | undefined,
+      () =>
+        // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any QueryBuilder configuration
+        new QueryBuilder<TargetTable, any, any, any, any, DatabaseIncludeSpecialColumns, undefined>({
+          occurrence: targetTable,
+          databaseName: this.databaseName,
+          context: this.context,
+          databaseUseEntityIds: this.databaseUseEntityIds,
+          databaseIncludeSpecialColumns: this.databaseIncludeSpecialColumns,
+        }),
+    );
+
+    mutableBuilder.expandConfigs.push(expandConfig);
+    // biome-ignore lint/suspicious/noExplicitAny: Type assertion needed as expand changes generic parameters in complex way that TypeScript cannot infer
+    return newBuilder as any;
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  navigate<TargetTable extends FMTable<any, any>>(
+    targetTable: ValidExpandTarget<Occ, TargetTable>,
   ): QueryBuilder<
-    ExtractSchemaFromOccurrence<
-      FindNavigationTarget<Occ, RelationName>
-    > extends Record<string, StandardSchemaV1>
-      ? InferSchemaType<
-          ExtractSchemaFromOccurrence<FindNavigationTarget<Occ, RelationName>>
-        >
-      : Record<string, any>
-  >;
-  // Overload for arbitrary strings - returns generic QueryBuilder with system fields
-  navigate(
-    relationName: string,
-  ): QueryBuilder<{ ROWID: number; ROWMODID: number; [key: string]: any }>;
-  // Implementation
-  navigate(relationName: string): QueryBuilder<any> {
-    // Use the target occurrence if available, otherwise allow untyped navigation
-    // (useful when types might be incomplete)
-    const targetOccurrence = this.occurrence?.navigation[relationName];
-    const builder = new QueryBuilder<any>({
-      occurrence: targetOccurrence,
-      tableName: targetOccurrence?.name ?? relationName,
+    TargetTable,
+    keyof InferSchemaOutputFromFMTable<TargetTable>,
+    false,
+    false,
+    {},
+    DatabaseIncludeSpecialColumns,
+    undefined
+  > {
+    // Extract name and validate
+    const relationName = getTableName(targetTable);
+
+    // Runtime validation: Check if relation name is in navigationPaths
+    if (this.table) {
+      const navigationPaths = getNavigationPaths(this.table);
+      if (navigationPaths && !navigationPaths.includes(relationName)) {
+        this.logger.warn(
+          `Cannot navigate to "${relationName}". Valid navigation paths: ${navigationPaths.length > 0 ? navigationPaths.join(", ") : "none"}`,
+        );
+      }
+    }
+
+    // Create QueryBuilder with target table
+    // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any QueryBuilder configuration
+    const builder = new QueryBuilder<TargetTable, any, any, any, any, DatabaseIncludeSpecialColumns, undefined>({
+      occurrence: targetTable,
       databaseName: this.databaseName,
       context: this.context,
+      databaseUseEntityIds: this.databaseUseEntityIds,
+      databaseIncludeSpecialColumns: this.databaseIncludeSpecialColumns,
     });
-    // Store the navigation info - we'll use it in execute
-    // Transform relation name to FMTID if using entity IDs
-    const relationId = targetOccurrence
-      ? transformTableName(targetOccurrence)
-      : relationName;
 
-    (builder as any).isNavigate = true;
-    (builder as any).navigateRecordId = this.recordId;
-    (builder as any).navigateRelation = relationId;
+    // Store the navigation info - we'll use it in execute
+    // Use relation name as-is (entity ID handling is done in QueryBuilder)
+    const relationId = relationName;
 
     // If this RecordBuilder came from a navigated EntitySet, we need to preserve that base path
-    if (
-      this.isNavigateFromEntitySet &&
-      this.navigateSourceTableName &&
-      this.navigateRelation
-    ) {
+    let sourceTableName: string;
+    let baseRelation: string | undefined;
+    if (this.isNavigateFromEntitySet && this.navigateSourceTableName && this.navigateRelation) {
       // Build the base path: /sourceTable/relation('recordId')/newRelation
-      (builder as any).navigateSourceTableName = this.navigateSourceTableName;
-      (builder as any).navigateBaseRelation = this.navigateRelation;
+      sourceTableName = this.navigateSourceTableName;
+      baseRelation = this.navigateRelation;
     } else {
       // Normal record navigation: /tableName('recordId')/relation
-      // Transform source table name to FMTID if using entity IDs
-      const sourceTableId = this.occurrence
-        ? transformTableName(this.occurrence)
-        : this.tableName;
-      (builder as any).navigateSourceTableName = sourceTableId;
+      // Use table ID if available, otherwise table name
+      if (!this.table) {
+        throw new Error("Table occurrence is required for navigation");
+      }
+      sourceTableName = resolveTableId(this.table, getTableName(this.table), this.context, this.databaseUseEntityIds);
     }
 
+    // biome-ignore lint/suspicious/noExplicitAny: Mutation of readonly properties for builder pattern
+    (builder as any).navigation = {
+      recordId: this.recordId,
+      relation: relationId,
+      sourceTableName,
+      baseRelation,
+    };
+    // biome-ignore lint/suspicious/noExplicitAny: Mutation of readonly properties for builder pattern
+    (builder as any).navigation = {
+      recordId: this.recordId,
+      relation: relationId,
+      sourceTableName,
+      baseRelation,
+    };
+
     return builder;
   }
 
-  async execute(
-    options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },
+  /**
+   * Builds the complete query string including $select and $expand parameters.
+   */
+  private buildQueryString(includeSpecialColumns?: boolean, useEntityIds?: boolean): string {
+    // Use merged includeSpecialColumns if provided, otherwise use database-level default
+    const finalIncludeSpecialColumns = includeSpecialColumns ?? this.databaseIncludeSpecialColumns;
+    // Use merged useEntityIds if provided, otherwise use database-level default
+    const finalUseEntityIds = useEntityIds ?? this.databaseUseEntityIds;
+
+    return buildSelectExpandQueryString({
+      selectedFields: this.selectedFields,
+      expandConfigs: this.expandConfigs,
+      table: this.table,
+      useEntityIds: finalUseEntityIds,
+      logger: this.logger,
+      includeSpecialColumns: finalIncludeSpecialColumns,
+    });
+  }
+
+  async execute<EO extends ExecuteOptions>(
+    options?: ExecuteMethodOptions<EO>,
   ): Promise<
-    Result<IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata>
+    Result<
+      ConditionallyWithODataAnnotations<
+        ConditionallyWithSpecialColumns<
+          RecordReturnType<
+            InferSchemaOutputFromFMTable<NonNullable<Occ>>,
+            IsSingleField,
+            FieldColumn,
+            Selected,
+            Expands,
+            SystemCols
+          >,
+          // Use the merged value: if explicitly provided in options, use that; otherwise use database default
+          NormalizeIncludeSpecialColumns<EO["includeSpecialColumns"], DatabaseIncludeSpecialColumns>,
+          // Check if select was applied: if Selected is Record (object select) or a subset of keys, select was applied
+          IsSingleField extends true
+            ? false // Single field operations don't include special columns
+            : // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+              Selected extends Record<string, Column<any, any, any>>
+              ? true
+              : Selected extends keyof InferSchemaOutputFromFMTable<NonNullable<Occ>>
+                ? false
+                : true
+        >,
+        EO["includeODataAnnotations"] extends true ? true : false
+      >
+    >
   > {
     let url: string;
 
     // Build the base URL depending on whether this came from a navigated EntitySet
-    if (
-      this.isNavigateFromEntitySet &&
-      this.navigateSourceTableName &&
-      this.navigateRelation
-    ) {
+    if (this.isNavigateFromEntitySet && this.navigateSourceTableName && this.navigateRelation) {
       // From navigated EntitySet: /sourceTable/relation('recordId')
       url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
     } else {
@@ -223,71 +544,56 @@ export class RecordBuilder<
       url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
     }
 
+    const mergedOptions = this.mergeExecuteOptions(options);
+
     if (this.operation === "getSingleField" && this.operationParam) {
       url += `/${this.operationParam}`;
+    } else {
+      // Add query string for select/expand (only when not getting a single field)
+      const queryString = this.buildQueryString(mergedOptions.includeSpecialColumns, mergedOptions.useEntityIds);
+      url += queryString;
     }
-
-    const mergedOptions = this.mergeExecuteOptions(options);
     const result = await this.context._makeRequest(url, mergedOptions);
 
     if (result.error) {
       return { data: undefined, error: result.error };
     }
 
-    let response = result.data;
+    const response = result.data;
 
     // Handle single field operation
     if (this.operation === "getSingleField") {
       // Single field returns a JSON object with @context and value
-      const fieldResponse = response as ODataFieldResponse<T>;
+      // The type is extracted from the Column stored in FieldColumn generic
+      // biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API
+      const fieldResponse = response as ODataFieldResponse<any>;
+      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic type extraction
       return { data: fieldResponse.value as any, error: 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) {
-      response = transformResponseFields(
-        response,
-        this.occurrence.baseTable,
-        undefined, // No expand configs for simple get
-      );
-    }
-
-    // Get schema from occurrence if available
-    const schema = this.occurrence?.baseTable?.schema;
-
-    // Validate the single record response
-    const validation = await validateSingleResponse<any>(
-      response,
-      schema,
-      undefined, // No selected fields for record.get()
-      undefined, // No expand configs
-      "exact", // Expect exactly one record
-    );
-
-    if (!validation.valid) {
-      return { data: undefined, error: validation.error };
-    }
-
-    // Handle null response
-    if (validation.data === null) {
-      return { data: null as any, error: undefined };
-    }
-
-    return { data: validation.data, error: undefined };
+    // Use shared response processor
+    const expandBuilder = new ExpandBuilder(mergedOptions.useEntityIds ?? false, this.logger);
+    const expandValidationConfigs = expandBuilder.buildValidationConfigs(this.expandConfigs);
+
+    return processODataResponse(response, {
+      table: this.table,
+      schema: getSchemaFromTable(this.table),
+      singleMode: "exact",
+      selectedFields: this.selectedFields,
+      expandValidationConfigs,
+      skipValidation: options?.skipValidation,
+      useEntityIds: mergedOptions.useEntityIds,
+      includeSpecialColumns: mergedOptions.includeSpecialColumns,
+      fieldMapping: this.fieldMapping,
+    });
   }
 
+  // biome-ignore lint/suspicious/noExplicitAny: Request body can be any JSON-serializable value
   getRequestConfig(): { method: string; url: string; body?: any } {
     let url: string;
 
     // Build the base URL depending on whether this came from a navigated EntitySet
-    if (
-      this.isNavigateFromEntitySet &&
-      this.navigateSourceTableName &&
-      this.navigateRelation
-    ) {
+    if (this.isNavigateFromEntitySet && this.navigateSourceTableName && this.navigateRelation) {
       // From navigated EntitySet: /sourceTable/relation('recordId')
       url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
     } else {
@@ -296,8 +602,16 @@ export class RecordBuilder<
       url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
     }
 
-    if (this.operation === "getSingleField" && this.operationParam) {
+    if (this.operation === "getSingleField" && this.operationColumn) {
+      // Use the column's getFieldIdentifier to support entity IDs
+      url += `/${this.operationColumn.getFieldIdentifier(this.databaseUseEntityIds)}`;
+    } else if (this.operation === "getSingleField" && this.operationParam) {
+      // Fallback for backwards compatibility (shouldn't happen in normal flow)
       url += `/${this.operationParam}`;
+    } else {
+      // Add query string for select/expand (only when not getting a single field)
+      const queryString = this.buildQueryString();
+      url += queryString;
     }
 
     return {
@@ -306,68 +620,89 @@ export class RecordBuilder<
     };
   }
 
-  toRequest(baseUrl: string): Request {
+  /**
+   * Returns the query string for this record builder (for testing purposes).
+   */
+  getQueryString(options?: { useEntityIds?: boolean }): string {
+    const useEntityIds = options?.useEntityIds ?? this.databaseUseEntityIds;
+    let path: string;
+
+    // Build the path depending on navigation context
+    if (this.isNavigateFromEntitySet && this.navigateSourceTableName && this.navigateRelation) {
+      path = `/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
+    } else {
+      // Use getTableId to respect entity ID settings (same as getRequestConfig)
+      const tableId = this.getTableId(useEntityIds);
+      path = `/${tableId}('${this.recordId}')`;
+    }
+
+    if (this.operation === "getSingleField" && this.operationColumn) {
+      return `${path}/${this.operationColumn.getFieldIdentifier(useEntityIds)}`;
+    }
+    if (this.operation === "getSingleField" && this.operationParam) {
+      // Fallback for backwards compatibility (shouldn't happen in normal flow)
+      return `${path}/${this.operationParam}`;
+    }
+
+    const queryString = this.buildQueryString(undefined, useEntityIds);
+    return `${path}${queryString}`;
+  }
+
+  toRequest(baseUrl: string, options?: ExecuteOptions): 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",
-      },
-    });
+    return createODataRequest(baseUrl, config, options);
   }
 
   async processResponse(
     response: Response,
     options?: ExecuteOptions,
   ): Promise<
-    Result<IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata>
+    Result<
+      RecordReturnType<
+        InferSchemaOutputFromFMTable<NonNullable<Occ>>,
+        IsSingleField,
+        FieldColumn,
+        Selected,
+        Expands,
+        SystemCols
+      >
+    >
   > {
-    const rawResponse = await response.json();
+    // Check for error responses (important for batch operations)
+    if (!response.ok) {
+      const tableName = this.table ? getTableName(this.table) : "unknown";
+      const error = await parseErrorResponse(response, response.url || `/${this.databaseName}/${tableName}`);
+      return { data: undefined, error };
+    }
+
+    // Use safeJsonParse to handle FileMaker's invalid JSON with unquoted ? values
+    const rawResponse = await safeJsonParse(response);
 
     // Handle single field operation
     if (this.operation === "getSingleField") {
       // Single field returns a JSON object with @context and value
-      const fieldResponse = rawResponse as ODataFieldResponse<T>;
+      // The type is extracted from the Column stored in FieldColumn generic
+      // biome-ignore lint/suspicious/noExplicitAny: Type parameter inferred from FieldColumn generic
+      const fieldResponse = rawResponse as ODataFieldResponse<any>;
+      // biome-ignore lint/suspicious/noExplicitAny: Type parameter inferred from FieldColumn generic
       return { data: fieldResponse.value as any, error: 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 = options?.useEntityIds ?? this.databaseUseEntityIds;
-    
-    let transformedResponse = rawResponse;
-    if (this.occurrence?.baseTable && shouldUseIds) {
-      transformedResponse = transformResponseFields(
-        rawResponse,
-        this.occurrence.baseTable,
-        undefined, // No expand configs for simple get
-      );
-    }
-
-    // Get schema from occurrence if available
-    const schema = this.occurrence?.baseTable?.schema;
-
-    // Validate the single record response
-    const validation = await validateSingleResponse<any>(
-      transformedResponse,
-      schema,
-      undefined, // No selected fields for record.get()
-      undefined, // No expand configs
-      "exact", // Expect exactly one record
-    );
-
-    if (!validation.valid) {
-      return { data: undefined, error: validation.error };
-    }
-
-    // Handle null response
-    if (validation.data === null) {
-      return { data: null as any, error: undefined };
-    }
-
-    return { data: validation.data, error: undefined };
+    // Use shared response processor
+    const mergedOptions = this.mergeExecuteOptions(options);
+    const expandBuilder = new ExpandBuilder(mergedOptions.useEntityIds ?? false, this.logger);
+    const expandValidationConfigs = expandBuilder.buildValidationConfigs(this.expandConfigs);
+
+    return processODataResponse(rawResponse, {
+      table: this.table,
+      schema: getSchemaFromTable(this.table),
+      singleMode: "exact",
+      selectedFields: this.selectedFields,
+      expandValidationConfigs,
+      skipValidation: options?.skipValidation,
+      useEntityIds: mergedOptions.useEntityIds,
+      includeSpecialColumns: mergedOptions.includeSpecialColumns,
+      fieldMapping: this.fieldMapping,
+    });
   }
 }