feat(micro-dash): add shuffle()

projects/micro-dash-sizes/src/app/collection/shuffle.lodash.ts

@@ -0,0 +1,3 @@
+import shuffle from 'lodash-es/shuffle';
+
+console.log(shuffle([1, 2]), shuffle({ a: 1, b: 2 }), shuffle(null));

projects/micro-dash-sizes/src/app/collection/shuffle.microdash.ts

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

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

@@ -12,6 +12,7 @@ export { reduce } from './reduce';
 export { reduceRight } from './reduce-right';
 export { sample } from './sample';
 export { sampleSize } from './sample-size';
+export { shuffle } from './shuffle';
 export { size } from './size';
 export { some } from './some';
 export { sortBy } from './sort-by';

projects/micro-dash/src/lib/collection/sample-size.spec.ts

@@ -2,6 +2,10 @@ import { difference } from 'lodash-es';
 import { sampleSize } from './sample-size';
 
 describe('sampleSize()', () => {
+  //
+  // stolen from https://github.com/lodash/lodash
+  //
+
   const array = [1, 2, 3];
 
   it('should return an array of random elements', () => {

projects/micro-dash/src/lib/collection/shuffle.spec.ts

@@ -0,0 +1,35 @@
+import { sortBy, times, uniqBy } from 'lodash-es';
+import { shuffle } from './shuffle';
+
+describe('shuffle()', () => {
+  it('accepts nil values for the collection, returning an empty array', () => {
+    expect(shuffle(null)).toEqual([]);
+    expect(shuffle(undefined)).toEqual([]);
+  });
+
+  //
+  // stolen from https://github.com/lodash/lodash
+  //
+
+  const array = [1, 2, 3];
+  const object = { a: 1, b: 2, c: 3 };
+
+  it('should return a new array', () => {
+    const actual = shuffle(array);
+    expect(actual).toEqual(jasmine.arrayWithExactContents(array));
+    expect(actual).not.toBe(array);
+  });
+
+  it('should contain the same elements after a collection is shuffled', () => {
+    expect(shuffle(array).sort()).toEqual(array);
+    expect(shuffle(object).sort()).toEqual(array);
+  });
+
+  it('should shuffle small collections', () => {
+    const actual = times(1000, () => shuffle([1, 2]));
+    expect(sortBy(uniqBy(actual, String), '0')).toEqual([
+      [1, 2],
+      [2, 1],
+    ]);
+  });
+});

projects/micro-dash/src/lib/collection/shuffle.ts

@@ -0,0 +1,18 @@
+import { Nil } from '../interfaces';
+import { sampleSize } from './sample-size';
+import { size } from './size';
+
+/**
+ * Creates an array of shuffled values, using a version of the [Fisher-Yates shuffle](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle).
+ *
+ * Contribution to minified bundle size, when it is the only function imported:
+ * - Lodash: 3,846 bytes
+ * - Micro-dash: 842 bytes
+ */
+
+export function shuffle<T>(array: T[] | Nil): T[];
+export function shuffle<T>(object: T | Nil): Array<T[keyof T]>;
+
+export function shuffle(collection: any): any {
+  return sampleSize(collection, size(collection));
+}

projects/micro-dash/src/typing-tests/collection/shuffle.dts-spec.ts

@@ -0,0 +1,21 @@
+import { shuffle } from '../../lib/collection';
+
+declare const array: number[];
+declare const arrayOrNull: number[] | null;
+declare const arrayOrUndefined: number[] | undefined;
+declare const object: { a: number; b: string };
+declare const objectOrNull: { a: number; b: string } | null;
+declare const objectOrUndefined: { a: number; b: string } | undefined;
+
+// $ExpectType number[]
+shuffle(array);
+// $ExpectType (string | number)[]
+shuffle(object);
+// $ExpectType number[]
+shuffle(arrayOrNull);
+// $ExpectType number[]
+shuffle(arrayOrUndefined);
+// $ExpectType (string | number)[]
+shuffle(objectOrNull);
+// $ExpectType (string | number)[]
+shuffle(objectOrUndefined);