ad-bs-converter 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.6.0] - 2026-11-11
+
+### Fixed
+
+- Corrected the month lengths for BS years 2082 and 2083. The rows shipped since 2017 were
+  provisional predictions; they are now aligned with the published calendar and with the
+  independent `nepali-date-converter`, `@remotemerge/nepali-date-converter` and
+  `@sbmdkl/nepali-date-converter` tables. Conversions in the second half of those years were
+  previously off by one day (for example `ad2bs('2026/11/11')` returned 2083/7/26 instead of
+  2083/7/25).
+
+  | Year | Old row (Baisakh - Chaitra)                       | New row                                           |
+  | ---- | ------------------------------------------------- | ------------------------------------------------- |
+  | 2082 | 31 31 32 31 31 30 30 30 29 30 30 30 (365)         | 31 31 32 31 31 31 30 29 30 29 30 30 (365)         |
+  | 2083 | 31 31 32 31 31 30 30 30 29 30 30 30 (365)         | 31 31 32 31 31 31 30 29 30 29 30 30 (365)         |
+
+- Restored the month lengths for BS years 2004, 2062 and 2087 to the values published in 0.5.0.
+  PR #11 (Feb 2024, on `master` only, never released) corrected 2081 but at the same time rewrote
+  these three rows to values that match no reference library. The restored rows were verified
+  against two independent implementations, `nepali-date-converter` and
+  `@remotemerge/nepali-date-converter`; the yearly totals are unchanged, so only the days around
+  the affected month boundaries move.
+
+  | Year | Row on `master` (Baisakh - Chaitra)       | Restored row                              |
+  | ---- | ----------------------------------------- | ----------------------------------------- |
+  | 2004 | 30 32 31 32 31 30 30 30 30 29 29 31 (365) | 30 32 31 32 31 30 30 30 29 30 29 31 (365) |
+  | 2062 | 31 31 31 32 31 31 29 30 29 30 29 31 (365) | 30 32 31 32 31 31 29 30 29 30 29 31 (365) |
+  | 2087 | 31 31 32 31 31 31 30 29 30 30 30 30 (366) | 31 31 32 31 31 31 30 30 29 30 30 30 (366) |
+
+- `ad2bs()` no longer crashes with a `TypeError` when walking past the end of the calendar table
+  (in the 0.5.0 npm release this happened for every AD date after 2036-04-14). The conversion now
+  works for every day in the table and throws a descriptive `RangeError` beyond it.
+
+### Added
+
+- TypeScript source with bundled type declarations; the package is published as ESM (`import`)
+  and CommonJS (`require`) through an `exports` map.
+- `ad2bs()` accepts a `Date` object; both functions accept `{ year, month, day }` objects and
+  `yyyy-mm-dd` strings in addition to `yyyy/mm/dd`.
+- `SUPPORTED_RANGE` constant, plus `CALENDAR_DATA`, `MIN_BS_YEAR` and `MAX_BS_YEAR` exports.
+- Exported types: `AdDate`, `AdDateInput`, `BsDate`, `BsDateFields`, `BsDateInput`, `DateParts`,
+  `SupportedRange`, `YearData`.
+- Malformed input, impossible dates and out-of-range dates throw `RangeError` with a clear message
+  (previously the behaviour was undefined: wrong results or a `TypeError`).
+- Test suite migrated to vitest, with a round-trip test over every day in the table and a
+  cross-check of every day in 2000 - 2090 BS against `nepali-date-converter`.
+- GitHub Actions CI (Node 22 / 24 / 26) replacing Travis; ESLint and Prettier. A `.nvmrc`
+  pins local development to Node 26.
+
+### Changed
+
+- Calendar data for BS 2101 - 2199 (already on `master`, never published to npm) is included.
+- `engines.node` is now `>=22` (Node 18 and 20 are end-of-life). The build targets Node 22 /
+  ES2022.
+
+### Notes
+
+- Years 2091 BS and later remain provisional (no official source yet) and may change. The
+  Feb 2024 data contribution shortened 2092 BS from 366 to 365 days, so `2092/12/30` now maps to
+  2036-04-13 (it was 2036-04-14 in 0.5.0) and 2093/1/1 is 2036-04-14; the corresponding unit
+  test was updated to the current table.
+- With the 2004/2062/2087 rows restored, the cross-check against `nepali-date-converter` is clean
+  for every day of 2000 - 2090 BS. `test/crosscheck.test.ts` keeps a `KNOWN_DISAGREEMENTS` list
+  (currently empty) for documenting any future, deliberate divergence.
+
+## 0.5.0 - 2017
+
+Last release of the original CommonJS implementation.
+
+[0.6.0]: https://github.com/techgaun/ad-bs-converter/compare/fd76e5a...master

package/README.md

@@ -1,50 +1,162 @@
-# ad-bs-converter [![npm version](https://badge.fury.io/js/ad-bs-converter.svg)](http://badge.fury.io/js/ad-bs-converter) [![Build Status](https://travis-ci.org/techgaun/ad-bs-converter.svg?branch=master)](https://travis-ci.org/techgaun/ad-bs-converter)
-A javascript implementation to convert bikram samvat to anno domini and vice-versa
+# ad-bs-converter [![npm version](https://badge.fury.io/js/ad-bs-converter.svg)](http://badge.fury.io/js/ad-bs-converter) [![CI](https://github.com/techgaun/ad-bs-converter/actions/workflows/ci.yml/badge.svg)](https://github.com/techgaun/ad-bs-converter/actions/workflows/ci.yml)
 
-_If you are looking for ad-bs converter for python, check out [ad-bs-converter.py](https://github.com/techgaun/ad-bs-converter.py)._
+Convert Bikram Sambat (BS, the Nepali calendar) dates to Anno Domini (AD, Gregorian) and vice-versa.
+
+Written in TypeScript, published as both ESM and CommonJS with bundled type declarations. Requires
+Node 22 or newer (CI runs on Node 22, 24 and 26; `.nvmrc` points at 26) and works in any modern
+browser bundler.
+
+_If you are looking for an ad-bs converter for Python, check out [ad-bs-converter.py](https://github.com/techgaun/ad-bs-converter.py)._
+
+## Installation
 
-### Installation
 ```bash
-npm install ad-bs-converter --save
+npm install ad-bs-converter
 ```
 
-### Example
-```javascript
-var adbs = require("ad-bs-converter");
+## Usage
 
-console.log(adbs.ad2bs("1990/8/10"))
-console.log(adbs.bs2ad("2047/4/26"))
+```ts
+// ESM / TypeScript
+import { ad2bs, bs2ad } from 'ad-bs-converter';
+
+// CommonJS
+const { ad2bs, bs2ad } = require('ad-bs-converter');
+```
+
+```ts
+console.log(ad2bs('1990/8/10'));
+console.log(bs2ad('2047/4/26'));
 ```
 
 outputs
 
-```javascript
-{ ne: 
-   { year: '२०४७',
-     month: '४',
-     day: '२६',
-     strMonth: 'श्रावण',
-     strShortMonth: 'श्रा',
-     dayOfWeek: '५',
-     strDayOfWeek: 'शुक्रवार',
-     strShortDayOfWeek: 'शुक्र',
-     strMinDayOfWeek: 'शु' },
-  en: 
-   { year: 2047,
-     month: 4,
-     day: 26,
-     strMonth: 'Shrawan',
-     strShortMonth: 'Shra',
-     dayOfWeek: 5,
-     strDayOfWeek: 'Shukrabaar',
-     strShortDayOfWeek: 'Shukra',
-     strMinDayOfWeek: 'Shu' } }
-{ year: 1990,
+```js
+{
+  ne: {
+    year: '२०४७',
+    month: '४',
+    day: '२६',
+    strMonth: 'श्रावण',
+    strShortMonth: 'श्रा',
+    dayOfWeek: '५',
+    strDayOfWeek: 'शुक्रवार',
+    strShortDayOfWeek: 'शुक्र',
+    strMinDayOfWeek: 'शु',
+    totalDaysInMonth: '३२'
+  },
+  en: {
+    year: 2047,
+    month: 4,
+    day: 26,
+    strMonth: 'Shrawan',
+    strShortMonth: 'Shra',
+    dayOfWeek: 5,
+    strDayOfWeek: 'Shukrabaar',
+    strShortDayOfWeek: 'Shukra',
+    strMinDayOfWeek: 'Shu',
+    totalDaysInMonth: 32
+  }
+}
+{
+  year: 1990,
   month: 8,
   strMonth: 'August',
   strShortMonth: 'Aug',
   day: 10,
   dayOfWeek: 5,
   strDayOfWeek: 'Friday',
-  strShortDayOfWeek: 'Fri' }
+  strShortDayOfWeek: 'Fri'
+}
+```
+
+### Accepted inputs
+
+Both functions accept a `"yyyy/mm/dd"` string (a `-` separator and leading zeros are fine) or a
+`{ year, month, day }` object. `ad2bs` additionally accepts a JavaScript `Date`, which is read in the
+local time zone (`getFullYear()`, `getMonth()`, `getDate()`).
+
+```ts
+ad2bs('2026-11-11');
+ad2bs({ year: 2026, month: 11, day: 11 });
+ad2bs(new Date(2026, 10, 11));
+
+bs2ad('2083/07/25');
+bs2ad({ year: 2083, month: 7, day: 25 });
 ```
+
+Months and days are always 1-based. `dayOfWeek` is `0` for Sunday through `6` for Saturday.
+
+### Errors
+
+Malformed input, impossible dates (for example `2083/7/31`, since Kartik 2083 has 30 days) and dates
+outside the supported range throw a `RangeError` with a descriptive message.
+
+```ts
+try {
+  ad2bs('1900/1/1');
+} catch (error) {
+  // RangeError: AD date 1900/1/1 is outside the supported range 1918/4/13 - 2143/4/18
+}
+```
+
+### Supported range
+
+```ts
+import { SUPPORTED_RANGE } from 'ad-bs-converter';
+
+SUPPORTED_RANGE.bs; // { start: { year: 1975, month: 1, day: 1 }, end: { year: 2199, month: 12, day: 30 } }
+SUPPORTED_RANGE.ad; // { start: { year: 1918, month: 4, day: 13 }, end: { year: 2143, month: 4, day: 18 } }
+```
+
+The calendar table lives in [`src/data.ts`](src/data.ts) and is also exported as `CALENDAR_DATA`
+(with `MIN_BS_YEAR` / `MAX_BS_YEAR`) for anyone who needs the raw month lengths.
+
+### A note on data accuracy
+
+The Bikram Sambat calendar is not computed from a formula: month lengths are published by Nepal's
+Panchanga Nirnayak Samiti year by year. This library therefore ships a lookup table.
+
+- **1978 - 2090 BS**: considered reliable. Every day in 2000 - 2090 BS is cross-checked in CI
+  against the independent [`nepali-date-converter`](https://www.npmjs.com/package/nepali-date-converter)
+  table with no disagreements (see [`test/crosscheck.test.ts`](test/crosscheck.test.ts)).
+- **2082 and 2083 BS** were corrected in v0.6.0; earlier releases carried provisional 2017-era
+  predictions that were off by a day in the second half of those years (see the
+  [changelog](CHANGELOG.md)).
+- **2004, 2062 and 2087 BS**: PR #11 (2024, never published to npm) fixed 2081 but also rewrote
+  these three rows to values that match no reference library. v0.6.0 restores the original rows,
+  which agree with both `nepali-date-converter` and `@remotemerge/nepali-date-converter`.
+- **2091 BS and later** are provisional. No official data exists yet and different sources disagree;
+  the rows are kept so conversions keep working but they may change in a future release.
+
+If you spot a discrepancy, please open an issue with the source you are comparing against.
+
+### TypeScript
+
+All inputs and outputs are typed:
+
+```ts
+import type {
+  AdDate,
+  AdDateInput,
+  BsDate,
+  BsDateInput,
+  DateParts,
+  SupportedRange,
+} from 'ad-bs-converter';
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm run lint        # eslint + prettier --check
+npm test            # vitest (unit, round-trip and cross-check suites)
+npm run build       # tsup -> dist/ (ESM + CJS + .d.ts)
+npm run smoke       # require()/import the built package
+```
+
+## License
+
+ISC

package/dist/index.d.mts

@@ -0,0 +1,148 @@
+/** A calendar date broken into its numeric parts. Months and days are 1-based. */
+interface DateParts {
+    year: number;
+    month: number;
+    day: number;
+}
+/**
+ * Input accepted by {@link bs2ad}: a `"yyyy/mm/dd"` (or `"yyyy-mm-dd"`) string
+ * or a {@link DateParts} object describing a Bikram Sambat date.
+ */
+type BsDateInput = string | DateParts;
+/**
+ * Input accepted by {@link ad2bs}: a `"yyyy/mm/dd"` (or `"yyyy-mm-dd"`) string,
+ * a {@link DateParts} object, or a JavaScript `Date` (interpreted in the local
+ * time zone, i.e. via `getFullYear()`, `getMonth()` and `getDate()`).
+ */
+type AdDateInput = string | DateParts | Date;
+/**
+ * One localisation of a Bikram Sambat date. `T` is `string` for the Nepali
+ * (Devanagari numeral) version and `number` for the English version.
+ */
+interface BsDateFields<T extends string | number> {
+    year: T;
+    month: T;
+    day: T;
+    /** Full month name, e.g. `"श्रावण"` / `"Shrawan"`. */
+    strMonth: string;
+    /** Abbreviated month name, e.g. `"श्रा"` / `"Shra"`. */
+    strShortMonth: string;
+    /** Day of week, `0` for Sunday through `6` for Saturday. */
+    dayOfWeek: T;
+    /** Full weekday name, e.g. `"शनिवार"` / `"Shanibaar"`. */
+    strDayOfWeek: string;
+    /** Short weekday name, e.g. `"शनि"` / `"Shani"`. */
+    strShortDayOfWeek: string;
+    /** Minimal weekday name, e.g. `"श"` / `"Sha"`. */
+    strMinDayOfWeek: string;
+    /** Number of days in the BS month the date falls in. */
+    totalDaysInMonth: T;
+}
+/** Result of {@link ad2bs}. */
+interface BsDate {
+    /** Nepali (Devanagari) representation. Numbers are strings of Devanagari digits. */
+    ne: BsDateFields<string>;
+    /** English representation. Numbers are plain JavaScript numbers. */
+    en: BsDateFields<number>;
+}
+/** Result of {@link bs2ad}. */
+interface AdDate {
+    year: number;
+    /** 1-based Gregorian month. */
+    month: number;
+    /** Full month name, e.g. `"August"`. */
+    strMonth: string;
+    /** Abbreviated month name, e.g. `"Aug"`. */
+    strShortMonth: string;
+    day: number;
+    /** Day of week, `0` for Sunday through `6` for Saturday. */
+    dayOfWeek: number;
+    /** Full weekday name, e.g. `"Friday"`. */
+    strDayOfWeek: string;
+    /** Short weekday name, e.g. `"Fri"`. */
+    strShortDayOfWeek: string;
+}
+/** Inclusive bounds of the dates this library can convert. */
+interface SupportedRange {
+    bs: {
+        start: DateParts;
+        end: DateParts;
+    };
+    ad: {
+        start: DateParts;
+        end: DateParts;
+    };
+}
+
+/**
+ * Inclusive bounds of the dates this library can convert, in both calendars.
+ * Derived from the calendar table, so it grows automatically when rows are added.
+ */
+declare const SUPPORTED_RANGE: Readonly<SupportedRange>;
+/**
+ * Converts a Bikram Sambat date to the Gregorian (AD) calendar.
+ *
+ * @param input `"yyyy/mm/dd"` string or `{ year, month, day }` object.
+ * @throws {RangeError} if the input is malformed, not a real BS date, or
+ *   outside {@link SUPPORTED_RANGE}.
+ */
+declare function bs2ad(input: BsDateInput): AdDate;
+/**
+ * Converts a Gregorian (AD) date to the Bikram Sambat calendar.
+ *
+ * @param input `"yyyy/mm/dd"` string, `{ year, month, day }` object, or a
+ *   `Date` (read in the local time zone).
+ * @throws {RangeError} if the input is malformed, not a real date, or outside
+ *   {@link SUPPORTED_RANGE}.
+ */
+declare function ad2bs(input: AdDateInput): BsDate;
+
+/**
+ * Bikram Sambat calendar table.
+ *
+ * Each row is keyed by BS year and holds the number of days in each of the
+ * twelve months (Baisakh to Chaitra) followed by the total number of days in
+ * that year.
+ *
+ * Data provenance:
+ * - 1975-2092: original table shipped with this package (npm 0.5.0).
+ *   - 2082 and 2083 were corrected in 0.6.0: they were provisional
+ *     predictions when first added in 2017.
+ *   - 2081 was corrected by PR #11 (2024). The same PR also rewrote 2004,
+ *     2062 and 2087 to values that match no reference library; 0.6.0
+ *     restores the 0.5.0 rows, which agree with nepali-date-converter and
+ *     @remotemerge/nepali-date-converter.
+ * - 2093-2100: https://nepalipatro.com.np/calendar/monthly/bs/2093/1
+ * - 2101-2199: community contribution (PR #11, see git history).
+ *
+ * Years after 2090 BS have not been officially published by the Nepal
+ * Panchanga Nirnayak Samiti and are therefore provisional; they may change.
+ *
+ * The module keeps the table in a separate file so that updating it is a
+ * one-line change per year. `test/data.test.ts` verifies that every row is
+ * internally consistent (month lengths sum to the yearly total).
+ */
+/** Twelve month lengths followed by the total number of days in the year. */
+type YearData = readonly [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
+declare const CALENDAR_DATA: Readonly<Record<number, YearData>>;
+/** First BS year present in the table. */
+declare const MIN_BS_YEAR = 1975;
+/** Last BS year present in the table. */
+declare const MAX_BS_YEAR = 2199;
+
+export { CALENDAR_DATA, MAX_BS_YEAR, MIN_BS_YEAR, SUPPORTED_RANGE, ad2bs, bs2ad };
+export type { AdDate, AdDateInput, BsDate, BsDateFields, BsDateInput, DateParts, SupportedRange, YearData };

package/dist/index.d.ts

@@ -0,0 +1,148 @@
+/** A calendar date broken into its numeric parts. Months and days are 1-based. */
+interface DateParts {
+    year: number;
+    month: number;
+    day: number;
+}
+/**
+ * Input accepted by {@link bs2ad}: a `"yyyy/mm/dd"` (or `"yyyy-mm-dd"`) string
+ * or a {@link DateParts} object describing a Bikram Sambat date.
+ */
+type BsDateInput = string | DateParts;
+/**
+ * Input accepted by {@link ad2bs}: a `"yyyy/mm/dd"` (or `"yyyy-mm-dd"`) string,
+ * a {@link DateParts} object, or a JavaScript `Date` (interpreted in the local
+ * time zone, i.e. via `getFullYear()`, `getMonth()` and `getDate()`).
+ */
+type AdDateInput = string | DateParts | Date;
+/**
+ * One localisation of a Bikram Sambat date. `T` is `string` for the Nepali
+ * (Devanagari numeral) version and `number` for the English version.
+ */
+interface BsDateFields<T extends string | number> {
+    year: T;
+    month: T;
+    day: T;
+    /** Full month name, e.g. `"श्रावण"` / `"Shrawan"`. */
+    strMonth: string;
+    /** Abbreviated month name, e.g. `"श्रा"` / `"Shra"`. */
+    strShortMonth: string;
+    /** Day of week, `0` for Sunday through `6` for Saturday. */
+    dayOfWeek: T;
+    /** Full weekday name, e.g. `"शनिवार"` / `"Shanibaar"`. */
+    strDayOfWeek: string;
+    /** Short weekday name, e.g. `"शनि"` / `"Shani"`. */
+    strShortDayOfWeek: string;
+    /** Minimal weekday name, e.g. `"श"` / `"Sha"`. */
+    strMinDayOfWeek: string;
+    /** Number of days in the BS month the date falls in. */
+    totalDaysInMonth: T;
+}
+/** Result of {@link ad2bs}. */
+interface BsDate {
+    /** Nepali (Devanagari) representation. Numbers are strings of Devanagari digits. */
+    ne: BsDateFields<string>;
+    /** English representation. Numbers are plain JavaScript numbers. */
+    en: BsDateFields<number>;
+}
+/** Result of {@link bs2ad}. */
+interface AdDate {
+    year: number;
+    /** 1-based Gregorian month. */
+    month: number;
+    /** Full month name, e.g. `"August"`. */
+    strMonth: string;
+    /** Abbreviated month name, e.g. `"Aug"`. */
+    strShortMonth: string;
+    day: number;
+    /** Day of week, `0` for Sunday through `6` for Saturday. */
+    dayOfWeek: number;
+    /** Full weekday name, e.g. `"Friday"`. */
+    strDayOfWeek: string;
+    /** Short weekday name, e.g. `"Fri"`. */
+    strShortDayOfWeek: string;
+}
+/** Inclusive bounds of the dates this library can convert. */
+interface SupportedRange {
+    bs: {
+        start: DateParts;
+        end: DateParts;
+    };
+    ad: {
+        start: DateParts;
+        end: DateParts;
+    };
+}
+
+/**
+ * Inclusive bounds of the dates this library can convert, in both calendars.
+ * Derived from the calendar table, so it grows automatically when rows are added.
+ */
+declare const SUPPORTED_RANGE: Readonly<SupportedRange>;
+/**
+ * Converts a Bikram Sambat date to the Gregorian (AD) calendar.
+ *
+ * @param input `"yyyy/mm/dd"` string or `{ year, month, day }` object.
+ * @throws {RangeError} if the input is malformed, not a real BS date, or
+ *   outside {@link SUPPORTED_RANGE}.
+ */
+declare function bs2ad(input: BsDateInput): AdDate;
+/**
+ * Converts a Gregorian (AD) date to the Bikram Sambat calendar.
+ *
+ * @param input `"yyyy/mm/dd"` string, `{ year, month, day }` object, or a
+ *   `Date` (read in the local time zone).
+ * @throws {RangeError} if the input is malformed, not a real date, or outside
+ *   {@link SUPPORTED_RANGE}.
+ */
+declare function ad2bs(input: AdDateInput): BsDate;
+
+/**
+ * Bikram Sambat calendar table.
+ *
+ * Each row is keyed by BS year and holds the number of days in each of the
+ * twelve months (Baisakh to Chaitra) followed by the total number of days in
+ * that year.
+ *
+ * Data provenance:
+ * - 1975-2092: original table shipped with this package (npm 0.5.0).
+ *   - 2082 and 2083 were corrected in 0.6.0: they were provisional
+ *     predictions when first added in 2017.
+ *   - 2081 was corrected by PR #11 (2024). The same PR also rewrote 2004,
+ *     2062 and 2087 to values that match no reference library; 0.6.0
+ *     restores the 0.5.0 rows, which agree with nepali-date-converter and
+ *     @remotemerge/nepali-date-converter.
+ * - 2093-2100: https://nepalipatro.com.np/calendar/monthly/bs/2093/1
+ * - 2101-2199: community contribution (PR #11, see git history).
+ *
+ * Years after 2090 BS have not been officially published by the Nepal
+ * Panchanga Nirnayak Samiti and are therefore provisional; they may change.
+ *
+ * The module keeps the table in a separate file so that updating it is a
+ * one-line change per year. `test/data.test.ts` verifies that every row is
+ * internally consistent (month lengths sum to the yearly total).
+ */
+/** Twelve month lengths followed by the total number of days in the year. */
+type YearData = readonly [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
+declare const CALENDAR_DATA: Readonly<Record<number, YearData>>;
+/** First BS year present in the table. */
+declare const MIN_BS_YEAR = 1975;
+/** Last BS year present in the table. */
+declare const MAX_BS_YEAR = 2199;
+
+export { CALENDAR_DATA, MAX_BS_YEAR, MIN_BS_YEAR, SUPPORTED_RANGE, ad2bs, bs2ad };
+export type { AdDate, AdDateInput, BsDate, BsDateFields, BsDateInput, DateParts, SupportedRange, YearData };