feat(general): introduce initial modules and general structure to sup…

…port upcoming features

+ Add randomArrayElement helper
+ Add randomArrayElements helper
+ Add getLocale helper
+ Add firstName module
+ Introduces name module

src/__tests__/faker.test.ts

@@ -0,0 +1,11 @@
+import faker from '..';
+
+describe('Faker', () => {
+    it('has helpers module', () => {
+        expect(faker).toHaveProperty('helpers');
+    });
+
+    it('has name module', () => {
+        expect(faker).toHaveProperty('name');
+    });
+});

src/helpers/__tests__/getLocale.test.ts

@@ -0,0 +1,37 @@
+import { Locale, LocaleObject } from '../../types/locale';
+
+import getLocale from '../getLocale';
+
+describe('Helpers | getLocale', () => {
+    it('returns requested locale from given locale collection', () => {
+        const locales: LocaleObject<string[]> = { en: ['en'], pt_BR: ['pt_BR'] };
+
+        const locale = getLocale(locales, Locale.PT_BR);
+
+        expect(locale).toEqual(['pt_BR']);
+    });
+
+    it(`returns ${Locale.EN} locale by default`, () => {
+        const locales: LocaleObject<string[]> = { en: ['en'], pt_BR: ['pt_BR¿'] };
+
+        const locale = getLocale(locales);
+
+        expect(locale).toEqual(['en']);
+    });
+
+    it(`returns ${Locale.EN} if given locale is invalid`, () => {
+        const locales: LocaleObject<string[]> = { en: ['en'], pt_BR: ['pt_BR¿'] };
+
+        const locale = getLocale(locales, Locale.RU);
+
+        expect(locale).toEqual(['en']);
+    });
+
+    it(`throws an error if given locale and fallback ${Locale.EN} does not exists`, () => {
+        const locales = {};
+
+        expect(() => {
+            getLocale(locales, Locale.RU);
+        }).toThrowError();
+    });
+});

src/helpers/__tests__/helpers.test.ts

@@ -0,0 +1,19 @@
+import helpers from '..';
+
+describe('Helpers', () => {
+    it('has randomNumber module', () => {
+        expect(helpers).toHaveProperty('randomNumber');
+    });
+
+    it('has randomArrayElement module', () => {
+        expect(helpers).toHaveProperty('randomArrayElement');
+    });
+
+    it('has randomArrayElements module', () => {
+        expect(helpers).toHaveProperty('randomArrayElements');
+    });
+
+    it('has getLocale module', () => {
+        expect(helpers).toHaveProperty('getLocale');
+    });
+});

src/helpers/__tests__/randomArrayElement.test.ts

@@ -0,0 +1,10 @@
+import randomArrayElement from '../randomArrayElement';
+
+describe('Helpers | randomArrayElement', () => {
+    it('returns a random element from an array', () => {
+        const collection = ['foo', 'bar', 'baz'];
+        const item = randomArrayElement(collection);
+
+        expect(collection).toContain(item);
+    });
+});

src/helpers/__tests__/randomArrayElements.ts

@@ -0,0 +1,19 @@
+import randomArrayElements from '../randomArrayElements';
+
+describe('Helpers | randomArrayElements', () => {
+    it('returns a number of random elements from array', () => {
+        const collection = ['foo', 'bar', 'baz'];
+
+        const items = randomArrayElements(collection, 2);
+
+        expect(collection).toEqual(expect.arrayContaining(items));
+    });
+
+    it('returns the maximum amount of items possibile in collection when parameter amount exceeds collection length', () => {
+        const collection = ['foo', 'bar', 'baz'];
+
+        const items = randomArrayElements(collection, 100);
+
+        expect(items).toHaveLength(3);
+    });
+});

src/helpers/__tests__/randomNumber.test.ts

@@ -0,0 +1,28 @@
+import randomNumber from '../randomNumber';
+
+describe('Helpers | randomNumber', () => {
+    it('returns a positive random number', () => {
+        const number = randomNumber();
+
+        expect(number).toBeGreaterThanOrEqual(0);
+    });
+
+    it('returns a random integer number by default', () => {
+        const number = randomNumber(1, 2);
+
+        expect(Number.isInteger(number)).toBeTruthy();
+    });
+
+    it('returns a random float number', () => {
+        const number = randomNumber(1, 2, true);
+
+        expect(!Number.isInteger(number)).toBeTruthy();
+    });
+
+    it('returns a random float number between min and max', () => {
+        const number = randomNumber(1, 2, true);
+
+        expect(number).toBeGreaterThanOrEqual(1);
+        expect(number).toBeLessThanOrEqual(2);
+    });
+});

src/helpers/getLocale.ts

