nepali-fiscal-year

Nepali (Bikram Sambat) fiscal year utilities for TypeScript and JavaScript.

Nepal's fiscal year — आर्थिक वर्ष — runs from Shrawan 1 to the last day of Ashadh of the following BS year. Ashadh is 31 or 32 days depending on the year, so the end date cannot be hardcoded; it comes from the bundled calendar data.

• Current fiscal year, resolved in Asia/Kathmandu rather than the host timezone
• AD and BS date ranges for any fiscal year
• Fiscal year for any AD date
• Fiscal year for any BS date
• A precomputed FISCAL_YEARS table you can filter, index or ship to a client
• Zero runtime dependencies, ESM + CJS, full type declarations

Install

npm install nepali-fiscal-year

Quick start

import {
  getCurrentFiscalYear,
  getFiscalYear,
  getFiscalYearFromAdDate,
  getFiscalYearFromBsDate,
} from 'nepali-fiscal-year'

getCurrentFiscalYear().label            // '2083/84'  (as of 2026-08-19)

getFiscalYear('2082/83').adStartISO     // '2025-07-17'
getFiscalYear('2082/83').adEndISO       // '2026-07-16'
getFiscalYear('82-83').bsEndISO         // '2083-03-32'

getFiscalYearFromAdDate('2026-07-16').label   // '2082/83'
getFiscalYearFromAdDate('2026-07-17').label   // '2083/84'

getFiscalYearFromBsDate('2082-03-31').label   // '2081/82'
getFiscalYearFromBsDate('2082-04-01').label   // '2082/83'

The FiscalYear object

Every lookup returns the same shape:

getFiscalYear('2082/83')
// {
//   label:       '2082/83',
//   shortLabel:  '82/83',
//   startYear:   2082,
//   endYear:     2083,
//   bsStart:     { year: 2082, month: 4, day: 1 },
//   bsEnd:       { year: 2083, month: 3, day: 32 },
//   adStart:     { year: 2025, month: 7, day: 17 },
//   adEnd:       { year: 2026, month: 7, day: 16 },
//   adStartISO:  '2025-07-17',
//   adEndISO:    '2026-07-16',
//   bsStartISO:  '2082-04-01',
//   bsEndISO:    '2083-03-32',
//   days:        365,
// }

Objects are frozen, so they are safe to hand out and cache.

API

getCurrentFiscalYear(now?: Date): FiscalYear

The fiscal year currently running in Nepal. now defaults to the present instant and is converted to a calendar date in Asia/Kathmandu (UTC+05:45) — a server running in UTC will not report yesterday's fiscal year late in the evening.

getFiscalYear(input: FiscalYearInput): FiscalYear

Fiscal year for a fiscal-year notation. All of these mean the same thing:

'2082/83'   '2082/2083'   '2082-83'   '82/83'   '82-83'   '2082'   2082   82

Two-digit years expand into the 2000s. A pair whose halves are not consecutive ('2082/84') throws InvalidInputError.

getFiscalYearFromAdDate(date: AdDateInput): FiscalYear

Fiscal year containing an AD date. Accepts:

| Input | Read as | | --- | --- | | '2025-12-31' | a calendar date | | { year: 2025, month: 12, day: 31 } | a calendar date | | new Date(...) | a calendar date in Asia/Kathmandu |

A Date is an instant, not a date. new Date('2026-07-16T19:00:00Z') is already 2026-07-17 in Nepal, so it resolves to fiscal year 2083/84. Pass a string or an object if you want a plain calendar date with no timezone reasoning.

getFiscalYearFromBsDate(date: BsDateInput): FiscalYear

Fiscal year containing a BS date. Accepts '2082-04-01' or { year: 2082, month: 4, day: 1 }. The day is validated against the real length of that BS month, so '2082-01-32' throws.

FISCAL_YEARS: readonly FiscalYear[]

Every fiscal year the bundled data can describe, oldest first — 2000/01 through 2089/90. This is the dataset the lookups index into; filter it directly, or use:

listFiscalYears({ from?, to? }): FiscalYear[]

listFiscalYears({ from: '2080/81', to: '2084/85' }).map((fy) => fy.label)
// ['2080/81', '2081/82', '2082/83', '2083/84', '2084/85']

Both bounds are inclusive and accept any fiscal-year notation.

isAdDateInFiscalYear(date, fiscalYear): boolean / isBsDateInFiscalYear(date, fiscalYear): boolean

isAdDateInFiscalYear('2026-07-16', '2082/83')  // true
isAdDateInFiscalYear('2026-07-17', '2082/83')  // false

Date conversion helpers

The BS ↔ AD conversion behind the fiscal-year logic is exported too:

import { adToBs, bsToAd, bsMonthDays, BS_MONTH_NAMES, todayInKathmandu } from 'nepali-fiscal-year'

bsToAd({ year: 2082, month: 4, day: 1 })   // { year: 2025, month: 7, day: 17 }
adToBs({ year: 2025, month: 7, day: 17 })  // { year: 2082, month: 4, day: 1 }
bsMonthDays(2083, 3)                       // 32  (Ashadh 2083)
BS_MONTH_NAMES[3]                          // 'Shrawan'
todayInKathmandu()                         // today's AD date in Nepal

Also exported: BS_MONTH_NAMES_NE, formatAdISO, formatBsISO, parseAdDate, parseBsDate, assertValidBsDate, parseFiscalYearInput.

Errors

| Class | Thrown when | | --- | --- | | InvalidInputError | input cannot be parsed, or names a date that does not exist | | OutOfRangeError | the date or fiscal year falls outside the bundled calendar data |

Both extend NepaliFiscalYearError.

Supported range

| | Range | | --- | --- | | Calendar data | BS 2000 – 2090 (AD 1943-04-14 – 2034-04-13) | | Fiscal years | 2000/01 – 2089/90 |

A fiscal year needs Shrawan–Chaitra of its start year and Baishakh–Ashadh of the next, so the last usable fiscal year starts one year before the calendar data ends. Anything outside these bounds throws OutOfRangeError rather than guessing.

Calendar data: source and verification

The BS month-length table comes from sanjay-np/nepali-datepicker, anchored on the standard BS 2000-01-01 = AD 1943-04-14.

It was cross-checked before adoption:

• Rows 2000–2089 are identical to bikram-sambat (medic), and are corroborated by @sbmdkl/nepali-date-converter, @zener/nepali-date and nepali-calendar-js.
• Row 2090 matches @sbmdkl/nepali-date-converter.
• Rows 2091–2099 were dropped — a deviation from the upstream table, made deliberately. Its 2096 row sums to 364 days, which is impossible for a BS year (always 365 or 366), and 2093/2094 look row-shifted. The same defects are present in @sbmdkl, so there is no source to repair them from, and a wrong row corrupts every conversion after it. The data stops at 2090 instead.
• test/data-verification.test.ts re-runs the comparison against bikram-sambat on every test run: all month lengths for 2000–2089, the AD start and end of every fiscal year through 2088/89, and a day-by-day check of one whole fiscal year.

Note that BS years from 2084 onward are provisional in every published dataset. Nepal's official calendar is fixed year by year, so those rows may be revised. Rebuild with npm run generate:data after updating scripts/source-nepali-date-data.ts when newer official data lands.

Development

npm install
npm run generate:data   # rebuild src/data.ts from the vendored source table
npm run typecheck
npm test
npm run build

License

MIT