get-or-throw 2.0.1 → 2.2.0

package/docs/.vitepress/config.mts

@@ -0,0 +1,47 @@
+import { defineConfig } from "vitepress";
+
+const hostname = "https://get-or-throw.codecompose.dev";
+
+export default defineConfig({
+  title: "Get-Or-Throw",
+  description:
+    "Safe indexed access for TypeScript with noUncheckedIndexedAccess",
+  base: "/",
+  cleanUrls: true,
+
+  sitemap: {
+    hostname,
+  },
+
+  transformHead({ pageData }) {
+    const canonicalUrl = `${hostname}/${pageData.relativePath}`
+      .replace(/index\.md$/, "")
+      .replace(/\.md$/, "");
+
+    return [["link", { rel: "canonical", href: canonicalUrl }]];
+  },
+
+  themeConfig: {
+    sidebar: [
+      {
+        text: "Guide",
+        items: [
+          { text: "Introduction", link: "/" },
+          { text: "Getting Started", link: "/getting-started" },
+          { text: "Usage", link: "/usage" },
+        ],
+      },
+      {
+        text: "Reference",
+        items: [
+          { text: "API", link: "/api" },
+          { text: "Why Get-Or-Throw?", link: "/reasoning" },
+        ],
+      },
+    ],
+
+    socialLinks: [
+      { icon: "github", link: "https://github.com/0x80/get-or-throw" },
+    ],
+  },
+});

package/docs/.vitepress/theme/CustomLayout.vue

@@ -0,0 +1,31 @@
+<script setup>
+import DefaultTheme from "vitepress/theme";
+
+const { Layout } = DefaultTheme;
+</script>
+
+<template>
+  <Layout>
+    <template #layout-bottom>
+      <footer class="custom-footer">
+        <p class="message">Released under the MIT License.</p>
+        <p class="copyright">Copyright &copy; Thijs Koerselman</p>
+      </footer>
+    </template>
+  </Layout>
+</template>
+
+<style scoped>
+.custom-footer {
+  border-top: 1px solid var(--vp-c-divider);
+  padding: 26px 32px;
+  text-align: center;
+  font-size: 14px;
+  color: var(--vp-c-text-2);
+}
+
+.custom-footer p {
+  margin: 0;
+  line-height: 24px;
+}
+</style>

package/docs/.vitepress/theme/custom.css

@@ -0,0 +1,3 @@
+.VPFeature .icon {
+  background-color: transparent !important;
+}

package/docs/.vitepress/theme/index.mts

@@ -0,0 +1,8 @@
+import DefaultTheme from "vitepress/theme";
+import CustomLayout from "./CustomLayout.vue";
+import "./custom.css";
+
+export default {
+  extends: DefaultTheme,
+  Layout: CustomLayout,
+};

package/docs/api.md

@@ -0,0 +1,65 @@
+# API Reference
+
+## `getOrThrow`
+
+Get a value from an object or array, throwing an error if the key or index does
+not exist or if the resulting value is `undefined`.
+
+### Signatures
+
+#### Array Access
+
+```ts
+function getOrThrow<T>(array: T[], index: number, errorMessage?: string): T;
+```
+
+#### Object Access
+
+```ts
+function getOrThrow<T extends object, K extends keyof T>(
+  object: T,
+  key: K,
+  errorMessage?: string,
+): NonNullable<T[K]>;
+```
+
+### Parameters
+
+| Parameter          | Type          | Description                                            |
+| ------------------ | ------------- | ------------------------------------------------------ |
+| `array` / `object` | `T[] \| T`    | The array or object to access.                         |
+| `index` / `key`    | `number \| K` | The index (for arrays) or key (for objects) to access. |
+| `errorMessage`     | `string`      | Optional custom error message.                         |
+
+### Returns
+
+The value at the given key or index, guaranteed to be defined. For objects, the
+return type is `NonNullable<T[K]>`.
+
+### Throws
+
+- If the index is out of bounds: `"Index {n} is out of bounds."`
+- If the key does not exist: `'Key "{key}" does not exist in the object.'`
+- If the value is `undefined`: `"Value at index {n} is undefined."` or
+  `'Value at key "{key}" is undefined.'`
+
+When a custom `errorMessage` is provided, it is used instead of the default
+messages.
+
+### Behavior
+
+- **Negative indexing**: Negative indices count from the end of the array.
+  `got(arr, -1)` returns the last element.
+- **Null values**: `null` is treated as a valid value and does not trigger an
+  error. Only `undefined` causes a throw.
+
+## `got`
+
+An alias for `getOrThrow`. Both functions are identical — use whichever you
+prefer.
+
+```ts
+import { got } from "get-or-throw";
+// is equivalent to
+import { getOrThrow } from "get-or-throw";
+```

