From a3a7da60b2775063450dc4a2fea5d607df7a4cea Mon Sep 17 00:00:00 2001
From: Gadi Cohen <dragon@wastelands.net>
Date: Sat, 5 Jun 2021 09:03:47 +0100
Subject: [PATCH] feat(errors): expose in yf.errors; improve docs (#202)

---
 docs/README.md      | 47 +++++++++++++++++++++++++++++++++++++++++----
 src/index-common.ts |  4 ++++
 src/lib/errors.ts   | 19 ++++++++++++++----
 3 files changed, 62 insertions(+), 8 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index 2469250e..4c1d56c8 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -62,6 +62,7 @@ try {
   result = await yahooFinance.quote(symbol);
 } catch (error) {
   // Inspect error and decide what to do; often, you may want to just abort:
+  console.warn(`Skipping yf.quote("${symbol}"): [${error.name}] ${error.message})`);
   return;
 }
 
@@ -80,11 +81,49 @@ the result you receive will be in an expected format and structure, that
 is safe to use, put in your database, perform calculations with, etc
 (but please do let us know if you come across any edge cases).
 
-There is a list of specific errors at [lib/errors.ts](../src/lib/errors.ts)
-but generally we'll prevent you from making bad requests with invalid option,
-etc.
+There is a list of specific errors at [lib/errors.ts](../src/lib/errors.ts),
+accessible via `yahooFinance.errors`, but many of these will require further
+inspection at runtime.  For example:
 
-See also: [Validation](./validation.md)
+* `FailedYahooValidationError` - see the [Validation](./validation.md) section
+on how to handle these correctly.
+
+* `HTTPError` - the `message` property will be the HTTP Response statusText.
+
+* `Error` - thrown after a "successful" HTTP request that returns JSON with an
+  `{ error: { name: "ErrorName", description: "string" } }` shape, and where
+  we don't have an "ErrorName" class.  The `message` property will be the
+  `description`.
+
+Example:
+
+```js
+import yahooFinance from 'yahoo-finance2';
+
+let result;
+try {
+  result = await yahooFinance.quote(symbol);
+} catch (error) {
+  if (error instanceof yahooFinance.errors.FailedYahooValidationError) {
+    // See the validation docs for examples of how to handle this
+    // error.result will be a partially validated / coerced result.
+  } else if (error instanceof yahooFinance.errors.HTTPError) {
+    // Probably you just want to log and skip these
+    console.warn(`Skipping yf.quote("${symbol}"): [${error.name}] ${error.message})`);
+    return;
+  } else {
+    // Same here
+    console.warn(`Skipping yf.quote("${symbol}"): [${error.name}] ${error.message})`);
+    return;
+  }
+}
+
+doSomethingWith(result); // safe to use in the way you expect
+```
+
+
+If you run into any problems with error handling, feel free to open an issue
+so we can make these docs clearer.
 
 ## Validation
 
diff --git a/src/index-common.ts b/src/index-common.ts
index be20d55c..e087fb20 100644
--- a/src/index-common.ts
+++ b/src/index-common.ts
@@ -2,6 +2,7 @@
 import yahooFinanceFetch from "./lib/yahooFinanceFetch.js";
 import moduleExec from "./lib/moduleExec.js";
 import options from "./lib/options.js";
+import errors from "./lib/errors.js";
 
 // modules
 import autoc from "./modules/autoc.js";
@@ -24,6 +25,9 @@ export default {
   _moduleExec: moduleExec,
   _opts: options,
 
+  // errors
+  errors,
+
   // modules,
   autoc,
   historical,
diff --git a/src/lib/errors.ts b/src/lib/errors.ts
index c24fe2c4..91a8b663 100644
--- a/src/lib/errors.ts
+++ b/src/lib/errors.ts
@@ -1,14 +1,22 @@
 import type { ErrorObject } from "ajv/dist/types";
 
+// Yahoo's servers returned an HTTP 400 for this request.
 export class BadRequestError extends Error {
   name = "BadRequestError";
 }
+
+// Yahoo's servers returned a 'not-ok' status for this request.
+// https://developer.mozilla.org/en-US/docs/Web/API/Response/ok
 export class HTTPError extends Error {
   name = "HTTPError";
 }
+
+// A YahooFinance method was called with invalid options.
 export class InvalidOptionsError extends Error {
   name = "InvalidOptionsError";
 }
+
+// An internal method yahooFinanceFetch() was called without this._env set.
 export class NoEnvironmentError extends Error {
   name = "NoEnvironmentError";
 }
@@ -28,14 +36,17 @@ export class FailedYahooValidationError extends Error {
   }
 }
 
-interface ErrorsIndex {
+// Index necessary to allow things like: const ErrorClass = errors[errorName];
+type ErrorsIndex = {
   [key: string]: any;
-}
+};
 
-export default {
+const errors: ErrorsIndex = {
   BadRequestError,
   HTTPError,
   InvalidOptionsError,
   NoEnvironmentError,
   FailedYahooValidationError,
-} as ErrorsIndex;
+};
+
+export default errors;