javascript and typescript, as one wasm package for every runtime

WebAssembly rather than a native Node addon: one artifact serves Node,
Deno, Bun, a browser and anything built on them, where napi would have
meant a prebuilt binary per platform and a source build for whoever the
matrix missed. The engine is pure computation and the menologion is
already compiled in, so there is nothing for it to give up.

A day comes back as a plain object, not a handle. A wasm class would
have meant a .free() that every caller eventually forgets, and this way
JSON.stringify works and the thing spreads into state. Two serializer
defaults had to be overridden to keep the promise that it is the same
document --json emits: maps as objects, and an absent field as null
rather than undefined, which stringify would otherwise drop entirely.

The TypeScript is hand-written, because the generated types for a value
crossing as JsValue are `any`, and a binding that types its whole
return as `any` is a binding TypeScript cannot check. tsc --strict is a release
gate now, the way mypy --strict already is, and the check includes three
lines that must fail to compile.

The one place this differs from every other binding: no remembered
default jurisdiction, because a browser has nowhere to keep one. It is
called out in the README, in the types and in docs/versioning.md.

The test resolves typikon through a staged node_modules rather than a
relative path, so what it exercises is the exports map, and it compares
a year of days field by field against the command line for four
jurisdictions.
This commit is contained in:
funkpower
2026-09-18 14:55:40 -04:00
parent d90d4c171f
commit 69907eb186
16 changed files with 1002 additions and 3 deletions
+48
View File
@@ -71,6 +71,15 @@ no network either. Wheels are built for Linux on x86-64 and aarch64; everywhere
else pip falls back to the source distribution, which needs a Rust toolchain of
1.85 or newer on the installing machine.
For JavaScript and TypeScript, there is a package:
```console
$ npm install typikon
```
WebAssembly, so the one package serves Node, Deno, Bun and the browser with no
native build to go wrong.
## Which calendar?
Three things get conflated constantly, and keeping them apart is most of what
@@ -455,6 +464,45 @@ day.title -- "The Holy Prophet Zachariah, father of the Forerunner"
day.commemorations
```
## From JavaScript and TypeScript
```sh
npm install typikon
```
```js
import { today } from "typikon";
const day = today({ jurisdiction: "rocor" });
day.churchDate; // "5 September"
day.fast; // "xerophagy"
day.emoji; // the glyph for the level
day.title; // "The Holy Prophet Zachariah, father of the Forerunner"
day.season; // null in ordinary time
day.daysToPascha;
```
```js
import { describe, describeIso, week, pascha, jurisdictions } from "typikon";
describeIso("2026-04-12", { jurisdiction: "moscow" });
describe(new Date(), { jurisdiction: "goarch", tradition: "greek" });
week(new Date(), 7, { jurisdiction: "oca" }); // seven consecutive days
pascha(2027, "old"); // 2027-05-02
```
It is WebAssembly, so it is one package for Node, Deno, Bun, a browser and
anything built on them, with no native build to go wrong. Node loads it itself;
in a browser or a bundler, `await init()` first. A day comes back as a plain
object, not a handle: the same document `--json` emits, with nothing to free
and `JSON.stringify` working on it. TypeScript types ship with the package and
`tsc --strict` is clean against them.
There is no remembered default here, because a browser has nowhere to keep one:
the default is the New Calendar, and anything else is passed. That is the only
place this binding differs from the others.
## The menologion
The fixed calendar ships as data and is indexed by **ecclesiastical** date, so