moderndash 0.0.5

package/.ctiignore

@@ -0,0 +1,3 @@
+{
+  "src/helpers": "*",
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "moderndash",
+  "version": "0.0.5",
+  "type": "module",
+  "description": "A lodash inspired utility framework for ESM/Typescript/ES2020",
+  "scripts": {
+    "build": "ctix create ----startAt src --overwrite --noBackup & tsup",
+    "publish": "npm run build & npm publish",
+    "test": "vitest",
+    "test-ui": "vitest --ui"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Maggi64/moderndash.git"
+  },
+  "keywords": [
+    "lodash",
+    "utility",
+    "helper",
+    "underscore",
+    "esm"
+  ],
+  "author": "Maggi64",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Maggi64/moderndash/issues"
+  },
+  "browserslist": [
+    ">2% and not dead"
+  ],
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "homepage": "https://github.com/Maggi64/moderndash#readme",
+  "devDependencies": {
+    "@vitest/coverage-c8": "0.27.1",
+    "@vitest/ui": "0.27.1",
+    "vitest": "0.27.1",
+    "tsup": "6.5.0",
+    "ctix": "1.8.1"
+  }
+}

package/src/array/chunk.ts

@@ -0,0 +1,31 @@
+/**
+ * Creates an array of elements split into groups the length of size. If array can't be split evenly, the final chunk will be the remaining elements.
+ *
+ * @category Array
+ * @returns Returns the new array of chunks.
+ * @param chunkSize - The array to process.
+ * @param array - The length of each chunk
+ * @example
+ * chunk(2, ['a', 'b', 'c', 'd'])
+ * // => [['a', 'b'], ['c', 'd']]
+ *
+ * chunk(3, ['a', 'b', 'c', 'd'])
+ * // => [['a', 'b', 'c'], ['d']]
+ */
+
+export function chunk<TInput>(chunkSize: number, array: TInput[]): TInput[][] {
+    const sizeInteger = Math.trunc(chunkSize);
+    if (array.length === 0 || sizeInteger < 1) {
+        return [];
+    }
+
+    const chunkedArray = [];
+    let i = 0;
+
+    while (i < array.length) {
+        chunkedArray.push(array.slice(i, i + sizeInteger));
+        i += sizeInteger;
+    }
+
+    return chunkedArray;
+}

package/src/array/difference.ts

@@ -0,0 +1,21 @@
+import type { MinimumTwoArrays } from '../types';
+
+import { differenceWith } from '@array/differenceWith';
+import { isEqual } from '@lang/isEqual';
+
+/**
+ * Creates an array of `array` values not included in the other given arrays. The order and references of result values are determined by the first array.
+ *
+ * **Note:** Unlike `pullAll`, this method returns a new array.
+ *
+ * @category Array
+ * @param arrays - First array is inspected, others are excluded.
+ * @returns Returns the new array of filtered values.
+ * @example
+ * difference([2, 1], [2, 3])
+ * // =\> [1]
+ */
+
+export function difference<T>(...arrays: MinimumTwoArrays<T>): T[] {
+    return differenceWith(isEqual, ...arrays);
+}

package/src/array/differenceBy.ts

@@ -0,0 +1,30 @@
+import type { IterateeFunction, MinimumTwoArrays, PropertyShorthand } from '../types';
+
+import { differenceWith } from '@array/differenceWith';
+import { getIterateFunction } from '@helpers/shortHands';
+import { isEqualWith } from '@lang/isEqualWith';
+
+/**
+ * This method is like `difference` except that it accepts `iteratee` which
+ * is invoked for each element of `array` and `values` to generate the criterion
+ * by which they're compared. The order and references of result values are
+ * determined by the first array.
+ *
+ * **Note:** Unlike `pullAllBy`, this method returns a new array.
+ *
+ * @category Array
+ * @param iteratee - The iteratee invoked per element. Or property shorthand.
+ * @param arrays - First array to inspect. Others are excluded.
+
+ * @returns Returns the new array of filtered values.
+ * @example
+ * differenceBy(Math.floor, [2.1, 1.2], [2.3, 3.4])
+ * // => [1.2]
+ * differenceBy('x', [{ 'x': 2 }, { 'x': 1 }], [{ 'x': 1 }])
+ * // => [{ 'x': 2 }]
+ */
+
+export function differenceBy<T>(iteratee: IterateeFunction<T> | PropertyShorthand<T>, ...arrays: MinimumTwoArrays<T>): T[] {
+    const iterateeFunction = getIterateFunction(iteratee);
+    return differenceWith((a, b) => isEqualWith(iterateeFunction, a, b), ...arrays);
+}

