@valkyriestudios/utils 12.17.1 → 12.18.0

package/README.md

@@ -633,6 +633,9 @@ equal(new RegExp(/ab+c/, 'i'), /ab+c/i); // TRUE
 ```
 
 ### function
+- **debounce(val:Fn, wait:number)**
+Wrap a function in a debounce proxy that waits for X uninterrupted milliseconds before running callback function
+
 - **isFunction(val:unknown)**
 Check if a variable is a Function
 
@@ -923,13 +926,16 @@ isNotEmptyString(' ', false); // TRUE
 isNotEmptyString('Hi'); // TRUE
 ```
 
-- **shorten(val:any, length:integer, postfix:string=...)**
+- **shorten(val:any, length:integer, postfix:string=..., truncate_words=true)**
 Shorten a string and add a postfix if string went over length
 ```typescript
 shorten('To the moon and beyond', 11, '..'); // 'To the moon..'
 shorten('Hi', 250); // 'Hi'
 shorten('To the moon and beyond'); // 'To the moon...'
 shorten('To the moon and beyond', 11, ' '); // 'To the moon '
+
+/* For when you don't want words to be truncated mid-word */
+shorten('To the moon and beyond', 11, '...', false);
 ```
 
 - **humanizeBytes(val:number|string)**

package/array/dedupe.js

@@ -2,35 +2,53 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dedupe = dedupe;
 exports.default = dedupe;
