pakdatakit 2.6.0 → 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 (84) hide show
  1. package/DATA.md +83 -7
  2. package/README.md +48 -14
  3. package/dist/{chunk-LQHM3ADX.js → chunk-33JPVN33.js} +11 -6
  4. package/dist/{chunk-YSRYWZCQ.cjs → chunk-36K225SE.cjs} +9 -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-QG5T7YQ5.js → chunk-OYQJQE5R.js} +5 -5
  15. package/dist/{chunk-5RGX4DWF.js → chunk-SGGQ6XB2.js} +46 -14
  16. package/dist/{chunk-UYFTXD4P.js → chunk-T6K46DGW.js} +1 -1
  17. package/dist/{chunk-AUQFA7EE.cjs → chunk-VSIVT5RT.cjs} +11 -6
  18. package/dist/{chunk-H6M6L26S.cjs → chunk-VZIBHQC7.cjs} +2 -2
  19. package/dist/{chunk-EA3SIHYT.js → chunk-WYNM5ZWY.js} +84 -1
  20. package/dist/{chunk-5DDHO5Z7.cjs → chunk-XWGSREI5.cjs} +46 -14
  21. package/dist/class-validator.cjs +13 -8
  22. package/dist/class-validator.d.cts +5 -2
  23. package/dist/class-validator.d.ts +5 -2
  24. package/dist/class-validator.js +12 -7
  25. package/dist/cli.js +1 -1
  26. package/dist/cnic.cjs +11 -3
  27. package/dist/cnic.d.cts +80 -3
  28. package/dist/cnic.d.ts +80 -3
  29. package/dist/cnic.js +1 -1
  30. package/dist/incometax.cjs +6 -6
  31. package/dist/incometax.d.cts +51 -7
  32. package/dist/incometax.d.ts +51 -7
  33. package/dist/incometax.js +1 -1
  34. package/dist/index.cjs +56 -44
  35. package/dist/index.d.cts +4 -4
  36. package/dist/index.d.ts +4 -4
  37. package/dist/index.js +9 -9
  38. package/dist/input.cjs +8 -8
  39. package/dist/input.js +2 -2
  40. package/dist/joi.cjs +7 -7
  41. package/dist/joi.d.cts +1 -1
  42. package/dist/joi.d.ts +1 -1
  43. package/dist/joi.js +6 -6
  44. package/dist/numbers.cjs +5 -5
  45. package/dist/numbers.d.cts +28 -5
  46. package/dist/numbers.d.ts +28 -5
  47. package/dist/numbers.js +1 -1
  48. package/dist/quality.cjs +5 -5
  49. package/dist/quality.js +2 -2
  50. package/dist/raast.cjs +5 -5
  51. package/dist/raast.d.cts +17 -6
  52. package/dist/raast.d.ts +17 -6
  53. package/dist/raast.js +1 -1
  54. package/dist/{rules-GxgPiVws.d.cts → rules-GEELAOfb.d.cts} +5 -0
  55. package/dist/{rules-GxgPiVws.d.ts → rules-GEELAOfb.d.ts} +5 -0
  56. package/dist/superstruct.cjs +7 -7
  57. package/dist/superstruct.d.cts +1 -1
  58. package/dist/superstruct.d.ts +1 -1
  59. package/dist/superstruct.js +6 -6
  60. package/dist/tax.cjs +5 -5
  61. package/dist/tax.d.cts +8 -2
  62. package/dist/tax.d.ts +8 -2
  63. package/dist/tax.js +2 -2
  64. package/dist/text.cjs +13 -9
  65. package/dist/text.d.cts +40 -4
  66. package/dist/text.d.ts +40 -4
  67. package/dist/text.js +1 -1
  68. package/dist/valibot.cjs +13 -7
  69. package/dist/valibot.d.cts +1 -1
  70. package/dist/valibot.d.ts +1 -1
  71. package/dist/valibot.js +12 -6
  72. package/dist/words.d.cts +4 -1
  73. package/dist/words.d.ts +4 -1
  74. package/dist/yup.cjs +7 -7
  75. package/dist/yup.d.cts +1 -1
  76. package/dist/yup.d.ts +1 -1
  77. package/dist/yup.js +6 -6
  78. package/dist/zod.cjs +9 -7
  79. package/dist/zod.d.cts +1 -1
  80. package/dist/zod.d.ts +1 -1
  81. package/dist/zod.js +8 -6
  82. package/package.json +1 -1
  83. package/dist/chunk-EEVNLTB4.js +0 -32
  84. package/dist/chunk-HTCSHHOR.cjs +0 -35
