Fix fmodata mutation Prefer header merging

Author: eluce2

.changeset/fix-fmodata-mutation-special-columns.md

@@ -0,0 +1,5 @@
+---
+"@proofkit/fmodata": patch
+---
+
+Fix `insert()` and `update(..., { returnFullRecord: true })` to preserve merged `Prefer` headers for `fmodata.include-specialcolumns` and `fmodata.entity-ids`, and return special columns in typed full-record mutation responses.

packages/fmodata/src/client/builders/mutation-helpers.ts

@@ -17,13 +17,37 @@ export interface FilterQueryBuilder {
 export function mergeMutationExecuteOptions(
   options: (RequestInit & FFetchOptions & ExecuteOptions) | undefined,
   databaseUseEntityIds: boolean,
-): RequestInit & FFetchOptions & { useEntityIds?: boolean } {
+  databaseIncludeSpecialColumns: boolean,
+): RequestInit & FFetchOptions & { useEntityIds?: boolean; includeSpecialColumns?: boolean } {
   return {
     ...options,
     useEntityIds: options?.useEntityIds ?? databaseUseEntityIds,
+    includeSpecialColumns: options?.includeSpecialColumns ?? databaseIncludeSpecialColumns,
   };
 }
 
+export function mergePreferHeaderValues(...values: Array<string | undefined>): string | undefined {
+  const merged: string[] = [];
+  const seen = new Set<string>();
+
+  for (const value of values) {
+    if (!value) {
+      continue;
+    }
+
+    for (const part of value.split(",")) {
+      const normalized = part.trim();
+      if (!normalized || seen.has(normalized)) {
+        continue;
+      }
+      seen.add(normalized);
+      merged.push(normalized);
+    }
+  }
+
+  return merged.length > 0 ? merged.join(", ") : undefined;
+}
+
 export function resolveMutationTableId(
   // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
   table: FMTable<any, any> | undefined,

packages/fmodata/src/client/delete-builder.ts

@@ -101,7 +101,11 @@ export class ExecutableDeleteBuilder<Occ extends FMTable<any, any>>
   }
 
   execute(options?: ExecuteMethodOptions<ExecuteOptions>): Promise<Result<{ deletedCount: number }>> {
-    const mergedOptions = mergeMutationExecuteOptions(options, this.config.useEntityIds);
+    const mergedOptions = mergeMutationExecuteOptions(
+      options,
+      this.config.useEntityIds,
+      this.config.includeSpecialColumns,
+    );
     // biome-ignore lint/suspicious/noExplicitAny: Execute options include dynamic fetch fields
     const { method: _method, body: _body, ...requestOptions } = mergedOptions as any;
     const useEntityIds = mergedOptions.useEntityIds ?? this.config.useEntityIds;

packages/fmodata/src/client/entity-set.ts

@@ -230,19 +230,25 @@ export class EntitySet<Occ extends FMTable<any, any>, DatabaseIncludeSpecialColu
   }
 
   // Overload: when returnFullRecord is false
-  insert(data: InsertDataFromFMTable<Occ>, options: { returnFullRecord: false }): InsertBuilder<Occ, "minimal">;
+  insert(
+    data: InsertDataFromFMTable<Occ>,
+    options: { returnFullRecord: false },
+  ): InsertBuilder<Occ, "minimal", DatabaseIncludeSpecialColumns>;
 
   // Overload: when returnFullRecord is true or omitted (default)
-  insert(data: InsertDataFromFMTable<Occ>, options?: { returnFullRecord?: true }): InsertBuilder<Occ, "representation">;
+  insert(
+    data: InsertDataFromFMTable<Occ>,
+    options?: { returnFullRecord?: true },
+  ): InsertBuilder<Occ, "representation", DatabaseIncludeSpecialColumns>;
 
   // Implementation
   insert(
     data: InsertDataFromFMTable<Occ>,
     options?: { returnFullRecord?: boolean },
-  ): InsertBuilder<Occ, "minimal" | "representation"> {
+  ): InsertBuilder<Occ, "minimal" | "representation", DatabaseIncludeSpecialColumns> {
     const returnPreference = options?.returnFullRecord === false ? "minimal" : "representation";
 
-    return new InsertBuilder<Occ, typeof returnPreference>({
+    return new InsertBuilder<Occ, typeof returnPreference, DatabaseIncludeSpecialColumns>({
       occurrence: this.occurrence,
       layer: this.layer,
       // biome-ignore lint/suspicious/noExplicitAny: Input type is validated/transformed at runtime
@@ -253,19 +259,25 @@ export class EntitySet<Occ extends FMTable<any, any>, DatabaseIncludeSpecialColu
   }
 
   // Overload: when returnFullRecord is explicitly true
-  update(data: UpdateDataFromFMTable<Occ>, options: { returnFullRecord: true }): UpdateBuilder<Occ, "representation">;
+  update(
+    data: UpdateDataFromFMTable<Occ>,
+    options: { returnFullRecord: true },
+  ): UpdateBuilder<Occ, "representation", DatabaseIncludeSpecialColumns>;
 
   // Overload: when returnFullRecord is false or omitted (default)
-  update(data: UpdateDataFromFMTable<Occ>, options?: { returnFullRecord?: false }): UpdateBuilder<Occ, "minimal">;
+  update(
+    data: UpdateDataFromFMTable<Occ>,
+    options?: { returnFullRecord?: false },
+  ): UpdateBuilder<Occ, "minimal", DatabaseIncludeSpecialColumns>;
 
   // Implementation
   update(
     data: UpdateDataFromFMTable<Occ>,
     options?: { returnFullRecord?: boolean },
-  ): UpdateBuilder<Occ, "minimal" | "representation"> {
+  ): UpdateBuilder<Occ, "minimal" | "representation", DatabaseIncludeSpecialColumns> {
     const returnPreference = options?.returnFullRecord === true ? "representation" : "minimal";
 
-    return new UpdateBuilder<Occ, typeof returnPreference>({
+    return new UpdateBuilder<Occ, typeof returnPreference, DatabaseIncludeSpecialColumns>({
       occurrence: this.occurrence,
       layer: this.layer,
       // biome-ignore lint/suspicious/noExplicitAny: Input type is validated/transformed at runtime

packages/fmodata/src/client/insert-builder.ts

@@ -9,16 +9,19 @@ import type { FMODataLayer, ODataConfig } from "../services";
 import { transformFieldNamesToIds, transformResponseFields } from "../transform";
 import type {
   ConditionallyWithODataAnnotations,
+  ConditionallyWithSpecialColumns,
   ExecutableBuilder,
   ExecuteMethodOptions,
   ExecuteOptions,
+  NormalizeIncludeSpecialColumns,
   Result,
 } from "../types";
 import { getAcceptHeader } from "../types";
 import { validateAndTransformInput, validateSingleResponse } from "../validation";
 import {
   getLocationHeader,
   mergeMutationExecuteOptions,
+  mergePreferHeaderValues,
   parseRowIdFromLocationHeader,
   resolveMutationTableId,
 } from "./builders/mutation-helpers";
@@ -36,9 +39,16 @@ export class InsertBuilder<
   // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
   Occ extends FMTable<any, any> | undefined = undefined,
   ReturnPreference extends "minimal" | "representation" = "representation",
+  DatabaseIncludeSpecialColumns extends boolean = false,
 > implements
     ExecutableBuilder<
-      ReturnPreference extends "minimal" ? { ROWID: number } : InferSchemaOutputFromFMTable<NonNullable<Occ>>
+      ReturnPreference extends "minimal"
+        ? { ROWID: number }
+        : ConditionallyWithSpecialColumns<
+            InferSchemaOutputFromFMTable<NonNullable<Occ>>,
+            DatabaseIncludeSpecialColumns,
+            false
+          >
     >
 {
   private readonly table?: Occ;
@@ -67,8 +77,8 @@ export class InsertBuilder<
    */
   private mergeExecuteOptions(
     options?: RequestInit & FFetchOptions & ExecuteOptions,
-  ): RequestInit & FFetchOptions & { useEntityIds?: boolean } {
-    return mergeMutationExecuteOptions(options, this.config.useEntityIds);
+  ): RequestInit & FFetchOptions & { useEntityIds?: boolean; includeSpecialColumns?: boolean } {
+    return mergeMutationExecuteOptions(options, this.config.useEntityIds, this.config.includeSpecialColumns);
   }
 
   /**
@@ -117,7 +127,11 @@ export class InsertBuilder<
       ReturnPreference extends "minimal"
         ? { ROWID: number }
         : ConditionallyWithODataAnnotations<
-            InferSchemaOutputFromFMTable<NonNullable<Occ>>,
+            ConditionallyWithSpecialColumns<
+              InferSchemaOutputFromFMTable<NonNullable<Occ>>,
+              NormalizeIncludeSpecialColumns<EO["includeSpecialColumns"], DatabaseIncludeSpecialColumns>,
+              false
+            >,
             EO["includeODataAnnotations"] extends true ? true : false
           >
     >
@@ -128,8 +142,14 @@ export class InsertBuilder<
     const { method: _method, headers: callerHeaders, body: _body, ...requestOptions } = mergedOptions as any;
     const tableId = this.getTableId(mergedOptions.useEntityIds);
     const url = `/${this.config.databaseName}/${tableId}`;
-    const shouldUseIds = mergedOptions.useEntityIds ?? false;
-    const preferHeader = this.returnPreference === "minimal" ? "return=minimal" : "return=representation";
+    const shouldUseIds = mergedOptions.useEntityIds ?? this.config.useEntityIds;
+    const includeSpecialColumns = mergedOptions.includeSpecialColumns ?? this.config.includeSpecialColumns;
+    const preferHeader = mergePreferHeaderValues(
+      new Headers(callerHeaders).get("Prefer") ?? undefined,
+      this.returnPreference === "minimal" ? "return=minimal" : "return=representation",
+      shouldUseIds ? "fmodata.entity-ids" : undefined,
+      includeSpecialColumns ? "fmodata.include-specialcolumns" : undefined,
+    );
 
     const pipeline = Effect.gen(this, function* () {
       // Step 1: Validate input
@@ -157,7 +177,7 @@ export class InsertBuilder<
         headers: {
           ...(callerHeaders || {}),
           "Content-Type": "application/json",
-          Prefer: preferHeader,
+          ...(preferHeader ? { Prefer: preferHeader } : {}),
         },
         body: JSON.stringify(transformedData),
       });
@@ -191,6 +211,7 @@ export class InsertBuilder<
           undefined,
           undefined,
           "exact",
+          includeSpecialColumns,
         ),
       );
 
@@ -216,7 +237,11 @@ export class InsertBuilder<
         ReturnPreference extends "minimal"
           ? { ROWID: number }
           : ConditionallyWithODataAnnotations<
-              InferSchemaOutputFromFMTable<NonNullable<Occ>>,
+              ConditionallyWithSpecialColumns<
+                InferSchemaOutputFromFMTable<NonNullable<Occ>>,
+                NormalizeIncludeSpecialColumns<EO["includeSpecialColumns"], DatabaseIncludeSpecialColumns>,
+                false
+              >,
               EO["includeODataAnnotations"] extends true ? true : false
             >
       >
@@ -241,16 +266,20 @@ export class InsertBuilder<
   toRequest(baseUrl: string, options?: ExecuteOptions): Request {
     const config = this.getRequestConfig();
     const fullUrl = `${baseUrl}${config.url}`;
-
-    // Set Prefer header based on return preference
-    const preferHeader = this.returnPreference === "minimal" ? "return=minimal" : "return=representation";
+    const preferHeader = mergePreferHeaderValues(
+      this.returnPreference === "minimal" ? "return=minimal" : "return=representation",
+      (options?.useEntityIds ?? this.config.useEntityIds) ? "fmodata.entity-ids" : undefined,
+      (options?.includeSpecialColumns ?? this.config.includeSpecialColumns)
+        ? "fmodata.include-specialcolumns"
+        : undefined,
+    );
 
     return new Request(fullUrl, {
       method: config.method,
       headers: {
         "Content-Type": "application/json",
         Accept: getAcceptHeader(options?.includeODataAnnotations),
-        Prefer: preferHeader,
+        ...(preferHeader ? { Prefer: preferHeader } : {}),
       },
       body: config.body,
     });
@@ -260,7 +289,15 @@ export class InsertBuilder<
     response: Response,
     options?: ExecuteOptions,
   ): Promise<
-    Result<ReturnPreference extends "minimal" ? { ROWID: number } : InferSchemaOutputFromFMTable<NonNullable<Occ>>>
+    Result<
+      ReturnPreference extends "minimal"
+        ? { ROWID: number }
+        : ConditionallyWithSpecialColumns<
+            InferSchemaOutputFromFMTable<NonNullable<Occ>>,
+            DatabaseIncludeSpecialColumns,
+            false
+          >
+    >
   > {
     // Check for error responses (important for batch operations)
     if (!response.ok) {
@@ -345,6 +382,7 @@ export class InsertBuilder<
 
     // Transform response field IDs back to names if using entity IDs
     const shouldUseIds = options?.useEntityIds ?? this.config.useEntityIds;
+    const includeSpecialColumns = options?.includeSpecialColumns ?? this.config.includeSpecialColumns;
 
     let transformedResponse = rawResponse;
     if (this.table && shouldUseIds) {
@@ -376,6 +414,7 @@ export class InsertBuilder<
       undefined, // No selected fields for insert
       undefined, // No expand configs
       "exact", // Expect exactly one record
+      includeSpecialColumns,
     );
 
     if (!validation.valid) {