-const fnv1A_1 = require("../hash/fnv1A");
+const REPL_NAN = 'nan';
+const REPL_TRUE = 'true';
+const REPL_FALSE = 'false';
+const REPL_UNDEF = 'undefined';
+const REPL_NULL = 'null';
+function getTypeString(el) {
+    switch (typeof el) {
+        case 'string':
+            return el;
+        case 'number':
+            return Number.isNaN(el) || !Number.isFinite(el) ? REPL_NAN : String(el);
+        case 'boolean':
+            return el ? REPL_TRUE : REPL_FALSE;
+        case 'undefined':
+            return REPL_UNDEF;
+        case 'object':
+            if (el === null) {
+                return REPL_NULL;
+            }
+            else if (Array.isArray(el) || el.toString() === '[object Object]') {
+                return JSON.stringify(el);
+            }
+            else if (el instanceof RegExp) {
+                return el.toString();
+            }
+            else if (el instanceof Date) {
+                return String(el.getTime());
+            }
+    }
+    return '';
+}
 function dedupe(val, opts) {
     if (!Array.isArray(val))
         return [];
-    const FILTER_FN = typeof opts?.filter_fn === 'function' ? opts?.filter_fn : false;
+    const FILTER_FN = opts?.filter_fn;
     const set = new Set();
     const acc = [];
     let hash;
     const len = val.length;
-    if (FILTER_FN) {
-        for (let i = 0; i < len; i++) {
-            const el = val[i];
-            if (FILTER_FN && !FILTER_FN(el))
-                continue;
-            hash = (0, fnv1A_1.fnv1A)(el);
-            if (!set.has(hash)) {
-                set.add(hash);
-                acc.push(el);
-            }
-        }
-    }
-    else {
-        for (let i = 0; i < len; i++) {
-            const el = val[i];
-            hash = (0, fnv1A_1.fnv1A)(el);
-            if (!set.has(hash)) {
-                set.add(hash);
-                acc.push(el);
-            }
+    for (let i = 0; i < len; i++) {
+        const el = val[i];
+        if (FILTER_FN && !FILTER_FN(el))
+            continue;
+        hash = getTypeString(el);
+        if (!set.has(hash)) {
+            set.add(hash);
+            acc.push(el);
         }
     }
     return acc;

package/array/groupBy.js

@@ -23,11 +23,12 @@ function groupBy(arr, handler) {
         key = n_handler(el);
         if (key === undefined || (typeof key === 'string' && !key.length))
             key = FALLBACK;
-        if (Array.isArray(acc[key])) {
+        if (!acc[key]) {
+            acc[key] = [el];
+        }
+        else {
             acc[key].push(el);
-            continue;
         }
-        acc[key] = [el];
     }
     return acc;
 }

package/array/mapKey.js

@@ -3,19 +3,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.mapKey = mapKey;
 exports.default = mapKey;
 function mapKey(arr, key, opts) {
-    if ((!Array.isArray(arr) || !arr.length) ||
-        typeof key !== 'string')
+    if (!Array.isArray(arr) || typeof key !== 'string')
         return {};
     const key_s = key.trim();
     if (!key_s.length)
         return {};
+    const len = arr.length;
+    if (!len)
+        return {};
     const MERGE = opts?.merge === true;
     const map = {};
-    for (let i = 0; i < arr.length; i++) {
+    for (let i = 0; i < len; i++) {
         const el = arr[i];
-        if (el?.[key_s] === undefined)
+        const el_key = el?.[key_s];
+        if (el_key === undefined)
             continue;
-        map[el[key_s]] = MERGE && map.hasOwnProperty(el[key_s]) ? { ...map[el[key_s]], ...el } : el;
+        map[el_key] = MERGE && el_key in map ? { ...map[el_key], ...el } : el;
     }
     return map;
 }

package/array/sort.d.ts

@@ -60,5 +60,5 @@ type sortByFunction = (el: Record<string, any>) => string;
  */
 declare function sort<T extends {
     [key: string]: any;
-}[]>(arr: T, by: string | sortByFunction, dir?: 'asc' | 'desc', opts?: sortOptions<T>): T;
+}>(arr: T[], by: string | sortByFunction, dir?: 'asc' | 'desc', opts?: sortOptions<T>): T[];
 export { sort, sort as default };

package/array/sort.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sort = sort;
 exports.default = sort;
-const isNotEmpty_1 = require("../object/isNotEmpty");
+const is_1 = require("../object/is");
 const INSERTION_SORT_THRESHOLD = 10;
 function partition(arr, low, high) {
     const pivot = arr[(low + high) >> 1][0];
@@ -24,9 +24,9 @@ function partition(arr, low, high) {
     return i;
 }
 function quickSort(arr) {
-    const stack = [{ low: 0, high: arr.length - 1 }];
+    const stack = [[0, arr.length - 1]];
     while (stack.length) {
-        const { low, high } = stack.pop();
+        const [low, high] = stack.pop();
         if (high - low <= INSERTION_SORT_THRESHOLD) {
             for (let i = low + 1; i <= high; i++) {
                 const key = arr[i];
@@ -41,22 +41,24 @@ function quickSort(arr) {
         else {
             const p = partition(arr, low, high);
             if (p - 1 > low)
-                stack.push({ low, high: p - 1 });
+                stack.push([low, p - 1]);
             if (p < high)
-                stack.push({ low: p, high });
+                stack.push([p, high]);
         }
     }
-    return arr;
 }
 function sort(arr, by, dir = 'asc', opts) {
-    if (!Array.isArray(arr) || !arr.length)
+    if (!Array.isArray(arr))
+        return [];
+    const len = arr.length;
+    if (!len)
         return [];
     const NOKEY_HIDE = opts?.nokey_hide === true;
     const NOKEY_AT_END = opts?.nokey_atend !== false;
-    let FILTER_FN = isNotEmpty_1.isNotEmptyObject;
+    let FILTER_FN = is_1.isObject;
     if (typeof opts?.filter_fn === 'function') {
         const fn = opts.filter_fn;
-        FILTER_FN = (el => (0, isNotEmpty_1.isNotEmptyObject)(el) && fn(el));
+        FILTER_FN = (el => (0, is_1.isObject)(el) && fn(el));
     }
     const prepared_arr = [];
     const nokey_arr = [];
@@ -64,19 +66,22 @@ function sort(arr, by, dir = 'asc', opts) {
         const by_s = by.trim();
         if (!by_s.length)
             throw new Error('Sort by as string should contain content');
-        for (const el of arr) {
+        for (let i = 0; i < len; i++) {
+            const el = arr[i];
             if (!FILTER_FN(el))
                 continue;
-            if (el?.[by_s] === undefined) {
+            const key = el?.[by_s];
+            if (key === undefined) {
                 nokey_arr.push(el);
             }
             else {
-                prepared_arr.push([el[by_s], el]);
+                prepared_arr.push([key, el]);
             }
         }
     }
     else if (typeof by === 'function') {
-        for (const el of arr) {
+        for (let i = 0; i < len; i++) {
+            const el = arr[i];
             if (!FILTER_FN(el))
                 continue;
             const key = by(el);

package/function/debounce.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Debounce a function
+ *
+ * Take Note, the debounced function also contains a "cancel" and "flush" method
+ * "cancel": Allows clearing the timeout
+ * "flush": Allows immediately executing the debounced function if pending
+ *
+ * Example Usage:
+ *
+ * const log = (message: string) => console.log(message);
+ *
+ * const debouncedLog = debounce(log, 2000);
+ *
+ * debouncedLog("Hello, World!");
+ * debouncedLog.cancel();
+ * debouncedLog.flush();
+ *
+ * @param {Function} fn - Function to debounce
+ * @param {number} wait - Amount of time to debounce the function for
+ */
+declare function debounce<T extends (...args: any[]) => any>(fn: T, wait: number): T & {
+    cancel: () => void;
+    flush: () => void;
+};
+export { debounce, debounce as default };

package/function/debounce.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debounce = debounce;
+exports.default = debounce;
+const is_1 = require("./is");
+const isIntegerAbove_1 = require("../number/isIntegerAbove");
+function debounce(fn, wait) {
+    if (!(0, is_1.isFunction)(fn))
+        throw new Error('functions/debounce: Expected a function');
+    if (!(0, isIntegerAbove_1.isIntegerAbove)(wait, 0))
+        throw new Error('functions/debounce: Wait should be an integer above 0');
+    let timeout;
+    let self;
+    let current_args;
+    let current_rslt;
+    const clear = () => {
+        if (!timeout)
+            return;
+        clearTimeout(timeout);
+        timeout = null;
+    };
+    const flush = () => {
+        if (!timeout)
+            return;
+        current_rslt = fn.apply(self, current_args);
+        clearTimeout(timeout);
+        timeout = null;
+    };
+    const debouncedFn = function (...args) {
+        self = this;
+        current_args = args;
+        clear();
+        timeout = setTimeout(() => {
+            timeout = null;
+            current_rslt = fn.apply(self, current_args);
+        }, wait);
+        return current_rslt;
+    };
+    debouncedFn.cancel = clear;
+    debouncedFn.flush = flush;
+    return debouncedFn;
+}

package/function/index.d.ts

@@ -1,7 +1,8 @@
+import { debounce } from './debounce';
 import { isFunction } from './is';
 import { isAsyncFunction } from './isAsync';
 import { noop } from './noop';
 import { noopresolve } from './noopresolve';
 import { noopreturn } from './noopreturn';
 import { sleep } from './sleep';
-export { isFunction, isFunction as is, isFunction as isFn, isAsyncFunction, isAsyncFunction as isAsync, isAsyncFunction as isAsyncFn, noop, noopresolve, noopreturn, sleep };
+export { debounce, isFunction, isFunction as is, isFunction as isFn, isAsyncFunction, isAsyncFunction as isAsync, isAsyncFunction as isAsyncFn, noop, noopresolve, noopreturn, sleep };

package/function/index.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sleep = exports.noopreturn = exports.noopresolve = exports.noop = exports.isAsyncFn = exports.isAsync = exports.isAsyncFunction = exports.isFn = exports.is = exports.isFunction = void 0;
+exports.sleep = exports.noopreturn = exports.noopresolve = exports.noop = exports.isAsyncFn = exports.isAsync = exports.isAsyncFunction = exports.isFn = exports.is = exports.isFunction = exports.debounce = void 0;
+const debounce_1 = require("./debounce");
+Object.defineProperty(exports, "debounce", { enumerable: true, get: function () { return debounce_1.debounce; } });
 const is_1 = require("./is");
 Object.defineProperty(exports, "isFunction", { enumerable: true, get: function () { return is_1.isFunction; } });
 Object.defineProperty(exports, "is", { enumerable: true, get: function () { return is_1.isFunction; } });

package/index.d.ts

@@ -6,10 +6,6 @@ declare module "equal" {
     function equal(a: any, b: any): boolean;
     export { equal, equal as default };
 }
-declare module "hash/fnv1A" {
-    function fnv1A(data: unknown, offset?: number): number;
-    export { fnv1A, fnv1A as default };
-}
 declare module "array/dedupe" {
     type DedupeOptions<T> = {
         filter_fn?: (el: T) => boolean;
@@ -91,6 +87,12 @@ declare module "array/split" {
     function split<T>(arr: T[], size: number, opts?: SplitOptions<T>): T[][];
     export { split, split as default };
 }
+declare module "object/is" {
+    function isObject(val: unknown): val is {
+        [key: string]: any;
+    };
+    export { isObject, isObject as default };
+}
 declare module "array/sort" {
     type sortOptions<T> = {
         filter_fn?: (el: T) => boolean;
@@ -100,7 +102,7 @@ declare module "array/sort" {
     type sortByFunction = (el: Record<string, any>) => string;
     function sort<T extends {
         [key: string]: any;
-    }[]>(arr: T, by: string | sortByFunction, dir?: 'asc' | 'desc', opts?: sortOptions<T>): T;
+    }>(arr: T[], by: string | sortByFunction, dir?: 'asc' | 'desc', opts?: sortOptions<T>): T[];
     export { sort, sort as default };
 }
 declare module "array/index" {
@@ -205,6 +207,17 @@ declare module "function/is" {
     function isFunction(val: unknown): val is (...args: unknown[]) => unknown;
     export { isFunction, isFunction as default };
 }
+declare module "number/isIntegerAbove" {
+    function isIntegerAbove(val: unknown, ref: number): val is number;
+    export { isIntegerAbove, isIntegerAbove as default };
+}
+declare module "function/debounce" {
+    function debounce<T extends (...args: any[]) => any>(fn: T, wait: number): T & {
+        cancel: () => void;
+        flush: () => void;
+    };
+    export { debounce, debounce as default };
+}
 declare module "function/isAsync" {
     function isAsyncFunction(val: unknown): val is (...args: unknown[]) => Promise<unknown>;
     export { isAsyncFunction, isAsyncFunction as default };
@@ -226,13 +239,14 @@ declare module "function/sleep" {
     export { sleep, sleep as default };
 }
 declare module "function/index" {
+    import { debounce } from "function/debounce";
     import { isFunction } from "function/is";
     import { isAsyncFunction } from "function/isAsync";
     import { noop } from "function/noop";
     import { noopresolve } from "function/noopresolve";
     import { noopreturn } from "function/noopreturn";
     import { sleep } from "function/sleep";
-    export { isFunction, isFunction as is, isFunction as isFn, isAsyncFunction, isAsyncFunction as isAsync, isAsyncFunction as isAsyncFn, noop, noopresolve, noopreturn, sleep };
+    export { debounce, isFunction, isFunction as is, isFunction as isFn, isAsyncFunction, isAsyncFunction as isAsync, isAsyncFunction as isAsyncFn, noop, noopresolve, noopreturn, sleep };
 }
 declare module "regexp/is" {
     function isRegExp(val: unknown): val is RegExp;
@@ -257,12 +271,6 @@ declare module "object/define" {
     };
     export { define, define as default };
 }
-declare module "object/is" {
-    function isObject(val: unknown): val is {
-        [key: string]: any;
-    };
-    export { isObject, isObject as default };
-}
 declare module "object/merge" {
     function merge(target: {
         [key: string]: any;
@@ -333,10 +341,6 @@ declare module "number/isInteger" {
     function isInteger(val: unknown): val is number;
     export { isInteger, isInteger as default };
 }
-declare module "number/isIntegerAbove" {
-    function isIntegerAbove(val: unknown, ref: number): val is number;
-    export { isIntegerAbove, isIntegerAbove as default };
-}
 declare module "number/isIntegerBelow" {
     function isIntegerBelow(val: unknown, ref: number): val is number;
     export { isIntegerBelow, isIntegerBelow as default };
@@ -412,7 +416,7 @@ declare module "string/isBetween" {
     export { isStringBetween, isStringBetween as default };
 }
 declare module "string/shorten" {
-    function shorten(val: string, length: number, postfix?: string): string;
+    function shorten(val: string, length: number, postfix?: string, truncate_words?: boolean): string;
     export { shorten, shorten as default };
 }
 declare module "string/index" {
@@ -528,6 +532,10 @@ declare module "deep/index" {
     import { deepSet } from "deep/set";
     export { deepFreeze as freeze, deepFreeze, deepGet as get, deepGet, deepSeal as seal, deepSeal, deepSet as set, deepSet };
 }
+declare module "hash/fnv1A" {
+    function fnv1A(data: unknown, offset?: number): number;
+    export { fnv1A, fnv1A as default };
+}
 declare module "hash/guid" {
     function guid(): string;
     export { guid, guid as default };

package/package.json

@@ -1 +1 @@
-{ "name": "@valkyriestudios/utils", "version": "12.17.1", "description": "A collection of single-function utilities for common tasks", "author": { "name": "Peter Vermeulen", "url": "https://www.linkedin.com/in/petervermeulen1/" }, "keywords": [ "utility", "library", "javascript", "js", "node", "bun" ], "license": "MIT", "repository": { "type": "git", "url": "git+https://github.com/ValkyrieStudios/utils.git" }, "bugs": { "url": "https://github.com/ValkyrieStudios/utils/issues" }, "homepage": "https://github.com/ValkyrieStudios/utils#readme", "types": "index.d.ts" }
+{ "name": "@valkyriestudios/utils", "version": "12.18.0", "description": "A collection of single-function utilities for common tasks", "author": { "name": "Peter Vermeulen", "url": "https://www.linkedin.com/in/petervermeulen1/" }, "keywords": [ "utility", "library", "javascript", "js", "node", "bun" ], "license": "MIT", "repository": { "type": "git", "url": "git+https://github.com/ValkyrieStudios/utils.git" }, "bugs": { "url": "https://github.com/ValkyrieStudios/utils/issues" }, "homepage": "https://github.com/ValkyrieStudios/utils#readme", "types": "index.d.ts" }

package/string/shorten.d.ts

@@ -1,11 +1,12 @@
 /**
  * Shorten a string and add a postfix if it goes over a specific length, will autotrim value.
  *
- * @param val - String value to shorten
- * @param length - Length to shorten it to
- * @param postfix - (default='...') Postfix to use in case the string got shortened
+ * @param {string} val - String value to shorten
+ * @param {number} length - Length to shorten it to
+ * @param {string} postfix - (default:'...') Postfix to use in case the string got shortened
+ * @param {boolean?} truncate_words - (default:true) Truncate words or not
  *
  * @returns Shortened string
  */
-declare function shorten(val: string, length: number, postfix?: string): string;
+declare function shorten(val: string, length: number, postfix?: string, truncate_words?: boolean): string;
 export { shorten, shorten as default };

package/string/shorten.js

@@ -2,11 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.shorten = shorten;
 exports.default = shorten;
-function shorten(val, length, postfix = '...') {
+function shorten(val, length, postfix = '...', truncate_words = true) {
     if (typeof val !== 'string')
         return '';
     if (typeof postfix !== 'string' || !Number.isInteger(length) || length <= 0)
         return val;
     const sanitized = val.trim();
-    return sanitized.length <= length ? sanitized : `${sanitized.substring(0, length)}${postfix}`;
+    if (sanitized.length <= length)
+        return sanitized;
+    const truncated = sanitized.substring(0, length);
+    if (truncate_words)
+        return truncated + postfix;
+    let end = length;
+    while (end > 0 && sanitized[end] !== ' ' && sanitized[end - 1] !== ' ') {
+        end--;
+    }
+    if (end === 0) {
+        return sanitized.substring(0, length) + postfix;
+    }
+    return sanitized.substring(0, end).trim() + postfix;
 }