feat: error.response. Deprecates error.headers (#194)

Author: gr2m

README.md

@@ -55,11 +55,11 @@ const error = new RequestError("Oops", 500, {
 
 error.message; // Oops
 error.status; // 500
-error.headers; // { 'x-github-request-id': '1:2:3:4' }
 error.request.method; // POST
 error.request.url; // https://api.github.com/foo
 error.request.body; // { bar: 'baz' }
 error.request.headers; // { authorization: 'token [REDACTED]' }
+error.response; // { url, status, headers, data }
 ```
 
 ## LICENSE

src/index.ts

@@ -1,8 +1,13 @@
 import { Deprecation } from "deprecation";
 import once from "once";
-const logOnce = once((deprecation: any) => console.warn(deprecation));
+const logOnceCode = once((deprecation: any) => console.warn(deprecation));
+const logOnceHeaders = once((deprecation: any) => console.warn(deprecation));
 
-import { RequestOptions, ResponseHeaders } from "@octokit/types";
+import {
+  RequestOptions,
+  ResponseHeaders,
+  OctokitResponse,
+} from "@octokit/types";
 import { RequestErrorOptions } from "./types";
 
 /**
@@ -23,15 +28,22 @@ export class RequestError extends Error {
    */
   code!: number;
 
+  /**
+   * Request options that lead to the error.
+   */
+  request: RequestOptions;
+
   /**
    * error response headers
+   *
+   * @deprecated `error.headers` is deprecated in favor of `error.response.headers`
    */
-  headers: ResponseHeaders;
+  headers!: ResponseHeaders;
 
   /**
-   * Request options that lead to the error.
+   * Response object if a response was received
    */
-  request: RequestOptions;
+  response?: OctokitResponse<unknown>;
 
   constructor(
     message: string,
@@ -48,17 +60,16 @@ export class RequestError extends Error {
 
     this.name = "HttpError";
     this.status = statusCode;
-    Object.defineProperty(this, "code", {
-      get() {
-        logOnce(
-          new Deprecation(
-            "[@octokit/request-error] `error.code` is deprecated, use `error.status`."
-          )
-        );
-        return statusCode;
-      },
-    });
-    this.headers = options.headers || {};
+    let headers: ResponseHeaders;
+
+    if ("headers" in options && typeof options.headers !== "undefined") {
+      headers = options.headers;
+    }
+
+    if ("response" in options) {
+      this.response = options.response;
+      headers = options.response.headers;
+    }
 
     // redact request credentials without mutating original request options
     const requestCopy = Object.assign({}, options.request);
@@ -80,5 +91,27 @@ export class RequestError extends Error {
       .replace(/\baccess_token=\w+/g, "access_token=[REDACTED]");
 
     this.request = requestCopy;
+
+    // deprecations
+    Object.defineProperty(this, "code", {
+      get() {
+        logOnceCode(
+          new Deprecation(
+            "[@octokit/request-error] `error.code` is deprecated, use `error.status`."
+          )
+        );
+        return statusCode;
+      },
+    });
+    Object.defineProperty(this, "headers", {
+      get() {
+        logOnceHeaders(
+          new Deprecation(
+            "[@octokit/request-error] `error.headers` is deprecated, use `error.response.headers`."
+          )
+        );
+        return headers || {};
+      },
+    });
   }
 }

src/types.ts

@@ -1,6 +1,16 @@
-import { RequestOptions, ResponseHeaders } from "@octokit/types";
+import {
+  RequestOptions,
+  ResponseHeaders,
+  OctokitResponse,
+} from "@octokit/types";
 
-export type RequestErrorOptions = {
-  headers?: ResponseHeaders;
-  request: RequestOptions;
-};
+export type RequestErrorOptions =
+  | {
+      /** @deprecated set `response` instead */
+      headers?: ResponseHeaders;
+      request: RequestOptions;
+    }
+  | {
+      response: OctokitResponse<unknown>;
+      request: RequestOptions;
+    };

test/request-error.test.ts

@@ -10,38 +10,27 @@ const mockOptions: RequestErrorOptions = {
 };
 
 describe("RequestError", () => {
-  it("inherits from Error", () => {
+  test("inherits from Error", () => {
     const error = new RequestError("test", 123, mockOptions);
     expect(error).toBeInstanceOf(Error);
   });
 
-  it("sets .name to 'RequestError'", () => {
+  test("sets .name to 'RequestError'", () => {
     const error = new RequestError("test", 123, mockOptions);
     expect(error.name).toBe("HttpError");
   });
 
-  it("sets .message", () => {
+  test("sets .message", () => {
     expect(new RequestError("test", 123, mockOptions).message).toEqual("test");
     expect(new RequestError("foo", 123, mockOptions).message).toEqual("foo");
   });
 
-  it("sets .status", () => {
+  test("sets .status", () => {
     expect(new RequestError("test", 123, mockOptions).status).toEqual(123);
     expect(new RequestError("test", 404, mockOptions).status).toEqual(404);
   });
 
-  it("sets .headers", () => {
-    const options = Object.assign({}, mockOptions, {
-      headers: {
-        foo: "bar",
-      },
-    });
-    expect(new RequestError("test", 123, options).headers).toEqual({
-      foo: "bar",
-    });
-  });
-
-  it("sets .request", () => {
+  test("sets .request", () => {
     const options = Object.assign({}, mockOptions, {
       request: {
         method: "POST",
@@ -67,7 +56,7 @@ describe("RequestError", () => {
     });
   });
 
-  it("redacts credentials from error.request.url", () => {
+  test("redacts credentials from error.request.url", () => {
     const options = Object.assign({}, mockOptions, {
       request: {
         method: "GET",
@@ -83,7 +72,7 @@ describe("RequestError", () => {
     );
   });
 
-  it("redacts client_secret from error.request.url", () => {
+  test("redacts client_secret from error.request.url", () => {
     const options = Object.assign({}, mockOptions, {
       request: {
         method: "GET",
@@ -99,7 +88,7 @@ describe("RequestError", () => {
     );
   });
 
-  it("redacts access_token from error.request.url", () => {
+  test("redacts access_token from error.request.url", () => {
     const options = Object.assign({}, mockOptions, {
       request: {
         method: "GET",
@@ -115,10 +104,53 @@ describe("RequestError", () => {
     );
   });
 
-  it("deprecates .code", () => {
+  test("error.response", () => {
+    const error = new RequestError("test", 123, {
+      request: mockOptions.request,
+      response: {
+        url: mockOptions.request.url,
+        status: 404,
+        data: {
+          error: "Not Found",
+        },
+        headers: {
+          "x-github-request-id": "1",
+        },
+      },
+    });
+
+    expect(error.response).toStrictEqual({
+      data: {
+        error: "Not Found",
+      },
+      headers: {
+        "x-github-request-id": "1",
+      },
+      status: 404,
+      url: "https://api.github.com/",
+    });
+  });
+
+  test("deprecates .code", () => {
     global.console.warn = jest.fn();
     expect(new RequestError("test", 123, mockOptions).code).toEqual(123);
     expect(new RequestError("test", 404, mockOptions).code).toEqual(404);
     expect(console.warn).toHaveBeenCalledTimes(1);
   });
+
+  test("deprecates .headers", () => {
+    global.console.warn = jest.fn();
+    expect(new RequestError("test", 123, mockOptions).headers).toStrictEqual(
+      {}
+    );
+    expect(
+      new RequestError("test", 404, { ...mockOptions, headers: { foo: "bar" } })
+        .headers
+    ).toStrictEqual({ foo: "bar" });
+    expect(
+      new RequestError("test", 404, { ...mockOptions, headers: undefined })
+        .headers
+    ).toStrictEqual({});
+    expect(console.warn).toHaveBeenCalledTimes(1);
+  });
 });