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

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(",");
+}
+
+

package/src/client/builders/shared-types.ts

@@ -0,0 +1,41 @@
+import type { QueryOptions } from "odata-query";
+import type { ExecutionContext } from "../../types";
+import type { FMTable } from "../../orm/table";
+
+/**
+ * Expand configuration used by both QueryBuilder and RecordBuilder
+ */
+export type ExpandConfig = {
+  relation: string;
+  options?: Partial<QueryOptions<any>>;
+  targetTable?: FMTable<any, any>;
+};
+
+/**
+ * Type to represent expanded relations in return types
+ */
+export type ExpandedRelations = Record<string, { schema: any; selected: any }>;
+
+/**
+ * Navigation context shared between builders
+ */
+export interface NavigationContext {
+  isNavigate?: boolean;
+  navigateRecordId?: string | number;
+  navigateRelation?: string;
+  navigateSourceTableName?: string;
+  navigateBaseRelation?: string;
+  navigateBasePath?: string;
+}
+
+/**
+ * Common builder configuration
+ */
+export interface BuilderConfig<Occ extends FMTable<any, any> | undefined> {
+  occurrence?: Occ;
+  tableName: string;
+  databaseName: string;
+  context: ExecutionContext;
+  databaseUseEntityIds?: boolean;
+}
+

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

@@ -0,0 +1,87 @@
+import type { ExecutionContext } from "../../types";
+import { getAcceptHeader } from "../../types";
+import type { FMTable } from "../../orm/table";
+import {
+  getTableName,
+  getTableId as getTableIdHelper,
+  isUsingEntityIds,
+} from "../../orm/table";
+import type { FFetchOptions } from "@fetchkit/ffetch";
+import type { ExecuteOptions } from "../../types";
+
+/**
+ * Resolves table identifier based on entity ID settings.
+ * Used by both QueryBuilder and RecordBuilder.
+ */
+export function resolveTableId(
+  table: FMTable<any, any> | undefined,
+  fallbackTableName: string,
+  context: ExecutionContext,
+  useEntityIdsOverride?: boolean,
+): string {
+  if (!table) {
+    return fallbackTableName;
+  }
+
+  const contextDefault = context._getUseEntityIds?.() ?? false;
+  const shouldUseIds = useEntityIdsOverride ?? contextDefault;
+
+  if (shouldUseIds) {
+    if (!isUsingEntityIds(table)) {
+      throw new Error(
+        `useEntityIds is true but table "${getTableName(table)}" does not have entity IDs configured`,
+      );
+    }
+    return getTableIdHelper(table);
+  }
+
+  return getTableName(table);
+}
+
+/**
+ * Merges database-level useEntityIds with per-request options.
+ */
+export function mergeEntityIdOptions<T extends Record<string, any>>(
+  options: T | undefined,
+  databaseDefault: boolean,
+): T & { useEntityIds?: boolean } {
+  return {
+    ...options,
+    useEntityIds: (options as any)?.useEntityIds ?? databaseDefault,
+  } as T & { useEntityIds?: boolean };
+}
+
+/**
+ * Type-safe helper for merging execute options with entity ID settings
+ */
+export function mergeExecuteOptions(
+  options: (RequestInit & FFetchOptions & ExecuteOptions) | undefined,
+  databaseUseEntityIds: boolean,
+): RequestInit & FFetchOptions & { useEntityIds?: boolean } {
+  return mergeEntityIdOptions(options, databaseUseEntityIds);
+}
+
+/**
+ * Creates an OData Request object with proper headers.
+ * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+ *
+ * @param baseUrl - Base URL for the request
+ * @param config - Request configuration with method and url
+ * @param options - Optional execution options
+ * @returns Request object ready to use
+ */
+export function createODataRequest(
+  baseUrl: string,
+  config: { method: string; url: string },
+  options?: { includeODataAnnotations?: boolean },
+): Request {
+  const fullUrl = `${baseUrl}${config.url}`;
+
+  return new Request(fullUrl, {
+    method: config.method,
+    headers: {
+      "Content-Type": "application/json",
+      Accept: getAcceptHeader(options?.includeODataAnnotations),
+    },
+  });
+}