@silvermine/toolbox 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [our coding standards][commit-messages] for commit guidelines.
 
+## [0.6.0](https://github.com/silvermine/toolbox/compare/v0.5.1...v0.6.0) (2025-11-12)
+
+
+### Features
+
+* add groupBy util ([e828ca8](https://github.com/silvermine/toolbox/commit/e828ca8f54e18b7513034cee12ec5eb4e5ed2159))
+
+
+### [0.5.1](https://github.com/silvermine/toolbox/compare/v0.5.0...v0.5.1) (2025-11-08)
+
+
+### Bug Fixes
+
+* ensure hasDefined is called on an object ([e532ebf](https://github.com/silvermine/toolbox/commit/e532ebf571481d38a0a6d22890e08e18eba3f807))
+
+
 ## [0.5.0](https://github.com/silvermine/toolbox/compare/v0.4.0...v0.5.0) (2025-10-24)
 
 

package/dist/commonjs/index.js

@@ -36,6 +36,7 @@ tslib_1.__exportStar(require("./utils/pick"), exports);
 tslib_1.__exportStar(require("./utils/pluck"), exports);
 tslib_1.__exportStar(require("./utils/delay"), exports);
 tslib_1.__exportStar(require("./utils/get"), exports);
+tslib_1.__exportStar(require("./utils/group-by"), exports);
 tslib_1.__exportStar(require("./utils/escape-html"), exports);
 tslib_1.__exportStar(require("./utils/make-template"), exports);
 tslib_1.__exportStar(require("./utils/uniq"), exports);

package/dist/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,uEAA6C;AAC7C,uDAA6B;AAC7B,2DAAiC;AACjC,gEAAsC;AACtC,iEAAuC;AACvC,kEAAwC;AACxC,8DAAoC;AACpC,0EAAgD;AAChD,4DAAkC;AAClC,mEAAyC;AACzC,2DAAiC;AAEjC,8DAAoC;AACpC,+DAAqC;AACrC,2DAAiC;AACjC,sEAA4C;AAC5C,6DAAmC;AACnC,2DAAiC;AACjC,gEAAsC;AACtC,6EAAmD;AACnD,4DAAkC;AAClC,4DAAkC;AAClC,6DAAmC;AACnC,kEAAwC;AACxC,yDAA+B;AAC/B,4DAAkC;AAClC,+DAAqC;AACrC,0DAAgC;AAChC,2EAAiD;AAEjD,wDAA8B;AAC9B,0DAAgC;AAChC,0DAAgC;AAChC,uDAA6B;AAC7B,wDAA8B;AAC9B,wDAA8B;AAC9B,sDAA4B;AAC5B,8DAAoC;AACpC,gEAAsC;AACtC,uDAA6B;AAC7B,wDAA8B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,uEAA6C;AAC7C,uDAA6B;AAC7B,2DAAiC;AACjC,gEAAsC;AACtC,iEAAuC;AACvC,kEAAwC;AACxC,8DAAoC;AACpC,0EAAgD;AAChD,4DAAkC;AAClC,mEAAyC;AACzC,2DAAiC;AAEjC,8DAAoC;AACpC,+DAAqC;AACrC,2DAAiC;AACjC,sEAA4C;AAC5C,6DAAmC;AACnC,2DAAiC;AACjC,gEAAsC;AACtC,6EAAmD;AACnD,4DAAkC;AAClC,4DAAkC;AAClC,6DAAmC;AACnC,kEAAwC;AACxC,yDAA+B;AAC/B,4DAAkC;AAClC,+DAAqC;AACrC,0DAAgC;AAChC,2EAAiD;AAEjD,wDAA8B;AAC9B,0DAAgC;AAChC,0DAAgC;AAChC,uDAA6B;AAC7B,wDAA8B;AAC9B,wDAA8B;AAC9B,sDAA4B;AAC5B,2DAAiC;AACjC,8DAAoC;AACpC,gEAAsC;AACtC,uDAA6B;AAC7B,wDAA8B"}

package/dist/commonjs/utils/group-by.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupBy = void 0;
+const has_defined_1 = require("./has-defined");
+const is_string_1 = require("./is-string");
+/**
+ * Given an array of items and a function that returns a key, groups the items by the key.
+ * If the returned key is `undefined`, the item is not included in the result. If a string
+ * is passed as the second argument, the item is grouped by the values of that property.
+ */
+function groupBy(items, fn) {
+    const keyFn = typeof fn === 'function' ? fn : (item) => {
+        const key = item[fn];
+        return is_string_1.isString(key) ? key : undefined;
+    };
+    return items.reduce((memo, item) => {
+        const key = keyFn(item);
+        if (key === undefined) {
+            return memo;
+        }
+        if (has_defined_1.hasDefined(memo, key)) {
+            memo[key].push(item);
+        }
+        else {
+            memo[key] = [item];
+        }
+        return memo;
+    }, {});
+}
+exports.groupBy = groupBy;
+//# sourceMappingURL=group-by.js.map

package/dist/commonjs/utils/group-by.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-by.js","sourceRoot":"","sources":["../../../src/utils/group-by.ts"],"names":[],"mappings":";;;AACA,+CAA2C;AAC3C,2CAAuC;AAEvC;;;;GAIG;AACH,SAAgB,OAAO,CAAsB,KAAU,EAAE,EAAgE;IACtH,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAO,EAAE,EAAE;QACvD,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;QAErB,OAAO,oBAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1C,CAAC,CAAC;IAEF,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE;QAChC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QAExB,IAAI,GAAG,KAAK,SAAS,EAAE;YACpB,OAAO,IAAI,CAAC;SACd;QAED,IAAI,wBAAU,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE;YACxB,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SACvB;aAAM;YACJ,IAAI,CAAC,GAAG,CAAC,GAAG,CAAE,IAAI,CAAE,CAAC;SACvB;QAED,OAAO,IAAI,CAAC;IACf,CAAC,EAAE,EAAqC,CAAC,CAAC;AAC7C,CAAC;AAtBD,0BAsBC"}

package/dist/commonjs/utils/has-defined.js.map

@@ -1 +1 @@
-{"version":3,"file":"has-defined.js","sourceRoot":"","sources":["../../../src/utils/has-defined.ts"],"names":[],"mappings":";;;AAAA,iDAA6C;AAI7C;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,UAAU,CAAsC,CAAI,EAAE,QAAW;IAC9E,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,0BAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AACzF,CAAC;AAFD,gCAEC"}
+{"version":3,"file":"has-defined.js","sourceRoot":"","sources":["../../../src/utils/has-defined.ts"],"names":[],"mappings":";;;AAAA,iDAA6C;AAI7C;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,UAAU,CAAqD,CAAI,EAAE,QAAW;IAC7F,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,0BAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AACzF,CAAC;AAFD,gCAEC"}

package/dist/esm/index.js

@@ -33,6 +33,7 @@ export * from './utils/pick';
 export * from './utils/pluck';
 export * from './utils/delay';
 export * from './utils/get';
+export * from './utils/group-by';
 export * from './utils/escape-html';
 export * from './utils/make-template';
 export * from './utils/uniq';

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AAEjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kCAAkC,CAAC;AAEjD,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AAEjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kCAAkC,CAAC;AAEjD,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC"}

package/dist/esm/utils/group-by.js

@@ -0,0 +1,27 @@
+import { hasDefined } from './has-defined';
+import { isString } from './is-string';
+/**
+ * Given an array of items and a function that returns a key, groups the items by the key.
+ * If the returned key is `undefined`, the item is not included in the result. If a string
+ * is passed as the second argument, the item is grouped by the values of that property.
+ */
+export function groupBy(items, fn) {
+    const keyFn = typeof fn === 'function' ? fn : (item) => {
+        const key = item[fn];
+        return isString(key) ? key : undefined;
+    };
+    return items.reduce((memo, item) => {
+        const key = keyFn(item);
+        if (key === undefined) {
+            return memo;
+        }
+        if (hasDefined(memo, key)) {
+            memo[key].push(item);
+        }
+        else {
+            memo[key] = [item];
+        }
+        return memo;
+    }, {});
+}
+//# sourceMappingURL=group-by.js.map

package/dist/esm/utils/group-by.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-by.js","sourceRoot":"","sources":["../../../src/utils/group-by.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAsB,KAAU,EAAE,EAAgE;IACtH,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAO,EAAE,EAAE;QACvD,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;QAErB,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1C,CAAC,CAAC;IAEF,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE;QAChC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QAExB,IAAI,GAAG,KAAK,SAAS,EAAE;YACpB,OAAO,IAAI,CAAC;SACd;QAED,IAAI,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE;YACxB,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SACvB;aAAM;YACJ,IAAI,CAAC,GAAG,CAAC,GAAG,CAAE,IAAI,CAAE,CAAC;SACvB;QAED,OAAO,IAAI,CAAC;IACf,CAAC,EAAE,EAAqC,CAAC,CAAC;AAC7C,CAAC"}

package/dist/esm/utils/has-defined.js.map

@@ -1 +1 @@
-{"version":3,"file":"has-defined.js","sourceRoot":"","sources":["../../../src/utils/has-defined.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAI7C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,UAAU,CAAsC,CAAI,EAAE,QAAW;IAC9E,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AACzF,CAAC"}
+{"version":3,"file":"has-defined.js","sourceRoot":"","sources":["../../../src/utils/has-defined.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAI7C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,UAAU,CAAqD,CAAI,EAAE,QAAW;IAC7F,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AACzF,CAAC"}

package/dist/types/index.d.ts

@@ -33,6 +33,7 @@ export * from './utils/pick';
 export * from './utils/pluck';
 export * from './utils/delay';
 export * from './utils/get';
+export * from './utils/group-by';
 export * from './utils/escape-html';
 export * from './utils/make-template';
 export * from './utils/uniq';

package/dist/types/utils/group-by.d.ts

@@ -0,0 +1,7 @@
+import { PropsWithType } from '../types/PropsWithType';
+/**
+ * Given an array of items and a function that returns a key, groups the items by the key.
+ * If the returned key is `undefined`, the item is not included in the result. If a string
+ * is passed as the second argument, the item is grouped by the values of that property.
+ */
+export declare function groupBy<T, U extends string>(items: T[], fn: ((item: T) => string | undefined) | PropsWithType<T, string>): Record<U, T[] | undefined>;

package/dist/types/utils/has-defined.d.ts

@@ -17,6 +17,6 @@ import { UnionKeys } from '../types/UnionKeys';
  * @param propName the name of the optional or possibly-undefined property that you want
  * to be required
  */
-export declare function hasDefined<T, U extends keyof T | UnionKeys<T>>(o: T, propName: U): o is RequireDefined<Extract<T, {
+export declare function hasDefined<T extends object, U extends keyof T | UnionKeys<T>>(o: T, propName: U): o is RequireDefined<Extract<T, {
     [key in U]?: unknown;
 }>, U>;

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "@silvermine/toolbox",
-   "version": "0.5.0",
+   "version": "0.6.0",
    "description": "A library of common TypeScript types, custom type guards, and utility functions.",
    "main": "./dist/commonjs/index",
    "types": "./dist/types/index.d.ts",

package/src/index.ts

@@ -35,6 +35,7 @@ export * from './utils/pick';
 export * from './utils/pluck';
 export * from './utils/delay';
 export * from './utils/get';
+export * from './utils/group-by';
 export * from './utils/escape-html';
 export * from './utils/make-template';
 export * from './utils/uniq';

package/src/utils/group-by.ts

@@ -0,0 +1,32 @@
+import { PropsWithType } from '../types/PropsWithType';
+import { hasDefined } from './has-defined';
+import { isString } from './is-string';
+
+/**
+ * Given an array of items and a function that returns a key, groups the items by the key.
+ * If the returned key is `undefined`, the item is not included in the result. If a string
+ * is passed as the second argument, the item is grouped by the values of that property.
+ */
+export function groupBy<T, U extends string>(items: T[], fn: ((item: T) => string | undefined) | PropsWithType<T, string>): Record<U, T[] | undefined> {
+   const keyFn = typeof fn === 'function' ? fn : (item: T) => {
+      const key = item[fn];
+
+      return isString(key) ? key : undefined;
+   };
+
+   return items.reduce((memo, item) => {
+      const key = keyFn(item);
+
+      if (key === undefined) {
+         return memo;
+      }
+
+      if (hasDefined(memo, key)) {
+         memo[key].push(item);
+      } else {
+         memo[key] = [ item ];
+      }
+
+      return memo;
+   }, {} as Record<string, T[] | undefined>);
+}

package/src/utils/has-defined.ts

@@ -19,6 +19,6 @@ import { UnionKeys } from '../types/UnionKeys';
  * @param propName the name of the optional or possibly-undefined property that you want
  * to be required
  */
-export function hasDefined<T, U extends keyof T | UnionKeys<T>>(o: T, propName: U): o is RequireDefined<Extract<T, { [key in U]?: unknown }>, U> {
+export function hasDefined<T extends object, U extends keyof T | UnionKeys<T>>(o: T, propName: U): o is RequireDefined<Extract<T, { [key in U]?: unknown }>, U> {
    return Object.prototype.hasOwnProperty.call(o, propName) && !isUndefined(o[propName]);
 }