Install

npm install financial-fns

Usage

Use se import or require

ES6 Modules

import { xirr } from 'financial-fns'

const result = xirr(
    [-10000, 2750, 4250, 3250, 2750],
    [
        new Date('2008-01-01'),
        new Date('2008-03-01'),
        new Date('2008-10-30'),
        new Date('2009-02-15'),
        new Date('2009-04-01')
    ]
)

console.log('RESULT', result) // RESULT 0.3733625335188315

CommonJS

const { xirr } require('financial-fns')

const result = xirr(
    [-10000, 2750, 4250, 3250, 2750],
    [
        new Date('2008-01-01'),
        new Date('2008-03-01'),
        new Date('2008-10-30'),
        new Date('2009-02-15'),
        new Date('2009-04-01')
    ]
)

console.log('RESULT', result) // RESULT 0.3733625335188315

Functions

XIRR

Calculates the internal rate of return (IRR) for a schedule of cash flows that is not necessarily periodic. Excel

• =XIRR (English)
• =TIR.NO.PER (Spanish)

xirr(cashFlow, dates, guess)

Example

const result = xirr(
    [-10000, 2750, 4250, 3250, 2750],
    [
        new Date('2008-01-01'),
        new Date('2008-03-01'),
        new Date('2008-10-30'),
        new Date('2009-02-15'),
        new Date('2009-04-01')
    ]
)
console.log(result) // 0.3733625335188315

IRR

Calculates the internal rate of return (IRR) for a series of cash flows represented by the numbers in values. Excel:

• =IRR (English)
• =TIR (Spanish)

// guess default 0,1
irr(cashFlow, guess)

Example

const result = irr([-10000, 2750, 4250, 3250, 2750])
console.log(result) // 0.1154127831005586

NPV

Calculates the net present value of an investment based on a discount rate and a series of cash flows.

Excel:

• =NPV (English)
• =VNA (Spanish)

// rate default 0
npv(cashFlow, rate)

Example

const result = npv(
    [
        -1333.11,
        178.46,
        178.46,
        178.46,
        178.46,
        178.46,
        178.46,
        178.46,
        178.46,
        178.46,
        178.46,
        178.46,
        178.46
    ],
    0.05
)
console.log(result) // 248.62588704065456

XNPV

Calculates the net present value of an investment based on a discount rate and a series of cash flows.

Excel:

• =XNPV (English)
• =VNA.NO.PER (Spanish)

// rate default 0
xnpv(cashFlow, dates, rate)

Example

const result = xnpv(
    [-10000, 2750, 4250, 3250, 2750],
    [
        new Date('2008-01-01'),
        new Date('2008-03-01'),
        new Date('2008-10-30'),
        new Date('2009-02-15'),
        new Date('2009-04-01')
    ],
    0.1
)
console.log(result) // 1994.5100406532633

Rate

Monthly rate

Excel:

• =RATE (English)
• =TASA (Spanish)

rate(
    nPeriods,
    payment,
    presentValue,
    (futureValue = 0),
    (dueDateType = 0),
    (guess = 0.1)
)

Example

const monthlyRate = rate(4 * 12, -200, 8000)
console.log(monthlyRate) // 0.0077014724882104105
const annualRate = rate(4 * 12, -200, 8000) * 12
console.log(annualRate) // 0.09241766985852493

NPER

Calculate number of periods

Excel:

• =NPER (English)
• =NPER (Spanish)

nper(rate, payment, presentValue, (futureValue = 0), (dueDateType = 0))

Example

const result = nper(0, 500, -25000)
console.log(result) // 50

FV

Calculate the future value of an investment based on a constant interest rate. You can use FV with either periodic, constant payments, or a single lump sum payment. Excel:

• =FV (English)
• =VF (Spanish)

fv(rate, totalPeriods, payment, (presentValue = 0), (dueDateType = 0))

Example

const result = fv(0.12 / 12, 12, -1000)
console.log(result) // 12682.503013196972

FV Schedule

Future value (applying a series of compound interest rates) Excel:

• =FVSCHEDULE (English)
• =VF.PLAN (Spanish)

fvSchedule(principal, schedule)

Example

const result = fvSchedule(336, [0.02, 0.05, 0.03])
console.log(result) // 370.65168

Effect

Returns the effective annual interest rate, given the nominal annual interest rate and the number of compounding periods per year. Excel:

• =EFFECT (English)
• =INT.EFECTIVO (Spanish)

effect(rate, nPeriods)

Example

const result = effect(0.1, 12)
console.log(result) // 0.10471306744129724

Day count by date

Count days between two dates without time

dayCountByDate(dateFrom, dateTo, (abs = false))