@@ -0,0 +1,28 @@
+import { Locale, LocaleObject } from '../types/locale';
+
+import get from 'lodash/get';
+
+/**
+ * Return selectedLocale from locales collection.
+ * If selectedLocale is not found, it will return Locale.EN as fallback.
+ * If both are not present, them it will throw an error
+ *
+ * @export
+ * @template T
+ * @param {LocaleObject<T>} locales
+ * @param {Locale} [selectedLocale=Locale.EN]
+ * @returns {T}
+ */
+export default function getLocale<T>(locales: LocaleObject<T>, selectedLocale: Locale = Locale.EN): T {
+    let locale: T | undefined = get(locales, selectedLocale);
+
+    if (locale === undefined) {
+        locale = get(locales, Locale.EN);
+    }
+
+    if (locale === undefined) {
+        throw new Error(`Cannot find locale ${selectedLocale}, nor default fallback locale ${Locale.EN}`);
+    }
+
+    return locale;
+}

src/helpers/index.ts

@@ -0,0 +1,6 @@
+import getLocale from './getLocale';
+import randomArrayElement from './randomArrayElement';
+import randomArrayElements from './randomArrayElements';
+import randomNumber from './randomNumber';
+
+export default { getLocale, randomArrayElement, randomArrayElements, randomNumber };

src/helpers/randomArrayElement.ts

@@ -0,0 +1,18 @@
+import randomNumber from './randomNumber';
+
+/**
+ * Return a random element from given array
+ *
+ * @export
+ * @template T
+ * @param {T[]} collection
+ * @returns {T}
+ */
+export default function randomArrayElement<T>(collection: T[]): T {
+    const min = 0;
+    const max = collection.length - 1;
+
+    const index = randomNumber(min, max);
+
+    return collection[index];
+}

src/helpers/randomArrayElements.ts

@@ -0,0 +1,19 @@
+import shuffle from 'lodash/shuffle';
+import take from 'lodash/take';
+
+/**
+ * Return N random items from given array.
+ * If the amount of items requested is greater than collection length,
+ * it will return as many items as possible
+ *
+ * @export
+ * @template T
+ * @param {T[]} collection
+ * @param {number} amount
+ * @returns {T[]}
+ */
+export default function randomArrayElements<T>(collection: T[], amount: number): T[] {
+    const shuffledCollection = shuffle(collection);
+
+    return take(shuffledCollection, amount);
+}

src/helpers/randomNumber.ts

@@ -0,0 +1,24 @@
+import random from 'lodash/random';
+
+/**
+ * Return a random number between min and max values.
+ * By default this function returns integers numbers, but can
+ * return float if isFloating = true
+ *
+ * @export
+ * @param {number} [min]
+ * @param {number} [max]
+ * @param {boolean} [isFloating=false]
+ * @returns {number}
+ */
+export default function randomNumber(min?: number, max?: number, isFloating: boolean = false): number {
+    if (min === undefined) {
+        min = 0;
+    }
+
+    if (max === undefined) {
+        max = min + 100;
+    }
+
+    return random(min, max, isFloating);
+}

src/index.ts

@@ -0,0 +1,6 @@
+import helpers from './helpers';
+import name from './name';
+
+const faker = { helpers, name };
+
+export default faker;

src/name/__tests__/firstName.test.ts

@@ -0,0 +1,19 @@
+import { Locale } from '../../types/locale';
+import firstName from '../firstName/firstName';
+import locales from '../firstName/locales';
+
+describe('Name | firstName', () => {
+    it('returns a random first name', () => {
+        const name = firstName();
+        const { en } = locales;
+
+        expect(en).toContain(name);
+    });
+
+    it('accepts any existing locale', () => {
+        const name = firstName(Locale.PT_BR);
+        const { pt_BR } = locales;
+
+        expect(pt_BR).toContain(name);
+    });
+});

src/name/__tests__/name.test.ts

@@ -0,0 +1,7 @@
+import name from '..';
+
+describe('Name', () => {
+    it('has firstName module', () => {
+        expect(name).toHaveProperty('firstName');
+    });
+});

src/name/firstName/firstName.ts

@@ -0,0 +1,19 @@
+import { Locale } from '../../types/locale';
+import getLocale from '../../helpers/getLocale';
+import locales from './locales';
+import randomArrayElement from '../../helpers/randomArrayElement';
+
+/**
+ * Return a random first name.
+ * If a valid locale is given, it will the locale collection.
+ * If the given locale is not valid, it will fallback to Locale.EN
+ *
+ * @export
+ * @param {Locale} [selectedLocale]
+ * @returns {string}
+ */
+export default function firstName(selectedLocale?: Locale): string {
+    const collection = getLocale(locales, selectedLocale);
+
+    return randomArrayElement(collection);
+}

src/name/firstName/locales/__tests__/locales.test.ts

@@ -0,0 +1,11 @@
+import locales from '..';
+
+describe('Name | firstName | Locales', () => {
+    it('has en', () => {
+        expect(locales).toHaveProperty('en');
+    });
+
+    it('has pt_BR', () => {
+        expect(locales).toHaveProperty('pt_BR');
+    });
+});