package/src/array/differenceWith.ts

@@ -0,0 +1,31 @@
+import type { MinimumTwoArrays } from '../types';
+
+/**
+ * This method is like `difference` except that it accepts `comparator`
+ * which is invoked to compare elements of `array` to `values`. The order and
+ * references of result values are determined by the first array. The comparator
+ * is invoked with two arguments: (arrVal, othVal).
+ *
+ * **Note:** Unlike `pullAllWith`, this method returns a new array.
+ *
+ * @category Array
+ * @param comparator - The comparator invoked per element.
+ * @param arrays - First array to inspect. Others are excluded.
+ * @returns Returns the new array of filtered values.
+ * @example
+ * differenceWith(isEqual, [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }], [{ 'x': 1, 'y': 2 }])
+ * // => [{ 'x': 2, 'y': 1 }]
+ */
+
+export function differenceWith<T>(comparator: (a: T, b: T) => boolean, ...arrays: MinimumTwoArrays<T>): T[] {
+    const difference: T[] = [];
+    const [firstArray, ...restArrays] = arrays;
+
+    firstArray.forEach(element => {
+        if (!restArrays.some(array => array.some(item => comparator(item, element)))) {
+            difference.push(element);
+        }
+    });
+
+    return difference;
+}

package/src/array/dropRightWhile.ts

@@ -0,0 +1,28 @@
+/**
+ * Creates a slice of `array` excluding elements dropped from the end.
+ * Elements are dropped until `predicate` returns falsey. The predicate is
+ * invoked with three arguments: (value, index, array).
+ *
+ * @category Array
+ * @param predicate - The function invoked per iteration.
+ * @param array - The array to query.
+ * @returns Returns the slice of `array`.
+ * @example
+ * const users = [
+ *   { 'user': 'barney',  'active': false },
+ *   { 'user': 'fred',    'active': true },
+ *   { 'user': 'pebbles', 'active': true }
+ * ]
+ *
+ * dropRightWhile(({ active }) => active, users)
+ * // => objects for ['barney']
+ */
+
+
+export function dropRightWhile<T>(predicate: (value: T) => boolean, array: T[]) {
+    let i = array.length;
+    while (i > 0 && predicate(array[i - 1])) {
+        i--;
+    }
+    return array.slice(0, i);
+}

package/src/array/dropWhile.ts

@@ -0,0 +1,24 @@
+/**
+ * Creates a slice of `array` excluding elements dropped from the beginning.
+ * Elements are dropped until `predicate` returns falsey. The predicate is
+ * invoked with three arguments: (value, index, array).
+ *
+ * @category Array
+ * @param predicate - The function invoked per iteration.
+ * @param array - The array to query.
+ * @returns Returns the slice of `array`.
+ * @example
+ * const users = [
+ *   { 'user': 'barney',  'active': true },
+ *   { 'user': 'fred',    'active': true },
+ *   { 'user': 'pebbles', 'active': false }
+ * ]
+ *
+ * dropWhile(({ active }) => active, users)
+ * // => objects for ['pebbles']
+ */
+
+export function dropWhile<T>(predicate: (value: T) => boolean, array: T[]): T[] {
+    const index = array.findIndex(x => !predicate(x));
+    return array.slice(index === -1 ? array.length : index);
+}

