@proofkit/fmodata 0.1.0-alpha.0

package/src/client/query-builder.ts

@@ -0,0 +1,1076 @@
+import { QueryOptions } from "odata-query";
+import buildQuery from "odata-query";
+import type {
+  ExecutionContext,
+  ExecutableBuilder,
+  WithSystemFields,
+  ODataRecordMetadata,
+  Result,
+  InferSchemaType,
+  ExecuteOptions,
+  ConditionallyWithODataAnnotations,
+  ExtractSchemaFromOccurrence,
+} from "../types";
+import type { Filter } from "../filter-types";
+import type { TableOccurrence } from "./table-occurrence";
+import type { BaseTable } from "./base-table";
+import { validateListResponse, validateSingleResponse } from "../validation";
+import { type FFetchOptions } from "@fetchkit/ffetch";
+import { z } from "zod/v4";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+// 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 & string
+      : 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>
+    ? Nav extends Record<string, any>
+      ? Name extends keyof Nav
+        ? ResolveNavigationItem<Nav[Name]>
+        : TableOccurrence<
+            BaseTable<Record<string, z.ZodTypeAny>, any>,
+            any,
+            any,
+            any
+          >
+      : TableOccurrence<
+          BaseTable<Record<string, z.ZodTypeAny>, any>,
+          any,
+          any,
+          any
+        >
+    : TableOccurrence<
+        BaseTable<Record<string, z.ZodTypeAny>, any>,
+        any,
+        any,
+        any
+      >;
+
+// Helper type to get the inferred schema type from a target occurrence
+type GetTargetSchemaType<
+  O extends TableOccurrence<any, any, any, any> | undefined,
+  Rel extends string,
+> = [FindNavigationTarget<O, Rel>] extends [
+  TableOccurrence<infer BT, any, any, any>,
+]
+  ? [BT] extends [BaseTable<infer S, any>]
+    ? [S] extends [Record<string, StandardSchemaV1>]
+      ? InferSchemaType<S>
+      : Record<string, any>
+    : Record<string, any>
+  : Record<string, any>;
+
+// Internal type for expand configuration
+type ExpandConfig = {
+  relation: string;
+  options?: Partial<QueryOptions<any>>;
+};
+
+// Type to represent expanded relations
+type ExpandedRelations = Record<string, { schema: any; selected: any }>;
+
+export class QueryBuilder<
+  T extends Record<string, any>,
+  Selected extends keyof T = keyof T,
+  SingleMode extends "exact" | "maybe" | false = false,
+  IsCount extends boolean = false,
+  Occ extends TableOccurrence<any, any, any, any> | undefined = undefined,
+  Expands extends ExpandedRelations = {},
+> {
+  private queryOptions: Partial<QueryOptions<T>> = {};
+  private expandConfigs: ExpandConfig[] = [];
+  private singleMode: SingleMode = false as SingleMode;
+  private isCountMode = false as IsCount;
+  private occurrence?: Occ;
+  private tableName: string;
+  private databaseName: string;
+  private context: ExecutionContext;
+  private isNavigate?: boolean;
+  private navigateRecordId?: string | number;
+  private navigateRelation?: string;
+  private navigateSourceTableName?: string;
+  private navigateBaseRelation?: string;
+  constructor(config: {
+    occurrence?: Occ;
+    tableName: string;
+    databaseName: string;
+    context: ExecutionContext;
+  }) {
+    this.occurrence = config.occurrence;
+    this.tableName = config.tableName;
+    this.databaseName = config.databaseName;
+    this.context = config.context;
+  }
+
+  /**
+   * Helper to conditionally strip OData annotations based on options
+   */
+  private stripODataAnnotationsIfNeeded<T extends Record<string, any>>(
+    data: T,
+    options?: ExecuteOptions,
+  ): T {
+    // Only include annotations if explicitly requested
+    if (options?.includeODataAnnotations === true) {
+      return data;
+    }
+
+    // Strip OData annotations
+    const { "@id": _id, "@editLink": _editLink, ...rest } = data;
+    return rest as T;
+  }
+
+  select<K extends keyof T>(
+    ...fields: K[]
+  ): QueryBuilder<T, K, SingleMode, IsCount, Occ, Expands> {
+    const uniqueFields = [...new Set(fields)];
+    const newBuilder = new QueryBuilder<
+      T,
+      K,
+      SingleMode,
+      IsCount,
+      Occ,
+      Expands
+    >({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+    });
+    newBuilder.queryOptions = {
+      ...this.queryOptions,
+      select: uniqueFields as string[],
+    };
+    newBuilder.expandConfigs = [...this.expandConfigs];
+    newBuilder.singleMode = this.singleMode;
+    newBuilder.isCountMode = this.isCountMode;
+    // Preserve navigation metadata
+    newBuilder.isNavigate = this.isNavigate;
+    newBuilder.navigateRecordId = this.navigateRecordId;
+    newBuilder.navigateRelation = this.navigateRelation;
+    newBuilder.navigateSourceTableName = this.navigateSourceTableName;
+    newBuilder.navigateBaseRelation = this.navigateBaseRelation;
+    return newBuilder;
+  }
+
+  /**
+   * Transforms our filter format to odata-query's expected format
+   * - Arrays of operators are converted to AND conditions
+   * - Single operator objects pass through as-is
+   * - Shorthand values are handled by odata-query
+   */
+  private transformFilter(
+    filter: Filter<ExtractSchemaFromOccurrence<Occ>>,
+  ): QueryOptions<T>["filter"] {
+    if (typeof filter === "string") {
+      // Raw string filters pass through
+      return filter;
+    }
+
+    if (Array.isArray(filter)) {
+      // Array of filters - odata-query handles this as implicit AND
+      return filter.map((f) => this.transformFilter(f as any)) as any;
+    }
+
+    // Check if it's a logical filter (and/or/not)
+    if ("and" in filter || "or" in filter || "not" in filter) {
+      const result: any = {};
+      if ("and" in filter && Array.isArray(filter.and)) {
+        result.and = filter.and.map((f: any) => this.transformFilter(f));
+      }
+      if ("or" in filter && Array.isArray(filter.or)) {
+        result.or = filter.or.map((f: any) => this.transformFilter(f));
+      }
+      if ("not" in filter && filter.not) {
+        result.not = this.transformFilter(filter.not as any);
+      }
+      return result;
+    }
+
+    // Transform field filters
+    const result: any = {};
+    const andConditions: any[] = [];
+
+    for (const [field, value] of Object.entries(filter)) {
+      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];
+        } else {
+          // Multiple operators - combine with AND
+          // Create separate conditions for each operator
+          for (const op of value) {
+            andConditions.push({ [field]: op });
+          }
+        }
+      } else if (
+        value &&
+        typeof value === "object" &&
+        !(value instanceof Date) &&
+        !Array.isArray(value)
+      ) {
+        // Check if it's an operator object (has operator keys like eq, gt, etc.)
+        const operatorKeys = [
+          "eq",
+          "ne",
+          "gt",
+          "ge",
+          "lt",
+          "le",
+          "contains",
+          "startswith",
+          "endswith",
+          "in",
+        ];
+        const isOperatorObject = operatorKeys.some((key) => key in value);
+
+        if (isOperatorObject) {
+          // Single operator object - pass through
+          result[field] = value;
+        } else {
+          // Regular object - might be nested filter, pass through
+          result[field] = value;
+        }
+      } else {
+        // Primitive value (shorthand) - pass through
+        result[field] = value;
+      }
+    }
+
+    // If we have AND conditions from arrays, combine them
+    if (andConditions.length > 0) {
+      if (Object.keys(result).length > 0) {
+        // We have both regular fields and array-derived AND conditions
+        // Combine everything with AND
+        return { and: [...andConditions, result] };
+      } else {
+        // Only array-derived AND conditions
+        return { and: andConditions };
+      }
+    }
+
+    return result;
+  }
+
+  filter(
+    filter: Filter<ExtractSchemaFromOccurrence<Occ>>,
+  ): QueryBuilder<T, Selected, SingleMode, IsCount, Occ, Expands> {
+    // Transform our filter format to odata-query's expected format
+    this.queryOptions.filter = this.transformFilter(filter) as any;
+    return this;
+  }
+
+  orderBy(
+    orderBy: QueryOptions<T>["orderBy"],
+  ): QueryBuilder<T, Selected, SingleMode, IsCount, Occ, Expands> {
+    this.queryOptions.orderBy = orderBy;
+    return this;
+  }
+
+  top(
+    count: number,
+  ): QueryBuilder<T, Selected, SingleMode, IsCount, Occ, Expands> {
+    this.queryOptions.top = count;
+    return this;
+  }
+
+  skip(
+    count: number,
+  ): QueryBuilder<T, Selected, SingleMode, IsCount, Occ, Expands> {
+    this.queryOptions.skip = count;
+    return this;
+  }
+
+  /**
+   * Formats select fields for use in query strings.
+   * - Wraps "id" fields in double quotes
+   * - URL-encodes special characters but preserves spaces
+   */
+  private formatSelectFields(select: QueryOptions<any>["select"]): string {
+    if (!select) return "";
+    const selectFieldsArray = Array.isArray(select) ? select : [select];
+    return selectFieldsArray
+      .map((field) => {
+        if (field === "id") return `"id"`;
+        const encodedField = encodeURIComponent(String(field));
+        return encodedField.replace(/%20/g, " ");
+      })
+      .join(",");
+  }
+
+  /**
+   * Builds expand validation configs from internal expand configurations.
+   * These are used to validate expanded navigation properties.
+   */
+  private buildExpandValidationConfigs(
+    configs: ExpandConfig[],
+  ): import("../validation").ExpandValidationConfig[] {
+    return configs.map((config) => {
+      // Look up target occurrence from navigation
+      const targetOccurrence = this.occurrence?.navigation[config.relation];
+      const targetSchema = targetOccurrence?.baseTable?.schema;
+
+      // Extract selected fields from options
+      const selectedFields = config.options?.select
+        ? Array.isArray(config.options.select)
+          ? config.options.select.map((f) => String(f))
+          : [String(config.options.select)]
+        : undefined;
+
+      return {
+        relation: config.relation,
+        targetSchema: targetSchema,
+        targetOccurrence: targetOccurrence,
+        selectedFields: selectedFields,
+        nestedExpands: undefined, // TODO: Handle nested expands if needed
+      };
+    });
+  }
+
+  /**
+   * Builds OData expand query string from expand configurations.
+   * Handles nested expands recursively.
+   */
+  private buildExpandString(configs: ExpandConfig[]): string {
+    if (configs.length === 0) {
+      return "";
+    }
+
+    return configs
+      .map((config) => {
+        if (!config.options || Object.keys(config.options).length === 0) {
+          // Simple expand without options
+          return config.relation;
+        }
+
+        // Build query options for this expand
+        const parts: string[] = [];
+
+        if (config.options.select) {
+          const selectFields = this.formatSelectFields(config.options.select);
+          parts.push(`$select=${selectFields}`);
+        }
+
+        if (config.options.filter) {
+          // Use odata-query to build filter string
+          const filterQuery = buildQuery({ filter: config.options.filter });
+          const filterMatch = filterQuery.match(/\$filter=([^&]+)/);
+          if (filterMatch) {
+            parts.push(`$filter=${filterMatch[1]}`);
+          }
+        }
+
+        if (config.options.orderBy) {
+          const orderByValue = Array.isArray(config.options.orderBy)
+            ? config.options.orderBy.join(",")
+            : config.options.orderBy;
+          parts.push(`$orderby=${String(orderByValue)}`);
+        }
+
+        if (config.options.top !== undefined) {
+          parts.push(`$top=${config.options.top}`);
+        }
+
+        if (config.options.skip !== undefined) {
+          parts.push(`$skip=${config.options.skip}`);
+        }
+
+        // Handle nested expands (from expand configs)
+        if (config.options.expand) {
+          // If expand is a string, it's already been built
+          if (typeof config.options.expand === "string") {
+            parts.push(`$expand=${config.options.expand}`);
+          }
+        }
+
+        if (parts.length === 0) {
+          return config.relation;
+        }
+
+        return `${config.relation}(${parts.join(";")})`;
+      })
+      .join(",");
+  }
+
+  expand<
+    Rel extends ExtractNavigationNames<Occ> | (string & {}),
+    TargetOcc extends FindNavigationTarget<Occ, Rel> = FindNavigationTarget<
+      Occ,
+      Rel
+    >,
+    TargetSchema extends GetTargetSchemaType<Occ, Rel> = GetTargetSchemaType<
+      Occ,
+      Rel
+    >,
+    TargetSelected extends keyof TargetSchema = keyof TargetSchema,
+  >(
+    relation: Rel,
+    callback?: (
+      builder: QueryBuilder<
+        TargetSchema,
+        keyof TargetSchema,
+        false,
+        false,
+        TargetOcc extends TableOccurrence<any, any, any, any>
+          ? TargetOcc
+          : undefined
+      >,
+    ) => QueryBuilder<
+      WithSystemFields<TargetSchema>,
+      TargetSelected,
+      any,
+      any,
+      any
+    >,
+  ): QueryBuilder<
+    T,
+    Selected,
+    SingleMode,
+    IsCount,
+    Occ,
+    Expands & {
+      [K in Rel]: { schema: TargetSchema; selected: TargetSelected };
+    }
+  > {
+    // Look up target occurrence from navigation
+    const targetOccurrence = this.occurrence?.navigation[relation as string];
+
+    if (callback) {
+      // Create a new QueryBuilder for the target occurrence
+      const targetBuilder = new QueryBuilder<any>({
+        occurrence: targetOccurrence,
+        tableName: targetOccurrence?.name ?? (relation as string),
+        databaseName: this.databaseName,
+        context: this.context,
+      });
+
+      // Cast to the expected type for the callback
+      // At runtime, the builder is untyped (any), but at compile-time we enforce proper types
+      const typedBuilder = targetBuilder as QueryBuilder<
+        TargetSchema,
+        keyof TargetSchema,
+        false,
+        false,
+        TargetOcc extends TableOccurrence<any, any, any, any>
+          ? TargetOcc
+          : undefined
+      >;
+
+      // Pass to callback and get configured builder
+      const configuredBuilder = callback(typedBuilder);
+
+      // Extract the builder's query options
+      const expandOptions: Partial<QueryOptions<any>> = {
+        ...configuredBuilder.queryOptions,
+      };
+
+      // If the configured builder has nested expands, we need to include them
+      if (configuredBuilder.expandConfigs.length > 0) {
+        // Build nested expand string from the configured builder's expand configs
+        const nestedExpandString = this.buildExpandString(
+          configuredBuilder.expandConfigs,
+        );
+        if (nestedExpandString) {
+          // Add nested expand to options
+          expandOptions.expand = nestedExpandString as any;
+        }
+      }
+
+      const expandConfig: ExpandConfig = {
+        relation: relation as string,
+        options: expandOptions,
+      };
+
+      this.expandConfigs.push(expandConfig);
+    } else {
+      // Simple expand without callback
+      this.expandConfigs.push({ relation: relation as string });
+    }
+
+    return this as any;
+  }
+
+  single(): QueryBuilder<T, Selected, "exact", IsCount, Occ, Expands> {
+    const newBuilder = new QueryBuilder<
+      T,
+      Selected,
+      "exact",
+      IsCount,
+      Occ,
+      Expands
+    >({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+    });
+    newBuilder.queryOptions = { ...this.queryOptions };
+    newBuilder.expandConfigs = [...this.expandConfigs];
+    newBuilder.singleMode = "exact";
+    newBuilder.isCountMode = this.isCountMode;
+    // Preserve navigation metadata
+    newBuilder.isNavigate = this.isNavigate;
+    newBuilder.navigateRecordId = this.navigateRecordId;
+    newBuilder.navigateRelation = this.navigateRelation;
+    newBuilder.navigateSourceTableName = this.navigateSourceTableName;
+    newBuilder.navigateBaseRelation = this.navigateBaseRelation;
+    return newBuilder;
+  }
+
+  maybeSingle(): QueryBuilder<T, Selected, "maybe", IsCount, Occ, Expands> {
+    const newBuilder = new QueryBuilder<
+      T,
+      Selected,
+      "maybe",
+      IsCount,
+      Occ,
+      Expands
+    >({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+    });
+    newBuilder.queryOptions = { ...this.queryOptions };
+    newBuilder.expandConfigs = [...this.expandConfigs];
+    newBuilder.singleMode = "maybe";
+    newBuilder.isCountMode = this.isCountMode;
+    // Preserve navigation metadata
+    newBuilder.isNavigate = this.isNavigate;
+    newBuilder.navigateRecordId = this.navigateRecordId;
+    newBuilder.navigateRelation = this.navigateRelation;
+    newBuilder.navigateSourceTableName = this.navigateSourceTableName;
+    newBuilder.navigateBaseRelation = this.navigateBaseRelation;
+    return newBuilder;
+  }
+
+  count(): QueryBuilder<T, Selected, SingleMode, true, Occ, Expands> {
+    const newBuilder = new QueryBuilder<
+      T,
+      Selected,
+      SingleMode,
+      true,
+      Occ,
+      Expands
+    >({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+    });
+    newBuilder.queryOptions = { ...this.queryOptions, count: true };
+    newBuilder.expandConfigs = [...this.expandConfigs];
+    newBuilder.singleMode = this.singleMode;
+    newBuilder.isCountMode = true as true;
+    // Preserve navigation metadata
+    newBuilder.isNavigate = this.isNavigate;
+    newBuilder.navigateRecordId = this.navigateRecordId;
+    newBuilder.navigateRelation = this.navigateRelation;
+    newBuilder.navigateSourceTableName = this.navigateSourceTableName;
+    newBuilder.navigateBaseRelation = this.navigateBaseRelation;
+    return newBuilder;
+  }
+
+  async execute<EO extends ExecuteOptions>(
+    options?: RequestInit & FFetchOptions & EO,
+  ): Promise<
+    Result<
+      IsCount extends true
+        ? number
+        : SingleMode extends "exact"
+          ? ConditionallyWithODataAnnotations<
+              Pick<T, Selected> & {
+                [K in keyof Expands]: Pick<
+                  Expands[K]["schema"],
+                  Expands[K]["selected"]
+                >[];
+              },
+              EO["includeODataAnnotations"] extends true ? true : false
+            >
+          : SingleMode extends "maybe"
+            ? ConditionallyWithODataAnnotations<
+                Pick<T, Selected> & {
+                  [K in keyof Expands]: Pick<
+                    Expands[K]["schema"],
+                    Expands[K]["selected"]
+                  >[];
+                },
+                EO["includeODataAnnotations"] extends true ? true : false
+              > | null
+            : ConditionallyWithODataAnnotations<
+                Pick<T, Selected> & {
+                  [K in keyof Expands]: Pick<
+                    Expands[K]["schema"],
+                    Expands[K]["selected"]
+                  >[];
+                },
+                EO["includeODataAnnotations"] extends true ? true : false
+              >[]
+    >
+  > {
+    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;
+      }
+
+      let queryString = buildQuery(queryOptionsWithoutExpand);
+
+      // Build custom expand string
+      const expandString = this.buildExpandString(this.expandConfigs);
+      if (expandString) {
+        const separator = queryString.includes("?") ? "&" : "?";
+        queryString = `${queryString}${separator}$expand=${expandString}`;
+      }
+
+      // 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);
+
+        // 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 Error(
+                  `Expected ${this.singleMode === "exact" ? "exactly one" : "at most one"} record, but received ${count}`,
+                ),
+              };
+            }
+
+            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 };
+          }
+        }
+
+        // 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,
+          );
+          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 };
+        }
+      }
+
+      // 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;
+
+            if (count > 1) {
+              return {
+                data: undefined,
+                error: new Error(
+                  `Expected ${this.singleMode === "exact" ? "exactly one" : "at most one"} record, but received ${count}`,
+                ),
+              };
+            }
+
+            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 };
+          }
+        }
+
+        // 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,
+          );
+          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 };
+        }
+      }
+
+      // Handle $count endpoint
+      if (this.isCountMode) {
+        const result = await this.context._makeRequest(
+          `/${this.databaseName}/${this.tableName}/$count${queryString}`,
+          options,
+        );
+        // 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;
+      }
+
+      const response = await this.context._makeRequest(
+        `/${this.databaseName}/${this.tableName}${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;
+
+          if (count > 1) {
+            return {
+              data: undefined,
+              error: new Error(
+                `Expected ${this.singleMode === "exact" ? "exactly one" : "at most one"} record, but received ${count}`,
+              ),
+            };
+          }
+
+          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 {
+          // 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: 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,
+        };
+      }
+    } catch (error) {
+      return {
+        data: undefined,
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+  }
+
+  getQueryString(): string {
+    // Build query without expand (we'll add it manually)
+    const queryOptionsWithoutExpand = { ...this.queryOptions };
+    delete queryOptionsWithoutExpand.expand;
+
+    // Format select fields before building query - buildQuery treats & as separator,
+    // so we need to pre-encode special characters. buildQuery preserves encoded values.
+    if (queryOptionsWithoutExpand.select) {
+      queryOptionsWithoutExpand.select = this.formatSelectFields(
+        queryOptionsWithoutExpand.select,
+      ) as any;
+    }
+
+    let queryParams = buildQuery(queryOptionsWithoutExpand);
+
+    // Post-process: buildQuery encodes spaces as %20, but we want to preserve spaces
+    // Replace %20 with spaces in the $select part
+    if (this.queryOptions.select) {
+      queryParams = queryParams.replace(
+        /\$select=([^&]*)/,
+        (match, selectValue) => {
+          return `$select=${selectValue.replace(/%20/g, " ")}`;
+        },
+      );
+    }
+    const expandString = this.buildExpandString(this.expandConfigs);
+    if (expandString) {
+      const separator = queryParams.includes("?") ? "&" : "?";
+      queryParams = `${queryParams}${separator}$expand=${expandString}`;
+    }
+
+    // Handle navigation from RecordBuilder (with record ID)
+    if (
+      this.isNavigate &&
+      this.navigateRecordId &&
+      this.navigateRelation &&
+      this.navigateSourceTableName
+    ) {
+      let path: string;
+      if (this.navigateBaseRelation) {
+        // Navigation from a navigated EntitySet: /sourceTable/baseRelation('recordId')/relation
+        path = `/${this.navigateSourceTableName}/${this.navigateBaseRelation}('${this.navigateRecordId}')/${this.navigateRelation}`;
+      } else {
+        // Normal navigation: /sourceTableName('recordId')/relationName
+        path = `/${this.navigateSourceTableName}('${this.navigateRecordId}')/${this.navigateRelation}`;
+      }
+      // Append query params if any exist
+      return queryParams ? `${path}${queryParams}` : path;
+    }
+
+    // Handle navigation from EntitySet (without record ID)
+    if (
+      this.isNavigate &&
+      !this.navigateRecordId &&
+      this.navigateRelation &&
+      this.navigateSourceTableName
+    ) {
+      // Return the path portion: /sourceTableName/relationName
+      const path = `/${this.navigateSourceTableName}/${this.navigateRelation}`;
+      // Append query params if any exist
+      return queryParams ? `${path}${queryParams}` : path;
+    }
+
+    // Default case: return table name with query params
+    return `/${this.tableName}${queryParams}`;
+  }
+
+  getRequestConfig(): { method: string; url: string; body?: any } {
+    // 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;
+    }
+
+    let queryString = buildQuery(queryOptionsWithoutExpand);
+
+    // Build custom expand string
+    const expandString = this.buildExpandString(this.expandConfigs);
+    if (expandString) {
+      const separator = queryString.includes("?") ? "&" : "?";
+      queryString = `${queryString}${separator}$expand=${expandString}`;
+    }
+
+    let url: string;
+
+    // Handle navigation from RecordBuilder (with record ID)
+    if (
+      this.isNavigate &&
+      this.navigateRecordId &&
+      this.navigateRelation &&
+      this.navigateSourceTableName
+    ) {
+      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}`;
+      }
+    } else if (
+      this.isNavigate &&
+      !this.navigateRecordId &&
+      this.navigateRelation &&
+      this.navigateSourceTableName
+    ) {
+      // Handle navigation from EntitySet (without record ID)
+      url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}${queryString}`;
+    } else if (this.isCountMode) {
+      url = `/${this.databaseName}/${this.tableName}/$count${queryString}`;
+    } else {
+      url = `/${this.databaseName}/${this.tableName}${queryString}`;
+    }
+
+    return {
+      method: "GET",
+      url,
+    };
+  }
+}