feat: 🔥 random pick from array

README.md

@@ -19,7 +19,7 @@ Create massive amounts of fake data in the browser and NodeJS. Tree Shakeable &
 
 </p>
 
-✅ &nbsp;197 Functions  
+✅ &nbsp;198 Functions  
 ✅ &nbsp;Tree Shakable  
 ✅ &nbsp;Fully Typed  
 ✅ &nbsp;Factory Functions  

docs/docs/getting-started.mdx

@@ -13,7 +13,7 @@ title: Getting Started
   />
 </p>
 
-✅ &nbsp;197 Functions  
+✅ &nbsp;198 Functions  
 ✅ &nbsp;Tree Shakable  
 ✅ &nbsp;Fully Typed  
 ✅ &nbsp;Entity Functions  

packages/falso/src/index.ts

@@ -204,3 +204,4 @@ export {
 } from './lib/factories/incremental-date';
 export { randAggregation } from './lib/aggregation';
 export { toCollection } from './lib/collection';
+export { randPick } from './lib/pick';

packages/falso/src/lib/pick.ts

@@ -0,0 +1,38 @@
+import { FakeOptions, fake } from './core/core';
+import { randNumber } from './number';
+
+/**
+ * Generate a random pick from an array.
+ *
+ * @category General
+ *
+ * @example
+ *
+ * randPick([ "A", "B", "C", ... ])
+ *
+ * @example
+ *
+ * randPick([ 1, 2, 3, ... ])
+ *
+ * @example
+ *
+ * randPick([ "test", 123, { hello:"world" }, ... ])
+ *
+ * @example
+ *
+ * randPick([ 1, 3, 8, 12],{ length: 10 })
+ *
+ */
+export function randPick<Options extends FakeOptions = never>(
+  array: Array<unknown>,
+  options?: Options
+) {
+  if (!array || array.length === 0) {
+    throw new Error('the array need to have at least 1 element');
+  }
+
+  const factory = () => {
+    return array[randNumber({ min: 0, max: array.length - 1 })];
+  };
+  return fake(factory, options);
+}

packages/falso/src/tests/pick.spec.ts

@@ -0,0 +1,11 @@
+import { randPick } from '../lib/pick';
+
+describe('randPick', () => {
+  it('should throw an error on empty array', () => {
+    const test = () => {
+      randPick([]);
+    };
+    expect(test).toThrow(Error);
+    expect(test).toThrow('the array need to have at least 1 element');
+  });
+});