package/src/array/index.ts

@@ -0,0 +1,24 @@
+export * from './chunk';
+export * from './difference';
+export * from './differenceBy';
+export * from './differenceWith';
+export * from './dropRightWhile';
+export * from './dropWhile';
+export * from './intersection';
+export * from './intersectionBy';
+export * from './intersectionWith';
+export * from './sample';
+export * from './sampleSize';
+export * from './shuffle';
+export * from './takeRightWhile';
+export * from './takeWhile';
+export * from './union';
+export * from './unionBy';
+export * from './unionWith';
+export * from './uniq';
+export * from './uniqBy';
+export * from './uniqWith';
+export * from './unzip';
+export * from './unzipWith';
+export * from './zip';
+export * from './zipWith';

package/src/array/intersection.ts

@@ -0,0 +1,20 @@
+import type { MinimumTwoArrays } from '../types';
+
+import { intersectionWith } from '@array/intersectionWith';
+import { isEqual } from '@lang/isEqual';
+
+/**
+ * Creates an array of unique values that are included in all given arrays.
+ * The order and references of result values are determined by the first array.
+ *
+ * @category Array
+ * @param arrays - The arrays to inspect.
+ * @returns Returns the new array of intersecting values.
+ * @example
+ * intersection([2, 1], [2, 3])
+ * // => [2]
+ */
+
+export function intersection<TInput>(...arrays: MinimumTwoArrays<TInput>): TInput[] {
+    return intersectionWith(isEqual, ...arrays);
+}

package/src/array/intersectionBy.ts

@@ -0,0 +1,26 @@
+import type { IterateeFunction, MinimumTwoArrays, PropertyShorthand } from '../types';
+
+import { intersectionWith } from '@array/intersectionWith';
+import { getIterateFunction } from '@helpers/shortHands';
+import { isEqualWith } from '@lang/isEqualWith';
+
+/**
+ * This method is like `intersection` except that it accepts `iteratee`
+ * which is invoked for each element of each `arrays` to generate the criterion
+ * by which they're compared. The order and references of result values are
+ * determined by the first array. The iteratee is invoked with one argument:
+ * (value).
+ *
+ * @category Array
+ * @param iteratee - The iteratee invoked per element. Or property shorthand.
+ * @param arrays - The arrays to inspect.
+ * @returns Returns the new array of intersecting values.
+ * @example
+ * intersectionBy(Math.floor, [2.1, 1.2], [2.3, 3.4])
+ * // => [2.1]
+ */
+
+export function intersectionBy<TInput>(iteratee: IterateeFunction<TInput> | PropertyShorthand<TInput>, ...arrays: MinimumTwoArrays<TInput>): TInput[] {
+    const iterateeFunction = getIterateFunction(iteratee);
+    return intersectionWith((a, b) => isEqualWith(iterateeFunction, a, b), ...arrays);
+}

package/src/array/intersectionWith.ts

@@ -0,0 +1,33 @@
+import type { MinimumTwoArrays } from '../types';
+
+/**
+ * This method is like `intersection` except that it accepts `comparator`
+ * which is invoked to compare elements of `arrays`. The order and references
+ * of result values are determined by the first array. The comparator is
+ * invoked with two arguments: (arrVal, othVal).
+ *
+ * @category Array
+ * @param comparator - The comparator invoked per element.
+ * @param arrays - The arrays to inspect.
+ * @returns Returns the new array of intersecting values.
+ * @example
+ * const objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }]
+ * const others = [{ 'x': 1, 'y': 1 }, { 'x': 1, 'y': 2 }]
+ *
+ * intersectionWith(isEqual, objects, others)
+ * // => [{ 'x': 1, 'y': 2 }]
+ */
+
+export function intersectionWith<T>(comparator: (a: T, b: T) => boolean, ...arrays: MinimumTwoArrays<T>): T[] {
+    const intersection: T[] = [];
+
+    const [firstArray, ...restArrays] = arrays;
+
+    firstArray.forEach(element => {
+        if (restArrays.every(array => array.some(item => comparator(item, element)))) {
+            intersection.push(element);
+        }
+    });
+
+    return intersection;
+}

