pakdatakit 2.5.1 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/DATA.md +83 -7
  2. package/README.md +94 -31
  3. package/dist/{chunk-LQHM3ADX.js → chunk-33JPVN33.js} +11 -6
  4. package/dist/{chunk-XCFZKCV2.cjs → chunk-36K225SE.cjs} +14 -9
  5. package/dist/{chunk-CEPNSHIC.js → chunk-3OCMTNQ7.js} +1 -1
  6. package/dist/{chunk-YDUXIENX.cjs → chunk-4YLSPXBZ.cjs} +2 -2
  7. package/dist/{chunk-2OBKPYJZ.cjs → chunk-6AIN4FKB.cjs} +12 -4
  8. package/dist/chunk-7NTUEHQV.cjs +69 -0
  9. package/dist/{chunk-KRYHLYN2.js → chunk-BATPA7GN.js} +12 -4
  10. package/dist/chunk-CKCOK6X4.js +64 -0
  11. package/dist/{chunk-7DY26QPN.js → chunk-CRYCAMWC.js} +1 -1
  12. package/dist/{chunk-TVL6RDAU.cjs → chunk-EGF4CINK.cjs} +2 -2
  13. package/dist/{chunk-XVEG53NN.cjs → chunk-GOGEMCGG.cjs} +84 -0
  14. package/dist/chunk-NDW52ZK3.js +85 -0
  15. package/dist/chunk-NLSIAPZG.cjs +90 -0
  16. package/dist/{chunk-IDTRFOQW.js → chunk-OYQJQE5R.js} +10 -5
  17. package/dist/{chunk-5RGX4DWF.js → chunk-SGGQ6XB2.js} +46 -14
  18. package/dist/{chunk-UYFTXD4P.js → chunk-T6K46DGW.js} +1 -1
  19. package/dist/{chunk-AUQFA7EE.cjs → chunk-VSIVT5RT.cjs} +11 -6
  20. package/dist/{chunk-H6M6L26S.cjs → chunk-VZIBHQC7.cjs} +2 -2
  21. package/dist/{chunk-EA3SIHYT.js → chunk-WYNM5ZWY.js} +84 -1
  22. package/dist/{chunk-5DDHO5Z7.cjs → chunk-XWGSREI5.cjs} +46 -14
  23. package/dist/class-validator.cjs +18 -9
  24. package/dist/class-validator.d.cts +12 -3
  25. package/dist/class-validator.d.ts +12 -3
  26. package/dist/class-validator.js +17 -9
  27. package/dist/cli.js +1 -1
  28. package/dist/cnic.cjs +11 -3
  29. package/dist/cnic.d.cts +80 -3
  30. package/dist/cnic.d.ts +80 -3
  31. package/dist/cnic.js +1 -1
  32. package/dist/format.cjs +11 -3
  33. package/dist/format.d.cts +57 -1
  34. package/dist/format.d.ts +57 -1
  35. package/dist/format.js +1 -1
  36. package/dist/incometax.cjs +6 -6
  37. package/dist/incometax.d.cts +51 -7
  38. package/dist/incometax.d.ts +51 -7
  39. package/dist/incometax.js +1 -1
  40. package/dist/index.cjs +67 -47
  41. package/dist/index.d.cts +5 -5
  42. package/dist/index.d.ts +5 -5
  43. package/dist/index.js +10 -10
  44. package/dist/input.cjs +8 -8
  45. package/dist/input.js +2 -2
  46. package/dist/joi.cjs +10 -8
  47. package/dist/joi.d.cts +2 -1
  48. package/dist/joi.d.ts +2 -1
  49. package/dist/joi.js +9 -7
  50. package/dist/numbers.cjs +5 -5
  51. package/dist/numbers.d.cts +28 -5
  52. package/dist/numbers.d.ts +28 -5
  53. package/dist/numbers.js +1 -1
  54. package/dist/quality.cjs +5 -5
  55. package/dist/quality.js +2 -2
  56. package/dist/raast.cjs +5 -5
  57. package/dist/raast.d.cts +17 -6
  58. package/dist/raast.d.ts +17 -6
  59. package/dist/raast.js +1 -1
  60. package/dist/{rules-GxgPiVws.d.cts → rules-GEELAOfb.d.cts} +5 -0
  61. package/dist/{rules-GxgPiVws.d.ts → rules-GEELAOfb.d.ts} +5 -0
  62. package/dist/superstruct.cjs +10 -8
  63. package/dist/superstruct.d.cts +2 -1
  64. package/dist/superstruct.d.ts +2 -1
  65. package/dist/superstruct.js +9 -7
  66. package/dist/tax.cjs +5 -5
  67. package/dist/tax.d.cts +8 -2
  68. package/dist/tax.d.ts +8 -2
  69. package/dist/tax.js +2 -2
  70. package/dist/text.cjs +13 -9
  71. package/dist/text.d.cts +40 -4
  72. package/dist/text.d.ts +40 -4
  73. package/dist/text.js +1 -1
  74. package/dist/valibot.cjs +16 -8
  75. package/dist/valibot.d.cts +2 -1
  76. package/dist/valibot.d.ts +2 -1
  77. package/dist/valibot.js +15 -7
  78. package/dist/words.d.cts +4 -1
  79. package/dist/words.d.ts +4 -1
  80. package/dist/yup.cjs +10 -8
  81. package/dist/yup.d.cts +2 -1
  82. package/dist/yup.d.ts +2 -1
  83. package/dist/yup.js +9 -7
  84. package/dist/zod.cjs +12 -8
  85. package/dist/zod.d.cts +2 -1
  86. package/dist/zod.d.ts +2 -1
  87. package/dist/zod.js +11 -7
  88. package/package.json +2 -2
  89. package/dist/chunk-6TSKA2PH.js +0 -38
  90. package/dist/chunk-EEVNLTB4.js +0 -32
  91. package/dist/chunk-HTCSHHOR.cjs +0 -35
  92. package/dist/chunk-LVHTH4P7.cjs +0 -41
