@proofkit/fmodata 0.1.0-alpha.12 → 0.1.0-alpha.14

package/src/client/query-builder.ts

@@ -1,1447 +1,8 @@
-import { QueryOptions } from "odata-query";
-import buildQuery from "odata-query";
-import type {
-  ExecutionContext,
-  ExecutableBuilder,
-  WithSystemFields,
-  Result,
-  InferSchemaType,
-  ExecuteOptions,
-  ConditionallyWithODataAnnotations,
-  ExtractSchemaFromOccurrence,
-} from "../types";
-import { getAcceptHeader } 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 { RecordCountMismatchError } from "../errors";
-import { type FFetchOptions } from "@fetchkit/ffetch";
-import type { StandardSchemaV1 } from "@standard-schema/spec";
-import {
-  transformFieldNamesArray,
-  transformFieldName,
-  transformOrderByField,
-  transformResponseFields,
-  getTableIdentifiers,
-} from "../transform";
-import { safeJsonParse } from "./sanitize-json";
-
-/**
- * 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<
-  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 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
-        ? Nav[Name]
-        : TableOccurrence<
-            BaseTable<Record<string, StandardSchemaV1>, any, any, any>,
-            any,
-            any,
-            any
-          >
-      : TableOccurrence<
-          BaseTable<Record<string, StandardSchemaV1>, any, any, any>,
-          any,
-          any,
-          any
-        >
-    : TableOccurrence<
-        BaseTable<Record<string, StandardSchemaV1>, any, any, 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, any, 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
-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>,
-  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 = {},
-> implements
-    ExecutableBuilder<
-      QueryReturnType<T, Selected, SingleMode, IsCount, Expands>
-    >
-{
-  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;
-  private navigateBasePath?: string; // Full base path for chained entity set navigations
-  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,
-    };
-  }
-
-  /**
-   * 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> {
-    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,
-      databaseUseEntityIds: this.databaseUseEntityIds,
-    });
-    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)) {
-      // 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[fieldId] = value[0];
-        } else {
-          // Multiple operators - combine with AND
-          // Create separate conditions for each operator
-          for (const op of value) {
-            andConditions.push({ [fieldId]: 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[fieldId] = value;
-        } else {
-          // Regular object - might be nested filter, pass through
-          result[fieldId] = value;
-        }
-      } else {
-        // Primitive value (shorthand) - pass through
-        result[fieldId] = 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> {
-    // 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;
-  }
-
-  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.
-   * - 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"],
-    baseTable?: BaseTable<any, any, any, any>,
-  ): string {
-    if (!select) return "";
-    const selectFieldsArray = Array.isArray(select) ? select : [select];
-
-    // 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));
-        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,
-        targetBaseTable: targetOccurrence?.baseTable,
-        occurrence: targetOccurrence, // Add occurrence for transformation
-        selectedFields: selectedFields,
-        nestedExpands: undefined, // TODO: Handle nested expands if needed
-      };
-    });
-  }
-
-  /**
-   * 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) {
-      return "";
-    }
-
-    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 relationName;
-        }
-
-        // Build query options for this expand
-        const parts: string[] = [];
-
-        if (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=([^&]+)/);
-          if (filterMatch) {
-            parts.push(`$filter=${filterMatch[1]}`);
-          }
-        }
-
-        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;
-          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 relationName;
-        }
-
-        return `${relationName}(${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];
-
-    // Helper function to get defaultSelect fields from target occurrence
-    const getDefaultSelectFields = (): string[] | undefined => {
-      if (!targetOccurrence) return undefined;
-      const defaultSelect = targetOccurrence.defaultSelect;
-      if (defaultSelect === "schema") {
-        const schema = targetOccurrence.baseTable?.schema;
-        if (schema) {
-          return [...new Set(Object.keys(schema))];
-        }
-      } else if (Array.isArray(defaultSelect)) {
-        return [...new Set(defaultSelect)];
-      }
-      // If "all", return undefined (no select restriction)
-      return undefined;
-    };
-
-    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,
-        databaseUseEntityIds: this.databaseUseEntityIds,
-      });
-
-      // 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 callback didn't provide select, apply defaultSelect from target occurrence
-      if (!expandOptions.select) {
-        const defaultFields = getDefaultSelectFields();
-        if (defaultFields) {
-          expandOptions.select = defaultFields;
-        }
-      }
-
-      // 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 - apply defaultSelect if available
-      const defaultFields = getDefaultSelectFields();
-      if (defaultFields) {
-        this.expandConfigs.push({
-          relation: relation as string,
-          options: { select: defaultFields },
-        });
-      } else {
-        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,
-      databaseUseEntityIds: this.databaseUseEntityIds,
-    });
-    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,
-      databaseUseEntityIds: this.databaseUseEntityIds,
-    });
-    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,
-      databaseUseEntityIds: this.databaseUseEntityIds,
-    });
-    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
-              >[]
-    >
-  > {
-    // Build query without expand (we'll add it manually)
-    const queryOptionsWithoutExpand = { ...this.queryOptions };
-    delete queryOptionsWithoutExpand.expand;
-
-    const mergedOptions = this.mergeExecuteOptions(options);
-
-    // Format select fields before building query
-    if (queryOptionsWithoutExpand.select) {
-      queryOptionsWithoutExpand.select = this.formatSelectFields(
-        queryOptionsWithoutExpand.select,
-        this.occurrence?.baseTable,
-      ) 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 result = await this.context._makeRequest(url, 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;
-          return { data: record as any, error: undefined };
-        } else {
-          const records = resp.value ?? [];
-          const stripped = records.map((record: any) => record);
-          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 };
-        }
-        return { data: validation.data as any, error: undefined };
-      } else {
-        const validation = await validateListResponse<T>(
-          response,
-          schema,
-          selectedFields,
-          expandValidationConfigs,
-        );
-        if (!validation.valid) {
-          return { data: undefined, error: validation.error };
-        }
-        return { data: validation.data as any, error: undefined };
-      }
-    }
-
-    // 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;
-        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;
-          return { data: record as any, error: undefined };
-        } else {
-          const records = resp.value ?? [];
-          const stripped = records.map((record: any) => record);
-          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 };
-        }
-        return { data: validation.data as any, error: undefined };
-      } else {
-        const validation = await validateListResponse<T>(
-          response,
-          schema,
-          selectedFields,
-          expandValidationConfigs,
-        );
-        if (!validation.valid) {
-          return { data: undefined, error: validation.error };
-        }
-        return { data: validation.data 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 };
-      }
-
-      // 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;
-        return { data: record as any, error: undefined };
-      } else {
-        // Handle list response structure
-        const records = resp.value ?? [];
-        return { data: records 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 };
-      }
-      return {
-        data: validation.data as any,
-        error: undefined,
-      };
-    } else {
-      const validation = await validateListResponse<T>(
-        response,
-        schema,
-        selectedFields,
-        expandValidationConfigs,
-      );
-      if (!validation.valid) {
-        return { data: undefined, error: validation.error };
-      }
-      return {
-        data: validation.data as any,
-        error: undefined,
-      };
-    }
-  }
-
-  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,
-        this.occurrence?.baseTable,
-      ) 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
-    ) {
-      let path: string;
-      if (this.navigateBasePath) {
-        // Chained navigation: /basePath/relationName (basePath already includes intermediate segments)
-        path = `/${this.navigateBasePath}/${this.navigateRelation}`;
-      } else {
-        // Single navigation: /sourceTableName/relationName
-        path = `/${this.navigateSourceTableName}/${this.navigateRelation}`;
-      }
-      // Append query params if any exist
-      return queryParams ? `${path}${queryParams}` : path;
-    }
-
-    // Default case: return table ID (respects entity ID settings) with query params
-    const tableId = this.getTableId(this.databaseUseEntityIds);
-    return `/${tableId}${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,
-        this.occurrence?.baseTable,
-      ) 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)
-      if (this.navigateBasePath) {
-        // Chained navigation: /basePath/relationName (basePath already includes intermediate segments)
-        url = `/${this.databaseName}/${this.navigateBasePath}/${this.navigateRelation}${queryString}`;
-      } else {
-        // Single navigation: /sourceTableName/relationName
-        url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}${queryString}`;
-      }
-    } else if (this.isCountMode) {
-      // Use getTableId to respect entity ID settings (for batch operations)
-      const tableId = this.getTableId(this.databaseUseEntityIds);
-      url = `/${this.databaseName}/${tableId}/$count${queryString}`;
-    } else {
-      // Use getTableId to respect entity ID settings (for batch operations)
-      const tableId = this.getTableId(this.databaseUseEntityIds);
-      url = `/${this.databaseName}/${tableId}${queryString}`;
-    }
-
-    return {
-      method: "GET",
-      url,
-    };
-  }
-
-  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: getAcceptHeader(options?.includeODataAnnotations),
-      },
-    });
-  }
-
-  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 (using safeJsonParse to handle FileMaker's invalid JSON with unquoted ? values)
-    let rawData;
-    try {
-      rawData = await safeJsonParse(response);
-    } 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;
-        return { data: record as any, error: undefined };
-      } else {
-        // Handle list response structure
-        const records = resp.value ?? [];
-        return { data: records 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 };
-      }
-
-      return { data: validation.data as any, error: undefined };
-    }
-
-    // List mode
-    const validation = await validateListResponse<T>(
-      transformedData,
-      schema,
-      selectedFields,
-      expandValidationConfigs,
-    );
-
-    if (!validation.valid) {
-      return { data: undefined, error: validation.error };
-    }
-
-    return { data: validation.data as any, error: undefined };
-  }
-}
+// Re-export QueryBuilder and types from the new modular location
+// This maintains backward compatibility for existing imports
+export {
+  QueryBuilder,
+  type TypeSafeOrderBy,
+  type ExpandedRelations,
+  type QueryReturnType,
+} from "./query";