moderndash 0.0.10 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moderndash",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "type": "module",
   "description": "A lodash inspired utility framework for ESM/Typescript/ES2020",
   "scripts": {
@@ -40,7 +40,7 @@
     "dist",
     "src"
   ],
-  "homepage": "https://github.com/Maggi64/moderndash#readme",
+  "homepage": "https://moderndash.io",
   "devDependencies": {
     "@vitest/coverage-c8": "0.27.1",
     "@vitest/ui": "0.27.1",

package/src/array/difference.ts

@@ -13,9 +13,9 @@ import { isEqual } from '@lang/isEqual';
  * @returns Returns the new array of filtered values.
  * @example
  * difference([2, 1], [2, 3])
- * // =\> [1]
+ * // => [1]
  */
 
-export function difference<T>(...arrays: MinimumTwoArrays<T>): T[] {
+export function difference<TInput>(...arrays: MinimumTwoArrays<TInput>): TInput[] {
     return differenceWith(isEqual, ...arrays);
 }

package/src/array/differenceBy.ts

@@ -26,5 +26,5 @@ import { isEqualWith } from '@lang/isEqualWith';
 
 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);
+    return differenceWith((a, b) => isEqualWith(a, b, iterateeFunction), ...arrays);
 }

package/src/array/index.ts

@@ -12,9 +12,6 @@ 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';

package/src/array/intersectionBy.ts

@@ -22,5 +22,5 @@ import { isEqualWith } from '@lang/isEqualWith';
 
 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);
+    return intersectionWith((a, b) => isEqualWith(a, b, iterateeFunction), ...arrays);
 }

package/src/array/shuffle.ts

@@ -5,7 +5,7 @@
  * @since 0.1.0
  * @category Array
  * @param array - The array or object to shuffle.
- * @returns {Array} Returns the new shuffled array.
+ * @returns Returns the new shuffled array.
  * @example
  * shuffle([1, 2, 3, 4])
  * // => [4, 1, 3, 2]

package/src/array/uniqWith.ts

@@ -5,7 +5,7 @@
  * @category Array
  * @param array - The array to inspect.
  * @param comparator - The comparator invoked per element.
- * @returns {Array} Returns the new duplicate free array.
+ * @returns Returns the new duplicate free array.
  * @example
  * const objects = [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }, { 'x': 1, 'y': 2 }]
  *

package/src/collection/countBy.ts

@@ -7,10 +7,6 @@ import { getValuesFromCollection } from '@helpers/collections';
  * each element of `collection` thru `iteratee`. The corresponding value of
  * each key is the number of times the key was returned by `iteratee`.
  *
