npm package: @mtdevworks/toolkit
Description: Finance calculators & developer utilities — GST, HRA, SIP, EMI, Income Tax, FD/RD, Gratuity, JSON, Base64, Hash, Password
Author: mtdevworks
Latest version: 1.0.1

# @mtdevworks/toolkit

> India-specific financial calculators & developer utilities — used by [mtdevworks.com/tools](https://mtdevworks.com/tools)

[![npm](https://img.shields.io/npm/v/@mtdevworks/toolkit)](https://www.npmjs.com/package/@mtdevworks/toolkit)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Install

```bash
npm install @mtdevworks/toolkit
```

## Quick Start

```typescript
import {
  calculateSip,
  formatJson,
  generatePassword,
} from '@mtdevworks/toolkit';

// SIP Investment Returns
const sip = calculateSip({
  monthlyAmount: 10000,
  years: 10,
  expectedReturn: 12,
});
console.log(sip.corpus); // ₹23,23,391
console.log(sip.cagr); // 12%

// Format JSON
const formatted = formatJson('{"b":2,"a":1}', { sortKeys: true, indent: 2 });

// Generate Secure Password
const [pw] = generatePassword({ length: 20, symbols: true });
console.log(pw.password); // "kQ#9xR!mP2..."
console.log(pw.strength); // "very-strong"
```

## Sub-path Imports

Import only what you need for smaller bundles:

```typescript
import { calculateEmi } from '@mtdevworks/toolkit/finance';
import { base64Encode } from '@mtdevworks/toolkit/dev';
```

---

## Finance Calculators

### `calculateGstLateFee(input)`

GST late filing fee + 18% interest for GSTR-3B, GSTR-1, GSTR-4, GSTR-9.

```typescript
import { calculateGstLateFee } from '@mtdevworks/toolkit';

const result = calculateGstLateFee({
  returnType: '3B',
  isNil: false,
  daysLate: 45,
  taxLiability: 100000,
  annualTurnover: 10000000,
});
// { lateFee: 2000, interest: 2219.18, total: 4219.18, dailyFee: 50, capped: true }
```

### `calculateHra(input)`

HRA exemption under Section 10(13A) — min of actual HRA, rent minus 10% basic, 50%/40% of basic.

```typescript
const result = calculateHra({
  basicAnnual: 600000,
  hraReceived: 300000,
  rentPaidAnnual: 240000,
  isMetro: true,
});
// { exemption: 180000, taxableHra: 120000, ... }
```

### `calculateSip(input)`

SIP returns with CAGR, inflation-adjusted corpus, and equity LTCG or debt tax.

| Field            | Type                  | Description                     |
| ---------------- | --------------------- | ------------------------------- |
| `monthlyAmount`  | number                | Monthly SIP amount              |
| `years`          | number                | Investment period               |
| `expectedReturn` | number                | Annual return %                 |
| `inflation`      | number?               | Inflation rate % (default: 6)   |
| `fundType`       | `'equity' \| 'debt'`? | Tax treatment (default: equity) |

### `calculateEmi(input)`

EMI with year-by-year amortization table and prepayment analysis.

```typescript
const result = calculateEmi({
  principal: 5000000,
  rate: 8.5,
  tenureYears: 20,
  annualPrepayment: 100000,
});
console.log(result.emi); // 43391.22
console.log(result.actualTenureYears); // 15 (reduced by prepayment)
console.log(result.amortization); // [{ year, principalPaid, interestPaid, balance }]
```

### `calculateFd(input)` / `calculateRd(input)`

Fixed Deposit and Recurring Deposit with quarterly compounding, TDS, and senior citizen bonus.

### `calculateIncomeTax(input)`

Old vs New regime comparison for FY 2025-26 with all major deductions.

```typescript
const result = calculateIncomeTax({
  grossIncome: 1500000,
  deductions80c: 150000,
  deductions80d: 25000,
  hraExemption: 180000,
});
// { oldRegime: { tax: ... }, newRegime: { tax: ... }, recommended: 'old', savings: 42000 }
```

### `calculateGratuity(input)`

Gratuity under Payment of Gratuity Act — under/not-under Act formulas, ₹25L tax exemption cap.

### `optimizeSalary(input)`

CTC-to-take-home breakdown with Old vs New regime comparison, EPF, HRA exemption.

---

## Developer Utilities

### `formatJson(input, options?)` / `minifyJson(input)` / `validateJson(input)`

```typescript
formatJson('{"b":2,"a":1}', { sortKeys: true, indent: 4 });
minifyJson('{ "a" : 1 }'); // '{"a":1}'
validateJson('invalid'); // { valid: false, error: "..." }
```

### `base64Encode(input, options?)` / `base64Decode(input, options?)`

```typescript
base64Encode('Hello World'); // "SGVsbG8gV29ybGQ="
base64Encode('Hello World', { urlSafe: true }); // "SGVsbG8gV29ybGQ"
base64Decode('SGVsbG8gV29ybGQ='); // "Hello World"
```

### `generateHash(input, algorithms?)`

Requires Node.js. Generates MD5, SHA-1, SHA-256, SHA-512 hashes.

```typescript
const hashes = generateHash('my secret data');
// { md5: "...", sha1: "...", sha256: "...", sha512: "..." }

const sha = generateHash('my data', ['sha256']);
// { sha256: "..." }
```

### `generatePassword(options?)`

Cryptographically secure password generation with entropy scoring.

```typescript
const passwords = generatePassword({
  length: 24,
  uppercase: true,
  lowercase: true,
  digits: true,
  symbols: true,
  excludeAmbiguous: true,
  count: 5,
});
// [{ password: "...", entropy: 142.56, strength: "very-strong" }, ...]
```

---

## Also Available As

| Channel       | URL                                                  |
| ------------- | ---------------------------------------------------- |
| **Web UI**    | [mtdevworks.com/tools](https://mtdevworks.com/tools) |
| **REST API**  | [api.mtdevworks.com](https://api.mtdevworks.com)     |
| **Portfolio** | [mtdevworks.com](https://mtdevworks.com)             |

## License

MIT © [mtdevworks](https://mtdevworks.com)