@proofkit/fmodata 0.1.0-alpha.13 → 0.1.0-alpha.15

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

@@ -0,0 +1,236 @@
+import { QueryOptions } from "odata-query";
+import buildQuery from "odata-query";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { FMTable } from "../../orm/table";
+import {
+  getBaseTableConfig,
+  getTableName,
+  getNavigationPaths,
+} from "../../orm/table";
+import type { ExpandValidationConfig } from "../../validation";
+import type { ExpandConfig } from "./shared-types";
+import { formatSelectFields } from "./select-utils";
+import { getDefaultSelectFields } from "./default-select";
+
+/**
+ * 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 {
+  constructor(private useEntityIds: boolean) {}
+
+  /**
+   * 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: 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;
+      }
+
+      const selectedFields = config.options?.select
+        ? Array.isArray(config.options.select)
+          ? config.options.select.map(String)
+          : [String(config.options.select)]
+        : undefined;
+
+      return {
+        relation: config.relation,
+        targetSchema,
+        targetTable,
+        table: targetTable,
+        selectedFields,
+        nestedExpands: undefined,
+      };
+    });
+  }
+
+  /**
+   * 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
+   */
+  processExpand<TargetTable extends FMTable<any, any>, Builder = any>(
+    targetTable: TargetTable,
+    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)) {
+        console.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
+      const expandOptions: Partial<QueryOptions<any>> = {
+        ...(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
+      if ((configuredBuilder as any).expandConfigs?.length > 0) {
+        // Build nested expand string from the configured builder's expand configs
+        const nestedExpandString = this.buildExpandString(
+          (configuredBuilder as any).expandConfigs,
+        );
+        if (nestedExpandString) {
+          // Add nested expand to options
+          expandOptions.expand = nestedExpandString as any;
+        }
+      }
+
+      return {
+        relation: relationName,
+        options: expandOptions,
+        targetTable,
+      };
+    } else {
+      // Simple expand without callback - apply defaultSelect if available
+      const defaultFields = getDefaultSelectFields(targetTable);
+      if (defaultFields) {
+        return {
+          relation: relationName,
+          options: { select: defaultFields },
+          targetTable,
+        };
+      } else {
+        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) {
+      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=([^&]+)/);
+      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) {
+      if (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
+export * from "./shared-types";
+export * from "./table-utils";
+export * from "./select-utils";
+export * from "./select-mixin";
+export * from "./expand-builder";
+export * from "./response-processor";
+export * from "./default-select";
+export * from "./query-string-builder";
+
+

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

@@ -0,0 +1,41 @@
+import type { FMTable } from "../../orm/table";
+import { ExpandBuilder } from "./expand-builder";
+import type { ExpandConfig } from "./shared-types";
+import { formatSelectFields } from "./select-utils";
+
+/**
+ * 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[];
+  table?: FMTable<any, any>;
+  useEntityIds: boolean;
+}): string {
+  const parts: string[] = [];
+  const expandBuilder = new ExpandBuilder(config.useEntityIds);
+
+  // Build $select
+  if (config.selectedFields && config.selectedFields.length > 0) {
+    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,273 @@
+import type { FMTable } from "../../orm/table";
+import type { Result } from "../../types";
+import type { ExpandValidationConfig } from "../../validation";
+import { validateSingleResponse, validateListResponse } from "../../validation";
+import { transformResponseFields } from "../../transform";
+import { RecordCountMismatchError } from "../../errors";
+import { getBaseTableConfig } from "../../orm/table";
+import { ExpandBuilder } from "./expand-builder";
+import type { ExpandConfig } from "./shared-types";
+
+export interface ProcessResponseConfig {
+  table?: FMTable<any, any>;
+  schema?: Record<string, any>;
+  singleMode: "exact" | "maybe" | false;
+  selectedFields?: string[];
+  expandValidationConfigs?: ExpandValidationConfig[];
+  skipValidation?: boolean;
+  useEntityIds?: 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.
+ */
+export async function processODataResponse<T>(
+  rawResponse: any,
+  config: ProcessResponseConfig,
+): Promise<Result<T>> {
+  const {
+    table,
+    schema,
+    singleMode,
+    selectedFields,
+    expandValidationConfigs,
+    skipValidation,
+    useEntityIds,
+    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
+  if (singleMode !== false) {
+    const validation = await validateSingleResponse<any>(
+      response,
+      schema,
+      selectedFields as any,
+      expandValidationConfigs,
+      singleMode,
+    );
+
+    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 };
+  }
+
+  const validation = await validateListResponse<any>(
+    response,
+    schema,
+    selectedFields as any,
+    expandValidationConfigs,
+  );
+
+  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.
+ */
+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).
+ */
+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 }).
+ */
+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,
+      value: data.value.map((item: any) =>
+        renameFieldsInResponse(item, fieldMapping),
+      ),
+    };
+  }
+
+  // Handle single record
+  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>(
+  response: any,
+  config: {
+    occurrence?: FMTable<any, any>;
+    singleMode: "exact" | "maybe" | false;
+    queryOptions: { select?: (keyof T)[] | string[] };
+    expandConfigs: ExpandConfig[];
+    skipValidation?: boolean;
+    useEntityIds?: boolean;
+    // Mapping from field names to output keys (for renamed fields in select)
+    fieldMapping?: Record<string, string>;
+  },
+): Promise<Result<any>> {
+  const {
+    occurrence,
+    singleMode,
+    queryOptions,
+    expandConfigs,
+    skipValidation,
+    useEntityIds,
+    fieldMapping,
+  } = config;
+
+  const expandBuilder = new ExpandBuilder(useEntityIds ?? false);
+  const expandValidationConfigs =
+    expandBuilder.buildValidationConfigs(expandConfigs);
+
+  const selectedFields = queryOptions.select
+    ? Array.isArray(queryOptions.select)
+      ? queryOptions.select.map(String)
+      : [String(queryOptions.select)]
+    : undefined;
+
+  // Process the response first
+  let processedResponse = await processODataResponse(response, {
+    table: occurrence,
+    schema: getSchemaFromTable(occurrence),
+    singleMode,
+    selectedFields,
+    expandValidationConfigs,
+    skipValidation,
+    useEntityIds,
+  });
+
+  // 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,74 @@
+import { isColumn, type Column } 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
+ */
+export function processSelectFields(
+  ...fields: (string | Column<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>(
+  fields: Record<string, Column<any, TTableName>>,
+  tableName: string,
+): { 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) {
+      console.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 : {},
+  };
+}
+
+/**
+ * Legacy class name for backward compatibility.
+ * @deprecated Use processSelectFields function instead
+ */
+export class SelectMixin {
+  static processSelect = processSelectFields;
+}
+

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

@@ -0,0 +1,34 @@
+import type { FMTable } from "../../orm/table";
+import { transformFieldNamesArray } from "../../transform";
+
+/**
+ * Formats select fields for use in OData query strings.
+ * - Transforms field names to FMFIDs if using entity IDs
+ * - Wraps "id" fields in double quotes (OData reserved)
+ * - URL-encodes special characters but preserves spaces
+ */
+export function formatSelectFields(
+  select: string[] | readonly string[] | undefined,
+  table?: FMTable<any, any>,
+  useEntityIds?: boolean,
+): string {
+  if (!select || select.length === 0) return "";
+
+  const selectArray = Array.isArray(select) ? select : [select];
+
+  // Transform to field IDs if using entity IDs
+  const transformedFields =
+    table && useEntityIds
+      ? transformFieldNamesArray(selectArray.map(String), table)
+      : selectArray.map(String);
+
+  return transformedFields
+    .map((field) => {
+      if (field === "id") return `"id"`;
+      const encoded = encodeURIComponent(field);
+      return encoded.replace(/%20/g, " ");
+    })
+    .join(",");
+}
+
+