nepali-tax-pro-max

नेपाली कर — pro-max edition

The complete Nepal tax calculator. IRD income tax slabs (single/couple, SSF/disabled/pensioner/women), TDS by category, VAT 13%, capital gains, SSF (31%), PF, CIT, corporate tax, and full payroll pipelines — fiscal-year-versioned, TypeScript-first, zero dependencies.

✨ Highlights

🇳🇵 Built for Nepal — IRD slabs, NPR rupees, fiscal-year-aware (Shrawan–Ashad)
📅 Fiscal-year-versioned — pin to "2081/82", never mutate historical rates
👥 Full profile coverage — single/couple, SSF members, disabled, pensioner, women rebate, non-resident, remote-area
💼 15+ TDS categories — rent, royalty, dividend, interest, commission, lottery, …
💰 VAT calculator — 13%, exclusive/inclusive, threshold checker
📈 Capital gains — listed/unlisted shares, land/building, individual/entity, short/long-term
🏛️ SSF (31%) — full sub-allocation (medical, accident, dependent, retirement)
🧾 Vendor bill calculator — service + VAT + TDS pipeline in one call
💵 Full payroll — gross → SSF/PF → deductions → slabs → monthly net + monthly TDS
📦 Tree-shakeable — pure ESM exports, sideEffects: false
🎯 TypeScript-first — strict mode, exhaustive type exports, JSDoc on every function
🪶 Zero dependencies — works in Node, Deno, Bun, the browser, Workers

📦 Install

# npm
npm install nepali-tax-pro-max

# pnpm
pnpm add nepali-tax-pro-max

# yarn
yarn add nepali-tax-pro-max

# bun
bun add nepali-tax-pro-max

Works with Node ≥ 14, modern browsers, Deno, Bun, Cloudflare Workers, Vercel Edge.

⚡ Quick Start

import {
  calculateIncomeTax,
  calculateTDS,
  calculateVAT,
  calculateBill,
  calculatePayroll,
  calculateCapitalGains,
  calculateSSF,
  calculatePF,
  calculateCorporateTax,
} from "nepali-tax-pro-max";

// Income tax
calculateIncomeTax({ income: 1_000_000, status: "single" });
// { tax: 85000, taxableIncome: 1000000, effectiveRate: 0.085, ... }

// TDS — rent 10%
calculateTDS({ amount: 100_000, type: "rent" }).tds;          // 10000

// VAT 13%
calculateVAT(1000).total;                                     // 1130
calculateVAT(1130, { inclusive: true }).vat;                  // 130

// Vendor bill (service + VAT + TDS)
calculateBill({
  serviceAmount: 100_000,
  applyVAT: true,
  tdsType: "service-vat-registered",
});
// { vat: 13000, tds: 1500, payableToVendor: 111500, ... }

// Capital gains — listed shares, individual, > 365 days = 5%
calculateCapitalGains({
  gain: 100_000,
  asset: "shares-listed",
  ownerType: "individual",
  holdingDays: 400,
}).tax;                                                       // 5000

// SSF 31% on basic
calculateSSF(50_000);
// { employee: 5500, employer: 10000, total: 15500, breakdown: {...} }

// Corporate tax — bank 30%
calculateCorporateTax({ profit: 10_000_000, category: "bank-financial" }).tax;
// 3000000

// Full payroll
calculatePayroll({
  monthlyBasic: 50_000,
  monthlyAllowances: 20_000,
  festivalBonus: true,
  profile: { status: "single", isSSFMember: true },
  deductions: { lifeInsurance: 30_000 },
});
// { annualGross: 910000, annualTax: ..., monthlyNet: ..., ssfEmployee: ..., ... }

🧠 Mental Model

Rule	Why
Default fiscal year is 2081/82 (Shrawan 1, 2081 → Ashad 31, 2082).	Most current. Override via `{ fiscalYear: "2081/82" }`.
All rate data is keyed by fiscal year in `RATES_BY_FY`.	Never mutate historical rates — add new files for new FYs.
Single vs couple slabs differ.	Couple gets a wider basic exemption (Rs 6 lakh vs 5 lakh).
SSF members skip the 1% SST.	Pass `profile: { isSSFMember: true }`.
Non-resident is flat 25% — no slabs.	Pass `profile: { residency: "non-resident" }`.
Salary TDS uses slabs; everything else is flat-rate per category.	`calculateTDS` rejects `"salary"` — use `calculateSalaryTDS` or `calculatePayroll`.
VAT is computed on service amount, TDS is computed on service amount.	TDS is not on the VAT (per IRD).
All amounts are NPR rupees (`number`); paisa precision via half-up rounding.	If you need BigInt-precise paisa, use `nepali-numbers-pro-max` for the math.

