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