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

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

@@ -0,0 +1,244 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { QueryOptions } from "odata-query";
+import type { FMTable } from "../../orm/table";
+import type { Result } from "../../types";
+import { RecordCountMismatchError } from "../../errors";
+import { transformResponseFields } from "../../transform";
+import { validateListResponse, validateSingleResponse } from "../../validation";
+import type { ExpandValidationConfig } from "../../validation";
+import type { ExpandConfig } from "./expand-builder";
+import { FMTable as FMTableClass } from "../../orm/table";
+
+/**
+ * Configuration for processing query responses
+ */
+export interface ProcessQueryResponseConfig<T> {
+  occurrence?: FMTable<any, any>;
+  singleMode: "exact" | "maybe" | false;
+  queryOptions: Partial<QueryOptions<T>>;
+  expandConfigs: ExpandConfig[];
+  skipValidation?: boolean;
+  useEntityIds?: boolean;
+  // Mapping from field names to output keys (for renamed fields in select)
+  fieldMapping?: Record<string, string>;
+}
+
+/**
+ * Builds expand validation configs from internal expand configurations.
+ * These are used to validate expanded navigation properties.
+ */
+function buildExpandValidationConfigs(
+  configs: ExpandConfig[],
+): ExpandValidationConfig[] {
+  return configs.map((config) => {
+    // Get target table/occurrence from config (stored during expand call)
+    const targetTable = config.targetTable;
+
+    // Extract schema from target table/occurrence
+    let targetSchema: Record<string, StandardSchemaV1> | undefined;
+    if (targetTable) {
+      const tableSchema = (targetTable as any)[FMTableClass.Symbol.Schema];
+      if (tableSchema) {
+        const zodSchema = tableSchema["~standard"]?.schema;
+        if (
+          zodSchema &&
+          typeof zodSchema === "object" &&
+          "shape" in zodSchema
+        ) {
+          targetSchema = zodSchema.shape as Record<string, StandardSchemaV1>;
+        }
+      }
+    }
+
+    // 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,
+      targetTable: targetTable,
+      table: targetTable, // For transformation
+      selectedFields: selectedFields,
+      nestedExpands: undefined, // TODO: Handle nested expands if needed
+    };
+  });
+}
+
+/**
+ * Extracts records from response data without validation.
+ * Handles both single and list responses.
+ */
+function extractRecords(
+  data: any,
+  singleMode: "exact" | "maybe" | false,
+): Result<any> {
+  const resp = data as any;
+  if (singleMode !== false) {
+    const records = resp.value ?? [resp];
+    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 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 };
+  }
+}
+
+/**
+ * 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 a query response by transforming field IDs and validating the data.
+ * This function consolidates the response processing logic that was duplicated
+ * across multiple navigation branches in QueryBuilder.execute().
+ */
+export async function processQueryResponse<T>(
+  response: any,
+  config: ProcessQueryResponseConfig<T>,
+): Promise<Result<any>> {
+  const { occurrence, singleMode, skipValidation, useEntityIds, fieldMapping } =
+    config;
+
+  // Transform response if needed
+  let data = response;
+  if (occurrence && useEntityIds) {
+    const expandValidationConfigs = buildExpandValidationConfigs(
+      config.expandConfigs,
+    );
+    data = transformResponseFields(
+      response,
+      occurrence,
+      expandValidationConfigs,
+    );
+  }
+
+  // Skip validation path
+  if (skipValidation) {
+    const result = extractRecords(data, singleMode);
+    // Rename fields AFTER extraction (but before returning)
+    if (result.data && fieldMapping && Object.keys(fieldMapping).length > 0) {
+      return {
+        ...result,
+        data: renameFieldsInResponse(result.data, fieldMapping),
+      };
+    }
+    return result;
+  }
+
+  // Validation path
+  // Get schema from occurrence if available
+  let schema: Record<string, StandardSchemaV1> | undefined;
+  if (occurrence) {
+    const tableSchema = (occurrence as any)[FMTableClass.Symbol.Schema];
+    if (tableSchema) {
+      const zodSchema = tableSchema["~standard"]?.schema;
+      if (zodSchema && typeof zodSchema === "object" && "shape" in zodSchema) {
+        schema = zodSchema.shape as Record<string, StandardSchemaV1>;
+      }
+    }
+  }
+
+  const selectedFields = config.queryOptions.select
+    ? ((Array.isArray(config.queryOptions.select)
+        ? config.queryOptions.select.map((f) => String(f))
+        : [String(config.queryOptions.select)]) as (keyof T)[])
+    : undefined;
+  const expandValidationConfigs = buildExpandValidationConfigs(
+    config.expandConfigs,
+  );
+
+  // Validate with original field names
+  const validationResult =
+    singleMode !== false
+      ? await validateSingleResponse(
+          data,
+          schema,
+          selectedFields as string[] | undefined,
+          expandValidationConfigs,
+          singleMode,
+        )
+      : await validateListResponse(
+          data,
+          schema,
+          selectedFields as string[] | undefined,
+          expandValidationConfigs,
+        );
+
+  if (!validationResult.valid) {
+    return { data: undefined, error: validationResult.error };
+  }
+
+  // Rename fields AFTER validation completes
+  if (fieldMapping && Object.keys(fieldMapping).length > 0) {
+    return {
+      data: renameFieldsInResponse(validationResult.data, fieldMapping),
+      error: undefined,
+    };
+  }
+
+  return { data: validationResult.data as any, error: undefined };
+}