package/dist/format.cjs CHANGED
@@ -1,14 +1,22 @@
1
1
  'use strict';
2
2
 
3
- var chunkLVHTH4P7_cjs = require('./chunk-LVHTH4P7.cjs');
3
+ var chunkNLSIAPZG_cjs = require('./chunk-NLSIAPZG.cjs');
4
4
 
5
5
 
6
6
 
7
+ Object.defineProperty(exports, "formatAmountInput", {
8
+ enumerable: true,
9
+ get: function () { return chunkNLSIAPZG_cjs.formatAmountInput; }
10
+ });
7
11
  Object.defineProperty(exports, "formatLakh", {
8
12
  enumerable: true,
9
- get: function () { return chunkLVHTH4P7_cjs.formatLakh; }
13
+ get: function () { return chunkNLSIAPZG_cjs.formatLakh; }
10
14
  });
11
15
  Object.defineProperty(exports, "formatPKR", {
12
16
  enumerable: true,
13
- get: function () { return chunkLVHTH4P7_cjs.formatPKR; }
17
+ get: function () { return chunkNLSIAPZG_cjs.formatPKR; }
18
+ });
19
+ Object.defineProperty(exports, "parseAmount", {
20
+ enumerable: true,
21
+ get: function () { return chunkNLSIAPZG_cjs.parseAmount; }
14
22
  });
package/dist/format.d.cts CHANGED
@@ -23,5 +23,61 @@ declare function formatPKR(amount: number): string;
23
23
  * @throws {RangeError} If `amount` is `NaN` or infinite
24
24
  */
25
25
  declare function formatLakh(amount: number): string;
