Get-Or-Throw / Got

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. Optionally, you can set a custom error message.

This was created to make it easy to adhere to Typescript's noUncheckedIndexedAccess setting, which is recommended for strict type checking.

Features

• 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

pnpm add get-or-throw

...or use the equivalent for your package manager.

Usage

The example code below uses the got alias but getOrThrow is also available if you want to be more explicit.

const arr = [1, 2, 3];
const value = got(arr, 1); // Output: 2

/** Support for negative indexing */
const arr = [1, 2, 3];
const value = got(arr, -1); // Output: 3

/** This will throw an error: "Index 3 is out of bounds." */
const value = got(arr, 3);

const obj = { a: 1, b: 2, c: 3 };
const value = got(obj, "b"); // Output: 2

/** This will throw an error: "Key "d" does not exist in the object." */
const value = got(obj, "d");

/** This will throw an error: "Failed to find d" */
const key = "d";
const value = got(obj, key, `Failed to find ${key}`);

/** Null is a valid value */
const arr = [1, null, 3];
const value = got(arr, 1); // Output: null

/** This will throw an error: "Value at index 1 is undefined." */
const arr = [1, undefined, 3];
const value = got(arr, 1);

/** Null is a valid value */
const obj = { a: 1, b: null, c: 3 };
const value = got(obj, "b"); // Output: null

/** This will throw an error: "Value at key 'b' is undefined." */
const obj = { a: 1, b: undefined, c: 3 };
const value = got(obj, "b");