@hebcal/hdate/dist/esm/anniversary.d.ts

converts between Hebrew and Gregorian dates using Rata Die (R.D.) algorithm by Dershowitz and Reingold

import { SimpleHebrewDate } from './hdateBase';
/**
 * Accepted forms of the original event date for `getYahrzeit`,
 * `getYahrzeitHD`, `getBirthdayOrAnniversary`, and `getBirthdayHD`.
 *
 * - `Date` — a Gregorian date (local time; hours and below ignored)
 * - `SimpleHebrewDate` — `{yy, mm, dd}` already in the Hebrew calendar
 * - `number` — an absolute R.D. day count
 */
export type AnniversaryDate = Date | SimpleHebrewDate | number;
/**
 * Calculates yahrzeit.
 * `hyear` must be after original `date` of death.
 * Returns `undefined` when requested year preceeds or is same as original year.
 *
 * Hebcal uses the algorithm defined in "Calendrical Calculations"
 * by Edward M. Reingold and Nachum Dershowitz.
 *
 * The customary anniversary date of a death is more complicated and depends
 * also on the character of the year in which the first anniversary occurs.
 * There are several cases:
 *
 * * If the date of death is Marcheshvan 30, the anniversary in general depends
 *   on the first anniversary; if that first anniversary was not Marcheshvan 30,
 *   use the day before Kislev 1.
 * * If the date of death is Kislev 30, the anniversary in general again depends
 *   on the first anniversary — if that was not Kislev 30, use the day before
 *   Tevet 1.
 * * If the date of death is Adar II, the anniversary is the same day in the
 *   last month of the Hebrew year (Adar or Adar II).
 * * If the date of death is Adar I 30, the anniversary in a Hebrew year that
 *   is not a leap year (in which Adar only has 29 days) is the last day in
 *   Shevat.
 * * In all other cases, use the normal (that is, same month number) anniversary
 *   of the date of death. [Calendrical Calculations p. 113]
 * @example
 * import {getYahrzeit} from '@hebcal/hdate';
 * const dt = new Date(2014, 2, 2); // '2014-03-02' == '30 Adar I 5774'
 * const anniversary = getYahrzeit(5780, dt); // '2/25/2020' == '30 Sh\'vat 5780'
 * @param hyear Hebrew year
 * @param date Gregorian or Hebrew date of death
 * @returns anniversary occurring in `hyear`
 */
export declare function getYahrzeit(hyear: number, date: AnniversaryDate): Date | undefined;
/**
 * Same calculation as `getYahrzeit`, but returns the result as a
 * `SimpleHebrewDate` (`{yy, mm, dd}`) rather than converting to a
 * Gregorian `Date`. Useful when the caller needs the Hebrew date
 * directly (e.g. for rendering with `gematriya` or further Hebrew-calendar
 * arithmetic) and wants to avoid an extra R.D. → Gregorian round-trip.
 *
 * See `getYahrzeit` for the full description of the algorithm and
 * edge cases (Marcheshvan 30, Kislev 30, Adar I / Adar II).
 * @example
 * import {getYahrzeitHD} from '@hebcal/hdate';
 * const dt = new Date(2014, 2, 2); // 30 Adar I 5774
 * getYahrzeitHD(5780, dt); // {yy: 5780, mm: 11, dd: 30} (30 Sh'vat)
 * @param hyear Hebrew year in which to find the anniversary
 * @param date Gregorian or Hebrew date of death
 * @returns anniversary occurring in `hyear`, or `undefined`
 *   when `hyear` is on or before the original year
 */
export declare function getYahrzeitHD(hyear: number, date: AnniversaryDate): SimpleHebrewDate | undefined;
/**
 * Calculates a birthday or anniversary (non-yahrzeit).
 * `hyear` must be on or after original `date` of anniversary.
 * Returns `undefined` when requested year preceeds the original year.
 *
 * Hebcal uses the algorithm defined in "Calendrical Calculations"
 * by Edward M. Reingold and Nachum Dershowitz.
 *
 * The birthday of someone born in Adar of an ordinary year or Adar II of
 * a leap year is also always in the last month of the year, be that Adar
 * or Adar II. The birthday in an ordinary year of someone born during the
 * first 29 days of Adar I in a leap year is on the corresponding day of Adar;
 * in a leap year, the birthday occurs in Adar I, as expected.
 *
 * Someone born on the thirtieth day of Marcheshvan, Kislev, or Adar I
 * has his birthday postponed until the first of the following month in
 * years where that day does not occur. [Calendrical Calculations p. 111]
 * @example
 * import {getBirthdayOrAnniversary} from '@hebcal/hdate';
 * const dt = new Date(2014, 2, 2); // '2014-03-02' == '30 Adar I 5774'
 * const anniversary = getBirthdayOrAnniversary(5780, dt); // '3/26/2020' == '1 Nisan 5780'
 * @param hyear Hebrew year
 * @param date Gregorian or Hebrew date of event
 * @returns anniversary occurring in `hyear`
 */
export declare function getBirthdayOrAnniversary(hyear: number, date: AnniversaryDate): Date | undefined;
/**
 * Same calculation as `getBirthdayOrAnniversary`, but returns the
 * result as a `SimpleHebrewDate` (`{yy, mm, dd}`) rather than
 * converting to a Gregorian `Date`. Useful when the caller needs the
 * Hebrew date directly (e.g. for rendering with `gematriya` or further
 * Hebrew-calendar arithmetic) and wants to avoid an extra R.D. →
 * Gregorian round-trip.
 *
 * See `getBirthdayOrAnniversary` for the full description of the
 * algorithm and edge cases (Adar / Adar II, and the 30th of
 * Marcheshvan, Kislev, or Adar I).
 * @example
 * import {getBirthdayHD} from '@hebcal/hdate';
 * const dt = new Date(2014, 2, 2); // 30 Adar I 5774
 * getBirthdayHD(5780, dt); // {yy: 5780, mm: 1, dd: 1} (1 Nisan)
 * @param hyear Hebrew year in which to find the anniversary
 * @param date Gregorian or Hebrew date of the original event
 * @returns anniversary occurring in `hyear`, or `undefined`
 *   when `hyear` precedes the original year
 */
export declare function getBirthdayHD(hyear: number, date: AnniversaryDate): SimpleHebrewDate | undefined;