ponomar-ts 0.1.0-alpha.0

package/src/data/types.ts

@@ -0,0 +1,35 @@
+// Shared, hand-written type definitions for generated data under src/data/.
+// The codegen scripts import these; generated files reference them via
+// import type. Do not edit generated files by hand.
+
+/**
+ * One SAINT record from a `<DAY>` XML file (pentecostarion/triodion/menaion).
+ * `sIds` is a list because upstream sometimes packs multiple ids into one
+ * `SId="a,b,c"` attribute.
+ */
+export interface Saint {
+	readonly sIds: readonly string[];
+	readonly cId: string;
+	/** Raw StringOp DSL guard, evaluated at runtime; missing means "always". */
+	readonly cmd?: string;
+	/** Raw DSL expression yielding a numeric tone, or a bare literal. */
+	readonly tone?: string;
+	/** Source tag: G (Greek), R (Russian), U (Unsourced), etc. */
+	readonly src?: string;
+}
+
+/** All saints registered for a single day of a cycle. */
+export interface DayEntry {
+	readonly saints: readonly Saint[];
+}
+
+/**
+ * One `<COMMAND>` record from Commands/DivineLiturgy.xml (or similar).
+ * `value` and `cmd` are DSL expressions.
+ */
+export interface Command {
+	readonly name: string;
+	readonly value: string;
+	readonly cmd?: string;
+	readonly comment?: string;
+}

package/src/engine/day.ts

@@ -0,0 +1,67 @@
+// The day-context calculator: given a Gregorian date, produce the numeric
+// variables that the upstream StringOp DSL expects (`doy`, `dow`, `nday`,
+// `ndayP`, `ndayF`). Follows upstream conventions: all values derive from
+// the *Julian* civil-date equivalent (that is what the Ponomar engine and
+// its rule XML use).
+
+import type { JulianDate } from "../core/calendar/jdate.ts";
+import {
+	dayOfWeek,
+	dayOfYear,
+	difference,
+	fromGregorian,
+} from "../core/calendar/jdate.ts";
+import type { CalendarDate } from "../core/calendar/pcalendar.ts";
+import { getJulianPaschaRich } from "../paschalion.ts";
+
+/**
+ * Numeric context variables for a single day, in the shape the StringOp DSL
+ * expects. Sunday is `dow === 0`; `doy` is 0-indexed to match upstream.
+ */
+export interface DayContext {
+	readonly gregorian: CalendarDate;
+	readonly julian: JulianDate;
+	readonly doy: number;
+	readonly dow: number;
+	readonly nday: number;
+	readonly ndayP: number;
+	readonly ndayF: number;
+}
+
+export function computeDayContext(gregorian: CalendarDate): DayContext {
+	const julian = fromGregorian(gregorian);
+	const year = julian.year;
+	const paschaThis = getJulianPaschaRich(year);
+	const paschaPrev = getJulianPaschaRich(year - 1);
+	const paschaNext = getJulianPaschaRich(year + 1);
+	return {
+		gregorian,
+		julian,
+		doy: dayOfYear(julian),
+		dow: dayOfWeek(julian),
+		nday: difference(julian, paschaThis),
+		ndayP: difference(julian, paschaPrev),
+		ndayF: difference(julian, paschaNext),
+	};
+}
+
+/**
+ * Format a `DayContext` as a plain lookup table for the DSL evaluator.
+ * `dRank` defaults to 10 (upstream's "no rank found" fallback), matching
+ * initial state before Commemorations are loaded.
+ */
+export function dslContext(
+	ctx: DayContext,
+	extra?: Readonly<Record<string, number>>,
+): Readonly<Record<string, number>> {
+	return {
+		doy: ctx.doy,
+		dow: ctx.dow,
+		nday: ctx.nday,
+		ndayP: ctx.ndayP,
+		ndayF: ctx.ndayF,
+		dRank: 10,
+		GS: 1,
+		...extra,
+	};
+}

package/src/engine/index.ts

