feat(message): add withHeader function

Author: TomokiMiyauci

README.md

@@ -550,6 +550,46 @@ assert(isRetrieveMethod("HEAD"));
 assert(!isRetrieveMethod("POST"));
 ```
 
+## withHeader
+
+Return an instance with the provided value replacing the specified header. There
+are no side effects on the original target.
+
+This was inspired by
+[PSR-7: HTTP message interfaces](https://www.php-fig.org/psr/psr-7/).
+
+`Request`:
+
+```ts
+import { withHeader } from "https://deno.land/x/http_utils@$VERSION/message.ts";
+import { assert } from "https://deno.land/std@$VERSION/testing/asserts.ts";
+
+declare const init: Request;
+declare const header: string;
+declare const value: string;
+
+const request = withHeader(init, header, value);
+
+assert(request.headers.get(header), value);
+assert(init !== request);
+```
+
+`Response`:
+
+```ts
+import { withHeader } from "https://deno.land/x/http_utils@$VERSION/message.ts";
+import { assert } from "https://deno.land/std@$VERSION/testing/asserts.ts";
+
+declare const init: Response;
+declare const header: string;
+declare const value: string;
+
+const response = withHeader(init, header, value);
+
+assert(response.headers.get(header), value);
+assert(init !== response);
+```
+
 ## License
 
 Copyright © 2023-present [httpland](https://github.com/httpland).

message.ts

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

message_test.ts

@@ -0,0 +1,58 @@
+import { withHeader } from "./message.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 request instance with specified header", async () => {
+    const METHOD = "POST";
+
+    const initRequest = new Request("test:", {
+      method: METHOD,
+      body: BODY,
+      headers: {
+        [INIT_HEADER]: INIT_HEADER_VALUE,
+      },
+    });
+
+    const request = withHeader(initRequest, FIELD_NAME, FIELD_VALUE);
+
+    assert(request !== initRequest);
+    assertEquals(request.headers.get(FIELD_NAME), FIELD_VALUE);
+    assertEquals(request.headers.get(INIT_HEADER), INIT_HEADER_VALUE);
+    assertEquals(await request.text(), BODY);
+    assertEquals(request.method, METHOD);
+
+    assert(!initRequest.headers.has(FIELD_NAME));
+    assert(initRequest.headers.has(INIT_HEADER));
+  });
+
+  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));
+  });
+});

mod.ts

@@ -38,3 +38,4 @@ export {
   type RetrieveMethod,
   type SafeMethod,
 } from "./method.ts";
+export { withHeader } from "./message.ts";