@heroiclands/package-build 22.8.0 → 22.9.0

package/types/engine/calendars.d.mts

@@ -36,22 +36,87 @@ export function canonicalYear(year: number, epoch?: number): number;
  */
 export function dateSortKey(year: number, month: number | null, day: number | null): number;
 /**
- * The bounds a package states for a month, or `null` where it states none.
+ * One month of a calendar, as the note declares it.
  *
- * Separate from the check that reads it so a caller can ask what a package
- * declares without phrasing a finding about it.
+ * @typedef {object} CalendarMonth
+ * @property {string} name - What the month is called.
+ * @property {string} [abbreviation] - A short form, where the note gives one.
+ * @property {number} days - How many days it holds.
+ */
+/**
+ * The months a calendar keeps, or `null` where it declares none.
  *
- * @param {{months?: number|null, monthDays?: number|null}} [calendar] - The
- *   resolved `calendar:` block.
- * @returns {{months: number|null, monthDays: number|null}} What it declares.
+ * Separate from the check that reads it so a caller can ask what a calendar
+ * divides its year into without phrasing a finding about it. An empty list
+ * reads as no list: a calendar that declares nothing and one that declares
+ * nothing in a pair of brackets divide the year identically.
+ *
+ * @param {{months?: readonly CalendarMonth[]|null}} [calendar] - The calendar
+ *   the date is written in, as its note declares it.
+ * @returns {{months: readonly CalendarMonth[]|null}} What it divides the year
+ *   into.
  */
 export function calendarStructure(calendar?: {
-    months?: number | null;
-    monthDays?: number | null;
+    months?: readonly CalendarMonth[] | null;
 }): {
-    months: number | null;
-    monthDays: number | null;
+    months: readonly CalendarMonth[] | null;
 };
+/**
+ * How long one month of a calendar is, or `null` where the calendar is silent.
+ *
+ * @param {{months?: readonly CalendarMonth[]|null}} [calendar] - The calendar.
+ * @param {number} month - The month, numbered from 1.
+ * @returns {number|null} Its length in days, or `null`.
+ */
+export function daysInMonth(calendar?: {
+    months?: readonly CalendarMonth[] | null;
+}, month: number): number | null;
+/**
+ * How many days the months add up to.
+ *
+ * The number a calendar's list claims the year is. Whether that is the year the
+ * world keeps is a question about the world, and is asked elsewhere.
+ *
+ * @param {readonly CalendarMonth[]} months - The ordered month list.
+ * @returns {number} The sum of their day counts.
+ */
+export function daysInYear(months: readonly CalendarMonth[]): number;
+/**
+ * The day of the year each month opens on, in order, numbered from 1.
+ *
+ * The sum read as a sequence rather than as a total. Two lists holding the same
+ * numbers in a different order sum alike and open their months on different
+ * days, which is the error a total cannot see.
+ *
+ * @param {readonly CalendarMonth[]} months - The ordered month list.
+ * @returns {number[]} One entry per month: the day of the year it begins on.
+ */
+export function monthStarts(months: readonly CalendarMonth[]): number[];
+/**
+ * Which day of the year a written month and day land on, numbered from 1.
+ *
+ * @param {readonly CalendarMonth[]} months - The ordered month list.
+ * @param {number} month - The month, numbered from 1.
+ * @param {number} day - The day within it, numbered from 1.
+ * @returns {number} The day of the year.
+ */
+export function dayOfYear(months: readonly CalendarMonth[], month: number, day: number): number;
+/**
+ * How far into its cycle a moon is on a given day.
+ *
+ * **Floored, not truncated.** JavaScript's `%` takes the dividend's sign, so a
+ * day seven before the epoch yields `-7` where the phase is 23 — a value that
+ * is right on one side of the epoch and wrong on the other, which is invisible
+ * in any list that does not span it.
+ *
+ * @param {number} dayNumber - The day, on whatever continuous day count the
+ *   caller keeps.
+ * @param {number} epochDay - The day of that same count on which the moon was
+ *   new.
+ * @param {number} cycle - The cycle's length in days.
+ * @returns {number} Days into the cycle, `0` to `cycle - 1`.
+ */
+export function lunarPhase(dayNumber: number, epochDay: number, cycle: number): number;
 /**
  * **The axis every date normalises onto, and the one function that puts a
  * reckoning on it.**
@@ -93,14 +158,23 @@ export function calendarStructure(calendar?: {
  * and off by one on the other, which is invisible in any list that does not
  * span it.
  *
- * ## The month structure is the package's, and an absent bound checks nothing
+ * ## The month structure is the calendar's, and an absent list bounds nothing
  *
- * An era moves where year 1 sits; it does not divide the year differently. So
- * the subdivision is declared once for the package, in `calendar.months` and
- * `calendar.monthDays`, and a package that declares neither is bounded below
- * and not above — a toolchain that invented twelve Gregorian months would
- * refuse `667/2/30`, which is an ordinary date in a year of twelve thirty-day
- * months.
+ * An era moves where year 1 sits; it does not divide the year differently. The
+ * division belongs to the calendar, which is a note declaring an **ordered
+ * list** of months, each with a name and a day count. Position in the list is
+ * position in the year, so a five-day month sits wherever its people put it and
+ * needs no rule of its own.
+ *
+ * A date is bounded by the calendar it is written in, and a calendar whose list
+ * nobody has written down bounds nothing — a toolchain that invented twelve
+ * Gregorian months would refuse `667/2/30`, an ordinary date in a year of
+ * twelve thirty-day months.
+ *
+ * ## The lunar phase takes a floored modulo, not JavaScript's
+ *
+ * `%` takes the dividend's sign, so a day before the epoch yields `-7` where
+ * the phase is 23. {@link lunarPhase} is the one place that is written.
  *
  * @module
  */