package/docs/getting-started.md

@@ -0,0 +1,53 @@
+# Getting Started
+
+## Installation
+
+```bash
+pnpm add get-or-throw
+```
+
+Or use the equivalent for your package manager:
+
+```bash
+npm install get-or-throw
+yarn add get-or-throw
+```
+
+## Prerequisites
+
+Get-Or-Throw is designed to work with TypeScript's
+[noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig/#noUncheckedIndexedAccess)
+compiler option. While it works without it, the library is most useful when this
+option is enabled:
+
+```json
+{
+  "compilerOptions": {
+    "noUncheckedIndexedAccess": true
+  }
+}
+```
+
+With this setting, TypeScript treats every indexed access as potentially
+`undefined`, which is correct but can make code verbose. Get-Or-Throw provides a
+clean way to handle this.
+
+## Basic Usage
+
+The library exports two identical functions: `getOrThrow` and its shorter alias
+`got`.
+
+```ts
+import { got } from "get-or-throw";
+// or
+import { getOrThrow } from "get-or-throw";
+
+const arr = [1, 2, 3];
+const arrValue = got(arr, 1); // 2
+
+const obj = { a: 1, b: 2, c: 3 };
+const objValue = got(obj, "b"); // 2
+```
+
+Both functions behave identically — use whichever you prefer. The `got` alias is
+convenient for keeping code concise.

package/docs/index.md

@@ -0,0 +1,46 @@
+---
+layout: home
+
+hero:
+  name: Get-Or-Throw
+  tagline: Safe indexed access for TypeScript with noUncheckedIndexedAccess
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /getting-started
+    - theme: alt
+      text: Why Get-Or-Throw?
+      link: /reasoning
+
+features:
+  - title: Type-Safe Access
+    details: TypeScript assertions for type narrowing — the returned value is guaranteed to be defined.
+  - title: Arrays & Objects
+    details: Works with both objects and arrays, including support for negative indexing.
+  - title: Zero Dependencies
+    details: Tiny footprint with no external dependencies. Just the utility you need, nothing more.
+---
+
+## What is Get-Or-Throw?
+
+Get-Or-Throw provides 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`.
+
+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.
+
+```ts
+import { got } from "get-or-throw";
+
+const arr = [1, 2, 3];
+const arrValue = got(arr, 1); // 2 — type is `number`, not `number | undefined`
+
+const obj = { a: 1, b: 2, c: 3 };
+const objValue = got(obj, "b"); // 2
+```
+
+Instead of writing repetitive guard clauses or non-null assertions throughout
+your code, `got()` gives you a single, expressive call that either returns a
+defined value or throws a descriptive error.

package/docs/reasoning.md

@@ -0,0 +1,144 @@
+# Why Get-Or-Throw?
+
+## The Core Question
+
+When you access an array element or object property by a dynamic key, the value
+might not be there. TypeScript's `noUncheckedIndexedAccess` makes this explicit
+by adding `| undefined` to every indexed access. But how should you handle that
+`undefined`?
+
+There are two fundamental approaches:
+
+1. **Defensive programming** — check for `undefined` and handle the absence
+   gracefully
+2. **Fail-fast** — assert the value exists and throw immediately if it doesn't
+
+Get-Or-Throw is for the second case: when absence is a bug, not a valid state.
+
+## When to Use `got()`
+
+Use `got()` when a missing value means something has gone wrong — a business
+invariant has been violated, data is corrupt, or an earlier operation failed
+silently:
+
+```ts
+// The config must have a "database" section
+const dbConfig = got(config, "database");
+
+// There must be at least one item after filtering
+const first = got(filtered, 0, "Filter returned no results");
+
+// Parallel arrays must have the same length
+const label = got(labels, index);
+```
+
+In these cases, continuing with `undefined` would cause confusing downstream
+errors. Failing immediately with a clear message is better.
+
+## When NOT to Use `got()`
+
+When absence is a legitimate possibility, use native patterns instead:
+
+```ts
+// User might not exist — that's fine
+const user = users.find((u) => u.id === id);
+if (!user) {
+  return notFound();
+}
+
+// Optional configuration
+const timeout = config.timeout ?? 5000;
+
+// Array might be empty
+const first = items[0];
+if (first === undefined) {
+  showEmptyState();
+}
+```
+
+If the code after the access handles the `undefined` case meaningfully, you
+don't need `got()`.
+
+## When to Use Tuple Types Instead
+
+If the length of an array is statically known, TypeScript can track individual
+element types without `| undefined`. In those cases, prefer a tuple type over
+`got()`:
+
+```ts
+// TypeScript knows this has exactly 3 elements
+const rgb: [number, number, number] = [255, 128, 0];
+const red = rgb[0]; // number, not number | undefined
+```
+
+## Problems with Defensive Patterns
+
+### Silent Failures
+
+The most dangerous pattern is silently swallowing `undefined`:
+
+```ts
+// Bug: if arr[i] is undefined, localeCompare is called on undefined
+arr.sort((a, b) => {
+  const valA = mapping[a]; // possibly undefined
+  const valB = mapping[b]; // possibly undefined
+  return valA.localeCompare(valB); // runtime crash, no clear message
+});
+```
+
+With `got()`, the failure is immediate and descriptive:
+
+```ts
+arr.sort((a, b) => {
+  const valA = got(mapping, a);
+  const valB = got(mapping, b);
+  return valA.localeCompare(valB); // safe — both are guaranteed strings
+});
+```
+
+### Verbose Guard Clauses
+
+Without `got()`, you end up with repetitive null checks:
+
+```ts
+const value = obj[key];
+if (value === undefined) {
+  throw new Error(`Expected key "${key}" to exist`);
+}
+// now use value
+```
+
+This pattern repeated across a codebase adds significant noise. `got()` reduces
+it to a single expression:
+
+```ts
+const value = got(obj, key);
+```
+
+### Inconsistency
+
+Different developers write different error messages, check in different ways
+(`=== undefined`, `!= null`, `in` operator), or sometimes forget to check at
+all. `got()` provides a single consistent pattern.
+
+## Addressing Objections
+
+### "It's a dependency for something trivial"
+
+Get-Or-Throw has zero dependencies and is only a few lines of code. The value
+isn't in the implementation complexity — it's in the consistency and
+expressiveness it brings to a codebase. A shared convention is worth more than
+any individual helper function.
+
+### "Throwing crashes the app"
+
+That's the point. If a business invariant is violated, you _want_ to know
+immediately. The alternative — continuing with `undefined` — leads to corrupted
+data, confusing errors far from the source, and bugs that are hard to reproduce.
+
+### "I can just use the non-null assertion (`!`)"
+
+The non-null assertion (`value!`) tells TypeScript to trust you, but provides no
+runtime safety. If you're wrong, you get a confusing `undefined` error
+somewhere downstream. `got()` gives you both the type narrowing _and_ a clear
+runtime error at the point of access.

package/docs/usage.md

@@ -0,0 +1,85 @@
+# Usage
+
+The examples below use the `got` alias, but `getOrThrow` works identically.
+
+## Array Access
+
+```ts
+const arr = [1, 2, 3];
+const value = got(arr, 1); // 2
+```
+
+### Negative Indexing
+
+Negative indices count from the end of the array, similar to `Array.at()`:
+
+```ts
+const arr = [1, 2, 3];
+got(arr, -1); // 3
+got(arr, -2); // 2
+```
+
+### Out of Bounds
+
+Accessing an index outside the array bounds throws an error:
+
+```ts
+const arr = [1, 2, 3];
+got(arr, 3); // throws: "Index 3 is out of bounds."
+```
+
+## Object Access
+
+```ts
+const obj = { a: 1, b: 2, c: 3 };
+const value = got(obj, "b"); // 2
+```
+
+### Missing Keys
+
+Accessing a key that doesn't exist throws an error:
+
+```ts
+const obj = { a: 1, b: 2, c: 3 };
+got(obj, "d"); // throws: 'Key "d" does not exist in the object.'
+```
+
+## Null vs Undefined
+
+`null` is treated as a valid value and will not cause an error. Only `undefined`
+triggers a throw:
+
+```ts
+// null is valid
+const arr = [1, null, 3];
+got(arr, 1); // null
+
+const obj = { a: 1, b: null, c: 3 };
+got(obj, "b"); // null
+
+// undefined throws
+const arr2 = [1, undefined, 3];
+got(arr2, 1); // throws: "Value at index 1 is undefined."
+
+const obj2 = { a: 1, b: undefined, c: 3 };
+got(obj2, "b"); // throws: 'Value at key "b" is undefined.'
+```
+
+## Custom Error Messages
+
+You can provide a custom error message as the third argument:
+
+```ts
+const obj = { a: 1, b: 2, c: 3 };
+const key = "d";
+got(obj, key, `Failed to find ${key}`);
+// throws: "Failed to find d"
+```
+
+This is useful when you want to provide more context about why the value was
+expected to exist:
+
+```ts
+const users = [{ name: "Alice" }, { name: "Bob" }];
+const user = got(users, userIndex, `User at index ${userIndex} not found`);
+```

package/package.json

@@ -1,7 +1,23 @@
 {
   "name": "get-or-throw",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "A convenience function for safely getting values from dynamic objects and arrays",
+  "keywords": [
+    "indexed",
+    "noUncheckedIndexedAccess",
+    "typescript",
+    "unchecked"
+  ],
+  "homepage": "https://get-or-throw.codecompose.dev",
+  "bugs": {
+    "url": "https://github.com/0x80/get-or-throw/issues"
+  },
+  "license": "MIT",
+  "author": "Thijs Koerselman",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0x80/get-or-throw.git"
+  },
   "type": "module",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
@@ -11,40 +27,37 @@
       "require": "./dist/index.cjs"
     }
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/0x80/get-or-throw.git"
+  "publishConfig": {
+    "access": "public"
   },
-  "keywords": [
-    "typescript",
-    "indexed",
-    "unchecked",
-    "noUncheckedIndexedAccess"
-  ],
-  "author": "Thijs Koerselman",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/0x80/get-or-throw/issues"
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "clean": "del dist tsconfig.tsbuildinfo",
+    "prepare": "pnpm build",
+    "check-lint": "oxlint -c .oxlintrc.json --type-aware",
+    "format": "oxfmt .",
+    "check-format": "oxfmt --check .",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
-  "homepage": "https://github.com/0x80/get-or-throw#readme",
   "devDependencies": {
-    "@codecompose/typescript-config": "^1.1.2",
-    "@eslint/js": "^9.22.0",
+    "@codecompose/typescript-config": "^3.0.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-eslint": "^8.26.0",
+    "oxfmt": "^0.33.0",
+    "oxlint": "^1.48.0",
+    "oxlint-tsgolint": "^0.15.0",
+    "tsdown": "^0.12.0",
+    "typescript": "6.0.0-beta",
+    "vite": "^6.0.0",
+    "vitepress": "^1.6.0",
     "vitest": "^3.0.8"
   },
-  "scripts": {
-    "build": "tsup",
-    "clean": "del dist tsconfig.tsbuildinfo",
-    "lint": "eslint .",
-    "type-check": "tsc --noEmit",
-    "test": "vitest",
-    "format": "prettier --write ."
-  }
-}
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "packageManager": "pnpm@9.8.0+sha256.56a9e76b51796ca7f73b85e44cf83712862091f4d498c0ce4d5b7ecdc6ba18f7"
+}

package/src/get-or-throw.ts

@@ -13,7 +13,7 @@ export function getOrThrow<T extends object, K extends keyof T>(
   objOrArr: T,
   keyOrIndex: K,
   errorMessage?: string,
-): T[K];
+): NonNullable<T[K]>;
 export function getOrThrow<T>(
   objOrArr: T[],
   keyOrIndex: number,

package/tsconfig.json

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

package/tsdown.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: { index: "src/index.ts" },
+  format: ["esm", "cjs"],
+  target: "node20",
+  sourcemap: true,
+  dts: true,
+  clean: true,
+});

package/.prettierignore

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

package/.prettierrc.json

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

package/dist/index.mjs

@@ -1,21 +0,0 @@
-// src/get-or-throw.ts
-function getOrThrow(objOrArr, keyOrIndex) {
-  if (Array.isArray(objOrArr)) {
-    if (keyOrIndex in objOrArr) {
-      return objOrArr[keyOrIndex];
-    } else {
-      throw new Error(`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.`
-      );
-    }
-  }
-}
-export {
-  getOrThrow
-};

package/eslint.config.js

@@ -1,28 +0,0 @@
-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/tsup.config.ts

@@ -1,8 +0,0 @@
-import { defineConfig } from "tsup";
-
-export default defineConfig({
-  entry: ["src/index.ts"],
-  format: ["esm", "cjs"],
-  target: "node18",
-  dts: true,
-});