@equisoft/tax-us 0.0.1-snapshot.20250723132536

package/.eslintrc.json

@@ -0,0 +1,42 @@
+{
+  "extends": [
+    "@equisoft/eslint-config-typescript",
+    "plugin:import/typescript"
+  ],
+  "settings": {
+    "import/resolver": {
+      "typescript": {
+        "project": [
+          "tsconfig.json",
+          "tests/tsconfig.json"
+        ]
+      }
+    }
+  },
+  "rules": {
+    "import/no-extraneous-dependencies": [
+      "error",
+      {
+        "devDependencies": [
+          "/*.js",
+          "test/**/*",
+          "**/*.test.{js,jsx,ts,tsx}",
+          "**/*.spec.{js,jsx,ts,tsx}"
+        ]
+      }
+    ]
+  },
+  "overrides": [
+    {
+      "files": ["test/**/*"],
+      "rules": {
+        "import/no-unresolved": [
+          "error",
+          {
+            "ignore": ["^~/"]
+          }
+        ]
+      }
+    }
+  ]
+}

package/.tool-versions

@@ -0,0 +1 @@
+nodejs 22.17.0

package/Makefile

@@ -0,0 +1,28 @@
+BASE_DIR := $(dir $(realpath $(firstword $(MAKEFILE_LIST))))
+OS_TYPE := $(shell uname -s)
+
+.PHONY: all
+all: setup check compile test
+
+.PHONY: setup
+setup:
+	@asdf plugin update nodejs || (asdf plugin add nodejs && ~/.asdf/plugins/nodejs/bin/import-release-team-keyring)
+	@asdf plugin update yarn || asdf plugin add yarn
+	@asdf install
+	@yarn --cwd "$(BASE_DIR)"
+
+.PHONY: check
+check:
+	@yarn eslint
+
+.PHONY: dev
+dev:
+	@yarn dev:watch
+
+.PHONY: compile
+compile:
+	@yarn build
+
+.PHONY: test
+test:
+	@yarn test

package/README.md