Example

const dayCount = dayCountByDate(new Date('2022-06-10'), new Date('2022-02-18'))
console.log(dayCount) // -112

const dayCountAbs = dayCountByDate(
    new Date('2022-06-10'),
    new Date('2022-02-18'),
    true
)
console.log(dayCountAbs) // 112

Day count by dateTime

Count days between two dates without time

dayCountByDateTime(dateFrom, dateTo, (abs = false))

Example

const dayCount = dayCountByDateTime(
    new Date('2022-03-04 22:00:00'),
    new Date('2022-02-27 22:00:00')
)
console.log(dayCount) // -5

const dayCountAbs = dayCountByDateTime(
    new Date('2022-03-04 22:00:00'),
    new Date('2022-02-27 22:00:00'),
    true
)
console.log(dayCountAbs) // 5
const dayCountAbs2 = dayCountByDateTime(
    new Date('2022-03-04 23:00:00'),
    new Date('2022-02-27 22:00:00'),
    true
)
console.log(dayCountAbs2) // 5.04

Get days by frequency

Get total days in a frequency

getDaysByFrequency(frequency)

Example

/**
 * weekly: 7,
 * biWeekly: 14,
 * monthly: 1,
 * everyTwoMonths: 2,
 * everyThreeMonths: 3,
 * everyFourMonths: 4,
 * everySixMonths: 6,
 * yearly: 12,
 */
const monthlyDays = getDaysByFrequency(1)
console.log(monthlyDays) // 30
const biWeekly = getDaysByFrequency(14)
console.log(biWeekly) // 15

Last date of month

Get last date of month.

getLastDateOfMonth(month, year)

Example

/**
 * JS Months from 0 to 11
 */
const lastDate1 = getLastDateOfMonth(1, 2022)
console.log(lastDate) // 28
const lastDate2 = getLastDateOfMonth(1, 2024)
console.log(lastDate) // 29

Round

Round a number to a specified number of decimal places.

round(num, places)

Example

const result = round(135.15000004)
console.log(result) // 135.15
const result2 = round(135.15366007, 4)
console.log(result2) // 135.1537

Changelog

All notable changes to this project will be documented in this file. See standard-version for commit guidelines.

0.0.8 (2024-10-19)

Chore

• compilerOptions - keep comments (3a6b932)
• misspellings (96bc82c)
• package.json - Add keywords (24ba392)
• update README (71addca)

0.0.7 (2024-10-18)

0.0.6 (2024-10-18)

0.0.5 (2024-10-18)

Bug Fixes

• index.ts use import (c25828e)

0.0.4 (2024-10-18)

Bug Fixes

• package.json and ts-config (358f1f6)

0.0.3 (2024-10-18)

Bug Fixes

• Remove package.json type (e1f22de)

0.0.2 (2023-10-22)

0.0.1 (2023-10-22)

Bug Fixes

• fv - dueDateType as number (3254a50)

Tests

• fix monthly frequency (3799aa3)

Chore

• Add constants.ts (f05209a)
• Add dayCountByDate (79a01ba)
• Add dayCountByDateTime (c5edf20)
• Add effect (60acd03)
• add FV - Future Value (2979f8c)
• add FVSCHEDULE - Future Value applying a series of compound interest rates (0c97fdb)
• Add getDaysByFrequency (2a8db0d)
• Add getLastDateOfMonth (b38b811)
• Add irr (Internal Rate of Return) (d06a8f3)
• add nper - Number of periods (786135d)
• Add npv (Net Present Value) (2627e13)
• add package decimal.js (cd4f694)
• Add packages tsdx and tslib (d44ec04)
• add rate (0160392)
• Add round (613a48e)
• Add xirr (Internal Rate of Return for a schedule of cash flows) (beba54a)
• Add xnpv (Net Present Value for a schedule of cash flows) (a3943b1)
• Fix getDaysByFrequency - monthly as 1 (3f25646)
• Move constants into functions (5c9cde0)
• rename functions by lib (e85c149)
• setup commit conventions and standard version (c74de9b)
• update comments (e6c28bb)
• update comments - add excel formula English/Spanish (00181f5)
• Update export for round and irr (4f20234)
• Update exports (6e9bbd8)
• Update function exports (cdc78b1)
• update functions exports (cc3da10)
• Update imports and exports (64fbc56)
• update npv doc (517aa53)
• Update package.json - type module (46b275c)
• Update rate - remove condition for rate 0 in loop (f48976d)

Refactors

• Move types into types folder (0f78bcd)
• remove .env.example (689b2c3)
• replace throw by NaN (747e156)
• uninstall dotenv (245881b)