26
+ /** The result of {@link parseAmount}. */
27
+ interface ParsedAmount {
28
+ /** The amount in rupees, rounded half-up to the paisa (2 decimals). */
29
+ value: number;
30
+ /** The input with surrounding whitespace removed. */
31
+ raw: string;
32
+ }
33
+ /**
34
+ * Reads a rupee amount the way people type it in Pakistan, and returns it in
35
+ * rupees, rounded half-up to the paisa. Returns `null` for anything that is
36
+ * not exactly one non-negative amount; it never throws.
37
+ *
38
+ * Accepted:
39
+ * - digits, with or without grouping: `150000`, `150,000` (international) or
40
+ * `1,50,000` (Pakistani: groups of two, then three), and decimals
41
+ * (`1,234.50`, `.5`, `5.`); a grouping must be complete and consistent;
42
+ * - Urdu (`۱۵۰۰۰۰`) and Arabic-Indic (`١٥٠٠٠٠`) digits, also mixed with
43
+ * 0-9, and the Arabic decimal and thousands separators (`٫`, `٬`);
44
+ * - one currency mark before or after the number: `Rs`, `Rs.`, `PKR` or `₨`
45
+ * (any case), and a trailing `/-` (`Rs. 5,000/-`);
46
+ * - one shorthand unit after the number, with or without a space, in any
47
+ * case: `k`, `thousand(s)`, `hazar`, `ہزار` (× 1,000); `lakh(s)`, `lac(s)`,
48
+ * `لاکھ` (× 100,000); `crore(s)`, `cr`, `کروڑ` (× 10,000,000). Decimals
49
+ * work with units: `1.5 lakh` is 150,000 and `2.25cr` is 22,500,000;
50
+ * - whitespace around and between the parts (spaces, tabs, line breaks and
51
+ * no-break spaces).
52
+ *
53
+ * Rejected (`null`): empty input, negative or signed amounts (`-500`,
54
+ * `+500`), ranges (`5-10k`), more than one number (`500 600`), two currency
55
+ * marks or two units, leftover letters (`500 rupees`, `5kk`), grouping that
56
+ * could be read two ways or is broken (`1,50`, `1.500,00`, `1,5000`), and
57
+ * amounts over Rs. 50 trillion (50 lakh crore), beyond which a number can no
58
+ * longer hold every paisa exactly.
59
+ *
60
+ * The arithmetic is done on the digits, so the result is exact: `1.005`
61
+ * rounds to 1.01 and `1.5 lakh` is exactly 150000.
62
+ *
63
+ * @param input - The amount as typed
64
+ * @returns `{ value, raw }`, or `null` if the input is not one amount
65
+ * @example
66
+ * parseAmount('Rs. 1,50,000/-'); // { value: 150000, raw: 'Rs. 1,50,000/-' }
67
+ * parseAmount('2.25cr'); // { value: 22500000, raw: '2.25cr' }
68
+ * parseAmount('5-10k'); // null
69
+ */
70
+ declare function parseAmount(input: string): ParsedAmount | null;
71
+ /**
72
+ * Writes back an amount typed in any form {@link parseAmount} accepts, for
73
+ * showing next to the field ("= Rs. 150,000"): `Rs.`, international
74
+ * grouping, and paisa only when there are any (`Rs. 1,234.50`). Returns
75
+ * `null` when `parseAmount` does; it never throws.
76
+ *
77
+ * @param input - The amount as typed
78
+ * @returns E.g. `"Rs. 150,000"` for `"1.5 lakh"`, or `null`
79
+ */
80
+ declare function formatAmountInput(input: string): string | null;
26
81
 
27
- export { formatLakh, formatPKR };
82
+ export { formatAmountInput, formatLakh, formatPKR, parseAmount };
83
+ export type { ParsedAmount };
package/dist/format.d.ts CHANGED
@@ -23,5 +23,61 @@ declare function formatPKR(amount: number): string;
23
23
  * @throws {RangeError} If `amount` is `NaN` or infinite
24
24
  */
25
25
  declare function formatLakh(amount: number): string;
