Add table method findOrNull (#87)

So that the caller can easily implement alternative logic.

.changeset/fuzzy-kings-repair.md

@@ -0,0 +1,5 @@
+---
+"@qualifyze/airtable": minor
+---
+
+Add table method `findOrNull` which returns `null` when the record is not found by id.

integration.ts

@@ -56,11 +56,9 @@ const validateNotFound = async <R>(target: () => Promise<R>) => {
   try {
     await target();
     throw new Error("Expected an error here");
-    // TODO There should be a method to return null instead of an error when record is not found
-    // This is a quickfix to implicit => explicit any in the latest typescript version
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  } catch (error: any) {
-    if (error.statusCode !== 404) throw error;
+  } catch (err: unknown) {
+    if (err instanceof Airtable.Error && err.error === "NOT_FOUND") return;
+    throw err;
   }
 };
 
@@ -115,6 +113,13 @@ const main = async () => {
     console.log("Checking table.find...");
     validateRecord(await table.find(multipleRecords[0].id), multipleRecords[0]);
 
+    console.log("Checking table.findOrNull...");
+
+    validateRecord(
+      (await table.findOrNull(multipleRecords[0].id)) ?? { id: "wrong" },
+      multipleRecords[0]
+    );
+
     console.log("Checking table.update for multiple records...");
 
     const updatedRecords = await table.update([
@@ -195,9 +200,15 @@ const main = async () => {
   } finally {
     console.log("Cleaning up with table.destroy for multiple records...");
     await table.destroy(multipleRecords.map((record) => record.id));
+  }
+
+  console.log("Checking with table.find for non-existing record...");
+  await validateNotFound(() => table.find(multipleRecords[0].id));
+
+  console.log("Checking with table.findOne for non-existing record...");
 
-    console.log("Checking with table.find for non-existing record...");
-    await validateNotFound(() => table.find(multipleRecords[0].id));
+  if ((await table.findOrNull(multipleRecords[0].id)) !== null) {
+    throw new Error(`The method findOrNull didn't return null as expected`);
   }
 
   // TODO Test table.select & validation

src/table.ts

@@ -1,3 +1,5 @@
+import Airtable from "airtable";
+
 import { FieldsValidator, UnknownFields } from "./fields";
 import { ActionPoint, ActionPointOptions } from "./action-point";
 import { ValidationContext } from "./validator";
@@ -74,6 +76,18 @@ export class Table<Fields extends UnknownFields>
     return new AirtableRecordDraft(this, recordId).fetch();
   }
 
+  async findOrNull(recordId: string): Promise<AirtableRecord<Fields> | null> {
+    try {
+      // async/await are needed here to catch the error
+      return await new AirtableRecordDraft(this, recordId).fetch();
+    } catch (err: unknown) {
+      if (err instanceof Airtable.Error && err.error === "NOT_FOUND") {
+        return null;
+      }
+      throw err;
+    }
+  }
+
   select(query: SelectQueryParams<Fields> = {}): SelectQuery<Fields> {
     return new SelectQuery<Fields>(this, query);
   }