Add arrayIncludes() (#8)

Co-authored-by: Sindre Sorhus <[email protected]>

source/array-includes.ts

@@ -0,0 +1,24 @@
+/**
+An alternative to `Array.prototype.includes` that properly acts as a type guard.
+
+It was [rejected](https://github.com/microsoft/TypeScript/issues/26255#issuecomment-748211891) from being done in TypeScript itself.
+
+@example
+```
+import {arrayIncludes} from 'ts-extras';
+
+const values = ['a', 'b', 'c'] as const;
+const valueToCheck: unknown = 'a';
+
+if (arrayIncludes(values, valueToCheck)) {
+	// We now know that the value is of type `typeof values[number]`.
+}
+```
+*/
+export function arrayIncludes<Type>(
+	array: Type[] | readonly Type[],
+	item: unknown,
+	fromIndex?: number,
+): item is Type {
+	return array.includes(item as Type, fromIndex);
+}

source/index.ts

@@ -1,3 +1,4 @@
+export {arrayIncludes} from './array-includes.js';
 export {isDefined} from './is-defined.js';
 export {isEmpty} from './is-empty.js';
 export {assertError} from './assert-error.js';

test/array-includes.ts

@@ -0,0 +1,29 @@
+import test from 'ava';
+import {arrayIncludes} from '../source/index.js';
+
+test('arrayIncludes()', t => {
+	const values = ['a', 'b', 'c'] as const;
+	const validValue: unknown = 'a';
+	const invalidValue: unknown = 'd';
+	let testValueType: typeof values[number];
+
+	t.true(arrayIncludes(values, validValue));
+	t.false(arrayIncludes(values, invalidValue));
+
+	if (arrayIncludes(values, validValue)) {
+		// @ts-expect-error
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-call
+		values.push(); // Ensure readonly array is still readonly.
+
+		testValueType = validValue;
+	} else {
+		// @ts-expect-error
+		testValueType = validValue;
+
+		// @ts-expect-error
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-call
+		values.push(); // Ensure readonly array is still readonly.
+	}
+
+	t.is(testValueType, 'a');
+});