@williamthorsen/toolbelt.arrays 4.0.1 → 5.0.1

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## 5.0.1 — 2026-08-16
+
+### Tests
+
+- Drop expect-type in favor of expectTypeOf (#175)
+
+  Replaces all imports of `expectTypeOf` from `expect-type` with the same import from `vitest`. Previously there had been imports from both libraries. `expect-type` is removed as a dependency.
+
+## 5.0.0 — 2026-08-15
+
+### Features
+
+- 🚨 **Breaking:** Fix unsound narrowing in `getAtIndexOrThrow` and rename it to `getItemAtIndexOrThrow` (#152)
+
+  Fixes an issue where `getAtIndexOrThrow` could falsely treat an `undefined` return value as satisfying a return type that excluded `undefined`. The function now throws a `RangeError` if the array holds no item at the index and a `TypeError` if the index is not a safe integer. `undefined` is a valid return value if the input array's type allows `undefined` elements. The function is renamed `getItemAtIndexOrThrow`.
+
+  Separately, `findOrThrow` now decides a match by its predicate rather than by the value it found, so an element is not treated as not found merely because it is falsy. Its return type is now `T` rather than `NonNullable<T>`.
+
+  Migration: Consumers of `@williamthorsen/toolbelt.arrays/candidate` import `getItemAtIndexOrThrow` in place of `getAtIndexOrThrow`.
+
+- 🚨 **Breaking:** Rename `findOrThrow` to `findItemOrThrow` and document it (#153)
+
+  Renames `findOrThrow` to `findItemOrThrow` in `@williamthorsen/toolbelt.arrays` for consistency with repo naming conventions.
+
+  Migration: Consumers import `findItemOrThrow` from `@williamthorsen/toolbelt.arrays/candidate`. The signature and behavior are unchanged.
+
 ## 4.0.1 — 2026-08-13
 
 ### Tooling

package/README.md

@@ -6,4 +6,92 @@ Array utilities.
 
 ## Installation
 
+```sh
+pnpm add @williamthorsen/toolbelt.arrays
+```
+
 Requires Node.js 24 or later.
+
+`findItemOrThrow` and `getItemAtIndexOrThrow` are candidate tier: imported from `@williamthorsen/toolbelt.arrays/candidate` rather than the package root, and subject to change.
+
+## `findItemOrThrow`
+
+```ts
+findItemOrThrow<T>(
+  items: ReadonlyArray<T>,
+  predicate: (item: T, index: number, items: ReadonlyArray<T>) => boolean,
+  options?: { label?: string },
+): T;
+```
+
+Returns the first item satisfying the predicate, or throws if no item does.
+
+```ts
+import { findItemOrThrow } from '@williamthorsen/toolbelt.arrays/candidate';
+
+const account = findItemOrThrow(accounts, (candidate) => candidate.isActive, { label: 'active account' });
+```
+
+Its value is narrowing. `Array.prototype.find` returns `T | undefined`, so every call needs a check or an assertion before the value is usable. This collapses that to `T` or throws, so the call site needs neither.
+
+The predicate alone decides the match. An item satisfying it is returned whatever its value: `0`, `''`, `false`, `null`, and even `undefined` all pass through. `Array.prototype.find` cannot express this, because the `undefined` it returns conflates a missing match with a found `undefined`.
+
+The narrowing is therefore bounded by `T`. Searching a `ReadonlyArray<string | undefined>` yields `string | undefined`, since a match proves an item satisfied the predicate, not that the item is defined. Where the elements themselves are nullable and the result must not be, the caller narrows after the call as it would anywhere else.
+
+### When it throws
+
+No matching item throws an `Error`:
+
+```
+Could not find item.
+```
+
+`label` replaces `item` in that message, so a caller names what it was looking for:
+
+```ts
+findItemOrThrow(users, (user) => user.id === id, { label: `user ${id}` });
+// throws Error("Could not find user 42.")
+```
+
+## `getItemAtIndexOrThrow`
+
+```ts
+getItemAtIndexOrThrow<T>(array: ReadonlyArray<T>, index: number): T;
+```
+
+Returns the item at the index, or throws if the array has no item there.
+
+```ts
+import { getItemAtIndexOrThrow } from '@williamthorsen/toolbelt.arrays/candidate';
+
+const fields = parseRow(line);
+const label = getItemAtIndexOrThrow(fields, labelColumnIndex);
+```
+
+Its value is narrowing. Under `noUncheckedIndexedAccess`, indexing an array yields `T | undefined`, so every read needs a check or an assertion before the value is usable. This collapses that to `T` or throws, so the call site needs neither.
+
+The index must be non-negative. A negative index throws rather than resolving from the end as `Array.prototype.at` would: The function exists to make a violated index invariant loud, and silently reading from the end would turn an off-by-one into a wrong answer. A caller who wants the last item names it:
+
+```ts
+getItemAtIndexOrThrow(letters, letters.length - 1);
+```
+
+### When it throws
+
+An index naming no item throws a `RangeError`, whether it is negative, reaches past the end of the array, or lands on a hole in a sparse one:
+
+```
+No item at index 4 of an array of length 4.
+```
+
+The message names the length rather than claiming the index is out of bounds, so the reader can tell the cases apart: An in-range index in the message means the array is sparse.
+
+A non-integer index throws a `TypeError`:
+
+```
+Index must be a safe integer, but received 0.5.
+```
+
+This covers `NaN` and `Infinity` as well. `Array.prototype.at` truncates a fractional index toward zero, so `at(0.5)` and `at(NaN)` both return the first item; here they fail instead, since neither is a plausible thing to have meant.
+
+An item is returned whatever its value: `0`, `''`, `false`, `null`, and even `undefined` all pass through, because presence at the index is what is tested, not the value read from it. Only absence throws.

package/dist/esm/3-candidate/findItemOrThrow.d.ts

@@ -0,0 +1,5 @@
+export declare function findItemOrThrow<T>(items: ReadonlyArray<T>, predicate: (item: T, index: number, items: ReadonlyArray<T>) => boolean, options?: Options): T;
+interface Options {
+    label?: string | undefined;
+}
+export {};

package/dist/esm/3-candidate/findItemOrThrow.js

@@ -0,0 +1,9 @@
+export function findItemOrThrow(items, predicate, options = {}) {
+    const { label = 'item' } = options;
+    for (const [index, item] of items.entries()) {
+        if (predicate(item, index, items)) {
+            return item;
+        }
+    }
+    throw new Error(`Could not find ${label}.`);
+}

package/dist/esm/3-candidate/findWeightedIndex.js

@@ -1,4 +1,4 @@
-import { getAtIndexOrThrow } from "./getAtIndexOrThrow.js";
+import { getItemAtIndexOrThrow } from "./getItemAtIndexOrThrow.js";
 export function findWeightedIndex(cumulativeWeights, targetWeight) {
     if (cumulativeWeights.length === 0) {
         return undefined;
@@ -7,7 +7,7 @@ export function findWeightedIndex(cumulativeWeights, targetWeight) {
         return undefined;
     }
     for (let i = 0; i < cumulativeWeights.length; i++) {
-        if (targetWeight <= getAtIndexOrThrow(cumulativeWeights, i)) {
+        if (targetWeight <= getItemAtIndexOrThrow(cumulativeWeights, i)) {
             return i;
         }
     }

package/dist/esm/3-candidate/getItemAtIndexOrThrow.d.ts

@@ -0,0 +1 @@
+export declare function getItemAtIndexOrThrow<T>(array: ReadonlyArray<T>, index: number): T;

package/dist/esm/3-candidate/getItemAtIndexOrThrow.js

@@ -0,0 +1,9 @@
+export function getItemAtIndexOrThrow(array, index) {
+    if (!Number.isSafeInteger(index)) {
+        throw new TypeError(`Index must be a safe integer, but received ${index}.`);
+    }
+    if (!Object.hasOwn(array, index)) {
+        throw new RangeError(`No item at index ${index} of an array of length ${array.length}.`);
+    }
+    return array[index];
+}

package/dist/esm/3-candidate/index.d.ts

@@ -1,8 +1,8 @@
 export { arraify } from './arraify.js';
 export { extractWeights } from './extractWeights.js';
-export { findOrThrow } from './findOrThrow.js';
+export { findItemOrThrow } from './findItemOrThrow.js';
 export { findWeightedIndex } from './findWeightedIndex.js';
-export { getAtIndexOrThrow } from './getAtIndexOrThrow.js';
+export { getItemAtIndexOrThrow } from './getItemAtIndexOrThrow.js';
 export { includes } from './includes.js';
 export { listDuplicateItems } from './listDuplicateItems.js';
 export { listUniqueItems } from './listUniqueItems.js';

package/dist/esm/3-candidate/index.js

@@ -1,8 +1,8 @@
 export { arraify } from "./arraify.js";
 export { extractWeights } from "./extractWeights.js";
-export { findOrThrow } from "./findOrThrow.js";
+export { findItemOrThrow } from "./findItemOrThrow.js";
 export { findWeightedIndex } from "./findWeightedIndex.js";
-export { getAtIndexOrThrow } from "./getAtIndexOrThrow.js";
+export { getItemAtIndexOrThrow } from "./getItemAtIndexOrThrow.js";
 export { includes } from "./includes.js";
 export { listDuplicateItems } from "./listDuplicateItems.js";
 export { listUniqueItems } from "./listUniqueItems.js";

package/dist/esm/3-candidate/pickItem.js

@@ -1,8 +1,8 @@
 import { generateRandom } from '@williamthorsen/toolbelt.numbers/candidate';
-import { getAtIndexOrThrow } from "./getAtIndexOrThrow.js";
+import { getItemAtIndexOrThrow } from "./getItemAtIndexOrThrow.js";
 export function pickItem(items, options = {}) {
     if (items.length === 0) {
         throw new Error('Cannot pick an item from an empty array.');
     }
-    return getAtIndexOrThrow(items, Math.floor(generateRandom(options) * items.length));
+    return getItemAtIndexOrThrow(items, Math.floor(generateRandom(options) * items.length));
 }

package/dist/esm/3-candidate/pickWeightedIndex.js

@@ -1,10 +1,10 @@
 import { assert } from '@williamthorsen/toolbelt.guards';
 import { generateRandom } from '@williamthorsen/toolbelt.numbers/candidate';
 import { findWeightedIndex } from "./findWeightedIndex.js";
-import { getAtIndexOrThrow } from "./getAtIndexOrThrow.js";
+import { getItemAtIndexOrThrow } from "./getItemAtIndexOrThrow.js";
 export function pickWeightedIndex(cumulativeWeights, options = {}) {
     assertValidCumulativeWeights(cumulativeWeights);
-    const cumulativeWeight = getAtIndexOrThrow(cumulativeWeights, cumulativeWeights.length - 1);
+    const cumulativeWeight = getItemAtIndexOrThrow(cumulativeWeights, cumulativeWeights.length - 1);
     const randomValue = generateRandom(options);
     const targetWeight = randomValue * cumulativeWeight;
     const pickedIndex = findWeightedIndex(cumulativeWeights, targetWeight);
@@ -24,7 +24,7 @@ export function assertValidCumulativeWeights(weights, nItems = weights.length) {
 }
 function assertAscendingWeights(values) {
     for (let i = 1; i < values.length; i++) {
-        if (getAtIndexOrThrow(values, i) < getAtIndexOrThrow(values, i - 1)) {
+        if (getItemAtIndexOrThrow(values, i) < getItemAtIndexOrThrow(values, i - 1)) {
             throw new Error('Cumulative weights must be in ascending order.');
         }
     }

package/dist/esm/3-candidate/pickWeightedItem.js

@@ -1,4 +1,4 @@
-import { getAtIndexOrThrow } from "./getAtIndexOrThrow.js";
+import { getItemAtIndexOrThrow } from "./getItemAtIndexOrThrow.js";
 import { assertValidCumulativeWeights, pickWeightedIndex } from "./pickWeightedIndex.js";
 import { toCumulativeValues } from "./toCumulativeValues.js";
 export function pickWeightedItem(items, weights) {
@@ -6,7 +6,7 @@ export function pickWeightedItem(items, weights) {
     assertValidCumulativeWeights(cumulativeWeights, items.length);
     return function pickItem(options = {}) {
         const index = pickWeightedIndex(cumulativeWeights, options);
-        return getAtIndexOrThrow(items, index);
+        return getItemAtIndexOrThrow(items, index);
     };
 }
 export const toPickWeightedItem = pickWeightedItem;

package/dist/esm/3-candidate/shuffle.js

@@ -1,5 +1,5 @@
 import { pickInteger, SeededRng } from '@williamthorsen/toolbelt.numbers/candidate';
-import { getAtIndexOrThrow } from "./getAtIndexOrThrow.js";
+import { getItemAtIndexOrThrow } from "./getItemAtIndexOrThrow.js";
 export function shuffle(items, options = {}) {
     const shuffled = [...items];
     shuffleInPlace(shuffled, options);
@@ -9,8 +9,8 @@ export function shuffleInPlace(items, options = {}) {
     const seed = SeededRng.spawn(options.seed);
     for (let i = items.length - 1; i > 0; i--) {
         const j = pickInteger({ max: i, seed });
-        const swapped = getAtIndexOrThrow(items, i);
-        items[i] = getAtIndexOrThrow(items, j);
+        const swapped = getItemAtIndexOrThrow(items, i);
+        items[i] = getItemAtIndexOrThrow(items, j);
         items[j] = swapped;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.arrays",
-  "version": "4.0.1",
+  "version": "5.0.1",
   "description": "Array utilities",
   "keywords": [
     "array",
@@ -44,7 +44,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@williamthorsen/toolbelt.guards": "3.1.10",
+    "@williamthorsen/toolbelt.guards": "3.1.11",
     "@williamthorsen/toolbelt.numbers": "6.0.1"
   },
   "engines": {

package/dist/esm/3-candidate/findOrThrow.d.ts

@@ -1,5 +0,0 @@
-export declare function findOrThrow<T>(items: ReadonlyArray<T>, predicate: (item: T, index: number, items: ReadonlyArray<T>) => boolean, options?: FindOrThrowOptions): NonNullable<T>;
-interface FindOrThrowOptions {
-    label?: string | undefined;
-}
-export {};

package/dist/esm/3-candidate/findOrThrow.js

@@ -1,8 +0,0 @@
-export function findOrThrow(items, predicate, options = {}) {
-    const { label = 'item' } = options;
-    const foundItem = items.find(predicate);
-    if (!foundItem) {
-        throw new Error(`Could not find ${label}.`);
-    }
-    return foundItem;
-}

package/dist/esm/3-candidate/getAtIndexOrThrow.d.ts

@@ -1 +0,0 @@
-export declare function getAtIndexOrThrow<T>(array: ReadonlyArray<T>, index: number): T;

package/dist/esm/3-candidate/getAtIndexOrThrow.js

@@ -1,6 +0,0 @@
-export function getAtIndexOrThrow(array, index) {
-    if (index < 0 || index >= array.length) {
-        throw new RangeError(`Index ${index} is out of bounds.`);
-    }
-    return array[index];
-}