package/src/array/sample.ts

@@ -0,0 +1,18 @@
+/**
+ * Gets a random element from `array`.
+ *
+ * @category Array
+ * @param array - The array to sample.
+ * @returns Returns the random element.
+ * @example
+ * sample([1, 2, 3, 4])
+ * // => 2
+ */
+
+export function sample<T>(array: T[]): T | undefined {
+    if (array.length === 0) {
+        return undefined;
+    }
+    const randomIndex = Math.floor(Math.random() * array.length);
+    return array[randomIndex];
+}

package/src/array/sampleSize.ts

@@ -0,0 +1,31 @@
+import { sample } from '@array/sample';
+
+/**
+ * Gets `n` random elements at unique keys from `array` up to the
+ * size of `array`.
+ *
+ * @category Array
+ * @param size The number of elements to sample.
+ * @param array The array to sample.
+ * @returns Returns the random elements.
+ * @example
+ * sampleSize([1, 2, 3], 2)
+ * // => [3, 1]
+ *
+ * sampleSize([1, 2, 3], 4)
+ * // => [2, 3, 1]
+ */
+
+export function sampleSize<TInput>(size: number, array: TInput[]): TInput[] {
+    const sampleArray: TInput[] = [];
+
+    if (array.length === 0 || size <= 0) {
+        return sampleArray;
+    }
+
+    for (let i = 0; i < size; i++) {
+        sampleArray.push(sample(array) as TInput);
+    }
+
+    return sampleArray;
+}

package/src/array/shuffle.ts

@@ -0,0 +1,33 @@
+/**
+ * Creates an array of shuffled values, using a version of the
+ * [Fisher-Yates shuffle](https://en.wikipedia.org/wiki/Fisher-Yates_shuffle).
+ *
+ * @since 0.1.0
+ * @category Array
+ * @param array - The array or object to shuffle.
+ * @returns {Array} Returns the new shuffled array.
+ * @example
+ * shuffle([1, 2, 3, 4])
+ * // => [4, 1, 3, 2]
+ */
+
+export function shuffle<TInput>(array: TInput[]): TInput[] {
+    const shuffledArray = [...array];
+    let currentIndex = shuffledArray.length;
+    let temporaryValue: TInput;
+    let randomIndex: number;
+
+    // While there remain elements to shuffle...
+    while (0 !== currentIndex) {
+        // Pick a remaining element...
+        randomIndex = Math.floor(Math.random() * currentIndex);
+        currentIndex -= 1;
+
+        // And swap it with the current element.
+        temporaryValue = shuffledArray[currentIndex];
+        shuffledArray[currentIndex] = shuffledArray[randomIndex];
+        shuffledArray[randomIndex] = temporaryValue;
+    }
+
+    return shuffledArray;
+}

package/src/array/takeRightWhile.ts

@@ -0,0 +1,33 @@
+/**
+ * Creates a slice of `array` with elements taken from the end. Elements are
+ * taken until `predicate` returns falsey. The predicate is invoked with
+ * three arguments: (value, index, array).
+ *
+ * @category Array
+ * @param predicate - The function invoked per iteration.
+ * @param array - The array to query.
+ * @returns Returns the slice of `array`.
+ * @example
+ * const users = [
+ *   { 'user': 'barney',  'active': false },
+ *   { 'user': 'fred',    'active': true },
+ *   { 'user': 'pebbles', 'active': true }
+ * ]
+ *
+ * takeRightWhile(({ active }) => active, users)
+ * // => objects for ['fred', 'pebbles']
+ */
+
+export function takeRightWhile<T>(predicate: (elem: T) => boolean, array: T[]): T[] {
+    const result: T[] = [];
+
+    for (let i = array.length - 1; i >= 0; i--) {
+        if (predicate(array[i])) {
+            result.unshift(array[i]);
+        } else {
+            break;
+        }
+    }
+
+    return result;
+}