26
+ /** The result of {@link parseAmount}. */
27
+ interface ParsedAmount {
28
+ /** The amount in rupees, rounded half-up to the paisa (2 decimals). */
29
+ value: number;
30
+ /** The input with surrounding whitespace removed. */
31
+ raw: string;
32
+ }
33
+ /**
34
+ * Reads a rupee amount the way people type it in Pakistan, and returns it in
35
+ * rupees, rounded half-up to the paisa. Returns `null` for anything that is
36
+ * not exactly one non-negative amount; it never throws.
37
+ *
38
+ * Accepted:
39
+ * - digits, with or without grouping: `150000`, `150,000` (international) or
40
+ * `1,50,000` (Pakistani: groups of two, then three), and decimals
41
+ * (`1,234.50`, `.5`, `5.`); a grouping must be complete and consistent;
42
+ * - Urdu (`۱۵۰۰۰۰`) and Arabic-Indic (`١٥٠٠٠٠`) digits, also mixed with
43
+ * 0-9, and the Arabic decimal and thousands separators (`٫`, `٬`);
44
+ * - one currency mark before or after the number: `Rs`, `Rs.`, `PKR` or `₨`
45
+ * (any case), and a trailing `/-` (`Rs. 5,000/-`);
46
+ * - one shorthand unit after the number, with or without a space, in any
47
+ * case: `k`, `thousand(s)`, `hazar`, `ہزار` (× 1,000); `lakh(s)`, `lac(s)`,
48
+ * `لاکھ` (× 100,000); `crore(s)`, `cr`, `کروڑ` (× 10,000,000). Decimals
49
+ * work with units: `1.5 lakh` is 150,000 and `2.25cr` is 22,500,000;
50
+ * - whitespace around and between the parts (spaces, tabs, line breaks and
51
+ * no-break spaces).
52
+ *
53
+ * Rejected (`null`): empty input, negative or signed amounts (`-500`,
54
+ * `+500`), ranges (`5-10k`), more than one number (`500 600`), two currency
55
+ * marks or two units, leftover letters (`500 rupees`, `5kk`), grouping that
56
+ * could be read two ways or is broken (`1,50`, `1.500,00`, `1,5000`), and
57
+ * amounts over Rs. 50 trillion (50 lakh crore), beyond which a number can no
58
+ * longer hold every paisa exactly.
59
+ *
60
+ * The arithmetic is done on the digits, so the result is exact: `1.005`
61
+ * rounds to 1.01 and `1.5 lakh` is exactly 150000.
62
+ *
63
+ * @param input - The amount as typed
64
+ * @returns `{ value, raw }`, or `null` if the input is not one amount
65
+ * @example
66
+ * parseAmount('Rs. 1,50,000/-'); // { value: 150000, raw: 'Rs. 1,50,000/-' }
67
+ * parseAmount('2.25cr'); // { value: 22500000, raw: '2.25cr' }
68
+ * parseAmount('5-10k'); // null
69
+ */
70
+ declare function parseAmount(input: string): ParsedAmount | null;
71
+ /**
72
+ * Writes back an amount typed in any form {@link parseAmount} accepts, for
73
+ * showing next to the field ("= Rs. 150,000"): `Rs.`, international
74
+ * grouping, and paisa only when there are any (`Rs. 1,234.50`). Returns
75
+ * `null` when `parseAmount` does; it never throws.
76
+ *
77
+ * @param input - The amount as typed
78
+ * @returns E.g. `"Rs. 150,000"` for `"1.5 lakh"`, or `null`
79
+ */
80
+ declare function formatAmountInput(input: string): string | null;
26
81
 
27
- export { formatLakh, formatPKR };
82
+ export { formatAmountInput, formatLakh, formatPKR, parseAmount };
83
+ export type { ParsedAmount };
package/dist/format.js CHANGED
@@ -1 +1 @@
1
- export { formatLakh, formatPKR } from './chunk-6TSKA2PH.js';
1
+ export { formatAmountInput, formatLakh, formatPKR, parseAmount } from './chunk-NDW52ZK3.js';
@@ -1,27 +1,27 @@
1
1
  'use strict';
2
2
 
3
- var chunk5DDHO5Z7_cjs = require('./chunk-5DDHO5Z7.cjs');
3
+ var chunkXWGSREI5_cjs = require('./chunk-XWGSREI5.cjs');
4
4
  require('./chunk-SF4ECUZ6.cjs');
5
5
 
6
6
 
7
7
 
8
8
  Object.defineProperty(exports, "calculateMonthlySalaryTax", {
9
9
  enumerable: true,
10
- get: function () { return chunk5DDHO5Z7_cjs.calculateMonthlySalaryTax; }
10
+ get: function () { return chunkXWGSREI5_cjs.calculateMonthlySalaryTax; }
11
11
  });
12
12
  Object.defineProperty(exports, "calculateSalaryTax", {
13
13
  enumerable: true,
14
- get: function () { return chunk5DDHO5Z7_cjs.calculateSalaryTax; }
14
+ get: function () { return chunkXWGSREI5_cjs.calculateSalaryTax; }
15
15
  });
16
16
  Object.defineProperty(exports, "getSalaryTaxSlabs", {
17
17
  enumerable: true,
18
- get: function () { return chunk5DDHO5Z7_cjs.getSalaryTaxSlabs; }
18
+ get: function () { return chunkXWGSREI5_cjs.getSalaryTaxSlabs; }
19
19
  });
20
20
  Object.defineProperty(exports, "getSalaryTaxYears", {
21
21
  enumerable: true,
22
- get: function () { return chunk5DDHO5Z7_cjs.getSalaryTaxYears; }
22
+ get: function () { return chunkXWGSREI5_cjs.getSalaryTaxYears; }
23
23
  });
