@proofkit/fmodata 0.1.0-alpha.9 → 0.1.0-beta.24

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

@@ -0,0 +1,226 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { QueryOptions } from "odata-query";
+import { RecordCountMismatchError } from "../../errors";
+import type { InternalLogger } from "../../logger";
+import type { FMTable } from "../../orm/table";
+import { getTableSchema } from "../../orm/table";
+import { transformResponseFields } from "../../transform";
+import type { Result } from "../../types";
+import type { ExpandValidationConfig } from "../../validation";
+import { validateListResponse, validateSingleResponse } from "../../validation";
+import type { ExpandConfig } from "./expand-builder";
+
+/**
+ * Configuration for processing query responses
+ */
+export interface ProcessQueryResponseConfig<T> {
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  occurrence?: FMTable<any, any>;
+  singleMode: "exact" | "maybe" | false;
+  queryOptions: Partial<QueryOptions<T>>;
+  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;
+}
+
+/**
+ * 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
+    // Schema is stored directly as Partial<Record<keyof TFields, StandardSchemaV1>>
+    const targetSchema = targetTable
+      ? (getTableSchema(targetTable) as Record<string, StandardSchemaV1> | undefined)
+      : undefined;
+
+    // Extract selected fields from options
+    let selectedFields: string[] | undefined;
+    if (config.options?.select) {
+      selectedFields = Array.isArray(config.options.select)
+        ? config.options.select.map((f) => String(f))
+        : [String(config.options.select)];
+    }
+
+    return {
+      relation: config.relation,
+      targetSchema,
+      targetTable,
+      table: targetTable, // For transformation
+      selectedFields,
+      nestedExpands: undefined, // TODO: Handle nested expands if needed
+    };
+  });
+}
+
+/**
+ * Extracts records from response data without validation.
+ * Handles both single and list responses.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API, generic return type
+function extractRecords(data: any, singleMode: "exact" | "maybe" | false): Result<any> {
+  // biome-ignore lint/suspicious/noExplicitAny: Type assertion for response structure
+  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),
+        };
+      }
+      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type
+      return { data: null as any, error: undefined };
+    }
+
+    const record = Array.isArray(records) ? records[0] : records;
+    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type
+    return { data: record as any, error: undefined };
+  }
+  // Handle list response structure
+  const records = resp.value ?? [];
+  // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type
+  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 }).
+ */
+// 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 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>(
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API
+  response: any,
+  config: ProcessQueryResponseConfig<T>,
+  // biome-ignore lint/suspicious/noExplicitAny: Generic return type for interface compliance
+): 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
+  // Schema is stored directly as Partial<Record<keyof TFields, StandardSchemaV1>>
+  const schema = occurrence ? getTableSchema(occurrence) : undefined;
+
+  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
+  // Special columns are excluded when using single() method (per OData spec behavior)
+  // Note: While FileMaker may return special columns in single mode if requested via header,
+  // we exclude them here to maintain OData spec compliance. The types will also not include
+  // special columns for single mode to match this runtime behavior.
+  const shouldIncludeSpecialColumns = singleMode === false ? (config.includeSpecialColumns ?? false) : false;
+  const validationResult =
+    singleMode !== false
+      ? await validateSingleResponse(
+          data,
+          schema,
+          selectedFields as string[] | undefined,
+          expandValidationConfigs,
+          singleMode,
+          shouldIncludeSpecialColumns,
+        )
+      : await validateListResponse(
+          data,
+          schema,
+          selectedFields as string[] | undefined,
+          expandValidationConfigs,
+          shouldIncludeSpecialColumns,
+        );
+
+  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,
+    };
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type
+  return { data: validationResult.data as any, error: undefined };
+}

package/src/client/query/types.ts

