@naman_deep_singh/js-extensions 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,8 @@
 # @naman_deep_singh/js-extensions
 
-Universal JavaScript prototype extensions for common development utilities. Works in both Node.js and browser environments.
+**Version:** 1.1.0
+
+Universal JavaScript prototype extensions for common development utilities. Works in both Node.js and browser environments with 50+ utility methods.
 
 ## Installation
 
@@ -10,9 +12,7 @@ npm install @naman_deep_singh/js-extensions
 pnpm add @naman_deep_singh/js-extensions
 ```
 
-## Usage
-
-### Initialize All Extensions
+## Quick Start
 
 ```typescript
 import { initExtensions } from '@naman_deep_singh/js-extensions';
@@ -20,63 +20,290 @@ import { initExtensions } from '@naman_deep_singh/js-extensions';
 // Initialize all extensions
 initExtensions();
 
-// Now use the extensions
+// String utilities
 "hello world".toCapitalize(); // "Hello world"
+"test@email.com".isEmail(); // true
+"hello world".words(); // ["hello", "world"]
+
+// Array utilities
 [1, 2, 2, 3].unique(); // [1, 2, 3]
+[1, 2, 3, 4, 5].chunk(2); // [[1, 2], [3, 4], [5]]
+[1, 2, 3].sample(); // Random element
+
+// Number utilities
+(42).toOrdinal(); // "42nd"
+(0.75).toPercent(); // "75.00%"
+(5).times(i => console.log(i)); // Logs 0,1,2,3,4
+
+// Object utilities
+({a: 1, b: 2}).pick(['a']); // {a: 1}
+({}).isEmpty(); // true
+({user: {name: "John"}}).getPath('user.name'); // "John"
 ```
 
+## Configuration
+
 ### Selective Extensions
 
 ```typescript
-import { extend } from '@naman_deep_singh/js-extensions';
+import { initExtensions, extend } from '@naman_deep_singh/js-extensions';
+
+// Only specific types
+initExtensions({ 
+  string: true, 
+  array: true, 
+  object: false, 
+  number: false 
+});
+
+// Individual extension functions
+extend.string(); // Only string methods
+extend.array();  // Only array methods
+```
+
+### Performance Configuration
+
+```typescript
+import { initExtensions, setPerformanceConfig } from '@naman_deep_singh/js-extensions';
 
-// Only extend strings
-extend.string();
+// Configure performance options
+initExtensions({
+  performance: {
+    enableCaching: true,    // Cache expensive operations
+    maxCacheSize: 200,      // LRU cache size
+    enableValidation: false // Skip input validation for speed
+  }
+});
 
