add mergeHeaders until we get to the point or removing legacy options

Author: dixonyant

packages/arcgis-rest-request/src/request.ts

@@ -19,6 +19,7 @@ import { IRetryAuthError } from "./utils/retryAuthError.js";
 import { IAuthenticationManager } from "./index.js";
 import { isSameOrigin } from "./utils/isSameOrigin.js";
 import { normalizeDeprecatedRequestOptions } from "./utils/normalize-deprecated-request-options.js";
+import { mergeHeaders } from "./utils/merge-headers.js";
 
 export const NODEJS_DEFAULT_REFERER_HEADER = `@esri/arcgis-rest-js`;
 const ENTERPRISE_MAX_URL_LENGTH = 2000;
@@ -237,10 +238,10 @@ function normalizeRequestOptions(
       fetchOptions: {
         ...defaults.fetchOptions,
         ...normalizedRequestOptions.fetchOptions,
-        headers: {
-          ...(defaults.fetchOptions?.headers as any),
-          ...(normalizedRequestOptions.fetchOptions?.headers as any)
-        }
+        headers: mergeHeaders(
+          defaults.fetchOptions?.headers,
+          normalizedRequestOptions.fetchOptions?.headers
+        )
       }
     }
   };
@@ -468,10 +469,7 @@ https://developers.arcgis.com/rest/users-groups-and-items/update-resources.htm
   }
 
   // Mixin headers from request options
-  fetchOptions.headers = {
-    ...requestHeaders,
-    ...(fetchOptions.headers as any)
-  };
+  fetchOptions.headers = mergeHeaders(requestHeaders, fetchOptions.headers);
 
   // This should have the same conditional for Node JS as ArcGISIdentityManager.refreshWithUsernameAndPassword()
   // to ensure that generated tokens have the same referer when used in Node with a username and password.

packages/arcgis-rest-request/src/utils/merge-headers.ts

@@ -0,0 +1,42 @@
+/* Copyright (c) 2026 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+type HeaderMap = {
+  [key: string]: string;
+};
+
+function appendHeaders(target: HeaderMap, headers?: HeadersInit): void {
+  if (!headers) {
+    return;
+  }
+
+  if (Array.isArray(headers)) {
+    headers.forEach(([key, value]) => {
+      target[key] = String(value);
+    });
+    return;
+  }
+
+  if (typeof Headers !== "undefined" && headers instanceof Headers) {
+    headers.forEach((value, key) => {
+      target[key] = value;
+    });
+    return;
+  }
+
+  Object.entries(headers).forEach(([key, value]) => {
+    if (typeof value !== "undefined") {
+      target[key] = String(value);
+    }
+  });
+}
+
+export function mergeHeaders(...headerSets: Array<HeadersInit | undefined>) {
+  const mergedHeaders: HeaderMap = {};
+
+  headerSets.forEach((headers) => {
+    appendHeaders(mergedHeaders, headers);
+  });
+
+  return mergedHeaders;
+}

packages/arcgis-rest-request/src/utils/normalize-deprecated-request-options.ts

@@ -2,6 +2,7 @@
  * Apache-2.0 */
 
 import { IRequestOptions } from "./IRequestOptions.js";