💼 Income Tax

import { calculateIncomeTax, getSlabs, getEffectiveRate, getMarginalRate } from "nepali-tax-pro-max";

calculateIncomeTax({ income: 1_000_000, status: "single" });
// {
//   fiscalYear: "2081/82",
//   grossIncome: 1000000,
//   taxableIncome: 1000000,
//   tax: 85000,
//   effectiveRate: 0.085,
//   perBracket: [
//     { bracket: { from: 0, to: 500000, rate: 0.01 }, amountInBracket: 500000, tax: 5000 },
//     { bracket: { from: 500000, to: 700000, rate: 0.10 }, amountInBracket: 200000, tax: 20000 },
//     { bracket: { from: 700000, to: 1000000, rate: 0.20 }, amountInBracket: 300000, tax: 60000 },
//   ],
//   notes: [],
// }

// Profile flags
calculateIncomeTax({
  income: 1_000_000,
  profile: { isSSFMember: true, isWomanRebate: true, remoteArea: "A" },
});

// Helpers
getSlabs("single");           // FY 2081/82 single slabs
getEffectiveRate(1_000_000);  // 0.085
getMarginalRate(800_000);     // 0.20

FY 2081/82 slabs

Bracket	Single (Rs)	Couple (Rs)	Rate
1 (SST)	0 – 5,00,000	0 – 6,00,000	1% (0% if SSF)
2	5,00,001 – 7,00,000	6,00,001 – 8,00,000	10%
3	7,00,001 – 10,00,000	8,00,001 – 11,00,000	20%
4	10,00,001 – 20,00,000	11,00,001 – 20,00,000	30%
5	20,00,001 – 50,00,000	20,00,001 – 50,00,000	36%
6	Above 50,00,000	Above 50,00,000	39%

Profile modifiers

Flag	Effect
`isSSFMember: true`	First slab is 0% (no 1% SST), retirement deduction cap rises to Rs 5 lakh
`isDisabled: true`	Basic exemption widens by 50% (e.g. Rs 5L → Rs 7.5L for single)
`isPensioner: true`	Basic exemption widens by 25%
`isWomanRebate: true`	10% rebate on tax (employment income, single only)
`residency: "non-resident"`	Flat 25% on Nepal-source income, no slabs
`remoteArea: "A"` to `"E"`	Additional Rs 50k → Rs 10k deduction

🧾 TDS

import { calculateTDS, calculateSalaryTDS, getTDSRate } from "nepali-tax-pro-max";

calculateTDS({ amount: 100_000, type: "rent" });
// { tds: 10000, rate: 0.10, netToVendor: 90000, ... }

calculateTDS({ amount: 50_000, type: "service-vat-registered" }).tds;   // 750  (1.5%)
calculateTDS({ amount: 50_000, type: "service-non-vat" }).tds;          // 7500 (15%)
calculateTDS({ amount: 100_000, type: "lottery" }).tds;                 // 25000

calculateSalaryTDS({ annualIncome: 1_000_000 });
// { annualTax: 85000, monthlyTds: 7083.33, fiscalYear: "2081/82" }

getTDSRate("commission");    // 0.15

TDS categories (FY 2081/82)

Category	Rate
`rent`	10%
`rent-vehicle`	1.5%
`service-vat-registered`	1.5%
`service-non-vat`	15%
`service-non-resident`	15%
`royalty`	15%
`dividend-resident` / `dividend-non-resident`	5%
`interest-bank-individual`	5%
`interest-other`	15%
`commission`	15%
`lottery`	25%
`meeting-allowance`	15%
`aircraft-lease`	10%
`reinsurance-non-resident`	1.5%
`consumer-committee`	1.5%
`exam-fee`	15%

💰 VAT

import { calculateVAT, extractVAT, addVAT, isAboveVATThreshold } from "nepali-tax-pro-max";

calculateVAT(1000);                      // { base: 1000, vat: 130, total: 1130, inclusive: false }
calculateVAT(1130, { inclusive: true }); // { base: 1000, vat: 130, total: 1130, inclusive: true }

extractVAT(1130);                        // 130
addVAT(1000);                            // 130

isAboveVATThreshold(60_00_000, "goods");   // true (above Rs 50 lakh)
isAboveVATThreshold(40_00_000, "service"); // true (above Rs 30 lakh)

VAT rate: 13%. Thresholds: Rs 50 lakh goods / Rs 30 lakh services (FY 2081/82).

📈 Capital Gains

import { calculateCapitalGains } from "nepali-tax-pro-max";

