@arnonsang/utils 0.0.2 → 0.0.3

package/README.md

@@ -13,7 +13,19 @@ npm install @arnonsang/utils
 ### Importing Utilities
 
 ```ts
-import { logger, charAt, charAtFrom } from "@arnonsang/utils";
+import { 
+  logger, 
+  charAt, 
+  charAtFrom,
+  capitalize,
+  toCamelCase,
+  unique,
+  chunk,
+  formatDate,
+  dateDiff,
+  clamp,
+  formatBytes
+} from "@arnonsang/utils";
 ```
 
 ### Logger Utility
@@ -27,13 +39,67 @@ logger.debug("Debugging info");
 logger.table([{ name: "Alice" }, { name: "Bob" }], "User Data");
 ```
 
-### Chat Utilities
+### Character Utilities
 
 ```ts
 console.log(charAt(3, "upper")); // "D"
 console.log(charAtFrom("hello", 1)); // "e"
 ```
 
+### String Utilities
+
+```ts
+capitalize("hello world"); // "Hello world"
+toCamelCase("hello world"); // "helloWorld"
+toKebabCase("Hello World"); // "hello-world"
+toSnakeCase("Hello World"); // "hello_world"
+truncate("This is a long string", 10); // "This is..."
+cleanWhitespace("  hello   world  "); // "hello world"
+isValidEmail("test@example.com"); // true
+randomString(8); // "aB3xY9pQ"
+pluralize("item", 5); // "items"
+```
+
+### Array Utilities
+
+```ts
+unique([1, 2, 2, 3, 3, 4]); // [1, 2, 3, 4]
+chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+flatten([[1, 2], [3, 4]]); // [1, 2, 3, 4]
+groupBy([{type: 'a'}, {type: 'b'}, {type: 'a'}], item => item.type);
+shuffle([1, 2, 3, 4, 5]); // [3, 1, 5, 2, 4] (random)
+sample([1, 2, 3, 4, 5]); // 3 (random)
+intersection([1, 2, 3], [2, 3, 4]); // [2, 3]
+sum([1, 2, 3, 4, 5]); // 15
+average([1, 2, 3, 4, 5]); // 3
+```
+
+### Date Utilities
+
+```ts
+formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss');
+dateDiff(date1, date2, 'days'); // 5
+addTime(new Date(), 5, 'days');
+subtractTime(new Date(), 2, 'hours');
+isToday(new Date()); // true
+isPast(someDate); // true/false
+getAge(new Date('1990-01-01')); // 34 (example)
+```
+
+### Number Utilities
+
+```ts
+clamp(15, 0, 10); // 10
+round(3.14159, 2); // 3.14
+randomBetween(1, 10); // 7.234 (random)
+randomInt(1, 10); // 7 (random)
+isEven(4); // true
+percentage(25, 100); // 25
+formatNumber(1234567); // "1,234,567"
+formatBytes(1024); // "1 KB"
+factorial(5); // 120
+```
+
 ## Contributing
 
 Feel free to open an issue or a pull request to contribute new utilities or improve existing ones.

package/dist/index.d.ts

@@ -1,2 +1,6 @@
-export * from "./utils/chat";
+export * from "./utils/char";
+export * from "./utils/string";
+export * from "./utils/array";
+export * from "./utils/date";
+export * from "./utils/number";
 export { default as logger } from "./utils/logger";

package/dist/index.js

@@ -15,6 +15,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.logger = void 0;
-__exportStar(require("./utils/chat"), exports);
+__exportStar(require("./utils/char"), exports);
+__exportStar(require("./utils/string"), exports);
+__exportStar(require("./utils/array"), exports);
+__exportStar(require("./utils/date"), exports);
+__exportStar(require("./utils/number"), exports);
 var logger_1 = require("./utils/logger");
 Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_1.default; } });

package/dist/utils/array.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Removes duplicate values from an array
+ * @param arr - The array to deduplicate
+ * @returns Array with unique values
+ */
+export declare const unique: <T>(arr: T[]) => T[];
+/**
+ * Chunks an array into smaller arrays of specified size
+ * @param arr - The array to chunk
+ * @param size - The size of each chunk
+ * @returns Array of chunks
+ */
+export declare const chunk: <T>(arr: T[], size: number) => T[][];
+/**
+ * Flattens a nested array to a specified depth
+ * @param arr - The array to flatten
+ * @param depth - The depth to flatten (default: 1)
+ * @returns Flattened array
+ */
+export declare const flatten: <T>(arr: (T | T[])[], depth?: number) => T[];
+/**
+ * Groups array elements by a key function
+ * @param arr - The array to group
+ * @param keyFn - Function to extract the grouping key
+ * @returns Object with grouped elements
+ */
+export declare const groupBy: <T, K extends string | number | symbol>(arr: T[], keyFn: (item: T) => K) => Record<K, T[]>;
+/**
+ * Shuffles an array randomly
+ * @param arr - The array to shuffle
+ * @returns New shuffled array
+ */
+export declare const shuffle: <T>(arr: T[]) => T[];
+/**
+ * Gets a random element from an array
+ * @param arr - The array to pick from
+ * @returns Random element or undefined if array is empty
+ */
+export declare const sample: <T>(arr: T[]) => T | undefined;
+/**
+ * Gets multiple random elements from an array
+ * @param arr - The array to pick from
+ * @param count - Number of elements to pick
+ * @returns Array of random elements
+ */
+export declare const sampleSize: <T>(arr: T[], count: number) => T[];
+/**
+ * Finds the intersection of two arrays
+ * @param arr1 - First array
+ * @param arr2 - Second array
+ * @returns Array of common elements
+ */
+export declare const intersection: <T>(arr1: T[], arr2: T[]) => T[];
+/**
+ * Finds the difference between two arrays (elements in first but not in second)
+ * @param arr1 - First array
+ * @param arr2 - Second array
+ * @returns Array of different elements
+ */
+export declare const difference: <T>(arr1: T[], arr2: T[]) => T[];
+/**
+ * Sums all numbers in an array
+ * @param arr - Array of numbers
+ * @returns Sum of all numbers
+ */
+export declare const sum: (arr: number[]) => number;
+/**
+ * Gets the average of all numbers in an array
+ * @param arr - Array of numbers
+ * @returns Average of all numbers
+ */
+export declare const average: (arr: number[]) => number;
+/**
+ * Finds the minimum value in an array
+ * @param arr - Array of numbers
+ * @returns Minimum value or undefined if array is empty
+ */
+export declare const min: (arr: number[]) => number | undefined;
+/**
+ * Finds the maximum value in an array
+ * @param arr - Array of numbers
+ * @returns Maximum value or undefined if array is empty
+ */
+export declare const max: (arr: number[]) => number | undefined;

package/dist/utils/array.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.max = exports.min = exports.average = exports.sum = exports.difference = exports.intersection = exports.sampleSize = exports.sample = exports.shuffle = exports.groupBy = exports.flatten = exports.chunk = exports.unique = void 0;
+/**
+ * Removes duplicate values from an array
+ * @param arr - The array to deduplicate
+ * @returns Array with unique values
+ */
+const unique = (arr) => {
+    return [...new Set(arr)];
+};
+exports.unique = unique;
+/**
+ * Chunks an array into smaller arrays of specified size
+ * @param arr - The array to chunk
+ * @param size - The size of each chunk
+ * @returns Array of chunks
+ */
+const chunk = (arr, size) => {
+    const chunks = [];
+    for (let i = 0; i < arr.length; i += size) {
+        chunks.push(arr.slice(i, i + size));
+    }
+    return chunks;
+};
+exports.chunk = chunk;
+/**
+ * Flattens a nested array to a specified depth
+ * @param arr - The array to flatten
+ * @param depth - The depth to flatten (default: 1)
+ * @returns Flattened array
+ */
+const flatten = (arr, depth = 1) => {
+    return depth > 0
+        ? arr.reduce((acc, val) => acc.concat(Array.isArray(val) ? (0, exports.flatten)(val, depth - 1) : val), [])
+        : arr.slice();
+};
+exports.flatten = flatten;
+/**
+ * Groups array elements by a key function
+ * @param arr - The array to group
+ * @param keyFn - Function to extract the grouping key
+ * @returns Object with grouped elements
+ */
+const groupBy = (arr, keyFn) => {
+    return arr.reduce((groups, item) => {
+        const key = keyFn(item);
+        (groups[key] = groups[key] || []).push(item);
+        return groups;
+    }, {});
+};
+exports.groupBy = groupBy;
+/**
+ * Shuffles an array randomly
+ * @param arr - The array to shuffle
+ * @returns New shuffled array
+ */
+const shuffle = (arr) => {
+    const shuffled = [...arr];
+    for (let i = shuffled.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    return shuffled;
+};
+exports.shuffle = shuffle;
+/**
+ * Gets a random element from an array
+ * @param arr - The array to pick from
+ * @returns Random element or undefined if array is empty
+ */
+const sample = (arr) => {
+    return arr[Math.floor(Math.random() * arr.length)];
+};
+exports.sample = sample;
+/**
+ * Gets multiple random elements from an array
+ * @param arr - The array to pick from
+ * @param count - Number of elements to pick
+ * @returns Array of random elements
+ */
+const sampleSize = (arr, count) => {
+    const shuffled = (0, exports.shuffle)(arr);
+    return shuffled.slice(0, Math.min(count, arr.length));
+};
+exports.sampleSize = sampleSize;
+/**
+ * Finds the intersection of two arrays
+ * @param arr1 - First array
+ * @param arr2 - Second array
+ * @returns Array of common elements
+ */
+const intersection = (arr1, arr2) => {
+    const set2 = new Set(arr2);
+    return arr1.filter(item => set2.has(item));
+};
+exports.intersection = intersection;
+/**
+ * Finds the difference between two arrays (elements in first but not in second)
+ * @param arr1 - First array
+ * @param arr2 - Second array
+ * @returns Array of different elements
+ */
+const difference = (arr1, arr2) => {
+    const set2 = new Set(arr2);
+    return arr1.filter(item => !set2.has(item));
+};
+exports.difference = difference;
+/**
+ * Sums all numbers in an array
+ * @param arr - Array of numbers
+ * @returns Sum of all numbers
+ */
+const sum = (arr) => {
+    return arr.reduce((total, num) => total + num, 0);
+};
+exports.sum = sum;
+/**
+ * Gets the average of all numbers in an array
+ * @param arr - Array of numbers
+ * @returns Average of all numbers
+ */
+const average = (arr) => {
+    return arr.length > 0 ? (0, exports.sum)(arr) / arr.length : 0;
+};
+exports.average = average;
+/**
+ * Finds the minimum value in an array
+ * @param arr - Array of numbers
+ * @returns Minimum value or undefined if array is empty
+ */
+const min = (arr) => {
+    return arr.length > 0 ? Math.min(...arr) : undefined;
+};
+exports.min = min;
+/**
+ * Finds the maximum value in an array
+ * @param arr - Array of numbers
+ * @returns Maximum value or undefined if array is empty
+ */
+const max = (arr) => {
+    return arr.length > 0 ? Math.max(...arr) : undefined;
+};
+exports.max = max;

package/dist/utils/date.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Formats a date to a readable string
+ * @param date - The date to format
+ * @param format - The format pattern (default: 'YYYY-MM-DD')
+ * @returns Formatted date string
+ */
+export declare const formatDate: (date: Date, format?: string) => string;
+/**
+ * Gets the difference between two dates in various units
+ * @param date1 - First date
+ * @param date2 - Second date
+ * @param unit - Unit of measurement ('days', 'hours', 'minutes', 'seconds')
+ * @returns Difference in specified unit
+ */
+export declare const dateDiff: (date1: Date, date2: Date, unit?: "days" | "hours" | "minutes" | "seconds") => number;
+/**
+ * Adds time to a date
+ * @param date - The base date
+ * @param amount - Amount to add
+ * @param unit - Unit of time ('days', 'hours', 'minutes', 'seconds')
+ * @returns New date with added time
+ */
+export declare const addTime: (date: Date, amount: number, unit: "days" | "hours" | "minutes" | "seconds") => Date;
+/**
+ * Subtracts time from a date
+ * @param date - The base date
+ * @param amount - Amount to subtract
+ * @param unit - Unit of time ('days', 'hours', 'minutes', 'seconds')
+ * @returns New date with subtracted time
+ */
+export declare const subtractTime: (date: Date, amount: number, unit: "days" | "hours" | "minutes" | "seconds") => Date;
+/**
+ * Checks if a date is in the past
+ * @param date - The date to check
+ * @returns True if date is in the past
+ */
+export declare const isPast: (date: Date) => boolean;
+/**
+ * Checks if a date is in the future
+ * @param date - The date to check
+ * @returns True if date is in the future
+ */
+export declare const isFuture: (date: Date) => boolean;
+/**
+ * Checks if a date is today
+ * @param date - The date to check
+ * @returns True if date is today
+ */
+export declare const isToday: (date: Date) => boolean;
+/**
+ * Gets the start of day for a date
+ * @param date - The date
+ * @returns Date set to start of day (00:00:00)
+ */
+export declare const startOfDay: (date: Date) => Date;
+/**
+ * Gets the end of day for a date
+ * @param date - The date
+ * @returns Date set to end of day (23:59:59.999)
+ */
+export declare const endOfDay: (date: Date) => Date;
+/**
+ * Gets the age in years from a birth date
+ * @param birthDate - The birth date
+ * @param referenceDate - The reference date (default: now)
+ * @returns Age in years
+ */
+export declare const getAge: (birthDate: Date, referenceDate?: Date) => number;

package/dist/utils/date.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAge = exports.endOfDay = exports.startOfDay = exports.isToday = exports.isFuture = exports.isPast = exports.subtractTime = exports.addTime = exports.dateDiff = exports.formatDate = void 0;
+/**
+ * Formats a date to a readable string
+ * @param date - The date to format
+ * @param format - The format pattern (default: 'YYYY-MM-DD')
+ * @returns Formatted date string
+ */
+const formatDate = (date, format = 'YYYY-MM-DD') => {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    const hours = String(date.getHours()).padStart(2, '0');
+    const minutes = String(date.getMinutes()).padStart(2, '0');
+    const seconds = String(date.getSeconds()).padStart(2, '0');
+    return format
+        .replace('YYYY', String(year))
+        .replace('MM', month)
+        .replace('DD', day)
+        .replace('HH', hours)
+        .replace('mm', minutes)
+        .replace('ss', seconds);
+};
+exports.formatDate = formatDate;
+/**
+ * Gets the difference between two dates in various units
+ * @param date1 - First date
+ * @param date2 - Second date
+ * @param unit - Unit of measurement ('days', 'hours', 'minutes', 'seconds')
+ * @returns Difference in specified unit
+ */
+const dateDiff = (date1, date2, unit = 'days') => {
+    const diff = Math.abs(date1.getTime() - date2.getTime());
+    switch (unit) {
+        case 'seconds':
+            return Math.floor(diff / 1000);
+        case 'minutes':
+            return Math.floor(diff / (1000 * 60));
+        case 'hours':
+            return Math.floor(diff / (1000 * 60 * 60));
+        case 'days':
+            return Math.floor(diff / (1000 * 60 * 60 * 24));
+        default:
+            return diff;
+    }
+};
+exports.dateDiff = dateDiff;
+/**
+ * Adds time to a date
+ * @param date - The base date
+ * @param amount - Amount to add
+ * @param unit - Unit of time ('days', 'hours', 'minutes', 'seconds')
+ * @returns New date with added time
+ */
+const addTime = (date, amount, unit) => {
+    const newDate = new Date(date);
+    switch (unit) {
+        case 'seconds':
+            newDate.setSeconds(newDate.getSeconds() + amount);
+            break;
+        case 'minutes':
+            newDate.setMinutes(newDate.getMinutes() + amount);
+            break;
+        case 'hours':
+            newDate.setHours(newDate.getHours() + amount);
+            break;
+        case 'days':
+            newDate.setDate(newDate.getDate() + amount);
+            break;
+    }
+    return newDate;
+};
+exports.addTime = addTime;
+/**
+ * Subtracts time from a date
+ * @param date - The base date
+ * @param amount - Amount to subtract
+ * @param unit - Unit of time ('days', 'hours', 'minutes', 'seconds')
+ * @returns New date with subtracted time
+ */
+const subtractTime = (date, amount, unit) => {
+    return (0, exports.addTime)(date, -amount, unit);
+};
+exports.subtractTime = subtractTime;
+/**
+ * Checks if a date is in the past
+ * @param date - The date to check
+ * @returns True if date is in the past
+ */
+const isPast = (date) => {
+    return date < new Date();
+};
+exports.isPast = isPast;
+/**
+ * Checks if a date is in the future
+ * @param date - The date to check
+ * @returns True if date is in the future
+ */
+const isFuture = (date) => {
+    return date > new Date();
+};
+exports.isFuture = isFuture;
+/**
+ * Checks if a date is today
+ * @param date - The date to check
+ * @returns True if date is today
+ */
+const isToday = (date) => {
+    const today = new Date();
+    return date.toDateString() === today.toDateString();
+};
+exports.isToday = isToday;
+/**
+ * Gets the start of day for a date
+ * @param date - The date
+ * @returns Date set to start of day (00:00:00)
+ */
+const startOfDay = (date) => {
+    const newDate = new Date(date);
+    newDate.setHours(0, 0, 0, 0);
+    return newDate;
+};
+exports.startOfDay = startOfDay;
+/**
+ * Gets the end of day for a date
+ * @param date - The date
+ * @returns Date set to end of day (23:59:59.999)
+ */
+const endOfDay = (date) => {
+    const newDate = new Date(date);
+    newDate.setHours(23, 59, 59, 999);
+    return newDate;
+};
+exports.endOfDay = endOfDay;
+/**
+ * Gets the age in years from a birth date
+ * @param birthDate - The birth date
+ * @param referenceDate - The reference date (default: now)
+ * @returns Age in years
+ */
+const getAge = (birthDate, referenceDate = new Date()) => {
+    let age = referenceDate.getFullYear() - birthDate.getFullYear();
+    const monthDiff = referenceDate.getMonth() - birthDate.getMonth();
+    if (monthDiff < 0 || (monthDiff === 0 && referenceDate.getDate() < birthDate.getDate())) {
+        age--;
+    }
+    return age;
+};
+exports.getAge = getAge;

package/dist/utils/logger.d.ts

@@ -1,13 +1,63 @@
+/**
+ * A styled console logger that only outputs in development mode
+ * Provides colored output with consistent formatting for different log levels
+ */
 declare class Logger {
     private isDev;
+    /**
+     * Creates a new Logger instance
+     * Automatically detects development mode based on NODE_ENV
+     */
     constructor();
+    /**
+     * Internal method for styled console logging
+     * @param type - The console method to use (info, warn, error, etc.)
+     * @param message - The message to log
+     * @param color - CSS color for the log level indicator
+     * @param args - Additional arguments to pass to console
+     */
     private logMessage;
+    /**
+     * Logs a success message with green color
+     * @param message - The success message to log
+     * @param args - Additional arguments to include in the log
+     */
     success(message: string, ...args: unknown[]): void;
+    /**
+     * Logs an informational message with blue color
+     * @param message - The info message to log
+     * @param args - Additional arguments to include in the log
+     */
     info(message: string, ...args: unknown[]): void;
+    /**
+     * Logs a warning message with yellow color
+     * @param message - The warning message to log
+     * @param args - Additional arguments to include in the log
+     */
     warn(message: string, ...args: unknown[]): void;
+    /**
+     * Logs an error message with red color
+     * @param message - The error message to log
+     * @param args - Additional arguments to include in the log
+     */
     error(message: string, ...args: unknown[]): void;
+    /**
+     * Logs a debug message with green color
+     * @param message - The debug message to log
+     * @param args - Additional arguments to include in the log
+     */
     debug(message: string, ...args: unknown[]): void;
+    /**
+     * Logs a general message with white color
+     * @param message - The message to log
+     * @param args - Additional arguments to include in the log
+     */
     log(message: string, ...args: unknown[]): void;
+    /**
+     * Displays data in a table format using console.table
+     * @param data - The data to display in table format
+     * @param from - Optional label to identify the source of the data
+     */
     table(data: unknown, from?: string): void;
 }
 declare const logger: Logger;

package/dist/utils/logger.js

@@ -1,33 +1,83 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * A styled console logger that only outputs in development mode
+ * Provides colored output with consistent formatting for different log levels
+ */
 class Logger {
+    /**
+     * Creates a new Logger instance
+     * Automatically detects development mode based on NODE_ENV
+     */
     constructor() {
         this.isDev = process.env.NODE_ENV === "development" || !process.env.NODE_ENV;
     }
+    /**
+     * Internal method for styled console logging
+     * @param type - The console method to use (info, warn, error, etc.)
+     * @param message - The message to log
+     * @param color - CSS color for the log level indicator
+     * @param args - Additional arguments to pass to console
+     */
     logMessage(type, message, color, ...args) {
         if (!this.isDev)
             return;
         const styles = `color: ${color}; font-weight: bold;`;
         console[type](`%c[${type.toUpperCase()}] %c${message}`, styles, "color:white;", ...args);
     }
+    /**
+     * Logs a success message with green color
+     * @param message - The success message to log
+     * @param args - Additional arguments to include in the log
+     */
     success(message, ...args) {
         this.logMessage("info", message, "#28a745", ...args);
     }
+    /**
+     * Logs an informational message with blue color
+     * @param message - The info message to log
+     * @param args - Additional arguments to include in the log
+     */
     info(message, ...args) {
         this.logMessage("info", message, "#007bff", ...args);
     }
+    /**
+     * Logs a warning message with yellow color
+     * @param message - The warning message to log
+     * @param args - Additional arguments to include in the log
+     */
     warn(message, ...args) {
         this.logMessage("warn", message, "#ffc107", ...args);
     }
+    /**
+     * Logs an error message with red color
+     * @param message - The error message to log
+     * @param args - Additional arguments to include in the log
+     */
     error(message, ...args) {
         this.logMessage("error", message, "#dc3545", ...args);
     }
+    /**
+     * Logs a debug message with green color
+     * @param message - The debug message to log
+     * @param args - Additional arguments to include in the log
+     */
     debug(message, ...args) {
         this.logMessage("debug", message, "#28a745", ...args);
     }
+    /**
+     * Logs a general message with white color
+     * @param message - The message to log
+     * @param args - Additional arguments to include in the log
+     */
     log(message, ...args) {
         this.logMessage("log", message, "white", ...args);
     }
+    /**
+     * Displays data in a table format using console.table
+     * @param data - The data to display in table format
+     * @param from - Optional label to identify the source of the data
+     */
     table(data, from) {
         if (!this.isDev)
             return;

package/dist/utils/number.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Clamps a number between min and max values
+ * @param num - The number to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Clamped number
+ */
+export declare const clamp: (num: number, min: number, max: number) => number;
+/**
+ * Rounds a number to specified decimal places
+ * @param num - The number to round
+ * @param decimals - Number of decimal places
+ * @returns Rounded number
+ */
+export declare const round: (num: number, decimals?: number) => number;
+/**
+ * Generates a random number between min and max (inclusive)
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Random number
+ */
+export declare const randomBetween: (min: number, max: number) => number;
+/**
+ * Generates a random integer between min and max (inclusive)
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Random integer
+ */
+export declare const randomInt: (min: number, max: number) => number;
+/**
+ * Checks if a number is even
+ * @param num - The number to check
+ * @returns True if even, false otherwise
+ */
+export declare const isEven: (num: number) => boolean;
+/**
+ * Checks if a number is odd
+ * @param num - The number to check
+ * @returns True if odd, false otherwise
+ */
+export declare const isOdd: (num: number) => boolean;
+/**
+ * Converts degrees to radians
+ * @param degrees - Angle in degrees
+ * @returns Angle in radians
+ */
+export declare const toRadians: (degrees: number) => number;
+/**
+ * Converts radians to degrees
+ * @param radians - Angle in radians
+ * @returns Angle in degrees
+ */
+export declare const toDegrees: (radians: number) => number;
+/**
+ * Calculates the percentage of a value relative to a total
+ * @param value - The value
+ * @param total - The total
+ * @returns Percentage (0-100)
+ */
+export declare const percentage: (value: number, total: number) => number;
+/**
+ * Formats a number with thousand separators
+ * @param num - The number to format
+ * @param separator - The separator to use (default: ',')
+ * @returns Formatted number string
+ */
+export declare const formatNumber: (num: number, separator?: string) => string;
+/**
+ * Converts bytes to human readable format
+ * @param bytes - Number of bytes
+ * @param decimals - Number of decimal places (default: 2)
+ * @returns Human readable string
+ */
+export declare const formatBytes: (bytes: number, decimals?: number) => string;
+/**
+ * Calculates the factorial of a number
+ * @param n - The number
+ * @returns Factorial of n
+ */
+export declare const factorial: (n: number) => number;
+/**
+ * Calculates the greatest common divisor of two numbers
+ * @param a - First number
+ * @param b - Second number
+ * @returns GCD of a and b
+ */
+export declare const gcd: (a: number, b: number) => number;
+/**
+ * Calculates the least common multiple of two numbers
+ * @param a - First number
+ * @param b - Second number
+ * @returns LCM of a and b
+ */
+export declare const lcm: (a: number, b: number) => number;

package/dist/utils/number.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lcm = exports.gcd = exports.factorial = exports.formatBytes = exports.formatNumber = exports.percentage = exports.toDegrees = exports.toRadians = exports.isOdd = exports.isEven = exports.randomInt = exports.randomBetween = exports.round = exports.clamp = void 0;
+/**
+ * Clamps a number between min and max values
+ * @param num - The number to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Clamped number
+ */
+const clamp = (num, min, max) => {
+    return Math.min(Math.max(num, min), max);
+};
+exports.clamp = clamp;
+/**
+ * Rounds a number to specified decimal places
+ * @param num - The number to round
+ * @param decimals - Number of decimal places
+ * @returns Rounded number
+ */
+const round = (num, decimals = 0) => {
+    const factor = Math.pow(10, decimals);
+    return Math.round(num * factor) / factor;
+};
+exports.round = round;
+/**
+ * Generates a random number between min and max (inclusive)
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Random number
+ */
+const randomBetween = (min, max) => {
+    return Math.random() * (max - min) + min;
+};
+exports.randomBetween = randomBetween;
+/**
+ * Generates a random integer between min and max (inclusive)
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Random integer
+ */
+const randomInt = (min, max) => {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+};
+exports.randomInt = randomInt;
+/**
+ * Checks if a number is even
+ * @param num - The number to check
+ * @returns True if even, false otherwise
+ */
+const isEven = (num) => {
+    return num % 2 === 0;
+};
+exports.isEven = isEven;
+/**
+ * Checks if a number is odd
+ * @param num - The number to check
+ * @returns True if odd, false otherwise
+ */
+const isOdd = (num) => {
+    return num % 2 !== 0;
+};
+exports.isOdd = isOdd;
+/**
+ * Converts degrees to radians
+ * @param degrees - Angle in degrees
+ * @returns Angle in radians
+ */
+const toRadians = (degrees) => {
+    return degrees * (Math.PI / 180);
+};
+exports.toRadians = toRadians;
+/**
+ * Converts radians to degrees
+ * @param radians - Angle in radians
+ * @returns Angle in degrees
+ */
+const toDegrees = (radians) => {
+    return radians * (180 / Math.PI);
+};
+exports.toDegrees = toDegrees;
+/**
+ * Calculates the percentage of a value relative to a total
+ * @param value - The value
+ * @param total - The total
+ * @returns Percentage (0-100)
+ */
+const percentage = (value, total) => {
+    return total === 0 ? 0 : (value / total) * 100;
+};
+exports.percentage = percentage;
+/**
+ * Formats a number with thousand separators
+ * @param num - The number to format
+ * @param separator - The separator to use (default: ',')
+ * @returns Formatted number string
+ */
+const formatNumber = (num, separator = ',') => {
+    return num.toString().replace(/\B(?=(\d{3})+(?!\d))/g, separator);
+};
+exports.formatNumber = formatNumber;
+/**
+ * Converts bytes to human readable format
+ * @param bytes - Number of bytes
+ * @param decimals - Number of decimal places (default: 2)
+ * @returns Human readable string
+ */
+const formatBytes = (bytes, decimals = 2) => {
+    if (bytes === 0)
+        return '0 Bytes';
+    const k = 1024;
+    const dm = decimals < 0 ? 0 : decimals;
+    const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
+};
+exports.formatBytes = formatBytes;
+/**
+ * Calculates the factorial of a number
+ * @param n - The number
+ * @returns Factorial of n
+ */
+const factorial = (n) => {
+    if (n < 0)
+        return NaN;
+    if (n === 0 || n === 1)
+        return 1;
+    return n * (0, exports.factorial)(n - 1);
+};
+exports.factorial = factorial;
+/**
+ * Calculates the greatest common divisor of two numbers
+ * @param a - First number
+ * @param b - Second number
+ * @returns GCD of a and b
+ */
+const gcd = (a, b) => {
+    return b === 0 ? a : (0, exports.gcd)(b, a % b);
+};
+exports.gcd = gcd;
+/**
+ * Calculates the least common multiple of two numbers
+ * @param a - First number
+ * @param b - Second number
+ * @returns LCM of a and b
+ */
+const lcm = (a, b) => {
+    return Math.abs(a * b) / (0, exports.gcd)(a, b);
+};
+exports.lcm = lcm;

package/dist/utils/string.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Capitalizes the first letter of a string
+ * @param str - The string to capitalize
+ * @returns The string with first letter capitalized
+ */
+export declare const capitalize: (str: string) => string;
+/**
+ * Converts a string to camelCase
+ * @param str - The string to convert
+ * @returns The camelCase string
+ */
+export declare const toCamelCase: (str: string) => string;
+/**
+ * Converts a string to kebab-case
+ * @param str - The string to convert
+ * @returns The kebab-case string
+ */
+export declare const toKebabCase: (str: string) => string;
+/**
+ * Converts a string to snake_case
+ * @param str - The string to convert
+ * @returns The snake_case string
+ */
+export declare const toSnakeCase: (str: string) => string;
+/**
+ * Truncates a string to a specified length and adds ellipsis
+ * @param str - The string to truncate
+ * @param length - The maximum length
+ * @param suffix - The suffix to add (default: '...')
+ * @returns The truncated string
+ */
+export declare const truncate: (str: string, length: number, suffix?: string) => string;
+/**
+ * Removes leading and trailing whitespace and reduces multiple spaces to single space
+ * @param str - The string to clean
+ * @returns The cleaned string
+ */
+export declare const cleanWhitespace: (str: string) => string;
+/**
+ * Checks if a string is a valid email address
+ * @param email - The email string to validate
+ * @returns True if valid email, false otherwise
+ */
+export declare const isValidEmail: (email: string) => boolean;
+/**
+ * Generates a random string of specified length
+ * @param length - The length of the string to generate
+ * @param chars - The characters to use (default: alphanumeric)
+ * @returns A random string
+ */
+export declare const randomString: (length: number, chars?: string) => string;
+/**
+ * Pluralizes a word based on count
+ * @param word - The word to pluralize
+ * @param count - The count to check
+ * @param plural - Custom plural form (optional)
+ * @returns The singular or plural form
+ */
+export declare const pluralize: (word: string, count: number, plural?: string) => string;

package/dist/utils/string.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluralize = exports.randomString = exports.isValidEmail = exports.cleanWhitespace = exports.truncate = exports.toSnakeCase = exports.toKebabCase = exports.toCamelCase = exports.capitalize = void 0;
+/**
+ * Capitalizes the first letter of a string
+ * @param str - The string to capitalize
+ * @returns The string with first letter capitalized
+ */
+const capitalize = (str) => {
+    if (!str)
+        return str;
+    return str.charAt(0).toUpperCase() + str.slice(1);
+};
+exports.capitalize = capitalize;
+/**
+ * Converts a string to camelCase
+ * @param str - The string to convert
+ * @returns The camelCase string
+ */
+const toCamelCase = (str) => {
+    return str
+        .replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : '')
+        .replace(/^[A-Z]/, (c) => c.toLowerCase());
+};
+exports.toCamelCase = toCamelCase;
+/**
+ * Converts a string to kebab-case
+ * @param str - The string to convert
+ * @returns The kebab-case string
+ */
+const toKebabCase = (str) => {
+    return str
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/\s+/g, '-')
+        .toLowerCase();
+};
+exports.toKebabCase = toKebabCase;
+/**
+ * Converts a string to snake_case
+ * @param str - The string to convert
+ * @returns The snake_case string
+ */
+const toSnakeCase = (str) => {
+    return str
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/\s+/g, '_')
+        .toLowerCase();
+};
+exports.toSnakeCase = toSnakeCase;
+/**
+ * Truncates a string to a specified length and adds ellipsis
+ * @param str - The string to truncate
+ * @param length - The maximum length
+ * @param suffix - The suffix to add (default: '...')
+ * @returns The truncated string
+ */
+const truncate = (str, length, suffix = '...') => {
+    if (str.length <= length)
+        return str;
+    return str.substring(0, length - suffix.length) + suffix;
+};
+exports.truncate = truncate;
+/**
+ * Removes leading and trailing whitespace and reduces multiple spaces to single space
+ * @param str - The string to clean
+ * @returns The cleaned string
+ */
+const cleanWhitespace = (str) => {
+    return str.trim().replace(/\s+/g, ' ');
+};
+exports.cleanWhitespace = cleanWhitespace;
+/**
+ * Checks if a string is a valid email address
+ * @param email - The email string to validate
+ * @returns True if valid email, false otherwise
+ */
+const isValidEmail = (email) => {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+};
+exports.isValidEmail = isValidEmail;
+/**
+ * Generates a random string of specified length
+ * @param length - The length of the string to generate
+ * @param chars - The characters to use (default: alphanumeric)
+ * @returns A random string
+ */
+const randomString = (length, chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789') => {
+    let result = '';
+    for (let i = 0; i < length; i++) {
+        result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+};
+exports.randomString = randomString;
+/**
+ * Pluralizes a word based on count
+ * @param word - The word to pluralize
+ * @param count - The count to check
+ * @param plural - Custom plural form (optional)
+ * @returns The singular or plural form
+ */
+const pluralize = (word, count, plural) => {
+    if (count === 1)
+        return word;
+    return plural || word + 's';
+};
+exports.pluralize = pluralize;

package/package.json

@@ -1,19 +1,32 @@
 {
   "name": "@arnonsang/utils",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "A collection of utility functions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "license": "MIT",
   "author": "arnonsang",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arnonsang/utils.git"
+  },
+  "homepage": "https://github.com/arnonsang/utils#readme",
+  "bugs": {
+    "url": "https://github.com/arnonsang/utils/issues"
+  },
   "scripts": {
     "prepare": "tsc",
     "build": "tsc",
     "patch": "npm version patch && npm publish --access public ",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/node": "^22.13.1",
+    "jest": "^30.0.3",
+    "ts-jest": "^29.4.0",
     "typescript": "^5.7.3"
   }
 }

package/index.js

@@ -1,23 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.logger = void 0;
-__exportStar(require("./utils/chat"), exports);
-var logger_1 = require("./utils/logger");
-Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return __importDefault(logger_1).default; } });

package/index.ts

@@ -1,2 +0,0 @@
-export * from "./utils/chat";
-export { default as logger } from "./utils/logger";

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES6",
-    "module": "CommonJS",
-    "declaration": true,
-    "outDir": "dist",
-    "strict": true
-  },
-  "include": ["index.ts", "utils"]
-}

package/utils/chat.js

@@ -1,29 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.charAtFrom = exports.charAt = void 0;
-/**
- * Returns the character in the alphabet at the given index (0-based).
- * @param index index of the character in the alphabet
- * @param type  type of character to return (lowercase or uppercase)
- * @returns   character at the given index
- */
-const charAt = (index, type = "lower") => {
-    const charset = "abcdefghijklmnopqrstuvwxyz";
-    if (index < 0 || index >= charset.length) {
-        return "";
-    }
-    return type === "upper"
-        ? charset.charAt(index).toUpperCase()
-        : charset.charAt(index);
-};
-exports.charAt = charAt;
-/**
- * Returns the character at the given index in the string.
- * @param str   input string
- * @param index index of the character to return
- * @returns     character at the given index
- */
-const charAtFrom = (str, index) => {
-    return str.charAt(index);
-};
-exports.charAtFrom = charAtFrom;

package/utils/chat.ts

@@ -1,28 +0,0 @@
-/**
- * Returns the character in the alphabet at the given index (0-based).
- * @param index index of the character in the alphabet
- * @param type  type of character to return (lowercase or uppercase)
- * @returns   character at the given index
- */
-const charAt = (index: number, type: "lower" | "upper" = "lower") => {
-  const charset = "abcdefghijklmnopqrstuvwxyz";
-
-  if (index < 0 || index >= charset.length) {
-    return "";
-  }
-  return type === "upper"
-    ? charset.charAt(index).toUpperCase()
-    : charset.charAt(index);
-};
-
-/**
- * Returns the character at the given index in the string.
- * @param str   input string
- * @param index index of the character to return
- * @returns     character at the given index
- */
-const charAtFrom = (str: string, index: number) => {
-  return str.charAt(index);
-};
-
-export { charAt, charAtFrom };

package/utils/logger.js

@@ -1,40 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-class Logger {
-    constructor() {
-        this.isDev = process.env.NODE_ENV === "development" || !process.env.NODE_ENV;
-    }
-    logMessage(type, message, color, ...args) {
-        if (!this.isDev)
-            return;
-        const styles = `color: ${color}; font-weight: bold;`;
-        console[type](`%c[${type.toUpperCase()}] %c${message}`, styles, "color:white;", ...args);
-    }
-    success(message, ...args) {
-        this.logMessage("info", message, "#28a745", ...args);
-    }
-    info(message, ...args) {
-        this.logMessage("info", message, "#007bff", ...args);
-    }
-    warn(message, ...args) {
-        this.logMessage("warn", message, "#ffc107", ...args);
-    }
-    error(message, ...args) {
-        this.logMessage("error", message, "#dc3545", ...args);
-    }
-    debug(message, ...args) {
-        this.logMessage("debug", message, "#28a745", ...args);
-    }
-    log(message, ...args) {
-        this.logMessage("log", message, "white", ...args);
-    }
-    table(data, from) {
-        if (!this.isDev)
-            return;
-        console.log(`%c[DATA TABLE] %c${from || ""}`, "color: #007bff; font-weight: bold;", "color:white;");
-        console.table(data);
-    }
-}
-// Export an instance
-const logger = new Logger();
-exports.default = logger;

package/utils/logger.ts

@@ -1,55 +0,0 @@
-type LogType = "info" | "warn" | "error" | "debug" | "log" | "table";
-
-class Logger {
-  private isDev: boolean;
-
-  constructor() {
-    this.isDev = process.env.NODE_ENV === "development" || !process.env.NODE_ENV;
-  }
-
-  private logMessage(
-    type: LogType,
-    message: string,
-    color: string,
-    ...args: unknown[]
-  ): void {
-    if (!this.isDev) return;
-
-    const styles = `color: ${color}; font-weight: bold;`;
-    console[type](`%c[${type.toUpperCase()}] %c${message}`, styles, "color:white;", ...args);
-  }
-
-  success(message: string, ...args: unknown[]): void {
-    this.logMessage("info", message, "#28a745", ...args);
-  }
-
-  info(message: string, ...args: unknown[]): void {
-    this.logMessage("info", message, "#007bff", ...args);
-  }
-
-  warn(message: string, ...args: unknown[]): void {
-    this.logMessage("warn", message, "#ffc107", ...args);
-  }
-
-  error(message: string, ...args: unknown[]): void {
-    this.logMessage("error", message, "#dc3545", ...args);
-  }
-
-  debug(message: string, ...args: unknown[]): void {
-    this.logMessage("debug", message, "#28a745", ...args);
-  }
-
-  log(message: string, ...args: unknown[]): void {
-    this.logMessage("log", message, "white", ...args);
-  }
-
-  table(data: unknown, from?: string): void {
-    if (!this.isDev) return;
-    console.log(`%c[DATA TABLE] %c${from || ""}`, "color: #007bff; font-weight: bold;", "color:white;");
-    console.table(data);
-  }
-}
-
-// Export an instance
-const logger = new Logger();
-export default logger;