get-or-throw 1.4.0 → 1.5.1

package/.github/workflows/CODEOWNERS

@@ -0,0 +1 @@
+* @0x80

package/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        command: [lint, type-check, test]
+
+    name: ${{ matrix.command }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 8
+
+      - name: Get pnpm store directory
+        id: pnpm-cache
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          # First tries exact match with lock file hash. If not found,
+          # falls back to any cache starting with 'pnpm-store-'.
+          # This way we get exact cache on repeated runs, but can still
+          # use older cache as starting point when dependencies change.
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run ${{ matrix.command }}
+        run: pnpm ${{ matrix.command }}

package/.prettierignore

@@ -0,0 +1 @@
+*.yml

package/.prettierrc.json

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

package/README.md

@@ -1,19 +1,22 @@
-# get-or-throw
+# Get-Or-Throw / Got
 
-A convenience function for adhering to Typescript's `noUncheckedIndexedAccess`
-setting.
+A convenience function for safely accessing values in dynamic objects and
+arrays. It gets the value at a specified key or index, and throws an error if
+the resulting value is `undefined` or `null`. Optionally, you can set custom
+error message.
 
-Get a value from an object or array at the specified key or index. Throw an
-error if the key or index does not exist, or if the resulting value is undefined
-or null.
+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
 
-- Uses Typescript assertions for type narrowing.
+- Typescript assertions for type narrowing.
 - Works with both objects and arrays.
 - Supports negative indexing for arrays.
 - Allows for custom error messages.
 - Zero dependencies.
+- Provides `got` as alias for `getOrThrow`
 
 ## Installation
 
@@ -25,36 +28,39 @@ pnpm add get-or-throw
 
 ## Usage
 
+The example code below uses the `got` alias but `getOrThrow` is also available
+if you want to be more explicit.
+
 ```ts
 const arr = [1, 2, 3];
-console.log(getOrThrow(arr, 1)); // Output: 2
+const value = got(arr, 1); // Output: 2
 
 /** Support for negative indexing */
 const arr = [1, 2, 3];
-console.log(getOrThrow(arr, -1)); // Output: 3
+const value = got(arr, -1); // Output: 3
 
 /** This will throw an error: "Index 3 is out of bounds." */
-console.log(getOrThrow(arr, 3));
+const value = got(arr, 3);
 
 const obj = { a: 1, b: 2, c: 3 };
-console.log(getOrThrow(obj, "b")); // Output: 2
+const value = got(obj, "b"); // Output: 2
 
 /** This will throw an error: "Key "d" does not exist in the object." */
-console.log(getOrThrow(obj, "d"));
+const value = got(obj, "d");
 
 /** This will throw an error: "Failed to find d" */
 const key = "d";
-console.log(getOrThrow(obj, key, `Failed to find ${key}`));
+const value = got(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));
+const value = got(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));
+const value = got(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"));
+const value = got(obj, "b");
 ```

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,17 +35,16 @@ function getOrThrow(objOrArr, keyOrIndex, errorMessage) {
     }
     if (index >= 0 && index < length) {
       const value = objOrArr[index];
-      if (value !== void 0 && value !== null) {
-        return value;
-      } else if (value === void 0) {
+      if (value === void 0) {
         throw new Error(
           errorMessage ?? `Value at index ${String(keyOrIndex)} is undefined.`
         );
-      } else {
+      } else if (value === null) {
         throw new Error(
           errorMessage ?? `Value at index ${String(keyOrIndex)} is null.`
         );
       }
+      return value;
     } else {
       throw new Error(
         errorMessage ?? `Index ${String(keyOrIndex)} is out of bounds.`
@@ -73,5 +73,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

@@ -10,7 +10,6 @@
  * @throws An error if the key or index does not exist, or if the resulting
  *   value is undefined or null.
  */
-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>;
+declare function getOrThrow<T extends object, K extends keyof T>(objOrArr: T | (T | null)[], keyOrIndex: K | number, errorMessage?: string): NonNullable<T[K]> | NonNullable<T>;
 
-export { getOrThrow };
+export { getOrThrow, getOrThrow as got };

package/dist/index.d.ts

@@ -10,7 +10,6 @@
  * @throws An error if the key or index does not exist, or if the resulting
  *   value is undefined or null.
  */
-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>;
+declare function getOrThrow<T extends object, K extends keyof T>(objOrArr: T | (T | null)[], keyOrIndex: K | number, errorMessage?: string): NonNullable<T[K]> | NonNullable<T>;
 
-export { getOrThrow };
+export { getOrThrow, getOrThrow as got };

package/dist/index.js

@@ -8,17 +8,16 @@ function getOrThrow(objOrArr, keyOrIndex, errorMessage) {
     }
     if (index >= 0 && index < length) {
       const value = objOrArr[index];
-      if (value !== void 0 && value !== null) {
-        return value;
-      } else if (value === void 0) {
+      if (value === void 0) {
         throw new Error(
           errorMessage ?? `Value at index ${String(keyOrIndex)} is undefined.`
         );
-      } else {
+      } else if (value === null) {
         throw new Error(
           errorMessage ?? `Value at index ${String(keyOrIndex)} is null.`
         );
       }
+      return value;
     } else {
       throw new Error(
         errorMessage ?? `Index ${String(keyOrIndex)} is out of bounds.`
@@ -46,5 +45,6 @@ function getOrThrow(objOrArr, keyOrIndex, errorMessage) {
   }
 }
 export {
-  getOrThrow
+  getOrThrow,
+  getOrThrow as got
 };

package/eslint.config.js

@@ -0,0 +1,28 @@
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  {
+    ignores: [
+      "dist/**",
+      "node_modules/**",
+      /**
+       * Ignore all config files int the root. We should instead solve this with
+       * projectService setting so that these files can also be linted, but
+       * let's get this to work first
+       */
+      "*.{js,ts}",
+    ],
+  },
+  eslint.configs.recommended,
+  tseslint.configs.strictTypeChecked,
+  tseslint.configs.stylisticTypeChecked,
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "get-or-throw",
-  "version": "1.4.0",
-  "description": "A convenience function for adhering to Typescript's noUncheckedIndexedAccess rule",
+  "version": "1.5.1",
+  "description": "A convenience function for safely getting values from dynamic objects and arrays",
   "type": "module",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
@@ -29,15 +29,22 @@
   "homepage": "https://github.com/0x80/get-or-throw#readme",
   "devDependencies": {
     "@codecompose/typescript-config": "^1.1.2",
+    "@eslint/js": "^9.22.0",
     "del-cli": "^5.1.0",
+    "eslint": "^9.22.0",
     "prettier": "^3.3.3",
     "prettier-plugin-jsdoc": "^1.3.0",
     "tsup": "^8.3.0",
-    "typescript": "^5.6.2"
+    "typescript": "^5.6.2",
+    "typescript-eslint": "^8.26.0",
+    "vitest": "^3.0.8"
   },
   "scripts": {
     "build": "tsup",
     "clean": "del dist tsconfig.tsbuildinfo",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "lint": "eslint .",
+    "type-check": "tsc --noEmit",
+    "test": "vitest",
+    "format": "prettier --write ."
   }
 }

package/src/get-or-throw.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { getOrThrow, got } from "./get-or-throw";
+
+describe("get-or-throw", () => {
+  describe("array access", () => {
+    it("should get value at positive index", () => {
+      const arr = [1, 2, 3];
+      expect(got(arr, 1)).toBe(2);
+      expect(getOrThrow(arr, 1)).toBe(2);
+    });
+
+    it("should support negative indexing", () => {
+      const arr = [1, 2, 3];
+      expect(got(arr, -1)).toBe(3);
+      expect(got(arr, -2)).toBe(2);
+    });
+
+    it("should throw on out of bounds index", () => {
+      const arr = [1, 2, 3];
+      expect(() => got(arr, 3)).toThrow("Index 3 is out of bounds.");
+    });
+
+    it("should throw on null values", () => {
+      const arr = [1, null, 3];
+      expect(() => got(arr, 1)).toThrow("Value at index 1 is null.");
+    });
+
+    it("should throw on undefined values", () => {
+      const arr = [1, undefined, 3];
+      expect(() => got(arr, 1)).toThrow("Value at index 1 is undefined.");
+    });
+  });
+
+  describe("object access", () => {
+    it("should get value at existing key", () => {
+      const obj = { a: 1, b: 2, c: 3 };
+      expect(got(obj, "b")).toBe(2);
+      expect(getOrThrow(obj, "b")).toBe(2);
+    });
+
+    it("should throw on non-existent key", () => {
+      const obj = { a: 1, b: 2, c: 3 };
+      expect(() => got(obj, "d" as keyof typeof obj)).toThrow(
+        'Key "d" does not exist in the object.',
+      );
+    });
+
+    it("should throw on null values", () => {
+      const obj = { a: 1, b: null, c: 3 };
+      expect(() => got(obj, "b")).toThrow('Value at key "b" is null.');
+    });
+
+    it("should throw on undefined values", () => {
+      const obj = { a: 1, b: undefined, c: 3 };
+      expect(() => got(obj, "b")).toThrow('Value at key "b" is undefined.');
+    });
+  });
+
+  describe("custom error messages", () => {
+    it("should use custom error message when provided", () => {
+      const obj = { a: 1, b: 2, c: 3 };
+      const key = "d";
+      expect(() =>
+        got(obj, key as keyof typeof obj, `Failed to find ${key}`),
+      ).toThrow("Failed to find d");
+    });
+  });
+});

package/src/get-or-throw.ts

@@ -11,19 +11,9 @@
  *   value is undefined or null.
  */
 export function getOrThrow<T extends object, K extends keyof T>(
-  objOrArr: T,
-  keyOrIndex: K,
-  errorMessage?: string
-): NonNullable<T[K]>;
-export function getOrThrow<T>(
-  objOrArr: T[],
-  keyOrIndex: number,
-  errorMessage?: string
-): NonNullable<T>;
-export function getOrThrow<T extends object, K extends keyof T>(
-  objOrArr: T | T[],
+  objOrArr: T | (T | null)[],
   keyOrIndex: K | number,
-  errorMessage?: string
+  errorMessage?: string,
 ): NonNullable<T[K]> | NonNullable<T> {
   if (Array.isArray(objOrArr)) {
     const length = objOrArr.length;
@@ -37,20 +27,19 @@ export function getOrThrow<T extends object, K extends keyof T>(
     if (index >= 0 && index < length) {
       const value = objOrArr[index];
 
-      if (value !== undefined && value !== null) {
-        return value as NonNullable<T>;
-      } else if (value === undefined) {
+      if (value === undefined) {
         throw new Error(
-          errorMessage ?? `Value at index ${String(keyOrIndex)} is undefined.`
+          errorMessage ?? `Value at index ${String(keyOrIndex)} is undefined.`,
         );
-      } else {
+      } else if (value === null) {
         throw new Error(
-          errorMessage ?? `Value at index ${String(keyOrIndex)} is null.`
+          errorMessage ?? `Value at index ${String(keyOrIndex)} is null.`,
         );
       }
+      return value;
     } else {
       throw new Error(
-        errorMessage ?? `Index ${String(keyOrIndex)} is out of bounds.`
+        errorMessage ?? `Index ${String(keyOrIndex)} is out of bounds.`,
       );
     }
   } else {
@@ -61,18 +50,21 @@ export function getOrThrow<T extends object, K extends keyof T>(
         return value as NonNullable<T[K]>;
       } else if (value === undefined) {
         throw new Error(
-          errorMessage ?? `Value at key "${String(keyOrIndex)}" is undefined.`
+          errorMessage ?? `Value at key "${String(keyOrIndex)}" is undefined.`,
         );
       } else {
         throw new Error(
-          errorMessage ?? `Value at key "${String(keyOrIndex)}" is null.`
+          errorMessage ?? `Value at key "${String(keyOrIndex)}" is null.`,
         );
       }
     } else {
       throw new Error(
         errorMessage ??
-          `Key "${String(keyOrIndex)}" does not exist in the object.`
+          `Key "${String(keyOrIndex)}" does not exist in the object.`,
       );
     }
   }
 }
+
+/** Export the same function under the alias 'got' */
+export { getOrThrow as got };

package/tsconfig.json

@@ -1,3 +1,6 @@
 {
-  "extends": "@codecompose/typescript-config/single-library.json"
+  "extends": "@codecompose/typescript-config/single-library.json",
+  "compilerOptions": {
+    "rootDir": "." // Needed for CI for some reason
+  }
 }