@@ -0,0 +1,44 @@
+// Top-level public API for the day-info engine.
+//
+// This composes the day-context calculator, the DayEntry lookups
+// (pentecostarion / triodion / menaion) and the DSL-guard filter into one
+// call. It answers: "for this Gregorian date, which saints are commemorated,
+// and what is the paschal-cycle context?"
+
+import type { CalendarDate } from "../core/calendar/pcalendar.ts";
+import type { DayContext } from "./day.ts";
+import { computeDayContext } from "./day.ts";
+import { selectMenaionEntry, selectPaschalCycleEntry } from "./lookup.ts";
+import type { ResolvedSaint } from "./resolve.ts";
+import { resolveSaints } from "./resolve.ts";
+
+/** Result of `getLiturgicalDay`. */
+export interface LiturgicalDay {
+	readonly context: DayContext;
+	/** Saints from the paschal cycle (pentecostarion or triodion), Cmd-filtered. */
+	readonly paschalSaints: readonly ResolvedSaint[];
+	/** Saints from the fixed Menaion at Julian MM-DD, Cmd-filtered. */
+	readonly menaionSaints: readonly ResolvedSaint[];
+	/** Union of paschalSaints then menaionSaints, in that order. */
+	readonly allSaints: readonly ResolvedSaint[];
+}
+
+export function getLiturgicalDay(gregorian: CalendarDate): LiturgicalDay {
+	const context = computeDayContext(gregorian);
+	const paschal = selectPaschalCycleEntry(context);
+	const menaion = selectMenaionEntry(context);
+	const paschalSaints = paschal ? resolveSaints(paschal, context) : [];
+	const menaionSaints = menaion ? resolveSaints(menaion, context) : [];
+	return {
+		context,
+		paschalSaints,
+		menaionSaints,
+		allSaints: [...paschalSaints, ...menaionSaints],
+	};
+}
+
+export type { DayContext } from "./day.ts";
+export { computeDayContext, dslContext } from "./day.ts";
+export { selectMenaionEntry, selectPaschalCycleEntry } from "./lookup.ts";
+export type { ResolvedSaint } from "./resolve.ts";
+export { resolveSaints } from "./resolve.ts";

package/src/engine/lookup.ts

@@ -0,0 +1,34 @@
+// Given a DayContext, pull the raw `DayEntry` rows from the generated data
+// modules for the Paschal cycle (pentecostarion or triodion) and the fixed
+// Menaion, if present. Both entries are optional: the vendor may not have
+// data for every calendar slot.
+
+import type { DayEntry } from "../data/index.ts";
+import { MENAION, PENTECOSTARION, TRIODION } from "../data/index.ts";
+import type { DayContext } from "./day.ts";
+
+/** Selection of Paschal-cycle DayEntry for a given `nday` / `ndayP`. */
+export function selectPaschalCycleEntry(ctx: DayContext): DayEntry | null {
+	// After Pascha, through Pentecost and beyond, up to ~245 days out.
+	if (ctx.nday >= 0 && ctx.nday < PENTECOSTARION.length) {
+		return PENTECOSTARION[ctx.nday] ?? null;
+	}
+	// Pre-Lent through Holy Saturday: negative nday, indexed by absolute value.
+	if (ctx.nday >= -70 && ctx.nday < 0) {
+		const idx = Math.abs(ctx.nday) - 1;
+		return TRIODION[idx] ?? null;
+	}
+	// After Pentecost / before Triodion opens: fall back to previous year's
+	// Pascha cycle. `ndayP` is days since previous-year Pascha.
+	if (ctx.nday < -70 && ctx.ndayP >= 0 && ctx.ndayP < PENTECOSTARION.length) {
+		return PENTECOSTARION[ctx.ndayP] ?? null;
+	}
+	return null;
+}
+
+/** Menaion entry keyed by Julian MM-DD; may be absent for days without data. */
+export function selectMenaionEntry(ctx: DayContext): DayEntry | null {
+	const mm = ctx.julian.month.toString().padStart(2, "0");
+	const dd = ctx.julian.day.toString().padStart(2, "0");
+	return MENAION[`${mm}-${dd}`] ?? null;
+}

package/src/engine/resolve.ts

