tibetan-calendar-temporal 1.0.0 → 1.0.2
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 +28 -7
- package/docs/guide.md +4 -6
- package/docs/why-trust-these-dates.md +1 -3
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -4,6 +4,12 @@ Compute Tibetan calendar dates in JavaScript — leap months, doubled and skippe
|
|
|
4
4
|
year names and observances — for almanac applications, practice calendars, and anything that has to
|
|
5
5
|
show a Tibetan date and be right about it.
|
|
6
6
|
|
|
7
|
+
It computes two calendars: **Phugpa**, the Men-Tsee-Khang standard and the basis of the almanacs most
|
|
8
|
+
Tibetans 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 yet**: the engine can
|
|
10
|
+
express them as configuration, and each will be exported once its dates have been checked against an
|
|
11
|
+
almanac of its own — see [Traditions](#traditions).
|
|
12
|
+
|
|
7
13
|
```sh
|
|
8
14
|
npm install tibetan-calendar-temporal
|
|
9
15
|
```
|
|
@@ -57,7 +63,7 @@ see [why you can trust these dates](docs/why-trust-these-dates.md).
|
|
|
57
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 |
|
|
58
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 |
|
|
59
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 |
|
|
60
|
-
| **
|
|
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 |
|
|
61
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 |
|
|
62
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) |
|
|
63
69
|
|
|
@@ -386,7 +392,7 @@ worked `switch` over every code is in [the guide](docs/guide.md#handling-errors)
|
|
|
386
392
|
### Traditions
|
|
387
393
|
|
|
388
394
|
**v1 ships two calendars in four configurations.** Phugpa (*phug pa*) is the Men-Tsee-Khang
|
|
389
|
-
standard and the basis of the almanacs most
|
|
395
|
+
standard and the basis of the almanacs most Tibetans use; Bhutanese is the calendar of the
|
|
390
396
|
Royal Government of Bhutan. Each ships twice, because each has two defensible parameterisations:
|
|
391
397
|
|
|
392
398
|
```js
|
|
@@ -412,10 +418,12 @@ back-projection is worse than the headline rate suggests. All three counts are r
|
|
|
412
418
|
engine and asserted in `test/computation/conversion.test.ts`. The evidence for the default is in
|
|
413
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).
|
|
414
420
|
|
|
415
|
-
**
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
project exists to avoid — not because the
|
|
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).
|
|
419
427
|
|
|
420
428
|
It can. Every astronomical constant is injected through a `TraditionConfig` rather than hardcoded,
|
|
421
429
|
including the scaling denominator, which is *derived* from the constants rather than fixed — Phugpa
|
|
@@ -570,7 +578,7 @@ from; in coordinate space a leap month is simply the next lunation.
|
|
|
570
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 |
|
|
571
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 |
|
|
572
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` |
|
|
573
|
-
| `addMonthsToDate` | `(date: TibetanDateFields, months: number, options?) => TibetanDate` | "The same day next month". `options` is `{ overflow?, tradition? }
|
|
581
|
+
| `addMonthsToDate` | `(date: TibetanDateFields, months: number, options?) => TibetanDate` | "The same day next month". `options` is `{ overflow?, tradition? }`, 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
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 |
|
|
575
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 |
|
|
576
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 |
|
|
@@ -787,6 +795,19 @@ Implemented from Svante Janson, *Tibetan Calendar Mathematics*
|
|
|
787
795
|
with any existing implementation — see [CONTRIBUTING.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/CONTRIBUTING.md) for the rules that
|
|
788
796
|
keep it that way.
|
|
789
797
|
|
|
798
|
+
**How it was built.** I, Andreas Bothner, am a software architect, and I built this package with
|
|
799
|
+
Claude Code, Anthropic's AI coding assistant: it wrote the code, tests and documentation under my
|
|
800
|
+
direction and review, and the design decisions are mine. That changes where trust has to come from,
|
|
801
|
+
not how much is needed. The calendar arithmetic is taken from Janson's paper alone, and the dates are
|
|
802
|
+
checked against independent published calendars over stated ranges of years — see
|
|
803
|
+
[why you can trust these dates](docs/why-trust-these-dates.md). Before 1.0.0 the code went through a
|
|
804
|
+
source code review, two security reviews, an adversarial review, a maintainability review and an
|
|
805
|
+
audit of every documentation comment, each by sessions that had not written the code under review,
|
|
806
|
+
and through blind builds by clients working from a packed tarball alone. The clean-room rule binds
|
|
807
|
+
the assistant as it binds any contributor: no session read another implementation's source. What a
|
|
808
|
+
model saw in training cannot be ruled out, so the evidence of independent derivation is the commit
|
|
809
|
+
history itself, where the arithmetic is built up step by step from the paper's sections.
|
|
810
|
+
|
|
790
811
|
## Project identity
|
|
791
812
|
|
|
792
813
|
| Thing | Name |
|
package/docs/guide.md
CHANGED
|
@@ -245,9 +245,8 @@ nextObservance(from, ruleId, observanceConfig, traditionConfig);
|
|
|
245
245
|
Both are positional. The observance config is **required**: no config is the default, because which
|
|
246
246
|
days a practice keeps is a convention and the package does not choose one for you, so a call
|
|
247
247
|
without one throws `TCT_INVALID_OBSERVANCE_CONFIG`. The tradition is last and optional, defaulting
|
|
248
|
-
to `PHUGPA`.
|
|
249
|
-
|
|
250
|
-
you called and its own signature.
|
|
248
|
+
to `PHUGPA`. Passing an options bag, or a `TraditionConfig`, where the config belongs throws the
|
|
249
|
+
same code, and the message names the function you called and its own signature.
|
|
251
250
|
|
|
252
251
|
| | `TraditionConfig` | `ObservanceConfig` |
|
|
253
252
|
|---|---|---|
|
|
@@ -909,9 +908,8 @@ isoToTibetan(Temporal.PlainDate.from('2003-06-01')).year; // 2130, after it
|
|
|
909
908
|
**A year of dates, serialised, is about 126 KB** (354 days, ordinary year 2153) or **137 KB** for a
|
|
910
909
|
thirteen-month leap year like 2151 — measured, not assumed, in `test/serialisation.test.ts`.
|
|
911
910
|
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
repeated across all 354 days, and together they were more than half of a serialised year. Reach them
|
|
911
|
+
**Year-level naming is not a field on a date**: the element–animal name and the rabjung position
|
|
912
|
+
describe the *year*, so on a date they would be one value repeated across all 354 days. Reach them
|
|
915
913
|
with `yearNameFor(date.year)` and `rabjungFor(date.year)`, which are closed forms and touch no lunar
|
|
916
914
|
arithmetic. `TibetanMonth` still carries `yearName`, so the `monthsFor` → `datesFor` path keeps it
|
|
917
915
|
one hop away.
|
|
@@ -189,9 +189,7 @@ Stating this is the point of the page.
|
|
|
189
189
|
- **The calendar is usable from 1447**, when the Phugpa system was introduced. Earlier dates are
|
|
190
190
|
computed, and they are a back-projection: the system did not exist, and the year numbering is a
|
|
191
191
|
modern convention applied backwards.
|
|
192
|
-
- **The astrological attributes are computed but corroborated much less than the dates.**
|
|
193
|
-
"no astrological information is computed" until 2026-09-12, when the `./astrology` subpath landed,
|
|
194
|
-
and the honest version is longer. The cycles — the year's five elements, the month's and lunar
|
|
192
|
+
- **The astrological attributes are computed but corroborated much less than the dates.** The cycles — the year's five elements, the month's and lunar
|
|
195
193
|
day's labels, the calendar day's — are closed forms checked against Janson's own printed tables,
|
|
196
194
|
which catches a transcription or formula error and is **not** external corroboration. The **lunar
|
|
197
195
|
mansion** needs real astronomy and agrees, for Phugpa, with FPMT's published codes on **98.0%** of the 1,821 days
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "tibetan-calendar-temporal",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.2",
|
|
4
4
|
"description": "Tibetan calendar computation engine built on Temporal — the Phugpa and Bhutanese traditions, with the Tsurphu and Mongolian variants addable as config.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -18,6 +18,7 @@
|
|
|
18
18
|
"phugpa",
|
|
19
19
|
"buddhist",
|
|
20
20
|
"lunisolar",
|
|
21
|
+
"lunisolar-calendar",
|
|
21
22
|
"tibetan-calendar",
|
|
22
23
|
"losar",
|
|
23
24
|
"bhutanese",
|