tibetan-calendar-temporal 0.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.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +92 -0
  3. package/index.js +5 -0
  4. package/package.json +39 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Andreas Bothner
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,92 @@
1
+ # tibetan-calendar-temporal
2
+
3
+ > ## ⚠️ Placeholder release
4
+ >
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.
7
+ >
8
+ > Everything below describes the **planned** API, not shipped behaviour. Do not depend on this
9
+ > package until v1.0.0.
10
+
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/).
14
+
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.
17
+
18
+ ## Design
19
+
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**
27
+
28
+ ## Planned API
29
+
30
+ ```js
31
+ import { isoToTibetan, tibetanToIso, getPracticeDays } from 'tibetan-calendar-temporal';
32
+ ```
33
+
34
+ An optional Temporal Calendar Protocol adapter is exposed at
35
+ `tibetan-calendar-temporal/temporal`.
36
+
37
+ Full detail: [docs/architecture.md](docs/architecture.md).
38
+
39
+ ## Requirements
40
+
41
+ Node 26 for native Temporal. Earlier versions need a polyfill supplied by the consumer.
42
+
43
+ ## Why this exists
44
+
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.
49
+
50
+ The engine is separate from the app because:
51
+
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
56
+
57
+ ## Provenance
58
+
59
+ Implemented from Svante Janson, *Tibetan Calendar Mathematics*
60
+ ([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
62
+ keep it that way.
63
+
64
+ ## Project identity
65
+
66
+ | Thing | Name |
67
+ |-------|------|
68
+ | npm package | `tibetan-calendar-temporal` (unscoped) |
69
+ | GitHub/npm org | `nyamlen` |
70
+ | Repository | `github.com/nyamlen/tibetan-calendar-temporal` |
71
+ | App (separate repo) | `Nyamlen` |
72
+
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`.
76
+
77
+ ## Documentation
78
+
79
+ | | |
80
+ |---|---|
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 |
86
+
87
+ ## Licence
88
+
89
+ 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).
package/index.js ADDED
@@ -0,0 +1,5 @@
1
+ // Placeholder release. The computation engine is in development and this module
2
+ // intentionally exports no calendar functions yet — see README.md.
3
+ // STATUS is removed at v0.1.0, when the real API lands.
4
+
5
+ export const STATUS = "pre-release";
package/package.json ADDED
@@ -0,0 +1,39 @@
1
+ {
2
+ "name": "tibetan-calendar-temporal",
3
+ "version": "0.0.1",
4
+ "description": "Tibetan calendar (Phugpa tradition) computation engine built on Temporal. Pre-release placeholder — implementation in development.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "author": "Andreas Bothner <contact@nyamlen.app>",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/nyamlen/tibetan-calendar-temporal.git"
11
+ },
12
+ "homepage": "https://github.com/nyamlen/tibetan-calendar-temporal#readme",
13
+ "bugs": "https://github.com/nyamlen/tibetan-calendar-temporal/issues",
14
+ "keywords": [
15
+ "tibetan",
16
+ "calendar",
17
+ "temporal",
18
+ "phugpa",
19
+ "buddhist",
20
+ "lunisolar",
21
+ "tibetan-calendar",
22
+ "losar"
23
+ ],
24
+ "exports": {
25
+ ".": "./index.js"
26
+ },
27
+ "files": [
28
+ "index.js",
29
+ "README.md",
30
+ "LICENSE"
31
+ ],
32
+ "engines": {
33
+ "node": ">=22"
34
+ },
35
+ "sideEffects": false,
36
+ "publishConfig": {
37
+ "access": "public"
38
+ }
39
+ }