@@ -1,16 +1,16 @@
1
- import { RULES } from './chunk-QG5T7YQ5.js';
1
+ import { RULES } from './chunk-OYQJQE5R.js';
2
2
  import './chunk-S274QFFB.js';
3
- import './chunk-UYFTXD4P.js';
4
- import './chunk-CEPNSHIC.js';
3
+ import './chunk-T6K46DGW.js';
4
+ import './chunk-3OCMTNQ7.js';
5
5
  import './chunk-RZQJAZKC.js';
6
6
  import './chunk-IBZPJS4H.js';
7
7
  import './chunk-V2XE3NCG.js';
8
- import './chunk-LQHM3ADX.js';
8
+ import './chunk-33JPVN33.js';
9
9
  import './chunk-P7LVE2TF.js';
10
10
  import './chunk-E6HSKRAE.js';
11
11
  import './chunk-B7DOQ5QF.js';
12
12
  import './chunk-33QMFE2Z.js';
13
- import './chunk-EEVNLTB4.js';
13
+ import './chunk-CKCOK6X4.js';
14
14
  import './chunk-NDW52ZK3.js';
15
15
  import './chunk-XOTCIXY6.js';
16
16
  import './chunk-E2XU6NOW.js';
@@ -20,13 +20,18 @@ import { registerDecorator } from 'class-validator';
20
20
  function decorator(name) {
21
21
  const rule = RULES[name];
22
22
  return (options = {}) => (target, propertyName) => {
23
+ const { services, ...validationOptions } = options;
24
+ const ruleOptions = { services: services === true };
23
25
  registerDecorator({
24
26
  name: `pk-${name}`,
25
27
  target: target.constructor,
26
28
  propertyName,
27
- options: { ...options, message: options.message ?? rule.message },
29
+ options: {
30
+ ...validationOptions,
31
+ message: options.message ?? rule.message
32
+ },
28
33
  validator: {
29
- validate: (value) => typeof value === "string" && rule.test(value)
34
+ validate: (value) => typeof value === "string" && rule.test(value, ruleOptions)
30
35
  }
31
36
  });
32
37
  };
package/dist/cli.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import { normalizeRomanUrdu, formatHijri, toHijri, formatPKR, formatLakh, parseAddress, getCityByPostalCode, getPostalCode, getProvince, getBankFromIBAN, validateIBAN, analyzePhone, validatePhone, validateCNIC } from 'pakdatakit';
3
3
 
4
4
  // package.json
5
- var version = "2.6.0";
5
+ var version = "2.7.0";
6
6
  var EXIT_OK = 0;
7
7
  var EXIT_NEGATIVE = 1;
8
8
  var EXIT_USAGE = 2;
package/dist/cnic.cjs CHANGED
@@ -1,15 +1,23 @@
1
1
  'use strict';
2
2
 
3
- var chunkHTCSHHOR_cjs = require('./chunk-HTCSHHOR.cjs');
3
+ var chunk7NTUEHQV_cjs = require('./chunk-7NTUEHQV.cjs');
4
4
  require('./chunk-VPBMIYO2.cjs');
5
5
 
6
6
 
7
7
 
8
+ Object.defineProperty(exports, "findCNICs", {
9
+ enumerable: true,
10
+ get: function () { return chunk7NTUEHQV_cjs.findCNICs; }
11
+ });
8
12
  Object.defineProperty(exports, "getCNICInfo", {
9
13
  enumerable: true,
10
- get: function () { return chunkHTCSHHOR_cjs.getCNICInfo; }
14
+ get: function () { return chunk7NTUEHQV_cjs.getCNICInfo; }
15
+ });
16
+ Object.defineProperty(exports, "maskCNICs", {
17
+ enumerable: true,
18
+ get: function () { return chunk7NTUEHQV_cjs.maskCNICs; }
11
19
  });
12
20
  Object.defineProperty(exports, "validateCNIC", {
13
21
  enumerable: true,
14
- get: function () { return chunkHTCSHHOR_cjs.validateCNIC; }
22
+ get: function () { return chunk7NTUEHQV_cjs.validateCNIC; }
15
23
  });
package/dist/cnic.d.cts CHANGED
@@ -1,5 +1,6 @@
1
1
  /**
2
- * Validates a Pakistani CNIC number.
2
+ * Validates the format of a Pakistani CNIC number: 13 digits, in 5-7-1
3
+ * groups or together, starting with a province code from 1 to 8.
3
4
  *
4
5
  * Accepts `3520212345671`, `35202-1234567-1`, `35202 1234567 1` and Urdu digits.
5
6
  * Separators must sit between the 5-7-1 digit groups and be used consistently.
@@ -31,6 +32,82 @@ interface CNICInfo {
31
32
  * @returns Decoded information, or `null` if the CNIC is invalid
32
33
  */
33
34
  declare function getCNICInfo(cnic: string): CNICInfo | null;
35
+ /**
36
+ * A CNIC that {@link findCNICs} found in free text: as written, its digits,
37
+ * its formatted form and where it is in the text.
38
+ */
39
+ interface CNICMatch {
40
+ /** The text as written, e.g. `35202 1234567-1` or with Urdu digits. */
41
+ raw: string;
42
+ /** The 13 digits, in ASCII. */
43
+ digits: string;
44
+ /** The CNIC in `#####-#######-#` form. */
45
+ formatted: string;
46
+ /** Offset of the first character in the text (UTF-16 code units). */
47
+ start: number;
48
+ /** Offset just after the last character (UTF-16 code units). */
49
+ end: number;
50
+ }
51
+ /**
52
+ * Finds CNIC numbers in free text, such as a chat message, a note or an
53
+ * uploaded document, for example to mask them before logging.
54
+ *
55
+ * A match is 13 digits whose first digit is a province code (1-8), written
56
+ * together or in 5-7-1 groups with a hyphen, dash, dot or space between the
57
+ * groups (the two separators may differ). Digits may be ASCII, Urdu or
58
+ * Arabic-Indic, even mixed. A match never starts or ends next to another
59
+ * digit, so a longer number is not cut into a CNIC.
60
+ *
61
+ * This is looser than {@link validateCNIC}, which needs the same separator
62
+ * twice: text is written carelessly. It is a pattern match, so any other
63
+ * 13-digit number that starts with 1-8 (an account or order number, say) also
64
+ * matches.
65
+ *
66
+ * @example
67
+ * findCNICs('CNIC: 35202-1234567-1, phone 0300-1234567');
68
+ * // [{ raw: '35202-1234567-1', digits: '3520212345671',
69
+ * // formatted: '35202-1234567-1', start: 6, end: 21 }]
70
+ *
71
+ * @param text - Any text
72
+ * @returns The matches in order, or `[]` (also for a value that is not a
73
+ * string). Never throws.
74
+ */
75
+ declare function findCNICs(text: string): CNICMatch[];
76
+ /** Options for {@link maskCNICs}. */
77
+ interface MaskCNICsOptions {
78
+ /** What each digit is replaced with. Default `'X'`. */
79
+ mask?: string;
80
+ }
81
+ /**
82
+ * What {@link maskCNICs} returns: the text with every CNIC's digits masked,
83
+ * and how many CNICs it masked.
84
+ */
85
+ interface MaskedText {
86
+ /** The text with every CNIC's digits masked; separators are kept. */
87
+ text: string;
88
+ /** How many CNICs were masked. */
89
+ count: number;
90
+ }
91
+ /**
92
+ * Masks every CNIC in free text, as found by {@link findCNICs}: each digit
93
+ * becomes the mask and the separators stay, so `35202-1234567-1` becomes
94
+ * `XXXXX-XXXXXXX-X`. The rest of the text is unchanged.
95
+ *
96
+ * Like {@link findCNICs}, it also masks any other 13-digit number that
97
+ * starts with 1-8.
98
+ *
99
+ * @example
100
+ * maskCNICs('My CNIC is 35202-1234567-1');
101
+ * // { text: 'My CNIC is XXXXX-XXXXXXX-X', count: 1 }
102
+ * maskCNICs('35202 1234567 1', { mask: '*' });
103
+ * // { text: '***** ******* *', count: 1 }
104
+ *
105
+ * @param text - Any text
106
+ * @param options - `mask`: the string that replaces each digit
107
+ * @returns The masked text and the number of CNICs masked. A value that is
108
+ * not a string gives `{ text: '', count: 0 }`. Never throws.
109
+ */
110
+ declare function maskCNICs(text: string, options?: MaskCNICsOptions): MaskedText;
34
111
 
35
- export { getCNICInfo, validateCNIC };
36
- export type { CNICInfo };
112
+ export { findCNICs, getCNICInfo, maskCNICs, validateCNIC };
113
+ export type { CNICInfo, CNICMatch, MaskCNICsOptions, MaskedText };
package/dist/cnic.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  /**
2
- * Validates a Pakistani CNIC number.
2
+ * Validates the format of a Pakistani CNIC number: 13 digits, in 5-7-1
3
+ * groups or together, starting with a province code from 1 to 8.
3
4
  *
4
5
  * Accepts `3520212345671`, `35202-1234567-1`, `35202 1234567 1` and Urdu digits.
5
6
  * Separators must sit between the 5-7-1 digit groups and be used consistently.
@@ -31,6 +32,82 @@ interface CNICInfo {
31
32
  * @returns Decoded information, or `null` if the CNIC is invalid
32
33
  */
33
34
  declare function getCNICInfo(cnic: string): CNICInfo | null;
35
+ /**
36
+ * A CNIC that {@link findCNICs} found in free text: as written, its digits,
37
+ * its formatted form and where it is in the text.
38
+ */
39
+ interface CNICMatch {
40
+ /** The text as written, e.g. `35202 1234567-1` or with Urdu digits. */
41
+ raw: string;
42
+ /** The 13 digits, in ASCII. */
43
+ digits: string;
44
+ /** The CNIC in `#####-#######-#` form. */
45
+ formatted: string;
46
+ /** Offset of the first character in the text (UTF-16 code units). */
47
+ start: number;
48
+ /** Offset just after the last character (UTF-16 code units). */
49
+ end: number;
50
+ }
51
+ /**
52
+ * Finds CNIC numbers in free text, such as a chat message, a note or an
53
+ * uploaded document, for example to mask them before logging.
54
+ *
55
+ * A match is 13 digits whose first digit is a province code (1-8), written
56
+ * together or in 5-7-1 groups with a hyphen, dash, dot or space between the
57
+ * groups (the two separators may differ). Digits may be ASCII, Urdu or
58
+ * Arabic-Indic, even mixed. A match never starts or ends next to another
59
+ * digit, so a longer number is not cut into a CNIC.
60
+ *
61
+ * This is looser than {@link validateCNIC}, which needs the same separator
62
+ * twice: text is written carelessly. It is a pattern match, so any other
63
+ * 13-digit number that starts with 1-8 (an account or order number, say) also
64
+ * matches.
65
+ *
66
+ * @example
67
+ * findCNICs('CNIC: 35202-1234567-1, phone 0300-1234567');
68
+ * // [{ raw: '35202-1234567-1', digits: '3520212345671',
69
+ * // formatted: '35202-1234567-1', start: 6, end: 21 }]
70
+ *
71
+ * @param text - Any text
72
+ * @returns The matches in order, or `[]` (also for a value that is not a
73
+ * string). Never throws.
74
+ */
75
+ declare function findCNICs(text: string): CNICMatch[];
76
+ /** Options for {@link maskCNICs}. */
77
+ interface MaskCNICsOptions {
78
+ /** What each digit is replaced with. Default `'X'`. */
79
+ mask?: string;
80
+ }
81
+ /**
82
+ * What {@link maskCNICs} returns: the text with every CNIC's digits masked,
83
+ * and how many CNICs it masked.
84
+ */
85
+ interface MaskedText {
86
+ /** The text with every CNIC's digits masked; separators are kept. */
87
+ text: string;
88
+ /** How many CNICs were masked. */
89
+ count: number;
90
+ }
91
+ /**
92
+ * Masks every CNIC in free text, as found by {@link findCNICs}: each digit
93
+ * becomes the mask and the separators stay, so `35202-1234567-1` becomes
94
+ * `XXXXX-XXXXXXX-X`. The rest of the text is unchanged.
95
+ *
96
+ * Like {@link findCNICs}, it also masks any other 13-digit number that
97
+ * starts with 1-8.
98
+ *
99
+ * @example
100
+ * maskCNICs('My CNIC is 35202-1234567-1');
101
+ * // { text: 'My CNIC is XXXXX-XXXXXXX-X', count: 1 }
102
+ * maskCNICs('35202 1234567 1', { mask: '*' });
103
+ * // { text: '***** ******* *', count: 1 }
104
+ *
105
+ * @param text - Any text
106
+ * @param options - `mask`: the string that replaces each digit
107
+ * @returns The masked text and the number of CNICs masked. A value that is
108
+ * not a string gives `{ text: '', count: 0 }`. Never throws.
109
+ */
110
+ declare function maskCNICs(text: string, options?: MaskCNICsOptions): MaskedText;
34
111
 
35
- export { getCNICInfo, validateCNIC };
36
- export type { CNICInfo };
112
+ export { findCNICs, getCNICInfo, maskCNICs, validateCNIC };
113
+ export type { CNICInfo, CNICMatch, MaskCNICsOptions, MaskedText };
package/dist/cnic.js CHANGED
@@ -1,2 +1,2 @@
1
- export { getCNICInfo, validateCNIC } from './chunk-EEVNLTB4.js';
1
+ export { findCNICs, getCNICInfo, maskCNICs, validateCNIC } from './chunk-CKCOK6X4.js';
2
2
  import './chunk-ENQ7O7VW.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';