// Listed shares, individual, > 365 days = 5%
calculateCapitalGains({
  gain: 100_000,
  asset: "shares-listed",
  ownerType: "individual",
  holdingDays: 400,
});
// { rate: 0.05, tax: 5000, netProceeds: 95000, ... }

// Land, individual, ≥ 5 years = 5%
calculateCapitalGains({
  gain: 1_000_000,
  asset: "land",
  ownerType: "individual",
  holdingDays: 10 * 365,
}).tax;                                                       // 50000

Asset	Rate
Listed shares — individual, < 365 days	7.5%
Listed shares — individual, ≥ 365 days	5%
Listed shares — entity	10%
Unlisted shares — individual	10%
Unlisted shares — entity	15%
Land/building — individual, < 5 years	7.5%
Land/building — individual, ≥ 5 years	5%
Land/building — entity	1.5% (advance)

🏛️ SSF / PF / CIT

import { calculateSSF, calculatePF, calculateCIT } from "nepali-tax-pro-max";

calculateSSF(50_000);
// {
//   basicSalary: 50000,
//   employee: 5500,
//   employer: 10000,
//   total: 15500,
//   breakdown: { medical: 1610, accident: 700, dependent: 135, retirement: 13055 },
// }

calculatePF(50_000);
// { employee: 5000, employer: 5000, total: 10000 }

calculatePF(50_000, { employeeRate: 0.15 });   // custom

calculateCIT(500_000);
// { contribution: 500000, cappedContribution: 300000, cap: 300000, excess: 200000, ... }

calculateCIT(600_000, { isSSFMember: true });
// SSF cap is 500k
// { cappedContribution: 500000, cap: 500000, ... }

Scheme	Employee	Employer	Notes
SSF	11%	20%	Total 31% on basic. SSF members skip 1% SST.
PF	10%	10%	Standard provident fund.
CIT	voluntary	—	Capped at Rs 3 lakh (or Rs 5 lakh for SSF members).

🏢 Corporate Tax

import { calculateCorporateTax, getCorporateRate } from "nepali-tax-pro-max";

calculateCorporateTax({ profit: 10_000_000, category: "standard" }).tax;          // 2,500,000
calculateCorporateTax({ profit: 10_000_000, category: "bank-financial" }).tax;    // 3,000,000
calculateCorporateTax({ profit: 10_000_000, category: "special-industry" }).tax;  // 2,000,000

getCorporateRate("export");  // 0.20

Category	Rate
`standard`	25%
`bank-financial` / `insurance` / `telecom` / `petroleum` / `capital-market` / `tobacco-alcohol`	30%
`special-industry` (manufacturing) / `export`	20%

💵 Full Payroll

import { calculatePayroll } from "nepali-tax-pro-max";

calculatePayroll({
  monthlyBasic: 50_000,
  monthlyAllowances: 20_000,
  festivalBonus: true,            // adds 1 month gross as Dashain bonus
  profile: { status: "single", isSSFMember: true },
  deductions: { lifeInsurance: 30_000 },
  retirementScheme: "ssf",        // "ssf" | "pf" | "none"
});
// {
//   fiscalYear: "2081/82",
//   annualGross: 910000,        // 13 × 70000
//   ssfEmployee: 71500,         // 11% × 650000 (basic only)
//   ssfEmployer: 130000,        // 20% × 650000
//   annualDeductions: ...,
//   taxableIncome: ...,
//   annualTax: ...,
//   monthlyTds: ...,
//   annualNet: ...,
//   monthlyNet: ...,
//   notes: [...],
// }

Pipeline:

Annualize — 12 × monthly + festival bonus
SSF or PF on basic
Cap deductions (life insurance ≤ 40k, health ≤ 20k, donation ≤ 5% of income or 100k, retirement ≤ 300k or 500k for SSF)
Apply slabs to taxable income
Apply rebates (women, etc.)
Annual net = gross − employee retirement − tax
Monthly TDS = annualTax / 12

🧾 Vendor Bills (VAT + TDS)

import { calculateBill } from "nepali-tax-pro-max";

calculateBill({
  serviceAmount: 100_000,
  applyVAT: true,
  tdsType: "service-vat-registered",
});
// {
//   serviceAmount: 100000,
//   vat: 13000,
//   tds: 1500,            // 1.5% of service amount (NOT VAT)
//   grossInvoice: 113000, // service + VAT
//   payableToVendor: 111500,  // gross − TDS
//   payableToGovtVAT: 13000,
//   payableToGovtTDS: 1500,
// }

// Rent — no VAT, just TDS
calculateBill({ serviceAmount: 100_000, tdsType: "rent" });
// { tds: 10000, payableToVendor: 90000, ... }