@@ -0,0 +1,113 @@
+# tax-us
+
+## Description
+
+The `tax-us` library contains up-to-date provincial and federal tax data and calculation functions.
+
+We built it so that we would have a single source of truth for taxes data across all of our applications.  The initial version is derived from code from the `fna-engine` and `kronos-fna` repositories.
+
+As we develop and update `tax-us`, we will try to make it as application-agnostic as possible.
+
+## Installation
+
+Using `npm` : 
+```
+npm install @equisoft/tax-us --save
+```
+
+Using `yarn` :
+```
+yarn add @equisoft/tax-us
+```
+
+## Versions
+
+The `major` portion of the library version is named according to the year of the dataset it contains. There could be breaking changes (such as modifications to the data structure) in both `major` and `minor` updates.
+
+Updates at the `patch` level are reserved for bug fixes, non-breaking changes and minor improvements.
+
+We suggest you lock the library dependency to the `minor` version and execute exhaustive testing before migrating to a new version to avoid unintentional regression.
+
+```javascript
+  "dependencies": {
+    "@equisoft/tax-us": "^2018.0.4",
+  },
+```
+
+
+## Usage
+
+To use the library, we recommend you start by going through the **Modules** list (see below) to locate the data set or function you are looking for.
+
+Once you know where your target data or function is located, simply import the module then access it directly in the code.
+
+```javascript
+import { PENSION } from '@equisoft/tax-us';
+
+const { OAS, CPP } = PENSION;
+
+console.log("OAS maximum age: ", OAS.MAX_AGE); // 70
+```
+
+
+## Modules
+
+### `INVESTMENTS`
+
+Data relating to registered investments accounts.
+
+```
+INVESTMENTS
+  |--LifeIncomeFund
+  |--RegisteredRetirementIncomeFund
+  |--RegisteredRetirementSavingsPlan
+  |--TaxFreeSavingsAccount
+```
+
+### `PENSION`
+
+Data relating to federal and provincial pension plans.
+
+```
+PENSION
+  |--CanadaPensionPlan
+  |--OldAgeSecurity
+  |--PublicPensionPlan
+  |--QuebecPensionPlan
+  |--SupplementalPensionPlan
+```
+
+### `TAXES`
+
+Data relating to federal and provincial income taxes and social charges.
+
+```
+TAXES
+  |--DividendCredit
+  |--EmploymentInsurance
+  |--IncomeTax
+  |--QuebecParentalInsurancePlan
+```
+
+### `MISC`
+
+Complementary data useful in a tax calculation context.
+
+```
+MISC
+  |--ConsumerPriceIndex
+  |--IPFStats
+  |--LifeExpectancy
+```
+
+
+## Development
+
+This library is maintained by the _Equisoft/plan_ product team in Quebec City, QC, Canada.
+
+We strongly value [inner source](https://en.wikipedia.org/wiki/Inner_source) practices within Equisoft and encourage contributors external to the FNA team to submit issues (including feature requests) and pull requests to the repository. 
+
+## Release
+
+Versions of this package are built by Github Actions.
+All you need to do is create a new tag and release using the Github Interface.

package/RELEASE.md

@@ -0,0 +1,29 @@
+# Upgrade Steps
+
+-
+-
+
+# Breaking Changes
+
+-
+-
+
+# New Features
+
+- 
+-
+
+# Bug Fixes
+
+- 
+-
+
+# Improvements
+
+-
+-
+
+# Other Changes
+
+-
+-

package/babel.config.js

@@ -0,0 +1 @@
+module.exports = {presets: ['@babel/preset-env', '@babel/preset-typescript']}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './investments';
+export * from './misc';
+export * from './pension';
+export * from './taxes';
+export * from './utils';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./investments"), exports);
+__exportStar(require("./misc"), exports);
+__exportStar(require("./pension"), exports);
+__exportStar(require("./taxes"), exports);
+__exportStar(require("./utils"), exports);

package/dist/investments/index.d.ts

@@ -0,0 +1,6 @@
+export * from './life-income-fund';
+export * from './registered-retirement-income-fund';
+export * from './registered-retirement-savings-plan';
+export * from './tax-free-savings-account';
+export * from './non-registered-savings-plan';
+export * from './registered-education-savings-plan';

package/dist/investments/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./life-income-fund"), exports);
+__exportStar(require("./registered-retirement-income-fund"), exports);
+__exportStar(require("./registered-retirement-savings-plan"), exports);
+__exportStar(require("./tax-free-savings-account"), exports);
+__exportStar(require("./non-registered-savings-plan"), exports);
+__exportStar(require("./registered-education-savings-plan"), exports);

package/dist/investments/life-income-fund.d.ts

@@ -0,0 +1,11 @@
+import { ByProvince, FederalCode, ProvinceCode } from '../misc';
+interface MaxWithdrawalPctByAge {
+    [key: number]: number;
+}
+export declare const province1MaxWithdrawalPct: MaxWithdrawalPctByAge;
+export declare const province2MaxWithdrawalPct: MaxWithdrawalPctByAge;
+export declare const othersMaxWithdrawalPct: MaxWithdrawalPctByAge;
+export declare const federalMaxWithdrawalPct: MaxWithdrawalPctByAge;
+export declare function getMaxWithdrawalPct(jurisdiction: ProvinceCode | FederalCode, age: number): number;
+export declare const YMPEUnlockingSmallBalance: ByProvince<number>;
+export {};

package/dist/investments/life-income-fund.js

@@ -0,0 +1,291 @@
+"use strict";
+// tslint:disable:max-line-length
+/*
+Sources
+    Provincial: https://www.empire.ca/sites/default/files/2024-02/INV-996A-LIFMinMaxWithdrawalPercentages-EN-web.pdf
+                https://ca.rbcwealthmanagement.com/documents/1647873/2467026/2023+-+Registered+Plan+Minimums+%26+Maximums.pdf/f26cb471-e962-47cd-9033-fc1d9c34663e
+    Federal & Territories & PEI : http://www.osfi-bsif.gc.ca/Eng/pp-rr/faq/Pages/lif-frv.aspx
+
+Conversion for Federal, Territories and PEI
+    Because the age of reference is at the end of the previous year, we must shift the reference rate
+    by one year to reflect the calculation engine which uses the age at the end of the current year.
+    i.e. : Gov has a rate for age 60 but we use it for age 61.
+
+Revised
+    2024-12-23
+*/
+// tslint:enable:max-line-length
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YMPEUnlockingSmallBalance = exports.federalMaxWithdrawalPct = exports.othersMaxWithdrawalPct = exports.province2MaxWithdrawalPct = exports.province1MaxWithdrawalPct = void 0;
+exports.getMaxWithdrawalPct = getMaxWithdrawalPct;
+const utils_1 = require("../utils");
+/* Alberta (AB), British Columbia (BC), Ontario (ON), New Brunswick (NB),
+ Newfoundland and Labrador (NL), Saskatchewan (SK)
+*/
+exports.province1MaxWithdrawalPct = {
+    51: 0.0627,
+    52: 0.0631,
+    53: 0.0635,
+    54: 0.0640,
+    55: 0.0645,
+    56: 0.0651,
+    57: 0.0657,
+    58: 0.0663,
+    59: 0.0670,
+    60: 0.0677,
+    61: 0.0685,
+    62: 0.0694,
+    63: 0.0704,
+    64: 0.0714,
+    65: 0.0726,
+    66: 0.0738,
+    67: 0.0752,
+    68: 0.0767,
+    69: 0.0783,
+    70: 0.0802,
+    71: 0.0822,
+    72: 0.0845,
+    73: 0.0871,
+    74: 0.0900,
+    75: 0.0934,
+    76: 0.0971,
+    77: 0.1015,
+    78: 0.1066,
+    79: 0.1125,
+    80: 0.1196,
+    81: 0.1282,
+    82: 0.1387,
+    83: 0.1519,
+    84: 0.1690,
+    85: 0.1919,
+    86: 0.2240,
+    87: 0.2723,
+    88: 0.3529,
+    89: 0.5146,
+    90: 1,
+};
+// Quebec (QC), Manitoba (MB), Nova Scotia (NS)
+exports.province2MaxWithdrawalPct = {
+    51: 0.0610,
+    52: 0.0610,
+    53: 0.0610,
+    54: 0.0610,
+    55: 0.0610,
+    56: 0.0640,
+    57: 0.0650,
+    58: 0.0650,
+    59: 0.0660,
+    60: 0.0670,
+    61: 0.0670,
+    62: 0.0680,
+    63: 0.0690,
+    64: 0.0700,
+    65: 0.0710,
+    66: 0.0720,
+    67: 0.0730,
+    68: 0.0740,
+    69: 0.0760,
+    70: 0.0770,
+    71: 0.0790,
+    72: 0.0810,
+    73: 0.0830,
+    74: 0.0850,
+    75: 0.0880,
+    76: 0.0910,
+    77: 0.0940,
+    78: 0.0980,
+    79: 0.1030,
+    80: 0.1080,
+    81: 0.1150,
+    82: 0.1210,
+    83: 0.1290,
+    84: 0.1380,
+    85: 0.1480,
+    86: 0.1600,
+    87: 0.1730,
+    88: 0.1890,
+    89: 0.2000,
+};
+// Others: Northwest Territories (NT), Nunavut (NU), Prince Edward Island (PE), Yukon (YT)
+exports.othersMaxWithdrawalPct = {
+    20: 0.044298,
+    21: 0.04435,
+    22: 0.044406,
+    23: 0.044465,
+    24: 0.044528,
+    25: 0.044594,
+    26: 0.044665,
+    27: 0.04474,
+    28: 0.044821,
+    29: 0.044906,
+    30: 0.044996,
+    31: 0.045093,
+    32: 0.045196,
+    33: 0.045305,
+    34: 0.045422,
+    35: 0.045546,
+    36: 0.045679,
+    37: 0.04582,
+    38: 0.045971,
+    39: 0.046132,
+    40: 0.046304,
+    41: 0.046487,
+    42: 0.046683,
+    43: 0.046893,
+    44: 0.047117,
+    45: 0.047357,
+    46: 0.047614,
+    47: 0.04789,
+    48: 0.048186,
+    49: 0.048503,
+    50: 0.048844,
+    51: 0.049211,
+    52: 0.049606,
+    53: 0.050032,
+    54: 0.050491,
+    55: 0.050987,
+    56: 0.051524,
+    57: 0.052105,
+    58: 0.052736,
+    59: 0.053421,
+    60: 0.054168,
+    61: 0.054982,
+    62: 0.055872,
+    63: 0.056848,
+    64: 0.05792,
+    65: 0.059101,
+    66: 0.060407,
+    67: 0.061856,
+    68: 0.063469,
+    69: 0.065275,
+    70: 0.067303,
+    71: 0.069597,
+    72: 0.072204,
+    73: 0.07519,
+    74: 0.078638,
+    75: 0.082655,
+    76: 0.087258,
+    77: 0.092582,
+    78: 0.098807,
+    79: 0.106178,
+    80: 0.115041,
+    81: 0.125892,
+    82: 0.139476,
+    83: 0.156966,
+    84: 0.180313,
+    85: 0.213033,
+    86: 0.262155,
+    87: 0.344082,
+    88: 0.508019,
+    89: 1,
+};
+// Federal
+exports.federalMaxWithdrawalPct = {
+    20: 0.044298,
+    21: 0.04435,
+    22: 0.044406,
+    23: 0.044465,
+    24: 0.044528,
+    25: 0.044594,
+    26: 0.044665,
+    27: 0.04474,
+    28: 0.044821,
+    29: 0.044906,
+    30: 0.044996,
+    31: 0.045093,
+    32: 0.045196,
+    33: 0.045305,
+    34: 0.045422,
+    35: 0.045546,
+    36: 0.045679,
+    37: 0.04582,
+    38: 0.045971,
+    39: 0.046132,
+    40: 0.046304,
+    41: 0.046487,
+    42: 0.046683,
+    43: 0.046893,
+    44: 0.047117,
+    45: 0.047357,
+    46: 0.047614,
+    47: 0.04789,
+    48: 0.048186,
+    49: 0.048503,
+    50: 0.048844,
+    51: 0.049211,
+    52: 0.049606,
+    53: 0.050032,
+    54: 0.050491,
+    55: 0.050987,
+    56: 0.051524,
+    57: 0.052105,
+    58: 0.052736,
+    59: 0.053421,
+    60: 0.054168,
+    61: 0.054982,
+    62: 0.055872,
+    63: 0.056848,
+    64: 0.05792,
+    65: 0.059101,
+    66: 0.060407,
+    67: 0.061856,
+    68: 0.063469,
+    69: 0.065275,
+    70: 0.067303,
+    71: 0.069597,
+    72: 0.072204,
+    73: 0.07519,
+    74: 0.078638,
+    75: 0.082655,
+    76: 0.087258,
+    77: 0.092582,
+    78: 0.098807,
+    79: 0.106178,
+    80: 0.115041,
+    81: 0.125892,
+    82: 0.139476,
+    83: 0.156966,
+    84: 0.180313,
+    85: 0.213033,
+    86: 0.262155,
+    87: 0.344082,
+    88: 0.508019,
+    89: 1,
+};
+function getMaxWithdrawalPct(jurisdiction, age) {
+    const getAgeLimitByProvinceGroup = (group, biggest = true) => ((biggest)
+        ? Math.max(...Object.keys(group).map(Number))
+        : Math.min(...Object.keys(group).map(Number)));
+    switch (jurisdiction) {
+        case 'AB':
+        case 'BC':
+        case 'ON':
+        case 'NB':
+        case 'NL':
+        case 'SK':
+            return exports.province1MaxWithdrawalPct[(0, utils_1.clamp)(age, getAgeLimitByProvinceGroup(exports.province1MaxWithdrawalPct, false), getAgeLimitByProvinceGroup(exports.province1MaxWithdrawalPct))];
+        case 'QC':
+        case 'MB':
+        case 'NS':
+            return exports.province2MaxWithdrawalPct[(0, utils_1.clamp)(age, getAgeLimitByProvinceGroup(exports.province2MaxWithdrawalPct, false), getAgeLimitByProvinceGroup(exports.province2MaxWithdrawalPct))];
+        case 'CA':
+            return exports.federalMaxWithdrawalPct[(0, utils_1.clamp)(age, getAgeLimitByProvinceGroup(exports.federalMaxWithdrawalPct, false), getAgeLimitByProvinceGroup(exports.federalMaxWithdrawalPct))];
+        default:
+            return exports.othersMaxWithdrawalPct[(0, utils_1.clamp)(age, getAgeLimitByProvinceGroup(exports.othersMaxWithdrawalPct, false), getAgeLimitByProvinceGroup(exports.othersMaxWithdrawalPct))];
+    }
+}
+exports.YMPEUnlockingSmallBalance = {
+    AB: 0.4,
+    BC: 0.4,
+    MB: 0.4,
+    NB: 0.4,
+    NL: 0.4,
+    NS: 0.5,
+    PE: 0.4,
+    ON: 0.4,
+    QC: 0.4,
+    SK: 0.4,
+    NT: 0.4,
+    NU: 0.4,
+    YT: 0.4,
+};

package/dist/investments/non-registered-savings-plan.d.ts

@@ -0,0 +1,3 @@
+import { Rate } from '../taxes';
+export declare const CAPITAL_GAINS_BRACKETS: Rate[];
+export declare function getCapitalGainsTaxableAmount(totalCapitalGains: number): number;

package/dist/investments/non-registered-savings-plan.js

@@ -0,0 +1,30 @@
+"use strict";
+// tslint:disable:max-line-length
+/*
+Sources
+    https://www.canada.ca/en/department-finance/news/2024/06/capital-gains-inclusion-rate.html
+    https://www.revenuquebec.ca/en/press-room/tax-news/details/2024-06-19/capital-gains-inclusion-rate-increase-1/
+
+Revised
+    2024-12-30
+*/
+// tslint:enable:max-line-length
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPITAL_GAINS_BRACKETS = void 0;
+exports.getCapitalGainsTaxableAmount = getCapitalGainsTaxableAmount;
+exports.CAPITAL_GAINS_BRACKETS = [
+    {
+        FROM: 0,
+        TO: Infinity,
+        RATE: 0.5,
+    },
+];
+function getCapitalGainsTaxableAmount(totalCapitalGains) {
+    return exports.CAPITAL_GAINS_BRACKETS.reduce((taxableAmount, currentBracket) => {
+        const currentBracketRate = currentBracket.RATE;
+        const bracketTaxableAmount = Math.min(totalCapitalGains, currentBracket.TO);
+        if (bracketTaxableAmount <= currentBracket.FROM)
+            return taxableAmount;
+        return taxableAmount + ((bracketTaxableAmount - currentBracket.FROM) * currentBracketRate);
+    }, 0);
+}

package/dist/investments/registered-education-savings-plan/beneficiary.d.ts

@@ -0,0 +1,4 @@
+export interface Beneficiary {
+    MAX_AGE: number;
+}
+export declare const Beneficiary: Beneficiary;

package/dist/investments/registered-education-savings-plan/beneficiary.js

@@ -0,0 +1,16 @@
+"use strict";
+/*
+ Sources
+ https://www150.statcan.gc.ca/t1/tbl1/en/tv.action?pid=3710004501&cubeTimeFrame.startYear=2024+%2F+2025&cubeTimeFrame.endYear=2024+%2F+2025&referencePeriods=20240101%2C20240101
+
+ Revised data
+ 2024-09-04
+
+ Last updated
+ 2025-02-07
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Beneficiary = void 0;
+exports.Beneficiary = {
+    MAX_AGE: 35,
+};

package/dist/investments/registered-education-savings-plan/british-columbia-training-and-education-savings-grant.d.ts

@@ -0,0 +1,10 @@
+export interface BritishColumbiaTrainingAndEducationSavingsGrant {
+    BENEFICIARY_AGE_ALLOCATION: number;
+    MAX_GRANT: number;
+    getTotalForAYear: (beneficiaryAge: number) => number;
+}
+export interface BritishColumbiaTrainingAndEducationSavingsGrantData {
+    BENEFICIARY_AGE_ALLOCATION: number;
+    MAX_GRANT: number;
+}
+export declare const BritishColumbiaTrainingAndEducationSavingsGrant: BritishColumbiaTrainingAndEducationSavingsGrant;

package/dist/investments/registered-education-savings-plan/british-columbia-training-and-education-savings-grant.js

@@ -0,0 +1,21 @@
+"use strict";
+/*
+ Sources
+ https://www.canada.ca/en/employment-social-development/services/student-financial-aid/education-savings/resp/resp-promoters/infocapsules/bc.html
+
+ Last updated
+ 2025-02-11
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BritishColumbiaTrainingAndEducationSavingsGrant = void 0;
+const BritishColumbiaTrainingAndEducationSavingsGrantData = {
+    BENEFICIARY_AGE_ALLOCATION: 6,
+    MAX_GRANT: 1200,
+};
+// Pour simplifier, on assume que si l'enfant a > 6ans, la subvention a déjà été allouée
+// Comme on peut l'allouer une seule fois, on la donne à 6ans
+const getTotalForAYear = (beneficiaryAge) => {
+    const { BENEFICIARY_AGE_ALLOCATION, MAX_GRANT } = BritishColumbiaTrainingAndEducationSavingsGrantData;
+    return beneficiaryAge === BENEFICIARY_AGE_ALLOCATION ? MAX_GRANT : 0;
+};
+exports.BritishColumbiaTrainingAndEducationSavingsGrant = Object.assign(Object.assign({}, BritishColumbiaTrainingAndEducationSavingsGrantData), { getTotalForAYear });

package/dist/investments/registered-education-savings-plan/canada-education-savings-grant.d.ts

@@ -0,0 +1,2 @@
+import { SavingsGrant } from './savings-grant';
+export declare const CanadaEducationSavingsGrant: SavingsGrant;