feat!: Headers should be Headers

README.md

@@ -27,9 +27,9 @@ Gaxios supports setting default properties both on the default instance, and on
 const gaxios = require('gaxios');
 gaxios.instance.defaults = {
   baseURL: 'https://example.com'
-  headers: {
+  headers: new Headers({
     Authorization: 'SOME_TOKEN'
-  }
+  })
 }
 gaxios.request({url: '/data'}).then(...);
 ```
@@ -51,7 +51,7 @@ interface GaxiosOptions = {
   baseURL: 'https://example.com';
 
   // The HTTP methods to be sent with the request.
-  headers: { 'some': 'header' } || new Headers(),
+  headers: new Headers(),
 
   // The data to send in the body of the request. Objects will be serialized as JSON
   // except for:

browser-test/test.browser.ts

@@ -41,7 +41,7 @@ describe('💻 browser tests', () => {
   });
 
   it('should support multipart post from the browser', async () => {
-    const headers: {[key: string]: string} = {};
+    const headers = new Headers();
     const multipart = [
       {
         'Content-Type': 'application/json',
@@ -55,7 +55,7 @@ describe('💻 browser tests', () => {
     const boundary =
       globalThis?.crypto.randomUUID() || (await import('crypto')).randomUUID();
     const finale = `--${boundary}--`;
-    headers['Content-Type'] = `multipart/related; boundary=${boundary}`;
+    headers.set('Content-Type', `multipart/related; boundary=${boundary}`);
 
     let content = '';
     for (const part of multipart) {

src/common.ts

@@ -28,9 +28,6 @@ import {Readable} from 'stream';
 type _BodyInit = typeof globalThis extends {BodyInit: infer T}
   ? T
   : import('undici-types').BodyInit;
-type _HeadersInit = typeof globalThis extends {HeadersInit: infer T}
-  ? T
-  : import('undici-types').HeadersInit;
 
 /**
  * Support `instanceof` operator for `GaxiosError`s in different versions of this library.
@@ -145,7 +142,7 @@ export interface GaxiosResponse<T = GaxiosResponseData> extends Response {
 }
 
 export interface GaxiosMultipartOptions {
-  headers: _HeadersInit;
+  headers: Headers;
   content: string | Readable;
 }
 
@@ -164,6 +161,24 @@ export interface GaxiosOptions extends RequestInit {
     defaultAdapter: (options: GaxiosOptionsPrepared) => GaxiosPromise<T>,
   ) => GaxiosPromise<T>;
   url?: string | URL;
+  /**
+   * Headers to add to the request.
+   *
+   * @remarks
+   *
+   * Using the proper Headers type has the following benefits:
+   * - creates consistency throughout the libraries; no need to check properties for different casing
+   *   - see {@link https://github.com/googleapis/gaxios/issues/262 #262}
+   * - Alignment with {@link https://developer.mozilla.org/en-US/docs/Web/API/Request/headers `Request#headers`}
+   * - Can easily append an existing header or create it ('upsert') if it does exist, like so:
+   * ```ts
+   * const headers = new Headers();
+   *
+   * // creates, if not exist, or appends to an existing header
+   * headers.append('x-goog-api-client', 'abc');
+   * ```
+   */
+  headers?: Headers;
   /**
    * @deprecated
    */
@@ -323,7 +338,7 @@ export interface GaxiosOptions extends RequestInit {
 }
 
 export interface GaxiosOptionsPrepared extends GaxiosOptions {
-  headers: globalThis.Headers;
+  headers: Headers;
   url: URL;
 }
 

src/gaxios.ts

@@ -293,6 +293,23 @@ export class Gaxios {
     return promiseChain;
   }
 
