get-or-throw 1.0.0 → 1.2.0

package/.prettierrc.json

@@ -0,0 +1,5 @@
+{
+  "trailingComma": "es5",
+  "proseWrap": "always",
+  "plugins": ["./node_modules/prettier-plugin-jsdoc/dist/index.js"]
+}

package/README.md

@@ -1,6 +1,14 @@
 # get-or-throw
 
-A convenience function for adhering to Typescript's `noUncheckedIndexedAccess` setting.
+A convenience function for adhering to Typescript's `noUncheckedIndexedAccess`
+setting.
+
+## Features
+
+- Uses Typescript assertions for type narrowing.
+- Works with both objects and arrays.
+- Supports negative indexing for arrays.
+- Allows for custom error messages.
 
 ## Installation
 
@@ -16,6 +24,10 @@ pnpm add get-or-throw
 const arr = [1, 2, 3];
 console.log(getOrThrow(arr, 1)); // Output: 2
 
+/** Support for negative indexing */
+const arr = [1, 2, 3];
+console.log(getOrThrow(arr, -1)); // Output: 3
+
 /** This will throw an error: "Index 3 is out of bounds." */
 console.log(getOrThrow(arr, 3));
 
@@ -24,4 +36,8 @@ console.log(getOrThrow(obj, "b")); // Output: 2
 
 /** This will throw an error: "Key "d" does not exist in the object." */
 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}`));
 ```

package/dist/index.cjs

