@proofkit/fmodata 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/transform.ts

@@ -0,0 +1,263 @@
+import type { FMTable } from "./orm/table";
+import {
+  getBaseTableConfig,
+  getFieldId,
+  getFieldName,
+  getTableId,
+  getTableName,
+  isUsingEntityIds,
+} from "./orm/table";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+/**
+ * Transforms field names to FileMaker field IDs (FMFID) in an object
+ * @param data - Object with field names as keys
+ * @param table - FMTable instance to get field IDs from
+ * @returns Object with FMFID keys instead of field names
+ */
+export function transformFieldNamesToIds<T extends Record<string, any>>(
+  data: T,
+  table: FMTable<any, any>,
+): Record<string, any> {
+  const config = getBaseTableConfig(table);
+  if (!config.fmfIds) {
+    return data;
+  }
+
+  const transformed: Record<string, any> = {};
+  for (const [fieldName, value] of Object.entries(data)) {
+    const fieldId = getFieldId(table, fieldName);
+    transformed[fieldId] = value;
+  }
+  return transformed;
+}
+
+/**
+ * Transforms FileMaker field IDs (FMFID) to field names in an object
+ * @param data - Object with FMFID keys
+ * @param table - FMTable instance to get field names from
+ * @returns Object with field names as keys instead of FMFIDs
+ */
+export function transformFieldIdsToNames<T extends Record<string, any>>(
+  data: T,
+  table: FMTable<any, any>,
+): Record<string, any> {
+  const config = getBaseTableConfig(table);
+  if (!config.fmfIds) {
+    return data;
+  }
+
+  const transformed: Record<string, any> = {};
+  for (const [key, value] of Object.entries(data)) {
+    // Check if this is an OData metadata field (starts with @)
+    if (key.startsWith("@")) {
+      transformed[key] = value;
+      continue;
+    }
+
+    const fieldName = getFieldName(table, key);
+    transformed[fieldName] = value;
+  }
+  return transformed;
+}
+
+/**
+ * Transforms a field name to FMFID or returns the field name if not using IDs
+ * @param fieldName - The field name to transform
+ * @param table - FMTable instance to get field ID from
+ * @returns The FMFID or field name
+ */
+export function transformFieldName(
+  fieldName: string,
+  table: FMTable<any, any>,
+): string {
+  return getFieldId(table, fieldName);
+}
+
+/**
+ * Transforms a table name to FMTID or returns the name if not using IDs
+ * @param table - FMTable instance to get table ID from
+ * @returns The FMTID or table name
+ */
+export function transformTableName(table: FMTable<any, any>): string {
+  return getTableId(table);
+}
+
+/**
+ * Gets both table name and ID from a table
+ * @param table - FMTable instance
+ * @returns Object with name (always present) and id (may be undefined if not using IDs)
+ */
+export function getTableIdentifiers(
+  table: FMTable<any, any>,
+): { name: string; id: string | undefined } {
+  return {
+    name: getTableName(table),
+    id: isUsingEntityIds(table) ? getTableId(table) : undefined,
+  };
+}
+
+/**
+ * Transforms response data by converting field IDs back to field names recursively.
+ * Handles both single records and arrays of records, as well as nested expand relationships.
+ *
+ * @param data - Response data from FileMaker (can be single record, array, or wrapped in value property)
+ * @param table - FMTable instance for the main table
+ * @param expandConfigs - Configuration for expanded relations (optional)
+ * @returns Transformed data with field names instead of IDs
+ */
+export function transformResponseFields(
+  data: any,
+  table: FMTable<any, any>,
+  expandConfigs?: Array<{
+    relation: string;
+    table?: FMTable<any, any>;
+  }>,
+): any {
+  const config = getBaseTableConfig(table);
+  if (!config.fmfIds) {
+    return data;
+  }
+
+  // Handle null/undefined
+  if (data === null || data === undefined) {
+    return data;
+  }
+
+  // Handle OData list response with value array
+  if (data.value && Array.isArray(data.value)) {
+    return {
+      ...data,
+      value: data.value.map((record: any) =>
+        transformSingleRecord(record, table, expandConfigs),
+      ),
+    };
+  }
+
+  // Handle array of records
+  if (Array.isArray(data)) {
+    return data.map((record) =>
+      transformSingleRecord(record, table, expandConfigs),
+    );
+  }
+
+  // Handle single record
+  return transformSingleRecord(data, table, expandConfigs);
+}
+
+/**
+ * Transforms a single record, converting field IDs to names and handling nested expands
+ */
+function transformSingleRecord(
+  record: any,
+  table: FMTable<any, any>,
+  expandConfigs?: Array<{
+    relation: string;
+    table?: FMTable<any, any>;
+  }>,
+): any {
+  if (!record || typeof record !== "object") {
+    return record;
+  }
+
+  const transformed: Record<string, any> = {};
+
+  for (const [key, value] of Object.entries(record)) {
+    // Preserve OData metadata fields
+    if (key.startsWith("@")) {
+      transformed[key] = value;
+      continue;
+    }
+
+    // Check if this is an expanded relation (by relation name)
+    let expandConfig = expandConfigs?.find((ec) => ec.relation === key);
+
+    // If not found by relation name, check if this key is a FMTID
+    // (FileMaker returns expanded relations with FMTID keys when using entity IDs)
+    if (!expandConfig && key.startsWith("FMTID:")) {
+      expandConfig = expandConfigs?.find(
+        (ec) =>
+          ec.table && isUsingEntityIds(ec.table) && getTableId(ec.table) === key,
+      );
+    }
+
+    if (expandConfig && expandConfig.table) {
+      // Transform the expanded relation data recursively
+      // Use the relation name (not the FMTID) as the key
+      const relationKey = expandConfig.relation;
+
+      if (Array.isArray(value)) {
+        transformed[relationKey] = value.map((nestedRecord) =>
+          transformSingleRecord(
+            nestedRecord,
+            expandConfig.table!,
+            undefined, // Don't pass nested expand configs for now
+          ),
+        );
+      } else if (value && typeof value === "object") {
+        transformed[relationKey] = transformSingleRecord(
+          value,
+          expandConfig.table,
+          undefined,
+        );
+      } else {
+        transformed[relationKey] = value;
+      }
+      continue;
+    }
+
+    // Transform field ID to field name
+    const fieldName = getFieldName(table, key);
+    transformed[fieldName] = value;
+  }
+
+  return transformed;
+}
+
+/**
+ * Transforms an array of field names to FMFIDs
+ * @param fieldNames - Array of field names
+ * @param table - FMTable instance to get field IDs from
+ * @returns Array of FMFIDs or field names
+ */
+export function transformFieldNamesArray(
+  fieldNames: string[],
+  table: FMTable<any, any>,
+): string[] {
+  const config = getBaseTableConfig(table);
+  if (!config.fmfIds) {
+    return fieldNames;
+  }
+
+  return fieldNames.map((fieldName) => getFieldId(table, fieldName));
+}
+
+/**
+ * Transforms a field name in an orderBy string (e.g., "name desc" -> "FMFID:1 desc")
+ * @param orderByString - The orderBy string (field name with optional asc/desc)
+ * @param table - FMTable instance to get field ID from
+ * @returns Transformed orderBy string with FMFID
+ */
+export function transformOrderByField(
+  orderByString: string,
+  table: FMTable<any, any> | undefined,
+): string {
+  if (!table) {
+    return orderByString;
+  }
+  const config = getBaseTableConfig(table);
+  if (!config || !config.fmfIds) {
+    return orderByString;
+  }
+
+  // Parse the orderBy string to extract field name and direction
+  const parts = orderByString.trim().split(/\s+/);
+  const fieldName = parts[0];
+  if (!fieldName) {
+    return orderByString;
+  }
+  const direction = parts[1]; // "asc" or "desc" or undefined
+
+  const fieldId = getFieldId(table, fieldName);
+  return direction ? `${fieldId} ${direction}` : fieldId;
+}

