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

package/src/client/builders/expand-builder.ts

@@ -0,0 +1,246 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import buildQuery, { type QueryOptions } from "odata-query";
+import type { InternalLogger } from "../../logger";
+import { FMTable, getBaseTableConfig, getNavigationPaths, getTableName } from "../../orm/table";
+import type { ExpandValidationConfig } from "../../validation";
+import { getDefaultSelectFields } from "./default-select";
+import { formatSelectFields } from "./select-utils";
+import type { ExpandConfig } from "./shared-types";
+
+const FILTER_QUERY_REGEX = /\$filter=([^&]+)/;
+
+/**
+ * Builds OData expand query strings and validation configs.
+ * Handles nested expands recursively and transforms relation names to FMTIDs
+ * when using entity IDs.
+ */
+export class ExpandBuilder {
+  private readonly useEntityIds: boolean;
+  private readonly logger: InternalLogger;
+
+  constructor(useEntityIds: boolean, logger: InternalLogger) {
+    this.useEntityIds = useEntityIds;
+    this.logger = logger;
+  }
+
+  /**
+   * Builds OData $expand query string from expand configurations.
+   */
+  buildExpandString(configs: ExpandConfig[]): string {
+    if (configs.length === 0) {
+      return "";
+    }
+
+    return configs.map((config) => this.buildSingleExpand(config)).join(",");
+  }
+
+  /**
+   * Builds validation configs for expanded navigation properties.
+   */
+  buildValidationConfigs(configs: ExpandConfig[]): ExpandValidationConfig[] {
+    return configs.map((config) => {
+      const targetTable = config.targetTable;
+
+      let targetSchema: Partial<Record<string, StandardSchemaV1>> | undefined;
+      if (targetTable) {
+        const baseTableConfig = getBaseTableConfig(targetTable);
+        const containerFields = baseTableConfig.containerFields || [];
+
+        // Filter out container fields from schema
+        const schema = { ...baseTableConfig.schema };
+        for (const containerField of containerFields) {
+          delete schema[containerField as string];
+        }
+
+        targetSchema = schema;
+      }
+
+      let selectedFields: string[] | undefined;
+      if (config.options?.select) {
+        selectedFields = Array.isArray(config.options.select)
+          ? config.options.select.map(String)
+          : [String(config.options.select)];
+      }
+
+      // Recursively build validation configs for nested expands
+      const nestedExpands = config.nestedExpandConfigs
+        ? this.buildValidationConfigs(config.nestedExpandConfigs)
+        : undefined;
+
+      return {
+        relation: config.relation,
+        targetSchema,
+        targetTable,
+        table: targetTable,
+        selectedFields,
+        nestedExpands,
+      };
+    });
+  }
+
+  /**
+   * Process an expand() call and return the expand config.
+   * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+   *
+   * @param targetTable - The target table to expand to
+   * @param sourceTable - The source table (for validation)
+   * @param callback - Optional callback to configure the expand query
+   * @param builderFactory - Function that creates a QueryBuilder for the target table
+   * @returns ExpandConfig to add to the builder's expandConfigs array
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration, generic Builder type
+  processExpand<TargetTable extends FMTable<any, any>, Builder = any>(
+    targetTable: TargetTable,
+    // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+    sourceTable: FMTable<any, any> | undefined,
+    callback?: (builder: Builder) => Builder,
+    builderFactory?: () => Builder,
+  ): ExpandConfig {
+    // Extract name and validate
+    const relationName = getTableName(targetTable);
+
+    // Runtime validation: Check if relation name is in navigationPaths
+    if (sourceTable) {
+      const navigationPaths = getNavigationPaths(sourceTable);
+      if (navigationPaths && !navigationPaths.includes(relationName)) {
+        this.logger.warn(
+          `Cannot expand to "${relationName}". Valid navigation paths: ${navigationPaths.length > 0 ? navigationPaths.join(", ") : "none"}`,
+        );
+      }
+    }
+
+    if (callback && builderFactory) {
+      // Create a new QueryBuilder for the target table
+      const targetBuilder = builderFactory();
+
+      // Pass to callback and get configured builder
+      const configuredBuilder = callback(targetBuilder);
+
+      // Extract the builder's query options
+      // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any QueryOptions configuration
+      const expandOptions: Partial<QueryOptions<any>> = {
+        // biome-ignore lint/suspicious/noExplicitAny: Type assertion for internal builder property access
+        ...(configuredBuilder as any).queryOptions,
+      };
+
+      // If callback didn't provide select, apply defaultSelect from target table
+      if (!expandOptions.select) {
+        const defaultFields = getDefaultSelectFields(targetTable);
+        if (defaultFields) {
+          expandOptions.select = defaultFields;
+        }
+      }
+
+      // If the configured builder has nested expands, we need to include them
+      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for internal builder property access
+      const nestedExpandConfigs = (configuredBuilder as any).expandConfigs;
+      if (nestedExpandConfigs?.length > 0) {
+        // Build nested expand string from the configured builder's expand configs
+        const nestedExpandString = this.buildExpandString(nestedExpandConfigs);
+        if (nestedExpandString) {
+          // Add nested expand to options
+          // biome-ignore lint/suspicious/noExplicitAny: Type assertion for expand string
+          expandOptions.expand = nestedExpandString as any;
+        }
+      }
+
+      return {
+        relation: relationName,
+        options: expandOptions,
+        targetTable,
+        nestedExpandConfigs: nestedExpandConfigs?.length > 0 ? nestedExpandConfigs : undefined,
+      };
+    }
+    // Simple expand without callback - apply defaultSelect if available
+    const defaultFields = getDefaultSelectFields(targetTable);
+    if (defaultFields) {
+      return {
+        relation: relationName,
+        options: { select: defaultFields },
+        targetTable,
+      };
+    }
+    return {
+      relation: relationName,
+      targetTable,
+    };
+  }
+
+  /**
+   * Builds a single expand string with its options.
+   */
+  private buildSingleExpand(config: ExpandConfig): string {
+    const relationName = this.resolveRelationName(config);
+    const parts = this.buildExpandParts(config);
+
+    if (parts.length === 0) {
+      return relationName;
+    }
+
+    return `${relationName}(${parts.join(";")})`;
+  }
+
+  /**
+   * Resolves relation name, using FMTID if entity IDs are enabled.
+   */
+  private resolveRelationName(config: ExpandConfig): string {
+    if (!this.useEntityIds) {
+      return config.relation;
+    }
+
+    const targetTable = config.targetTable;
+    if (targetTable && FMTable.Symbol.EntityId in targetTable) {
+      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for Symbol property access
+      const tableId = (targetTable as any)[FMTable.Symbol.EntityId] as `FMTID:${string}` | undefined;
+      if (tableId) {
+        return tableId;
+      }
+    }
+
+    return config.relation;
+  }
+
+  /**
+   * Builds expand parts (select, filter, orderBy, etc.) for a single expand.
+   */
+  private buildExpandParts(config: ExpandConfig): string[] {
+    if (!config.options || Object.keys(config.options).length === 0) {
+      return [];
+    }
+
+    const parts: string[] = [];
+    const opts = config.options;
+
+    if (opts.select) {
+      const selectArray = Array.isArray(opts.select) ? opts.select.map(String) : [String(opts.select)];
+      const selectFields = formatSelectFields(selectArray, config.targetTable, this.useEntityIds);
+      parts.push(`$select=${selectFields}`);
+    }
+
+    if (opts.filter) {
+      const filterQuery = buildQuery({ filter: opts.filter });
+      const match = filterQuery.match(FILTER_QUERY_REGEX);
+      if (match) {
+        parts.push(`$filter=${match[1]}`);
+      }
+    }
+
+    if (opts.orderBy) {
+      const orderByValue = Array.isArray(opts.orderBy) ? opts.orderBy.join(",") : String(opts.orderBy);
+      parts.push(`$orderby=${orderByValue}`);
+    }
+
+    if (opts.top !== undefined) {
+      parts.push(`$top=${opts.top}`);
+    }
+    if (opts.skip !== undefined) {
+      parts.push(`$skip=${opts.skip}`);
+    }
+
+    if (opts.expand && typeof opts.expand === "string") {
+      parts.push(`$expand=${opts.expand}`);
+    }
+
+    return parts;
+  }
+}

