chore: custom errors

.changeset/two-jeans-kick.md

@@ -0,0 +1,5 @@
+---
+"react-loqate": major
+---
+
+Breaking: implement LoqateError and ReactLoqateError

README.md

@@ -95,6 +95,15 @@ import AddressSearch from 'react-loqate';
 />;
 ```
 
+### Errors
+
+Two types of errors can be thrown, LoqateError and ReactLoqateError.
+Loqate Errors are errors from the Loqate API. Their structure, causes and resolutions can be [found in the loqate docs](https://www.loqate.com/developers/api/generic-errors/).
+
+Currently only one ReactLoqateError can be thrown. This error occurs when the Retrieve API returns an empty Items array after querying it with an existing ID.
+
+It is on you as the implementing party to catch and handle these errors.
+
 ### Contributing
 
 This codebases use [@changesets](https://github.com/changesets/changesets) for release and version management

src/error.ts

@@ -0,0 +1,41 @@
+type ReactLocateErrorCode = 'NO_ITEMS_RETRIEVED';
+
+export class ReactLoqateError extends Error {
+  public code: ReactLocateErrorCode;
+
+  constructor({
+    message,
+    code,
+  }: {
+    message: string;
+    code: ReactLocateErrorCode;
+  }) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export class LoqateError extends Error {
+  public Cause: string;
+  public Description: string;
+  public Error: string;
+  public Resolution: string;
+
+  constructor({
+    Description,
+    Cause,
+    Error,
+    Resolution,
+  }: {
+    Description: string;
+    Cause: string;
+    Error: string;
+    Resolution: string;
+  }) {
+    super(Description);
+    this.Cause = Cause;
+    this.Description = Description;
+    this.Error = Error;
+    this.Resolution = Resolution;
+  }
+}

src/index.tsx

@@ -110,7 +110,7 @@ export interface Item {
   Highlight: string;
 }
 
-export interface ErrorItem {
+export interface LoqateErrorItem {
   Error: string;
   Description: string;
   Cause: string;
@@ -172,16 +172,13 @@ function AddressSearch(props: Props): JSX.Element {
           Items = res.Items;
         }
       } catch (e) {
+        setSuggestions([]);
         // error needs to be thrown in the render in order to be caught by the ErrorBoundary
         setError(() => {
           throw e;
         });
       }
 
-      if (Items.length) {
-        setSuggestions([]);
-      }
-
       onSelect(Items[0] as unknown as Address);
       return;
     }

src/utils/Loqate.ts

@@ -1,9 +1,10 @@
-import { ErrorItem, Item } from '..';
+import { Item, LoqateErrorItem } from '..';
 import {
   LOQATE_BASE_URL,
   LOQATE_FIND_URL,
   LOQATE_RETRIEVE_URL,
 } from '../constants/loqate';
+import { LoqateError, ReactLoqateError } from '../error';
 
 interface FindQuery {
   text: string;
@@ -13,7 +14,7 @@ interface FindQuery {
   containerId?: string;
 }
 
-type LoqateResponse = { Items?: Item[] | ErrorItem[] };
+type LoqateResponse = { Items?: Item[] | LoqateErrorItem[] };
 type LoqateNoErrorResponse = { Items?: Item[] };
 class Loqate {
   constructor(
@@ -29,7 +30,16 @@ class Loqate {
     const params = new URLSearchParams({ Id: id, Key: this.key });
     const url = `${this.baseUrl}/${LOQATE_RETRIEVE_URL}?${params.toString()}`;
     const res = await fetch(url).then<LoqateResponse>((r) => r.json());
-    return this.handleErrors(res);
+    const noLoqateErrosRes = this.handleErrors(res);
+
+    if (noLoqateErrosRes.Items && !noLoqateErrosRes.Items?.length) {
+      throw new ReactLoqateError({
+        code: 'NO_ITEMS_RETRIEVED',
+        message: `Loqate retrieve API did not return any address items for the provided ID ${id}`,
+      });
+    }
+
+    return noLoqateErrosRes;
   }
 
   public async find(query: FindQuery): Promise<LoqateNoErrorResponse> {
@@ -54,9 +64,9 @@ class Loqate {
   }
 
   private handleErrors = (res: LoqateResponse): LoqateNoErrorResponse => {
-    const firstItem: Item | ErrorItem | undefined = res?.Items?.[0];
+    const firstItem: Item | LoqateErrorItem | undefined = res?.Items?.[0];
     if (firstItem && Object.hasOwn(firstItem, 'Error')) {
-      throw new Error(`Loqate error: ${JSON.stringify(firstItem)}`);
+      throw new LoqateError(firstItem as LoqateErrorItem);
     }
 
     return res as LoqateNoErrorResponse;