🧰 Full API Reference

Income tax

Function	Description
`calculateIncomeTax(opts)`	Full slab calculation with profile + deductions.
`applySlabs(taxable, slabs)`	Pure: apply a slab table to a value.
`getSlabs(status?, fy?)`	Slab table for a status & FY.
`getEffectiveRate(income, status?, fy?)`	Effective tax rate (`tax / income`).
`getMarginalRate(income, status?, fy?)`	Marginal rate at a given income.

TDS

Function	Description
`calculateTDS({ amount, type, fy? })`	TDS by category (returns `{ tds, rate, netToVendor }`).
`calculateSalaryTDS({ annualIncome, status?, profile?, deductions?, fy? })`	Slab-based annual + monthly TDS.
`getTDSRate(type, fy?)`	Lookup rate.
`totalDeductions(d, fy?, isSSFMember?, taxableForDonation?)`	Sum capped deductions.

VAT

Function	Description
`calculateVAT(amount, opts?)`	Base/vat/total breakdown.
`extractVAT(totalInclusive, fy?)`	VAT amount from inclusive total.
`addVAT(base, fy?)`	VAT amount on top of exclusive base.
`getVATRate(fy?)`	Standard rate (default 13%).
`getVATThreshold("goods" \| "service", fy?)`	Registration threshold.
`isAboveVATThreshold(turnover, type, fy?)`	True if turnover triggers registration.

Capital gains

Function	Description
`calculateCapitalGains({ gain, asset, ownerType, holdingDays?, fy? })`	High-level — picks the right canonical key.
`getCapitalGainsRate(canonicalKey, fy?)`	Direct lookup.

asset: "shares-listed" \| "shares-unlisted" \| "land". ownerType: "individual" \| "entity".

SSF / PF / CIT

Function	Description
`calculateSSF(basic, opts?)`	11%/20% with 4-way breakdown.
`calculatePF(basic, opts?)`	10%/10% (rates configurable).
`calculateCIT(contribution, opts?)`	Capped + excess.

Corporate tax

Function	Description
`calculateCorporateTax({ profit, category, fy? })`	Single-rate per category.
`getCorporateRate(category, fy?)`	Lookup.

Payroll & Bills

Function	Description
`calculatePayroll(opts)`	Full pipeline (gross → net).
`calculateBill({ serviceAmount, applyVAT?, tdsType?, fy? })`	Service + VAT + TDS breakdown.

Rates / data

Function / Constant	Description
`getRates(fy?)`	Full `RatesSnapshot` for a FY.
`getSupportedFiscalYears()`	List of FYs in the registry.
`RATES_BY_FY`	Map of FY → snapshot.
`RATES_FY_2081_82`	Snapshot for current FY.
`DEFAULT_FISCAL_YEAR`	`"2081/82"`.

🎯 Recipes

Salary slip (employee view)

import { calculatePayroll, formatNPR } from "nepali-tax-pro-max";
// (formatNPR from nepali-numbers-pro-max if you also use that — totally optional)

const slip = calculatePayroll({
  monthlyBasic: 80_000,
  monthlyAllowances: 30_000,
  festivalBonus: true,
  profile: { status: "single", isSSFMember: true },
  deductions: { lifeInsurance: 25_000, healthInsurance: 15_000 },
});

console.log(`Annual gross: Rs ${slip.annualGross.toLocaleString()}`);
console.log(`Monthly TDS: Rs ${slip.monthlyTds.toLocaleString()}`);
console.log(`Monthly net: Rs ${slip.monthlyNet.toLocaleString()}`);

Quarterly tax estimate

import { calculateIncomeTax } from "nepali-tax-pro-max";

const annual = calculateIncomeTax({ income: 1_500_000, status: "couple" });
const quarterly = annual.tax / 4;
console.log(`Quarterly advance: Rs ${quarterly}`);

Vendor bill workflow

import { calculateBill } from "nepali-tax-pro-max";

const bill = calculateBill({
  serviceAmount: 250_000,
  applyVAT: true,
  tdsType: "service-vat-registered",
});

// Pay the vendor:
console.log(`Cheque to vendor: Rs ${bill.payableToVendor}`);
// Deposit to IRD:
console.log(`VAT to IRD: Rs ${bill.payableToGovtVAT}`);
console.log(`TDS to IRD: Rs ${bill.payableToGovtTDS}`);

Compare SSF vs PF for an employee

import { calculatePayroll } from "nepali-tax-pro-max";

const opts = { monthlyBasic: 50_000, monthlyAllowances: 0 };

