@nepdatejs/core 0.0.0-bootstrap → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,433 @@
+//#region src/types.d.ts
+/** The two calendars this library knows. */
+type CalendarSystem = "AD" | "BS";
+/**
+ * Whole days since 1970-01-01 AD. The only value the AD and BS calendars share:
+ * every conversion goes BS → EpochDay → AD and back (docs/plan D-001, D-002).
+ * Branded so a year, month or day number can never be passed by mistake.
+ */
+type EpochDay = number & {
+  readonly __brand: "EpochDay";
+};
+/** 0 = Sunday … 6 = Saturday. */
+type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** 1 = Baisakh/January … 12 = Chaitra/December. */
+type MonthNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+/** A Gregorian (AD) calendar day. Create with `adDate()`; always frozen. */
+interface AdDate {
+  readonly calendar: "AD";
+  readonly year: number;
+  readonly month: MonthNumber;
+  readonly day: number;
+}
+/** A Bikram Sambat (BS) calendar day. Create with `bsDate()`; always frozen. */
+interface BsDate {
+  readonly calendar: "BS";
+  readonly year: number;
+  readonly month: MonthNumber;
+  readonly day: number;
+}
+type CalendarDate = AdDate | BsDate;
+/** The date type of a calendar: `DateOf<'BS'>` is `BsDate`. */
+type DateOf<C extends CalendarSystem> = C extends "AD" ? AdDate : BsDate;
+/** The BS month-length table. Keyed by BS year only; holds no AD dates (D-001). */
+interface BsData {
+  /** The BS year of the first row of `years`. */
+  readonly firstYear: number;
+  /** Days since 1970-01-01 of 1 Baisakh of `firstYear`. */
+  readonly epochStart: number;
+  /** Years after this one are projections, not yet checked against a published calendar. */
+  readonly verifiedThrough: number;
+  /** Twelve month lengths (Baisakh..Chaitra) per year, starting at `firstYear`. */
+  readonly years: readonly (readonly number[])[];
+}
+/** A locale code: built in are `en` and `ne`; more can be added with `registerLocale`. */
+type LocaleCode = "en" | "ne" | (string & Record<never, never>);
+/** Nepal's fiscal year: 1 Shrawan to the last day of Asar. */
+interface FiscalYear {
+  /** The BS year the fiscal year starts in: 2083 for FY 2083/84. */
+  readonly startYear: number;
+  /** "2083/84" */
+  readonly label: string;
+  readonly firstDay: BsDate;
+  readonly lastDay: BsDate;
+}
+//#endregion
+//#region src/errors.d.ts
+type NepDateRangeErrorCode = "INVALID_DATE" | "OUT_OF_TABLE" | "INVALID_ARGUMENT";
+/** Thrown for any invalid date or argument. Check `code`, not the message. */
+export declare class NepDateRangeError extends RangeError {
+  readonly code: NepDateRangeErrorCode;
+  constructor(code: NepDateRangeErrorCode, message: string);
+}
+type NepDateDataErrorCode = "EMPTY" | "BAD_MONTH_COUNT" | "BAD_MONTH" | "BAD_YEAR_TOTAL" | "BAD_ANCHOR";
+/** Thrown when a BS table passed to `setBsData` or `patchBsYear` is not valid. */
+export declare class NepDateDataError extends Error {
+  readonly code: NepDateDataErrorCode;
+  /** The BS year at fault, when there is one. */
+  readonly year: number | undefined;
+  /** The month (1–12) at fault, when there is one. */
+  readonly month: number | undefined;
+  constructor(code: NepDateDataErrorCode, message: string, year?: number, month?: number);
+}
+//#endregion
+//#region src/epoch.d.ts
+/** Brand a whole number of days since 1970-01-01 as an `EpochDay`. */
+export declare function toEpochDay(value: number): EpochDay;
+/** The weekday of a day count. 1970-01-01 was a Thursday. */
+export declare function weekdayOf(epoch: EpochDay): Weekday;
+//#endregion
+//#region src/config.d.ts
+/**
+ * Settings shared by both calendars. Calendar data is not here: the BS table is
+ * managed by setBsData/patchBsYear, and AD needs no data (docs/plan D-001).
+ */
+interface NepDateConfig {
+  /** Which time zone decides "today" and the calendar day of an instant. */
+  readonly timeZone: string;
+  readonly weekStartsOn: Weekday;
+  readonly weekendDays: readonly Weekday[];
+  readonly defaultLocale: LocaleCode;
+}
+/** Change one or more settings. Every value is checked before any is applied. */
+export declare function configure(changes: Partial<NepDateConfig>): void;
+export declare function getConfig(): NepDateConfig;
+/** Back to the defaults (Kathmandu, Sunday first, Saturday weekend, English). */
+export declare function resetConfig(): void;
+//#endregion
+//#region src/ad/calendar.d.ts
+/**
+ * The Gregorian (AD) calendar, by arithmetic only: no table, no BS knowledge,
+ * no `Date`. Works for any year in ±MAX_AD_YEAR (docs/plan D-001).
+ *
+ * The day-count algorithms are Howard Hinnant's days_from_civil and
+ * civil_from_days (proleptic Gregorian, March-based years).
+ */
+/** AD years must lie within ±this value. */
+export declare const MAX_AD_YEAR = 999999;
+export declare function isAdLeapYear(year: number): boolean;
+//#endregion
+//#region src/bs/table.d.ts
+export declare function bsFirstYear(): number;
+export declare function bsLastYear(): number;
+//#endregion
+//#region src/bs/data-api.d.ts
+/** The first BS month of Nepal's fiscal year: Shrawan. */
+export declare const BS_FISCAL_YEAR_START_MONTH = 4;
+/** Throws NepDateDataError when the table is not usable. Same rules as scripts/gen-data.ts. */
+export declare function validateBsData(table: BsData): void;
+/** The BS table in use (frozen). */
+export declare function getBsData(): BsData;
+/** Replace the whole BS table. Only BS results change; AD functions are unaffected. */
+export declare function setBsData(table: BsData): void;
+/**
+ * Correct one year's month lengths, or add the year just before the first or
+ * just after the last. Years after a corrected year move with it; earlier years
+ * never move (adding a year before the first keeps every existing year in place).
+ */
+export declare function patchBsYear(year: number, months: readonly number[]): void;
+/** Back to the table bundled with the package. */
+export declare function resetBsData(): void;
+//#endregion
+//#region src/create.d.ts
+/** An AD date. Any year within ±999,999 is allowed; only conversion to BS is limited. */
+export declare function adDate(year: number, month: number, day: number): AdDate;
+/** A BS date. The year must be in the BS table. */
+export declare function bsDate(year: number, month: number, day: number): BsDate;
+export declare function createDate<C extends CalendarSystem>(calendar: C, year: number, month: number, day: number): DateOf<C>;
+export declare function isValidDate(calendar: CalendarSystem, year: number, month: number, day: number): boolean;
+/** Days in a month of either calendar. */
+export declare function daysInMonth(calendar: CalendarSystem, year: number, month: number): number;
+/** True for a valid, frozen-or-not AD date object (e.g. from JSON). */
+export declare function isAdDate(value: unknown): value is AdDate;
+/** True for a valid BS date object (e.g. from JSON). */
+export declare function isBsDate(value: unknown): value is BsDate;
+export declare function isCalendarDate(value: unknown): value is CalendarDate;
+//#endregion
+//#region src/convert.d.ts
+/** The day count of a date in either calendar. */
+export declare function toEpoch(date: CalendarDate): EpochDay;
+/** The date of a day count in a calendar. BS throws OUT_OF_TABLE outside the table. */
+export declare function fromEpoch<C extends CalendarSystem>(epoch: EpochDay, calendar: C): DateOf<C>;
+export declare function adToBs(date: AdDate): BsDate;
+export declare function bsToAd(date: BsDate): AdDate;
+/** The same day in the given calendar (the date itself when it is already in it). */
+export declare function toCalendar<C extends CalendarSystem>(date: CalendarDate, calendar: C): DateOf<C>;
+/** The first day that can be converted, in either calendar (the start of the BS table). */
+export declare function minDate<C extends CalendarSystem>(calendar: C): DateOf<C>;
+/** The last day that can be converted, in either calendar (the end of the BS table). */
+export declare function maxDate<C extends CalendarSystem>(calendar: C): DateOf<C>;
+/** Whether a date can be converted to the other calendar. */
+export declare function isConvertible(date: CalendarDate): boolean;
+/** The AD day as "YYYY-MM-DD", the form to store and send (docs/plan D-003). */
+export declare function toIsoDate(date: CalendarDate): string;
+/**
+ * An AD date from "YYYY-MM-DD", or from a longer ISO timestamp by its date part
+ * ("2026-10-18T09:30:00Z" → 2026-10-18). Null for anything else.
+ */
+export declare function fromIsoDate(value: string | null | undefined): AdDate | null;
+/** The AD calendar day an instant falls on in a time zone (Nepal by default). */
+export declare function fromJsDate(instant: Date, timeZone?: string): AdDate;
+/**
+ * The calendar day and time of an ISO timestamp *with a zone* ("…Z",
+ * "…+05:45"), read in `timeZone` (Nepal by default). Null for anything else,
+ * including plain dates, which have no instant.
+ */
+export declare function fromIsoTimestamp(value: string | null | undefined, timeZone?: string): {
+  readonly date: AdDate;
+  readonly time: string;
+} | null;
+//#endregion
+//#region src/projected.d.ts
+/** Whether the date's BS year is after the last year checked against a published calendar. */
+export declare function isProjected(date: CalendarDate): boolean;
+//#endregion
+//#region src/clock.d.ts
+/**
+ * Today's date by the calendar day in `timeZone` (Nepal by default), not the
+ * device's zone. The only function in the library that reads the clock.
+ */
+export declare function today(): AdDate;
+export declare function today<C extends CalendarSystem>(calendar: C, timeZone?: string): DateOf<C>;
+/** The current calendar day and time (HH:MM) in `timeZone` (Nepal by default). */
+export declare function now(timeZone?: string): {
+  readonly date: AdDate;
+  readonly time: {
+    readonly hour: number;
+    readonly minute: number;
+  };
+};
+//#endregion
+//#region src/arithmetic.d.ts
+/** A date in the same calendar as `D`. */
+type Same<D extends CalendarDate> = DateOf<D["calendar"]>;
+export declare function addDays<D extends CalendarDate>(date: D, days: number): Same<D>;
+/** Move by whole months in the date's own calendar; the day is capped to the new month's length. */
+export declare function addMonths<D extends CalendarDate>(date: D, months: number): Same<D>;
+/** Move by whole years in the date's own calendar; the day is capped (29 Feb, short BS months). */
+export declare function addYears<D extends CalendarDate>(date: D, years: number): Same<D>;
+export declare function startOfMonth<D extends CalendarDate>(date: D): Same<D>;
+export declare function endOfMonth<D extends CalendarDate>(date: D): Same<D>;
+export declare function startOfYear<D extends CalendarDate>(date: D): Same<D>;
+export declare function endOfYear<D extends CalendarDate>(date: D): Same<D>;
+export declare function startOfWeek<D extends CalendarDate>(date: D, weekStartsOn?: Weekday): Same<D>;
+export declare function endOfWeek<D extends CalendarDate>(date: D, weekStartsOn?: Weekday): Same<D>;
+/** Whole days from `b` to `a` (positive when `a` is later). The calendars may differ. */
+export declare function differenceInDays(a: CalendarDate, b: CalendarDate): number;
+/** Every day from `start` to `end` inclusive, in `start`'s calendar. Nothing when end < start. */
+export declare function eachDayOfInterval<D extends CalendarDate>(start: D, end: CalendarDate): Generator<Same<D>, void, undefined>;
+/** Every day of the month the date is in. */
+export declare function eachDayOfMonth<D extends CalendarDate>(date: D): Same<D>[];
+//#endregion
+//#region src/compare.d.ts
+type Maybe = CalendarDate | null | undefined;
+/** -1, 0 or 1. Dates in different calendars compare by the day they fall on. */
+export declare function compareDates(a: CalendarDate, b: CalendarDate): -1 | 0 | 1;
+/** Same day, in any calendars. False when either is missing. */
+export declare function isSameDay(a: Maybe, b: Maybe): boolean;
+/** Whether `b` falls in the same month as `a`, judged in `a`'s calendar. */
+export declare function isSameMonth(a: CalendarDate, b: CalendarDate): boolean;
+/** Whether `b` falls in the same year as `a`, judged in `a`'s calendar. */
+export declare function isSameYear(a: CalendarDate, b: CalendarDate): boolean;
+export declare function isBefore(a: CalendarDate, b: CalendarDate): boolean;
+export declare function isAfter(a: CalendarDate, b: CalendarDate): boolean;
+/** On or after `min` and on or before `max`; a missing bound is open. */
+export declare function isWithin(date: CalendarDate, min?: Maybe, max?: Maybe): boolean;
+/** The date, or the nearest bound when it is outside, in the date's calendar. */
+export declare function clampDate<D extends CalendarDate>(date: D, min?: Maybe, max?: Maybe): DateOf<D["calendar"]>;
+/** 0 = Sunday … 6 = Saturday. The same in both calendars. */
+export declare function dayOfWeek(date: CalendarDate): Weekday;
+/** Saturday by default (Nepal); set `weekendDays` in configure() or pass them here. */
+export declare function isWeekend(date: CalendarDate, weekendDays?: readonly Weekday[]): boolean;
+//#endregion
+//#region src/locale/registry.d.ts
+type Names12 = readonly string[];
+/** Everything a language needs: digits, names, UI labels and validation messages. */
+interface LocaleData {
+  /** Ten digit characters, 0–9. */
+  readonly digits: readonly string[];
+  /** Seven names each, Sunday first. */
+  readonly weekdays: {
+    readonly long: readonly string[];
+    readonly short: readonly string[];
+    readonly narrow: readonly string[];
+  };
+  /** Twelve names each, first month first. */
+  readonly months: {
+    readonly AD: {
+      readonly long: Names12;
+      readonly short: Names12;
+    };
+    readonly BS: {
+      readonly long: Names12;
+      readonly short: Names12;
+    };
+  };
+  /** How each calendar is named in this language: "BS" / "वि.सं.". */
+  readonly calendarNames: {
+    readonly AD: string;
+    readonly BS: string;
+  };
+  readonly labels: {
+    readonly today: string;
+    readonly clear: string;
+    readonly previousMonth: string;
+    readonly nextMonth: string;
+    readonly previousYear: string;
+    readonly nextYear: string;
+    readonly month: string;
+    readonly year: string;
+    readonly openCalendar: string;
+    readonly chooseDate: string;
+    readonly calendar: string;
+    /** Picker shortcuts (presets) and the name of their list. */
+    readonly presets: string;
+    readonly fiscalYear: string;
+    readonly time: string;
+    readonly hour: string;
+    readonly minute: string;
+    readonly now: string;
+    readonly done: string;
+  };
+  /** Words for 12-hour times. */
+  readonly time: {
+    readonly am: string;
+    readonly pm: string;
+  };
+  /** Names of the built-in picker presets. */
+  readonly presets: {
+    readonly today: string;
+    readonly yesterday: string;
+    readonly tomorrow: string;
+    readonly thisWeek: string;
+    readonly lastWeek: string;
+    readonly last7Days: string;
+    readonly last30Days: string;
+    readonly thisMonth: string;
+    readonly lastMonth: string;
+    readonly thisYear: string;
+    readonly thisFiscalYear: string;
+    readonly lastFiscalYear: string;
+  };
+  /** Messages may use {min} and {max} placeholders. */
+  readonly messages: {
+    readonly invalidFormat: {
+      readonly AD: string;
+      readonly BS: string;
+    };
+    readonly outOfRange: string;
+    readonly onOrAfter: string;
+    readonly onOrBefore: string;
+    readonly unavailable: string;
+    /** Range pickers: {min} / {max} are day counts. */
+    readonly rangeTooShort: string;
+    readonly rangeTooLong: string;
+    /** Multiple-date pickers: {max} is a count of dates. */
+    readonly tooManyDates: string;
+    readonly invalidTime: string;
+  };
+}
+/** Add or replace a language. Lists must have the right lengths (10 digits, 7 weekdays, 12 months). */
+export declare function registerLocale(code: LocaleCode, data: LocaleData): void;
+export declare function hasLocale(code: LocaleCode): boolean;
+//#endregion
+//#region src/locale/index.d.ts
+/** The data for a locale (the configured default when omitted; English when unknown). */
+export declare function getLocale(locale?: LocaleCode): LocaleData;
+export declare function monthNames(calendar: CalendarSystem, locale?: LocaleCode, width?: "long" | "short"): readonly string[];
+export declare function weekdayNames(locale?: LocaleCode, width?: "long" | "short" | "narrow"): readonly string[];
+/** Replace Devanagari digits with ASCII digits. */
+export declare function toAsciiDigits(value: string): string;
+/** Replace ASCII digits with Devanagari digits. */
+export declare function toDevanagariDigits(value: string | number): string;
+/** Write a number (or digit string) with the locale's digits. */
+export declare function formatNumber(value: string | number, locale?: LocaleCode): string;
+/** Fill {name} placeholders in a locale message. */
+export declare function formatMessage(template: string, values: Record<string, string>): string;
+//#endregion
+//#region src/format.d.ts
+/** Named formats. `cbms` is the dotted form Nepal's tax system uses. */
+export declare const DATE_FORMATS: {
+  readonly iso: "Y-m-d";
+  readonly cbms: "Y.m.d";
+  readonly short: "j M Y";
+  readonly long: "j F Y";
+  readonly full: "l, j F Y";
+};
+type NamedFormat = keyof typeof DATE_FORMATS;
+/** A named format, or a pattern of tokens (see formatDate). */
+type DateFormatPattern = NamedFormat | (string & Record<never, never>);
+/**
+ * Format a date in its own calendar. Tokens: Y 2083, y 83, m 06, n 6, d 09,
+ * j 9, F month name, M short month name, l weekday, D short weekday. Put a
+ * backslash before a letter to print it as is. Digits follow the locale.
+ *
+ *   formatDate(bsDate(2082, 4, 1), 'full')        → "Thursday, 1 Shrawan 2082"
+ *   formatDate(bsDate(2082, 4, 1), 'long', 'ne')  → "१ साउन २०८२"
+ */
+export declare function formatDate(date: CalendarDate, pattern?: DateFormatPattern, locale?: LocaleCode): string;
+//#endregion
+//#region src/parse.d.ts
+/**
+ * A date written year first ("2083-06-24", "2083/6/24", "2083.06.24", or
+ * compact "20830624") in ASCII or Devanagari digits, in the calendar the caller names. Other orders are
+ * rejected, not guessed. Returns null when the text is not a valid date.
+ */
+export declare function parseDate<C extends CalendarSystem>(text: string | null | undefined, calendar: C): DateOf<C> | null;
+/** Like parseDate, but throws a NepDateRangeError that says what is wrong. */
+export declare function parseDateStrict<C extends CalendarSystem>(text: string, calendar: C): DateOf<C>;
+/**
+ * A fiscal year from its label: "2083/84", "2083/2084", "2083-84" or the
+ * tax form "2083.084", in ASCII or Devanagari digits. Null when not valid.
+ */
+export declare function parseFiscalYear(text: string | null | undefined): FiscalYear | null;
+//#endregion
+//#region src/fiscal.d.ts
+/** The fiscal year a date falls in: 1 Shrawan to the end of Asar. */
+export declare function fiscalYear(date: CalendarDate): FiscalYear;
+/** The fiscal year that starts in BS `startYear` (2083 → FY 2083/84). */
+export declare function fiscalYearRange(startYear: number): FiscalYear;
+/**
+ * label "2083/84" · full "2083/2084" · cbms "2083.084" (the form Nepal's tax
+ * system uses). Digits follow the locale.
+ */
+export declare function formatFiscalYear(fy: FiscalYear, style?: "label" | "full" | "cbms", locale?: LocaleCode): string;
+export declare function isInFiscalYear(date: CalendarDate, fy: FiscalYear): boolean;
+//#endregion
+//#region src/time.d.ts
+/** A time of day, 00:00–23:59. Frozen like dates. */
+interface TimeOfDay {
+  readonly hour: number;
+  readonly minute: number;
+}
+export declare function timeOfDay(hour: number, minute?: number): TimeOfDay;
+export declare function isValidTime(hour: number, minute: number): boolean;
+/** -1, 0 or 1. */
+export declare function compareTimes(a: TimeOfDay, b: TimeOfDay): -1 | 0 | 1;
+/**
+ * "14:30", "2:30 pm", "2 PM", "1430", "१४:३०", "२:३० अपराह्न" → TimeOfDay.
+ * Null when the text is not a time.
+ */
+export declare function parseTime(text: string | null | undefined): TimeOfDay | null;
+/** "14:30" (24-hour) or "2:30 PM" (hour12), in the locale's digits and words. */
+export declare function formatTime(time: TimeOfDay, options?: {
+  readonly hour12?: boolean;
+  readonly locale?: LocaleCode;
+}): string;
+/**
+ * The instant of a calendar day and time in a zone (Nepal by default), as an
+ * ISO timestamp with that zone's offset: "2026-10-18T14:30:00+05:45".
+ */
+export declare function toIsoDateTime(date: CalendarDate, time: TimeOfDay, timeZone?: string): string;
+/**
+ * The day and time of an ISO timestamp in a zone (Nepal by default). A value
+ * without an offset ("2026-10-18T14:30", as from <input type="datetime-local">)
+ * is read as a wall time already in that zone. Null for anything else.
+ */
+export declare function fromIsoDateTime(value: string | null | undefined, timeZone?: string): {
+  readonly date: AdDate;
+  readonly time: TimeOfDay;
+} | null;
+//#endregion
+export type { AdDate, BsData, BsDate, CalendarDate, CalendarSystem, DateFormatPattern, DateOf, EpochDay, FiscalYear, LocaleCode, LocaleData, MonthNumber, NamedFormat, NepDateConfig, NepDateDataErrorCode, NepDateRangeErrorCode, TimeOfDay, Weekday };
+//# sourceMappingURL=index.d.ts.map