hindu-devotional-texts/src/festivals/types.ts

Hand-curated, typed, authoritative Hindu devotional content — aartis, chalisas, kathas, stotras, mantras, ashtottaras & sahasranamas, Vedic suktas, daily prayers, puja vidhi, Navratri, tirthas, the festival/ekadashi calendar, and full scriptures (Bhagavad

import type { Bilingual, Deity } from '../types.js'
import type { KathaSlug } from '../kathas/index.js'
import type { PujaSlug } from '../puja/index.js'
import type { MantraSlug } from '../mantras/index.js'
import type { SuktaSlug } from '../suktas/index.js'
import type { StotraSlug } from '../stotras/index.js'

// Festivals & Vrats — the observance calendar as **descriptive reference**, not
// a panchang. Each entry names the tithi/paksha/month an observance falls on
// (those are NAMES, fully in scope) but ships NO computed dates — date
// calculation is deliberately out of scope. A standalone module like `tirtha/`
// and `vaar/`: no `Category` value, no `getContentForDeity` wiring; reverse
// lookup via `getFestivalsForDeity`.
//
// Content-accuracy posture (researched, cross-checked, shipped provisional —
// the puja/tirtha/vaar footing, NOT the hand-typed-from-one-text footing):
//  - Every entry's significance + story is the widely-attested traditional
//    account, cross-checked across ≥2 references (the actual translated Purāṇa
//    text on wisdomlib + independent vrat-katha pages). Research provenance
//    lives in `festivals/SOURCES.md`, never in a user-facing field. The whole
//    module ships flagged provisional (`reviewPending`) — the per-story details
//    (secondary character names, exact phala numbers) are devotional-tradition
//    level, not critical-edition level.
//  - `storySource` names only the **scriptural origin** (the Purāṇa + narrator
//    frame) — that is content (like a sūkta's `vedicSource`), NOT a digitization
//    source; the websites a story was cross-checked against are never named in
//    any field.
//  - `deity` cross-links to the per-deity roster content. Every Ekādaśī is a
//    Vaiṣṇava vrat → `vishnu`.

/** The kind of observance an entry is (the discriminator). */
export type FestivalCategory =
  | 'ekadashi' // one of the 24 (+2 adhika-māsa) Ekādaśī vrats (Viṣṇu)
  | 'tithi-vrat' // a recurring tithi-vrat — Pradoṣa, Sankaṣṭī, Pūrṇimā, Amāvasyā
  | 'festival' // a calendar festival — Mahāśivarātri, Janmāṣṭamī, Dīwālī, …

/** The two lunar fortnights. A *name*, not a date. */
export type Paksha =
  | 'shukla' // the bright/waxing fortnight (Amāvasyā → Pūrṇimā)
  | 'krishna' // the dark/waning fortnight (Pūrṇimā → Amāvasyā)

/**
 * A unified entry across every category — a single shape with a `category`
 * discriminator and category-specific OPTIONAL fields (chosen over a
 * discriminated union so `getAllFestivals()` returns one array type and the
 * data files stay uniform, mirroring `TirthaEntry`). Which optionals are
 * populated is governed by `category`:
 *  - `ekadashi`   → `paksha`, `month`, `isAdhikaMaasa?`
 *  - `tithi-vrat` → `paksha?`, `tithi`, `recurrence`
 *  - `festival`   → `month?`, `tithi?`
 */
export interface FestivalEntry {
  /** Stable kebab-case slug, unique across the module ('kamada-ekadashi'). */
  id: string
  category: FestivalCategory
  /** Display name of the observance. */
  name: Bilingual
  /** Devanagari proper name, where it differs usefully from `name.hi`. */
  nameSanskrit?: string
  /**
   * Roster cross-link to per-deity content (aarti/chalisa/…). `null` when the
   * observance is not tied to a single roster deity. Every Ekādaśī → `vishnu`.
   */
  deity: Deity | null
  /** One- or two-sentence significance / phala (what observing it grants). */
  significance: Bilingual
  /**
   * The vrat-kathā / origin narrative, as a researched sense-summary (never a
   * copied translation). Absent on the few phala-stuti observances the source
   * text gives no story for (Aparā, Kāmikā, Pāpāṅkuśā Ekādaśī).
   */
  story?: Bilingual
  /**
   * The **scriptural origin** of the observance/story — the Purāṇa + narrator
   * frame (e.g. "Padma Purāṇa, narrated by Kṛṣṇa to Yudhiṣṭhira"). This is
   * content (like a sūkta's `vedicSource`), NOT a digitization source. Omitted
   * where no single text is confidently attributable.
   */
  storySource?: Bilingual
  /** Ships provisional until a human pass signs off the story details. */
  reviewPending?: boolean

  // ── category-specific optionals ──────────────────────────────────────────
  /** The fortnight the observance falls in (ekadashi; some tithi-vrats). */
  paksha?: Paksha
  /** The lunar month, as a display name (ekadashi; some festivals). */
  month?: Bilingual
  /** The tithi the observance falls on (tithi-vrat; some festivals). */
  tithi?: Bilingual
  /** How often it recurs, described in words — never computed (tithi-vrat). */
  recurrence?: Bilingual
  /**
   * `true` for the two Ekādaśīs that occur ONLY in the intercalary Adhika
   * (Puruṣottama) māsa — Padminī (śukla) and Paramā (kṛṣṇa). They are over and
   * above the 24 regular Ekādaśīs and appear only once every ~3 years.
   */
  isAdhikaMaasa?: boolean

  // ── optional cross-links into other modules (every slug must resolve) ─────
  kathaSlug?: KathaSlug
  pujaSlug?: PujaSlug
  mantraSlugs?: readonly MantraSlug[]
  suktaSlugs?: readonly SuktaSlug[]
  stotraSlugs?: readonly StotraSlug[]
  /** A scripture slug ('bhagavad-geeta') — e.g. Mokṣadā ↔ Gītā Jayantī. */
  scriptureSlug?: string
}