package/src/types.ts

@@ -1,28 +1,58 @@
 import { type FFetchOptions } from "@fetchkit/ffetch";
-import { z } from "zod/v4";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { InternalLogger } from "./logger";
 
 export type Auth = { username: string; password: string } | { apiKey: string };
 
 export interface ExecutableBuilder<T> {
   execute(): Promise<Result<T>>;
   getRequestConfig(): { method: string; url: string; body?: any };
+
+  /**
+   * Convert this builder to a native Request object for batch processing.
+   * @param baseUrl - The base URL for the OData service
+   * @param options - Optional execution options (e.g., includeODataAnnotations)
+   * @returns A native Request object
+   */
+  toRequest(baseUrl: string, options?: ExecuteOptions): Request;
+
+  /**
+   * Process a raw Response object into a typed Result.
+   * This allows builders to apply their own validation and transformation logic.
+   * @param response - The native Response object from the batch operation
+   * @param options - Optional execution options (e.g., skipValidation, includeODataAnnotations)
+   * @returns A typed Result with the builder's expected return type
+   */
+  processResponse(
+    response: Response,
+    options?: ExecuteOptions,
+  ): Promise<Result<T>>;
 }
 
 export interface ExecutionContext {
   _makeRequest<T>(
     url: string,
-    options?: RequestInit & FFetchOptions,
-  ): Promise<T>;
+    options?: RequestInit &
+      FFetchOptions & {
+        useEntityIds?: boolean;
+        includeSpecialColumns?: boolean;
+      },
+  ): Promise<Result<T>>;
+  _setUseEntityIds?(useEntityIds: boolean): void;
+  _getUseEntityIds?(): boolean;
+  _setIncludeSpecialColumns?(includeSpecialColumns: boolean): void;
+  _getIncludeSpecialColumns?(): boolean;
+  _getBaseUrl?(): string;
+  _getLogger?(): InternalLogger;
 }
 
 export type InferSchemaType<Schema extends Record<string, StandardSchemaV1>> = {
-  [K in keyof Schema]: Schema[K] extends StandardSchemaV1<any, infer Output> 
-    ? Output 
+  [K in keyof Schema]: Schema[K] extends StandardSchemaV1<any, infer Output>
+    ? Output
     : never;
 };
 
