tibetan-calendar-temporal 0.0.1 → 1.0.1
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/README.md +803 -48
- package/dist/astrology/calendar-day.d.ts +94 -0
- package/dist/astrology/calendar-day.js +96 -0
- package/dist/astrology/index.d.ts +295 -0
- package/dist/astrology/index.js +398 -0
- package/dist/astrology/lunar-day.d.ts +77 -0
- package/dist/astrology/lunar-day.js +83 -0
- package/dist/astrology/mansion-elements.d.ts +37 -0
- package/dist/astrology/mansion-elements.js +103 -0
- package/dist/astrology/mansion-names.d.ts +31 -0
- package/dist/astrology/mansion-names.js +139 -0
- package/dist/astrology/mansions.d.ts +79 -0
- package/dist/astrology/mansions.js +126 -0
- package/dist/astrology/month.d.ts +113 -0
- package/dist/astrology/month.js +173 -0
- package/dist/astrology/types.d.ts +84 -0
- package/dist/astrology/types.js +12 -0
- package/dist/astrology/year.d.ts +59 -0
- package/dist/astrology/year.js +110 -0
- package/dist/astrology/yoga.d.ts +170 -0
- package/dist/astrology/yoga.js +197 -0
- package/dist/computation/arithmetic.d.ts +129 -0
- package/dist/computation/arithmetic.js +180 -0
- package/dist/computation/calendar.d.ts +340 -0
- package/dist/computation/calendar.js +419 -0
- package/dist/computation/conversion.d.ts +331 -0
- package/dist/computation/conversion.js +717 -0
- package/dist/computation/corrections.d.ts +145 -0
- package/dist/computation/corrections.js +224 -0
- package/dist/computation/epoch.d.ts +113 -0
- package/dist/computation/epoch.js +178 -0
- package/dist/computation/mean-astronomy.d.ts +77 -0
- package/dist/computation/mean-astronomy.js +92 -0
- package/dist/computation/scaling.d.ts +156 -0
- package/dist/computation/scaling.js +205 -0
- package/dist/cycle-tables.d.ts +14 -0
- package/dist/cycle-tables.js +33 -0
- package/dist/cycles.d.ts +123 -0
- package/dist/cycles.js +144 -0
- package/dist/errors.d.ts +319 -0
- package/dist/errors.js +489 -0
- package/dist/format.d.ts +98 -0
- package/dist/format.js +125 -0
- package/dist/freeze.d.ts +27 -0
- package/dist/freeze.js +43 -0
- package/dist/index.d.ts +68 -0
- package/dist/index.js +65 -0
- package/dist/month-names.d.ts +180 -0
- package/dist/month-names.js +266 -0
- package/dist/months.d.ts +283 -0
- package/dist/months.js +450 -0
- package/dist/names.d.ts +54 -0
- package/dist/names.js +130 -0
- package/dist/navigation.d.ts +398 -0
- package/dist/navigation.js +591 -0
- package/dist/observances/compose.d.ts +77 -0
- package/dist/observances/compose.js +347 -0
- package/dist/observances/example-observances.d.ts +74 -0
- package/dist/observances/example-observances.js +310 -0
- package/dist/observances/forms.d.ts +103 -0
- package/dist/observances/forms.js +363 -0
- package/dist/observances/formulas.d.ts +35 -0
- package/dist/observances/formulas.js +48 -0
- package/dist/observances/index.d.ts +102 -0
- package/dist/observances/index.js +176 -0
- package/dist/observances/next.d.ts +55 -0
- package/dist/observances/next.js +142 -0
- package/dist/observances/occurrences.d.ts +30 -0
- package/dist/observances/occurrences.js +196 -0
- package/dist/observances/types.d.ts +412 -0
- package/dist/observances/types.js +24 -0
- package/dist/observances/validate.d.ts +63 -0
- package/dist/observances/validate.js +504 -0
- package/dist/parse.d.ts +76 -0
- package/dist/parse.js +165 -0
- package/dist/rabjung-names.d.ts +31 -0
- package/dist/rabjung-names.js +343 -0
- package/dist/temporal-kind.d.ts +102 -0
- package/dist/temporal-kind.js +272 -0
- package/dist/traditions/bhutan.d.ts +70 -0
- package/dist/traditions/bhutan.js +142 -0
- package/dist/traditions/phugpa.d.ts +76 -0
- package/dist/traditions/phugpa.js +170 -0
- package/dist/traditions/types.d.ts +336 -0
- package/dist/traditions/types.js +24 -0
- package/dist/traditions/validate.d.ts +99 -0
- package/dist/traditions/validate.js +573 -0
- package/dist/types.d.ts +835 -0
- package/dist/types.js +362 -0
- package/docs/guide.md +1208 -0
- package/docs/how-it-is-calculated.md +361 -0
- package/docs/why-trust-these-dates.md +257 -0
- package/package.json +63 -8
- package/index.js +0 -5
package/README.md
CHANGED
|
@@ -1,64 +1,798 @@
|
|
|
1
1
|
# tibetan-calendar-temporal
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Compute Tibetan calendar dates in JavaScript — leap months, doubled and skipped days, moon phases,
|
|
4
|
+
year names and observances — for almanac applications, practice calendars, and anything that has to
|
|
5
|
+
show a Tibetan date and be right about it.
|
|
6
|
+
|
|
7
|
+
It computes two calendars: **Phugpa**, the Men-Tsee-Khang standard and the basis of the almanacs most
|
|
8
|
+
practitioners use, which is the default; and the **Bhutanese** calendar of the Royal Government of Bhutan.
|
|
9
|
+
The **Tsurphu** (Karma Kagyu) and **Mongolian** calendars are **not included**: the engine can express
|
|
10
|
+
them as configuration, but neither has been checked against an almanac of its own — see
|
|
11
|
+
[Traditions](#traditions).
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npm install tibetan-calendar-temporal
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
```js
|
|
18
|
+
import { isoToTibetan, formatTibetanDate, yearNameFor, rabjungFor } from 'tibetan-calendar-temporal';
|
|
19
|
+
|
|
20
|
+
const day = isoToTibetan(Temporal.PlainDate.from('2026-08-23'));
|
|
21
|
+
|
|
22
|
+
formatTibetanDate(day); // "2153-M07-11"
|
|
23
|
+
day.weekdayName.phonetic; // "nyima" — Sunday, the sun's day
|
|
24
|
+
day.isFullMoon; // false
|
|
25
|
+
yearNameFor(day.year).element; // "fire" — Fire Male Horse year
|
|
26
|
+
rabjungFor(day.year); // { cycle: 17, year: 40, … }
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Zero runtime dependencies, MIT licensed, built on [Temporal](https://tc39.es/proposal-temporal/docs/).
|
|
30
|
+
Every date it returns can be traced to a source and a range of years —
|
|
31
|
+
see [why you can trust these dates](docs/why-trust-these-dates.md).
|
|
32
|
+
|
|
33
|
+
## Contents
|
|
34
|
+
|
|
35
|
+
- [What you get](#what-you-get)
|
|
36
|
+
- [Why you can trust the dates](#why-you-can-trust-the-dates)
|
|
37
|
+
- [How this compares](#how-this-compares)
|
|
38
|
+
- [Requirements](#requirements)
|
|
39
|
+
- [Usage](#usage)
|
|
40
|
+
- [Converting a Western date](#converting-a-western-date)
|
|
41
|
+
- [Converting back](#converting-back)
|
|
42
|
+
- [Building a month grid](#building-a-month-grid)
|
|
43
|
+
- [Naming a year](#naming-a-year)
|
|
44
|
+
- [Errors and validation](#errors-and-validation)
|
|
45
|
+
- [Traditions](#traditions)
|
|
46
|
+
- [Observances](#observances)
|
|
47
|
+
- [Astrological attributes](#astrological-attributes)
|
|
48
|
+
- [API](#api)
|
|
49
|
+
- [Internationalisation](#internationalisation)
|
|
50
|
+
- [Provenance](#provenance)
|
|
51
|
+
- [Project identity](#project-identity)
|
|
52
|
+
- [Documentation](#documentation)
|
|
53
|
+
- [Licence](#licence)
|
|
54
|
+
|
|
55
|
+
## What you get
|
|
56
|
+
|
|
57
|
+
| | |
|
|
58
|
+
|---|---|
|
|
59
|
+
| **Conversion, both ways** | Western ↔ Tibetan, total in both directions. Every calendar day has a Tibetan date; a Tibetan date that no day carries is reported rather than guessed |
|
|
60
|
+
| **The hard cases, handled** | Leap months, doubled days and skipped days — the three things that make this calendar a calculation rather than a lookup. Roughly one of each every couple of months |
|
|
61
|
+
| **Month grids** | A year's months in calendar order with their boundaries, and one entry per calendar day of a month, so a grid needs no arithmetic of its own |
|
|
62
|
+
| **A full almanac row** | Fifteen fields per date: royal-era year, month code, day, true full and new moon, ISO and Tibetan weekday with its planet and element. The element–animal year name and the rabjung cycle position are properties of the *year*, so they are closed-form lookups rather than one value repeated on all 354 days |
|
|
63
|
+
| **Names in three renderings** | Tibetan script, Wylie, and THL Simplified phonetics (with eleven recorded corrections) for every weekday, element, gender, animal and rabjung year — each checked by machine against independent sources before it shipped |
|
|
64
|
+
| **Observances** | The great holy days and the monthly cycle, as configurable rules. Each result says *how* it landed on its day, so a display can show the almanac's footnote instead of presenting a moved date as an exact one |
|
|
65
|
+
| **Astrological attributes** | What kind of day it is, not just which day: the year's five elements, the month's and lunar day's labels, the calendar day's own, and the elemental yoga — which needs the moon's real position, not a cycle. A separate subpath, sourced piece by piece |
|
|
66
|
+
| **Two calendars, four configs** | Phugpa and Bhutanese, each in two parameterisations. Constants and rules are injected as data, so a further tradition is a config object rather than a code change; Tsurphu and Mongolian are expressible that way but not shipped, because no almanac has checked them |
|
|
67
|
+
| **Date arithmetic** | Add days or months, count between two dates, find the next true full or new moon, and reduce a month to one sortable integer for a database key |
|
|
68
|
+
| **Fast, and computed rather than looked up** | No date tables, no network, nothing asynchronous: every answer is integer arithmetic done on the spot, identical on every platform. On a 2026 laptop a conversion takes about 7 µs, a month grid about 0.14 ms and a year of observances in 2–3 ms, so it can run in a render path — [measured, with the machine](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/bench/RESULTS.md#re-recorded-2026-11-18) |
|
|
69
|
+
|
|
70
|
+
Everything is a pure function over plain objects. No classes, no instances, no hidden state.
|
|
71
|
+
|
|
72
|
+
**Why `Temporal.PlainDate`, and never `Date`.** Temporal is the language's replacement for `Date` —
|
|
73
|
+
a finished (stage 4) TC39 proposal, expected in ES2027, already shipping in Node 26, Chrome and
|
|
74
|
+
Firefox. MDN describes it as "designed as a full replacement for the `Date` object", and is blunt
|
|
75
|
+
about why one was needed: `Date` copies `java.util.Date`, a class Java itself replaced in the early
|
|
76
|
+
2010s, and survives only because JavaScript does not break backwards compatibility. So this is not
|
|
77
|
+
an exotic choice; it is the standard one, taken early.
|
|
78
|
+
|
|
79
|
+
It is also the only workable one here. `Date` can express **only the Gregorian calendar** — and
|
|
80
|
+
this package's entire job is a calendar that is not Gregorian. Beyond that, a `Date` is not a date
|
|
81
|
+
at all: it is a timestamp, and it always carries a time and an offset. Ask it for
|
|
82
|
+
"18 February 2026" and what you get is an instant, which lands on a different calendar day
|
|
83
|
+
depending on where the user is sitting.
|
|
84
|
+
For a Western calendar that is a nuisance; for this one it is a wrong answer, because a Tibetan
|
|
85
|
+
date labels a **whole day** whose boundary is already fixed in the arithmetic. `PlainDate` is
|
|
86
|
+
precisely that type — a calendar day, no time, no zone — so the commonest bug in date handling
|
|
87
|
+
cannot be expressed. It is also immutable, so a date this library hands you cannot be altered
|
|
88
|
+
underneath another caller, and it is a language built-in, which is how the package has zero
|
|
89
|
+
dependencies while still doing calendar arithmetic. [More on the day
|
|
90
|
+
boundary](docs/guide.md#where-a-day-begins).
|
|
91
|
+
|
|
92
|
+
## Why you can trust the dates
|
|
93
|
+
|
|
94
|
+
The engine is a clean-room implementation of Svante Janson's *Tibetan Calendar Mathematics*, and
|
|
95
|
+
every claim it makes about agreement comes with the range of years over which that agreement was
|
|
96
|
+
checked. Agreement quoted without its window is not evidence.
|
|
97
|
+
|
|
98
|
+
It also states what is *not* established — which traditions are expressible but unshipped, where it
|
|
99
|
+
differs from a published almanac and why, and which questions no available source can settle.
|
|
100
|
+
|
|
101
|
+
**[Read the full account →](docs/why-trust-these-dates.md)**
|
|
102
|
+
|
|
103
|
+
## How this compares
|
|
104
|
+
|
|
105
|
+
| | `tibetan-date-calculator` | `@hnw/date-tibetan` | Henning's software | this package |
|
|
106
|
+
|---|---|---|---|---|
|
|
107
|
+
| Date type | legacy `Date` | `Date` + Julian day | writes text files | `Temporal.PlainDate` |
|
|
108
|
+
| Traditions | Phugpa | 3, as fixed classes | Phugpa, Tsurphu, Zhonnu Pal | 4 configs, more addable as data |
|
|
109
|
+
| What a date carries | ~9 properties | a 6-element tuple | text columns | 15 fields, names in three scripts |
|
|
110
|
+
| Observances | — | — | hardcoded columns | configurable, with resolutions |
|
|
111
|
+
| Astrological data | — | — | **planets, lunar mansions, eclipses** | attributes and the yoga; no planets or eclipses |
|
|
112
|
+
| Stated validated range | — | — | — | every claim carries its window |
|
|
113
|
+
|
|
114
|
+
Henning's software computes a full astrological almanac — planets and eclipses included — which this
|
|
115
|
+
package does not attempt, and
|
|
116
|
+
`@hnw/date-tibetan` is the shortest route to a Mongolian date. **[When to use which
|
|
117
|
+
→](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/other-implementations.md)**
|
|
118
|
+
|
|
119
|
+
## Requirements
|
|
120
|
+
|
|
121
|
+
**Node 26 or later**, where `Temporal` is enabled by default. The package does not bundle a
|
|
122
|
+
polyfill — that is what keeps it at zero runtime dependencies — so on any older runtime, and in a
|
|
123
|
+
browser, you supply one.
|
|
124
|
+
|
|
125
|
+
The failure mode if you do not is **not** a helpful `TypeError` at the call that needed a date. The
|
|
126
|
+
engine touches `Temporal` while the module is evaluating, so a runtime without it fails on
|
|
127
|
+
`import`, before your code has called anything:
|
|
128
|
+
|
|
129
|
+
```js
|
|
130
|
+
import 'tibetan-calendar-temporal';
|
|
131
|
+
// Error: tibetan-calendar-temporal requires the Temporal API, which is not available in this
|
|
132
|
+
// runtime. Temporal ships enabled from Node 26; Node 24 has it behind --harmony-temporal. On
|
|
133
|
+
// older runtimes or in a browser, import a polyfill before this package:
|
|
134
|
+
// `import "temporal-polyfill/global";`
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
That message is a guard the package raises deliberately. Without it you would get a bare
|
|
138
|
+
`ReferenceError: Temporal is not defined` naming neither the requirement nor the fix.
|
|
139
|
+
|
|
140
|
+
**Using a polyfill.** Install [`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill)
|
|
141
|
+
and import it once, before this package, in your app's entry module:
|
|
142
|
+
|
|
143
|
+
```js
|
|
144
|
+
import 'temporal-polyfill/global';
|
|
145
|
+
import { isoToTibetan } from 'tibetan-calendar-temporal';
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
The same applies in a browser: `Temporal` ships in Chrome, Edge and Firefox but not yet in Safari.
|
|
149
|
+
`temporal-polyfill/global` installs nothing where `Temporal` already exists, so a test suite on
|
|
150
|
+
Node 26 that imports it has not tested the polyfill; [the guide](docs/guide.md#using-a-polyfill)
|
|
151
|
+
shows how to force it.
|
|
152
|
+
|
|
153
|
+
**Node 24 has `--harmony-temporal`, and you should not use it here.** That flag exposes V8's
|
|
154
|
+
unfinished implementation — it is behind a flag because it is not done — and nothing here has been
|
|
155
|
+
run against it. A polyfill is an implementation too, and the reason to prefer it is evidence rather
|
|
156
|
+
than principle: this package's output under `temporal-polyfill` and `@js-temporal/polyfill` has been
|
|
157
|
+
compared with its output under the built-in `Temporal` and found identical — see
|
|
158
|
+
[why you can trust these dates](docs/why-trust-these-dates.md#why-the-results-are-identical-everywhere).
|
|
159
|
+
Use the polyfill.
|
|
160
|
+
|
|
161
|
+
`engines` declares `">=26"`, which npm treats as **advisory** — a warning on install, not a block —
|
|
162
|
+
so a polyfilled Node 22 or 24 project works fine. See
|
|
163
|
+
[the guide](docs/guide.md#running-it-anywhere) for `engine-strict` and the rest.
|
|
164
|
+
|
|
165
|
+
**TypeScript 7 or later, if you type-check.** This is a *separate* requirement from the runtime one
|
|
166
|
+
above and is not implied by it. The ambient `Temporal` namespace type ships in TypeScript's own lib
|
|
167
|
+
files only from 7.0 (`lib.esnext.temporal.d.ts`), so on the 5.x line every declaration file here
|
|
168
|
+
that mentions a date fails with `TS2503: Cannot find namespace 'Temporal'` — which is all of them,
|
|
169
|
+
because dates are the product. **You can satisfy every runtime requirement on this page, on Node 26,
|
|
170
|
+
and still not compile a line.** If you see that error, this is the axis to check.
|
|
171
|
+
|
|
172
|
+
```sh
|
|
173
|
+
npm i -D typescript@^7
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
No `"lib"` setting is needed **if your `target` is `ESNext`** — that is what carries
|
|
177
|
+
`lib.esnext.temporal.d.ts`. Under `nodenext` with no `target` set, TypeScript 7.0.2 still reports
|
|
178
|
+
`TS2503` against this package. Set `"target": "ESNext"`, as
|
|
179
|
+
[the guide's tsconfig](docs/guide.md#type-checking-needs-typescript-7-which-the-runtime-requirement-does-not-imply)
|
|
180
|
+
does, or add `"lib": ["ES2024", "ESNext.Temporal"]`. And do **not** install
|
|
181
|
+
`temporal-polyfill`, `temporal-spec` or any other typings package to fix it: they are unnecessary
|
|
182
|
+
here, and the published `.d.ts` references the global deliberately. `engines` constrains only
|
|
183
|
+
`node`; npm has no field for the TypeScript version a package's *types* require, which is why this
|
|
184
|
+
lives in prose.
|
|
185
|
+
|
|
186
|
+
## Usage
|
|
187
|
+
|
|
188
|
+
### Converting a Western date
|
|
189
|
+
|
|
190
|
+
```js
|
|
191
|
+
import { isoToTibetan, formatTibetanDate } from 'tibetan-calendar-temporal';
|
|
192
|
+
|
|
193
|
+
const date = isoToTibetan(Temporal.PlainDate.from('2026-08-12'));
|
|
194
|
+
|
|
195
|
+
formatTibetanDate(date); // "2153-M06-30"
|
|
196
|
+
date.month; // 6
|
|
197
|
+
date.day; // 30
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
The full object:
|
|
201
|
+
|
|
202
|
+
```json
|
|
203
|
+
{
|
|
204
|
+
"year": 2153,
|
|
205
|
+
"yearStartsIn": 2026,
|
|
206
|
+
"month": 6,
|
|
207
|
+
"monthCode": "M06",
|
|
208
|
+
"isLeapMonth": false,
|
|
209
|
+
"day": 30,
|
|
210
|
+
"isDoubledDay": false,
|
|
211
|
+
"isLeapDay": false,
|
|
212
|
+
"isFullMoon": false,
|
|
213
|
+
"isNewMoon": true,
|
|
214
|
+
"isoDate": "2026-08-12",
|
|
215
|
+
"dayOfWeek": 3,
|
|
216
|
+
"tibetanWeekday": 4,
|
|
217
|
+
"weekdayName": { "tibetan": "ལྷག་པ", "wylie": "lhag pa", "phonetic": "lhakpa",
|
|
218
|
+
"planet": "mercury", "element": "water" },
|
|
219
|
+
"lunation": 15094
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### Converting back
|
|
224
|
+
|
|
225
|
+
```js
|
|
226
|
+
import { tibetanToIso } from 'tibetan-calendar-temporal';
|
|
227
|
+
|
|
228
|
+
tibetanToIso({ year: 2153, month: 6, day: 30 }).toString(); // "2026-08-12"
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
`year` is the **royal-era** number an almanac prints (2153), not the Gregorian year the Tibetan
|
|
232
|
+
year began in (2026, exposed as `yearStartsIn`). The two differ by 127.
|
|
233
|
+
|
|
234
|
+
> **This is the one mistake the library cannot catch for you.** Passing Gregorian 2026 where
|
|
235
|
+
> royal-era 2153 is meant returns a well-formed date in **1899** — because 2026 *is* a valid
|
|
236
|
+
> royal-era year. No guard can tell the two apart, so nothing throws. If your years come from user
|
|
237
|
+
> input or another system, convert explicitly and sanity-check the result:
|
|
4
238
|
>
|
|
5
|
-
>
|
|
6
|
-
>
|
|
239
|
+
> ```js
|
|
240
|
+
> const tibetanYear = gregorianYear + 127;
|
|
241
|
+
> const date = tibetanToIso({ year: tibetanYear, month: 6, day: 30 });
|
|
242
|
+
> // Or check after the fact, which also catches an off-by-one at a year boundary:
|
|
243
|
+
> isoToTibetan(date).yearStartsIn; // should be the Gregorian year you started from
|
|
244
|
+
> ```
|
|
245
|
+
|
|
246
|
+
### Building a month grid
|
|
247
|
+
|
|
248
|
+
`monthsFor` gives a year's months in calendar order, and where a leap month sits depends on the
|
|
249
|
+
tradition: under `PHUGPA` — the default, and the example below — it sits immediately **before** the
|
|
250
|
+
regular month it shares a number with, while `BHUTAN` numbers from the preceding month, so its leap
|
|
251
|
+
month **follows** its twin. Reconstructing that ordering yourself is the part most easily got wrong,
|
|
252
|
+
which is why `monthsFor` and `datesFor` exist; prefer them to a hand-rolled walk.
|
|
253
|
+
|
|
254
|
+
**A tradition's months are not the other's renumbered, and the leap pair is not even in the same
|
|
255
|
+
place.** Switching config does not just flip the pair around; it changes which lunation is doubled
|
|
256
|
+
and renumbers everything after it. For 2151 the thirteen lunations are the same thirteen, but:
|
|
257
|
+
|
|
258
|
+
```text
|
|
259
|
+
PHUGPA M01 M02 M03 M04 M05 M06L M06 M07 M08 M09 M10 M11 M12
|
|
260
|
+
BHUTAN M01 M02 M03 M04 M05 M06 M07 M08 M08L M09 M10 M11 M12
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
`leapMonthNumberFor(2151)` is **6** under `PHUGPA` and **8** under `BHUTAN`, and Phugpa's `M06L` is
|
|
264
|
+
Bhutan's `M06`. So a month identified as `(year, month, isLeapMonth)` under one tradition names a
|
|
265
|
+
different month under the other — always pair a stored month with the config it came from.
|
|
266
|
+
|
|
267
|
+
```js
|
|
268
|
+
import { monthsFor, hasLeapMonth, leapMonthNumberFor } from 'tibetan-calendar-temporal';
|
|
269
|
+
|
|
270
|
+
const months = monthsFor(2151);
|
|
271
|
+
months.length; // 13
|
|
272
|
+
months.map((m) => m.monthCode).join(' ');
|
|
273
|
+
// "M01 M02 M03 M04 M05 M06L M06 M07 M08 M09 M10 M11 M12"
|
|
274
|
+
|
|
275
|
+
hasLeapMonth(2151); // true
|
|
276
|
+
leapMonthNumberFor(2151); // 6
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
Each month carries its own boundaries, so a grid needs no further conversion to lay out:
|
|
280
|
+
|
|
281
|
+
`lunation` is also on every `TibetanDate`, carrying the month that date falls in — so a date has a
|
|
282
|
+
direct route back to its own month rather than needing a two-key search that is easy to get wrong
|
|
283
|
+
across a leap pair.
|
|
284
|
+
|
|
285
|
+
```js
|
|
286
|
+
const month = monthsFor(2153)[0];
|
|
287
|
+
month.year; // 2153
|
|
288
|
+
month.yearName; // { element: 'fire', animal: 'horse', gender: 'male' }
|
|
289
|
+
month.monthCode; // "M01"
|
|
290
|
+
month.days; // 29
|
|
291
|
+
month.firstDay.toString(); // "2026-02-18" — Losar
|
|
292
|
+
month.lastDay.toString(); // "2026-03-18"
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
A month identifies itself, so it can be passed on without the year travelling separately:
|
|
296
|
+
|
|
297
|
+
```js
|
|
298
|
+
daysInMonth(month); // 29 — a TibetanMonth is accepted directly
|
|
299
|
+
tibetanDateExists({ ...month, day: 8 }); // true
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
> **`days` counts calendar days, not date numbers.** Date numbers always run 1–30; the span is 29 or
|
|
303
|
+
> 30, because some numbers are skipped and some are carried by two days. So `for (d = 1; d <= days;
|
|
304
|
+
> d++)` builds a **wrong** grid.
|
|
305
|
+
>
|
|
306
|
+
> **Use `datesFor`.** It walks the month and hands back one `TibetanDate` per calendar day, each
|
|
307
|
+
> carrying both the number to print and the ISO date it falls on, so there is no walk to get wrong:
|
|
7
308
|
>
|
|
8
|
-
>
|
|
9
|
-
>
|
|
309
|
+
> ```js
|
|
310
|
+
> for (const date of datesFor(month)) {
|
|
311
|
+
> render(date.day, date.isoDate); // date.day is the number to print — never the loop index
|
|
312
|
+
> }
|
|
313
|
+
> ```
|
|
314
|
+
|
|
315
|
+
A grid usually needs cells on either side of the month — the days that finish the previous month and
|
|
316
|
+
start the next, so the first row can begin on the right weekday. Those are not this month's days, so
|
|
317
|
+
`datesFor` does not produce them: step **ISO** days and convert each one. `isoToTibetan` is total, so
|
|
318
|
+
the walk never has to know where the neighbouring month began or whether it was a leap month, and
|
|
319
|
+
each result carries the month it belongs to.
|
|
320
|
+
|
|
321
|
+
```js
|
|
322
|
+
let day = month.firstDay.subtract({ days: 3 });
|
|
10
323
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
324
|
+
for (let i = 0; i < 3; i++, day = day.add({ days: 1 })) {
|
|
325
|
+
const date = isoToTibetan(day);
|
|
326
|
+
formatTibetanDate(date); // "2152-M12-28", then "2152-M12-29", then "2152-M12-30"
|
|
327
|
+
}
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
Use it only for the cells outside the month: inside it, `datesFor` is what keeps a doubled or
|
|
331
|
+
skipped date number right.
|
|
14
332
|
|
|
15
|
-
|
|
16
|
-
|
|
333
|
+
`hasLeapMonth`, `leapMonthNumberFor` and `monthsInYear` are closed forms over the year and never touch
|
|
334
|
+
lunar arithmetic, so reach for them rather than for `monthsFor(y).length` when the months themselves
|
|
335
|
+
are not wanted.
|
|
17
336
|
|
|
18
|
-
|
|
337
|
+
`datesFor` lays out one month's calendar days; combine it with `monthsFor` to build a whole year —
|
|
338
|
+
`monthsFor(2153).flatMap((month) => datesFor(month))` gives 354 entries.
|
|
339
|
+
[The guide](docs/guide.md#the-cost-of-a-year) records what a year costs to serialise.
|
|
19
340
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
|
|
341
|
+
**Wrap the callback; do not pass one of these functions to `map` or `flatMap` point-free.**
|
|
342
|
+
`flatMap` calls back with `(value, index, array)`, and the second parameter of every function here
|
|
343
|
+
that takes a `TraditionConfig` is that config — so the array index lands in the config slot and the
|
|
344
|
+
call throws `TCT_INVALID_TRADITION_CONFIG`. TypeScript refuses it outright; JavaScript gets a throw
|
|
345
|
+
rather than a wrong calendar. A function whose signature ends at its first parameter survives
|
|
346
|
+
point-free use, `yearNameFor` and `rabjungFor` among them; wrapping costs nothing and is never wrong,
|
|
347
|
+
so wrap.
|
|
27
348
|
|
|
28
|
-
|
|
349
|
+
### Naming a year
|
|
29
350
|
|
|
30
351
|
```js
|
|
31
|
-
|
|
352
|
+
const losar = isoToTibetan(Temporal.PlainDate.from('2026-02-18'));
|
|
353
|
+
|
|
354
|
+
formatTibetanDate(losar); // "2153-M01-01" — Losar, Tibetan New Year
|
|
355
|
+
yearNameFor(losar.year); // { element: 'fire', animal: 'horse', gender: 'male' }
|
|
356
|
+
rabjungFor(losar.year); // { cycle: 17, year: 40, tibetanName: { … } }
|
|
32
357
|
```
|
|
33
358
|
|
|
34
|
-
|
|
35
|
-
|
|
359
|
+
**Year naming is a lookup, not a field on the date.** Both are closed forms over the year alone —
|
|
360
|
+
three modulos, no lunar arithmetic — so they take a year number and never a date. Putting them on
|
|
361
|
+
every date would repeat one value across all 354 days of the year, which was more than half of what
|
|
362
|
+
a serialised year cost.
|
|
36
363
|
|
|
37
|
-
|
|
364
|
+
`yearNameFor` gives the element–animal name practitioners recognise. `rabjungFor` gives the Indian
|
|
365
|
+
60-year cycle, which is a *numbering* rather than a name — and it indexes the year differently, so
|
|
366
|
+
the two are kept apart deliberately. See
|
|
367
|
+
[docs/development/architecture.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/development/architecture.md#why-rabjung-is-separate-from-yearname).
|
|
38
368
|
|
|
39
|
-
|
|
369
|
+
### Errors and validation
|
|
370
|
+
|
|
371
|
+
Two failure kinds, and telling them apart matters because they call for different responses.
|
|
372
|
+
|
|
373
|
+
**A skipped date is not an error in your code.** It is a fact about the calendar, and the right
|
|
374
|
+
response is usually to show the user something rather than to log a bug. It arrives as
|
|
375
|
+
`SkippedDayError`, the only error class this package exports.
|
|
40
376
|
|
|
41
|
-
|
|
377
|
+
**Every other failure about your input is a `RangeError`** carrying a machine-readable `code`; the
|
|
378
|
+
two that are not about your input are plain `Error`s, listed in the [API section](#errors). Branch on `error.code`,
|
|
379
|
+
never on the message text — codes are part of the API and never change; wording is not and may
|
|
380
|
+
improve in any release.
|
|
42
381
|
|
|
43
|
-
|
|
382
|
+
```js
|
|
383
|
+
tibetanDateExists({ year: 2150, month: 12, day: 29 }); // false — skipped
|
|
384
|
+
tibetanDateExists({ year: 2153, month: 13, day: 1 }); // false — no such month
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
`tibetanDateExists` is `false` exactly where `tibetanToIso` throws for a reason about the *date*.
|
|
388
|
+
It deliberately still throws on a malformed `TraditionConfig`, because that is a bug in your program
|
|
389
|
+
rather than a statement about a date. The full code list is in the [API section](#errors); the
|
|
390
|
+
worked `switch` over every code is in [the guide](docs/guide.md#handling-errors).
|
|
44
391
|
|
|
45
|
-
|
|
46
|
-
app (integrated modular PWA, separate repo). The app has additional modules — Meditation Timer,
|
|
47
|
-
Vow Tracker — but this library is the foundation: it computes what days are significant and
|
|
48
|
-
why.
|
|
392
|
+
### Traditions
|
|
49
393
|
|
|
50
|
-
|
|
394
|
+
**v1 ships two calendars in four configurations.** Phugpa (*phug pa*) is the Men-Tsee-Khang
|
|
395
|
+
standard and the basis of the almanacs most practitioners use; Bhutanese is the calendar of the
|
|
396
|
+
Royal Government of Bhutan. Each ships twice, because each has two defensible parameterisations:
|
|
51
397
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
398
|
+
```js
|
|
399
|
+
import { PHUGPA, PHUGPA_HENNING, BHUTAN, BHUTAN_HENNING } from 'tibetan-calendar-temporal';
|
|
400
|
+
|
|
401
|
+
const day = Temporal.PlainDate.from('2025-11-19');
|
|
402
|
+
|
|
403
|
+
formatTibetanDate(isoToTibetan(day)); // "2152-M09-30 (leap)"
|
|
404
|
+
formatTibetanDate(isoToTibetan(day, PHUGPA_HENNING)); // "2152-M09-29"
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
The two differ in exactly one constant, the lunar anomaly increment `a₂`, and are otherwise
|
|
408
|
+
identical — a test asserts that. `PHUGPA` uses `a₂ = 1/28`, the value almanacs use, and is the
|
|
409
|
+
right default for nearly everyone. `PHUGPA_HENNING` uses Henning's exact `3781/105840`.
|
|
410
|
+
`BHUTAN` and `BHUTAN_HENNING` split the same way. Bhutan also places its leap month *after* the
|
|
411
|
+
regular month sharing its number, where every other version places it before, and names its weekdays
|
|
412
|
+
one planet ahead of Tibet — both are configuration, not special cases in the arithmetic.
|
|
413
|
+
|
|
414
|
+
They disagree on about **one day in 4,100 days** — nine days in the twentieth century and eight in
|
|
415
|
+
the twenty-first, `2025-11-19` above being one of them. That is a long-run average rather than a
|
|
416
|
+
schedule, and the divergences cluster: Janson counts sixteen in the 65 years from 1027, so
|
|
417
|
+
back-projection is worse than the headline rate suggests. All three counts are reproduced by the
|
|
418
|
+
engine and asserted in `test/computation/conversion.test.ts`. The evidence for the default is in
|
|
419
|
+
[docs/decisions/2026-08-12-lunar-anomaly-a2-default.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/decisions/2026-08-12-lunar-anomaly-a2-default.md).
|
|
420
|
+
|
|
421
|
+
**Two other versions are not shipped: Tsurphu** (*mtshur phu*), the Karma Kagyu system, **and the
|
|
422
|
+
Mongolian** calendar, used in Mongolia and by the Buryats and Tuvinians. Neither ships because nothing
|
|
423
|
+
here has been validated against an almanac of its own, and an unvalidated calendar published with
|
|
424
|
+
this library's authority is exactly the failure this project exists to avoid — not because the
|
|
425
|
+
algorithm cannot express them. For a Mongolian date today, `@hnw/date-tibetan` is the shortest
|
|
426
|
+
route; see [when to use which](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/other-implementations.md).
|
|
427
|
+
|
|
428
|
+
It can. Every astronomical constant is injected through a `TraditionConfig` rather than hardcoded,
|
|
429
|
+
including the scaling denominator, which is *derived* from the constants rather than fixed — Phugpa
|
|
430
|
+
gives 102,317,040 and Tsurphu gives 1,534,755,600. So adding Tsurphu is a new config object, from
|
|
431
|
+
Janson's Appendix A.2, and no change to any computation module:
|
|
432
|
+
|
|
433
|
+
```js
|
|
434
|
+
const TSURPHU = { ...PHUGPA, id: 'tsurphu', name: 'Tsurphu', /* …Janson App. A.2 constants… */ };
|
|
435
|
+
|
|
436
|
+
isoToTibetan(Temporal.PlainDate.from('2026-08-12'), TSURPHU);
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
Configs are validated when first used, so a partial or mistyped one is rejected with the offending
|
|
440
|
+
field named rather than failing somewhere inside the arithmetic. Every field is documented where your
|
|
441
|
+
editor shows it, on the `TraditionConfig` type in the package's own declarations; the design behind
|
|
442
|
+
them is in
|
|
443
|
+
[docs/development/architecture.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/development/architecture.md#core-types). Note that validation checks **shape, not
|
|
444
|
+
astronomy** — plausible constants that are wrong will produce a plausible calendar that is wrong,
|
|
445
|
+
which is what [docs/development/testing.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/development/testing.md) exists to catch.
|
|
446
|
+
|
|
447
|
+
### Observances
|
|
448
|
+
|
|
449
|
+
Which days an institution marks — the great holy days and the monthly cycle — ship behind a
|
|
450
|
+
separate subpath:
|
|
451
|
+
|
|
452
|
+
```js
|
|
453
|
+
import { getObservances, observancesOn, EXAMPLE_OBSERVANCES } from 'tibetan-calendar-temporal/observances';
|
|
454
|
+
|
|
455
|
+
const duchen = getObservances(
|
|
456
|
+
Temporal.PlainDate.from('2026-01-01'),
|
|
457
|
+
Temporal.PlainDate.from('2026-12-31'),
|
|
458
|
+
EXAMPLE_OBSERVANCES,
|
|
459
|
+
).filter((o) => o.rule.tags?.includes('duchen'));
|
|
460
|
+
|
|
461
|
+
duchen.map((o) => `${o.rule.englishName}: ${o.date.isoDate}`);
|
|
462
|
+
// [ "Day of Miracles: 2026-03-03",
|
|
463
|
+
// "Lord Buddha's birth, enlightenment and parinirvana: 2026-05-31",
|
|
464
|
+
// "Lord Buddha's first teaching: 2026-07-18",
|
|
465
|
+
// "Lord Buddha's descent from God Realm of Thirty Three: 2026-11-01" ]
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
Each `Observance` has three fields that are always there — `date`, the `TibetanDate` it falls on and
|
|
469
|
+
always a real calendar day; `rule`, the rule that produced it, carrying `id`, `englishName`, and the
|
|
470
|
+
`level` and `tags` the config gave it; and `resolution`, how it landed there — and two that appear only
|
|
471
|
+
where they apply: `age`, the years since a rule's `ageFromYear`, and `period`, the first and last
|
|
472
|
+
calendar days of the whole span a `period` rule's day belongs to. The `rule` is the engine's own deeply frozen copy, made when the config was first used, and never the object you
|
|
473
|
+
passed: changing your config afterwards changes neither this nor any later answer, and a fresh object is checked and copied again.
|
|
474
|
+
|
|
475
|
+
**`EXAMPLE_OBSERVANCES` ships nineteen rules**, as an example of how to populate a config and not as any
|
|
476
|
+
institution's calendar: the four great days (tagged `duchen`), seven persons' days (tagged `anniversary`),
|
|
477
|
+
the whole of Saga Dawa, sojong, the fire puja, and the monthly Medicine Buddha, Tara, Heruka, Ḍākinī and
|
|
478
|
+
Dharma Protector days. Each rule names a `level` the config declares, so a front end can group what is for
|
|
479
|
+
everyone apart from what needs an empowerment, and fourteen carry a verified Tibetan name.
|
|
480
|
+
Sojong is a **counted schedule** — each Tibetan year's count starts on the full moon of month 1, and a fortnight
|
|
481
|
+
is 14 or 15 days — inferred from one published calendar that states no method; the fire puja is a formula
|
|
482
|
+
over the day number and the weekday. Neither is the tradition's own statement of a rule, and
|
|
483
|
+
[what each is checked against](docs/why-trust-these-dates.md)
|
|
484
|
+
is stated there, with its window.
|
|
485
|
+
|
|
486
|
+
It is a separate import for a reason. Everything on the root export makes a **falsifiable** claim:
|
|
487
|
+
a constant checks against Janson, a date against an almanac, and a disagreement is a bug. Nothing
|
|
488
|
+
here does. Which half of a doubled day an observance falls on, and whether it is kept in a leap
|
|
489
|
+
month at all, are **conventions**, and the published sources disagree — Janson, following Berzin,
|
|
490
|
+
says the first of a doubled pair; FPMT says the second. So the conventions are injected data,
|
|
491
|
+
cited in its docblocks and docs, never logic, and a consumer who only wants date conversion never
|
|
492
|
+
inherits anyone's.
|
|
493
|
+
|
|
494
|
+
### Astrological attributes
|
|
495
|
+
|
|
496
|
+
*What kind of day is this?* — the question an almanac view asks after it has the date. A separate
|
|
497
|
+
subpath, so a consumer who only converts dates never loads it.
|
|
498
|
+
|
|
499
|
+
```ts
|
|
500
|
+
import { attributesFor } from "tibetan-calendar-temporal/astrology";
|
|
501
|
+
|
|
502
|
+
const day = attributesFor(Temporal.PlainDate.from("2026-09-01"));
|
|
503
|
+
|
|
504
|
+
day.year.power; // "fire" — 2026 is a Fire Horse year
|
|
505
|
+
day.year.life; // "fire", and body, fortune and spirit each run on their own cycle
|
|
506
|
+
day.calendarDay.animal; // the sunrise-to-sunrise day's animal
|
|
507
|
+
day.lunarDay?.animal; // the lunar day's, which is a different label for the same date
|
|
508
|
+
day.yoga?.englishName; // "death" — the least auspicious of the ten
|
|
509
|
+
day.yoga?.favorable; // false
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
**A day carries two sets of labels that disagree, and almanacs print both.** The lunar day is the
|
|
513
|
+
thirtieth of a lunation; the calendar day runs sunrise to sunrise. On a doubled date the two halves
|
|
514
|
+
share `year`, `month` and `lunarDay` and differ in `calendarDay`, and can differ in `yoga` and
|
|
515
|
+
`lunarMansion` — that is the calendar, not a bug.
|
|
516
|
+
|
|
517
|
+
**`month`, `lunarDay` and `yoga` are `null` for the Bhutanese traditions.** Janson tabulates no
|
|
518
|
+
month-animal list for that version, and Bhutan shifts the weekday by one day, which no source carries
|
|
519
|
+
through to the yoga's weekday element, so the package refuses rather than handing over Phugpa's
|
|
520
|
+
answers; the primitives throw `TCT_ATTRIBUTE_NOT_SOURCED` where the composition reports `null`.
|
|
521
|
+
|
|
522
|
+
Favorability is FPMT's convention and is in neither Janson nor Henning; `auspiciousness` is a Tibetan
|
|
523
|
+
dictionary's four-way grading of the same ten yogas, with its groups read from the order it lists them in. What is validated, over which
|
|
524
|
+
years, and against what, is in
|
|
525
|
+
[docs/why-trust-these-dates.md](docs/why-trust-these-dates.md).
|
|
526
|
+
|
|
527
|
+
## API
|
|
528
|
+
|
|
529
|
+
The complete surface, across all three entry points. Everything is a pure function over plain objects —
|
|
530
|
+
same input, same output, no side effects. Wherever a `tradition?` parameter appears below it is a
|
|
531
|
+
`TraditionConfig` defaulting to `PHUGPA`, passed last and positionally; a function with a second
|
|
532
|
+
choice takes both in an `options?` bag instead, whose tradition key is also `tradition`.
|
|
533
|
+
A signature below with neither `tradition?` nor `options?` takes no tradition at all: what it
|
|
534
|
+
computes is the same in every shipped tradition.
|
|
535
|
+
|
|
536
|
+
The type declarations under `dist/` also describe internal modules; the `exports` map refuses a deep
|
|
537
|
+
import of them, so what is listed here is the whole of what can be imported.
|
|
538
|
+
|
|
539
|
+
### `tibetan-calendar-temporal`
|
|
540
|
+
|
|
541
|
+
#### Conversion
|
|
542
|
+
|
|
543
|
+
| Export | Signature | Notes |
|
|
544
|
+
|---|---|---|
|
|
545
|
+
| `isoToTibetan` | `(date: Temporal.PlainDate, tradition?) => TibetanDate` | Total; every calendar day has a Tibetan date |
|
|
546
|
+
| `tibetanToIso` | `(input: TibetanDateFields, tradition?) => Temporal.PlainDate` | Throws `SkippedDayError`, or `RangeError` on out-of-range input |
|
|
547
|
+
| `tibetanDateExists` | `(input: TibetanDateFields, tradition?) => boolean` | The predicate counterpart. `false` for a skipped date, an out-of-range field or a missing leap month; **throws** for anything else, including a date past the exact range — where the day was never computed, so `false` would be a claim about arithmetic that was refused |
|
|
548
|
+
| `losarFor` | `(year: number, tradition?) => TibetanDate` | Tibetan New Year. Not `{ month: 1, day: 1 }` — that throws where day 1 is skipped |
|
|
549
|
+
|
|
550
|
+
#### Months
|
|
551
|
+
|
|
552
|
+
`year` here is the royal era, matching `TibetanDate.year` — 2153, not 2026.
|
|
553
|
+
|
|
554
|
+
The first two compute month boundaries, so they evaluate the calendar and are bounded by the
|
|
555
|
+
tradition's exact range. The last three are closed forms over the year alone: no lunar arithmetic,
|
|
556
|
+
a handful of integer operations, and exact for any year — including ones where `monthsFor` refuses.
|
|
557
|
+
|
|
558
|
+
| Export | Signature | Notes |
|
|
559
|
+
|---|---|---|
|
|
560
|
+
| `monthsFor` | `(year: number, tradition?) => TibetanMonth[]` | The year's months in calendar order, 12 or 13. Tiles Losar to the day before the next Losar, leap month first of its pair |
|
|
561
|
+
| `resolveMonth` | `(month: TibetanMonthFields, tradition?) => TibetanMonth` | A month's identity to the month itself. Replaces `addMonths(m, 0)` and the `monthsFor().find()` search, which returns the wrong half of a leap pair when it matches on the number alone |
|
|
562
|
+
| `resolveDate` | `(date: TibetanDateFields, tradition?) => TibetanDate` | The same one tier down, replacing `addDays(d, 0)`. Throws `SkippedDayError` if no calendar day carries the date. Two passes, not a lookup |
|
|
563
|
+
| `daysInMonth` | `(month: TibetanMonthFields, tradition?) => number` | **Calendar days**, 29 or 30 — not the highest date number, which is always 30. Accepts a `TibetanDate` directly |
|
|
564
|
+
| `hasLeapMonth` | `(year: number, tradition?) => boolean` | Whether the year has a thirteenth month. Not called `isLeapYear`: a Tibetan leap year gains a *month*, not a day |
|
|
565
|
+
| `leapMonthNumberFor` | `(year: number, tradition?) => number \| undefined` | Which month number is doubled, or `undefined` |
|
|
566
|
+
| `monthsInYear` | `(year: number, tradition?) => number` | 12 or 13 |
|
|
567
|
+
| `datesFor` | `(month: TibetanMonthFields, tradition?) => TibetanDate[]` | The month's calendar days, labelled — one entry per day, so a doubled number appears twice and a skipped one not at all. Bounded at 29 or 30 |
|
|
568
|
+
|
|
569
|
+
#### Navigation
|
|
570
|
+
|
|
571
|
+
Arithmetic happens on the calendar's two **integer coordinate lines** — the Julian day for solar
|
|
572
|
+
days, the lunation for months — never on the labels. Labels are partial (a skipped date names no
|
|
573
|
+
day) and non-injective (a leap year has two months numbered 6), which is where ambiguity comes
|
|
574
|
+
from; in coordinate space a leap month is simply the next lunation.
|
|
575
|
+
|
|
576
|
+
| Export | Signature | Notes |
|
|
577
|
+
|---|---|---|
|
|
578
|
+
| `addDays` | `(date: TibetanDateFields, days: number, tradition?) => TibetanDate` | **Solar** days, the unit elapsed-time reckonings use. Total — it can never land on a skipped date, because stepping real days never reaches a label no day carries |
|
|
579
|
+
| `daysBetween` | `(from: TibetanDateFields, to: TibetanDateFields, tradition?) => number` | Signed. If both dates came from this package, `a.isoDate.until(b.isoDate)` is the better route; this is for dates you built yourself |
|
|
580
|
+
| `addMonths` | `(month: TibetanMonthFields & { day?: never }, months: number, tradition?) => TibetanMonth` | Month in, month out, so **total**. `+1` from a leap month is its twin. A `TibetanDate` does **not** compile — it would discard the day silently; use `addMonthsToDate` |
|
|
581
|
+
| `addMonthsToDate` | `(date: TibetanDateFields, months: number, options?) => TibetanDate` | "The same day next month". `options` is `{ overflow?, tradition? }` — the key was `config` until 2026-09-24, and any other key is refused; `overflow` is `"constrain"` (default — fall to the nearest **lower** existing day, or day 2 when day 1 is skipped) or `"reject"`. A doubled day keeps the start's half, leap or regular, and an ordinary start lands on the regular half |
|
|
582
|
+
| `monthsBetween` | `(from: TibetanMonthFields, to: TibetanMonthFields, tradition?) => number` | Signed, counted in **lunations** — month 5 to month 7 is three in a year that doubles month 6, two otherwise |
|
|
583
|
+
| `lunationFromMonth` | `(month: TibetanMonthFields, tradition?) => number` | The month as one sortable integer, for a database or cache key. No consumer-side route: it needs the intercalation index |
|
|
584
|
+
| `monthFromLunation` | `(lunation: number, tradition?) => TibetanMonth` | The inverse, for a stored coordinate with no year in hand. Narrower domain than its inverse — it returns boundaries, so it evaluates the calendar |
|
|
585
|
+
| `nextFullMoon` | `(date: Temporal.PlainDate \| TibetanDate, tradition?) => TibetanDate` | Strictly after. **Not** `day === 15`: when 15 is skipped the full moon is on the day numbered 14, about one month in forty-four. Takes a *resolved* date, so it chains — a bare `{ year, month, day }` names no calendar and is refused; pass `resolveDate(…)` |
|
|
586
|
+
| `nextNewMoon` | `(date: Temporal.PlainDate \| TibetanDate, tradition?) => TibetanDate` | Strictly after. On a doubled 30 it is the **second** of the pair, not the leap day |
|
|
587
|
+
|
|
588
|
+
These two chain with themselves: the resolved date they return is a date they accept.
|
|
589
|
+
|
|
590
|
+
```js
|
|
591
|
+
let moon = nextFullMoon(Temporal.PlainDate.from('2026-01-01'));
|
|
592
|
+
moon = nextFullMoon(moon); // the one after that — no .isoDate needed
|
|
593
|
+
```
|
|
594
|
+
|
|
595
|
+
This is the only parameter in the package spanning two calendars, so it takes only shapes that say
|
|
596
|
+
which one they mean — a `Temporal` instance, or a resolved `TibetanDate`. A bare
|
|
597
|
+
`{ year, month, day }` is a genuine value of both this package's Tibetan shape and Temporal's own,
|
|
598
|
+
so it names neither and is refused rather than guessed at. Pass `resolveDate({ … })` for a Tibetan
|
|
599
|
+
date, or `Temporal.PlainDate.from({ … })` for a Western one.
|
|
600
|
+
|
|
601
|
+
#### Year names
|
|
602
|
+
|
|
603
|
+
Closed forms over the year alone — no lunar arithmetic, no config, and exact for any safe integer
|
|
604
|
+
year, including ones where `losarFor` must refuse.
|
|
605
|
+
|
|
606
|
+
| Export | Signature | Notes |
|
|
607
|
+
|---|---|---|
|
|
608
|
+
| `yearNameFor` | `(year: number) => TibetanYearName` | `{ element, animal, gender }`. Element and gender repeat every ten years, the animal every twelve, the whole name every sixty; plus `elementName`, `genderName` and `animalName` in Tibetan script, Wylie and phonetics — which is why there are no separate lookups for those three |
|
|
609
|
+
| `rabjungFor` | `(year: number) => Rabjung` | `{ cycle, year, tibetanName }` — `cycle`/`year` are the sixty-year numbering from 1027 CE, a *numbering* rather than a name (the two cycles sit three apart), and `tibetanName` is the **Tibetan** name at that position. No Sanskrit: the cycle has two Sanskrit name lists disagreeing at five positions, so pairing either with the Tibetan would misname 8% of years — see [docs/how-it-is-calculated.md](docs/how-it-is-calculated.md) |
|
|
610
|
+
| `weekdayNameFor` | `(weekday: TibetanWeekday, tradition?) => TibetanWeekdayName` | Tibetan name of a weekday. Takes the **Tibetan** numbering, 0 = Saturday. Takes a tradition because Bhutan names its days one planet ahead. `monthNamesFor` takes one too; `yearNameFor` and `rabjungFor` take none |
|
|
611
|
+
| `asTibetanWeekday` | `(value: number) => TibetanWeekday` | Validates 0–6 and brands. The way in for a number this package did not produce — parsed JSON, a form field. `weekdayNameFor(date.dayOfWeek)` is a **compile error**: ISO runs 1–7 from Monday, Tibetan 0–6 from Saturday |
|
|
612
|
+
|
|
613
|
+
A year picker is a loop over these plus `hasLeapMonth`; there is no range function, because building
|
|
614
|
+
the list is the consumer's business and nothing about it can go wrong.
|
|
615
|
+
|
|
616
|
+
```js
|
|
617
|
+
const years = [];
|
|
618
|
+
for (let y = 2140; y <= 2160; y++) {
|
|
619
|
+
years.push({ year: y, name: yearNameFor(y), rabjung: rabjungFor(y), leap: hasLeapMonth(y) });
|
|
620
|
+
}
|
|
621
|
+
```
|
|
622
|
+
|
|
623
|
+
#### Month names
|
|
624
|
+
|
|
625
|
+
| Export | Signature | Notes |
|
|
626
|
+
|---|---|---|
|
|
627
|
+
| `monthNamesFor` | `(month: TibetanMonthFields, tradition?) => MonthNames` | The month's lunar-mansion name, its Indian month name (`indianMonth`, Sanskrit: *māgha* for month 1, where the mansion is *maghā*), and its season in **all four** seasonal systems at once — `fourSeasons.month1LateWinter`, `fourSeasons.month1EarlySpring`, `fourSeasons.tigerEarlySpring` and `sixSeasons.month3EarlySpring` — because almanacs print several and no source makes one a tradition's only answer. The same `season` key names different months in different systems. `tigerEarlySpring` is `null` for a tradition without a sourced Tiger month (Bhutan). A leap month takes its regular month's names. See [the guide](docs/guide.md#naming-a-month) for the month-by-month table |
|
|
628
|
+
|
|
629
|
+
#### Formatting
|
|
630
|
+
|
|
631
|
+
The two are exact inverses: `formatTibetanDate(parseTibetanDate(s)) === s`. Neither takes a config,
|
|
632
|
+
because naming a date needs no calendar.
|
|
633
|
+
|
|
634
|
+
| Export | Signature | Notes |
|
|
635
|
+
|---|---|---|
|
|
636
|
+
| `formatTibetanDate` | `(date: TibetanDateFields) => string` | `"2153-M06-30"`, with `L` on a leap month and a trailing `(leap)` on a leap day. A `TibetanDate` is assignable, so pass one straight in |
|
|
637
|
+
| `parseTibetanDate` | `(text: string) => TibetanDateFields` | Strict — the canonical form only. Returns the naming fields rather than a resolved date, so a **skipped** date parses rather than throwing; pass it to `tibetanToIso` or `tibetanDateExists` |
|
|
638
|
+
| `formatTibetanMonth` | `(month: TibetanMonthFields) => string` | `"2151-M06L"` for a leap month, `"2151-M06"` for its twin. A `TibetanDate` is accepted and its day dropped, as `daysInMonth` also does |
|
|
639
|
+
| `parseTibetanMonth` | `(text: string) => TibetanMonthFields` | The inverse, and strict for the same reason. Compose with `resolveMonth` to resolve it |
|
|
640
|
+
|
|
641
|
+
#### Interoperability
|
|
642
|
+
|
|
643
|
+
The Julian day number is the interchange representation of calendrical computing — it is how you
|
|
644
|
+
convert between any two calendars, and how Janson's paper is written. These are the extension
|
|
645
|
+
point, not internals that leaked.
|
|
646
|
+
|
|
647
|
+
**These are Julian day *numbers*, not Julian *dates*.** The distinction bites when wiring this to
|
|
648
|
+
an astronomy library. A Julian Date (JD) is a real number whose integer values fall at **noon UT**,
|
|
649
|
+
so JD 2440588.0 is 1970-01-01 12:00. A Julian Day Number (JDN) is the integer naming a whole day.
|
|
650
|
+
This package uses JDN only — integers throughout, no fractions, which is the same no-floating-point
|
|
651
|
+
rule that makes every result identical across platforms. Passing a fractional JD throws
|
|
652
|
+
`TCT_FIELD_OUT_OF_RANGE` rather than silently truncating; floor it, and mind the half-day offset in
|
|
653
|
+
whichever direction you are converting.
|
|
654
|
+
|
|
655
|
+
| Export | Signature | Notes |
|
|
656
|
+
|---|---|---|
|
|
657
|
+
| `julianDayFromIso` | `(date: Temporal.PlainDate) => number` | Also accepts a `PlainDateTime`, a `ZonedDateTime`, or an ISO string — but not a bare `{ year, month, day }` object, which is ambiguous with this package's own Tibetan-date input. A `PlainDate` from a **second Temporal implementation** is accepted: every date argument on the surface is tested by brand, not by `instanceof`. The calendar must be `iso8601` — convert with `.withCalendar("iso8601")`, which names the same day |
|
|
658
|
+
| `isoFromJulianDay` | `(julianDay: number, tradition?) => Temporal.PlainDate` | Takes a tradition because the exact-range bound it enforces belongs to the tradition |
|
|
659
|
+
| `tibetanWeekday` | `(julianDay: number) => TibetanWeekday` | The Tibetan day of week, `0` = Saturday, one per planet — not the ISO `dayOfWeek` field. Also on every `TibetanDate` as `tibetanWeekday`, which is what to use when you have one |
|
|
660
|
+
|
|
661
|
+
#### Tradition configs
|
|
662
|
+
|
|
663
|
+
Two traditions, Phugpa and Bhutanese, each in two parameterisations. See
|
|
664
|
+
[Traditions](#traditions) above.
|
|
665
|
+
|
|
666
|
+
| Export | Notes |
|
|
667
|
+
|---|---|
|
|
668
|
+
| `PHUGPA` | The default. Lunar anomaly increment `a₂ = 1/28`, as almanacs use |
|
|
669
|
+
| `PHUGPA_HENNING` | Identical but for `a₂`, Henning's exact `3781/105840`. Differs on ~1 day in 4,100 days |
|
|
670
|
+
| `BHUTAN` | The Bhutanese calendar, with `a₂ = 1/28` as `PHUGPA` has. Its own epoch and constants, so its leap month is usually a different month of the same year, and now and then falls a year apart; it places a leap month after the regular month sharing its number, and names weekdays one planet ahead |
|
|
671
|
+
| `BHUTAN_HENNING` | Identical to `BHUTAN` but for `a₂`, as `PHUGPA_HENNING` is to `PHUGPA` |
|
|
672
|
+
|
|
673
|
+
#### Errors
|
|
674
|
+
|
|
675
|
+
`SkippedDayError` is the only exported error class, and carries the offending date as
|
|
676
|
+
`.requested` — a frozen copy of the date fields it read, not the same object, so extra keys on what you passed are dropped.
|
|
677
|
+
Every failure about your **input** is a `RangeError`; the two that are not about your
|
|
678
|
+
input — `TCT_INTERNAL` and `TCT_MISSING_TEMPORAL` — are plain `Error`s, deliberately, as the
|
|
679
|
+
at-a-glance signal that the fault is not yours. What actually keeps `tibetanDateExists` from
|
|
680
|
+
reporting either as "that date does not exist" is their **absence from its allowlist**, which is one
|
|
681
|
+
class and two codes; the type is the weaker, wider claim, and saying the type is the mechanism was
|
|
682
|
+
wrong for as long as it stood. Every one of them carries
|
|
683
|
+
a `code`, which is what to branch on rather than the type:
|
|
684
|
+
|
|
685
|
+
| `error.code` | Thrown by | Meaning |
|
|
686
|
+
|---|---|---|
|
|
687
|
+
| `TCT_SKIPPED_DAY` | `tibetanToIso`, `resolveDate`, `addDays`, `daysBetween`, `addMonthsToDate` | The date is well-formed but no calendar day carries its number. Not a bug in your code — see [Errors and validation](#errors-and-validation) |
|
|
688
|
+
| `TCT_FIELD_OUT_OF_RANGE` | every function taking a date, a year or a Julian day | A year, month, day or Julian day is a number but not an integer, or is outside 1–12 / 1–30; a bare-number argument such as `yearNameFor`'s that is not a number at all gets this code too, but a field of a date or month object that is absent or not a number is `TCT_INVALID_ARGUMENT`. The argument was the right kind of thing and one of its numbers was wrong — so this is the one to surface to a user |
|
|
689
|
+
| `TCT_INVALID_ARGUMENT` | the same functions, plus `parseTibetanDate`, and `nextObservance` for a `ruleId` that is not a string or names no rule | The argument is the wrong *kind* of thing, so nothing in it is a field out of a range: a `Temporal.PlainDate` where a Tibetan date is expected, a bare `{ year, month, day }` where a Western date is expected, a non-boolean `isLeapMonth`/`isLeapDay`, `null`/`undefined`, a string outside `parseTibetanDate`'s grammar, an options bag that is not an object, cannot be read, or carries a key it does not have, a date's or month's field that cannot be read because your getter or `Proxy` trap threw, or an element passed to `elementalYoga` that is not one of the four. A bug in the calling code rather than bad data |
|
|
690
|
+
| `TCT_NO_SUCH_LEAP_MONTH` | every function taking a Tibetan month's or date's **fields**, except `tibetanDateExists`, which answers `false`, and the two formatters | `isLeapMonth: true` for a month with no leap twin that year |
|
|
691
|
+
| `TCT_OUTSIDE_EXACT_RANGE` | any conversion, `getObservances` and `observancesOn` for a range reaching past the end **or a day inside a `period` whose span ends past it**, `nextObservance` for a `from` past the end, and the closed-form year functions `hasLeapMonth`, `leapMonthNumberFor`, `monthsInYear` | Beyond where this tradition's integer arithmetic stays exact. For a conversion, `PHUGPA` and `BHUTAN` are exact from about ISO year −245,737 to 236,312; `PHUGPA_HENNING` and `BHUTAN_HENNING` from about −20,781 to 11,356. Both ranges end inside Temporal's own. A `period` result carries the bounds of its whole span, so a day of a span that ends past the end of the range cannot be answered even though the day is inside it; only the last weeks before the end are reached, and `nextObservance` answers `null` there instead. The three year functions are closed forms with a bound of their own, far wider: `hasLeapMonth(300000)` answers |
|
|
692
|
+
| `TCT_INVALID_TRADITION_CONFIG` | any function taking a tradition | The `TraditionConfig` is malformed, or is not one at all — `null`, or a `{ tradition }` bag passed where the config itself belongs. A key the config does not have is refused, a misspelt one included, and so is a value that cannot be copied — a `Proxy`, even one with no traps — or read, because your getter or `Proxy` trap threw. The message names the field or the key |
|
|
693
|
+
| `TCT_INVALID_OBSERVANCE_CONFIG` | `getObservances`, `observancesOn`, `nextObservance`, `composeObservances` | The `ObservanceConfig`, one of its rules, levels or `when` forms, or a `composeObservances` layer is malformed — an unknown key, a setting the rule's form does not use, a rule naming a level the config does not declare, or a layer naming an id the base does not have — or a value that cannot be copied or read, such as a `Proxy`, even one with no traps, or a getter that throws. The message names the field or id |
|
|
694
|
+
| `TCT_SPAN_TOO_WIDE` | `getObservances` | `to.year - from.year` is more than 10: the rule is on calendar years, so 2020-01-01 to 2030-12-31 is admitted and 2020-12-31 to 2031-01-01 is not. Chunk it; the function is pure, so concatenating is correct |
|
|
695
|
+
| `TCT_ATTRIBUTE_NOT_SOURCED` | `monthAttributesFor`, `lunarDayAttributesFor`, `elementalYogaFor` | Your input is fine; no source gives this attribute for this tradition. Thrown under `BHUTAN` and `BHUTAN_HENNING`, whose month animals Janson does not tabulate (`monthAttributesFor`, `lunarDayAttributesFor`), and by `elementalYogaFor` under any config with a nonzero `naming.weekdayOffset`, which both Bhutanese configs have, since a shifted weekday leaves the yoga's weekday element unsourced. `attributesFor` reports the same gap as `null` instead |
|
|
696
|
+
| `TCT_MISSING_TEMPORAL` | the `import` itself, and any date entry point if the global `Temporal` is deleted afterwards | No `Temporal` in this runtime — see [Requirements](#requirements) |
|
|
697
|
+
| `TCT_INTERNAL` | `isoToTibetan`, and the arithmetic primitives beneath it | An invariant the engine proves for itself did not hold. A bug here rather than in your input; please [report it](https://github.com/nyamlen/tibetan-calendar-temporal/issues) |
|
|
698
|
+
|
|
699
|
+
Where **your own code** throws while the engine reads your argument — a getter, a `Proxy` trap, a
|
|
700
|
+
method of a value you pass — the error is refused with a code and yours is kept as its `cause`:
|
|
701
|
+
`TCT_INVALID_ARGUMENT` for a date, month, options bag or Temporal-like value, and the config's own
|
|
702
|
+
code for a `TraditionConfig` or an `ObservanceConfig`. Each field of a Tibetan date is read once, so a
|
|
703
|
+
getter that answers differently the second time cannot change what is computed.
|
|
704
|
+
|
|
705
|
+
Codes are stable and part of the API. Message text is not — match on the code.
|
|
706
|
+
|
|
707
|
+
#### Types
|
|
708
|
+
|
|
709
|
+
Type-only exports, erased at runtime: `TibetanDate`, `TibetanDateFields`, `TibetanMonth`,
|
|
710
|
+
`TibetanMonthFields`, `TibetanYearName`, `Rabjung`, `TibetanName`, `SanskritName`,
|
|
711
|
+
`TibetanWeekdayName`, `TibetanWeekdayElement`, `TibetanWeekday`, `TibetanPlanet`, `TibetanElement`,
|
|
712
|
+
`TibetanAnimal`,
|
|
713
|
+
`TibetanGender`, `TraditionConfig`, `TraditionNaming`, `TraditionMonthAnimals`, `TraditionNineNumbers`, `MeanMotion`, `Rational`,
|
|
714
|
+
`TibetanCalendarErrorCode`, `MonthOverflow`, `AddMonthsToDateOptions`, `MonthNames`,
|
|
715
|
+
`FourSeasonMonthName`, `SixSeasonMonthName`.
|
|
716
|
+
|
|
717
|
+
### `tibetan-calendar-temporal/observances`
|
|
718
|
+
|
|
719
|
+
A separate subpath, so a consumer who only converts dates never loads it. `config` here is a required
|
|
720
|
+
`ObservanceConfig`, and `tradition` is the `TraditionConfig`, defaulting to `PHUGPA`; both are
|
|
721
|
+
positional, config first — see [Two kinds of config](docs/guide.md#two-kinds-of-config).
|
|
722
|
+
|
|
723
|
+
| Export | Signature | Notes |
|
|
724
|
+
|---|---|---|
|
|
725
|
+
| `getObservances` | `(from: Temporal.PlainDate, to: Temporal.PlainDate, config: ObservanceConfig, tradition?: TraditionConfig) => Observance[]` | Date order, and within a day the order of the rules in the config. Returns `[]` if `to` precedes `from`; throws when `to.year - from.year` is above 10 |
|
|
726
|
+
| `observancesOn` | `(date: Temporal.PlainDate, config: ObservanceConfig, tradition?: TraditionConfig) => Observance[]` | The single-day case; results in the order of the config's rules |
|
|
727
|
+
| `nextObservance` | `(from: Temporal.PlainDate, ruleId: string, config: ObservanceConfig, tradition?: TraditionConfig) => Observance \| null` | The first occurrence of one rule strictly after `from`. `null` means none within 10 years, or before the end of the computable range, not never |
|
|
728
|
+
| `composeObservances` | `(base: ObservanceConfig, layer: ObservanceLayer) => ObservanceConfig` | A base and a layer of differences give a new validated, frozen configuration; the inputs are never changed |
|
|
729
|
+
| `EXAMPLE_OBSERVANCES` | | An example config. Its practice days follow FPMT's published calendars, which [what is validated](docs/why-trust-these-dates.md) says how far; its sojong is inferred from Rabten Choeling's schedule, and its Heruka, Ḍākinī and Dharma Protector day names are authored from Cornu's dedications. It claims no lineage |
|
|
730
|
+
|
|
731
|
+
Type-only exports: `Observance`, `ObservanceConfig`, `ObservanceRule`, `ObservanceWhen`,
|
|
732
|
+
`ObservanceLayer`, `ObservanceLevel`, `TibetanMonthDay`, `FormulaName`, `ObservanceResolution`, `DoubledDayChoice`,
|
|
733
|
+
`SkippedDayChoice`, `LeapMonthChoice`.
|
|
734
|
+
|
|
735
|
+
Note that `SkippedDayError` is exported from the **root** only. Nothing in this layer throws it —
|
|
736
|
+
a skipped day is handled by the `skippedDay` convention instead.
|
|
737
|
+
|
|
738
|
+
Full detail: [docs/development/architecture.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/development/architecture.md).
|
|
739
|
+
|
|
740
|
+
### `tibetan-calendar-temporal/astrology`
|
|
741
|
+
|
|
742
|
+
A separate subpath, like `./observances`. `tradition?` is a `TraditionConfig`, defaulting to `PHUGPA`,
|
|
743
|
+
passed last and positionally as on the root: `attributesFor(date, BHUTAN)`.
|
|
744
|
+
|
|
745
|
+
| Export | Signature | Notes |
|
|
746
|
+
|---|---|---|
|
|
747
|
+
| `attributesFor` | `(date: Temporal.PlainDate \| TibetanDate, tradition?) => DayAttributes` | Everything about one day. `month`, `lunarDay` and `yoga` are `null` where unsourced |
|
|
748
|
+
| `yearAttributesFor` | `(year: number) => YearAttributes` | Royal era, and no tradition: closed forms on the year alone |
|
|
749
|
+
| `monthAttributesFor` | `(month: TibetanMonthFields, tradition?) => MonthAttributes` | Throws `TCT_ATTRIBUTE_NOT_SOURCED` for the Bhutanese configs |
|
|
750
|
+
| `lunarDayAttributesFor` | `(date: TibetanDateFields, tradition?) => LunarDayAttributes` | Tibetan fields in, so a **skipped** lunar day can be asked about. Throws `TCT_ATTRIBUTE_NOT_SOURCED` for the Bhutanese configs |
|
|
751
|
+
| `calendarDayAttributesFor` | `(date: Temporal.PlainDate \| TibetanDate) => CalendarDayAttributes` | Congruences on the Julian day; the number differs in Tsurphu calendars, which is not modelled |
|
|
752
|
+
| `lunarMansionFor` | `(date: Temporal.PlainDate \| TibetanDate, tradition?) => LunarMansion` | `{ index, tibetanName, sanskritName, element }`, index 0–26 as Janson and Henning number them, and no English name, because no source prints one. Needs the moon's real position; a published almanac sometimes prints the next mansion, late in a mansion — how often is in [why-trust-these-dates.md](docs/why-trust-these-dates.md). |
|
|
753
|
+
| `elementalYogaFor` | `(date: Temporal.PlainDate \| TibetanDate, tradition?) => ElementalYoga` | The weekday's element paired with the lunar mansion's. Throws `TCT_ATTRIBUTE_NOT_SOURCED` under a nonzero `naming.weekdayOffset`, which both shipped Bhutanese configs have |
|
|
754
|
+
| `elementalYoga` | `(a: TibetanWeekdayElement, b: TibetanWeekdayElement) => ElementalYoga` | The pair alone, order-insensitive |
|
|
755
|
+
| `ELEMENTAL_YOGAS` | | The ten, frozen: Henning's names, FPMT's favorability, and the *tshig mdzod chen mo*'s four-way grading as `auspiciousness` |
|
|
756
|
+
| `LUNAR_MANSIONS` | | All 27, frozen, in index order — the table `lunarMansionFor` looks a day up in |
|
|
757
|
+
|
|
758
|
+
Type-only exports: `DayAttributes`, `YearAttributes`, `MonthAttributes`, `LunarDayAttributes`,
|
|
759
|
+
`CalendarDayAttributes`, `ElementalYoga`, `YogaAuspiciousness`, `TibetanTrigram`, `LunarMansion`.
|
|
760
|
+
|
|
761
|
+
A date argument is a `Temporal.PlainDate` or a resolved `TibetanDate` — never loose
|
|
762
|
+
`{ year, month, day }`, which is a value of both calendars and would make the ambiguity silent.
|
|
763
|
+
`monthAttributesFor` and `lunarDayAttributesFor` are the exceptions, and the reason is that their
|
|
764
|
+
argument is Tibetan-only: there is nothing to disambiguate, and fields are what lets a skipped lunar
|
|
765
|
+
day be named at all.
|
|
766
|
+
|
|
767
|
+
## Internationalisation
|
|
768
|
+
|
|
769
|
+
**What ships:** the *Tibetan* name of a thing — Tibetan script, Wylie, and THL Simplified Phonetic
|
|
770
|
+
Transcription (with eleven recorded corrections) — on `weekdayName`, and on `elementName` / `genderName` / `animalName` under the
|
|
771
|
+
`TibetanYearName` that `yearNameFor` returns; and on every member of `monthNamesFor`'s result
|
|
772
|
+
except `indianMonth`, which is the Indian month's Sanskrit name and has no Tibetan of its own.
|
|
773
|
+
|
|
774
|
+
**What deliberately does not ship:** translations into any other language. What ships instead is a
|
|
775
|
+
stable key your own i18n layer maps from — `TibetanElement`, `TibetanGender`, `TibetanAnimal` and
|
|
776
|
+
`TibetanPlanet` are lowercase identifiers and are **contract**, twenty-six in total.
|
|
777
|
+
|
|
778
|
+
Western weekday names need nothing from this package: the Tibetan week is the same seven-day cycle,
|
|
779
|
+
so `date.isoDate.toLocaleString('fr', { weekday: 'long' })` covers every locale CLDR carries.
|
|
780
|
+
|
|
781
|
+
Every Tibetan string was verified before it was written down: two independent EWTS implementations
|
|
782
|
+
must agree on the script, it must read back as the same Wylie, and a dictionary must carry it —
|
|
783
|
+
Wiktionary at exactly that title for the weekday, element, gender and animal names, other
|
|
784
|
+
dictionaries for the rest (see the sourcing records). That check earns its keep: Janson gives Saturday as `spen ma` in his
|
|
785
|
+
day-of-week table and `spen pa` in his Bhutan appendix, and this package ships `spen pa`. See
|
|
786
|
+
[docs/names/vocabulary.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/names/vocabulary.md).
|
|
787
|
+
|
|
788
|
+
[The guide](docs/guide.md#displaying-tibetan-names) covers the Bhutanese weekday shift, the CLDR
|
|
789
|
+
curiosities, and localising observance labels.
|
|
56
790
|
|
|
57
791
|
## Provenance
|
|
58
792
|
|
|
59
793
|
Implemented from Svante Janson, *Tibetan Calendar Mathematics*
|
|
60
794
|
([arXiv:1401.6285](https://arxiv.org/abs/1401.6285)) as a clean-room build. It shares no code
|
|
61
|
-
with any existing implementation — see [CONTRIBUTING.md](CONTRIBUTING.md) for the rules that
|
|
795
|
+
with any existing implementation — see [CONTRIBUTING.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/CONTRIBUTING.md) for the rules that
|
|
62
796
|
keep it that way.
|
|
63
797
|
|
|
64
798
|
## Project identity
|
|
@@ -68,25 +802,46 @@ keep it that way.
|
|
|
68
802
|
| npm package | `tibetan-calendar-temporal` (unscoped) |
|
|
69
803
|
| GitHub/npm org | `nyamlen` |
|
|
70
804
|
| Repository | `github.com/nyamlen/tibetan-calendar-temporal` |
|
|
71
|
-
| App (separate repo) | `Nyamlen` |
|
|
72
805
|
|
|
73
|
-
**
|
|
74
|
-
|
|
75
|
-
|
|
806
|
+
**Why unscoped.** Unscoped names rank better in npm search, and discoverability is this package's job.
|
|
807
|
+
|
|
808
|
+
<details>
|
|
809
|
+
<summary><strong>Why the name says "Tibetan" when Bhutan and Mongolia have their own calendars</strong></summary>
|
|
810
|
+
|
|
811
|
+
Because that is how the field describes the family, not because their calendars are treated as
|
|
812
|
+
lesser. Svante Janson — whose *Tibetan Calendar Mathematics* this engine is derived from — writes
|
|
813
|
+
that "Bhutan and Mongolia also use versions of the Tibetan calendar", opens his Bhutan appendix
|
|
814
|
+
"Bhutan uses a version of the Tibetan calendar as an official calendar", and opens his Mongolia
|
|
815
|
+
appendix "The Mongolian calendar is a version of the Tibetan."
|
|
816
|
+
|
|
817
|
+
All of them descend from the Kālacakra कालचक्र system, which is the honest name for the family;
|
|
818
|
+
"Tibetan calendar" is the name people search for. Bhutan's is an official state calendar in
|
|
819
|
+
Dzongkha with its own eighteenth-century description and its own leap-month and weekday
|
|
820
|
+
conventions; Mongolia's carries two national holidays and dates its constitution by the sixty-year
|
|
821
|
+
cycle. Neither is a dialect of the other.
|
|
822
|
+
|
|
823
|
+
Traditions here are **data, not packages** — a variant is a `TraditionConfig`, never a separate
|
|
824
|
+
install.
|
|
825
|
+
|
|
826
|
+
</details>
|
|
76
827
|
|
|
77
828
|
## Documentation
|
|
78
829
|
|
|
79
830
|
| | |
|
|
80
831
|
|---|---|
|
|
81
|
-
| [docs/
|
|
82
|
-
| [docs/
|
|
83
|
-
| [docs/
|
|
84
|
-
| [docs/
|
|
85
|
-
| [
|
|
832
|
+
| [docs/how-it-is-calculated.md](docs/how-it-is-calculated.md) | **Start here if the calendar is new to you.** What a lunisolar calendar has to solve, leap months, why days are doubled and skipped, and what `a₂` is |
|
|
833
|
+
| [docs/guide.md](docs/guide.md) | The long-form companion to this file: the calendar's hard cases, where a day begins, working with the two configs, and running it outside Node 26 |
|
|
834
|
+
| [docs/why-trust-these-dates.md](docs/why-trust-these-dates.md) | What has been validated, against what, and over which years — and what has not. Written for a non-programmer |
|
|
835
|
+
| [docs/README.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/README.md) | Every document, grouped by who reads it |
|
|
836
|
+
| [docs/other-implementations.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/other-implementations.md) | The other software that computes Tibetan dates, and when to use it instead |
|
|
837
|
+
| [docs/development/architecture.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/development/architecture.md) | Layered model, API design, package structure, core types, tooling |
|
|
838
|
+
| [docs/development/testing.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/development/testing.md) | Three-tier testing strategy and validation sources |
|
|
839
|
+
| [docs/sources/validation-sources.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/sources/validation-sources.md) | Every source checked against, its **lineage**, what it settles, and what has been tried and rejected |
|
|
840
|
+
| [docs/development/roadmap.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/development/roadmap.md) | Implementation phases and release status |
|
|
841
|
+
| [docs/names/rabjung.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/names/rabjung.md) | The 60 rabjung year names, with the provenance of every column |
|
|
842
|
+
| [docs/decisions/](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/decisions/) | Decision records |
|
|
843
|
+
| [CONTRIBUTING.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/CONTRIBUTING.md) | Clean-room constraint, dev setup, how to add validation data |
|
|
86
844
|
|
|
87
845
|
## Licence
|
|
88
846
|
|
|
89
847
|
MIT — see [LICENSE](LICENSE). Fork it, build on it, ship commercial products with it.
|
|
90
|
-
|
|
91
|
-
Reasoning behind the choice, including why GPL/AGPL and MPL-2.0 were set aside:
|
|
92
|
-
[docs/decisions/2026-08-11-licensing.md](docs/decisions/2026-08-11-licensing.md).
|