package/src/client/query/types.ts

@@ -0,0 +1,102 @@
+import type { Column } from "../../orm/column";
+
+/**
+ * Type-safe orderBy type that provides better DX than odata-query's default.
+ *
+ * Supported forms:
+ * - `keyof T` - single field name (defaults to ascending)
+ * - `[keyof T, 'asc' | 'desc']` - single field with explicit direction
+ * - `Array<[keyof T, 'asc' | 'desc']>` - multiple fields with directions
+ *
+ * This type intentionally EXCLUDES `Array<keyof T>` to avoid ambiguity
+ * between [field1, field2] and [field, direction].
+ */
+export type TypeSafeOrderBy<T> =
+  | (keyof T & string) // Single field name
+  | [keyof T & string, "asc" | "desc"] // Single field with direction
+  | Array<[keyof T & string, "asc" | "desc"]>; // Multiple fields with directions
+
+// Internal type for expand configuration
+export type ExpandConfig = {
+  relation: string;
+  options?: Partial<import("odata-query").QueryOptions<any>>;
+  targetTable?: import("../../orm/table").FMTable<any, any>;
+};
+
+// Type to represent expanded relations
+export type ExpandedRelations = Record<string, { schema: any; selected: any }>;
+
+/**
+ * Extract the value type from a Column.
+ * This uses the phantom type stored in Column to get the actual value type.
+ */
+type ExtractColumnType<C> = C extends Column<infer T, any> ? T : never;
+
+/**
+ * Map a select object to its return type.
+ * For each key in the select object, extract the type from the corresponding Column.
+ */
+type MapSelectToReturnType<
+  TSelect extends Record<string, Column<any, any>>,
+  TSchema extends Record<string, any>,
+> = {
+  [K in keyof TSelect]: ExtractColumnType<TSelect[K]>;
+};
+
+export type QueryReturnType<
+  T extends Record<string, any>,
+  Selected extends keyof T | Record<string, Column<any, any>>,
+  SingleMode extends "exact" | "maybe" | false,
+  IsCount extends boolean,
+  Expands extends ExpandedRelations,
+> = IsCount extends true
+  ? number
+  : // Use tuple wrapping [Selected] extends [...] to prevent distribution over unions
+    [Selected] extends [Record<string, Column<any, any>>]
+    ? SingleMode extends "exact"
+      ? MapSelectToReturnType<Selected, T> & {
+          [K in keyof Expands]: Pick<
+            Expands[K]["schema"],
+            Expands[K]["selected"]
+          >[];
+        }
+      : SingleMode extends "maybe"
+        ?
+            | (MapSelectToReturnType<Selected, T> & {
+                [K in keyof Expands]: Pick<
+                  Expands[K]["schema"],
+                  Expands[K]["selected"]
+                >[];
+              })
+            | null
+        : (MapSelectToReturnType<Selected, T> & {
+            [K in keyof Expands]: Pick<
+              Expands[K]["schema"],
+              Expands[K]["selected"]
+            >[];
+          })[]
+    : // Use tuple wrapping to prevent distribution over union of keys
+      [Selected] extends [keyof T]
+      ? 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"]
+              >[];
+            })[]
+      : never;

package/src/client/query/url-builder.ts

