feat: add NonEmptyArray and specialized implementation of last()

src/array.test.ts

@@ -1,4 +1,31 @@
-import { containSameValues, insertIf, withoutIndex } from './array';
+import {
+  containSameValues,
+  insertIf,
+  isNonEmptyArray,
+  last,
+  NonEmptyArray,
+  withoutIndex,
+} from './array';
+
+describe('NonEmptyArray', () => {
+  it('can be proven to be non-empty', () => {
+    const array = [1];
+
+    // @ts-expect-error intentionally wrong
+    let nonEmptyArray: NonEmptyArray<unknown> = [];
+
+    // @ts-expect-error intentionally wrong
+    nonEmptyArray = array;
+
+    if (isNonEmptyArray(array)) {
+      nonEmptyArray = array;
+    }
+
+    expect(isNonEmptyArray(nonEmptyArray)).toBe(true);
+    expect(isNonEmptyArray([undefined])).toBe(true);
+    expect(isNonEmptyArray([])).toBe(false);
+  });
+});
 
 describe('withoutIndex', () => {
   it('handles empty arrays', () => {
@@ -40,3 +67,15 @@ describe('insertIf', () => {
     expect(insertIf(false, 1, 2)).toEqual([]);
   });
 });
+
+describe('last', () => {
+  it('returns the last element of an array', () => {
+    const array: NonEmptyArray<number> = [1, 2];
+    const actual: number = last(array);
+    expect(actual).toEqual(2);
+  });
+
+  it('returns undefined for empty arrays', () => {
+    expect(last([])).toEqual(undefined);
+  });
+});

src/array.ts

@@ -1,5 +1,11 @@
 import { isEqual, sortBy } from 'lodash';
 
+export type NonEmptyArray<T> = Array<T> & { 0: T };
+
+export function isNonEmptyArray<T>(value: Array<T>): value is NonEmptyArray<T> {
+  return value.length > 0;
+}
+
 /**
  * Return a new array that does not contain the item at the specified index.
  */
@@ -39,3 +45,10 @@ export function insertIf<T>(
 ): Array<T> {
   return condition ? elements : [];
 }
+
+export function last<T, A extends Array<T>>(
+  array: A,
+): A extends NonEmptyArray<T> ? T : T | undefined {
+  // @ts-expect-error too magical
+  return array[array.length - 1];
+}