utilitish 0.0.5 → 0.0.7

package/dist/utils/core.utils.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineStaticIfNotExists = exports.defineIfNotExists = void 0;
+exports.resolveSelector = resolveSelector;
+exports.assertValidSelector = assertValidSelector;
+exports.isNumberOrString = isNumberOrString;
+/**
+ * Defines a **non-enumerable, non-writable, non-configurable** property on a prototype
+ * if it does not already exist, or if the existing property is writable or configurable.
+ *
+ * - Intended for instance prototype methods (e.g., `Array.prototype`, `String.prototype`).
+ * - Does **not** overwrite non-configurable and non-writable properties.
+ * - Ensures immutability and hides the property from enumeration.
+ *
+ * @example
+ * defineIfNotExists(Array.prototype, 'last', function() {
+ *   return this[this.length - 1];
+ * });
+ *
+ * @template T The prototype object type (e.g., `Array.prototype`).
+ * @param {T} prototype The prototype on which to define the method.
+ * @param {string} name The name of the method to define.
+ * @param {Function} fn The function to assign as the method.
+ *
+ * @remarks
+ * Use this function to safely add prototype methods without overwriting stable or built-in ones.
+ */
+const defineIfNotExists = (prototype, name, fn) => {
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+    if (!descriptor || descriptor.writable || descriptor.configurable) {
+        Object.defineProperty(prototype, name, {
+            value: fn,
+            enumerable: false,
+            configurable: false,
+            writable: false,
+        });
+    }
+};
+exports.defineIfNotExists = defineIfNotExists;
+/**
+ * Defines a **static** property on a constructor if it does not already exist,
+ * or if the existing property is writable or configurable.
+ *
+ * - Only affects static properties on constructors (e.g., `Array`, `Map`).
+ * - The property is created as non-enumerable, immutable, and non-configurable.
+ * - Does **not** overwrite existing properties that are non-configurable and non-writable.
+ *
+ * @example
+ * defineStaticIfNotExists(Array, 'range', function(start: number, end?: number) {
+ *   // implementation
+ * });
+ *
+ * @template T The constructor type (e.g., `typeof Array`).
+ * @param {T} constructor The constructor object on which to define the static method.
+ * @param {string} name The name of the static method to define.
+ * @param {Function} fn The function to assign as the static method.
+ *
+ * @remarks
+ * To forcefully replace an existing property, delete it first or use `Object.defineProperty` directly.
+ */
+const defineStaticIfNotExists = (constructor, name, fn) => {
+    const descriptor = Object.getOwnPropertyDescriptor(constructor, name);
+    if (!descriptor || descriptor.writable || descriptor.configurable) {
+        Object.defineProperty(constructor, name, {
+            value: fn,
+            enumerable: false,
+            configurable: false,
+            writable: false,
+        });
+    }
+};
+exports.defineStaticIfNotExists = defineStaticIfNotExists;
+/**
+ * Resolves a selector parameter into a function that extracts a value from an item.
+ *
+ * The selector can be:
+ * - a key string of the object (returns the value at that key),
+ * - a function transforming the item to the desired value,
+ * - or undefined, in which case a fallback function must be provided.
+ *
+ * @example
+ * const sel1 = resolveSelector<{name: string}, string>('name');
+ * sel1({name: 'Alice'}); // 'Alice'
+ *
+ * const sel2 = resolveSelector<{value: number}, number>(item => item.value * 2);
+ * sel2({value: 5}); // 10
+ *
+ * const sel3 = resolveSelector(undefined, (item) => item.toString());
+ * sel3(42); // '42'
+ *
+ * @template T The type of the input items.
+ * @template R The type of the selected value.
+ * @param {keyof T | ((item: T) => R) | undefined} selector The selector key or function.
+ * @param {(item: T, index?: number) => R} [fallback] A fallback function if no selector is provided.
+ * @param {string} [name='selector'] Name used in error messages.
+ * @returns {(item: T, index?: number) => R} The resolved selector function.
+ *
+ * @throws {TypeError} If the selector is not a function or string key.
+ * @throws {TypeError} If no selector is provided and no fallback is given.
+ */
+function resolveSelector(selector, fallback, name = 'selector') {
+    assertValidSelector(selector);
+    if (typeof selector === 'function') {
+        return selector;
+    }
+    if (typeof selector === 'string') {
+        return (item) => item[selector];
+    }
+    if (selector) {
+        throw new TypeError(`${name} must be a function or a string key`);
+    }
+    if (fallback) {
+        if (typeof fallback === 'function') {
+            return fallback;
+        }
+        throw new TypeError(`fallback must be a function`);
+    }
+    throw new TypeError(`fallback must be given if no selector`);
+}
+/**
+ * Asserts that a selector parameter is valid, i.e., a function or a string.
+ *
+ * @template T The type of the input items.
+ * @template R The type of the selected value.
+ * @param {any} selector The selector to validate.
+ * @param {string} [name='selector'] The name to use in error messages.
+ *
+ * @throws {TypeError} If the selector is neither a function nor a string.
+ *
+ * @remarks
+ * Used internally by `resolveSelector` to provide clearer type safety and errors.
+ */
+function assertValidSelector(selector, name = 'selector') {
+    const isValid = typeof selector === 'function' || typeof selector === 'string';
+    if (selector !== undefined && !isValid) {
+        throw new TypeError(`${name} must be a function or a string key`);
+    }
+}
+/**
+ * Type guard to check if a value is a string or number.
+ *
+ * @example
+ * isNumberOrString('hello'); // true
+ * isNumberOrString(42);      // true
+ * isNumberOrString(true);    // false
+ *
+ * @param {unknown} value The value to test.
+ * @returns {value is string | number} True if the value is a string or number, else false.
+ */
+function isNumberOrString(value) {
+    return typeof value === 'string' || typeof value === 'number';
+}

