get-or-throw 1.3.0 → 1.5.0

package/README.md

@@ -1,7 +1,13 @@
 # get-or-throw
 
-A convenience function for adhering to Typescript's `noUncheckedIndexedAccess`
-setting.
+A simple convenience function for safely accessing values in objects and arrays.
+It gets a value from an object or array at a specified key or index, and throw
+an error if the resulting value is `undefined` or `null`. Optionally, you can
+set custom error message.
+
+This was created to make it easy to adhere to Typescript's
+[noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig/#noUncheckedIndexedAccess)
+setting, which is recommended for strict type checking.
 
 ## Features
 
@@ -10,6 +16,7 @@ setting.
 - Supports negative indexing for arrays.
 - Allows for custom error messages.
 - Zero dependencies.
+- Provides `got` as alias for `getOrThrow`
 
 ## Installation
 
@@ -41,4 +48,18 @@ console.log(getOrThrow(obj, "d"));
 /** This will throw an error: "Failed to find d" */
 const key = "d";
 console.log(getOrThrow(obj, key, `Failed to find ${key}`));
+
+/** This will throw an error: "Value at index 1 is undefined or null." */
+const arr = [1, null, 3];
+console.log(getOrThrow(arr, 1));
+
+/** This will throw an error: "Value at index 1 is undefined or null." */
+const arr = [1, undefined, 3];
+console.log(getOrThrow(arr, 1));
+
+/** This will throw an error: "Value at key 'b' is undefined or null." */
+const obj = { a: 1, b: undefined, c: 3 };
+console.log(getOrThrow(obj, "b"));
 ```
+
+## Alias

package/dist/index.cjs

@@ -20,7 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  getOrThrow: () => getOrThrow
+  getOrThrow: () => getOrThrow,
+  got: () => getOrThrow
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -34,12 +35,16 @@ function getOrThrow(objOrArr, keyOrIndex, errorMessage) {
     }
     if (index >= 0 && index < length) {
       const value = objOrArr[index];
-      if (value === void 0) {
+      if (value !== void 0 && value !== null) {
+        return value;
+      } else if (value === void 0) {
         throw new Error(
           errorMessage ?? `Value at index ${String(keyOrIndex)} is undefined.`
         );
       } else {
-        return value;
+        throw new Error(
+          errorMessage ?? `Value at index ${String(keyOrIndex)} is null.`
+        );
       }
     } else {
       throw new Error(
@@ -49,12 +54,16 @@ function getOrThrow(objOrArr, keyOrIndex, errorMessage) {
   } else {
     if (keyOrIndex in objOrArr) {
       const value = objOrArr[keyOrIndex];
-      if (value === void 0) {
+      if (value !== void 0 && value !== null) {
+        return value;
+      } else if (value === void 0) {
         throw new Error(
           errorMessage ?? `Value at key "${String(keyOrIndex)}" is undefined.`
         );
       } else {
-        return value;
+        throw new Error(
+          errorMessage ?? `Value at key "${String(keyOrIndex)}" is null.`
+        );
       }
     } else {
       throw new Error(
@@ -65,5 +74,6 @@ function getOrThrow(objOrArr, keyOrIndex, errorMessage) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  getOrThrow
+  getOrThrow,
+  got
 });

package/dist/index.d.cts

@@ -1,15 +1,16 @@
 /**
  * Get a value from an object or array, and throw an error if the key or index
- * does not exist or if the resulting value is undefined.
+ * does not exist or if the resulting value is undefined or null.
  *
  * @param objOrArr The object or array to get the value from.
  * @param keyOrIndex The key or index to get the value from.
  * @param errorMessage Optional error message to include in the error thrown.
- * @returns The value at the given key or index.
+ * @returns The value at the given key or index, guaranteed to be non-null and
+ *   non-undefined.
  * @throws An error if the key or index does not exist, or if the resulting
- *   value is undefined.
+ *   value is undefined or null.
  */
-declare function getOrThrow<T extends object, K extends keyof T>(obj: T, key: K, errorMessage?: string): T[K];
-declare function getOrThrow<T>(arr: T[], index: number, errorMessage?: string): T;
+declare function getOrThrow<T extends object, K extends keyof T>(objOrArr: T, keyOrIndex: K, errorMessage?: string): NonNullable<T[K]>;
+declare function getOrThrow<T>(objOrArr: T[], keyOrIndex: number, errorMessage?: string): NonNullable<T>;
 
-export { getOrThrow };
+export { getOrThrow, getOrThrow as got };

package/dist/index.d.ts

@@ -1,15 +1,16 @@
 /**
  * Get a value from an object or array, and throw an error if the key or index
- * does not exist or if the resulting value is undefined.
+ * does not exist or if the resulting value is undefined or null.
  *
  * @param objOrArr The object or array to get the value from.
  * @param keyOrIndex The key or index to get the value from.
  * @param errorMessage Optional error message to include in the error thrown.
- * @returns The value at the given key or index.
+ * @returns The value at the given key or index, guaranteed to be non-null and
+ *   non-undefined.
  * @throws An error if the key or index does not exist, or if the resulting
- *   value is undefined.
+ *   value is undefined or null.
  */
-declare function getOrThrow<T extends object, K extends keyof T>(obj: T, key: K, errorMessage?: string): T[K];
-declare function getOrThrow<T>(arr: T[], index: number, errorMessage?: string): T;
+declare function getOrThrow<T extends object, K extends keyof T>(objOrArr: T, keyOrIndex: K, errorMessage?: string): NonNullable<T[K]>;
+declare function getOrThrow<T>(objOrArr: T[], keyOrIndex: number, errorMessage?: string): NonNullable<T>;
 
-export { getOrThrow };
+export { getOrThrow, getOrThrow as got };

package/dist/index.js

@@ -8,12 +8,16 @@ function getOrThrow(objOrArr, keyOrIndex, errorMessage) {
     }
     if (index >= 0 && index < length) {
       const value = objOrArr[index];
-      if (value === void 0) {
+      if (value !== void 0 && value !== null) {
+        return value;
+      } else if (value === void 0) {
         throw new Error(
           errorMessage ?? `Value at index ${String(keyOrIndex)} is undefined.`
         );
       } else {
-        return value;
+        throw new Error(
+          errorMessage ?? `Value at index ${String(keyOrIndex)} is null.`
+        );
       }
     } else {
       throw new Error(
@@ -23,12 +27,16 @@ function getOrThrow(objOrArr, keyOrIndex, errorMessage) {
   } else {
     if (keyOrIndex in objOrArr) {
       const value = objOrArr[keyOrIndex];
-      if (value === void 0) {
+      if (value !== void 0 && value !== null) {
+        return value;
+      } else if (value === void 0) {
         throw new Error(
           errorMessage ?? `Value at key "${String(keyOrIndex)}" is undefined.`
         );
       } else {
-        return value;
+        throw new Error(
+          errorMessage ?? `Value at key "${String(keyOrIndex)}" is null.`
+        );
       }
     } else {
       throw new Error(
@@ -38,5 +46,6 @@ function getOrThrow(objOrArr, keyOrIndex, errorMessage) {
   }
 }
 export {
-  getOrThrow
+  getOrThrow,
+  getOrThrow as got
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-or-throw",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "A convenience function for adhering to Typescript's noUncheckedIndexedAccess rule",
   "type": "module",
   "main": "dist/index.cjs",

package/src/get-or-throw.ts

@@ -1,34 +1,35 @@
 /**
  * Get a value from an object or array, and throw an error if the key or index
- * does not exist or if the resulting value is undefined.
+ * does not exist or if the resulting value is undefined or null.
  *
  * @param objOrArr The object or array to get the value from.
  * @param keyOrIndex The key or index to get the value from.
  * @param errorMessage Optional error message to include in the error thrown.
- * @returns The value at the given key or index.
+ * @returns The value at the given key or index, guaranteed to be non-null and
+ *   non-undefined.
  * @throws An error if the key or index does not exist, or if the resulting
- *   value is undefined.
+ *   value is undefined or null.
  */
 export function getOrThrow<T extends object, K extends keyof T>(
-  obj: T,
-  key: K,
+  objOrArr: T,
+  keyOrIndex: K,
   errorMessage?: string
-): T[K];
+): NonNullable<T[K]>;
 export function getOrThrow<T>(
-  arr: T[],
-  index: number,
+  objOrArr: T[],
+  keyOrIndex: number,
   errorMessage?: string
-): T;
+): NonNullable<T>;
 export function getOrThrow<T extends object, K extends keyof T>(
   objOrArr: T | T[],
   keyOrIndex: K | number,
   errorMessage?: string
-): T[K] | T {
+): NonNullable<T[K]> | NonNullable<T> {
   if (Array.isArray(objOrArr)) {
     const length = objOrArr.length;
     let index = keyOrIndex as number;
 
-    // Handle negative indexing
+    /** Allow for negative indexing. */
     if (index < 0) {
       index = length + index;
     }
@@ -36,12 +37,16 @@ export function getOrThrow<T extends object, K extends keyof T>(
     if (index >= 0 && index < length) {
       const value = objOrArr[index];
 
-      if (value === undefined) {
+      if (value !== undefined && value !== null) {
+        return value as NonNullable<T>;
+      } else if (value === undefined) {
         throw new Error(
           errorMessage ?? `Value at index ${String(keyOrIndex)} is undefined.`
         );
       } else {
-        return value;
+        throw new Error(
+          errorMessage ?? `Value at index ${String(keyOrIndex)} is null.`
+        );
       }
     } else {
       throw new Error(
@@ -52,12 +57,16 @@ export function getOrThrow<T extends object, K extends keyof T>(
     if (keyOrIndex in objOrArr) {
       const value = objOrArr[keyOrIndex as K];
 
-      if (value === undefined) {
+      if (value !== undefined && value !== null) {
+        return value as NonNullable<T[K]>;
+      } else if (value === undefined) {
         throw new Error(
           errorMessage ?? `Value at key "${String(keyOrIndex)}" is undefined.`
         );
       } else {
-        return value;
+        throw new Error(
+          errorMessage ?? `Value at key "${String(keyOrIndex)}" is null.`
+        );
       }
     } else {
       throw new Error(
@@ -67,3 +76,6 @@ export function getOrThrow<T extends object, K extends keyof T>(
     }
   }
 }
+
+/** Export the same function under the alias 'got' */
+export { getOrThrow as got };