@@ -113,3 +187,20 @@ export function calendarStructure(calendar?: {
  * @type {number}
  */
 export const CANONICAL_EPOCH: number;
+/**
+ * One month of a calendar, as the note declares it.
+ */
+export type CalendarMonth = {
+    /**
+     * - What the month is called.
+     */
+    name: string;
+    /**
+     * - A short form, where the note gives one.
+     */
+    abbreviation?: string | undefined;
+    /**
+     * - How many days it holds.
+     */
+    days: number;
+};

package/types/engine/index.d.mts

@@ -31,6 +31,7 @@ export * as siteMaps from "./site-maps.mjs";
 export * as systems from "./systems.mjs";
 export * as calendars from "./calendars.mjs";
 export * as noteDates from "./note-dates.mjs";
+export * as calendarNotes from "./calendar-notes.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";
 export * as subtypeRegistry from "./subtype-registry.mjs";

package/types/engine/note-dates.d.mts

@@ -14,9 +14,10 @@
  * @param {unknown} value - The authored value. A number is what YAML hands
  *   back for a bare year, so it is accepted and stringified.
  * @param {object} [options]
- * @param {{months?: number|null, monthDays?: number|null}} [options.calendar]
- *   The resolved `calendar:` block, whose `months` and `monthDays` bound a
- *   written month and day. An absent bound is not applied.
+ * @param {{months?: readonly object[]|null}} [options.calendar] - The calendar
+ *   the value is written in, as its note declares it. Its ordered month list
+ *   bounds a written month and a written day, the day against the length of
+ *   the month it names. A calendar that declares no list bounds nothing.
  * @param {string} [options.field] - The key that carried it, named in every
  *   message. Omitted, a message names the value alone.
  * @param {boolean} [options.allowUnknown=true] - Whether `"unknown"` is a
@@ -31,8 +32,7 @@
  */
 export function parseNoteDate(value: unknown, options?: {
     calendar?: {
-        months?: number | null;
-        monthDays?: number | null;
+        months?: readonly object[] | null;
     } | undefined;
     field?: string | undefined;
     allowUnknown?: boolean | undefined;
@@ -52,7 +52,7 @@ export const UNKNOWN_DATE: string;
 /**
  * What a date's trailing token may look like.
  *
- * An affiliation's address followed by `.<era shortcode>`. The `{0,3}`
+ * A calendar note's address followed by `.<era shortcode>`. The `{0,3}`
  * repetition is the four address forms exactly — bare `shortcode`,
  * `type-shortcode`, `system-type-shortcode` and
  * `package-system-type-shortcode` — so the hyphen separates an address's