utilitish 0.0.16 → 0.0.19

package/dist/array/array-prototype.d.ts

@@ -409,5 +409,49 @@ declare global {
          * - Throws on the first non-string item encountered in the array.
          */
         slugifyIncludes(value: string): boolean;
+        /**
+         * Groups array elements into multiple groups based on an array of keys returned by the selector.
+         * Unlike `groupBy`, a single element can appear in multiple groups.
+         *
+         * @this {T[]} The array to group.
+         * @param {(item: T) => K[]} selector - A function returning an array of keys for each element.
+         * @returns {Map<K, T[]>} A Map where each key maps to an array of matching elements.
+         * @throws {TypeError} If selector is not a function or a string key.
+         *
+         * @example
+         * const posts = [
+         *   { title: 'A', tags: ['js', 'ts'] },
+         *   { title: 'B', tags: ['ts', 'node'] },
+         * ];
+         * posts.groupByMany(post => post.tags);
+         * // Map { 'js' => [{ title: 'A', ... }], 'ts' => [{ title: 'A', ... }, { title: 'B', ... }], 'node' => [{ title: 'B', ... }] }
+         *
+         * @remarks
+         * - Elements with an empty key array are ignored.
+         * - Order of elements within each group follows the original array order.
+         */
+        groupByMany<K>(this: T[], selector: Selector<T, K[]>): Map<K, T[]>;
+        /**
+         * Classifies array elements into named groups based on predicate functions.
+         * Each element is tested against all predicates and can appear in multiple groups.
+         *
+         * @this {T[]} The array to classify.
+         * @param {Record<K, (item: T) => boolean>} predicates - An object mapping group names to predicate functions.
+         * @returns {Map<K, T[]>} A Map where each key maps to elements matching the predicate.
+         * @throws {TypeError} If predicates is not a valid object.
+         *
+         * @example
+         * users.classify({
+         *   adult:   u => u.age >= 18,
+         *   admin:   u => u.roles.includes('ADMIN'),
+         *   premium: u => u.premium,
+         * });
+         *
+         * @remarks
+         * - Elements matching no predicate are ignored.
+         * - Elements can appear in multiple groups.
+         * - The return type infers K as a union of the literal keys of the predicates object.
+         */
+        classify<K extends string>(this: T[], predicates: Record<K, Selector<T, Boolean>>): Map<K, T[]>;
     }
 }

package/dist/array/array-prototype.js

@@ -232,3 +232,36 @@ const logic_utils_1 = require("../utils/logic.utils");
         return item.slugify() === slugified;
     });
 });
+/**
+ * @see Array.prototype.groupByMany
+ */
+(0, core_utils_1.defineIfNotExists)(Array.prototype, 'groupByMany', function (selector) {
+    const getKeys = (0, core_utils_1.resolveSelector)(selector);
+    const result = new Map();
+    for (const item of this) {
+        const keys = getKeys(item);
+        for (const key of keys) {
+            if (!result.has(key))
+                result.set(key, []);
+            result.get(key).push(item);
+        }
+    }
+    return result;
+});
+/**
+ * @see Array.prototype.classify
+ */
+(0, core_utils_1.defineIfNotExists)(Array.prototype, 'classify', function (predicates) {
+    if (typeof predicates !== 'object' || predicates === null)
+        (0, core_utils_1.utilitishError)('Array.prototype.classify', 'predicates must be a non-null object', predicates);
+    const resolvedPredicates = Object.fromEntries(Object.entries(predicates).map(([key, fn]) => [key, (0, core_utils_1.resolveSelector)(fn)]));
+    const entries = Object.entries(resolvedPredicates);
+    const result = new Map(entries.map(([key]) => [key, []]));
+    for (const item of this) {
+        for (const [key, predicate] of entries) {
+            if (!!predicate(item))
+                result.get(key).push(item);
+        }
+    }
+    return result;
+});

package/dist/array/array-prototype.spec.js

@@ -533,4 +533,103 @@ describe('Array.prototype', () => {
             });
         });
     });