-// Only extend arrays and objects
-initExtensions({ array: true, object: true, string: false, number: false });
+// Or configure separately
+setPerformanceConfig({
+  enableCaching: true,
+  maxCacheSize: 100
+});
 ```
 
 ## String Extensions
 
-- `toCapitalize()` - Capitalize first letter
-- `toCamelCase()` - Convert to camelCase
-- `toKebabCase()` - Convert to kebab-case
-- `toSnakeCase()` - Convert to snake_case
-- `truncate(length, suffix?)` - Truncate with optional suffix
-- `isEmail()` - Check if valid email
-- `isUrl()` - Check if valid URL
-- `removeWhitespace()` - Remove all whitespace
-- `reverse()` - Reverse string
+### Case Conversion
+```typescript
+"hello world".toCapitalize();     // "Hello world"
+"hello-world".toCamelCase();      // "helloWorld"
+"HelloWorld".toKebabCase();       // "hello-world"
+"Hello World".toSnakeCase();      // "hello_world"
+"hello world".toTitleCase();      // "Hello World"
+```
+
+### Validation
+```typescript
+"test@example.com".isEmail();     // true
+"https://example.com".isUrl();    // true
+"racecar".isPalindrome();         // true
+```
+
+### Text Processing
+```typescript
+"Long text here".truncate(8);     // "Long tex..."
+"Long text here".truncate(8, "!"); // "Long tex!"
+"hello world".removeWhitespace(); // "helloworld"
+"<p>Hello</p>".stripHtml();       // "Hello"
+"hello".reverse();                // "olleh"
+```
+
+### Padding & Formatting
+```typescript
+"5".padStart(3, "0");             // "005"
+"5".padEnd(3, "0");               // "500"
+"hello world hello".count("hello"); // 2
+```
+
+### Text Analysis
+```typescript
+"hello world test".words();       // ["hello", "world", "test"]
+"line1\nline2\nline3".lines();    // ["line1", "line2", "line3"]
+```
 
 ## Array Extensions
 
-- `unique()` - Remove duplicates
-- `shuffle()` - Randomly shuffle array
-- `chunk(size)` - Split into chunks
-- `groupBy(keyFn)` - Group by key function
-- `sum()` - Sum numeric values
-- `average()` - Calculate average
-- `compact()` - Remove falsy values
-- `pluck(key)` - Extract property values
+### Basic Operations
+```typescript
+[1, 2, 2, 3, 1].unique();         // [1, 2, 3]
+[1, 2, 3, 4, 5].shuffle();        // [3, 1, 5, 2, 4] (random)
+[1, 2, 3, 4, 5].chunk(2);         // [[1, 2], [3, 4], [5]]
+[0, 1, false, 2, "", 3].compact(); // [1, 2, 3]
+```
+
+### Mathematical Operations
+```typescript
+[1, 2, 3, 4, 5].sum();            // 15
+[1, 2, 3, 4, 5].average();        // 3
+```
+
+### Advanced Filtering & Grouping
+```typescript
+const users = [{name: 'John', age: 25}, {name: 'Jane', age: 30}];
+users.groupBy(u => u.age > 25);    // {false: [{name: 'John'...}], true: [{name: 'Jane'...}]}
+users.pluck('name');               // ['John', 'Jane']
+
+[1, 2, 3, 4, 5].partition(x => x % 2 === 0); // [[2, 4], [1, 3, 5]]
+[1, 2, 3, 4, 5].findLast(x => x > 3);        // 5
+```
+
+### Array Manipulation
+```typescript
+[1, [2, [3, 4]]].flatten(1);      // [1, 2, [3, 4]]
+[1, [2, [3, 4]]].deepFlatten();   // [1, 2, 3, 4]
+```
+
+### Set Operations
+```typescript
+[1, 2, 3].difference([2, 3, 4]);  // [1]
+[1, 2, 3].intersection([2, 3, 4]); // [2, 3]
+[1, 2, 3].union([3, 4, 5]);       // [1, 2, 3, 4, 5]
+```
+
+### Sampling & Slicing
+```typescript
+[1, 2, 3, 4, 5].sample();         // Random element (e.g., 3)
+[1, 2, 3, 4, 5].take(3);          // [1, 2, 3]
+[1, 2, 3, 4, 5].drop(2);          // [3, 4, 5]
+```
 
 ## Object Extensions
 
-- `isEmpty()` - Check if object is empty
-- `pick(keys)` - Pick specific keys
-- `omit(keys)` - Omit specific keys
-- `deepClone()` - Deep clone object
-- `merge(other)` - Merge with another object
+### Basic Operations
+```typescript
+({}).isEmpty();                    // true
+({a: 1, b: 2}).isEmpty();         // false
+
+const obj = {a: 1, b: 2, c: 3};
+obj.pick(['a', 'c']);             // {a: 1, c: 3}
+obj.omit(['b']);                  // {a: 1, c: 3}
+```
+
+### Deep Operations
+```typescript
+const original = {a: 1, b: {c: 2}};
+const cloned = original.deepClone(); // Complete deep copy
+const frozen = original.deepFreeze(); // Recursively frozen
+
+const obj1 = {a: 1, b: 2};
+const obj2 = {c: 3, d: 4};
+obj1.merge(obj2);                 // {a: 1, b: 2, c: 3, d: 4}
+```
+
+### Path Operations
+```typescript
+const data = {
+  user: {
+    profile: {
+      name: "John",
+      age: 30
+    }
+  }
+};
+
+data.hasPath('user.profile.name');     // true
+data.hasPath('user.profile.email');    // false
+data.getPath('user.profile.name');     // "John"
+data.getPath('user.profile.email', 'N/A'); // "N/A"
+data.setPath('user.profile.email', 'john@example.com');
+// Sets nested property, creates path if needed
+```
 
 ## Number Extensions
 
-- `toPercent(decimals?)` - Convert to percentage string
-- `toCurrency(currency?, locale?)` - Format as currency
-- `clamp(min, max)` - Clamp between min/max
-- `isEven()` - Check if even
-- `isOdd()` - Check if odd
-- `isPrime()` - Check if prime number
-- `factorial()` - Calculate factorial
+### Formatting
+```typescript
+(0.75).toPercent();               // "75.00%"
+(0.123).toPercent(1);             // "12.3%"
+(1234.56).toCurrency();           // "$1,234.56"
+(1234.56).toCurrency('EUR', 'de-DE'); // "1.234,56 €"
+```
+
+### Ordinal & Roman
+```typescript
+(1).toOrdinal();                  // "1st"
+(42).toOrdinal();                 // "42nd"
+(1984).toRoman();                 // "MCMLXXXIV"
+(2023).toRoman();                 // "MMXXIII"
+```
+
+### Mathematical Operations
+```typescript
+(15).clamp(10, 20);               // 15
+(5).clamp(10, 20);                // 10
+(25).clamp(10, 20);               // 20
+
+(15).inRange(10, 20);             // true
+(5).inRange(10, 20);              // false
+```
+
+### Number Properties
+```typescript
+(4).isEven();                     // true
+(5).isOdd();                      // true
+(7).isPrime();                    // true
+(5).factorial();                  // 120
+```
+
+### Precision & Math
+```typescript
+(3.14159).round(2);               // 3.14
+(3.14159).ceil(2);                // 3.15
+(3.14159).floor(2);               // 3.14
+(-5).abs();                       // 5
+(-5).sign();                      // -1
+```
+
+### Iteration
+```typescript
+(3).times(i => console.log(`Item ${i}`));
+// Logs: "Item 0", "Item 1", "Item 2"
+```
+
+## Performance Configuration
+
+### Caching System
+```typescript
+import { setPerformanceConfig, getPerformanceConfig } from '@naman_deep_singh/js-extensions';
+
+// Enable caching for expensive operations
+setPerformanceConfig({
+  enableCaching: true,
+  maxCacheSize: 200,
+  enableValidation: true
+});
+
+// Check current config
+const config = getPerformanceConfig();
+console.log(config); // {enableCaching: true, maxCacheSize: 200, enableValidation: true}
+```
+
+### Methods with Built-in Caching
+The following methods automatically use LRU cache when enabled:
+- **`isPrime()`** - Prime number calculations cached for repeated calls
+- **`factorial()`** - Factorial results cached to avoid recalculation  
+- **`toRoman()`** - Roman numeral conversions cached for reuse
+- **`deepClone()`** - Deep clone operations cached for identical objects
+
+### External Caching
+```typescript
+import { withCache } from '@naman_deep_singh/js-extensions';
+
+// Use caching in your own functions
+const expensiveOperation = (input: string) => {
+  return withCache(`myOp_${input}`, () => {
+    // Your expensive computation here
+    return complexCalculation(input);
+  });
+};
+```
+
+### Memory Management
+The LRU (Least Recently Used) cache automatically:
+- Removes oldest entries when cache is full
+- Moves frequently accessed items to front
+- Prevents memory leaks in long-running applications
 
 ## Browser Usage
 
@@ -85,5 +312,127 @@ initExtensions({ array: true, object: true, string: false, number: false });
 <script>
   // Extensions are automatically initialized
   console.log("hello".toCapitalize()); // "Hello"
+  console.log([1,2,2,3].unique()); // [1, 2, 3]
+  console.log((42).toOrdinal()); // "42nd"
+  console.log({a: 1, b: 2}.pick(['a'])); // {a: 1}
 </script>
+```
+
+## TypeScript Support
+
+Full TypeScript support with complete type definitions:
+
+```typescript
+// All methods are fully typed
+const result: string = "hello".toCapitalize();
+const numbers: number[] = [1, 2, 2, 3].unique();
+const picked: Pick<{a: number, b: string}, 'a'> = {a: 1, b: "test"}.pick(['a']);
+
+// Performance configuration is also typed
+const config: PerformanceConfig = {
+  enableCaching: true,
+  maxCacheSize: 100,
+  enableValidation: false
+};
+```
+
+## Package Stats
+
+- **60 utility methods** across 4 JavaScript types
+- **Zero dependencies** - lightweight and fast
+- **Universal compatibility** - Node.js and browser
+- **TypeScript native** - complete type definitions
+- **Performance optimized** - optional caching system
+- **Tree-shakable** - selective imports supported
+
+## Complete API Reference
+
+### Core Functions
+```typescript
+initExtensions(options?: ExtensionOptions): void
+extendAll(): void
+setPerformanceConfig(config: Partial<PerformanceConfig>): void
+getPerformanceConfig(): PerformanceConfig
+
+// Individual extension functions
+extend.string(): void
+extend.array(): void
+extend.object(): void
+extend.number(): void
+```
+
+### String Methods (17 methods)
+```typescript
+toCapitalize(): string
+toCamelCase(): string
+toKebabCase(): string
+toSnakeCase(): string
+toTitleCase(): string
+truncate(length: number, suffix?: string): string
+isEmail(): boolean
+isUrl(): boolean
+isPalindrome(): boolean
+removeWhitespace(): string
+stripHtml(): string
+reverse(): string
+padStart(targetLength: number, padString?: string): string
+padEnd(targetLength: number, padString?: string): string
+count(substring: string): number
+words(): string[]
+lines(): string[]
+```
+
+### Array Methods (18 methods)
+```typescript
+unique<T>(): T[]
+shuffle<T>(): T[]
+chunk<T>(size: number): T[][]
+groupBy<T, K>(keyFn: (item: T) => K): Record<K, T[]>
+sum(): number
+average(): number
+compact<T>(): T[]
+pluck<T, K>(key: K): T[K][]
+findLast<T>(predicate: (item: T) => boolean): T | undefined
+partition<T>(predicate: (item: T) => boolean): [T[], T[]]
+flatten(depth?: number): any[]
+deepFlatten(): any[]
+difference<T>(other: T[]): T[]
+intersection<T>(other: T[]): T[]
+union<T>(other: T[]): T[]
+sample<T>(): T | undefined
+take<T>(count: number): T[]
+drop<T>(count: number): T[]
+```
+
+### Object Methods (9 methods)
+```typescript
+isEmpty(): boolean
+pick<T, K>(keys: K[]): Pick<T, K>
+omit<T, K>(keys: K[]): Omit<T, K>
+deepClone<T>(): T
+deepFreeze<T>(): T
+merge(other: Record<string, any>): Record<string, any>
+hasPath(path: string): boolean
+getPath(path: string, defaultValue?: any): any
+setPath(path: string, value: any): any
+```
+
+### Number Methods (16 methods)
+```typescript
+toPercent(decimals?: number): string
+toCurrency(currency?: string, locale?: string): string
+toOrdinal(): string
+toRoman(): string
+clamp(min: number, max: number): number
+inRange(min: number, max: number): boolean
+isEven(): boolean
+isOdd(): boolean
+isPrime(): boolean
+factorial(): number
+round(decimals?: number): number
+ceil(decimals?: number): number
+floor(decimals?: number): number
+abs(): number
+sign(): number
+times(callback: (index: number) => void): void
 ```

