add doc for Headers.getSetCookie() (#26161)

* add doc for Headers.getSetCookie()

* Updates made according to comments from Josh-Cena and ricea

* another wording update

* Update example to show retrieval of multiple Set-Cookie values

* fix code error

files/en-us/web/api/headers/getsetcookie/index.md

@@ -0,0 +1,66 @@
+---
+title: "Headers: getSetCookie() method"
+short-title: getSetCookie()
+slug: Web/API/Headers/getSetCookie
+page-type: web-api-instance-method
+browser-compat: api.Headers.getSetCookie
+---
+
+{{APIRef("Fetch API")}}
+
+The **`getSetCookie()`** method of the {{domxref("Headers")}} interface returns an array containing the values of all {{httpheader("Set-Cookie")}} headers associated with a response. This allows {{domxref("Headers")}} objects to handle having multiple `Set-Cookie` headers, which wasn't possible prior to its implementation.
+
+This method is intended for use on server environments (for example Node.js). Browsers block frontend JavaScript code from accessing the {{httpheader("Set-Cookie")}} header, as required by the Fetch spec, which defines `Set-Cookie` as a [forbidden response-header name](https://fetch.spec.whatwg.org/#forbidden-response-header-name) that [must be filtered out](https://fetch.spec.whatwg.org/#ref-for-forbidden-response-header-name%E2%91%A0) from any response exposed to frontend code.
+
+## Syntax
+
+```js-nolint
+getSetCookie()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+An array of strings representing the values of all the different `Set-Cookie` headers associated with a response.
+
+If no `Set-Cookie` headers are set, the method will return an empty array (`[ ]`).
+
+## Examples
+
+As alluded to above, running code like the following on the client won't return any results — `Set-Cookie` is filtered out from {{domxref("Headers")}} retrieved over the network.
+
+```js
+fetch("https://example.com").then((response) => {
+  console.log(response.headers.getSetCookie());
+  // No header values returned
+});
+```
+
+However, the following could be used to query multiple `Set-Cookie` values. This is much more useful on the server, but it would also work on the client.
+
+```js
+const headers = new Headers({
+  "Set-Cookie": "name1=value1",
+});
+
+headers.append("Set-Cookie", "name2=value2");
+
+headers.getSetCookie();
+// Returns ["name1=value1", "name2=value2"]
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [HTTP](/en-US/docs/Web/HTTP)
+- {{httpheader("Set-Cookie")}}

files/en-us/web/api/headers/index.md

@@ -38,6 +38,8 @@ An object implementing `Headers` can directly be used in a {{jsxref("Statements/
   - : Executes a provided function once for each key/value pair in this `Headers` object.
 - {{domxref("Headers.get()")}}
   - : Returns a {{jsxref("String")}} sequence of all the values of a header within a `Headers` object with a given name.
+- {{domxref("Headers.getSetCookie()")}}
+  - : Returns an array containing the values of all {{httpheader("Set-Cookie")}} headers associated with a response.
 - {{domxref("Headers.has()")}}
   - : Returns a boolean stating whether a `Headers` object contains a certain header.
 - {{domxref("Headers.keys()")}}