24
24
  Object.defineProperty(exports, "getTaxYear", {
25
25
  enumerable: true,
26
- get: function () { return chunk5DDHO5Z7_cjs.getTaxYear; }
26
+ get: function () { return chunkXWGSREI5_cjs.getTaxYear; }
27
27
  });
@@ -12,6 +12,21 @@ interface SalaryTaxSlab {
12
12
  /** Percent of the income above `over`. */
13
13
  rate: number;
14
14
  }
15
+ /**
16
+ * The surcharge under section 4AB of the Income Tax Ordinance: `rate`
17
+ * percent of the tax from the rate table, payable when taxable income
18
+ * exceeds `over` rupees.
19
+ */
20
+ interface SalaryTaxSurcharge {
21
+ /** Percent of the tax from the rate table. `0` where the law sets none. */
22
+ rate: number;
23
+ /** Taxable income must exceed this many rupees (Rs 10 million). */
24
+ over: number;
25
+ /** The law that sets it. */
26
+ law: string;
27
+ /** Official document. */
28
+ source: string;
29
+ }
15
30
  /** The salaried rate table for one tax year (1 July to 30 June). */
16
31
  interface SalaryTaxYear {
17
32
  /** The tax year, named after the June it ends in: 2026 is 1 July 2025 to 30 June 2026. */
@@ -25,6 +40,11 @@ interface SalaryTaxYear {
25
40
  /** Official document. */
26
41
  source: string;
27
42
  slabs: SalaryTaxSlab[];
43
+ /**
44
+ * The section 4AB surcharge on salaried individuals for the year, or
45
+ * `null` for years before it existed (tax years up to 2024).
46
+ */
47
+ surcharge: SalaryTaxSurcharge | null;
28
48
  }
29
49
  /** Options for {@link calculateSalaryTax} and {@link calculateMonthlySalaryTax}. */
30
50
  interface SalaryTaxOptions {
@@ -32,14 +52,27 @@ interface SalaryTaxOptions {
32
52
  taxYear?: number;
33
53
  /** A day in the tax year (`YYYY-MM-DD` or a `Date`). Defaults to today. */
34
54
  date?: string | Date;
55
+ /**
56
+ * Add the section 4AB surcharge (tax years 2025 and 2026, above Rs 10
57
+ * million). Default `false` in 2.x, so existing results do not change; it
58
+ * will default to `true` in 3.0.
59
+ */
60
+ includeSurcharge?: boolean;
35
61
  }
36
62
  /** Result of {@link calculateSalaryTax}. */
37
63
  interface SalaryTax {
38
- /** Tax for the year, in rupees, rounded half up to the paisa. */
64
+ /** Tax for the year from the rate table, in rupees, rounded half up to the paisa. */
39
65
  tax: number;
40
- /** `tax / 12`, rounded half up to the paisa. */
66
+ /**
67
+ * The section 4AB surcharge, rounded half up to the paisa. `0` unless
68
+ * `includeSurcharge` is set and the year and income attract one.
69
+ */
70
+ surcharge: number;
71
+ /** `tax + surcharge`: the year's total. */
72
+ total: number;
73
+ /** `total / 12`, rounded half up to the paisa. */
41
74
  monthly: number;
42
- /** `tax` as a percent of the income, rounded half up to 2 decimals. */
75
+ /** `total` as a percent of the income, rounded half up to 2 decimals. */
43
76
  effectiveRate: number;
44
77
  /** The band the income falls in. */
45
78
  slab: SalaryTaxSlab;
@@ -65,8 +98,16 @@ declare function getSalaryTaxYears(): number[];
65
98
  * Income tax on a salaried individual's taxable income for a tax year, from
66
99
  * the salaried rate table (see {@link getSalaryTaxSlabs}).
67
100
  *
68
- * The rate table only: the surcharge, tax credits, exemptions, the separate
69
- * pension rate and withholding adjustments are not applied.
101
+ * With `includeSurcharge: true` it adds the section 4AB surcharge: a
102
+ * percentage of the whole tax once taxable income exceeds Rs 10 million (10%
103
+ * in tax year 2025, 9% for salaried individuals in 2026, none in 2027 or
104
+ * before 2025). Because it applies to the whole tax, one rupee over Rs 10
105
+ * million adds it in full. It is off by default in 2.x so that existing
106
+ * results do not change, and will be on by default in 3.0.
107
+ *
108
+ * Tax credits, exemptions, the separate pension rate, super tax and
109
+ * withholding adjustments are not applied. This is an estimate, not tax
110
+ * advice.
70
111
  *
71
112
  * @param annualIncome - Taxable income for the year in rupees, 0 to 1
72
113
  * trillion (at most 2 decimals count)
@@ -75,7 +116,10 @@ declare function getSalaryTaxYears(): number[];
75
116
  *
76
117
  * @example
77
118
  * calculateSalaryTax(1_800_000, { taxYear: 2026 });
78
- * // { tax: 72000, monthly: 6000, effectiveRate: 4, slab: { over: 1200000, … }, taxYear: 2026 }
119
+ * // { tax: 72000, surcharge: 0, total: 72000, monthly: 6000, effectiveRate: 4,
120
+ * // slab: { over: 1200000, … }, taxYear: 2026 }
121
+ * calculateSalaryTax(12_000_000, { taxYear: 2026, includeSurcharge: true });
122
+ * // { tax: 3381000, surcharge: 304290, total: 3685290, monthly: 307107.5, … }
79
123
  */
80
124
  declare function calculateSalaryTax(annualIncome: number, options?: SalaryTaxOptions): SalaryTax | null;
81
125
  /**
@@ -88,4 +132,4 @@ declare function calculateSalaryTax(annualIncome: number, options?: SalaryTaxOpt
88
132
  declare function calculateMonthlySalaryTax(monthlySalary: number, options?: SalaryTaxOptions): SalaryTax | null;
89
133
 
90
134
  export { calculateMonthlySalaryTax, calculateSalaryTax, getSalaryTaxSlabs, getSalaryTaxYears, getTaxYear };
91
- export type { SalaryTax, SalaryTaxOptions, SalaryTaxSlab, SalaryTaxYear };
135
+ export type { SalaryTax, SalaryTaxOptions, SalaryTaxSlab, SalaryTaxSurcharge, SalaryTaxYear };
@@ -12,6 +12,21 @@ interface SalaryTaxSlab {
12
12
  /** Percent of the income above `over`. */
13
13
  rate: number;
14
14
  }
15
+ /**
16
+ * The surcharge under section 4AB of the Income Tax Ordinance: `rate`
17
+ * percent of the tax from the rate table, payable when taxable income
18
+ * exceeds `over` rupees.
19
+ */
20
+ interface SalaryTaxSurcharge {
21
+ /** Percent of the tax from the rate table. `0` where the law sets none. */
22
+ rate: number;
23
+ /** Taxable income must exceed this many rupees (Rs 10 million). */
24
+ over: number;
25
+ /** The law that sets it. */
26
+ law: string;
27
+ /** Official document. */
28
+ source: string;
29
+ }
15
30
  /** The salaried rate table for one tax year (1 July to 30 June). */
16
31
  interface SalaryTaxYear {
17
32
  /** The tax year, named after the June it ends in: 2026 is 1 July 2025 to 30 June 2026. */
@@ -25,6 +40,11 @@ interface SalaryTaxYear {
25
40
  /** Official document. */
26
41
  source: string;
27
42
  slabs: SalaryTaxSlab[];
43
+ /**
44
+ * The section 4AB surcharge on salaried individuals for the year, or
45
+ * `null` for years before it existed (tax years up to 2024).
46
+ */
47
+ surcharge: SalaryTaxSurcharge | null;
28
48
  }
29
49
  /** Options for {@link calculateSalaryTax} and {@link calculateMonthlySalaryTax}. */
30
50
  interface SalaryTaxOptions {
@@ -32,14 +52,27 @@ interface SalaryTaxOptions {
32
52
  taxYear?: number;
33
53
  /** A day in the tax year (`YYYY-MM-DD` or a `Date`). Defaults to today. */
34
54
  date?: string | Date;
55
+ /**
56
+ * Add the section 4AB surcharge (tax years 2025 and 2026, above Rs 10
57
+ * million). Default `false` in 2.x, so existing results do not change; it
58
+ * will default to `true` in 3.0.
59
+ */
60
+ includeSurcharge?: boolean;
35
61
  }
36
62
  /** Result of {@link calculateSalaryTax}. */
37
63
  interface SalaryTax {
38
- /** Tax for the year, in rupees, rounded half up to the paisa. */
64
+ /** Tax for the year from the rate table, in rupees, rounded half up to the paisa. */
39
65
  tax: number;
40
- /** `tax / 12`, rounded half up to the paisa. */
66
+ /**
67
+ * The section 4AB surcharge, rounded half up to the paisa. `0` unless
68
+ * `includeSurcharge` is set and the year and income attract one.
69
+ */
70
+ surcharge: number;
71
+ /** `tax + surcharge`: the year's total. */
72
+ total: number;
73
+ /** `total / 12`, rounded half up to the paisa. */
41
74
  monthly: number;
42
- /** `tax` as a percent of the income, rounded half up to 2 decimals. */
75
+ /** `total` as a percent of the income, rounded half up to 2 decimals. */
43
76
  effectiveRate: number;
44
77
  /** The band the income falls in. */
45
78
  slab: SalaryTaxSlab;
@@ -65,8 +98,16 @@ declare function getSalaryTaxYears(): number[];
65
98
  * Income tax on a salaried individual's taxable income for a tax year, from
66
99
  * the salaried rate table (see {@link getSalaryTaxSlabs}).
67
100
  *
68
- * The rate table only: the surcharge, tax credits, exemptions, the separate
69
- * pension rate and withholding adjustments are not applied.
101
+ * With `includeSurcharge: true` it adds the section 4AB surcharge: a
102
+ * percentage of the whole tax once taxable income exceeds Rs 10 million (10%
103
+ * in tax year 2025, 9% for salaried individuals in 2026, none in 2027 or
104
+ * before 2025). Because it applies to the whole tax, one rupee over Rs 10
105
+ * million adds it in full. It is off by default in 2.x so that existing
106
+ * results do not change, and will be on by default in 3.0.
107
+ *
108
+ * Tax credits, exemptions, the separate pension rate, super tax and
109
+ * withholding adjustments are not applied. This is an estimate, not tax
110
+ * advice.
70
111
  *
71
112
  * @param annualIncome - Taxable income for the year in rupees, 0 to 1
72
113
  * trillion (at most 2 decimals count)
@@ -75,7 +116,10 @@ declare function getSalaryTaxYears(): number[];
75
116
  *
76
117
  * @example
77
118
  * calculateSalaryTax(1_800_000, { taxYear: 2026 });
78
- * // { tax: 72000, monthly: 6000, effectiveRate: 4, slab: { over: 1200000, … }, taxYear: 2026 }
119
+ * // { tax: 72000, surcharge: 0, total: 72000, monthly: 6000, effectiveRate: 4,
120
+ * // slab: { over: 1200000, … }, taxYear: 2026 }
121
+ * calculateSalaryTax(12_000_000, { taxYear: 2026, includeSurcharge: true });
122
+ * // { tax: 3381000, surcharge: 304290, total: 3685290, monthly: 307107.5, … }
79
123
  */
80
124
  declare function calculateSalaryTax(annualIncome: number, options?: SalaryTaxOptions): SalaryTax | null;
81
125
  /**
@@ -88,4 +132,4 @@ declare function calculateSalaryTax(annualIncome: number, options?: SalaryTaxOpt
88
132
  declare function calculateMonthlySalaryTax(monthlySalary: number, options?: SalaryTaxOptions): SalaryTax | null;
89
133
 
90
134
  export { calculateMonthlySalaryTax, calculateSalaryTax, getSalaryTaxSlabs, getSalaryTaxYears, getTaxYear };
91
- export type { SalaryTax, SalaryTaxOptions, SalaryTaxSlab, SalaryTaxYear };
135
+ export type { SalaryTax, SalaryTaxOptions, SalaryTaxSlab, SalaryTaxSurcharge, SalaryTaxYear };
package/dist/incometax.js CHANGED
@@ -1,2 +1,2 @@
1
- export { calculateMonthlySalaryTax, calculateSalaryTax, getSalaryTaxSlabs, getSalaryTaxYears, getTaxYear } from './chunk-5RGX4DWF.js';
1
+ export { calculateMonthlySalaryTax, calculateSalaryTax, getSalaryTaxSlabs, getSalaryTaxYears, getTaxYear } from './chunk-SGGQ6XB2.js';
2
2
  import './chunk-5EY5DQS7.js';