package/src/array/takeWhile.ts

@@ -0,0 +1,33 @@
+/**
+ * Creates a slice of `array` with elements taken from the beginning. Elements
+ * are taken until `predicate` returns falsey. The predicate is invoked with
+ * three arguments: (value, index, array).
+ *
+ * @category Array
+ * @param predicate The function invoked per iteration.
+ * @param array The array to query.
+ * @returns Returns the slice of `array`.
+ * @example
+ * const users = [
+ *   { 'user': 'barney',  'active': true },
+ *   { 'user': 'fred',    'active': true },
+ *   { 'user': 'pebbles', 'active': false }
+ * ]
+ *
+ * takeWhile(({ active }) => active, users)
+ * // => objects for ['barney', 'fred']
+ */
+
+export function takeWhile<T>(predicate: (elem: T) => boolean, array: T[]): T[] {
+    const result: T[] = [];
+
+    for (const element of array) {
+        if (predicate(element)) {
+            result.push(element);
+        } else {
+            break;
+        }
+    }
+
+    return result;
+}

package/src/array/union.ts

@@ -0,0 +1,16 @@
+import type { MinimumTwoArrays } from '../types';
+
+/**
+ * Creates an array of unique values, in order, from all given arrays using for equality comparisons.
+ *
+ * @category Array
+ * @param arrays - The arrays to inspect.
+ * @returns Returns the new array of combined values.
+ * @example
+ * union([2, 3], [1, 2])
+ * // => [2, 3, 1]
+ */
+
+export function union<TInput>(...arrays: MinimumTwoArrays<TInput>): TInput[] {
+    return [...new Set(arrays.flat())];
+}

package/src/array/unionBy.ts

@@ -0,0 +1,26 @@
+import type { IterateeFunction, MinimumTwoArrays, PropertyShorthand } from '../types';
+
+import { unionWith } from '@array/unionWith';
+import { getIterateFunction } from '@helpers/shortHands';
+import { isEqualWith } from '@lang/isEqualWith';
+
+/**
+ * This method is like `union` except that it accepts `iteratee` which is
+ * invoked for each element of each `arrays` to generate the criterion by
+ * which uniqueness is computed. Result values are chosen from the first
+ * array in which the value occurs. The iteratee is invoked with one argument:
+ * (value).
+ *
+ * @category Array
+ * @param arrays - The arrays to inspect.
+ * @param iteratee - The iteratee invoked per element. Or property shorthand.
+ * @returns Returns the new array of combined values.
+ * @example
+ * unionBy(Math.floor, [2.1], [1.2, 2.3])
+ * // => [2.1, 1.2]
+ */
+
+export function unionBy<T>(iteratee: IterateeFunction<T> | PropertyShorthand<T>, ...arrays: MinimumTwoArrays<T>): T[] {
+    const iterateeFunction = getIterateFunction(iteratee);
+    return unionWith((a, b) => isEqualWith(iterateeFunction, a, b), ...arrays);
+}

package/src/array/unionWith.ts

@@ -0,0 +1,31 @@
+import type { MinimumTwoArrays } from '../types';
+
+/**
+ * This method is like `union` except that it accepts `comparator` which
+ * is invoked to compare elements of `arrays`. Result values are chosen from
+ * the first array in which the value occurs. The comparator is invoked
+ * with two arguments: (arrVal, othVal).
+ *
+ * @category Array
+ * @param comparator - The comparator invoked per element.
+ * @param arrays - The arrays to inspect.
+ * @returns Returns the new array of combined values.
+ * @example
+ * const objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }]
+ * const others = [{ 'x': 1, 'y': 1 }, { 'x': 1, 'y': 2 }]
+ *
+ * unionWith(isEqual, objects, others)
+ * // => [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }, { 'x': 1, 'y': 1 }]
+ */
+
+export function unionWith<TInput>(comparator: (a: TInput, b: TInput) => boolean, ...arrays: MinimumTwoArrays<TInput>): TInput[] {
+    return arrays.reduce((acc, current) => {
+        for (const item of current) {
+            if (acc.some(x => comparator(x, item))) {
+                continue;
+            }
+            acc.push(item);
+        }
+        return acc;
+    }, []);
+}