- * @category Collection
- * @param iteratee - The iteratee to transform keys.
- * @param collection - The array or record to iterate over.
- * @returns Returns the composed aggregate object.
  * @example
  * const users = [
  *   { 'user': 'barney', 'active': true },
@@ -20,6 +16,10 @@ import { getValuesFromCollection } from '@helpers/collections';
  *
  * countBy(users, value => value.active);
  * // => { 'true': 2, 'false': 1 }
+ * @category Collection
+ * @param iteratee - The iteratee to transform keys.
+ * @param collection - The array or record to iterate over.
+ * @returns Returns the composed aggregate object.
  */
 
 export function countBy<TInput, TKey extends RecordKey>(collection: ArrayOrRecord<TInput>, iteratee: (value: TInput) => TKey): Record<TKey, number> {

package/src/collection/groupBy.ts

@@ -10,13 +10,13 @@ import { getValuesFromCollection } from '@helpers/collections';
  * value of each key is an array of elements responsible for generating the
  * key.
  *
+ * @example
+ * groupBy([6.1, 4.2, 6.3], Math.floor)
+ * // => { '4': [4.2], '6': [6.1, 6.3] }
  * @category Collection
  * @param collection - The array or object to iterate over.
  * @param iteratee - The iteratee to transform keys.
  * @returns Returns the composed aggregate object.
- * @example
- * groupBy([6.1, 4.2, 6.3], Math.floor)
- * // => { '4': [4.2], '6': [6.1, 6.3] }
  */
 
 export function groupBy<T, U extends RecordKey>(collection: ArrayOrRecord<T>, iteratee: (value: T) => U): Record<U, T[]> {

package/src/function/after.ts

@@ -1,3 +1,5 @@
+import type { GenericFunction } from '../types.js';
+
 /**
  * The opposite of `before`. This method creates a function that invokes `func` once it's called `n` or more times.
  *
@@ -6,13 +8,17 @@
  * @param func The function to restrict.
  * @returns Returns the new restricted function.
  * @example
- * const caution = () => alert("Caution!");
+ * const caution = () => console.log("Caution!");
+ *
+ * const afterFN = after(2, caution);
  *
- * // Display alert only after it has been called 5 times
- * after(5, caution)
+ * afterFN()
+ * afterFN()
+ * afterFN()
+ * // => `caution` is invoked after called twice
  */
 
-export function after<TFunc extends (...args: Parameters<TFunc>) => ReturnType<TFunc>>(n: number, func: TFunc) {
+export function after<TFunc extends GenericFunction<TFunc>>(n: number, func: TFunc) {
     let count = 1;
     return (...args: Parameters<TFunc>): ReturnType<TFunc> | undefined => {
         if (count >= n) {

package/src/function/before.ts

@@ -1,6 +1,5 @@
 /**
- * Creates a function that invokes `func`, with the `this` binding and arguments
- * of the created function, while it's called less than `n` times. Subsequent
+ * Creates a function that invokes `func`, while it's called less than `n` times. Subsequent
  * calls to the created function return the result of the last `func` invocation.
  *
  * @category Function
@@ -8,10 +7,15 @@
  * @param func - The function to restrict.
  * @returns Returns the new restricted function.
  * @example
- * const caution = () => alert("Caution!");
+ * const caution = () => console.log("Caution!");
  *
  * // Only call caution two times
- * before(2, caution)
+ * const reducedCaution = before(2, caution)
+ *
+ * reducedCaution()
+ * reducedCaution()
+ * reducedCaution()
+ * // => `caution` is invoked twice
  */
 
 export function before<TFunc extends (...args: Parameters<TFunc>) => ReturnType<TFunc>>(n: number, func: TFunc): TFunc {

package/src/function/debounce.ts

@@ -1,11 +1,12 @@
+import type { GenericFunction } from 'src/types.js';
 
 // TODO this is a port from lodash, it probably can be improved and shortened, also fix TS errors
-export function debounce<T extends (...args: Parameters<T>) => ReturnType<T>>(
-    fn: T, wait = 0, options: { leading?: boolean, maxWait?: number, trailing?: boolean } = {}
-): (this: ThisParameterType<T>, ...args: Parameters<T>) => ReturnType<T> {
-    let lastArgs: Parameters<T> | undefined;
-    let lastThis: ThisParameterType<T> | undefined;
-    let result: ReturnType<T>;
+export function debounce<TFunc extends GenericFunction<TFunc>>(
+    fn: TFunc, wait = 0, options: { leading?: boolean, maxWait?: number, trailing?: boolean } = {}
+): (this: ThisParameterType<TFunc>, ...args: Parameters<TFunc>) => ReturnType<TFunc> {
+    let lastArgs: Parameters<TFunc> | undefined;
+    let lastThis: ThisParameterType<TFunc> | undefined;
+    let result: ReturnType<TFunc>;
     let timerId: ReturnType<typeof setTimeout> | undefined;
     let lastCallTime: number | undefined;
     let lastInvokeTime = 0;
@@ -15,12 +16,12 @@ export function debounce<T extends (...args: Parameters<T>) => ReturnType<T>>(
     const maxWait = options.maxWait ?? 0;
 
     function invokeFunc(time: number) {
-        const args: Parameters<T> | undefined = lastArgs;
-        const thisArg: ThisParameterType<T> | undefined = lastThis;
+        const args: Parameters<TFunc> | undefined = lastArgs;
+        const thisArg: ThisParameterType<TFunc> | undefined = lastThis;
 
         lastArgs = lastThis = undefined;
         lastInvokeTime = time;
-        // @ts-ignore
+        // @ts-expect-error
         result = fn.apply(thisArg, args);
         return result;
     }
@@ -35,7 +36,7 @@ export function debounce<T extends (...args: Parameters<T>) => ReturnType<T>>(
     }
 
     function remainingWait(time: number) {
-        // @ts-ignore
+        // @ts-expect-error
         const timeSinceLastCall = time - lastCallTime;
         const timeSinceLastInvoke = time - lastInvokeTime;
         const timeWaiting = wait - timeSinceLastCall;
@@ -91,7 +92,7 @@ export function debounce<T extends (...args: Parameters<T>) => ReturnType<T>>(
         return timerId === undefined ? result : trailingEdge(Date.now());
     }
 
-    function debounced(this: ThisParameterType<T>, ...args: Parameters<T>): ReturnType<T> {
+    function debounced(this: ThisParameterType<TFunc>, ...args: Parameters<TFunc>): ReturnType<TFunc> {
         const time = Date.now();
         const isInvoking = shouldInvoke(time);
 

package/src/function/index.ts

@@ -4,3 +4,4 @@ export * from './debounce';
 export * from './memoize';
 export * from './once';
 export * from './throttle';
+export * from './times';

package/src/function/memoize.ts

@@ -1,5 +1,6 @@
+import type{ GenericFunction } from 'src/types.js';
+
 const defaultResolver = (...args: unknown[]) => JSON.stringify(args);
-type Cache = Map<string | symbol, unknown>;
 
 /**
  * Creates a function that memoizes the result of `func`. If `resolver` is
@@ -16,6 +17,8 @@ type Cache = Map<string | symbol, unknown>;
  * @category Function
  * @param func - The function to have its output memoized.
  * @param resolver - The function to resolve the cache key.
+ * @typeParam TFunc - The input function type
+ * @typeParam Cache - The cache map type
  * @returns  Returns the new memoized function.
  * @example
  * const object = \{ 'a': 1, 'b': 2 \}
@@ -40,10 +43,11 @@ type Cache = Map<string | symbol, unknown>;
  * memoize.Cache = WeakMap
  */
 
-export function memoize<TFunc extends (...args: Parameters<TFunc>) => ReturnType<TFunc>>(
+export function memoize<TFunc extends GenericFunction<TFunc>, Cache extends Map<string | symbol, ReturnType<TFunc>>>(
     func: TFunc, resolver: ((...args: Parameters<TFunc>) => string | symbol) = defaultResolver
 ): TFunc & { cache: Cache } {
-    const cache: Cache = new Map();
+
+    const cache = new Map() as Cache;
     const memoizedFunc = (...args: Parameters<TFunc>): ReturnType<TFunc> => {
         const key = resolver(...args);
         if (cache.has(key)) {

package/src/function/once.ts

@@ -1,3 +1,7 @@
+import type { GenericFunction } from 'src/types.js';
+
+import { before } from '@function/before';
+
 /**
  * Creates a function that is restricted to invoking `func` once. Repeat calls
  * to the function return the value of the first invocation. The `func` is
@@ -7,13 +11,12 @@
  * @param func - The function to restrict.
  * @returns Returns the new restricted function.
  * @example
- * const initialize = once(createApplication)
+ * const initialize = once(() => console.log('initialize'))
  * initialize()
  * initialize()
  * // => `createApplication` is invoked once
  */
-import { before } from '@function/before';
 
-export function once<TFunc extends (...args: Parameters<TFunc>) => ReturnType<TFunc>>(func: TFunc): TFunc {
+export function once<TFunc extends GenericFunction<TFunc>>(func: TFunc): TFunc {
     return before(1, func);
 }

package/src/function/throttle.ts

@@ -1,8 +1,10 @@
+import type { GenericFunction } from 'src/types.js';
+
 import { debounce } from '@function/debounce';
 
-export function throttle<T extends (...args: Parameters<T>) => ReturnType<T>>(
-    func: T, wait = 0, options: { leading?: boolean, trailing?: boolean } = {}
-): (this: ThisParameterType<T>, ...args: Parameters<T>) => ReturnType<T> {
+export function throttle<TFunc extends GenericFunction<TFunc>>(
+    func: TFunc, wait = 0, options: { leading?: boolean, trailing?: boolean } = {}
+): (this: ThisParameterType<TFunc>, ...args: Parameters<TFunc>) => ReturnType<TFunc> {
     return debounce(func, wait, {
         leading: options.leading ?? true,
         maxWait: wait,

package/src/lang/isEmpty.ts

@@ -1,4 +1,36 @@
-export function isEmpty(value: unknown): boolean {
+/**
+ * Checks if `value` is an empty object, collection, map, or set.
+ *
+ * Objects are considered empty if they have no own enumerable string keyed
+ * properties.
+ *
+ * Array-like values such as `arguments` objects, arrays, buffers, strings, or
+ * Similarly, maps and sets are considered empty if they have a `size` of `0`.
+ *
+ * @category Lang
+ * @param value - The value to check.
+ * @returns Returns `true` if `value` is empty, else `false`.
+ * @example
+ * isEmpty(null)
+ * // => true
+ *
+ * isEmpty({})
+ * // => true
+ *
+ * isEmpty("")
+ * // => true
+ *
+ * isEmpty([1, 2, 3])
+ * // => false
+ *
+ * isEmpty('abc')
+ * // => false
+ *
+ * isEmpty({ 'a': 1 })
+ * // => false
+ */
+
+export function isEmpty(value: string | object | null | undefined): boolean {
     if (value === null || value === undefined) {
         return true;
     }
@@ -7,10 +39,6 @@ export function isEmpty(value: unknown): boolean {
         return value.length === 0;
     }
 
-    if (typeof value === 'number') {
-        return false;
-    }
-
     if (value instanceof Map || value instanceof Set) {
         return value.size === 0;
     }

package/src/lang/isEqual.ts

@@ -1,5 +1,31 @@
 import type { RecordKey } from '../types';
 
+
+/**
+ * Performs a deep comparison between two values to determine if they are
+ * equivalent.
+ *
+ * **Note:** This method supports comparing arrays, array buffers, booleans,
+ * date objects, error objects, maps, numbers, `Object` objects, regexes,
+ * sets, strings, symbols, and typed arrays. `Object` objects are compared
+ * by their own, not inherited, enumerable properties. Functions and DOM
+ * nodes are compared by strict equality, i.e. `===`.
+ *
+ * @category Lang
+ * @param value1 - The value to compare.
+ * @param value2 - The other value to compare.
+ * @returns Returns `true` if the values are equivalent, else `false`.
+ * @example
+ * var object = { 'a': 1 };
+ * var other = { 'a': 1 };
+ *
+ * _.isEqual(object, other);
+ * // => true
+ *
+ * object === other;
+ * // => false
+ */
+
 export function isEqual(value1: unknown, value2: unknown): boolean {
     if (value1 === value2) return true;
 

package/src/lang/isEqualWith.ts

@@ -1,5 +1,34 @@
 import { isEqual } from '@lang/isEqual';
 
-export function isEqualWith<T>(customizer: (value: T) => unknown, a: T, b: T): boolean {
+/**
+ * This method is like `_.isEqual` except that it accepts `customizer` which
+ * is invoked to compare values. If `customizer` returns `undefined`, comparisons
+ * are handled by the method instead. The `customizer` is invoked with up to
+ * six arguments: (objValue, othValue [, index|key, object, other, stack]).
+ *
+ * @category Lang
+ * @param value1 - The value to compare.
+ * @param value2 - The other value to compare.
+ * @param customizer - The function to customize comparisons.
+ * @returns Returns `true` if the values are equivalent, else `false`.
+ * @example
+ * function isGreeting(value) {
+ *   return /^h(?:i|ello)$/.test(value);
+ * }
+ *
+ * function customizer(objValue, othValue) {
+ *   if (isGreeting(objValue) && isGreeting(othValue)) {
+ *     return true;
+ *   }
+ * }
+ *
+ * var array = ['hello', 'goodbye'];
+ * var other = ['hi', 'goodbye'];
+ *
+ * isEqualWith(array, other, customizer);
+ * // => true
+*/
+
+export function isEqualWith<T>(a: T, b: T, customizer: (value: T) => unknown): boolean {
     return isEqual(customizer(a), customizer(b));
 }

package/src/object/pick.ts

@@ -1,16 +1,15 @@
 /**
  * Creates an object composed of the picked `object` properties.
  *
- * @category Object
- * @param object The source object.
- * @param keys The property paths to pick.
- * @returns {Object} Returns the new object.
  * @example
- *
  * const object = { 'a': 1, 'b': '2', 'c': 3 }
  *
  * pick(object, ['a', 'c'])
  * // => { 'a': 1, 'c': 3 }
+ * @category Object
+ * @param object - The source object.
+ * @param keys - The property paths to pick.
+ * @returns Returns the new object.
  */
 
 export function pick<T, K extends keyof T>(object: T, keys: K[]): Pick<T, K> {

package/src/string/camelCase.ts

@@ -1,5 +1,20 @@
 import { splitWords } from '@helpers/stringModifiers';
 
+/**
+ * Converts `string` to camelCase.
+ *
+ * @example
+ * camelCase('Foo Bar')
+ * // => 'fooBar'
+ * camelCase('--foo-bar--')
+ * // => 'fooBar'
+ * camelCase('__FOO_BAR__')
+ * // => 'fooBar'
+ * @category String
+ * @param str - The string to convert.
+ * @returns Returns the camel cased string.
+ */
+
 export function camelCase(str: string): string {
     const words = splitWords(str);
 

package/src/string/capitalize.ts

@@ -1,3 +1,14 @@
+/**
+ * Converts the first character of a string to upper case and the remaining to lower case.
+ *
+ * @example
+ * capitalize('FRED')
+ * // => 'Fred'
+ * @category String
+ * @param str - The string to capitalize.
+ * @returns Returns the capitalized string.
+ */
+
 export function capitalize(str: string): string {
     return str.charAt(0).toUpperCase() + str.slice(1);
 }

package/src/string/deburr.ts

@@ -1,3 +1,18 @@
+/**
+ * Deburrs a string by converting
+ * [Latin-1 Supplement](https://en.wikipedia.org/wiki/Latin-1_Supplement_(Unicode_block)#Character_table)
+ * and [Latin Extended-A](https://en.wikipedia.org/wiki/Latin_Extended-A)
+ * letters to basic Latin letters and removing
+ * [combining diacritical marks](https://en.wikipedia.org/wiki/Combining_Diacritical_Marks).
+ *
+ * @example
+ * deburr('déjà vu')
+ * // => 'deja vu'
+ * @category String
+ * @param str - The string to deburr.
+ * @returns Returns the deburred string.
+ */
+
 export function deburr(str: string): string {
     // eslint-disable-next-line no-control-regex
     return str.replace(/[^\u0000-\u007E]/g, (chr: string) =>

package/src/string/escape.ts

@@ -1,3 +1,14 @@
+/**
+ * Converts the characters `&`, `<`, `>`, `"` and `'` in a string to their corresponding HTML entities.
+ *
+ * @example
+ * escape('fred, barney, & pebbles')
+ * // => 'fred, barney, &amp; pebbles'
+ * @category String
+ * @param str - The string to escape.
+ * @returns Returns the escaped string.
+ */
+
 export function escape(str: string): string {
     const escapeChars: Record<string, string> = {
         '&': '&amp;',

package/src/string/escapeRegExp.ts

@@ -1,3 +1,15 @@
+/**
+ * Escapes the `RegExp` special characters `^`, `$`, `\`, `.`, `*`, `+`,
+ * `?`, `(`, `)`, `[`, `]`, `{`, `}`, and `|` in a string.
+ *
+ * @example
+ * escapeRegExp('[moderndash](https://moderndash.io/)')
+ * // => '\[moderndash\]\(https://moderndash\.io/\)'
+ * @category String
+ * @param str - The string to escape.
+ * @returns Returns the escaped string.
+ */
+
 export function escapeRegExp(str: string): string {
     return str.replace(/[$()*+.?[\\\]^{|}]/g, '\\$&');
 }

package/src/string/kebabCase.ts

@@ -1,5 +1,20 @@
 import { splitWords } from '@helpers/stringModifiers';
 
+/**
+ * Converts a string to kebab-case.
+ *
+ * @example
+ * kebabCase('Foo Bar')
+ * // => 'foo-bar'
+ * kebabCase('fooBar')
+ * // => 'foo-bar'
+ * kebabCase('__FOO_BAR__')
+ * // => 'foo-bar'
+ * @category String
+ * @param str - The string to convert.
+ * @returns Returns the kebab cased string.
+ */
+
 export function kebabCase(str: string): string {
     const words = splitWords(str);
     let kebabCase = '';

package/src/string/pascalCase.ts

@@ -1,5 +1,21 @@
 import { splitWords } from '@helpers/stringModifiers';
 
+
+/**
+ * Converts a string to PascalCase.
+ *
+ * @example
+ * kebabCase('Foo Bar')
+ * // => 'FooBar'
+ * kebabCase('fooBar')
+ * // => 'FooBar'
+ * kebabCase('__FOO_BAR__')
+ * // => 'FooBar'
+ * @category String
+ * @param str - The string to convert.
+ * @returns Returns the pascal cased string.
+ */
+
 export function pascalCase(str: string): string {
     const words = splitWords(str);
     let pascalCase = '';

package/src/string/snakeCase.ts

@@ -1,5 +1,22 @@
 import { splitWords } from '@helpers/stringModifiers';
 
+/**
+ * Converts a string to snake_case.
+ *
+ * @example
+ * snakeCase('Foo Bar')
+ * // => 'foo_bar'
+ * snakeCase('fooBar')
+ * // => 'foo_bar'
+ * snakeCase('--FOO-BAR--')
+ * // => 'foo_bar'
+ * snakeCase('foo2bar')
+ * // => 'foo_2_bar'
+ * @category String
+ * @param str - The string to convert.
+ * @returns Returns the snake cased string.
+ */
+
 export function snakeCase(str: string): string {
     const words = splitWords(str);
     let snakeCase = '';

package/src/string/startCase.ts

@@ -1,5 +1,20 @@
 import { splitWords } from '@helpers/stringModifiers';
 
+/**
+ * Converts a string to Start Case.
+ *
+ * @example
+ * startCase('--foo-bar--')
+ * // => 'Foo Bar'
+ * startCase('fooBar')
+ * // => 'Foo Bar'
+ * startCase('__FOO_BAR__')
+ * // => 'Foo Bar'
+ * @category String
+ * @param str - The string to convert.
+ * @returns Returns the start cased string.
+ */
+
 export function startCase(str: string): string {
     const words = splitWords(str);
     let startCase = '';

package/src/string/stripSpecialChars.ts

@@ -1,5 +1,16 @@
 import { deburr } from '@string/deburr';
 
+/**
+ * Removes all special characters from a string.
+ *
+ * @example
+ * stripSpecialChars('Héllo! World #$%&*!')
+ * // => 'Hello World'
+ * @category String
+ * @param str - The string to remove special characters from.
+ * @returns Returns the string with special characters removed.
+*/
+
 export function stripSpecialChars(str: string): string {
     str = deburr(str);
     return str.replace(/[^\s\w]/gi, '');