+    describe('Array.prototype.groupByMany', () => {
+        describe('with selector function', () => {
+            it('should group elements by multiple keys', () => {
+                const posts = [
+                    { title: 'A', tags: ['js', 'ts'] },
+                    { title: 'B', tags: ['ts', 'node'] },
+                ];
+                const result = posts.groupByMany((p) => p.tags);
+                expect(result.get('js')).toEqual([{ title: 'A', tags: ['js', 'ts'] }]);
+                expect(result.get('ts')).toHaveLength(2);
+                expect(result.get('node')).toEqual([{ title: 'B', tags: ['ts', 'node'] }]);
+            });
+            it('should ignore elements with empty key array', () => {
+                const posts = [
+                    { title: 'A', tags: [] },
+                    { title: 'B', tags: ['ts'] },
+                ];
+                const result = posts.groupByMany((p) => p.tags);
+                expect(result.has('ts')).toBe(true);
+                expect(result.size).toBe(1);
+            });
+            it('should return empty Map for empty array', () => {
+                expect([].groupByMany((x) => x.tags)).toEqual(new Map());
+            });
+        });
+        describe('error handling', () => {
+            it('should throw TypeError when selector is invalid', () => {
+                expect(() => [{ tags: ['a'] }].groupByMany(123)).toThrow(TypeError);
+            });
+        });
+    });
+    describe('Array.prototype.classify', () => {
+        describe('with predicate object', () => {
+            it('should classify elements into named groups', () => {
+                const users = [
+                    { name: 'Alice', age: 25, admin: true, premium: false },
+                    { name: 'Bob', age: 16, admin: false, premium: true },
+                    { name: 'Carol', age: 30, admin: true, premium: true },
+                ];
+                const result = users.classify({
+                    adult: (u) => u.age >= 18,
+                    admin: (u) => u.admin,
+                    premium: (u) => u.premium,
+                });
+                expect(result.get('adult')).toHaveLength(2);
+                expect(result.get('admin')).toHaveLength(2);
+                expect(result.get('premium')).toHaveLength(2);
+            });
+            it('should allow an element to appear in multiple groups', () => {
+                const users = [{ name: 'Alice', age: 25, admin: true, premium: true }];
+                const result = users.classify({
+                    adult: (u) => u.age >= 18,
+                    admin: (u) => u.admin,
+                });
+                expect(result.get('adult')).toHaveLength(1);
+                expect(result.get('admin')).toHaveLength(1);
+            });
+            it('should ignore elements matching no predicate', () => {
+                const users = [{ name: 'Bob', age: 16, admin: false, premium: false }];
+                const result = users.classify({
+                    adult: (u) => u.age >= 18,
+                    admin: (u) => u.admin,
+                });
+                expect(result.get('adult')).toHaveLength(0);
+                expect(result.get('admin')).toHaveLength(0);
+            });
+            it('should return Map with empty arrays for empty input', () => {
+                const result = [].classify({ adult: (u) => u.age >= 18 });
+                expect(result.get('adult')).toEqual([]);
+            });
+            it('should work with key', () => {
+                const users = [
+                    { name: 'Alice', age: 0, admin: false, premium: false },
+                    { name: 'Bob', age: 16, admin: false, premium: false },
+                    { name: 'Chloe', age: 24, admin: true, premium: false },
+                ];
+                const result = users.classify({
+                    admin: 'admin',
+                    age: 'age',
+                });
+                expect(result.get('admin')).toHaveLength(1);
+                expect(result.get('age')).toHaveLength(2);
+            });
+        });
+        describe('error handling', () => {
+            it('should throw Error when key selector is invalid', () => {
+                expect(() => [{ id: 1 }].classify(123)).toThrow(Error);
+            });
+            it('should throw TypeError when predicates is not an object', () => {
+                expect(() => [].classify('invalid')).toThrow(TypeError);
+            });
+            it('should throw TypeError when predicates is null', () => {
+                expect(() => [].classify(null)).toThrow(TypeError);
+            });
+            it('should throw TypeError when a predicate is not a function', () => {
+                expect(() => [{ age: 25 }].classify({ adult: 'not an attribut' })).toThrow(TypeError);
+            });
+        });
+    });
 });

package/dist/string/string-prototype.d.ts

