{"id":22538088,"url":"https://github.com/cfpb/student-debt-calculator","last_synced_at":"2025-10-31T08:44:04.332Z","repository":{"id":46281622,"uuid":"43752809","full_name":"cfpb/student-debt-calculator","owner":"cfpb","description":"Calculate student debt at graduation based on a wide array of possible inputs","archived":false,"fork":false,"pushed_at":"2022-12-08T17:39:54.000Z","size":647,"stargazers_count":7,"open_issues_count":2,"forks_count":7,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-07-15T22:57:09.884Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@cfpb/student-debt-calculator","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cfpb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-06T13:36:22.000Z","updated_at":"2022-12-21T16:06:02.000Z","dependencies_parsed_at":"2023-01-25T15:01:27.894Z","dependency_job_id":null,"html_url":"https://github.com/cfpb/student-debt-calculator","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/cfpb/student-debt-calculator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfpb%2Fstudent-debt-calculator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfpb%2Fstudent-debt-calculator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfpb%2Fstudent-debt-calculator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfpb%2Fstudent-debt-calculator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cfpb","download_url":"https://codeload.github.com/cfpb/student-debt-calculator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfpb%2Fstudent-debt-calculator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268557845,"owners_count":24269677,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-07T11:10:07.879Z","updated_at":"2025-10-31T08:44:04.248Z","avatar_url":"https://github.com/cfpb.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Student Debt Calculator\n\n[![Build Status](https://travis-ci.org/cfpb/student-debt-calculator.svg?branch=master)](https://travis-ci.org/cfpb/student-debt-calculator)\n\n\u003e A JavaScript package which calculates student debt at graduation based on a wide array of possible inputs.\n\nThis calculator does not simply calculate debt based on loans - given inputs of costs, grants, scholarships, personal savings, and loans, it can calculate how much of the annual cost of attendance is left to pay, total debt at graduation, and monthly payment at graduation, based on combined loans and given loan rates.\n\n**Currently in Beta**\n\n## Dependencies\n\nThe package runs on [node.js](http://nodejs.org/). It can be included in front-end projects as an npm package - see 'Installation' below.\n\n## Installation\n\n1. Install node.js\n2. Run `yarn add student-debt-calc`\n\n## Usage\n\nThe intent of the package is to allow developers to perform calculations of student debt based on a standard\nset of costs, grants, scholarships, loans, and a set of constants.\n\nThis package can be required and used as a function. It takes in an Object, refered to in this documentation\nas the \"financials Object\" or as `financials`. It returns an Object as well, formatted nearly identically to\nObject it was passed, with values based on a set of calculations.\n\nThe Object taken in as a parameter and the Object returned are essentially the same Object, with a variety\nof calculations and corrections applied, and with properties updated with new values.\n\nFor instance, here is a sample of a \"financials\" Object that can be passed to the calculator:\n\n```\nconst financials = {\n  tuitionFees: 10000,\n  roomBoard: 2000,\n  books: 1000,\n  transportation: 500,\n  otherExpenses: 250,\n  scholarships: 0,\n  pell: 0,\n  savings: 0,\n  family: 0,\n  perkins: 0,\n  staffSubsidized: 0,\n  staffUnsubsidized: 0,\n  institutionalLoan: 0,\n  privateLoan: 13750,\n  undergrad: true\n}\n```\n\n### The financials object\n\nThe object passed to `studentDebtCalculator` is used to set up the calculations. Each property has a default value, so properties whose value does not need to be changed from the default can be omitted. Below, we list all the properties used in the calculations. They are separated by category for ease of reading.\n\n#### Costs of Attendance\n\nThese values are all added together to get the cost of attendance. They are taken as separate values to match with the [Financial Aid Shopping Sheet](http://www2.ed.gov/policy/highered/guid/aid-offer/index.html).\n\n| Property                    | Type   | Description                        | Default value |\n| --------------------------- | ------ | ---------------------------------- | ------------- |\n| `financials.tuitionFees`    | number | The value of tuition and fees      | 0             |\n| `financials.roomBoard`      | number | The cost of room and board         | 0             |\n| `financials.books`          | number | The cost of books                  | 0             |\n| `financials.otherExpenses`  | number | The cost of miscellaneous expenses | 0             |\n| `financials.transportation` | number | The costs of transporation         | 0             |\n\n#### Grants and Scholarships\n\nThese values are deducted from cost of attendance.\n\n| Property                               | Type   | Description                                | Default value |\n| -------------------------------------- | ------ | ------------------------------------------ | ------------- |\n| `financials.scholarships`              | number | Total value of scholarships                | 0             |\n| `financials.pell`                      | number | Total value of Pell grants                 | 0             |\n| `financials.militaryTuitionAssistance` | number | Total value of Military Tuition Assistance | 0             |\n| `financials.GIBill`                    | number | Total value of GI Bill                     | 0             |\n\n#### Contributions\n\n| Property                | Type   | Description                                                                                                                                                                           | Default value |\n| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |\n| `financials.workstudy`  | number | Value of work-study                                                                                                                                                                   | 0             |\n| `financials.savings`    | number | Total personal savings to be spent to reduce annual cost of attendance                                                                                                                | 0             |\n| `financials.family`     | number | Total family contributions to be spent to reduce annual cost of attendance                                                                                                            | 0             |\n| `financials.parentPlus` | number | Federal Parent PLUS loan amount (the interest for this loan is not added to student loan totals, but is calculated as a monthly payment in outputs as `financials.loanMonthlyParent`) | 0             |\n\n#### Federal Loans\n\n| Property                        | Type   | Description                                | Default value |\n| ------------------------------- | ------ | ------------------------------------------ | ------------- |\n| `financials.perkins`            | number | Amount of federal Perkins loan             | 0             |\n| `financials.directSubsidized`   | number | Amount of federal Direct subsidized loan   | 0             |\n| `financials.directUnsubsidized` | number | Amount of federal Direct unsubsidized loan | 0             |\n| `financials.gradPlus`           | number | Amount of GradPlus loan                    | 0             |\n\n#### Private Loans\n\n| Property                       | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Default value      |\n| ------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |\n| `financials.institutionalLoan` | number | Amount of loan from institution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | 0                  |\n| `financials.privateLoan`       | number | Amount of private loan                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | 0                  |\n| `financials.privateLoanMulti`  | Array  | Used for multiple private loans. This array should contain objects, with each object having two properties - `amount` for the amount of the loan, `rate` for the loan's rate expressed as a decimal, `fees` for the loan's fees expressed as a decimal (based on percent of amount), and `deferPeriod` for the number of months the loan is deferred. Example: `[ { 'amount': 3000, 'rate': 0.061, 'fees': .01, deferPeriod': 6 }, { 'amount': 3600, 'rate': 0.059, 'fees': .0125, 'deferPeriod': 6 } ]` **Important note:** If `privateLoanMulti` is not empty, then the values of `privateLoanMulti` are used and the value of `privateLoan` is ignored! | `[]` (empty array) |\n\n#### Loan rates\n\n| Property                               | Type   | Description                                              | Default value |\n| -------------------------------------- | ------ | -------------------------------------------------------- | ------------- |\n| `financials.institutionalLoanRate`     | number | Loan rate for institutional loan, expressed as a decimal | 0.079         |\n| `financials.privateLoanRate`           | number | Loan rate for private loan, expressed as a decimal       | 0.079         |\n| `financials.perkinsRate`               | number | Loan rate for federal Perkins loans                      | 0.05          |\n| `financials.subsidizedRate`            | number | Loan rate for Direct subsidized loans                    | 0.0466        |\n| `financials.unsubsidizedRateUndergrad` | number | Loan rate for Direct unsubsidized undergratuate loans    | 0.0466        |\n| `financials.unsubsidizedRateGrad`      | number | Loan rate for Direct unsubsidized gratuate loans         | 0.0621        |\n| `financials.DLOriginationFee`          | number | Origination fee for Direct loans                         | 1.01073       |\n| `financials.gradPlusRate`              | number | Loan rate for GradPLUS loan                              | 0.0721        |\n| `financials.parentPlusRate`            | number | Loan rate for ParentPLUS loan                            | 0.0721        |\n| `financials.plusOriginationFee`        | number | Origination fee for Plus loans                           | 1.04292       |\n\n#### Maximums and Caps\n\nThese properties give the calculator caps and maximums on certain values.\n\n| Property                     | Type   | Description                        | Default value |\n| ---------------------------- | ------ | ---------------------------------- | ------------- |\n| `financials.perkinsUnderCap` | number | Cap on undergratuate Perkins loans | 5500          |\n| `financials.perkinsGradCap`  | number | Cap on graduate Perkins loans      | 8000          |\n\n### Outputs\n\nThese properties are added to the returned Object and would generally be\nconsidered the \"outputs\" for the package.\n\n| Property                       | Type   | Description                                                                                |\n| ------------------------------ | ------ | ------------------------------------------------------------------------------------------ |\n| `financials.firstYearNetCost`  | number | The cost of attendance minus grants and scholarships                                       |\n| `financials.moneyForCollege`   | number | The total of grants, scholarships, and loans                                               |\n| `financials.remainingCost`     | number | The costs of attendance minus all grants, scholarships, and loans                          |\n| `financials.moneyForCollege`   | number | The total of grants, scholarships, and loans                                               |\n| `financials.loanMonthly`       | number | The monthly loan payment based on the loans specified and `financials.repaymentTerm`       |\n| `financials.loanLifetime`      | number | The lifetime cost of the loans based on the loans specified and `financials.repaymentTerm` |\n| `financials.loanMonthlyParent` | number | The monthly loan payment of the federal Parent PLUS loan.                                  |\n\n#### tenYear and twentyFiveYear properties\n\nTo make it easy to compare the difference between 10 and 25 year loan repayment terms,\nthe Object returned by the package has two additional properties - `financials.tenYear`\nand `financials.twentyFiveYear`. These properties are Objects themselves with their own\n`loanLifetime` and associated values:\n\n| Property                                 | Type   | Description                                                  |\n| ---------------------------------------- | ------ | ------------------------------------------------------------ |\n| `financials.tenYear.loanMonthly`         | number | The monthly loan payment with a 10 year repayment term       |\n| `financials.tenYear.loanLifetime`        | number | The lifetime cost of the loans with a 10 year repayment term |\n| `financials.twentyFiveYear.loanMonthly`  | number | The monthly loan payment with a 25 year repayment term       |\n| `financials.twentyFiveYear.loanLifetime` | number | The lifetime cost of the loan with a 25 year repayment term  |\n\n### Calculations, Caps, and Errors\n\nWhen applied to the \"financials\" Object, the package first establishes some\nconstants and determines which values should be used for a variety of numbers\n\n- for instance, based on whether the program is undergraduate or graduate,\n  what the limits of some federal loans are.\n\nThe package then establishes scholarships and grants, checking against caps,\nand calculates the `firstYearNetCost` property based on those values (applying\nthe grants and scholarships against the cost of attendance).\n\nThen, the package applies loans to the remaining cost, ensuring these values\nare below the limits for federal loans.\n\nAfter grants, scholarships, and loans are applied, the package determines the\ntotal money for college (`moneyForCollege` property) and the amount left to\npay (`remainingCost` property).\n\nFinally, the package calculates the debt at graduation (properties such as\n`perkinsDebt` or `privateLoanDebt`), the cost of the loans over the repayment\nterm (`loanLifetime` property) and the monthly payment of the loans\n('loanMonthly' property)\n\nAlong the way, the package also records and corrects \"errors\" - for instance,\nwhen the inputs exceed federal limits or the cost of attendance (in which case\nthe values for these inputs are changed to equal the limit). These errors can\nbe found in the `errors` property, which is an Object itself. The following\ntable illustrates the \"error codes\" which are used as keys in the `errors`\nObject:\n\n| `errors` Object key            | Error                                               |\n| ------------------------------ | --------------------------------------------------- |\n| `errors.pellOverCosts`         | Pell grant exceeds cost of attendance               |\n| `errors.pellOverCap`           | Pell grant exceeds federal limit                    |\n| `errors.perkinsOverCosts`      | Perkins loan exceeds cost of attendance             |\n| `errors.perkinsOverCap`        | Perkins loan exceeds federal limit                  |\n| `errors.mtaOverCap`            | Military Tuition Assistance exceeds federal limit   |\n| `errors.subsidizedOverCosts`   | Direct subsidized loan exceeds cost of attendance   |\n| `errors.subsidizedOverCap`     | Direct subsidized loan exceeds federal limit        |\n| `errors.unsubsidizedOverCosts` | Direct unsubsidized loan exceeds cost of attendance |\n| `errors.unsubsidizedOverCap`   | Direct unsubsidized loan exceeds federal limit      |\n\n## How to test the software\n\nRun tests with:\n\n```\nyarn test\n```\n\n## Getting help\n\nIf you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker.\n\n## License\n\nThe project is in the public domain within the United States, and\ncopyright and related rights in the work worldwide are waived through\nthe [CC0 1.0 Universal public domain dedication](http://creativecommons.org/publicdomain/zero/1.0/).\n\nAll contributions to this project will be released under the CC0\ndedication. By submitting a pull request, you are agreeing to comply\nwith this waiver of copyright interest.\n\nSoftware source code previously released under an open source license and then modified by CFPB staff is considered a \"joint work\" (see 17 USC § 101); it is partially copyrighted, partially public domain, and as a whole is protected by the copyrights of the non-government authors and must be released according to the terms of the original open-source license.\n\nFor further details, please see: http://www.consumerfinance.gov/developers/sourcecodepolicy/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfpb%2Fstudent-debt-calculator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcfpb%2Fstudent-debt-calculator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfpb%2Fstudent-debt-calculator/lists"}