js-utils-core 1.0.1 → 1.0.2

package/README.md

@@ -0,0 +1,320 @@
+# js-utils-core
+
+A lightweight, functional utility library for JavaScript with clean, reusable functions inspired by lodash and radash.
+
+## 📦 Installation
+
+```bash
+npm install js-utils-core
+```
+
+## 🚀 Quick Start
+
+```javascript
+const { camelCase, head, isEmpty, sum, clone } = require("js-utils-core");
+
+// String utilities
+camelCase("hello world"); // 'helloWorld'
+
+// Array utilities
+head([1, 2, 3]); // 1
+sum([1, 2, 3, 4]); // 10
+
+// Object utilities
+clone({ a: { b: 1 } }); // Deep clone
+
+// Type checking
+isEmpty(""); // true
+isEmpty([1, 2]); // false
+```
+
+## 📚 Features
+
+### Array Utilities
+
+Transform and manipulate arrays with functional helpers.
+
+- **`head(arr, n)`** - Get first element or n elements
+- **`tail(arr, n)`** - Get last element or n elements
+- **`flatten(arr, depth)`** - Flatten array by depth
+- **`unique(arr, key)`** - Remove duplicates
+- **`groupBy(arr, key)`** - Group array elements
+- **`chunk(arr, size)`** - Create chunks of specified size
+- **`minBy(arr, key)`** - Find minimum value
+- **`maxBy(arr, key)`** - Find maximum value
+- **`sum(arr, key)`** - Sum array values
+
+```javascript
+const { head, chunk, unique } = require("js-utils-core");
+
+head([1, 2, 3]); // 1
+chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+unique([1, 1, 2, 2, 3]); // [1, 2, 3]
+```
+
+### Object Utilities
+
+Work with objects safely and efficiently.
+
+- **`clone(obj)`** - Deep clone using structuredClone or JSON fallback
+- **`pick(obj, keys)`** - Pick specific keys
+- **`omit(obj, keys)`** - Omit specific keys
+- **`merge(...objects)`** - Shallow merge
+- **`deepMerge(...objects)`** - Deep merge
+- **`get(obj, path, default)`** - Get nested value safely
+- **`set(obj, path, value)`** - Set nested value
+- **`flatten(obj, prefix)`** - Flatten nested object
+
+```javascript
+const { pick, get, set } = require("js-utils-core");
+
+const user = { name: "John", email: "john@example.com", age: 30 };
+pick(user, ["name", "email"]); // { name: 'John', email: 'john@example.com' }
+
+const config = { db: { host: "localhost", port: 5432 } };
+get(config, "db.host"); // 'localhost'
+set(config, "db.port", 3306); // Updates config.db.port
+```
+
+### String Utilities
+
+Transform strings with common case conversions and operations.
+
+- **`camelCase(str)`** - Convert to camelCase
+- **`snakeCase(str)`** - Convert to snake_case
+- **`pascalCase(str)`** - Convert to PascalCase
+- **`kebabCase(str)`** - Convert to kebab-case
+- **`capitalize(str)`** - Capitalize first letter
+- **`truncate(str, length, suffix)`** - Truncate with ellipsis
+- **`reverse(str)`** - Reverse string
+- **`repeat(str, n)`** - Repeat string n times
+- **`padStart(str, length, padString)`** - Pad start
+- **`padEnd(str, length, padString)`** - Pad end
+
+```javascript
+const { camelCase, snakeCase, capitalize } = require("js-utils-core");
+
+camelCase("hello-world"); // 'helloWorld'
+snakeCase("helloWorld"); // 'hello_world'
+capitalize("john"); // 'John'
+```
+
+### Type Utilities
+
+Accurate type checking and validation.
+
+- **`typeOf(val)`** - Get exact type (array, date, null, etc.)
+- **`isEmpty(val)`** - Check if empty
+- **`isTruthy(val)`** - Check if truthy and not empty
+- **`isArray(val)`** - Check if array
+- **`isObject(val)`** - Check if object
+- **`isString(val)`** - Check if string
+- **`isNumber(val)`** - Check if valid number
+- **`isPlainObject(val)`** - Check if plain object
+- **`isDate(val)`** - Check if valid date
+- **`isNumeric(val)`** - Check if numeric (including strings)
+
+```javascript
+const { isEmpty, isPlainObject, typeOf } = require("js-utils-core");
+
+isEmpty([]); // true
+isEmpty(""); // true
+isPlainObject({ a: 1 }); // true
+typeOf(new Date()); // 'date'
+typeOf([1, 2, 3]); // 'array'
+```
+
+### Math Utilities
+
+Calculate and validate numeric values.
+
+- **`sum(numbers)`** - Sum array of numbers
+- **`average(numbers)`** - Calculate average
+- **`min(...numbers)`** - Find minimum
+- **`max(...numbers)`** - Find maximum
+- **`clamp(value, min, max)`** - Clamp between min and max
+- **`round(num, decimals)`** - Round to n decimal places
+- **`percentage(value, total)`** - Calculate percentage
+- **`isEven(num)`** - Check if even
+- **`isOdd(num)`** - Check if odd
+- **`isPrime(num)`** - Check if prime
+- **`random(min, max)`** - Generate random number
+- **`randomInt(min, max)`** - Generate random integer
+
+```javascript
+const { sum, clamp, round, isPrime } = require("js-utils-core");
+
+sum([1, 2, 3, 4]); // 10
+clamp(5, 0, 10); // 5
+clamp(15, 0, 10); // 10
+round(3.14159, 2); // 3.14
+isPrime(7); // true
+```
+
+## 💡 Usage Examples
+
+### Working with Arrays
+
+```javascript
+const { groupBy, chunk, maxBy } = require("js-utils-core");
+
+const users = [
+  { id: 1, team: "A", salary: 50000 },
+  { id: 2, team: "B", salary: 60000 },
+  { id: 3, team: "A", salary: 55000 },
+];
+
+// Group by team
+const teams = groupBy(users, "team");
+// { A: [...], B: [...] }
+
+// Create batches
+const batches = chunk(users, 2);
+
+// Find highest salary
+const topPaid = maxBy(users, (u) => u.salary);
+// { id: 2, team: 'B', salary: 60000 }
+```
+
+### Working with Objects
+
+```javascript
+const { deepMerge, get, set } = require("js-utils-core");
+
+const settings = {
+  theme: { dark: false, accent: "blue" },
+  notifications: { email: true },
+};
+
+// Deep merge
+deepMerge(settings, { theme: { dark: true } });
+
+// Safe nested access
+get(settings, "theme.dark"); // false
+get(settings, "theme.invalid", "default"); // 'default'
+
+// Set nested value
+set(settings, "notifications.push", true);
+```
+
+### String Transformations
+
+```javascript
+const { camelCase, snakeCase, truncate } = require("js-utils-core");
+
+const apiKey = "my-api-key-12345";
+camelCase(apiKey); // 'myApiKey12345'
+
+const description = "This is a very long description that needs truncation";
+truncate(description, 20); // 'This is a very long...'
+```
+
+## 🔍 Type Safety
+
+All utilities perform safe type checking internally:
+
+```javascript
+const { get, sum } = require("js-utils-core");
+
+const obj = null;
+get(obj, "prop"); // undefined (no error)
+
+const mixed = [1, "two", null, 4];
+sum(mixed); // 5 (skips non-numbers)
+```
+
+## 📖 Complete API
+
+All functions are exported at the top level:
+
+```javascript
+const utils = require("js-utils-core");
+
+// Array
+(utils.head,
+  utils.tail,
+  utils.flatten,
+  utils.unique,
+  utils.groupBy,
+  utils.chunk,
+  utils.minBy,
+  utils.maxBy,
+  utils.sum);
+
+// Object
+(utils.clone,
+  utils.pick,
+  utils.omit,
+  utils.merge,
+  utils.deepMerge,
+  utils.get,
+  utils.set,
+  utils.flatten);
+
+// String
+(utils.camelCase,
+  utils.snakeCase,
+  utils.pascalCase,
+  utils.kebabCase,
+  utils.capitalize,
+  utils.truncate,
+  utils.reverse,
+  utils.repeat,
+  utils.padStart,
+  utils.padEnd,
+  utils.trim,
+  utils.startsWith,
+  utils.endsWith);
+
+// Type
+(utils.typeOf,
+  utils.isEmpty,
+  utils.isTruthy,
+  utils.isArray,
+  utils.isObject,
+  utils.isString,
+  utils.isNumber,
+  utils.isPlainObject,
+  utils.isDate,
+  utils.isNumeric,
+  utils.isInteger,
+  utils.isFinite);
+
+// Math
+(utils.sum,
+  utils.average,
+  utils.min,
+  utils.max,
+  utils.clamp,
+  utils.round,
+  utils.percentage,
+  utils.percentageOf,
+  utils.isEven,
+  utils.isOdd,
+  utils.isPrime,
+  utils.random,
+  utils.randomInt,
+  utils.difference,
+  utils.approximatelyEqual);
+```
+
+## 🎯 Why js-utils-core?
+
+- **Lightweight** - Minimal bundle size with no dependencies
+- **Functional** - Pure, composable functions
+- **Type-safe** - Safe handling of null, undefined, and edge cases
+- **Well-documented** - Clear JSDoc comments in source
+- **Modern** - Written in ES6+
+- **Battle-tested** - Inspired by industry standards (lodash, radash)
+
+## 📄 License
+
+ISC
+
+## 👤 Author
+
+Manasa
+
+---
+
+**Found a bug or have a suggestion?** Please open an issue on [GitHub](https://github.com/manasabol/js-utils-core).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-utils-core",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A lightweight collection of reusable JavaScript utility functions designed to simplify everyday development tasks and promote clean, consistent code.",
   "main": "index.js",
   "scripts": {