package/src/client/builders/index.ts

@@ -0,0 +1,11 @@
+// Re-export all shared builder utilities
+/** biome-ignore-all lint/performance/noBarrelFile: Re-exporting all builder utilities */
+
+export * from "./default-select";
+export * from "./expand-builder";
+export * from "./query-string-builder";
+export * from "./response-processor";
+export * from "./select-mixin";
+export * from "./select-utils";
+export * from "./shared-types";
+export * from "./table-utils";

package/src/client/builders/query-string-builder.ts

@@ -0,0 +1,46 @@
+import type { InternalLogger } from "../../logger";
+import type { FMTable } from "../../orm/table";
+import { ExpandBuilder } from "./expand-builder";
+import { formatSelectFields } from "./select-utils";
+import type { ExpandConfig } from "./shared-types";
+
+/**
+ * Builds OData query string for $select and $expand parameters.
+ * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+ *
+ * @param config - Configuration object
+ * @returns Query string starting with ? or empty string if no parameters
+ */
+export function buildSelectExpandQueryString(config: {
+  selectedFields?: string[];
+  expandConfigs: ExpandConfig[];
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  table?: FMTable<any, any>;
+  useEntityIds: boolean;
+  logger: InternalLogger;
+  includeSpecialColumns?: boolean;
+}): string {
+  const parts: string[] = [];
+  const expandBuilder = new ExpandBuilder(config.useEntityIds, config.logger);
+
+  // Build $select
+  if (config.selectedFields && config.selectedFields.length > 0) {
+    // Important: do NOT implicitly add system columns (ROWID/ROWMODID) here.
+    // - `includeSpecialColumns` controls the Prefer header + response parsing, but should not
+    //   mutate/expand an explicit `$select` (e.g. when the user calls `.select({ ... })`).
+    // - If system columns are desired with `.select()`, they must be explicitly included via
+    //   the `systemColumns` argument, which will already have added them to `selectedFields`.
+    const selectString = formatSelectFields(config.selectedFields, config.table, config.useEntityIds);
+    if (selectString) {
+      parts.push(`$select=${selectString}`);
+    }
+  }
+
+  // Build $expand
+  const expandString = expandBuilder.buildExpandString(config.expandConfigs);
+  if (expandString) {
+    parts.push(`$expand=${expandString}`);
+  }
+
+  return parts.length > 0 ? `?${parts.join("&")}` : "";
+}