package/dist/utils/logic.utils.d.ts

@@ -0,0 +1,3 @@
+import { Selector } from './core.utils';
+export declare function mapToObject<K extends PropertyKey, V>(map: Map<K, V>): Record<K, V>;
+export declare function sortBy<T>(arr: T[], direction: 'asc' | 'desc', selector?: Selector<T, number | string>): T[];

package/dist/utils/logic.utils.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapToObject = mapToObject;
+exports.sortBy = sortBy;
+const core_utils_1 = require("./core.utils");
+function mapToObject(map) {
+    const obj = {};
+    for (const [key, value] of map) {
+        // Validate that key is not null or undefined
+        if (key === null || key === undefined) {
+            throw new TypeError(`Invalid key: key cannot be null or undefined. Key received: ${String(key)}`);
+        }
+        const keyType = typeof key;
+        // Only allow string, number, or symbol
+        if (keyType !== 'string' && keyType !== 'number' && keyType !== 'symbol') {
+            throw new TypeError(`Invalid key type: keys must be string, number, or symbol, received ${keyType}. Key value: ${String(key)}`);
+        }
+        obj[key] = value;
+    }
+    return obj;
+}
+function sortBy(arr, direction, selector) {
+    if (arr.length === 0)
+        return arr.slice();
+    const getValue = (0, core_utils_1.resolveSelector)(selector, (item) => item);
+    if (!selector && !arr.every((item) => (0, core_utils_1.isNumberOrString)(item))) {
+        throw new TypeError('Array elements must be number or string if no selector is provided');
+    }
+    return arr.slice().sort((a, b) => {
+        const valA = getValue(a);
+        const valB = getValue(b);
+        if (!(0, core_utils_1.isNumberOrString)(valA) || !(0, core_utils_1.isNumberOrString)(valB)) {
+            throw new TypeError('Selector must return number or string');
+        }
+        if (valA > valB)
+            return direction === 'asc' ? 1 : -1;
+        if (valA < valB)
+            return direction === 'asc' ? -1 : 1;
+        return 0;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "utilitish",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/utils.d.ts

@@ -1,28 +0,0 @@
-export declare const defineIfNotExists: <T extends object>(prototype: T, name: string, fn: Function) => void;
-/**
- * Defines a **static** property on a constructor if it does not already exist
- * (or if the existing property is writable **or** configurable).
- *
- * - Does **not** affect instance prototypes (use `defineIfNotExists` for `Foo.prototype`).
- * - The property is created with: { enumerable: false, configurable: false, writable: false }
- *   making it non-enumerable and immutable after definition.
- * - If an existing property is non-configurable AND non-writable, it will **not** be replaced.
- *
- * @template T
- * @param {T} constructor The constructor object (e.g., `Array`, `String`, `Map`, ...)
- * @param {string} name The name of the static method to define (e.g., `'create'`, `'range'`)
- * @param {Function} fn The function to attach as a static property
- *
- * @example
- * // Define Array.range if possible
- * defineStaticIfNotExists(Array, 'range', function(start: number, end?: number) { ... });
- *
- * @remarks
- * - To force replacement, delete the property first or use Object.defineProperty directly.
- * - This function is meant to standardize the addition of static methods in utilitish.
- */
-export declare const defineStaticIfNotExists: <T extends object>(constructor: T, name: string, fn: Function) => void;
-export declare function resolveSelector<T, R>(selector?: keyof T | ((item: T) => R), fallback?: (item: T, index?: number) => R, name?: string): (item: T, index?: number) => R;
-export declare function assertValidSelector<T, R>(selector: any, name?: string): asserts selector is Selector<T, R>;
-export declare function isNumberOrString(value: unknown): value is string | number;
-export type Selector<T, K> = keyof T | ((item: T) => K);

package/dist/utils.js

@@ -1,80 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineStaticIfNotExists = exports.defineIfNotExists = void 0;
-exports.resolveSelector = resolveSelector;
-exports.assertValidSelector = assertValidSelector;
-exports.isNumberOrString = isNumberOrString;
-const defineIfNotExists = (prototype, name, fn) => {
-    const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
-    if (!descriptor || descriptor.writable || descriptor.configurable) {
-        Object.defineProperty(prototype, name, {
-            value: fn,
-            enumerable: false,
-            configurable: false,
-            writable: false,
-        });
-    }
-};
-exports.defineIfNotExists = defineIfNotExists;
-/**
- * Defines a **static** property on a constructor if it does not already exist
- * (or if the existing property is writable **or** configurable).
- *
- * - Does **not** affect instance prototypes (use `defineIfNotExists` for `Foo.prototype`).
- * - The property is created with: { enumerable: false, configurable: false, writable: false }
- *   making it non-enumerable and immutable after definition.
- * - If an existing property is non-configurable AND non-writable, it will **not** be replaced.
- *
- * @template T
- * @param {T} constructor The constructor object (e.g., `Array`, `String`, `Map`, ...)
- * @param {string} name The name of the static method to define (e.g., `'create'`, `'range'`)
- * @param {Function} fn The function to attach as a static property
- *
- * @example
- * // Define Array.range if possible
- * defineStaticIfNotExists(Array, 'range', function(start: number, end?: number) { ... });
- *
- * @remarks
- * - To force replacement, delete the property first or use Object.defineProperty directly.
- * - This function is meant to standardize the addition of static methods in utilitish.
- */
-const defineStaticIfNotExists = (constructor, name, fn) => {
-    const descriptor = Object.getOwnPropertyDescriptor(constructor, name);
-    if (!descriptor || descriptor.writable || descriptor.configurable) {
-        Object.defineProperty(constructor, name, {
-            value: fn,
-            enumerable: false,
-            configurable: false,
-            writable: false,
-        });
-    }
-};
-exports.defineStaticIfNotExists = defineStaticIfNotExists;
-function resolveSelector(selector, fallback, name = 'selector') {
-    assertValidSelector(selector);
-    if (typeof selector === 'function') {
-        return selector;
-    }
-    if (typeof selector === 'string') {
-        return (item) => item[selector];
-    }
-    if (selector) {
-        throw new TypeError(`${name} must be a function or a string key`);
-    }
-    if (fallback) {
-        if (typeof fallback === 'function') {
-            return fallback;
-        }
-        throw new TypeError(`fallback must be a function`);
-    }
-    throw new TypeError(`fallback must be given if no selector`);
-}
-function assertValidSelector(selector, name = 'selector') {
-    const isValid = typeof selector === 'function' || typeof selector === 'string';
-    if (selector !== undefined && !isValid) {
-        throw new TypeError(`${name} must be a function or a string key`);
-    }
-}
-function isNumberOrString(value) {
-    return typeof value === 'string' || typeof value === 'number';
-}