@@ -0,0 +1,49 @@
+// Apply the DSL `Cmd` guards on `Saint` records to a DayContext, and resolve
+// the optional numeric `Tone` expression. Saints whose guard evaluates to
+// false are dropped.
+
+import { evaluate, evaluateBool } from "../core/dsl/index.ts";
+import type { DayEntry, Saint } from "../data/index.ts";
+import type { DayContext } from "./day.ts";
+import { dslContext } from "./day.ts";
+
+/**
+ * A `Saint` with its `Tone` expression resolved to a number (or null if
+ * absent). The `cmd` guard, if any, has already been evaluated to `true`.
+ */
+export interface ResolvedSaint {
+	readonly sIds: readonly string[];
+	readonly cId: string;
+	readonly src?: string;
+	readonly tone: number | null;
+}
+
+/** Evaluate every saint's `Cmd`, then resolve tone; drop saints where Cmd is false. */
+export function resolveSaints(
+	entry: DayEntry,
+	ctx: DayContext,
+	extraVars?: Readonly<Record<string, number>>,
+): ResolvedSaint[] {
+	const vars = dslContext(ctx, extraVars);
+	const out: ResolvedSaint[] = [];
+	for (const s of entry.saints) {
+		if (s.cmd !== undefined && !evaluateBool(s.cmd, vars)) continue;
+		out.push({
+			sIds: s.sIds,
+			cId: s.cId,
+			...(s.src !== undefined ? { src: s.src } : {}),
+			tone: resolveTone(s, vars),
+		});
+	}
+	return out;
+}
+
+function resolveTone(
+	s: Saint,
+	vars: Readonly<Record<string, number>>,
+): number | null {
+	if (s.tone === undefined) return null;
+	const n = evaluate(s.tone, vars);
+	if (!Number.isFinite(n)) return null;
+	return Math.trunc(n);
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * ponomar-ts — TypeScript port of the Ponomar Orthodox liturgics engine.
+ *
+ * This top-level entry re-exports every stable public module. Prefer deep
+ * imports (`ponomar-ts/paschalion`) for smaller bundles when possible.
+ *
+ * @packageDocumentation
+ */
+
+export * from "./paschalion.ts";
+export * as jdate from "./core/calendar/jdate.ts";
+export * as pcalendar from "./core/calendar/pcalendar.ts";
+export * as dsl from "./core/dsl/index.ts";
+export * as data from "./data/index.ts";
+export * as engine from "./engine/index.ts";
+export { getLiturgicalDay } from "./engine/index.ts";
+export type { LiturgicalDay } from "./engine/index.ts";

package/src/paschalion.ts

@@ -0,0 +1,80 @@
+// Ported from Ponomar/Paschalion.java (typiconman/ponomar).
+// Uses Gauss' formula for the Julian Pascha date, then converts to the
+// Gregorian civil calendar via Julian Day Number (see src/core/calendar/).
+
+import {
+	addDays as addDaysJulian,
+	julianDate,
+	toGregorian,
+	type JulianDate,
+} from "./core/calendar/jdate.ts";
+import type { CalendarDate } from "./core/calendar/pcalendar.ts";
+
+export type { CalendarDate } from "./core/calendar/pcalendar.ts";
+export {
+	addDays,
+	julianToGregorianOffset,
+} from "./core/calendar/pcalendar.ts";
+
+/**
+ * Julian calendar date of Orthodox Pascha for the given AD year, computed by
+ * Gauss' Easter formula. The returned month/day are on the *Julian* calendar.
+ *
+ * @throws {RangeError} if `year` is not a positive integer.
+ */
+export function getJulianPascha(year: number): CalendarDate {
+	const rich = getJulianPaschaRich(year);
+	return { year: rich.year, month: rich.month, day: rich.day };
+}
+
+/** Gregorian civil date of Orthodox Pascha for the given AD year. */
+export function getOrthodoxPascha(year: number): CalendarDate {
+	return toGregorian(getJulianPaschaRich(year));
+}
+
+/** Pentecost (Pascha + 49 days), Gregorian civil date. */
+export function getPentecost(year: number): CalendarDate {
+	return toGregorian(addDaysJulian(getJulianPaschaRich(year), 49));
+}
+
+/** Ascension (Pascha + 39 days), Gregorian civil date. */
+export function getAscension(year: number): CalendarDate {
+	return toGregorian(addDaysJulian(getJulianPaschaRich(year), 39));
+}
+
+/** Meatfare Sunday (Pascha - 56 days), Gregorian civil date. */
+export function getMeatfare(year: number): CalendarDate {
+	return toGregorian(addDaysJulian(getJulianPaschaRich(year), -56));
+}
+
+/** Cheesefare / Forgiveness Sunday (Pascha - 49 days), Gregorian. */
+export function getCheesefare(year: number): CalendarDate {
+	return toGregorian(addDaysJulian(getJulianPaschaRich(year), -49));
+}
+
+/** Clean Monday, start of Great Lent (Pascha - 48 days), Gregorian. */
+export function getLentStart(year: number): CalendarDate {
+	return toGregorian(addDaysJulian(getJulianPaschaRich(year), -48));
+}
+
+/** Apostles' Fast start (Pascha + 57 days), Gregorian. */
+export function getApostlesFastStart(year: number): CalendarDate {
+	return toGregorian(addDaysJulian(getJulianPaschaRich(year), 57));
+}
+
+/**
+ * Julian-calendar date of Pascha as a rich `JulianDate` (with pre-computed
+ * Julian Day Number). Used by the engine layer for `nday` derivations.
+ */
+export function getJulianPaschaRich(year: number): JulianDate {
+	if (!Number.isInteger(year) || year < 1) {
+		throw new RangeError(`year must be a positive integer, got ${year}`);
+	}
+	const a = year % 19;
+	const b = year % 4;
+	const c = year % 7;
+	const d = (19 * a + 15) % 30;
+	const e = (2 * b + 4 * c + 6 * d + 6) % 7;
+	const f = d + e;
+	return f <= 9 ? julianDate(year, 3, 22 + f) : julianDate(year, 4, f - 9);
+}