@valkyriestudios/utils 12.5.0 → 12.6.1

package/README.md

@@ -30,7 +30,7 @@ isNotEmptyArray([]); // FALSE
 isNotEmptyArray([0, 1, 2]); // TRUE
 ```
 
-- **mapKey(val:array[Object], key:string, opts:object={})**
+- **mapKey(val:Record[], key:string, opts:object={})**
 Map a non-primitive object array into an object map by key
 ```js
 mapKey([
@@ -99,7 +99,7 @@ output:
 }
 ```
 
-- **mapFn(val:array[Object], key:Function, opts:object={})**
+- **mapFn(val:Record[], key:Function, opts:object={})**
 Same behavior as mapKey but instead of a key, a function is passed to generate your own key. Eg:
 
 ```js
@@ -120,7 +120,7 @@ output:
 
 options are the same as the mapKey function
 
-- **mapPrimitive(val:any, opts:object={valtrim:false,keyround:false,valround:false})**
+- **mapPrimitive(val:any[], opts:object={valtrim:false,keyround:false,valround:false})**
 Map an array of primitives (number/string)
 ```js
 mapPrimitive([1,2,3]); // {1: 1, 2: 2, 3: 3}
@@ -128,6 +128,62 @@ mapPrimitive(['hello', 'hello', 'foo', 'bar']); // {hello: 'hello', foo: 'foo',
 mapPrimitive(['hello', ' hello', 'foo', '  foo'], {valtrim: true}); // {hello: 'hello', foo: 'foo'}
 ```
 
+- **groupBy(val:Record[], handler:Function|string)**
+Return a grouped object from an array. This function **will automatically filter out any non/empty objects**.
+
+Example usage when using a **function** as the handler
+```typescript
+/* The output of the function will be what the key is on the map  */
+const group = groupBy([
+    {tally: 20, name: 'Peter'},
+    {tally: 40, name: 'Jake'},
+    {tally: 5, name: 'Bob'},
+], el => el.tally > 15);
+
+/* Expected output: */
+{
+    false: [{tally: 5, name: 'Bob'}],
+    true: [{tally: 20, name: 'Peter'}, {tally: 40, name: 'Jake'}],
+}
+
+/* Can also work with a property return  */
+const group = groupBy([
+    {role: 'user', name: 'Peter'},
+    {role: 'user', name: 'Jake'},
+    {role: 'guest', name: 'Bob'},
+    {name: 'Alice'},
+], el => el.role || 'other');
+
+/* Expected output: */
+{
+    user: [{role: 'user', name: 'Peter'}, {role: 'user', name: 'Jake'}],
+    guest: [{role: 'guest', name: 'Bob'}],
+    other: [{name: 'Alice'}],
+}
+```
+**Take note**: If the function returns an undefined or empty string the object will be added to a fallback group called '_'
+
+
+Example usage when using a **string** as the handler to denote a grouping by a certain property name
+```typescript
+const group = groupBy([
+    {role: 'user', name: 'Peter'},
+    {role: 'user', name: 'Jake'},
+    {role: 'guest', name: 'Bob'},
+    {name: 'Alice'},
+], 'role');
+
+/* Expected output: */
+{
+    user: [{role: 'user', name: 'Peter'}, {role: 'user', name: 'Jake'}],
+    guest: [{role: 'guest', name: 'Bob'}],
+    _: [{name: 'Alice'}],
+}
+```
+
+**Take note**: any object without the key will be added to a fallback group called '_'
+
+
 - **dedupe(val:Array)**
 Remove all duplicates from an array, behind the scenes it uses the fnv 1A hash algorithm to performantly do comparisons.
 ```js

package/array/groupBy.d.ts

@@ -0,0 +1,3 @@
+type Handler<T> = (val: T) => string | number | boolean;
+declare function groupBy<T extends Record<string, any>>(arr: T[], handler: Handler<T> | string): Record<string, T[]>;
+export { groupBy, groupBy as default };

package/array/groupBy.js

@@ -0,0 +1,34 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.groupBy = void 0;
+const isNotEmpty_1 = require("../object/isNotEmpty");
+const FALLBACK = '_';
+const defaultHandler = () => FALLBACK;
+function groupBy(arr, handler) {
+    if (!Array.isArray(arr))
+        return {};
+    const acc = {};
+    const n_handler = typeof handler === 'function'
+        ? handler
+        : typeof handler === 'string' && handler.length
+            ? ((el) => el[handler] ?? FALLBACK)
+            : defaultHandler;
+    let key;
+    const set = new Set();
+    for (const el of arr) {
+        if (!(0, isNotEmpty_1.isNotEmptyObject)(el))
+            continue;
+        key = n_handler(el);
+        if (key === undefined || (typeof key === 'string' && !key.length))
+            key = FALLBACK;
+        if (set.has(key)) {
+            acc[key].push(el);
+            continue;
+        }
+        acc[key] = [el];
+        set.add(key);
+    }
+    return acc;
+}
+exports.groupBy = groupBy;
+exports.default = groupBy;

package/array/index.d.ts

@@ -5,6 +5,7 @@ import { join } from './join';
 import { mapFn } from './mapFn';
 import { mapKey } from './mapKey';
 import { mapPrimitive } from './mapPrimitive';
+import { groupBy } from './groupBy';
 import { shuffle } from './shuffle';
 import { sort } from './sort';
-export { dedupe, isArray, isArray as is, isNotEmptyArray, isNotEmptyArray as isNotEmpty, isNotEmptyArray as isNeArray, isNotEmptyArray as isNe, join, mapFn, mapKey, mapPrimitive, shuffle, sort };
+export { dedupe, isArray, isArray as is, isNotEmptyArray, isNotEmptyArray as isNotEmpty, isNotEmptyArray as isNeArray, isNotEmptyArray as isNe, join, mapFn, mapKey, mapPrimitive, groupBy, shuffle, sort };

package/array/index.js

@@ -1,6 +1,6 @@
 'use strict';
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sort = exports.shuffle = exports.mapPrimitive = exports.mapKey = exports.mapFn = exports.join = exports.isNe = exports.isNeArray = exports.isNotEmpty = exports.isNotEmptyArray = exports.is = exports.isArray = exports.dedupe = void 0;
+exports.sort = exports.shuffle = exports.groupBy = exports.mapPrimitive = exports.mapKey = exports.mapFn = exports.join = exports.isNe = exports.isNeArray = exports.isNotEmpty = exports.isNotEmptyArray = exports.is = exports.isArray = exports.dedupe = void 0;
 const dedupe_1 = require("./dedupe");
 Object.defineProperty(exports, "dedupe", { enumerable: true, get: function () { return dedupe_1.dedupe; } });
 const is_1 = require("./is");
@@ -19,6 +19,8 @@ const mapKey_1 = require("./mapKey");
 Object.defineProperty(exports, "mapKey", { enumerable: true, get: function () { return mapKey_1.mapKey; } });
 const mapPrimitive_1 = require("./mapPrimitive");
 Object.defineProperty(exports, "mapPrimitive", { enumerable: true, get: function () { return mapPrimitive_1.mapPrimitive; } });
+const groupBy_1 = require("./groupBy");
+Object.defineProperty(exports, "groupBy", { enumerable: true, get: function () { return groupBy_1.groupBy; } });
 const shuffle_1 = require("./shuffle");
 Object.defineProperty(exports, "shuffle", { enumerable: true, get: function () { return shuffle_1.shuffle; } });
 const sort_1 = require("./sort");

package/index.d.ts

@@ -61,16 +61,21 @@ declare module "array/mapPrimitive" {
     function mapPrimitive(arr: unknown[], opts?: mapOptions): mapReturn;
     export { mapPrimitive, mapPrimitive as default };
 }
-declare module "array/shuffle" {
-    function shuffle(arr: unknown[]): void;
-    export { shuffle, shuffle as default };
-}
 declare module "object/isNotEmpty" {
     function isNotEmptyObject(val: unknown): val is {
         [key: string]: any;
     };
     export { isNotEmptyObject, isNotEmptyObject as default };
 }
+declare module "array/groupBy" {
+    type Handler<T> = (val: T) => string | number | boolean;
+    function groupBy<T extends Record<string, any>>(arr: T[], handler: Handler<T> | string): Record<string, T[]>;
+    export { groupBy, groupBy as default };
+}
+declare module "array/shuffle" {
+    function shuffle(arr: unknown[]): void;
+    export { shuffle, shuffle as default };
+}
 declare module "array/sort" {
     interface sortOptions {
         filter_fn?: (el: any) => boolean;
@@ -92,9 +97,10 @@ declare module "array/index" {
     import { mapFn } from "array/mapFn";
     import { mapKey } from "array/mapKey";
     import { mapPrimitive } from "array/mapPrimitive";
+    import { groupBy } from "array/groupBy";
     import { shuffle } from "array/shuffle";
     import { sort } from "array/sort";
-    export { dedupe, isArray, isArray as is, isNotEmptyArray, isNotEmptyArray as isNotEmpty, isNotEmptyArray as isNeArray, isNotEmptyArray as isNe, join, mapFn, mapKey, mapPrimitive, shuffle, sort };
+    export { dedupe, isArray, isArray as is, isNotEmptyArray, isNotEmptyArray as isNotEmpty, isNotEmptyArray as isNeArray, isNotEmptyArray as isNe, join, mapFn, mapKey, mapPrimitive, groupBy, shuffle, sort };
 }
 declare module "boolean/is" {
     function isBoolean(val: unknown): val is boolean;

package/object/isNotEmpty.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = exports.isNotEmptyObject = void 0;
 function isNotEmptyObject(val) {
-    return Object.prototype.toString.call(val) === '[object Object]' && Object.keys(val).length > 0;
+    return Object.prototype.toString.call(val) === '[object Object]' && Object.keys(val).length !== 0;
 }
 exports.isNotEmptyObject = isNotEmptyObject;
 exports.default = isNotEmptyObject;

package/package.json

@@ -1 +1 @@
-{ "name": "@valkyriestudios/utils", "version": "12.5.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" }
+{ "name": "@valkyriestudios/utils", "version": "12.6.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" }