-export type WithSystemFields<T> =
+export type WithSpecialColumns<T> =
   T extends Record<string, any>
     ? T & {
         ROWID: number;
@@ -30,15 +60,12 @@ export type WithSystemFields<T> =
       }
     : never;
 
-// Helper type to exclude system fields from a union of keys
+// Helper type to exclude special columns from a union of keys
 export type ExcludeSystemFields<T extends keyof any> = Exclude<
   T,
   "ROWID" | "ROWMODID"
 >;
 
-// Helper type to omit system fields from an object type
-export type OmitSystemFields<T> = Omit<T, "ROWID" | "ROWMODID">;
-
 // OData record metadata fields (present on each record)
 export type ODataRecordMetadata = {
   "@id": string;
@@ -63,61 +90,254 @@ export type ODataFieldResponse<T> = {
 };
 
 // Result pattern for execute responses
-export type Result<T, E = Error> =
+export type Result<T, E = import("./errors").FMODataErrorType> =
   | { data: T; error: undefined }
   | { data: undefined; error: E };
 
+// Batch operation result types
+export type BatchItemResult<T> = {
+  data: T | undefined;
+  error: import("./errors").FMODataErrorType | undefined;
+  status: number; // HTTP status code (0 for truncated)
+};
+
+export type BatchResult<T extends readonly any[]> = {
+  results: { [K in keyof T]: BatchItemResult<T[K]> };
+  successCount: number;
+  errorCount: number;
+  truncated: boolean;
+  firstErrorIndex: number | null;
+};
+
 // Make specific keys required, rest optional
 export type MakeFieldsRequired<T, Keys extends keyof T> = Partial<T> &
   Required<Pick<T, Keys>>;
 
-// Extract insert data type from BaseTable
-// This type makes the insertRequired fields required while keeping others optional
-export type InsertData<BT> = BT extends import("./client/base-table").BaseTable<
-  infer Schema extends Record<string, z.ZodType>,
-  any,
-  infer InsertRequired extends readonly any[],
-  any
->
-  ? [InsertRequired[number]] extends [keyof InferSchemaType<Schema>]
-    ? InsertRequired extends readonly (keyof InferSchemaType<Schema>)[]
-      ? MakeFieldsRequired<InferSchemaType<Schema>, InsertRequired[number]>
-      : Partial<InferSchemaType<Schema>>
-    : Partial<InferSchemaType<Schema>>
-  : Partial<Record<string, any>>;
-
-// Extract update data type from BaseTable
-// This type makes the updateRequired fields required while keeping others optional
-export type UpdateData<BT> = BT extends import("./client/base-table").BaseTable<
-  infer Schema extends Record<string, z.ZodType>,
-  any,
-  any,
-  infer UpdateRequired extends readonly any[]
->
-  ? [UpdateRequired[number]] extends [keyof InferSchemaType<Schema>]
-    ? UpdateRequired extends readonly (keyof InferSchemaType<Schema>)[]
-      ? MakeFieldsRequired<InferSchemaType<Schema>, UpdateRequired[number]>
-      : Partial<InferSchemaType<Schema>>
-    : Partial<InferSchemaType<Schema>>
-  : Partial<Record<string, any>>;
+// Extract keys from schema where validator doesn't allow null/undefined (auto-required fields)
+export type AutoRequiredKeys<Schema extends Record<string, StandardSchemaV1>> =
+  {
+    [K in keyof Schema]: Extract<
+      StandardSchemaV1.InferOutput<Schema[K]>,
+      null | undefined
+    > extends never
+      ? K
+      : never;
+  }[keyof Schema];
+
+// Helper type to compute excluded fields (readOnly fields + idField)
+export type ExcludedFields<
+  IdField extends keyof any | undefined,
+  ReadOnly extends readonly any[],
+> = IdField extends keyof any ? IdField | ReadOnly[number] : ReadOnly[number];
+
+// Helper type for InsertData computation
+type ComputeInsertData<
+  Schema extends Record<string, StandardSchemaV1>,
+  IdField extends keyof Schema | undefined,
+  Required extends readonly any[],
+  ReadOnly extends readonly any[],
+> = [Required[number]] extends [keyof InferSchemaType<Schema>]
+  ? Required extends readonly (keyof InferSchemaType<Schema>)[]
+    ? MakeFieldsRequired<
+        Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>,
+        Exclude<
+          AutoRequiredKeys<Schema> | Required[number],
+          ExcludedFields<IdField, ReadOnly>
+        >
+      >
+    : MakeFieldsRequired<
+        Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>,
+        Exclude<AutoRequiredKeys<Schema>, ExcludedFields<IdField, ReadOnly>>
+      >
+  : MakeFieldsRequired<
+      Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>,
+      Exclude<AutoRequiredKeys<Schema>, ExcludedFields<IdField, ReadOnly>>
+    >;
 
 export type ExecuteOptions = {
   includeODataAnnotations?: boolean;
   skipValidation?: boolean;
+  /**
+   * Overrides the default behavior of the database to use entity IDs (rather than field names) in THIS REQUEST ONLY
+   */
+  useEntityIds?: boolean;
+  /**
+   * Overrides the default behavior of the database to include special columns (ROWID and ROWMODID) in THIS REQUEST ONLY.
+   * Note: Special columns are only included when there is no $select query.
+   */
+  includeSpecialColumns?: boolean;
 };
 
-export type ConditionallyWithODataAnnotations<T, IncludeODataAnnotations extends boolean> = 
-  IncludeODataAnnotations extends true 
-    ? T & {
-        "@id": string;
-        "@editLink": string;
-      }
-    : T;
-
-// Helper type to extract schema from a TableOccurrence
-export type ExtractSchemaFromOccurrence<Occ> =
-  Occ extends { baseTable: { schema: infer S } }
-    ? S extends Record<string, StandardSchemaV1>
-      ? S
-      : Record<string, StandardSchemaV1>
-    : Record<string, StandardSchemaV1>;
+/**
+ * Type for the fetchHandler callback function.
+ * This is a convenience type export that matches the fetchHandler signature in FFetchOptions.
+ *
+ * @example
+ * ```typescript
+ * import type { FetchHandler } from '@proofkit/fmodata';
+ *
+ * const myFetchHandler: FetchHandler = (input, init) => {
+ *   console.log('Custom fetch:', input);
+ *   return fetch(input, init);
+ * };
+ *
+ * await query.execute({
+ *   fetchHandler: myFetchHandler
+ * });
+ * ```
+ */
+export type FetchHandler = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+/**
+ * Combined type for execute() method options.
+ *
+ * Uses FFetchOptions from @fetchkit/ffetch to ensure proper type inference.
+ * FFetchOptions is re-exported in the package to ensure type availability in consuming packages.
+ */
+export type ExecuteMethodOptions<EO extends ExecuteOptions = ExecuteOptions> =
+  RequestInit & FFetchOptions & ExecuteOptions & EO;
+
+/**
+ * Get the Accept header value based on includeODataAnnotations option
+ * @param includeODataAnnotations - Whether to include OData annotations
+ * @returns Accept header value
+ */
+export function getAcceptHeader(includeODataAnnotations?: boolean): string {
+  return includeODataAnnotations === true
+    ? "application/json"
+    : "application/json;odata.metadata=none";
+}
+
+export type ConditionallyWithODataAnnotations<
+  T,
+  IncludeODataAnnotations extends boolean,
+> = IncludeODataAnnotations extends true
+  ? T & {
+      "@id": string;
+      "@editLink": string;
+    }
+  : T;
+
+/**
+ * Normalizes includeSpecialColumns with a database-level default.
+ * Uses distributive conditional types to handle unions correctly.
+ * @template IncludeSpecialColumns - The includeSpecialColumns value from execute options
+ * @template DatabaseDefault - The database-level includeSpecialColumns setting (defaults to false)
+ */
+export type NormalizeIncludeSpecialColumns<
+  IncludeSpecialColumns extends boolean | undefined,
+  DatabaseDefault extends boolean = false,
+> = [IncludeSpecialColumns] extends [true]
+  ? true
+  : [IncludeSpecialColumns] extends [false]
+    ? false
+    : DatabaseDefault; // When undefined, use database-level default
+
+/**
+ * Conditionally adds ROWID and ROWMODID special columns to a type.
+ * Special columns are only included when:
+ * - includeSpecialColumns is true AND
+ * - hasSelect is false (no $select query was applied) AND
+ * - T is an object type (not a primitive like string or number)
+ *
+ * Handles both single objects and arrays of objects.
+ */
+export type ConditionallyWithSpecialColumns<
+  T,
+  IncludeSpecialColumns extends boolean,
+  HasSelect extends boolean,
+> = IncludeSpecialColumns extends true
+  ? HasSelect extends false
+    ? // Handle array types
+      T extends readonly (infer U)[]
+      ? U extends Record<string, any>
+        ? (U & {
+            ROWID: number;
+            ROWMODID: number;
+          })[]
+        : T
+      : // Handle single object types
+        T extends Record<string, any>
+        ? T & {
+            ROWID: number;
+            ROWMODID: number;
+          }
+        : T // Don't add special columns to primitives (e.g., single field queries)
+    : T
+  : T;
+
+// Helper type to extract schema from a FMTable
+export type ExtractSchemaFromOccurrence<Occ> = Occ extends {
+  baseTable: { schema: infer S };
+}
+  ? S extends Record<string, StandardSchemaV1>
+    ? S
+    : Record<string, StandardSchemaV1>
+  : Record<string, StandardSchemaV1>;
+
+export type GenericFieldMetadata = {
+  $Nullable?: boolean;
+  "@Index"?: boolean;
+  "@Calculation"?: boolean;
+  "@Summary"?: boolean;
+  "@Global"?: boolean;
+  "@Org.OData.Core.V1.Permissions"?: "Org.OData.Core.V1.Permission@Read";
+};
+
+export type StringFieldMetadata = GenericFieldMetadata & {
+  $Type: "Edm.String";
+  $DefaultValue?: "USER" | "USERNAME" | "CURRENT_USER";
+  $MaxLength?: number;
+};
+
+export type DecimalFieldMetadata = GenericFieldMetadata & {
+  $Type: "Edm.Decimal";
+  "@AutoGenerated"?: boolean;
+};
+
+export type DateFieldMetadata = GenericFieldMetadata & {
+  $Type: "Edm.Date";
+  $DefaultValue?: "CURDATE" | "CURRENT_DATE";
+};
+
+export type TimeOfDayFieldMetadata = GenericFieldMetadata & {
+  $Type: "Edm.TimeOfDay";
+  $DefaultValue?: "CURTIME" | "CURRENT_TIME";
+};
+
+export type DateTimeOffsetFieldMetadata = GenericFieldMetadata & {
+  $Type: "Edm.Date";
+  $DefaultValue?: "CURTIMESTAMP" | "CURRENT_TIMESTAMP";
+  "@VersionId"?: boolean;
+};
+
+export type StreamFieldMetadata = {
+  $Type: "Edm.Stream";
+  $Nullable?: boolean;
+  "@EnclosedPath": string;
+  "@ExternalOpenPath": string;
+  "@ExternalSecurePath"?: string;
+};
+
+export type FieldMetadata =
+  | StringFieldMetadata
+  | DecimalFieldMetadata
+  | DateFieldMetadata
+  | TimeOfDayFieldMetadata
+  | DateTimeOffsetFieldMetadata
+  | StreamFieldMetadata;
+
+export type EntityType = {
+  $Kind: "EntityType";
+  $Key: string[];
+} & Record<string, FieldMetadata>;
+
+export type EntitySet = {
+  $Kind: "EntitySet";
+  $Type: string;
+};
+
+export type Metadata = Record<string, EntityType | EntitySet>;