@@ -0,0 +1,126 @@
+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
+  | [keyof T & string, "asc" | "desc"][]; // Multiple fields with directions
+
+// Internal type for expand configuration
+export interface ExpandConfig {
+  relation: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any QueryOptions configuration
+  options?: Partial<import("odata-query").QueryOptions<any>>;
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  targetTable?: import("../../orm/table").FMTable<any, any>;
+}
+
+// Type to represent expanded relations
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic schema and selected types from user input
+export type ExpandedRelations = Record<string, { schema: any; selected: any; nested?: ExpandedRelations }>;
+
+/**
+ * Extract the value type from a Column.
+ * This uses the phantom type stored in Column to get the actual value type (output type for reading).
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer
+type ExtractColumnType<C> = C extends Column<infer T, any, any, 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<
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+  TSelect extends Record<string, Column<any, any, any, any>>,
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any schema shape
+  _TSchema extends Record<string, any>,
+> = {
+  [K in keyof TSelect]: ExtractColumnType<TSelect[K]>;
+};
+
+/**
+ * Helper: Resolve a single expand's return type, including nested expands
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic schema and selected types from user input
+export type ResolveExpandType<Exp extends { schema: any; selected: any; nested?: ExpandedRelations }> = // Handle the selected fields
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+  (Exp["selected"] extends Record<string, Column<any, any, any, any>>
+    ? MapSelectToReturnType<Exp["selected"], Exp["schema"]>
+    : Exp["selected"] extends keyof Exp["schema"]
+      ? Pick<Exp["schema"], Exp["selected"]>
+      : Exp["schema"]) &
+    // Recursively handle nested expands
+    // biome-ignore lint/complexity/noBannedTypes: Empty object type represents no nested expands
+    (Exp["nested"] extends ExpandedRelations ? ResolveExpandedRelations<Exp["nested"]> : {});
+
+/**
+ * Helper: Resolve all expanded relations recursively
+ */
+export type ResolveExpandedRelations<Exps extends ExpandedRelations> = {
+  [K in keyof Exps]: ResolveExpandType<Exps[K]>[];
+};
+
+/**
+ * System columns option for select() method.
+ * Allows explicitly requesting ROWID and/or ROWMODID when using select().
+ */
+export interface SystemColumnsOption {
+  ROWID?: boolean;
+  ROWMODID?: boolean;
+}
+
+/**
+ * Extract system columns type from SystemColumnsOption.
+ * Returns an object type with ROWID and/or ROWMODID properties when set to true.
+ */
+export type SystemColumnsFromOption<T extends SystemColumnsOption | undefined> = (T extends { ROWID: true }
+  ? { ROWID: number }
+  : // biome-ignore lint/complexity/noBannedTypes: Empty object type represents no ROWID field
+    {}) &
+  // biome-ignore lint/complexity/noBannedTypes: Empty object type represents no ROWMODID field
+  (T extends { ROWMODID: true } ? { ROWMODID: number } : {});
+
+export type QueryReturnType<
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any schema shape
+  T extends Record<string, any>,
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+  Selected extends keyof T | Record<string, Column<any, any, any, any>>,
+  SingleMode extends "exact" | "maybe" | false,
+  IsCount extends boolean,
+  Expands extends ExpandedRelations,
+  SystemCols extends SystemColumnsOption | undefined = undefined,
+> = IsCount extends true
+  ? number
+  : // Use tuple wrapping [Selected] extends [...] to prevent distribution over unions
+    // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration
+    [Selected] extends [Record<string, Column<any, any, any, any>>]
+    ? SingleMode extends "exact"
+      ? MapSelectToReturnType<Selected, T> & ResolveExpandedRelations<Expands> & SystemColumnsFromOption<SystemCols>
+      : SingleMode extends "maybe"
+        ?
+            | (MapSelectToReturnType<Selected, T> &
+                ResolveExpandedRelations<Expands> &
+                SystemColumnsFromOption<SystemCols>)
+            | null
+        : (MapSelectToReturnType<Selected, T> &
+            ResolveExpandedRelations<Expands> &
+            SystemColumnsFromOption<SystemCols>)[]
+    : // Use tuple wrapping to prevent distribution over union of keys
+      [Selected] extends [keyof T]
+      ? SingleMode extends "exact"
+        ? Pick<T, Selected> & ResolveExpandedRelations<Expands> & SystemColumnsFromOption<SystemCols>
+        : SingleMode extends "maybe"
+          ? (Pick<T, Selected> & ResolveExpandedRelations<Expands> & SystemColumnsFromOption<SystemCols>) | null
+          : (Pick<T, Selected> & ResolveExpandedRelations<Expands> & SystemColumnsFromOption<SystemCols>)[]
+      : never;

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

@@ -0,0 +1,151 @@
+import type { FMTable } from "../../orm/table";
+import { getTableName } from "../../orm/table";
+import type { ExecutionContext } from "../../types";
+import { resolveTableId } from "../builders/table-utils";
+
+/**
+ * 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 {
+  private readonly databaseName: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  private readonly occurrence: FMTable<any, any>;
+  private readonly context: ExecutionContext;
+
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  constructor(databaseName: string, occurrence: FMTable<any, any>, context: ExecutionContext) {
+    this.databaseName = databaseName;
+    this.occurrence = occurrence;
+    this.context = context;
+  }
+
+  /**
+   * 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;
+  }
+}