diginext-utils/README.md

README.md

# Diginext Utils

A professional, production-ready utility library with full TypeScript support, comprehensive documentation, and optimized tree-shaking.

## Features

- 🎯 **Fully Typed**: Written in TypeScript with complete type definitions
- 📦 **Tree-Shakeable**: Import only what you need with ES modules
- 📚 **Well Documented**: Comprehensive JSDoc comments with examples
- 🧪 **Thoroughly Tested**: High test coverage with modern testing framework
- ⚡ **Zero Dependencies**: Core utilities have no external dependencies
- 🔧 **Multiple Module Formats**: Supports both CommonJS and ES modules

## Installation

```bash
npm install diginext-utils
# or
yarn add diginext-utils
# or
pnpm add diginext-utils
```

## Usage

### Modern Import (Recommended - Tree-shaking friendly)

```typescript
// Import specific functions
import { sum, average, shuffle } from 'diginext-utils/array';
import { isNull, toBool, deepClone } from 'diginext-utils/object';
import { randomInt, clamp } from 'diginext-utils/math';

const numbers = [1, 2, 3, 4, 5];
console.log(sum(numbers)); // 15
console.log(average(numbers)); // 3
console.log(shuffle(numbers)); // [3, 1, 5, 2, 4] (random order)
```

### Namespace Import

```typescript
import { array, object, math } from 'diginext-utils';

console.log(array.sum([1, 2, 3])); // 6
console.log(object.isNull(null)); // true
console.log(math.randomInt(1, 10)); // Random integer between 1-10
```

### Legacy Import (Backward Compatible)

```typescript
import utils from 'diginext-utils';

console.log(utils.array.sum([1, 2, 3])); // 6
console.log(utils.object.isNull(null)); // true
```

## API Documentation

### Array Utilities

Comprehensive array manipulation and analysis functions:

- `sum`, `average`, `min`, `max` - Statistical operations
- `first`, `last`, `randomElement` - Element access
- `sortByString`, `sortByNumber` - Sorting operations
- `unique`, `intersection`, `difference`, `union` - Set operations
- `shuffle`, `sample`, `chunk`, `compact`, `flatten` - Transformations
- `removeItem`, `removeItemByKey`, `moveElement` - Modifications

[See full array documentation](https://github.com/digitopvn/digitopecosystem-turbo-monorepo/tree/main/packages/diginext-utils#array-utilities)

### Object Utilities

Type-safe object operations and conversions:

- `isNull`, `isEmpty`, `isObject`, `isEqual` - Type checking
- `toBool`, `toInt`, `toFloat`, `toArray` - Type conversion
- `pick`, `omit`, `merge`, `deepClone` - Object manipulation
- `iterate` - Recursive traversal

[See full object documentation](https://github.com/digitopvn/digitopecosystem-turbo-monorepo/tree/main/packages/diginext-utils#object-utilities)

### Math Utilities

Mathematical operations and helpers:

- `random`, `randomInt`, `randomFloat` - Random number generation
- `clamp`, `lerp`, `round` - Number operations
- `degToRad`, `radToDeg` - Angle conversion
- `distance`, `angleBetweenPoints` - Geometric calculations

[See full math documentation](https://github.com/digitopvn/digitopecosystem-turbo-monorepo/tree/main/packages/diginext-utils#math-utilities)

### String Utilities

String manipulation and formatting (legacy modules maintained)

### File Utilities

File system operations and helpers (legacy modules maintained)

### Device Utilities

Browser and device detection (legacy modules maintained)

## TypeScript Support

All functions are fully typed with generics for type safety:

```typescript
import { sum } from 'diginext-utils/array';
import { pick } from 'diginext-utils/object';

interface User {
	id: number;
	name: string;
	age: number;
}

const users: User[] = [/* ... */];
const totalAge: number = sum(users, 'age');
const userSubset: Pick<User, 'id' | 'name'> = pick(users[0], ['id', 'name']);
```

## Performance & Bundle Size

Optimized for tree-shaking - import only what you need:

```typescript
// ✅ Good - Only includes sum function (~0.5kb)
import { sum } from 'diginext-utils/array';

// ❌ Less optimal - Includes all array utilities
import { array } from 'diginext-utils';
```

## Migration from v3.x

Backward compatible with improved APIs:

```typescript
// Old way (still works)
import utils from 'diginext-utils';
const result = utils.array.sumArray([1, 2, 3]);

// New way (recommended)
import { sum } from 'diginext-utils/array';
const result = sum([1, 2, 3]);
```

## Development

```bash
npm install        # Install dependencies
npm run build      # Build library
npm run test       # Run tests
npm run lint       # Lint code
```

## License

MIT © TOP GROUP (Digitop)

## Support

Contact [TOP GROUP Developers](mailto:dev@wearetopgroup.com) for support.