package/src/array/uniq.ts

@@ -0,0 +1,18 @@
+import { uniqWith } from '@array/uniqWith';
+import { isEqual } from '@lang/isEqual';
+
+/**
+ * Creates a duplicate-free version of an array, in which only the first occurrence of each element is kept.
+ * The order of result values is determined by the order they occur in the array.
+ *
+ * @category Array
+ * @param array - The array to inspect.
+ * @returns Returns the new duplicate free array.
+ * @example
+ * uniq([2, 1, 2])
+ * // => [2, 1]
+ */
+
+export function uniq<TInput>(array: TInput[]): TInput[] {
+    return uniqWith(isEqual, array);
+}

package/src/array/uniqBy.ts

@@ -0,0 +1,25 @@
+import type { IterateeFunction, PropertyShorthand } from '../types';
+
+import { uniqWith } from '@array/uniqWith';
+import { getIterateFunction } from '@helpers/shortHands';
+
+/**
+ * This method is like `uniq` except that it accepts `iteratee` which is
+ * invoked for each element in `array` to generate the criterion by which
+ * uniqueness is computed. The order of result values is determined by the
+ * order they occur in the array.
+ *
+ * @category Array
+ * @param array - The array to inspect.
+ * @param iteratee - The iteratee invoked per element. Or property shorthand.
+ * @returns Returns the new duplicate free array.
+ * @example
+ * uniqBy(Math.floor, [2.1, 1.2, 2.3])
+ * // => [2.1, 1.2]
+ */
+
+export function uniqBy<T>(iteratee: IterateeFunction<T> | PropertyShorthand<T>, array: T[]): T[] {
+    const iterateeFunction = getIterateFunction(iteratee);
+
+    return uniqWith((a, b) => iterateeFunction(a) === iterateeFunction(b), array);
+}

package/src/array/uniqWith.ts

@@ -0,0 +1,20 @@
+/**
+ * This method is like `uniq` except that it accepts `comparator` which is invoked to compare elements of `array`.
+ * The order of result values is determined by the order they occur in the array.
+ *
+ * @category Array
+ * @param array - The array to inspect.
+ * @param comparator - The comparator invoked per element.
+ * @returns {Array} Returns the new duplicate free array.
+ * @example
+ * const objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }, { 'x': 1, 'y': 2 }]
+ *
+ * uniqWith(isEqual, objects)
+ * // => [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }]
+ */
+
+export function uniqWith<TInput>(comparator: (a: TInput, b: TInput) => boolean, array: TInput[]): TInput[] {
+    return array.filter((value, index, self) => {
+        return self.findIndex(otherValue => comparator(value, otherValue)) === index;
+    });
+}

package/src/array/unzip.ts

@@ -0,0 +1,20 @@
+import { unzipWith } from '@array/unzipWith';
+
+/**
+ * This method is like `zip` except that it accepts an array of grouped
+ * elements and creates an array regrouping the elements to their pre-zip configuration.
+ *
+ * @category Array
+ * @param array - The array of grouped elements to process.
+ * @returns Returns the new array of regrouped elements.
+ * @example
+ * const zipped = zip(['a', 'b'], [1, 2], [true, false])
+ * // => [['a', 1, true], ['b', 2, false]]
+ *
+ * unzip(zipped)
+ * // => [['a', 'b'], [1, 2], [true, false]]
+ */
+
+export function unzip<TInput extends unknown[]>(array: TInput[]): TInput[] {
+    return unzipWith((...t) => t, array);
+}