package/src/client/builders/response-processor.ts

@@ -0,0 +1,279 @@
+import { RecordCountMismatchError } from "../../errors";
+import type { InternalLogger } from "../../logger";
+import type { FMTable } from "../../orm/table";
+import { getBaseTableConfig } from "../../orm/table";
+import { transformResponseFields } from "../../transform";
+import type { Result } from "../../types";
+import type { ExpandValidationConfig } from "../../validation";
+import { validateListResponse, validateSingleResponse } from "../../validation";
+import { ExpandBuilder } from "./expand-builder";
+import type { ExpandConfig } from "./shared-types";
+
+export interface ProcessResponseConfig {
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  table?: FMTable<any, any>;
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic schema shape from table configuration
+  schema?: Record<string, any>;
+  singleMode: "exact" | "maybe" | false;
+  selectedFields?: string[];
+  expandValidationConfigs?: ExpandValidationConfig[];
+  skipValidation?: boolean;
+  useEntityIds?: boolean;
+  includeSpecialColumns?: boolean;
+  // Mapping from field names to output keys (for renamed fields in select)
+  fieldMapping?: Record<string, string>;
+}
+
+/**
+ * Processes OData response with transformation and validation.
+ * Shared by QueryBuilder and RecordBuilder.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API
+export async function processODataResponse<T>(rawResponse: any, config: ProcessResponseConfig): Promise<Result<T>> {
+  const {
+    table,
+    schema,
+    singleMode,
+    selectedFields,
+    expandValidationConfigs,
+    skipValidation,
+    useEntityIds,
+    includeSpecialColumns,
+    fieldMapping,
+  } = config;
+
+  // Transform field IDs back to names if using entity IDs
+  let response = rawResponse;
+  if (table && useEntityIds) {
+    response = transformResponseFields(response, table, expandValidationConfigs);
+  }
+
+  // Fast path: skip validation
+  if (skipValidation) {
+    const result = extractRecords(response, singleMode);
+    // Rename fields AFTER extraction (but before returning)
+    if (result.data && fieldMapping && Object.keys(fieldMapping).length > 0) {
+      if (result.error) {
+        return { data: undefined, error: result.error } as Result<T>;
+      }
+      return {
+        data: renameFieldsInResponse(result.data, fieldMapping) as T,
+        error: undefined,
+      };
+    }
+    return result as Result<T>;
+  }
+
+  // Validation path
+  // Note: Special columns are excluded when using QueryBuilder.single() method,
+  // but included for RecordBuilder.get() method (both use singleMode: "exact")
+  // The exclusion is handled in QueryBuilder's processQueryResponse, not here
+  if (singleMode !== false) {
+    // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape
+    const validation = await validateSingleResponse<any>(
+      response,
+      schema,
+      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic type parameter
+      selectedFields as any,
+      expandValidationConfigs,
+      singleMode,
+      includeSpecialColumns,
+    );
+
+    if (!validation.valid) {
+      return { data: undefined, error: validation.error };
+    }
+
+    // Rename fields AFTER validation completes
+    if (fieldMapping && Object.keys(fieldMapping).length > 0) {
+      return {
+        data: renameFieldsInResponse(validation.data, fieldMapping) as T,
+        error: undefined,
+      };
+    }
+
+    return { data: validation.data as T, error: undefined };
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape
+  const validation = await validateListResponse<any>(
+    response,
+    schema,
+    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic type parameter
+    selectedFields as any,
+    expandValidationConfigs,
+    includeSpecialColumns,
+  );
+
+  if (!validation.valid) {
+    return { data: undefined, error: validation.error };
+  }
+
+  // Rename fields AFTER validation completes
+  if (fieldMapping && Object.keys(fieldMapping).length > 0) {
+    return {
+      data: renameFieldsInResponse(validation.data, fieldMapping) as T,
+      error: undefined,
+    };
+  }
+
+  return { data: validation.data as T, error: undefined };
+}
+
+/**
+ * Extracts records from response without validation.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API
+function extractRecords<T>(response: any, singleMode: "exact" | "maybe" | false): Result<T> {
+  if (singleMode === false) {
+    const records = response.value ?? [];
+    return { data: records as T, error: undefined };
+  }
+
+  const records = response.value ?? [response];
+  const count = Array.isArray(records) ? records.length : 1;
+
+  if (count > 1) {
+    return {
+      data: undefined,
+      error: new RecordCountMismatchError(singleMode === "exact" ? "one" : "at-most-one", count),
+    };
+  }
+
+  if (count === 0) {
+    if (singleMode === "exact") {
+      return { data: undefined, error: new RecordCountMismatchError("one", 0) };
+    }
+    return { data: null as T, error: undefined };
+  }
+
+  const record = Array.isArray(records) ? records[0] : records;
+  return { data: record as T, error: undefined };
+}
+
+/**
+ * Gets schema from a table occurrence, excluding container fields.
+ * Container fields are never returned in regular responses (only via getSingleField).
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration, dynamic schema shape
+export function getSchemaFromTable(table: FMTable<any, any> | undefined): Record<string, any> | undefined {
+  if (!table) {
+    return undefined;
+  }
+  const baseTableConfig = getBaseTableConfig(table);
+  const containerFields = baseTableConfig.containerFields || [];
+
+  // Filter out container fields from schema
+  const schema = { ...baseTableConfig.schema };
+  for (const containerField of containerFields) {
+    delete schema[containerField as string];
+  }
+
+  return schema;
+}
+
+/**
+ * Renames fields in response data according to the field mapping.
+ * Used when select() is called with renamed fields (e.g., { userEmail: users.email }).
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic response data transformation
+function renameFieldsInResponse(data: any, fieldMapping: Record<string, string>): any {
+  if (!data || typeof data !== "object") {
+    return data;
+  }
+
+  // Handle array responses
+  if (Array.isArray(data)) {
+    return data.map((item) => renameFieldsInResponse(item, fieldMapping));
+  }
+
+  // Handle OData list response structure
+  if ("value" in data && Array.isArray(data.value)) {
+    return {
+      ...data,
+      // biome-ignore lint/suspicious/noExplicitAny: Dynamic record transformation
+      value: data.value.map((item: any) => renameFieldsInResponse(item, fieldMapping)),
+    };
+  }
+
+  // Handle single record
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic field transformation
+  const renamed: Record<string, any> = {};
+  for (const [key, value] of Object.entries(data)) {
+    // Check if this field should be renamed
+    const outputKey = fieldMapping[key];
+    if (outputKey) {
+      renamed[outputKey] = value;
+    } else {
+      renamed[key] = value;
+    }
+  }
+  return renamed;
+}
+
+/**
+ * Processes query response with expand configs.
+ * This is a convenience wrapper that builds validation configs from expand configs.
+ */
+export async function processQueryResponse<T>(
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API
+  response: any,
+  config: {
+    // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+    occurrence?: FMTable<any, any>;
+    singleMode: "exact" | "maybe" | false;
+    queryOptions: { select?: (keyof T)[] | string[] };
+    expandConfigs: ExpandConfig[];
+    skipValidation?: boolean;
+    useEntityIds?: boolean;
+    includeSpecialColumns?: boolean;
+    // Mapping from field names to output keys (for renamed fields in select)
+    fieldMapping?: Record<string, string>;
+    logger: InternalLogger;
+  },
+  // biome-ignore lint/suspicious/noExplicitAny: Generic return type for interface compliance
+): Promise<Result<any>> {
+  const {
+    occurrence,
+    singleMode,
+    queryOptions,
+    expandConfigs,
+    skipValidation,
+    useEntityIds,
+    includeSpecialColumns,
+    fieldMapping,
+    logger,
+  } = config;
+
+  const expandBuilder = new ExpandBuilder(useEntityIds ?? false, logger);
+  const expandValidationConfigs = expandBuilder.buildValidationConfigs(expandConfigs);
+
+  let selectedFields: string[] | undefined;
+  if (queryOptions.select) {
+    selectedFields = Array.isArray(queryOptions.select)
+      ? queryOptions.select.map(String)
+      : [String(queryOptions.select)];
+  }
+
+  // Process the response first
+  let processedResponse = await processODataResponse(response, {
+    table: occurrence,
+    schema: getSchemaFromTable(occurrence),
+    singleMode,
+    selectedFields,
+    expandValidationConfigs,
+    skipValidation,
+    useEntityIds,
+    includeSpecialColumns,
+  });
+
+  // Rename fields if field mapping is provided (for renamed fields in select)
+  if (processedResponse.data && fieldMapping && Object.keys(fieldMapping).length > 0) {
+    processedResponse = {
+      ...processedResponse,
+      data: renameFieldsInResponse(processedResponse.data, fieldMapping),
+    };
+  }
+
+  return processedResponse;
+}

