npm package: @naveenyaduvanshi/oddeven-checker
Description: A comprehensive Node.js utility module for number analysis: even/odd checking, array processing, prime detection, and mathematical operations
Author: Naveen Yaduvanshi
Latest version: 2.0.1

# 🧮 Enhanced Number Utils - Comprehensive Number Analysis

A powerful Node.js utility module for comprehensive number analysis including even/odd checking, array processing, prime detection, and mathematical operations.

## 🚀 Features

- ✅ **Basic Operations**: Even/odd checking with boolean and string returns
- ✅ **Array Processing**: Bulk analysis, filtering, and counting
- ✅ **Prime Detection**: Efficient prime number checking
- ✅ **Number Analysis**: Comprehensive number property analysis
- ✅ **Input Validation**: Robust error handling for all functions
- ✅ **TypeScript Ready**: Complete JSDoc documentation
- ✅ **Zero Dependencies**: Lightweight and fast

## 📦 Installation

```bash
npm install @naveenyaduvanshi/oddeven-checker
```

## 🛠️ Usage

### Import Functions

```javascript
// Import specific functions
const { isEven, isOdd, filterEven, isPrime, analyzeNumber } = require('@naveenyaduvanshi/oddeven-checker');

// Or import all functions
const NumberUtils = require('@naveenyaduvanshi/oddeven-checker');
```

### Basic Even/Odd Checking

```javascript
const { isEvenOrOdd, isEven, isOdd } = require('@naveenyaduvanshi/oddeven-checker');

// String returns
console.log(isEvenOrOdd(4));  // "even"
console.log(isEvenOrOdd(7));  // "odd"

// Boolean returns
console.log(isEven(4));       // true
console.log(isOdd(7));        // true
console.log(isEven(0));       // true (zero is even)
```

### Array Processing

```javascript
const { checkArray, filterEven, filterOdd, countEvenOdd } = require('@naveenyaduvanshi/oddeven-checker');

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

// Analyze all numbers
console.log(checkArray(numbers));
// Returns: [{number: 1, status: "odd"}, {number: 2, status: "even"}, ...]

// Filter arrays
console.log(filterEven(numbers));  // [2, 4, 6, 8, 10]
console.log(filterOdd(numbers));   // [1, 3, 5, 7, 9]

// Count even/odd
console.log(countEvenOdd(numbers));
// Returns: {even: 5, odd: 5, total: 10}
```

### Prime Number Detection

```javascript
const { isPrime } = require('@naveenyaduvanshi/oddeven-checker');

console.log(isPrime(7));   // true
console.log(isPrime(8));   // false
console.log(isPrime(2));   // true (smallest prime)
console.log(isPrime(1));   // false
```

### Comprehensive Number Analysis

```javascript
const { analyzeNumber } = require('@naveenyaduvanshi/oddeven-checker');

console.log(analyzeNumber(7));
/* Returns:
{
  number: 7,
  isEven: false,
  isOdd: true,
  isPrime: true,
  isPositive: true,
  isNegative: false,
  isZero: false,
  absoluteValue: 7,
  square: 49
}
*/
```

## 📚 API Reference

### Core Functions

| Function | Parameters | Returns | Description |
|----------|------------|---------|-------------|
| `isEvenOrOdd(num)` | `number` | `string` | Returns "even" or "odd" |
| `isEven(num)` | `number` | `boolean` | Returns true if even |
| `isOdd(num)` | `number` | `boolean` | Returns true if odd |

### Array Functions

| Function | Parameters | Returns | Description |
|----------|------------|---------|-------------|
| `checkArray(numbers)` | `number[]` | `Object[]` | Analyzes array of numbers |
| `filterEven(numbers)` | `number[]` | `number[]` | Returns only even numbers |
| `filterOdd(numbers)` | `number[]` | `number[]` | Returns only odd numbers |
| `countEvenOdd(numbers)` | `number[]` | `Object` | Counts even/odd numbers |

### Advanced Functions

| Function | Parameters | Returns | Description |
|----------|------------|---------|-------------|
| `isPrime(num)` | `number` | `boolean` | Checks if number is prime |
| `analyzeNumber(num)` | `number` | `Object` | Comprehensive number analysis |

### Running Tests

```bash
npm test
# or
node test.js
```

## 🧪 Examples

### Real-world Usage Examples

```javascript
const { filterEven, filterOdd, isPrime, analyzeNumber } = require('@naveenyaduvanshi/oddeven-checker');

// Filter even IDs from a dataset
const userIds = [101, 102, 103, 104, 105, 106];
const evenIds = filterEven(userIds); // [102, 104, 106]

// Find prime numbers in a range
const range = [2, 3, 4, 5, 6, 7, 8, 9, 10, 11];
const primes = range.filter(isPrime); // [2, 3, 5, 7, 11]

// Analyze user scores
const scores = [85, 92, 78, 95, 88];
const analysis = scores.map(analyzeNumber);
```

## 🔧 Error Handling

All functions include comprehensive input validation:

```javascript
try {
  isEven("not a number"); // Throws error
} catch (error) {
  console.log(error.message); // "Input must be a valid number"
}

try {
  filterEven("not an array"); // Throws error
} catch (error) {
  console.log(error.message); // "Input must be an array"
}
```

## 🎯 Performance & Technical Details

- **Zero Dependencies**: No external dependencies for maximum performance
- **Efficient Algorithms**: Optimized prime checking with square root optimization  
- **Memory Efficient**: Minimal memory footprint
- **Fast Array Processing**: Optimized for large datasets
- **ES5 Compatible**: Works with older Node.js versions (>=12.0.0)

### Algorithm Details

- **Even/Odd**: Uses modulo operator (`%`) for O(1) performance
- **Prime Checking**: Square root optimization reduces complexity to O(√n)
- **Array Processing**: Single-pass algorithms for optimal performance

## 📄 License

MIT © [Naveen Yaduvanshi](https://github.com/naveenyaduvanshi)

## 🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📈 Version History

- **v2.0.0**: 🚀 Major release with array processing, prime detection, and comprehensive number analysis
- **v1.0.0**: 🎉 Initial release with basic even/odd checking

## 🔗 Links

- **npm Package**: https://www.npmjs.com/package/@naveenyaduvanshi/oddeven-checker
- **GitHub Repository**: https://github.com/naveen-yaduvanshi/oddeven-checker
- **Report Issues**: https://github.com/naveen-yaduvanshi/oddeven-checker/issues

---

⭐ **Star this repo if you find it helpful!** ⭐

Made with ❤️ by [Naveen Yaduvanshi](https://github.com/naveenyaduvanshi)