+  /**
+   * Merges headers.
+   *
+   * @param base headers to append/overwrite to
+   * @param append headers to append/overwrite with
+   * @returns the base headers instance with merged `Headers`
+   */
+  #mergeHeaders(base: Headers, append?: Headers) {
+    append?.forEach((value, key) => {
+      // set-cookie is the only header that would repeat.
+      // A bit of background: https://developer.mozilla.org/en-US/docs/Web/API/Headers/getSetCookie
+      key === 'set-cookie' ? base.append(key, value) : base.set(key, value);
+    });
+
+    return base;
+  }
+
   /**
    * Validates the options, merges them with defaults, and prepare request.
    *
@@ -302,7 +319,13 @@ export class Gaxios {
   async #prepareRequest(
     options: GaxiosOptions,
   ): Promise<GaxiosOptionsPrepared> {
+    // Prepare Headers - copy in order to not mutate the original objects
+    const preparedHeaders = new Headers(this.defaults.headers);
+    this.#mergeHeaders(preparedHeaders, options.headers);
+
+    // Merge options
     const opts = extend(true, {}, this.defaults, options);
+
     if (!opts.url) {
       throw new Error('URL is required.');
     }
@@ -344,11 +367,6 @@ export class Gaxios {
       opts.follow = options.maxRedirects;
     }
 
-    const preparedHeaders =
-      opts.headers instanceof Headers
-        ? opts.headers
-        : new Headers(opts.headers);
-
     const shouldDirectlyPassData =
       typeof opts.data === 'string' ||
       opts.data instanceof ArrayBuffer ||
@@ -526,12 +544,8 @@ export class Gaxios {
   ) {
     const finale = `--${boundary}--`;
     for (const currentPart of multipartOptions) {
-      const headers =
-        currentPart.headers instanceof Headers
-          ? currentPart.headers
-          : new Headers(currentPart.headers as HeadersInit);
       const partContentType =
-        headers.get('Content-Type') || 'application/octet-stream';
+        currentPart.headers.get('Content-Type') || 'application/octet-stream';
       const preamble = `--${boundary}\r\nContent-Type: ${partContentType}\r\n\r\n`;
       yield preamble;
       if (typeof currentPart.content === 'string') {

test/test.getch.ts

@@ -110,7 +110,7 @@ describe('🚙 error handling', () => {
       data: notJSON,
       status: 500,
       statusText: '',
-      headers: {},
+      headers: new Headers(),
       // workaround for `node-fetch`'s `.data` deprecation...
       bodyUsed: true,
     } as GaxiosResponse;
@@ -163,8 +163,11 @@ describe('🥁 configuration options', () => {
 
   it('should handle nested options passed into the constructor', async () => {
     const scope = nock(url).get('/').reply(200);
-    const inst = new Gaxios({headers: {apple: 'juice'}});
-    const res = await inst.request({url, headers: {figgy: 'pudding'}});
+    const inst = new Gaxios({headers: new Headers({apple: 'juice'})});
+    const res = await inst.request({
+      url,
+      headers: new Headers({figgy: 'pudding'}),
+    });
     scope.done();
     assert.strictEqual(res.config.headers.get('apple'), 'juice');
     assert.strictEqual(res.config.headers.get('figgy'), 'pudding');
@@ -714,7 +717,9 @@ describe('🎏 data handling', () => {
       url,
       method: 'POST',
       data: encoded,
-      headers: {'content-type': 'application/x-www-form-urlencoded'},
+      headers: new Headers({
+        'content-type': 'application/x-www-form-urlencoded',
+      }),
     });
     scope.done();
     assert.deepStrictEqual(res.data, {});
@@ -745,9 +750,9 @@ describe('🎏 data handling', () => {
       url,
       method: 'POST',
       data: body,
-      headers: {
+      headers: new Headers({
         'Content-Type': 'application/json-patch+json',
-      },
+      }),
     });
     scope.done();
     assert.deepStrictEqual(res.data, {});
@@ -763,9 +768,9 @@ describe('🎏 data handling', () => {
       url,
       method: 'POST',
       data: body,
-      headers: {
+      headers: new Headers({
         'Content-Type': 'application/x-www-form-urlencoded',
-      },
+      }),
     });
     scope.done();
     assert.deepStrictEqual(res.data, {});
@@ -909,7 +914,7 @@ describe('🎏 data handling', () => {
       method: 'POST',
       multipart: [
         {
-          headers: {'Content-Type': 'application/json'},
+          headers: new Headers({'Content-Type': 'application/json'}),
           content: body,
         },
       ],
@@ -939,11 +944,11 @@ describe('🎏 data handling', () => {
       method: 'POST',
       multipart: [
         {
-          headers: {'Content-Type': 'application/json'},
+          headers: new Headers({'Content-Type': 'application/json'}),
           content: body,
         },
         {
-          headers: {'Content-Type': 'text/plain'},
+          headers: new Headers({'Content-Type': 'text/plain'}),
           content: textContent,
         },
       ],
@@ -1106,7 +1111,7 @@ describe('🍂 defaults & instances', () => {
       url,
       method: 'POST',
       data: pkg,
-      headers: {'content-type': 'application/dicom'},
+      headers: new Headers({'content-type': 'application/dicom'}),
     });
     scope.done();
     assert.deepStrictEqual(res.data, {});
@@ -1145,11 +1150,14 @@ describe('🍂 defaults & instances', () => {
       const key = fs.readFileSync('./test/fixtures/fake.key', 'utf8');
       const scope = nock(url).get('/').reply(200);
       const inst = new GaxiosAssertAgentCache({
-        headers: {apple: 'juice'},
+        headers: new Headers({apple: 'juice'}),
         cert: fs.readFileSync('./test/fixtures/fake.cert', 'utf8'),
         key,
       });
-      const res = await inst.request({url, headers: {figgy: 'pudding'}});
+      const res = await inst.request({
+        url,
+        headers: new Headers({figgy: 'pudding'}),
+      });
       scope.done();
       assert.strictEqual(res.config.headers.get('apple'), 'juice');
       assert.strictEqual(res.config.headers.get('figgy'), 'pudding');
@@ -1160,12 +1168,12 @@ describe('🍂 defaults & instances', () => {
       const key = fs.readFileSync('./test/fixtures/fake.key', 'utf8');
       const scope = nock(url).get('/').reply(200).get('/').reply(200);
       const inst = new GaxiosAssertAgentCache({
-        headers: {apple: 'juice'},
+        headers: new Headers({apple: 'juice'}),
         cert: fs.readFileSync('./test/fixtures/fake.cert', 'utf8'),
         key,
       });
-      await inst.request({url, headers: {figgy: 'pudding'}});
-      await inst.request({url, headers: {figgy: 'pudding'}});
+      await inst.request({url, headers: new Headers({figgy: 'pudding'})});
+      await inst.request({url, headers: new Headers({figgy: 'pudding'})});
       scope.done();
       const agentCache = inst.getAgentCache();
       assert(agentCache.get(key));
@@ -1241,7 +1249,7 @@ describe('interceptors', () => {
           return Promise.resolve(config);
         },
       });
-      await instance.request({url, headers: {}});
+      await instance.request({url});
       scope.done();
     });
 
@@ -1354,7 +1362,7 @@ describe('interceptors', () => {
           return Promise.resolve(response);
         },
       });
-      const resp = await instance.request({url, headers: {}});
+      const resp = await instance.request({url});
       scope.done();
       assert.strictEqual(resp.headers.get('foo'), 'bar');
       assert.strictEqual(resp.headers.get('bar'), 'baz');