+import { mergeHeaders } from "./merge-headers.js";
 
 /**
  * Converts deprecated top-level request options into their v2 IRequestOptions
@@ -32,10 +33,7 @@ export function normalizeDeprecatedRequestOptions(
     ...(credentials !== undefined ? { credentials } : {}),
     ...(signal !== undefined ? { signal } : {}),
     ...requestOptions.fetchOptions,
-    headers: {
-      ...(headers as any),
-      ...(requestOptions.fetchOptions?.headers as any)
-    }
+    headers: mergeHeaders(headers as any, requestOptions.fetchOptions?.headers)
   };
 
   const normalizedOptions: IRequestOptions = {

packages/arcgis-rest-request/test/utils/merge-headers.test.ts

@@ -0,0 +1,74 @@
+/* Copyright (c) 2026 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { describe, expect, test } from "vitest";
+import { mergeHeaders } from "../../src/utils/merge-headers.js";
+
+describe("mergeHeaders", () => {
+  test("should merge plain object headers", () => {
+    const merged = mergeHeaders(
+      {
+        "X-Test": "from-defaults",
+        "X-Defaults-Only": "true"
+      },
+      {
+        "X-Test": "from-request",
+        "X-Request-Only": "true"
+      }
+    );
+
+    expect(merged).toEqual({
+      "X-Test": "from-request",
+      "X-Defaults-Only": "true",
+      "X-Request-Only": "true"
+    });
+  });
+
+  test("should merge tuple headers", () => {
+    const merged = mergeHeaders([
+      ["X-Token", "abc123"],
+      ["X-Custom", "custom-value"]
+    ]);
+
+    expect(merged).toEqual({
+      "X-Token": "abc123",
+      "X-Custom": "custom-value"
+    });
+  });
+
+  test("should merge Headers instance", () => {
+    if (typeof Headers === "undefined") {
+      return;
+    }
+
+    const headerObject = mergeHeaders(
+      { "X-Initial": "true" },
+      new Headers([["X-From-Headers", "true"]])
+    );
+
+    expect(headerObject["X-Initial"]).toBe("true");
+    expect(headerObject["x-from-headers"]).toBe("true");
+  });
+
+  test("should omit undefined object header values", () => {
+    const headerObject = mergeHeaders({
+      "X-Defined": "true",
+      "X-Undefined": undefined as any
+    });
+
+    expect(headerObject).toEqual({
+      "X-Defined": "true"
+    });
+    expect(headerObject["X-Undefined"]).toBeUndefined();
+  });
+
+  test("should ignore undefined header sets", () => {
+    const headerObject = mergeHeaders(undefined, {
+      "X-Defined": "true"
+    });
+
+    expect(headerObject).toEqual({
+      "X-Defined": "true"
+    });
+  });
+});

packages/arcgis-rest-request/test/utils/normalize-deprecated-request-options.test.ts

@@ -94,6 +94,88 @@ describe("normalizeDeprecatedRequestOptions", () => {
     });
   });
 
+  test("should normalize tuple-based fetch headers", () => {
+    const normalized = normalizeDeprecatedRequestOptions({
+      headers: {
+        "X-Deprecated": "legacy"
+      },
+      fetchOptions: {
+        headers: [["X-Fetch-Tuple", "tuple-value"]]
+      }
+    });
+
+    expect(normalized.fetchOptions?.headers).toEqual({
+      "X-Deprecated": "legacy",
+      "X-Fetch-Tuple": "tuple-value"
+    });
+  });
+
+  test("should prefer tuple-based fetch headers over deprecated top-level headers", () => {
+    const normalized = normalizeDeprecatedRequestOptions({
+      headers: {
+        "X-Test": "legacy-value",
+        "X-Deprecated-Only": "legacy"
+      },
+      fetchOptions: {
+        headers: [
+          ["X-Test", "tuple-value"],
+          ["X-Fetch-Only", "tuple-only"]
+        ]
+      }
+    });
+
+    expect(normalized.fetchOptions?.headers).toEqual({
+      "X-Test": "tuple-value",
+      "X-Deprecated-Only": "legacy",
+      "X-Fetch-Only": "tuple-only"
+    });
+  });
+
+  test("should normalize Headers instance in fetchOptions.headers", () => {
+    if (typeof Headers === "undefined") {
+      return;
+    }
+
+    const normalized = normalizeDeprecatedRequestOptions({
+      headers: {
+        "X-Deprecated": "legacy"
+      },
+      fetchOptions: {
+        headers: new Headers([["X-Fetch-Headers", "headers-value"]])
+      }
+    });
+
+    expect(normalized.fetchOptions?.headers).toEqual({
+      "X-Deprecated": "legacy",
+      "x-fetch-headers": "headers-value"
+    });
+  });
+
+  test("should prefer Headers instance values over deprecated top-level headers", () => {
+    if (typeof Headers === "undefined") {
+      return;
+    }
+
+    const normalized = normalizeDeprecatedRequestOptions({
+      headers: {
+        "x-test": "legacy-value",
+        "X-Deprecated-Only": "legacy"
+      },
+      fetchOptions: {
+        headers: new Headers([
+          ["X-Test", "headers-value"],
+          ["X-Fetch-Only", "headers-only"]
+        ])
+      }
+    });
+
+    expect(normalized.fetchOptions?.headers).toEqual({
+      "x-test": "headers-value",
+      "X-Deprecated-Only": "legacy",
+      "x-fetch-only": "headers-only"
+    });
+  });
+
   test("should drop legacy options without v2 replacements", () => {
     const normalized = normalizeDeprecatedRequestOptions({
       maxUrlLength: 3000,