@@ -87,6 +87,40 @@ declare global {
          * - Uses `splitWords()` internally
          */
         snakeCase(): string;
+        /**
+         * Converts this string to sentence case by splitting into words and joining them in lowercase.
+         *
+         * @this {string} The string to convert.
+         * @returns {string} The string with all words lowercased and joined by spaces.
+         *
+         * @example
+         * 'helloWorld'.sentenceCase();    // 'hello world'
+         * 'Hello-World'.sentenceCase();   // 'hello world'
+         * 'hello_world'.sentenceCase();   // 'hello world'
+         * 'HELLO WORLD'.sentenceCase();   // 'hello world'
+         *
+         * @remarks
+         * - Uses `splitWords` internally to handle camelCase, kebab-case, snake_case, and spaces.
+         * - All words are lowercased before joining.
+         */
+        sentenceCase(): string;
+        /**
+         * Converts this string to title case by capitalizing the first letter of each word.
+         *
+         * @this {string} The string to convert.
+         * @returns {string} The string with each word capitalized and joined by spaces.
+         *
+         * @example
+         * 'helloWorld'.titleCase();    // 'Hello World'
+         * 'hello-world'.titleCase();   // 'Hello World'
+         * 'hello_world'.titleCase();   // 'Hello World'
+         * 'HELLO WORLD'.titleCase();   // 'Hello World'
+         *
+         * @remarks
+         * - Uses `splitWords` internally to handle camelCase, kebab-case, snake_case, and spaces.
+         * - Each word is lowercased then capitalized.
+         */
+        titleCase(): string;
         /**
          * Truncates the string to a maximum number of characters, appending '...' if truncated.
          *

package/dist/string/string-prototype.js

@@ -8,7 +8,7 @@ const slugify_config_1 = require("../utils/slugify.config");
 (0, core_utils_1.defineIfNotExists)(String.prototype, 'splitWords', function () {
     return this.replace(/([a-z0-9])([A-Z])/g, '$1 $2') // helloWorld → hello World
         .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2') // HTMLParser → HTML Parser
-        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
         .trim()
         .split(/\s+/)
         .filter(Boolean);
@@ -38,6 +38,22 @@ const slugify_config_1 = require("../utils/slugify.config");
         .map((w) => w.toLowerCase())
         .join('_');
 });
+/**
+ * @see String.prototype.sentenceCase
+ */
+(0, core_utils_1.defineIfNotExists)(String.prototype, 'sentenceCase', function () {
+    return this.splitWords()
+        .map((w) => w.toLowerCase())
+        .join(' ');
+});
+/**
+ * @see String.prototype.titleCase
+ */
+(0, core_utils_1.defineIfNotExists)(String.prototype, 'titleCase', function () {
+    return this.splitWords()
+        .map((w) => w.toLowerCase().capitalize())
+        .join(' ');
+});
 /**
  * @see String.prototype.truncate
  */

package/dist/string/string-prototype.spec.js

@@ -18,6 +18,13 @@ describe('String.prototype', () => {
             expect('hello world'.splitWords()).toEqual(['hello', 'world']);
             expect('HTMLParser'.splitWords()).toEqual(['HTML', 'Parser']);
         });
+        it('should split with accent', () => {
+            expect('attaqueChargé'.splitWords()).toEqual(['attaque', 'Chargé']);
+            expect('attaque-chargé'.splitWords()).toEqual(['attaque', 'chargé']);
+            expect('attaque_chargé'.splitWords()).toEqual(['attaque', 'chargé']);
+            expect('attaque chargé'.splitWords()).toEqual(['attaque', 'chargé']);
+            expect('ATTAQUEChargé'.splitWords()).toEqual(['ATTAQUE', 'Chargé']);
+        });
     });
     describe('camelCase()', () => {
         it('should convert to camelCase', () => {
@@ -40,6 +47,24 @@ describe('String.prototype', () => {
             expect('hello_world_test'.snakeCase()).toBe('hello_world_test');
         });
     });
+    describe('sentenceCase()', () => {
+        it('should convert to sentence case', () => {
+            expect('helloWorld'.sentenceCase()).toBe('hello world');
+            expect('hello-world'.sentenceCase()).toBe('hello world');
+            expect('hello_world'.sentenceCase()).toBe('hello world');
+            expect('HELLO WORLD'.sentenceCase()).toBe('hello world');
+            expect('attaqueChargé'.sentenceCase()).toBe('attaque chargé');
+        });
+    });
+    describe('titleCase()', () => {
+        it('should convert to title case', () => {
+            expect('helloWorld'.titleCase()).toBe('Hello World');
+            expect('hello-world'.titleCase()).toBe('Hello World');
+            expect('hello_world'.titleCase()).toBe('Hello World');
+            expect('HELLO WORLD'.titleCase()).toBe('Hello World');
+            expect('attaqueChargé'.titleCase()).toBe('Attaque Chargé');
+        });
+    });
     describe('truncate()', () => {
         it('should truncate and add ... if needed', () => {
             expect('hello world'.truncate(5)).toBe('hello...');

package/dist/utils/core.utils.js

@@ -104,7 +104,11 @@ function resolveSelector(selector, fallback, name = 'selector') {
         return selector;
     }
     if (typeof selector === 'string') {
-        return (item) => item[selector];
+        return (item) => {
+            if (!(selector in item))
+                throw new TypeError(`selector string must be a key of the item`);
+            return item[selector];
+        };
     }
     if (selector) {
         throw new TypeError(`${name} must be a function or a string key`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "utilitish",
-  "version": "0.0.16",
+  "version": "0.0.19",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/FDonovan12/utilitish.git"
@@ -10,8 +10,15 @@
     "provenance": false
   },
   "description": "",
+  "moduleResolution": "Node16",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
   "files": [
     "dist"
   ],
@@ -19,7 +26,7 @@
     "build": "tsc",
     "test": "jest",
     "docs": "typedoc",
-    "release": "npm test && npm run build && npm version patch && git push --follow-tags && npm publish"
+    "release": "(npm whoami || npm login) && npm test && npm run build && npm version patch && git push --follow-tags && npm publish"
   },
   "keywords": [
     "typescript",