feat(with_header): add withHeader function

README.md

@@ -87,6 +87,25 @@ assertFalse(isResponse({}));
 assertFalse(isResponse(null));
 ```
 
+## withHeader
+
+Return an instance with the provided `Response` replacing the specified header.
+There are no side effects on the original `Response`.
+
+```ts
+import { withHeader } from "https://deno.land/x/response_utils@$VERSION/with_header.ts";
+import { assert } from "https://deno.land/std/testing/asserts.ts";
+
+declare const init: Response;
+declare const fieldName: string;
+declare const fieldValue: string;
+
+const response = withHeader(init, fieldName, fieldValue);
+
+assert(response.headers.get(fieldName), fieldValue);
+assert(init !== response);
+```
+
 ## API
 
 All APIs can be found in the [deno doc](https://deno.land/x/response_utils?doc).

with_header.ts

@@ -0,0 +1,34 @@
+// Copyright 2023-latest the httpland authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+/** Return an instance with the provided `Response` replacing the specified header.
+ * There are no side effects on the original `Response`.
+ *
+ * @example
+ * ```ts
+ * import { withHeader } from "https://deno.land/x/response_utils@$VERSION/with_header.ts";
+ * import { assert } from "https://deno.land/std/testing/asserts.ts";
+ *
+ * declare const init: Response;
+ * declare const fieldName: string;
+ * declare const fieldValue: string;
+ *
+ * const response = withHeader(init, fieldName, fieldValue);
+ *
+ * assert(response.headers.get(fieldName), fieldValue);
+ * assert(init !== response);
+ * ```
+ */
+export function withHeader(
+  response: Response,
+  fieldName: string,
+  fieldValue: string,
+): Response {
+  const headers = new Headers([...response.headers.entries(), [
+    fieldName,
+    fieldValue,
+  ]]);
+  const { status, statusText } = response;
+
+  return new Response(response.body, { headers, status, statusText });
+}

with_header_test.ts

@@ -0,0 +1,37 @@
+// Copyright 2023-latest the httpland authors. All rights reserved. MIT license.
+
+import { withHeader } from "./with_header.ts";
+import { assert, assertEquals, describe, it } from "./_dev_deps.ts";
+
+describe("withHeader", () => {
+  const FIELD_NAME = "x-x";
+  const FIELD_VALUE = "test";
+  const BODY = "ok";
+  const INIT_HEADER = "x-init";
+  const INIT_HEADER_VALUE = "init";
+
+  it("should return new response instance with specified header", async () => {
+    const STATUS = 201;
+    const STATUS_TEXT = "status text";
+
+    const initResponse = new Response(BODY, {
+      status: STATUS,
+      statusText: STATUS_TEXT,
+      headers: {
+        [INIT_HEADER]: INIT_HEADER_VALUE,
+      },
+    });
+
+    const response = withHeader(initResponse, FIELD_NAME, FIELD_VALUE);
+
+    assert(response !== initResponse);
+    assertEquals(response.headers.get(FIELD_NAME), FIELD_VALUE);
+    assertEquals(response.headers.get(INIT_HEADER), INIT_HEADER_VALUE);
+    assertEquals(response.status, STATUS);
+    assertEquals(response.statusText, STATUS_TEXT);
+    assertEquals(await response.text(), BODY);
+
+    assert(!initResponse.headers.has(FIELD_NAME));
+    assert(initResponse.headers.has(INIT_HEADER));
+  });
+});