package/src/client/builders/select-mixin.ts

@@ -0,0 +1,65 @@
+import type { InternalLogger } from "../../logger";
+import { type Column, isColumn } from "../../orm/column";
+
+/**
+ * Utility function for processing select() calls.
+ * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+ *
+ * @param fields - Field names or Column references
+ * @returns Object with selectedFields array
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+export function processSelectFields(...fields: (string | Column<any, any, string>)[]): { selectedFields: string[] } {
+  const fieldNames = fields.map((field) => {
+    if (isColumn(field)) {
+      return field.fieldName as string;
+    }
+    return String(field);
+  });
+  return { selectedFields: [...new Set(fieldNames)] };
+}
+
+/**
+ * Processes select() calls with field renaming support.
+ * Validates columns belong to the correct table and builds field mapping for renamed fields.
+ * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+ *
+ * @param fields - Object mapping output keys to column references
+ * @param tableName - Expected table name for validation
+ * @returns Object with selectedFields array and fieldMapping for renamed fields
+ */
+export function processSelectWithRenames<TTableName extends string>(
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+  fields: Record<string, Column<any, any, TTableName>>,
+  tableName: string,
+  logger: InternalLogger,
+): { selectedFields: string[]; fieldMapping: Record<string, string> } {
+  const selectedFields: string[] = [];
+  const fieldMapping: Record<string, string> = {};
+
+  for (const [outputKey, column] of Object.entries(fields)) {
+    if (!isColumn(column)) {
+      throw new Error(`select() expects column references, but got: ${typeof column}`);
+    }
+
+    // Warn (not throw) on table mismatch for consistency
+    if (column.tableName !== tableName) {
+      logger.warn(
+        `Column ${column.toString()} is from table "${column.tableName}", but query is for table "${tableName}"`,
+      );
+    }
+
+    const fieldName = column.fieldName;
+    selectedFields.push(fieldName);
+
+    // Build mapping from field name to output key (only if renamed)
+    if (fieldName !== outputKey) {
+      fieldMapping[fieldName] = outputKey;
+    }
+  }
+
+  return {
+    selectedFields,
+    fieldMapping: Object.keys(fieldMapping).length > 0 ? fieldMapping : {},
+  };
+}