feat: replace throwIfNull for throwIfNil

README.md

@@ -63,18 +63,18 @@ const updatedCount: number = await parseResult(collection.updateMany({}, { $set:
 const deletedCount: number = await parseResult(collection.deleteMany({ name: 'Charles' }));
 ```
 
-### Throw error if null
+### Throw error if null or undefined
 
-Sometimes you are fine with getting a null when you cannot find, update or delete a document, but sometimes you want to throw an error immediately.
+Sometimes you are fine with getting a null or undefined when you cannot find, update or delete a document, but sometimes you want to throw an error immediately.
 
-The **throwIfNull()** function will throw the provided error if the result of a promise returns null:
+The **throwIfNil()** function will throw the provided error if the result of a promise returns null or undefined:
 
 ```typescript
-import { throwIfNull } from '@valbo/mongodb-functions';
+import { throwIfNil } from '@valbo/mongodb-functions';
 
 const notFoundError = new Error('user not found');
 
-const user: User = await throwIfNull(notFoundError, parseResult(collection.findOneAndUpdate({ name: 'Charles' }, { $set: { name: 'Charlie' } })));
+const user: User = await throwIfNil(notFoundError, parseResult(collection.findOneAndUpdate({ name: 'Charles' }, { $set: { name: 'Charlie' } })));
 // throws because document does not exist
 ```
 
@@ -107,7 +107,7 @@ The **withTransaction()** function of this package combines the functionality of
 import { withTransaction } from '@valbo/mongodb-functions';
 
 const newUser: User | null = await withTransaction(client, async session => {
-  const parent: User = await throwIfNull(notFoundError, collection.findOneAndUpdate({ name: 'Robert' }, { $set: { children: 1 } }, { returnOriginal: false, session }));
+  const parent: User = await throwIfNil(notFoundError, collection.findOneAndUpdate({ name: 'Robert' }, { $set: { children: 1 } }, { returnOriginal: false, session }));
   return await throwIfDuplicated(notUniqueError, collection.insertOne({ name: 'Daisy', parent: parent.name }, { session }));
 });
 ```

src/index.ts

@@ -1,4 +1,4 @@
 export { parseResult } from './parse-result';
 export { Transaction, withTransaction } from './with-transaction';
-export { throwIfNull } from './throw-if-null';
+export { throwIfNil } from './throw-if-nil';
 export { throwIfDuplicated } from './throw-if-duplicated';

src/throw-if-nil.ts

@@ -0,0 +1,5 @@
+export async function throwIfNil<T>(ifNilError: Error, promise: Promise<T | null | undefined>): Promise<T> {
+  const result = await promise;
+  if (result === null || result === undefined) throw ifNilError;
+  return result;
+}

test/throw-if-nil.test.ts

@@ -0,0 +1,21 @@
+import { throwIfNil } from '../src/throw-if-nil';
+
+describe('throwIfNil()', () => {
+  const ifNilError = Error('value is null or undefined');
+
+  test('should return the value when it is not null', async () => {
+    const input = Promise.resolve(42);
+    const output = await throwIfNil(ifNilError, input);
+    expect(output).toBe(42);
+  });
+
+  test('should throw when the value is null', async () => {
+    const input = Promise.resolve(null);
+    await expect(throwIfNil(ifNilError, input)).rejects.toThrow(ifNilError);
+  });
+
+  test('should throw when the value is undefined', async () => {
+    const input = Promise.resolve(undefined);
+    await expect(throwIfNil(ifNilError, input)).rejects.toThrow(ifNilError);
+  });
+});