discount-calculator-js/README.md

A versatile utility for calculating various types of discounts

# Discount Calculator

A versatile and easy-to-use Node.js utility for calculating various types of discounts. Powered by [DiscountCalculator](https://discountcalculator.org/), this package helps businesses and developers quickly implement discount calculations in their applications.

## Features

- **Multiple Discount Types**:
  - Percentage discounts
  - Fixed amount discounts
  - "Buy X Get Y Free" promotions
  - Tiered discounts based on purchase thresholds

- **Detailed Results**:
  - Original amount
  - Discount amount
  - Final price
  - Savings percentage
  - Formatted output

- **Easy Integration**:
  - Simple API for developers
  - Command-line interface for quick calculations
  - Thoroughly documented with examples

## Installation

```bash
npm install discount-calculator-js
```

## Command Line Usage

After installing globally with `npm install -g discount-calculator-js`, you can use the calculator directly from your terminal:

```bash
discount-calculator
```

This will launch an interactive CLI that guides you through the discount calculation process.

## API Usage

```javascript
const { calculateDiscount } = require('discount-calculator-js');

// Example 1: Calculate a 20% discount on $100
const result1 = calculateDiscount(100, {
  type: 'percentage',
  value: 20,
  formatOutput: true
});
console.log(result1.formattedOutput);

// Example 2: Calculate a fixed $25 discount on $150
const result2 = calculateDiscount(150, {
  type: 'fixed',
  value: 25
});
console.log(`Final price: $${result2.finalPrice}`);

// Example 3: Calculate "Buy 2 Get 1 Free" for 5 items at $10 each
const result3 = calculateDiscount(10, {
  type: 'buyxgety',
  quantity: 5,
  buyQuantity: 2,
  getQuantity: 1
});
console.log(`You pay for ${result3.itemsPaid} items and get ${result3.itemsFree} free!`);

// Example 4: Tiered discount ($100+ = 10%, $200+ = 15%, $500+ = 20%)
const tiers = [
  { threshold: 100, discount: 10, type: 'percentage' },
  { threshold: 200, discount: 15, type: 'percentage' },
  { threshold: 500, discount: 20, type: 'percentage' }
];

const result4 = calculateDiscount(250, {
  type: 'tiered',
  tiers
});
console.log(`Discount applied: ${result4.discountValue}%`);
```

## API Reference

### calculateDiscount(amount, options)

Main function to calculate discounts based on the specified type.

**Parameters:**
- `amount`: (Number) The original price or item price
- `options`: (Object) Configuration options:
  - `type`: (String) Type of discount ('percentage', 'fixed', 'buyxgety', 'tiered')
  - `value`: (Number) The discount value (percentage or fixed amount)
  - `formatOutput`: (Boolean) Whether to include formatted output string
  - Additional parameters based on the discount type:
    - For 'buyxgety': `quantity`, `buyQuantity`, `getQuantity`
    - For 'tiered': `tiers` (Array of threshold objects)

**Returns:**
An object containing:
- `originalAmount`: The starting amount
- `discountType`: The type of discount applied
- `discountValue`: The discount value
- `discountAmount`: The amount saved
- `finalPrice`: The price after discount
- `savings`: The amount saved
- `savingsPercentage`: The percentage saved
- `formattedOutput`: (if requested) String representation of the result

### Additional Utility Functions

- `calculatePercentageDiscount(amount, percentage)`
- `calculateFixedDiscount(amount, discountAmount)`
- `calculateBuyXGetYDiscount(amount, quantity, buyQuantity, getQuantity)`
- `calculateTieredDiscount(amount, tiers)`
- `formatResult(result)`
- `getAvailableDiscountTypes()`

## Examples

### Percentage Discount
```javascript
const result = calculatePercentageDiscount(100, 25);
// Result: 25% off $100 = $25 discount, final price $75
```

### Fixed Discount
```javascript
const result = calculateFixedDiscount(80, 15);
// Result: $15 off $80 = final price $65
```

### Buy X Get Y Free
```javascript
const result = calculateBuyXGetYDiscount(10, 8, 2, 1);
// For 8 items at $10 each with "Buy 2 Get 1 Free"
// Result: Pay for 6 items, get 2 free, total $60 instead of $80
```

### Tiered Discount
```javascript
const tiers = [
  { threshold: 50, discount: 5, type: 'percentage' },
  { threshold: 100, discount: 10, type: 'percentage' }
];
const result = calculateTieredDiscount(120, tiers);
// Result: 10% discount applied to $120
```

## Use Cases

- E-commerce platforms
- Point of sale systems
- Pricing calculators
- Financial applications
- Budget planning tools

## License

MIT

---

Try our [advanced discount calculator](https://discountcalculator.org/).