cl-cricket-utils/README.md

A utility package for cricket match calculations

# cl-cricket-utils

A cricket utility package to calculate **target runs, required run rate, and projected scores** dynamically.

## 🚀 Features
- ✅ Calculate **target runs and balls left** in a match
- ✅ Compute **required run rate**
- ✅ Estimate **projected scores**
- ✅ More cricket-related utilities coming soon!

---

## 📦 Installation
Install via NPM:
```sh
npm install cl-cricket-utils
```

---

## 🔥 Usage
```javascript
const { calculateTargetRunsAndBallsLeft, calculateRequiredRunRate, calculateProjectedScore } = require('cl-cricket-utils');

const match = {
  status: { id: 2 },
  currentInning: {
    targetRuns: 200,
    totalRuns: 150,
    ballsLeft: 30,
    overs: 5,
  }
};

// Calculate Target Runs and Balls Left
const { targetRuns, ballsLeft, ballText } = calculateTargetRunsAndBallsLeft(match);
console.log(`Target Runs: ${targetRuns}, Balls Left: ${ballsLeft}, Display: ${ballText}`);

// Required Run Rate
const rrr = calculateRequiredRunRate(targetRuns, ballsLeft);
console.log(`Required Run Rate: ${rrr}`);

// Projected Score
const projected = calculateProjectedScore(150, 15, 20);
console.log(`Projected Score: ${projected}`);
```

---

## 🛠 Functions

### 1️⃣ `calculateTargetRunsAndBallsLeft(match)`
📌 **Description:** Determines how many runs are needed to win and how many balls are left.

📌 **Parameters:**
- `match` (**Object**) – Match data including status, target runs, total runs, balls left.

📌 **Returns:**
```js
{
  targetRuns: 50,
  ballsLeft: 30,
  ballText: "Overs" // or "Balls"
}
```

📌 **Example:**
```javascript
const { calculateTargetRunsAndBallsLeft } = require('cl-cricket-utils');
const result = calculateTargetRunsAndBallsLeft(match);
console.log(result);
```

---

### 2️⃣ `calculateRequiredRunRate(targetRuns, ballsLeft)`
📌 **Description:** Computes the required run rate to chase the target.

📌 **Parameters:**
- `targetRuns` (**Number**) – Runs required to win.
- `ballsLeft` (**Number**) – Balls remaining.

📌 **Returns:** `Number` (Required Run Rate)

📌 **Example:**
```javascript
const rrr = calculateRequiredRunRate(50, 30);
console.log(`Required Run Rate: ${rrr}`);
```

---

### 3️⃣ `calculateProjectedScore(currentRuns, currentOvers, totalOvers)`
📌 **Description:** Predicts the final score based on the current run rate.

📌 **Parameters:**
- `currentRuns` (**Number**) – Runs scored so far.
- `currentOvers` (**Number**) – Overs played.
- `totalOvers` (**Number**) – Total overs in the match.

📌 **Returns:** `Number` (Projected Score)

📌 **Example:**
```javascript
const projected = calculateProjectedScore(150, 15, 20);
console.log(`Projected Score: ${projected}`);
```

---

## 📜 License
This package is open-source under the **MIT License**.

## 🤝 Contributing
Feel free to open issues or pull requests on GitHub.

---
### **Final Notes:**
✅ **Users can now see everything on NPM and GitHub**  
✅ **Functions are well documented**  
✅ **Easy-to-follow examples**