@@ -25,19 +25,26 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/get-or-throw.ts
-function getOrThrow(objOrArr, keyOrIndex) {
+function getOrThrow(objOrArr, keyOrIndex, errorMessage) {
   if (Array.isArray(objOrArr)) {
-    if (keyOrIndex in objOrArr) {
-      return objOrArr[keyOrIndex];
+    const length = objOrArr.length;
+    let index = keyOrIndex;
+    if (index < 0) {
+      index = length + index;
+    }
+    if (index >= 0 && index < length) {
+      return objOrArr[index];
     } else {
-      throw new Error(`Index ${String(keyOrIndex)} is out of bounds.`);
+      throw new Error(
+        errorMessage ?? `Index ${String(keyOrIndex)} is out of bounds.`
+      );
     }
   } else {
     if (keyOrIndex in objOrArr) {
       return objOrArr[keyOrIndex];
     } else {
       throw new Error(
-        `Key "${String(keyOrIndex)}" does not exist in the object.`
+        errorMessage ?? `Key "${String(keyOrIndex)}" does not exist in the object.`
       );
     }
   }

package/dist/index.d.cts

@@ -1,11 +1,13 @@
 /**
- * Get a value from an object or array, or throw an error if the key or index does not exist.
+ * Get a value from an object or array, or throw an error if the key or index
+ * does not exist.
+ *
  * @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.
  * @throws An error if the key or index does not exist.
  */
-declare function getOrThrow<T extends object, K extends keyof T>(obj: T, key: K): T[K];
-declare function getOrThrow<T>(arr: T[], index: number): T;
+declare function getOrThrow<T extends object, K extends keyof T>(objOrArr: T | T[], keyOrIndex: K | number, errorMessage?: string): T[K] | T;
 
 export { getOrThrow };

package/dist/index.d.ts

@@ -1,11 +1,13 @@
 /**
- * Get a value from an object or array, or throw an error if the key or index does not exist.
+ * Get a value from an object or array, or throw an error if the key or index
+ * does not exist.
+ *
  * @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.
  * @throws An error if the key or index does not exist.
  */
-declare function getOrThrow<T extends object, K extends keyof T>(obj: T, key: K): T[K];
-declare function getOrThrow<T>(arr: T[], index: number): T;
+declare function getOrThrow<T extends object, K extends keyof T>(objOrArr: T | T[], keyOrIndex: K | number, errorMessage?: string): T[K] | T;
 
 export { getOrThrow };

package/dist/index.js

@@ -1,17 +1,24 @@
 // src/get-or-throw.ts
-function getOrThrow(objOrArr, keyOrIndex) {
+function getOrThrow(objOrArr, keyOrIndex, errorMessage) {
   if (Array.isArray(objOrArr)) {
-    if (keyOrIndex in objOrArr) {
-      return objOrArr[keyOrIndex];
+    const length = objOrArr.length;
+    let index = keyOrIndex;
+    if (index < 0) {
+      index = length + index;
+    }
+    if (index >= 0 && index < length) {
+      return objOrArr[index];
     } else {
-      throw new Error(`Index ${String(keyOrIndex)} is out of bounds.`);
+      throw new Error(
+        errorMessage ?? `Index ${String(keyOrIndex)} is out of bounds.`
+      );
     }
   } else {
     if (keyOrIndex in objOrArr) {
       return objOrArr[keyOrIndex];
     } else {
       throw new Error(
-        `Key "${String(keyOrIndex)}" does not exist in the object.`
+        errorMessage ?? `Key "${String(keyOrIndex)}" does not exist in the object.`
       );
     }
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "get-or-throw",
-  "version": "1.0.0",
-  "description": "A convenience function for adhering to TS noUncheckedIndexedAccess",
+  "version": "1.2.0",
+  "description": "A convenience function for adhering to Typescript's noUncheckedIndexedAccess rule",
   "type": "module",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
@@ -16,6 +16,9 @@
     "url": "git+https://github.com/0x80/get-or-throw.git"
   },
   "keywords": [
+    "typescript",
+    "indexed",
+    "unchecked",
     "noUncheckedIndexedAccess"
   ],
   "author": "Thijs Koerselman",
@@ -26,6 +29,8 @@
   "homepage": "https://github.com/0x80/get-or-throw#readme",
   "devDependencies": {
     "@codecompose/typescript-config": "^1.0.5",
+    "prettier": "^3.3.3",
+    "prettier-plugin-jsdoc": "^1.3.0",
     "tsup": "^8.3.0",
     "typescript": "^5.6.2"
   },

package/src/get-or-throw.ts

@@ -1,31 +1,41 @@
 /**
- * Get a value from an object or array, or throw an error if the key or index does not exist.
+ * Get a value from an object or array, or throw an error if the key or index
+ * does not exist.
+ *
  * @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.
  * @throws An error if the key or index does not exist.
  */
-export function getOrThrow<T extends object, K extends keyof T>(
-  obj: T,
-  key: K
-): T[K];
-export function getOrThrow<T>(arr: T[], index: number): T;
 export function getOrThrow<T extends object, K extends keyof T>(
   objOrArr: T | T[],
-  keyOrIndex: K | number
+  keyOrIndex: K | number,
+  errorMessage?: string
 ): T[K] | T {
   if (Array.isArray(objOrArr)) {
-    if (keyOrIndex in objOrArr) {
-      return objOrArr[keyOrIndex as number]!;
+    const length = objOrArr.length;
+    let index = keyOrIndex as number;
+
+    // Handle negative indexing
+    if (index < 0) {
+      index = length + index;
+    }
+
+    if (index >= 0 && index < length) {
+      return objOrArr[index]!;
     } else {
-      throw new Error(`Index ${String(keyOrIndex)} is out of bounds.`);
+      throw new Error(
+        errorMessage ?? `Index ${String(keyOrIndex)} is out of bounds.`
+      );
     }
   } else {
     if (keyOrIndex in objOrArr) {
       return objOrArr[keyOrIndex as K];
     } else {
       throw new Error(
-        `Key "${String(keyOrIndex)}" does not exist in the object.`
+        errorMessage ??
+          `Key "${String(keyOrIndex)}" does not exist in the object.`
       );
     }
   }

package/tsconfig.json

@@ -3,6 +3,5 @@
   "compilerOptions": {
     "composite": false,
     "incremental": false
-  },
-  "include": ["src"]
+  }
 }