const ssfRun = calculatePayroll({
  ...opts,
  profile: { status: "single", isSSFMember: true },
});
const pfRun = calculatePayroll({
  ...opts,
  profile: { status: "single" },
});

console.log(`SSF take-home: Rs ${ssfRun.monthlyNet}`);
console.log(`PF take-home:  Rs ${pfRun.monthlyNet}`);

Capital gains on a stock sale

import { calculateCapitalGains } from "nepali-tax-pro-max";

const result = calculateCapitalGains({
  gain: 250_000,
  asset: "shares-listed",
  ownerType: "individual",
  holdingDays: 300,    // short-term
});
console.log(`Tax on gain: Rs ${result.tax}`);   // 18,750 (7.5%)

🔧 Maintenance / Annual Updates

Every Nepali fiscal year (Jestha 15 budget speech) brings new rates. Updating:

Copy src/data/fy-2081-82.ts to src/data/fy-NEW.ts.
Update rates per the new Finance Act.
Add the new entry to RATES_BY_FY in src/data/index.ts.
Bump DEFAULT_FISCAL_YEAR to the new FY.
Add a regression test: calculateIncomeTax({ income, fiscalYear: "OLD" }) should still return the old result.
Bump minor version, ship.

Never mutate a published FY file — historical accuracy matters for past tax filings.

Verification sources

🏛️ IRD (ird.gov.np) — Finance Act PDFs, TDS booklet
💰 Ministry of Finance (mof.gov.np) — Budget Speech
🏛️ SSF (ssf.gov.np) — Contribution schedule
📊 ICAN (ican.org.np) — Tax bulletin
📕 Nepal Law Commission — Income Tax Act 2058 consolidated

Cross-check via PwC Nepal Tax Facts, KPMG Nepal Tax Card, and Deloitte Nepal Highlights annual PDFs.

⚠️ Disclaimer

This package implements tax math per published rate tables. It is not legal or financial advice. For binding tax filings, consult a licensed Nepali Chartered Accountant (CA). Authors and contributors disclaim liability for any reliance on these calculations.

🤝 Contributing

PRs welcome. Specifically wanted:

Verified rate tables for older fiscal years (2079/80, 2080/81, …)
Edge-case test coverage
Special-industry tax rates / rebates / incentives

npm install
npm test
npm run typecheck
npm run build

📜 License

Made with ❤️ for the Nepali developer community.

बनाइएको नेपाली डेभलपर समुदायको लागि।

Name	Name	Last commit message	Last commit date
Latest commit History 3 Commits 3 Commits
scripts	scripts
src	src
test	test
.gitignore	.gitignore
LICENSE	LICENSE
README.md	README.md
llms.txt	llms.txt
package-lock.json	package-lock.json
package.json	package.json
tsconfig.json	tsconfig.json
tsup.config.ts	tsup.config.ts
vitest.config.ts	vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

nepali-tax-pro-max

नेपाली कर — pro-max edition

📑 Table of Contents

✨ Highlights

📦 Install

⚡ Quick Start

🧠 Mental Model

💼 Income Tax

FY 2081/82 slabs

Profile modifiers

🧾 TDS

TDS categories (FY 2081/82)

💰 VAT

📈 Capital Gains

🏛️ SSF / PF / CIT

🏢 Corporate Tax

💵 Full Payroll

🧾 Vendor Bills (VAT + TDS)

🧰 Full API Reference

🎯 Recipes

Salary slip (employee view)

Quarterly tax estimate

Vendor bill workflow

Compare SSF vs PF for an employee

Capital gains on a stock sale

🔧 Maintenance / Annual Updates

Verification sources

⚠️ Disclaimer

🤝 Contributing

📜 License

About

Releases

Packages

Contributors

Languages

Search code, repositories, users, issues, pull requests...

Folders and files

Latest commit

History

Repository files navigation

nepali-tax-pro-max

नेपाली कर — pro-max edition

📑 Table of Contents

✨ Highlights

📦 Install

⚡ Quick Start

🧠 Mental Model

💼 Income Tax

FY 2081/82 slabs

Profile modifiers

🧾 TDS

TDS categories (FY 2081/82)

💰 VAT

📈 Capital Gains

🏛️ SSF / PF / CIT

🏢 Corporate Tax

💵 Full Payroll

🧾 Vendor Bills (VAT + TDS)

🧰 Full API Reference

🎯 Recipes

Salary slip (employee view)

Quarterly tax estimate

Vendor bill workflow

Compare SSF vs PF for an employee

Capital gains on a stock sale

🔧 Maintenance / Annual Updates

Verification sources

⚠️ Disclaimer

🤝 Contributing

📜 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages