bikram-sambat-date 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Santosh Kafle
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/NOTICE ADDED
@@ -0,0 +1,23 @@
1
+ bikram-sambat-date
2
+ Copyright (c) 2026 Santosh Kafle. Licensed under the MIT License.
3
+
4
+ The calendar table in src/data/calendar.generated.ts was built by
5
+ cross-checking month-length data published by the following projects. Their
6
+ original files and licenses are kept in data/sources/ in the source
7
+ repository.
8
+
9
+ - nepali-datetime, https://github.com/amitgaru2/nepali-datetime
10
+ Apache License 2.0
11
+ - bikram-sambat by Medic, https://github.com/medic/bikram-sambat
12
+ Apache License 2.0
13
+ - nepali-date-converter by subeshb1, https://github.com/subeshb1/Nepali-Date
14
+ MIT License
15
+ - bikram-sambat by ashok095, https://github.com/ashok095/bikram-sambat
16
+ MIT License
17
+ - @remotemerge/nepali-date-converter, https://github.com/remotemerge/nepali-date-converter
18
+ MIT License
19
+ - nepali-date-library by SandipGhimire, https://github.com/SandipGhimire/Nepali-Date-Library-NodeJS
20
+ MIT License
21
+
22
+ Month start dates were also checked against Hamro Patro
23
+ (https://www.hamropatro.com).
package/README.md CHANGED
@@ -1,3 +1,312 @@
1
- # Temporary Holding Version
1
+ # bikram-sambat-date
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![CI](https://github.com/santosh-kafle/bikram-sambat-date/actions/workflows/ci.yml/badge.svg)](https://github.com/santosh-kafle/bikram-sambat-date/actions/workflows/ci.yml)
4
+
5
+ Accurate, time-zone-safe **Bikram Sambat (BS) ↔ Gregorian (AD)** date
6
+ conversion for Node.js backends. Zero dependencies.
7
+
8
+ ```ts
9
+ import { adToBs, bsToAd, BsDate } from 'bikram-sambat-date';
10
+
11
+ adToBs({ year: 2026, month: 4, day: 14 }).toString(); // '2083-01-01'
12
+ bsToAd({ year: 2083, month: 4, day: 1 }); // { year: 2026, month: 7, day: 17 }
13
+ ```
14
+
15
+ > **Status:** pre-1.0. The API may still change in minor releases. Calendars
16
+ > are published up to BS 2083; update the package each year to get the
17
+ > newly published year.
18
+
19
+ ## Why another converter
20
+
21
+ - **Checked data.** BS month lengths cannot be calculated by a simple
22
+ formula. They have to come from published calendars. This library's table
23
+ is built by cross-checking six open-source tables against Hamro Patro.
24
+ Every disagreement is recorded and decided in writing, and the build fails
25
+ on any new one. See [docs/data-sources.md](docs/data-sources.md) and the
26
+ generated [data report](data/REPORT.md).
27
+ - **Honest about the future.** Calendars are published only about a year
28
+ ahead. Other libraries ship guesses for later years as if they were fact,
29
+ and those guesses have often been wrong. This library projects later years
30
+ from the Sūrya Siddhānta, the astronomy Nepal's calendar committee uses. It
31
+ is calibrated to 99.2% of published month starts, and every date tells you
32
+ whether it is `published`, `projected` or `uncertain`. See
33
+ [docs/projection.md](docs/projection.md).
34
+ - **Server-time-zone safe.** Conversions never go through a JavaScript
35
+ `Date`. The answer is the same on a server in UTC, New York or Kathmandu.
36
+ - **Backend-friendly.** It has 1-based months, immutable values, JSON output
37
+ as `"YYYY-MM-DD"`, typed errors, ESM and CommonJS builds, TypeScript types,
38
+ and NestJS validation helpers.
39
+
40
+ ## Install
41
+
42
+ ```sh
43
+ npm install bikram-sambat-date
44
+ ```
45
+
46
+ Requires Node.js 22 or newer. No dependencies; about 10 KB gzipped, and the
47
+ optional NestJS helpers add 1 KB.
48
+
49
+ ## Usage
50
+
51
+ ### Converting
52
+
53
+ ```ts
54
+ import { adToBs, bsToAd } from 'bikram-sambat-date';
55
+
56
+ const bs = adToBs({ year: 2026, month: 10, day: 13 });
57
+ bs.toString(); // '2083-06-27'
58
+
59
+ bsToAd({ year: 2083, month: 6, day: 27 }); // { year: 2026, month: 10, day: 13 }
60
+ ```
61
+
62
+ Months are **1-based** in both calendars: Baisakh and January are 1.
63
+
64
+ ### `BsDate`
65
+
66
+ ```ts
67
+ import { BsDate } from 'bikram-sambat-date';
68
+
69
+ const date = BsDate.of(2083, 4, 1); // 1 Shrawan 2083
70
+ date.year; // 2083
71
+ date.month; // 4
72
+ date.day; // 1
73
+ date.weekday; // 5 (0 is Sunday): a Friday
74
+ date.toAd(); // { year: 2026, month: 7, day: 17 }
75
+ date.toString(); // '2083-04-01'
76
+ JSON.stringify({ date }); // '{"date":"2083-04-01"}'
77
+
78
+ const ad = BsDate.fromAd({ year: 2026, month: 4, day: 14 });
79
+ ad.equals(BsDate.of(2083, 1, 1)); // true
80
+ ad.isBefore(date); // true
81
+ [date, ad].sort(BsDate.compare); // earliest first
82
+ ```
83
+
84
+ `BsDate` is immutable.
85
+
86
+ ### Arithmetic
87
+
88
+ ```ts
89
+ import { BsDate, monthGrid } from 'bikram-sambat-date';
90
+
91
+ const date = BsDate.of(2083, 3, 32); // 32 Asar 2083
92
+ date.addDays(1); // 2083-04-01
93
+ date.addMonths(1); // 2083-04-31, clamped to the end of Shrawan
94
+ date.endOfMonth(); // 2083-03-32
95
+ BsDate.today().diffInYears(BsDate.of(2050, 6, 28)); // age in BS years
96
+ monthGrid(2083, 4); // Shrawan 2083 as weeks, Sunday first
97
+ ```
98
+
99
+ Every method returns a new date. See [docs/arithmetic.md](docs/arithmetic.md)
100
+ for how months are clamped and differences counted.
101
+
102
+ ### Formatting and parsing
103
+
104
+ ```ts
105
+ const date = BsDate.of(2083, 4, 1);
106
+ date.format('D MMMM YYYY, dddd'); // '1 Shrawan 2083, Friday'
107
+ date.format('D MMMM YYYY, dddd', { locale: 'ne' }); // '१ साउन २०८३, शुक्रवार'
108
+
109
+ BsDate.parse('2083-04-01'); // default pattern YYYY-MM-DD
110
+ BsDate.parse('१ साउन २०८३', 'D MMMM YYYY'); // Devanagari digits and names
111
+ BsDate.parse('1 Saun 2083', 'D MMMM YYYY'); // common spellings
112
+ ```
113
+
114
+ Parsing is strict about structure and forgiving about spelling. It accepts
115
+ ASCII or Devanagari digits and English or Nepali names in any common
116
+ spelling, and it checks any weekday in the string against the date. See
117
+ [docs/formatting.md](docs/formatting.md) for the tokens.
118
+
119
+ ### Instants and Kathmandu time
120
+
121
+ A `Date` (or a database timestamp) is an instant, which falls on different
122
+ dates in different time zones. BS dates are read in **Kathmandu time**,
123
+ whatever the server's time zone:
124
+
125
+ ```ts
126
+ import { BsDate } from 'bikram-sambat-date';
127
+
128
+ BsDate.fromInstant(new Date('2026-07-16T18:15:00Z')).toString(); // '2083-04-01'
129
+ BsDate.today(); // today in Kathmandu
130
+ BsDate.of(2083, 4, 1).toInstant(); // 2026-07-16T18:15:00.000Z, midnight in Kathmandu
131
+ ```
132
+
133
+ ### Fiscal year
134
+
135
+ Nepal's fiscal year runs from 1 Shrawan to the last day of Asar:
136
+
137
+ ```ts
138
+ import { FiscalYear, fiscalYearOf } from 'bikram-sambat-date';
139
+
140
+ fiscalYearOf(new Date()).label; // '2083/84'
141
+ const fy = FiscalYear.parse('2083/84');
142
+ fy.firstDay.toString(); // '2083-04-01'
143
+ fy.contains(BsDate.of(2084, 3, 1)); // true
144
+ fy.next().label; // '2084/85'
145
+ ```
146
+
147
+ See [docs/time-and-fiscal-year.md](docs/time-and-fiscal-year.md) for
148
+ Kathmandu's clock history and querying records by BS day.
149
+
150
+ ### NestJS
151
+
152
+ ```ts
153
+ import {
154
+ IsBsDate,
155
+ ParseBsDatePipe,
156
+ ParseFiscalYearPipe,
157
+ ToBsDate,
158
+ } from 'bikram-sambat-date/nestjs';
159
+
160
+ class SalesReportQueryDto {
161
+ @ToBsDate() // '2083-04-01' → BsDate (ValidationPipe with transform: true)
162
+ @IsBsDate() // otherwise 400: "from must be a BS date (YYYY-MM-DD)"
163
+ from!: BsDate;
164
+ }
165
+
166
+ @Get('sales/:date')
167
+ salesOn(@Param('date', ParseBsDatePipe) date: BsDate) {}
168
+
169
+ @Get('reports/sales') // ?fy=2083/84
170
+ salesIn(@Query('fy', ParseFiscalYearPipe) fy: FiscalYear) {}
171
+ ```
172
+
173
+ Fiscal years have the same helpers: `@IsFiscalYear()`, `@ToFiscalYear()`
174
+ and `ParseFiscalYearPipe`.
175
+
176
+ The NestJS helpers live in a separate entry point. `@nestjs/common`,
177
+ `class-validator` and `class-transformer` are optional peer dependencies,
178
+ so the core stays dependency-free. See [docs/nestjs.md](docs/nestjs.md).
179
+
180
+ ### Calendar facts
181
+
182
+ ```ts
183
+ import {
184
+ daysInBsMonth,
185
+ daysInBsYear,
186
+ isValidBsDate,
187
+ supportedRange,
188
+ } from 'bikram-sambat-date';
189
+
190
+ daysInBsMonth(2083, 1); // 31
191
+ daysInBsYear(2083); // 365
192
+ isValidBsDate(2083, 1, 32); // false; never throws
193
+ supportedRange(); // { published, projected }: first and last dates of each, in BS and AD
194
+ ```
195
+
196
+ ### Projected dates
197
+
198
+ Dates after the last published calendar (BS 2083) convert normally. Each
199
+ `BsDate` says how far it can be trusted:
200
+
201
+ ```ts
202
+ import { adToBs, BsDate } from 'bikram-sambat-date';
203
+
204
+ BsDate.of(2083, 6, 27).confidence; // 'published'
205
+
206
+ const later = adToBs({ year: 2035, month: 1, day: 1 });
207
+ later.isProjected; // true
208
+ later.confidence; // 'projected' or 'uncertain'
209
+ ```
210
+
211
+ | `confidence` | Meaning |
212
+ | ------------ | ---------------------------------------------------------------- |
213
+ | `published` | From a published calendar. |
214
+ | `projected` | Computed. On the published years, such months were always right. |
215
+ | `uncertain` | Computed, but the month could start or end a day off. |
216
+
217
+ Where only published dates will do, such as legal or tax documents, pass
218
+ `{ strict: true }`. Projected dates then throw `ProjectedDateError`:
219
+
220
+ ```ts
221
+ adToBs({ year: 2035, month: 1, day: 1 }, { strict: true }); // throws ProjectedDateError
222
+ BsDate.of(2090, 1, 1, { strict: true }); // throws ProjectedDateError
223
+ ```
224
+
225
+ ### Errors
226
+
227
+ | Error | When |
228
+ | --------------------- | ----------------------------------------------------------------------------- |
229
+ | `DateOutOfRangeError` | The date is outside the supported range. |
230
+ | `ProjectedDateError` | With `{ strict: true }`: the date is projected, not published. |
231
+ | `InvalidDateError` | The date does not exist, such as 32 Baisakh 2083 or 30 February. |
232
+ | `DateParseError` | A string is not in the expected format, such as `BsDate.parse('2083/04/01')`. |
233
+
234
+ All extend `BikramSambatError`. `ProjectedDateError` also extends
235
+ `DateOutOfRangeError`, so code that handles out-of-range dates handles it
236
+ too.
237
+
238
+ ```ts
239
+ import { BikramSambatError, BsDate } from 'bikram-sambat-date';
240
+
241
+ try {
242
+ BsDate.of(year, month, day);
243
+ } catch (error) {
244
+ if (!(error instanceof BikramSambatError)) throw error;
245
+ // a bad or unsupported date: reject the request with a 400
246
+ }
247
+ ```
248
+
249
+ ## Supported range
250
+
251
+ | | BS | AD |
252
+ | ------------- | ------------------------ | ------------------------ |
253
+ | **Published** | 1975-01-01 to 2083-12-30 | 1918-04-13 to 2027-04-13 |
254
+ | **Projected** | 2084-01-01 to 2200-12-31 | 2027-04-14 to 2144-04-15 |
255
+
256
+ Each newly published year moves from projected to published in a release;
257
+ see
258
+ [adding a year](docs/data-sources.md#adding-a-year-when-a-new-calendar-is-published).
259
+ Keep the package up to date so that dates in the coming year are
260
+ `published`.
261
+
262
+ ## Roadmap
263
+
264
+ 1. **Foundation (done):** cross-checked table, conversion and `BsDate`.
265
+ 2. **Projected range (done):** Sūrya Siddhānta month starts through BS
266
+ 2200, with `confidence` and `{ strict: true }`.
267
+ 3. **Kathmandu time and fiscal year (done):** `fromInstant`, `today`,
268
+ `toInstant`, and `FiscalYear`.
269
+ 4. **Formatting and parsing (done):** `format` and `BsDate.parse` with
270
+ English and Nepali names and Devanagari digits.
271
+ 5. **Arithmetic (done):** add and diff days, months and years; month and
272
+ year boundaries; `monthGrid`.
273
+ 6. **NestJS helpers (done):** `@IsBsDate()`, `@ToBsDate()` and
274
+ `ParseBsDatePipe` in `bikram-sambat-date/nestjs`, and the same for
275
+ fiscal years.
276
+ 7. **Release readiness (done):** CI on Node 22, 24 and 26; package checks;
277
+ [RELEASING.md](RELEASING.md).
278
+
279
+ ## Development
280
+
281
+ ```sh
282
+ npm install
283
+ npm run check # typecheck, lint, format, data up to date, tests
284
+ npm run test:tz # tests under several time zones
285
+ npm run build # dist/: ESM, CommonJS and type definitions
286
+ npm run check:package # publint and are-the-types-wrong
287
+ npm run data:build # rebuild the calendar table from data/
288
+ npm run data:calibrate # score the projection against published years
289
+ ```
290
+
291
+ [RELEASING.md](RELEASING.md) covers releases, including the yearly one that
292
+ publishes a new calendar year.
293
+
294
+ - [docs/architecture.md](docs/architecture.md) explains how conversion works
295
+ and how the code is laid out.
296
+ - [docs/data-sources.md](docs/data-sources.md) explains where the calendar
297
+ data comes from and how to update it.
298
+ - [docs/projection.md](docs/projection.md) explains how years after the
299
+ published calendars are computed, and how accurate that is.
300
+ - [docs/time-and-fiscal-year.md](docs/time-and-fiscal-year.md) explains
301
+ instants, Kathmandu time and the fiscal year.
302
+ - [docs/formatting.md](docs/formatting.md) lists the format tokens and how
303
+ parsing reads strings.
304
+ - [docs/arithmetic.md](docs/arithmetic.md) explains adding and comparing
305
+ dates, and month grids.
306
+ - [docs/nestjs.md](docs/nestjs.md) covers validation, transformation, the
307
+ pipes, fiscal years, and how to store BS dates.
308
+
309
+ ## License
310
+
311
+ MIT. The calendar data draws on the open-source projects listed in
312
+ [NOTICE](NOTICE).