@ph-dev-utils/payroll 0.1.0 → 0.2.0

package/README.md

@@ -4,11 +4,11 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kon2raya24/ph-payroll/blob/main/LICENSE)
 [![Made in PH](https://img.shields.io/badge/made%20in-🇵🇭%20Philippines-0038A8)](https://github.com/kon2raya24)
 
-Filipino payroll calculators for JavaScript / TypeScript — SSS, PhilHealth, Pag-IBIG monthly contributions, 13th-month pay, and pre-tax net take-home. Tables versioned by effective date.
+Filipino payroll calculators for JavaScript / TypeScript — SSS, PhilHealth, Pag-IBIG monthly contributions, 13th-month pay, BIR monthly withholding tax (TRAIN), and pre-tax / post-tax net take-home. Tables versioned by effective date.
 
 ## ⚠️ READ FIRST
 
-This package handles **real money math**. Wrong outputs cause underpayment / overpayment in actual payroll runs. Verify outputs against official agency calculators before production use. Pin your dependency version — tables change every few years. **BIR withholding tax is NOT included in v0.1** (deferred to v0.2 to avoid shipping a naïve WT calculator).
+This package handles **real money math**. Wrong outputs cause underpayment / overpayment in actual payroll runs. Verify outputs against official agency calculators before production use. Pin your dependency version — tables change every few years. **BIR WT in v0.2 is monthly-only** and operates on **taxable income**, not raw gross. De minimis caps and the ₱90k 13th-month annual exemption are caller-handled in v0.2.
 
 Full disclaimer: [project README](https://github.com/kon2raya24/ph-payroll#-read-first--accuracy-disclaimer).
 
@@ -26,6 +26,7 @@ Requires Node 20+.
 import { netTakeHome } from '@ph-dev-utils/payroll';
 
 netTakeHome(30000);
+// pre-tax (v0.1 shape — unchanged):
 // {
 //   gross: 30000,
 //   sss: { msc: 30000, employeeShare: 1500, employerShare: 3030, ... },
@@ -34,6 +35,9 @@ netTakeHome(30000);
 //   totalDeductions: 2450,
 //   net: 27550
 // }
+
+netTakeHome(30000, { includeWT: true });
+// adds: taxableIncome: 27550, withholdingTax: 1007.55, netAfterTax: 26542.45
 ```
 
 ## API Reference
@@ -151,14 +155,84 @@ thirteenthMonthFromMonthly(30000, 1);    // 2500
 
 ---
 
+### `withholdingTaxMonthly(taxableIncome, opts?)` *(v0.2+)*
+
+Source: **BIR RR 11-2018** monthly table (TRAIN Law, second-phase rates effective 2023-01-01).
+
+```ts
+function withholdingTaxMonthly(
+  taxableIncome: number,
+  opts?: { year?: number }
+): { wt: number; bracket: 1|2|3|4|5|6; marginalRate: number }
+```
+
+**Input is taxable income, not gross.** To derive taxable income from gross, use [`taxableIncomeMonthly`](#taxableincomemonthlygross-opts-v02) (or compute manually as `gross − mandatories − nonTaxableAllowances`).
+
+**BIR monthly brackets (TRAIN 2023+):**
+
+| Bracket | Monthly taxable income | Tax |
+| --- | --- | --- |
+| 1 | ≤ ₱20,833 | 0 |
+| 2 | ₱20,833 – ₱33,333 | 15% of excess over ₱20,833 |
+| 3 | ₱33,333 – ₱66,667 | ₱1,875 + 20% of excess over ₱33,333 |
+| 4 | ₱66,667 – ₱166,667 | ₱8,541.80 + 25% of excess over ₱66,667 |
+| 5 | ₱166,667 – ₱666,667 | ₱33,541.80 + 30% of excess over ₱166,667 |
+| 6 | > ₱666,667 | ₱183,541.80 + 35% of excess over ₱666,667 |
+
+```ts
+withholdingTaxMonthly(15000);    // { wt: 0,         bracket: 1, marginalRate: 0    }
+withholdingTaxMonthly(25000);    // { wt: 625.05,    bracket: 2, marginalRate: 0.15 }
+withholdingTaxMonthly(50000);    // { wt: 5208.4,    bracket: 3, marginalRate: 0.20 }
+withholdingTaxMonthly(100000);   // { wt: 16875.05,  bracket: 4, marginalRate: 0.25 }
+withholdingTaxMonthly(200000);   // { wt: 43541.7,   bracket: 5, marginalRate: 0.30 }
+withholdingTaxMonthly(1000000);  // { wt: 300208.35, bracket: 6, marginalRate: 0.35 }
+```
+
+---
+
+### `taxableIncomeMonthly(gross, opts?)` *(v0.2+)*
+
+Derive monthly taxable income from gross. Formula:
+
+```
+taxableIncome = gross − mandatoryDeductions − nonTaxableAllowances
+```
+
+```ts
+function taxableIncomeMonthly(
+  gross: number,
+  opts?: {
+    year?: number;
+    mandatoryDeductions?: number;   // override SSS+PH+Pag-IBIG; default: auto-computed
+    nonTaxableAllowances?: number;  // de minimis within caps + tax-exempt allowances; default: 0
+  }
+): number
+```
+
+Caller-handled (not done here):
+- **De minimis caps** — pass only the non-taxable *portion* of each benefit. Rice subsidy is exempt up to ₱2,000/mo, uniform ₱6,000/yr, medical ₱10,000/yr (employee), etc. If a benefit exceeds its cap, the excess is taxable and should NOT appear in `nonTaxableAllowances`.
+- **13th-month / bonus ₱90k annual exemption** — applies at year level, not month. Excess goes in `gross` for the month received.
+
+```ts
+taxableIncomeMonthly(30000);                                  // 27550 (auto: gross − 2,450 mandatories − 0)
+taxableIncomeMonthly(30000, { nonTaxableAllowances: 2000 });  // 25550
+taxableIncomeMonthly(50000, { mandatoryDeductions: 3200 });   // 46800
+```
+
+---
+
 ### `netTakeHome(monthlySalary, opts?)`
 
-Pre-tax net take-home: gross salary minus mandatory SSS / PhilHealth / Pag-IBIG employee contributions.
+Net take-home: gross salary minus mandatory SSS / PhilHealth / Pag-IBIG employee contributions, and (optionally, v0.2+) BIR withholding tax.
 
 ```ts
 function netTakeHome(
   monthlySalary: number,
-  opts?: { year?: number }
+  opts?: {
+    year?: number;
+    includeWT?: boolean;            // v0.2+: also compute WT and netAfterTax
+    nonTaxableAllowances?: number;  // v0.2+: only used when includeWT is true
+  }
 ): NetTakeHome
 
 interface NetTakeHome {
@@ -166,17 +240,29 @@ interface NetTakeHome {
   sss: SSSContribution;
   philHealth: PhilHealthContribution;
   pagIbig: PagIbigContribution;
-  totalDeductions: number;   // sum of employee shares
-  net: number;               // gross - totalDeductions
+  totalDeductions: number;          // sum of employee shares
+  net: number;                      // gross - totalDeductions (pre-tax)
+  taxableIncome?: number;           // populated only when includeWT
+  withholdingTax?: number;          // populated only when includeWT
+  netAfterTax?: number;             // populated only when includeWT
 }
 ```
 
-**Important:** This is **pre-tax** net. It does NOT subtract BIR withholding tax. To get true take-home, you'd subtract WT yourself (using a tax engine that handles taxable-income calculation, per-period brackets, de minimis benefits, etc.).
+By default (no `includeWT`), this preserves the v0.1 pre-tax shape. The `includeWT: true` opt-in adds three fields without removing any.
 
 ```ts
-netTakeHome(30000).net;     // 27550
-netTakeHome(8000).net;      // 7190 (low-earner with floor PhilHealth + EC)
-netTakeHome(150000).net;    // 145550 (capped contributions)
+// v0.1 shape (default) — pre-tax:
+netTakeHome(30000).net;        // 27550
+netTakeHome(8000).net;         // 7190
+netTakeHome(150000).net;       // 145550
+
+// v0.2+ with WT:
+netTakeHome(30000, { includeWT: true }).withholdingTax;   // 1007.55
+netTakeHome(30000, { includeWT: true }).netAfterTax;      // 26542.45
+
+// v0.2+ with non-taxable allowances:
+netTakeHome(30000, { includeWT: true, nonTaxableAllowances: 2000 }).withholdingTax;
+// 707.55 (lower because TI dropped from 27,550 → 25,550)
 ```
 
 ---

package/data/bir-wt-monthly-train-2023.json

@@ -0,0 +1,28 @@
+{
+  "_meta": {
+    "effective_from": "2023-01-01",
+    "effective_until": null,
+    "applies_to_years": [2023, 2024, 2025, 2026],
+    "period": "monthly",
+    "source": "BIR Revenue Regulations No. 11-2018 (as amended by TRAIN Law) — Monthly Compensation Level (MCL) table, Annex E",
+    "source_url": "https://www.bir.gov.ph/index.php/tax-information/withholding-tax.html",
+    "authority": "Republic Act No. 10963 (Tax Reform for Acceleration and Inclusion / TRAIN Law), as further amended by RA 11534 (CREATE Law) — individual income tax brackets effective January 1, 2023 onwards (second phase of TRAIN rate reductions)",
+    "verified_on": "2026-05-20",
+    "notes": [
+      "Withholding tax is applied to TAXABLE INCOME, not gross compensation.",
+      "Taxable income = gross compensation − mandatory employee contributions (SSS, PhilHealth, Pag-IBIG) − non-taxable allowances (de minimis benefits within caps).",
+      "13th-month pay and other bonuses are non-taxable up to ₱90,000 per year (excess is taxable in the year of receipt); not applied at monthly level.",
+      "Bracket bases (1875.00, 8541.80, 33541.80, 183541.80) are the BIR-published rounded monthly values derived from annualized cumulative tax (annual base ÷ 12).",
+      "This table is for MONTHLY payroll periods only. Semi-monthly, weekly, and daily payrolls use separate BIR-published tables (planned for v0.3)."
+    ]
+  },
+
+  "brackets": [
+    { "bracket": 1, "over": 0,      "not_over": 20833,  "base": 0.00,      "rate_over_min": 0.00 },
+    { "bracket": 2, "over": 20833,  "not_over": 33333,  "base": 0.00,      "rate_over_min": 0.15 },
+    { "bracket": 3, "over": 33333,  "not_over": 66667,  "base": 1875.00,   "rate_over_min": 0.20 },
+    { "bracket": 4, "over": 66667,  "not_over": 166667, "base": 8541.80,   "rate_over_min": 0.25 },
+    { "bracket": 5, "over": 166667, "not_over": 666667, "base": 33541.80,  "rate_over_min": 0.30 },
+    { "bracket": 6, "over": 666667, "not_over": null,   "base": 183541.80, "rate_over_min": 0.35 }
+  ]
+}

package/dist/index.d.ts

@@ -5,5 +5,7 @@ export type { PhilHealthContribution, PhilHealthOptions } from './philhealth.js'
 export { pagIbigContribution } from './pagibig.js';
 export type { PagIbigContribution, PagIbigOptions } from './pagibig.js';
 export { thirteenthMonthPay, thirteenthMonthFromMonthly } from './thirteenth-month.js';
+export { withholdingTaxMonthly, taxableIncomeMonthly } from './withholding-tax.js';
+export type { WithholdingTaxResult, TaxableIncomeOptions } from './withholding-tax.js';
 export { netTakeHome } from './take-home.js';
 export type { NetTakeHome, NetTakeHomeOptions } from './take-home.js';

package/dist/index.js

@@ -2,4 +2,5 @@ export { sssContribution } from './sss.js';
 export { philHealthContribution } from './philhealth.js';
 export { pagIbigContribution } from './pagibig.js';
 export { thirteenthMonthPay, thirteenthMonthFromMonthly } from './thirteenth-month.js';
+export { withholdingTaxMonthly, taxableIncomeMonthly } from './withholding-tax.js';
 export { netTakeHome } from './take-home.js';

package/dist/take-home.d.ts

@@ -12,37 +12,42 @@ export interface NetTakeHome {
     pagIbig: PagIbigContribution;
     /** Sum of employee deductions across SSS, PhilHealth, and Pag-IBIG. */
     totalDeductions: number;
-    /** Gross minus totalDeductions. Excludes BIR withholding tax — see notes. */
+    /** Gross minus totalDeductions. Pre-tax — see `netAfterTax` for post-WT. */
     net: number;
+    /** Monthly taxable income (only present when `includeWT: true`). */
+    taxableIncome?: number;
+    /** BIR monthly withholding tax (only present when `includeWT: true`). */
+    withholdingTax?: number;
+    /** Net minus withholdingTax (only present when `includeWT: true`). */
+    netAfterTax?: number;
 }
 export interface NetTakeHomeOptions {
     year?: number;
+    /**
+     * If true, also compute BIR monthly withholding tax (v0.2+) and populate
+     * `taxableIncome`, `withholdingTax`, and `netAfterTax` on the result.
+     * Default: false (preserves v0.1 pre-tax shape).
+     */
+    includeWT?: boolean;
+    /**
+     * Total non-taxable allowances for the month. Used only when `includeWT: true`.
+     * Caller is responsible for capping per BIR de minimis rules.
+     */
+    nonTaxableAllowances?: number;
 }
 /**
- * Compute pre-tax net take-home: gross monthly salary minus mandatory
- * SSS / PhilHealth / Pag-IBIG employee contributions.
+ * Compute net take-home: gross monthly salary minus mandatory SSS / PhilHealth /
+ * Pag-IBIG employee contributions, and (optionally, v0.2+) BIR withholding tax.
  *
- * **DOES NOT INCLUDE BIR WITHHOLDING TAX.** Withholding requires taxable-income
- * calculation (gross minus non-taxable allowances minus mandatory contributions),
- * per-period derived tables, de minimis benefits handling, and year-end
- * annualization. A simple `gross → WT` calculator would be wrong in most real
- * cases. WT is planned for v0.2 once the package has user feedback and
- * accuracy validation.
- *
- * If you need an estimate including WT, compute taxable income manually and
- * use your preferred tax engine.
- *
- * @param monthlySalary Gross monthly basic salary in pesos.
+ * By default, returns **pre-tax** net (v0.1 shape). Pass `{ includeWT: true }` to
+ * also compute monthly WT and `netAfterTax`. WT is computed off taxable income,
+ * which is derived as `gross − mandatories − nonTaxableAllowances`.
  *
  * @example
- *   netTakeHome(30000);
- *   // {
- *   //   gross: 30000,
- *   //   sss: { employeeShare: 1500, ... },
- *   //   philHealth: { employee: 750, ... },
- *   //   pagIbig: { employee: 200, ... },
- *   //   totalDeductions: 2450,
- *   //   net: 27550
- *   // }
+ *   netTakeHome(30000);                              // pre-tax, v0.1 shape
+ *   // { gross: 30000, ..., totalDeductions: 2450, net: 27550 }
+ *
+ *   netTakeHome(30000, { includeWT: true });         // adds WT fields
+ *   // { ..., net: 27550, taxableIncome: 27550, withholdingTax: 1007.55, netAfterTax: 26542.45 }
  */
 export declare function netTakeHome(monthlySalary: number, opts?: NetTakeHomeOptions): NetTakeHome;

package/dist/take-home.js

@@ -1,35 +1,24 @@
 import { sssContribution } from './sss.js';
 import { philHealthContribution } from './philhealth.js';
 import { pagIbigContribution } from './pagibig.js';
+import { withholdingTaxMonthly, taxableIncomeMonthly } from './withholding-tax.js';
 function round2(n) {
     return Math.round(n * 100) / 100;
 }
 /**
- * Compute pre-tax net take-home: gross monthly salary minus mandatory
- * SSS / PhilHealth / Pag-IBIG employee contributions.
+ * Compute net take-home: gross monthly salary minus mandatory SSS / PhilHealth /
+ * Pag-IBIG employee contributions, and (optionally, v0.2+) BIR withholding tax.
  *
- * **DOES NOT INCLUDE BIR WITHHOLDING TAX.** Withholding requires taxable-income
- * calculation (gross minus non-taxable allowances minus mandatory contributions),
- * per-period derived tables, de minimis benefits handling, and year-end
- * annualization. A simple `gross → WT` calculator would be wrong in most real
- * cases. WT is planned for v0.2 once the package has user feedback and
- * accuracy validation.
- *
- * If you need an estimate including WT, compute taxable income manually and
- * use your preferred tax engine.
- *
- * @param monthlySalary Gross monthly basic salary in pesos.
+ * By default, returns **pre-tax** net (v0.1 shape). Pass `{ includeWT: true }` to
+ * also compute monthly WT and `netAfterTax`. WT is computed off taxable income,
+ * which is derived as `gross − mandatories − nonTaxableAllowances`.
  *
  * @example
- *   netTakeHome(30000);
- *   // {
- *   //   gross: 30000,
- *   //   sss: { employeeShare: 1500, ... },
- *   //   philHealth: { employee: 750, ... },
- *   //   pagIbig: { employee: 200, ... },
- *   //   totalDeductions: 2450,
- *   //   net: 27550
- *   // }
+ *   netTakeHome(30000);                              // pre-tax, v0.1 shape
+ *   // { gross: 30000, ..., totalDeductions: 2450, net: 27550 }
+ *
+ *   netTakeHome(30000, { includeWT: true });         // adds WT fields
+ *   // { ..., net: 27550, taxableIncome: 27550, withholdingTax: 1007.55, netAfterTax: 26542.45 }
  */
 export function netTakeHome(monthlySalary, opts = {}) {
     if (!Number.isFinite(monthlySalary) || monthlySalary < 0) {
@@ -40,7 +29,7 @@ export function netTakeHome(monthlySalary, opts = {}) {
     const pagIbig = pagIbigContribution(monthlySalary, opts);
     const totalDeductions = round2(sss.employeeShare + philHealth.employee + pagIbig.employee);
     const net = round2(monthlySalary - totalDeductions);
-    return {
+    const result = {
         gross: monthlySalary,
         sss,
         philHealth,
@@ -48,4 +37,16 @@ export function netTakeHome(monthlySalary, opts = {}) {
         totalDeductions,
         net,
     };
+    if (opts.includeWT) {
+        const taxableIncome = taxableIncomeMonthly(monthlySalary, {
+            year: opts.year,
+            mandatoryDeductions: totalDeductions,
+            nonTaxableAllowances: opts.nonTaxableAllowances,
+        });
+        const { wt } = withholdingTaxMonthly(taxableIncome, { year: opts.year });
+        result.taxableIncome = taxableIncome;
+        result.withholdingTax = wt;
+        result.netAfterTax = round2(net - wt);
+    }
+    return result;
 }

package/dist/withholding-tax.d.ts

@@ -0,0 +1,60 @@
+export interface WithholdingTaxResult {
+    /** Computed withholding tax for the month. */
+    wt: number;
+    /** Bracket number (1–6) that the taxable income fell into. */
+    bracket: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Marginal rate applied to the portion above the bracket floor. */
+    marginalRate: number;
+}
+export interface TaxableIncomeOptions {
+    year?: number;
+    /**
+     * Override mandatory deductions (SSS+PhilHealth+Pag-IBIG employee shares).
+     * If omitted, computed automatically from the gross via v0.1 contribution functions.
+     */
+    mandatoryDeductions?: number;
+    /**
+     * Total non-taxable allowances for the month (de minimis benefits within their caps,
+     * other tax-exempt allowances). Caller is responsible for capping per BIR rules — this
+     * function trusts the value as given.
+     */
+    nonTaxableAllowances?: number;
+}
+/**
+ * Compute BIR withholding tax for a given **monthly taxable income**.
+ *
+ * Source: BIR RR 11-2018 monthly table (TRAIN Law, second phase of rate reductions
+ * effective 2023-01-01).
+ *
+ * **Important:** the input is *taxable income*, not gross compensation. To derive
+ * taxable income from gross, use {@link taxableIncomeMonthly}.
+ *
+ * @example
+ *   withholdingTaxMonthly(25000);
+ *   // { wt: 625, bracket: 2, marginalRate: 0.15 }
+ *   // (15% × (25,000 − 20,833) = 625.05; rounded)
+ */
+export declare function withholdingTaxMonthly(taxableIncome: number, opts?: {
+    year?: number;
+}): WithholdingTaxResult;
+/**
+ * Derive monthly taxable income from gross compensation.
+ *
+ * Formula: `gross − mandatoryDeductions − nonTaxableAllowances`
+ *
+ * If `mandatoryDeductions` is omitted, it is auto-computed as the sum of SSS,
+ * PhilHealth, and Pag-IBIG employee shares for the given gross (using v0.1
+ * contribution functions).
+ *
+ * **Not handled here:** 13th-month + bonus ₱90,000 annual exemption (that's an
+ * annual concern, not monthly). De minimis benefit caps are the caller's
+ * responsibility — pass only the *non-taxable portion* in `nonTaxableAllowances`.
+ *
+ * @example
+ *   taxableIncomeMonthly(30000);
+ *   // 27,550 (gross − auto-computed 2,450 mandatories − 0 allowances)
+ *
+ *   taxableIncomeMonthly(50000, { nonTaxableAllowances: 2000 });
+ *   // 50,000 − mandatories(50k) − 2,000
+ */
+export declare function taxableIncomeMonthly(gross: number, opts?: TaxableIncomeOptions): number;

package/dist/withholding-tax.js

@@ -0,0 +1,88 @@
+import table from '../data/bir-wt-monthly-train-2023.json' with { type: 'json' };
+import { sssContribution } from './sss.js';
+import { philHealthContribution } from './philhealth.js';
+import { pagIbigContribution } from './pagibig.js';
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+function assertYearSupported(year) {
+    if (year === undefined)
+        return;
+    if (!table._meta.applies_to_years.includes(year)) {
+        throw new RangeError(`withholding-tax: no BIR monthly WT table available for year ${year}. Available: ${table._meta.applies_to_years.join(', ')}. Pin to an older package version if needed.`);
+    }
+}
+/**
+ * Compute BIR withholding tax for a given **monthly taxable income**.
+ *
+ * Source: BIR RR 11-2018 monthly table (TRAIN Law, second phase of rate reductions
+ * effective 2023-01-01).
+ *
+ * **Important:** the input is *taxable income*, not gross compensation. To derive
+ * taxable income from gross, use {@link taxableIncomeMonthly}.
+ *
+ * @example
+ *   withholdingTaxMonthly(25000);
+ *   // { wt: 625, bracket: 2, marginalRate: 0.15 }
+ *   // (15% × (25,000 − 20,833) = 625.05; rounded)
+ */
+export function withholdingTaxMonthly(taxableIncome, opts = {}) {
+    if (!Number.isFinite(taxableIncome) || taxableIncome < 0) {
+        throw new TypeError('withholdingTaxMonthly: taxableIncome must be a non-negative number');
+    }
+    assertYearSupported(opts.year);
+    const brackets = table.brackets;
+    let chosen = brackets[0];
+    for (const b of brackets) {
+        if (taxableIncome > b.over)
+            chosen = b;
+        else
+            break;
+    }
+    const wt = round2(chosen.base + chosen.rate_over_min * (taxableIncome - chosen.over));
+    return {
+        wt,
+        bracket: chosen.bracket,
+        marginalRate: chosen.rate_over_min,
+    };
+}
+/**
+ * Derive monthly taxable income from gross compensation.
+ *
+ * Formula: `gross − mandatoryDeductions − nonTaxableAllowances`
+ *
+ * If `mandatoryDeductions` is omitted, it is auto-computed as the sum of SSS,
+ * PhilHealth, and Pag-IBIG employee shares for the given gross (using v0.1
+ * contribution functions).
+ *
+ * **Not handled here:** 13th-month + bonus ₱90,000 annual exemption (that's an
+ * annual concern, not monthly). De minimis benefit caps are the caller's
+ * responsibility — pass only the *non-taxable portion* in `nonTaxableAllowances`.
+ *
+ * @example
+ *   taxableIncomeMonthly(30000);
+ *   // 27,550 (gross − auto-computed 2,450 mandatories − 0 allowances)
+ *
+ *   taxableIncomeMonthly(50000, { nonTaxableAllowances: 2000 });
+ *   // 50,000 − mandatories(50k) − 2,000
+ */
+export function taxableIncomeMonthly(gross, opts = {}) {
+    if (!Number.isFinite(gross) || gross < 0) {
+        throw new TypeError('taxableIncomeMonthly: gross must be a non-negative number');
+    }
+    let mandatory = opts.mandatoryDeductions;
+    if (mandatory === undefined) {
+        const sss = sssContribution(gross, { year: opts.year });
+        const ph = philHealthContribution(gross, { year: opts.year });
+        const pi = pagIbigContribution(gross, { year: opts.year });
+        mandatory = sss.employeeShare + ph.employee + pi.employee;
+    }
+    if (!Number.isFinite(mandatory) || mandatory < 0) {
+        throw new TypeError('taxableIncomeMonthly: mandatoryDeductions must be a non-negative number');
+    }
+    const nta = opts.nonTaxableAllowances ?? 0;
+    if (!Number.isFinite(nta) || nta < 0) {
+        throw new TypeError('taxableIncomeMonthly: nonTaxableAllowances must be a non-negative number');
+    }
+    return round2(Math.max(0, gross - mandatory - nta));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ph-dev-utils/payroll",
-  "version": "0.1.0",
-  "description": "Filipino payroll calculators — SSS, PhilHealth, Pag-IBIG contributions; 13th month pay; net take-home. Versioned contribution tables per effective year.",
+  "version": "0.2.0",
+  "description": "Filipino payroll calculators — SSS, PhilHealth, Pag-IBIG contributions; 13th month pay; BIR monthly withholding tax (TRAIN); net take-home. Versioned contribution tables per effective year.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,6 +30,9 @@
     "sss",
     "philhealth",
     "pagibig",
+    "bir",
+    "withholding-tax",
+    "train-law",
     "13th-month",
     "contribution",
     "calculator"