package/dist/{array-extensions.js → cjs/array-extensions.js}

@@ -62,4 +62,22 @@ function extendArray() {
     Array.prototype.deepFlatten = function () {
         return this.reduce((acc, val) => acc.concat(Array.isArray(val) ? val.deepFlatten() : val), []);
     };
+    Array.prototype.difference = function (other) {
+        return this.filter(item => !other.includes(item));
+    };
+    Array.prototype.intersection = function (other) {
+        return this.filter(item => other.includes(item));
+    };
+    Array.prototype.union = function (other) {
+        return [...new Set([...this, ...other])];
+    };
+    Array.prototype.sample = function () {
+        return this.length > 0 ? this[Math.floor(Math.random() * this.length)] : undefined;
+    };
+    Array.prototype.take = function (count) {
+        return this.slice(0, Math.max(0, count));
+    };
+    Array.prototype.drop = function (count) {
+        return this.slice(Math.max(0, count));
+    };
 }

package/dist/{index.d.ts → cjs/index.d.ts}

@@ -2,12 +2,15 @@ import { extendString } from './string-extensions';
 import { extendArray } from './array-extensions';
 import { extendObject } from './object-extensions';
 import { extendNumber } from './number-extensions';
+import { setPerformanceConfig, getPerformanceConfig, type PerformanceConfig, withCache } from './performance';
 import './types';