@@ -0,0 +1,179 @@
+import type { FMTable } from "../../orm/table";
+import { getTableName } from "../../orm/table";
+import { resolveTableId } from "../builders/table-utils";
+import type { ExecutionContext } from "../../types";
+
+/**
+ * Configuration for navigation from RecordBuilder or EntitySet
+ */
+export interface NavigationConfig {
+  recordId?: string | number;
+  relation: string;
+  sourceTableName: string;
+  baseRelation?: string; // For chained navigations from navigated EntitySets
+  basePath?: string; // Full base path for chained entity set navigations
+}
+
+/**
+ * Builds OData query URLs for different navigation modes.
+ * Handles:
+ * - Record navigation: /database/sourceTable('recordId')/relation
+ * - Entity set navigation: /database/sourceTable/relation
+ * - Count endpoint: /database/tableId/$count
+ * - Standard queries: /database/tableId
+ */
+export class QueryUrlBuilder {
+  constructor(
+    private databaseName: string,
+    private occurrence: FMTable<any, any>,
+    private context: ExecutionContext,
+  ) {}
+
+  /**
+   * Builds the full URL for a query request.
+   *
+   * @param queryString - The OData query string (e.g., "?$filter=...&$select=...")
+   * @param options - Options including whether this is a count query, useEntityIds override, and navigation config
+   */
+  build(
+    queryString: string,
+    options: {
+      isCount?: boolean;
+      useEntityIds?: boolean;
+      navigation?: NavigationConfig;
+    },
+  ): string {
+    const tableId = resolveTableId(
+      this.occurrence,
+      getTableName(this.occurrence),
+      this.context,
+      options.useEntityIds,
+    );
+
+    const navigation = options.navigation;
+    if (navigation?.recordId && navigation?.relation) {
+      return this.buildRecordNavigation(queryString, tableId, navigation);
+    }
+    if (navigation?.relation) {
+      return this.buildEntitySetNavigation(queryString, tableId, navigation);
+    }
+    if (options.isCount) {
+      return `/${this.databaseName}/${tableId}/$count${queryString}`;
+    }
+    return `/${this.databaseName}/${tableId}${queryString}`;
+  }
+
+  /**
+   * Builds URL for record navigation: /database/sourceTable('recordId')/relation
+   * or /database/sourceTable/baseRelation('recordId')/relation for chained navigations
+   */
+  private buildRecordNavigation(
+    queryString: string,
+    tableId: string,
+    navigation: NavigationConfig,
+  ): string {
+    const { sourceTableName, baseRelation, recordId, relation } = navigation;
+    const base = baseRelation
+      ? `${sourceTableName}/${baseRelation}('${recordId}')`
+      : `${sourceTableName}('${recordId}')`;
+    return `/${this.databaseName}/${base}/${relation}${queryString}`;
+  }
+
+  /**
+   * Builds URL for entity set navigation: /database/sourceTable/relation
+   * or /database/basePath/relation for chained navigations
+   */
+  private buildEntitySetNavigation(
+    queryString: string,
+    tableId: string,
+    navigation: NavigationConfig,
+  ): string {
+    const { sourceTableName, basePath, relation } = navigation;
+    const base = basePath || sourceTableName;
+    return `/${this.databaseName}/${base}/${relation}${queryString}`;
+  }
+
+  /**
+   * Builds a query string path (without database prefix) for getQueryString().
+   * Used when the full URL is not needed.
+   */
+  buildPath(
+    queryString: string,
+    options?: { useEntityIds?: boolean; navigation?: NavigationConfig },
+  ): string {
+    const useEntityIds = options?.useEntityIds;
+    const navigation = options?.navigation;
+    const tableId = resolveTableId(
+      this.occurrence,
+      getTableName(this.occurrence),
+      this.context,
+      useEntityIds,
+    );
+
+    if (navigation?.recordId && navigation?.relation) {
+      const { sourceTableName, baseRelation, recordId, relation } = navigation;
+      const base = baseRelation
+        ? `${sourceTableName}/${baseRelation}('${recordId}')`
+        : `${sourceTableName}('${recordId}')`;
+      return queryString
+        ? `/${base}/${relation}${queryString}`
+        : `/${base}/${relation}`;
+    }
+    if (navigation?.relation) {
+      const { sourceTableName, basePath, relation } = navigation;
+      const base = basePath || sourceTableName;
+      return queryString
+        ? `/${base}/${relation}${queryString}`
+        : `/${base}/${relation}`;
+    }
+    return queryString ? `/${tableId}${queryString}` : `/${tableId}`;
+  }
+
+  /**
+   * Build URL for record operations (single record by ID).
+   * Used by RecordBuilder to build URLs like /database/table('id').
+   *
+   * @param recordId - The record ID
+   * @param queryString - The OData query string (e.g., "?$select=...")
+   * @param options - Options including operation type and useEntityIds override
+   */
+  buildRecordUrl(
+    recordId: string | number,
+    queryString: string,
+    options?: {
+      operation?: "getSingleField";
+      operationParam?: string;
+      useEntityIds?: boolean;
+      isNavigateFromEntitySet?: boolean;
+      navigateSourceTableName?: string;
+      navigateRelation?: string;
+    },
+  ): string {
+    const tableId = resolveTableId(
+      this.occurrence,
+      getTableName(this.occurrence),
+      this.context,
+      options?.useEntityIds,
+    );
+
+    // Build the base URL depending on whether this came from a navigated EntitySet
+    let url: string;
+    if (
+      options?.isNavigateFromEntitySet &&
+      options.navigateSourceTableName &&
+      options.navigateRelation
+    ) {
+      // From navigated EntitySet: /sourceTable/relation('recordId')
+      url = `/${this.databaseName}/${options.navigateSourceTableName}/${options.navigateRelation}('${recordId}')`;
+    } else {
+      // Normal record: /tableName('recordId') - use FMTID if configured
+      url = `/${this.databaseName}/${tableId}('${recordId}')`;
+    }
+
+    if (options?.operation === "getSingleField" && options.operationParam) {
+      url += `/${options.operationParam}`;
+    }
+
+    return url + queryString;
+  }
+}