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 +21 -0
- package/NOTICE +23 -0
- package/README.md +311 -2
- package/dist/chunk-5TXZPGHY.cjs +1365 -0
- package/dist/chunk-5TXZPGHY.cjs.map +1 -0
- package/dist/chunk-P32BPDQ4.js +1344 -0
- package/dist/chunk-P32BPDQ4.js.map +1 -0
- package/dist/fiscal-year-BwwtaXya.d.cts +321 -0
- package/dist/fiscal-year-BwwtaXya.d.ts +321 -0
- package/dist/index.cjs +131 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +125 -0
- package/dist/index.d.ts +125 -0
- package/dist/index.js +63 -0
- package/dist/index.js.map +1 -0
- package/dist/nestjs/index.cjs +188 -0
- package/dist/nestjs/index.cjs.map +1 -0
- package/dist/nestjs/index.d.cts +147 -0
- package/dist/nestjs/index.d.ts +147 -0
- package/dist/nestjs/index.js +179 -0
- package/dist/nestjs/index.js.map +1 -0
- package/package.json +120 -4
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
|
-
#
|
|
1
|
+
# bikram-sambat-date
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](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).
|