+export { withCache };
 export interface ExtensionOptions {
     string?: boolean;
     array?: boolean;
     object?: boolean;
     number?: boolean;
+    performance?: PerformanceConfig;
 }
 /**
  * Initialize JavaScript prototype extensions
@@ -27,6 +30,7 @@ export declare const extend: {
     object: typeof extendObject;
     number: typeof extendNumber;
 };
+export { setPerformanceConfig, getPerformanceConfig, type PerformanceConfig };
 declare const _default: {
     initExtensions: typeof initExtensions;
     extendAll: typeof extendAll;
@@ -36,5 +40,7 @@ declare const _default: {
         object: typeof extendObject;
         number: typeof extendNumber;
     };
+    setPerformanceConfig: typeof setPerformanceConfig;
+    getPerformanceConfig: typeof getPerformanceConfig;
 };
 export default _default;

package/dist/{index.js → cjs/index.js}

@@ -1,19 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extend = void 0;
+exports.getPerformanceConfig = exports.setPerformanceConfig = exports.extend = exports.withCache = void 0;
 exports.initExtensions = initExtensions;
 exports.extendAll = extendAll;
 const string_extensions_1 = require("./string-extensions");
 const array_extensions_1 = require("./array-extensions");
 const object_extensions_1 = require("./object-extensions");
 const number_extensions_1 = require("./number-extensions");
+const performance_1 = require("./performance");
+Object.defineProperty(exports, "setPerformanceConfig", { enumerable: true, get: function () { return performance_1.setPerformanceConfig; } });
+Object.defineProperty(exports, "getPerformanceConfig", { enumerable: true, get: function () { return performance_1.getPerformanceConfig; } });
+Object.defineProperty(exports, "withCache", { enumerable: true, get: function () { return performance_1.withCache; } });
 require("./types");
 /**
  * Initialize JavaScript prototype extensions
  * @param options - Configure which extensions to enable (default: all enabled)
  */
 function initExtensions(options = {}) {
-    const { string = true, array = true, object = true, number = true } = options;
+    const { string = true, array = true, object = true, number = true, performance } = options;
+    if (performance) {
+        (0, performance_1.setPerformanceConfig)(performance);
+    }
     if (string)
         (0, string_extensions_1.extendString)();
     if (array)
@@ -41,5 +48,7 @@ exports.extend = {
 exports.default = {
     initExtensions,
     extendAll,
-    extend: exports.extend
+    extend: exports.extend,
+    setPerformanceConfig: performance_1.setPerformanceConfig,
+    getPerformanceConfig: performance_1.getPerformanceConfig
 };

package/dist/cjs/number-extensions.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extendNumber = extendNumber;
+// Number prototype extensions
+const performance_1 = require("./performance");
+function extendNumber() {
+    Number.prototype.toPercent = function (decimals = 2) {
+        return (this.valueOf() * 100).toFixed(decimals) + '%';
+    };
+    Number.prototype.toCurrency = function (currency = 'USD', locale = 'en-US') {
+        return new Intl.NumberFormat(locale, {
+            style: 'currency',
+            currency: currency
+        }).format(this.valueOf());
+    };
+    Number.prototype.clamp = function (min, max) {
+        return Math.min(Math.max(this.valueOf(), min), max);
+    };
+    Number.prototype.isEven = function () {
+        return this.valueOf() % 2 === 0;
+    };
+    Number.prototype.isOdd = function () {
+        return this.valueOf() % 2 !== 0;
+    };
+    Number.prototype.isPrime = function () {
+        const num = this.valueOf();
+        return (0, performance_1.withCache)(`prime_${num}`, () => {
+            if (num < 2)
+                return false;
+            for (let i = 2; i <= Math.sqrt(num); i++) {
+                if (num % i === 0)
+                    return false;
+            }
+            return true;
+        });
+    };
+    Number.prototype.factorial = function () {
+        const num = Math.floor(this.valueOf());
+        return (0, performance_1.withCache)(`factorial_${num}`, () => {
+            if (num < 0)
+                return NaN;
+            if (num === 0 || num === 1)
+                return 1;
+            let result = 1;
+            for (let i = 2; i <= num; i++) {
+                result *= i;
+            }
+            return result;
+        });
+    };
+    Number.prototype.toOrdinal = function () {
+        const num = Math.floor(this.valueOf());
+        const suffix = ['th', 'st', 'nd', 'rd'];
+        const v = num % 100;
+        return num + (suffix[(v - 20) % 10] || suffix[v] || suffix[0]);
+    };
+    Number.prototype.toRoman = function () {
+        const num = Math.floor(this.valueOf());
+        return (0, performance_1.withCache)(`roman_${num}`, () => {
+            if (num <= 0 || num >= 4000)
+                return num.toString();
+            const values = [1000, 900, 500, 400, 100, 90, 50, 40, 10, 9, 5, 4, 1];
+            const symbols = ['M', 'CM', 'D', 'CD', 'C', 'XC', 'L', 'XL', 'X', 'IX', 'V', 'IV', 'I'];
+            let result = '';
+            let n = num;
+            for (let i = 0; i < values.length; i++) {
+                while (n >= values[i]) {
+                    result += symbols[i];
+                    n -= values[i];
+                }
+            }
+            return result;
+        });
+    };
+    Number.prototype.inRange = function (min, max) {
+        const num = this.valueOf();
+        return num >= min && num <= max;
+    };
+    Number.prototype.round = function (decimals = 0) {
+        const factor = Math.pow(10, decimals);
+        return Math.round(this.valueOf() * factor) / factor;
+    };
+    Number.prototype.ceil = function (decimals = 0) {
+        const factor = Math.pow(10, decimals);
+        return Math.ceil(this.valueOf() * factor) / factor;
+    };
+    Number.prototype.floor = function (decimals = 0) {
+        const factor = Math.pow(10, decimals);
+        return Math.floor(this.valueOf() * factor) / factor;
+    };
+    Number.prototype.abs = function () {
+        return Math.abs(this.valueOf());
+    };
+    Number.prototype.sign = function () {
+        return Math.sign(this.valueOf());
+    };
+    Number.prototype.times = function (callback) {
+        const num = Math.floor(this.valueOf());
+        for (let i = 0; i < num; i++) {
+            callback(i);
+        }
+    };
+}