feat(micro-dash): add nth()

Closes #10

projects/micro-dash-sizes/src/app/array/nth.lodash.ts

@@ -0,0 +1,3 @@
+import nth from 'lodash-es/nth';
+
+console.log(nth([1, 2], 0), nth([1, 2], -1), nth(null, 0));

projects/micro-dash-sizes/src/app/array/nth.microdash.ts

@@ -0,0 +1,3 @@
+import { nth } from '@s-libs/micro-dash';
+
+console.log(nth([1, 2], 0), nth([1, 2], -1), nth(null, 0));

projects/micro-dash/src/lib/array/index.ts

@@ -5,6 +5,7 @@ export { difference } from './difference';
 export { flatten } from './flatten';
 export { initial } from './initial';
 export { last } from './last';
+export { nth } from './nth';
 export { pull } from './pull';
 export { pullAll } from './pull-all';
 export { pullAt } from './pull-at';

projects/micro-dash/src/lib/array/nth.spec.ts

@@ -0,0 +1,34 @@
+import { nth } from './nth';
+
+describe('nth()', () => {
+  //
+  // stolen from https://github.com/lodash/lodash
+  //
+
+  const array = ['a', 'b', 'c', 'd'];
+
+  it('should get the nth element of `array`', () => {
+    expect(nth(array, 0)).toBe('a');
+    expect(nth(array, 1)).toBe('b');
+    expect(nth(array, 2)).toBe('c');
+    expect(nth(array, 3)).toBe('d');
+  });
+
+  it('should work with a negative `n`', () => {
+    expect(nth(array, -1)).toBe('d');
+    expect(nth(array, -2)).toBe('c');
+    expect(nth(array, -3)).toBe('b');
+    expect(nth(array, -4)).toBe('a');
+  });
+
+  it('should return `undefined` for empty arrays', () => {
+    expect(nth(null, 1)).toBe(undefined);
+    expect(nth(undefined, 1)).toBe(undefined);
+    expect(nth([], 1)).toBe(undefined);
+  });
+
+  it('should return `undefined` for non-indexes', () => {
+    expect(nth([1, 2], Infinity)).toBeUndefined();
+    expect(nth([1, 2], 2)).toBeUndefined();
+  });
+});

projects/micro-dash/src/lib/array/nth.ts

@@ -0,0 +1,27 @@
+import { Nil } from '../interfaces';
+
+/**
+ * Gets the element at index `n` of `array`. If `n` is negative, the nth element from the end is returned.
+ *
+ * Differences from lodash:
+ * - does not handle a fractional value for `index`
+ *
+ * Contribution to minified bundle size, when it is the only function imported:
+ * - Lodash: 1,533 bytes
+ * - Micro-dash: 96 bytes
+ */
+
+export function nth<T>(array: ReadonlyArray<T>, index: number): T;
+export function nth<T>(
+  array: ReadonlyArray<T> | Nil,
+  index: number,
+): T | undefined;
+
+export function nth<T>(
+  array: ReadonlyArray<T> | Nil,
+  index: number,
+): T | undefined {
+  if (array) {
+    return array[index < 0 ? array.length + index : index];
+  }
+}