@nepdatejs/core 0.0.0-bootstrap → 0.1.0

package/src/bs/table.ts

@@ -0,0 +1,154 @@
+/**
+ * The Bikram Sambat calendar, from its table only. Nothing here reads or
+ * produces an AD year: BS dates map to and from day counts (EpochDay) through
+ * `epochStart` and the month lengths (docs/plan D-001).
+ */
+import { NepDateRangeError } from '../errors';
+import type { BsData } from '../types';
+import { BS_DATA } from './data/years';
+
+interface BsTable {
+  readonly data: BsData;
+  readonly lastYear: number;
+  /** yearStart[i] = day count of 1 Baisakh of firstYear + i; one extra entry for the end. */
+  readonly yearStart: Float64Array;
+  /** monthOffset[i * 12 + m] = days from 1 Baisakh to the first of month m + 1 in year i. */
+  readonly monthOffset: Uint16Array;
+}
+
+let data: BsData = freezeData(BS_DATA);
+let table: BsTable | null = null;
+
+/** Replace the data the table is built from. Callers validate first (data-api.ts). */
+export function useBsData(next: BsData): void {
+  data = freezeData(next);
+  table = null;
+}
+
+function freezeData(source: BsData): BsData {
+  return Object.freeze({
+    firstYear: source.firstYear,
+    epochStart: source.epochStart,
+    verifiedThrough: source.verifiedThrough,
+    years: Object.freeze(source.years.map((months) => Object.freeze([...months]))),
+  });
+}
+
+export function currentBsData(): BsData {
+  return data;
+}
+
+function buildTable(): BsTable {
+  const count = data.years.length;
+  const yearStart = new Float64Array(count + 1);
+  const monthOffset = new Uint16Array(count * 12);
+  let start = data.epochStart;
+
+  for (let i = 0; i < count; i++) {
+    yearStart[i] = start;
+    const months = data.years[i] ?? [];
+    let offset = 0;
+    for (let m = 0; m < 12; m++) {
+      monthOffset[i * 12 + m] = offset;
+      offset += months[m] ?? 0;
+    }
+    start += offset;
+  }
+  yearStart[count] = start;
+
+  return { data, lastYear: data.firstYear + count - 1, yearStart, monthOffset };
+}
+
+function bsTable(): BsTable {
+  return (table ??= buildTable());
+}
+
+export function bsFirstYear(): number {
+  return data.firstYear;
+}
+
+export function bsLastYear(): number {
+  return bsTable().lastYear;
+}
+
+/** The first and last day counts the table covers. */
+export function bsEpochRange(): { first: number; last: number } {
+  const { yearStart } = bsTable();
+
+  return { first: yearStart[0] ?? 0, last: (yearStart[yearStart.length - 1] ?? 0) - 1 };
+}
+
+/** Days in a BS month. Throws when the year is outside the table or the month is not 1–12. */
+export function bsMonthLength(year: number, month: number): number {
+  const { lastYear } = bsTable();
+  if (!Number.isInteger(year) || year < data.firstYear || year > lastYear) {
+    throw new NepDateRangeError(
+      'OUT_OF_TABLE',
+      `BS year ${String(year)} is outside the supported range (BS ${data.firstYear}–${lastYear}).`,
+    );
+  }
+  if (!Number.isInteger(month) || month < 1 || month > 12) {
+    throw new NepDateRangeError(
+      'INVALID_DATE',
+      `BS month ${String(month)} does not exist.`,
+    );
+  }
+
+  return data.years[year - data.firstYear]?.[month - 1] ?? 0;
+}
+
+export function isValidBsDate(year: number, month: number, day: number): boolean {
+  try {
+    return Number.isInteger(day) && day >= 1 && day <= bsMonthLength(year, month);
+  } catch {
+    return false;
+  }
+}
+
+/** Day count of a valid BS date. */
+export function bsToEpoch(year: number, month: number, day: number): number {
+  const { yearStart, monthOffset } = bsTable();
+  const index = year - data.firstYear;
+
+  return (yearStart[index] ?? 0) + (monthOffset[index * 12 + month - 1] ?? 0) + day - 1;
+}
+
+/** The BS year, month and day of a day count. Throws when it is outside the table. */
+export function epochToBs(epoch: number): { year: number; month: number; day: number } {
+  const { yearStart, monthOffset } = bsTable();
+  const { first, last } = bsEpochRange();
+  if (epoch < first || epoch > last) {
+    throw new NepDateRangeError(
+      'OUT_OF_TABLE',
+      `Day ${epoch} is outside the BS table (BS ${data.firstYear}–${bsLastYear()}).`,
+    );
+  }
+
+  // Last year whose start is on or before the day.
+  let low = 0;
+  let high = yearStart.length - 2;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if ((yearStart[middle] ?? 0) <= epoch) {
+      low = middle;
+    } else {
+      high = middle - 1;
+    }
+  }
+  const dayOfYear = epoch - (yearStart[low] ?? 0);
+  let month = 11;
+  while (month > 0 && (monthOffset[low * 12 + month] ?? 0) > dayOfYear) {
+    month--;
+  }
+
+  return {
+    year: data.firstYear + low,
+    month: month + 1,
+    day: dayOfYear - (monthOffset[low * 12 + month] ?? 0) + 1,
+  };
+}
+
+/** Whether a BS year is after the last year checked against a published calendar. */
+export function isProjectedBsYear(year: number): boolean {
+  return year > data.verifiedThrough;
+}

package/src/clock.ts

@@ -0,0 +1,33 @@
+import { getConfig } from './config';
+import { fromIsoTimestamp, fromJsDate, toCalendar } from './convert';
+import type { AdDate, CalendarSystem, DateOf } from './types';
+
+/**
+ * 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 function today(): AdDate;
+export function today<C extends CalendarSystem>(
+  calendar: C,
+  timeZone?: string,
+): DateOf<C>;
+export function today(
+  calendar: CalendarSystem = 'AD',
+  timeZone: string = getConfig().timeZone,
+): AdDate | DateOf<CalendarSystem> {
+  return toCalendar(fromJsDate(new Date(), timeZone), calendar);
+}
+
+/** The current calendar day and time (HH:MM) in `timeZone` (Nepal by default). */
+export function now(timeZone: string = getConfig().timeZone): {
+  readonly date: AdDate;
+  readonly time: { readonly hour: number; readonly minute: number };
+} {
+  const current = fromIsoTimestamp(new Date().toISOString(), timeZone);
+  const [hour = 0, minute = 0] = (current?.time ?? '00:00').split(':').map(Number);
+
+  return {
+    date: current?.date ?? fromJsDate(new Date(), timeZone),
+    time: Object.freeze({ hour, minute }),
+  };
+}

package/src/compare.ts

@@ -0,0 +1,73 @@
+import { inCalendarOf } from './arithmetic';
+import { getConfig } from './config';
+import { toCalendar, toEpoch } from './convert';
+import { weekdayOf } from './epoch';
+import type { CalendarDate, DateOf, Weekday } from './types';
+
+type Maybe = CalendarDate | null | undefined;
+
+/** -1, 0 or 1. Dates in different calendars compare by the day they fall on. */
+export function compareDates(a: CalendarDate, b: CalendarDate): -1 | 0 | 1 {
+  return Math.sign(toEpoch(a) - toEpoch(b)) as -1 | 0 | 1;
+}
+
+/** Same day, in any calendars. False when either is missing. */
+export function isSameDay(a: Maybe, b: Maybe): boolean {
+  return a != null && b != null && toEpoch(a) === toEpoch(b);
+}
+
+/** Whether `b` falls in the same month as `a`, judged in `a`'s calendar. */
+export function isSameMonth(a: CalendarDate, b: CalendarDate): boolean {
+  const other = inCalendarOf(a, b);
+
+  return other.year === a.year && other.month === a.month;
+}
+
+/** Whether `b` falls in the same year as `a`, judged in `a`'s calendar. */
+export function isSameYear(a: CalendarDate, b: CalendarDate): boolean {
+  return inCalendarOf(a, b).year === a.year;
+}
+
+export function isBefore(a: CalendarDate, b: CalendarDate): boolean {
+  return toEpoch(a) < toEpoch(b);
+}
+
+export function isAfter(a: CalendarDate, b: CalendarDate): boolean {
+  return toEpoch(a) > toEpoch(b);
+}
+
+/** On or after `min` and on or before `max`; a missing bound is open. */
+export function isWithin(date: CalendarDate, min?: Maybe, max?: Maybe): boolean {
+  const day = toEpoch(date);
+
+  return (min == null || day >= toEpoch(min)) && (max == null || day <= toEpoch(max));
+}
+
+/** The date, or the nearest bound when it is outside, in the date's calendar. */
+export function clampDate<D extends CalendarDate>(
+  date: D,
+  min?: Maybe,
+  max?: Maybe,
+): DateOf<D['calendar']> {
+  if (min != null && isBefore(date, min)) {
+    return toCalendar(min, date.calendar) as DateOf<D['calendar']>;
+  }
+  if (max != null && isAfter(date, max)) {
+    return toCalendar(max, date.calendar) as DateOf<D['calendar']>;
+  }
+
+  return date as DateOf<D['calendar']>;
+}
+
+/** 0 = Sunday … 6 = Saturday. The same in both calendars. */
+export function dayOfWeek(date: CalendarDate): Weekday {
+  return weekdayOf(toEpoch(date));
+}
+
+/** Saturday by default (Nepal); set `weekendDays` in configure() or pass them here. */
+export function isWeekend(
+  date: CalendarDate,
+  weekendDays: readonly Weekday[] = getConfig().weekendDays,
+): boolean {
+  return weekendDays.includes(dayOfWeek(date));
+}

package/src/config.ts

@@ -0,0 +1,85 @@
+import { NepDateRangeError } from './errors';
+import { hasLocale } from './locale/registry';
+import type { LocaleCode, Weekday } from './types';
+
+/**
+ * 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).
+ */
+export 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;
+}
+
+const DEFAULTS: NepDateConfig = Object.freeze({
+  timeZone: 'Asia/Kathmandu',
+  weekStartsOn: 0,
+  weekendDays: Object.freeze<Weekday[]>([6]),
+  defaultLocale: 'en',
+});
+
+let current: NepDateConfig = DEFAULTS;
+
+/** Change one or more settings. Every value is checked before any is applied. */
+export function configure(changes: Partial<NepDateConfig>): void {
+  const next = { ...current, ...changes };
+
+  if (!isTimeZone(next.timeZone)) {
+    throw new NepDateRangeError(
+      'INVALID_ARGUMENT',
+      `"${next.timeZone}" is not a time zone.`,
+    );
+  }
+  if (!isWeekday(next.weekStartsOn)) {
+    throw new NepDateRangeError(
+      'INVALID_ARGUMENT',
+      `weekStartsOn must be 0–6, not ${String(next.weekStartsOn)}.`,
+    );
+  }
+  if (
+    !next.weekendDays.every(isWeekday) ||
+    new Set(next.weekendDays).size !== next.weekendDays.length
+  ) {
+    throw new NepDateRangeError(
+      'INVALID_ARGUMENT',
+      'weekendDays must be different weekdays, each 0–6.',
+    );
+  }
+  if (!hasLocale(next.defaultLocale)) {
+    throw new NepDateRangeError(
+      'INVALID_ARGUMENT',
+      `Locale "${next.defaultLocale}" is not registered.`,
+    );
+  }
+
+  current = Object.freeze({
+    ...next,
+    weekendDays: Object.freeze([...next.weekendDays]),
+  });
+}
+
+export function getConfig(): NepDateConfig {
+  return current;
+}
+
+/** Back to the defaults (Kathmandu, Sunday first, Saturday weekend, English). */
+export function resetConfig(): void {
+  current = DEFAULTS;
+}
+
+export function isWeekday(value: unknown): value is Weekday {
+  return Number.isInteger(value) && (value as number) >= 0 && (value as number) <= 6;
+}
+
+function isTimeZone(value: string): boolean {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: value });
+
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/convert.ts

@@ -0,0 +1,188 @@
+/**
+ * The only place the AD and BS calendars meet, and only through EpochDay
+ * (docs/plan D-001). Nothing here looks up a year number across calendars.
+ */
+import { adToEpoch, epochToAd } from './ad/calendar';
+import { bsEpochRange, bsToEpoch, epochToBs } from './bs/table';
+import { getConfig } from './config';
+import { adDate, bsDate } from './create';
+import { toEpochDay } from './epoch';
+import { NepDateRangeError } from './errors';
+import type {
+  AdDate,
+  BsDate,
+  CalendarDate,
+  CalendarSystem,
+  DateOf,
+  EpochDay,
+} from './types';
+
+/** The day count of a date in either calendar. */
+export function toEpoch(date: CalendarDate): EpochDay {
+  return toEpochDay(
+    date.calendar === 'AD'
+      ? adToEpoch(date.year, date.month, date.day)
+      : bsToEpoch(date.year, date.month, date.day),
+  );
+}
+
+/** The date of a day count in a calendar. BS throws OUT_OF_TABLE outside the table. */
+export function fromEpoch<C extends CalendarSystem>(
+  epoch: EpochDay,
+  calendar: C,
+): DateOf<C> {
+  if (calendar === 'AD') {
+    const { year, month, day } = epochToAd(epoch);
+
+    return adDate(year, month, day) as DateOf<C>;
+  }
+  assertConvertible(epoch);
+  const { year, month, day } = epochToBs(epoch);
+
+  return bsDate(year, month, day) as DateOf<C>;
+}
+
+export function adToBs(date: AdDate): BsDate {
+  return fromEpoch(toEpoch(date), 'BS');
+}
+
+export function bsToAd(date: BsDate): AdDate {
+  return fromEpoch(toEpoch(date), 'AD');
+}
+
+/** The same day in the given calendar (the date itself when it is already in it). */
+export function toCalendar<C extends CalendarSystem>(
+  date: CalendarDate,
+  calendar: C,
+): DateOf<C> {
+  if (date.calendar === calendar) {
+    return date as DateOf<C>;
+  }
+
+  return fromEpoch(toEpoch(date), calendar);
+}
+
+/** The first day that can be converted, in either calendar (the start of the BS table). */
+export function minDate<C extends CalendarSystem>(calendar: C): DateOf<C> {
+  return fromEpoch(toEpochDay(bsEpochRange().first), calendar);
+}
+
+/** The last day that can be converted, in either calendar (the end of the BS table). */
+export function maxDate<C extends CalendarSystem>(calendar: C): DateOf<C> {
+  return fromEpoch(toEpochDay(bsEpochRange().last), calendar);
+}
+
+/** Whether a date can be converted to the other calendar. */
+export function isConvertible(date: CalendarDate): boolean {
+  const epoch = toEpoch(date);
+  const { first, last } = bsEpochRange();
+
+  return epoch >= first && epoch <= last;
+}
+
+/** The AD day as "YYYY-MM-DD", the form to store and send (docs/plan D-003). */
+export function toIsoDate(date: CalendarDate): string {
+  const { year, month, day } = toCalendar(date, 'AD');
+  if (year < 0 || year > 9999) {
+    throw new NepDateRangeError(
+      'INVALID_ARGUMENT',
+      `AD year ${year} cannot be written as YYYY-MM-DD.`,
+    );
+  }
+
+  return `${pad(year, 4)}-${pad(month, 2)}-${pad(day, 2)}`;
+}
+
+/**
+ * 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 function fromIsoDate(value: string | null | undefined): AdDate | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})(?:$|[T ])/.exec(value ?? '');
+  if (!match) {
+    return null;
+  }
+  try {
+    return adDate(Number(match[1]), Number(match[2]), Number(match[3]));
+  } catch {
+    return null;
+  }
+}
+
+/** The AD calendar day an instant falls on in a time zone (Nepal by default). */
+export function fromJsDate(
+  instant: Date,
+  timeZone: string = getConfig().timeZone,
+): AdDate {
+  if (Number.isNaN(instant.getTime())) {
+    throw new NepDateRangeError('INVALID_ARGUMENT', 'The Date is invalid.');
+  }
+  let parts: Intl.DateTimeFormatPart[];
+  try {
+    parts = new Intl.DateTimeFormat('en-US', {
+      timeZone,
+      year: 'numeric',
+      month: 'numeric',
+      day: 'numeric',
+      era: 'short',
+    }).formatToParts(instant);
+  } catch {
+    throw new NepDateRangeError('INVALID_ARGUMENT', `"${timeZone}" is not a time zone.`);
+  }
+  const part = (type: Intl.DateTimeFormatPartTypes): string =>
+    parts.find((item) => item.type === type)?.value ?? '';
+  const year = Number(part('year'));
+
+  return adDate(
+    part('era') === 'BC' ? 1 - year : year,
+    Number(part('month')),
+    Number(part('day')),
+  );
+}
+
+/**
+ * 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 function fromIsoTimestamp(
+  value: string | null | undefined,
+  timeZone: string = getConfig().timeZone,
+): { readonly date: AdDate; readonly time: string } | null {
+  if (!value || !/T.*(?:Z|[+-]\d{2}:?\d{2})$/.test(value)) {
+    return null;
+  }
+  const instant = new Date(value);
+  if (Number.isNaN(instant.getTime())) {
+    return null;
+  }
+  const time = new Intl.DateTimeFormat('en-GB', {
+    timeZone,
+    hour: '2-digit',
+    minute: '2-digit',
+    hourCycle: 'h23',
+  }).format(instant);
+
+  return { date: fromJsDate(instant, timeZone), time };
+}
+
+function assertConvertible(epoch: number): void {
+  const { first, last } = bsEpochRange();
+  if (epoch < first || epoch > last) {
+    const { year, month, day } = epochToAd(epoch);
+    const from = epochToAd(first);
+    const to = epochToAd(last);
+    throw new NepDateRangeError(
+      'OUT_OF_TABLE',
+      `AD ${isoParts(year, month, day)} is outside the BS table (AD ${isoParts(from.year, from.month, from.day)} to ${isoParts(to.year, to.month, to.day)}).`,
+    );
+  }
+}
+
+function isoParts(year: number, month: number, day: number): string {
+  return `${year}-${pad(month, 2)}-${pad(day, 2)}`;
+}
+
+function pad(value: number, length: number): string {
+  return String(value).padStart(length, '0');
+}

package/src/create.ts

@@ -0,0 +1,112 @@
+import { adMonthLength, isValidAdDate, MAX_AD_YEAR } from './ad/calendar';
+import { bsMonthLength, isValidBsDate } from './bs/table';
+import { NepDateRangeError } from './errors';
+import type {
+  AdDate,
+  BsDate,
+  CalendarDate,
+  CalendarSystem,
+  DateOf,
+  MonthNumber,
+} from './types';
+
+/** An AD date. Any year within ±999,999 is allowed; only conversion to BS is limited. */
+export function adDate(year: number, month: number, day: number): AdDate {
+  if (!isValidAdDate(year, month, day)) {
+    throw new NepDateRangeError(
+      Number.isInteger(year) && Number.isInteger(month) && Number.isInteger(day)
+        ? 'INVALID_DATE'
+        : 'INVALID_ARGUMENT',
+      Math.abs(year) > MAX_AD_YEAR
+        ? `AD year ${String(year)} is outside ±${MAX_AD_YEAR}.`
+        : `AD ${String(year)}-${String(month)}-${String(day)} is not a valid date.`,
+    );
+  }
+
+  return Object.freeze({ calendar: 'AD', year, month: month as MonthNumber, day });
+}
+
+/** A BS date. The year must be in the BS table. */
+export function bsDate(year: number, month: number, day: number): BsDate {
+  const length = bsMonthLength(year, month);
+  if (!Number.isInteger(day) || day < 1 || day > length) {
+    throw new NepDateRangeError(
+      Number.isInteger(day) ? 'INVALID_DATE' : 'INVALID_ARGUMENT',
+      `BS ${year}-${month} has ${length} days, not ${String(day)}.`,
+    );
+  }
+
+  return Object.freeze({ calendar: 'BS', year, month: month as MonthNumber, day });
+}
+
+export function createDate<C extends CalendarSystem>(
+  calendar: C,
+  year: number,
+  month: number,
+  day: number,
+): DateOf<C> {
+  return (
+    calendar === 'AD' ? adDate(year, month, day) : bsDate(year, month, day)
+  ) as DateOf<C>;
+}
+
+export function isValidDate(
+  calendar: CalendarSystem,
+  year: number,
+  month: number,
+  day: number,
+): boolean {
+  return calendar === 'AD'
+    ? isValidAdDate(year, month, day)
+    : isValidBsDate(year, month, day);
+}
+
+/** Days in a month of either calendar. */
+export function daysInMonth(
+  calendar: CalendarSystem,
+  year: number,
+  month: number,
+): number {
+  if (calendar === 'BS') {
+    return bsMonthLength(year, month);
+  }
+  if (!isValidAdDate(year, month, 1)) {
+    throw new NepDateRangeError(
+      'INVALID_DATE',
+      `AD ${String(year)}-${String(month)} is not a month.`,
+    );
+  }
+
+  return adMonthLength(year, month);
+}
+
+/** True for a valid, frozen-or-not AD date object (e.g. from JSON). */
+export function isAdDate(value: unknown): value is AdDate {
+  return isDateLike(value, 'AD') && isValidAdDate(value.year, value.month, value.day);
+}
+
+/** True for a valid BS date object (e.g. from JSON). */
+export function isBsDate(value: unknown): value is BsDate {
+  return isDateLike(value, 'BS') && isValidBsDate(value.year, value.month, value.day);
+}
+
+export function isCalendarDate(value: unknown): value is CalendarDate {
+  return isAdDate(value) || isBsDate(value);
+}
+
+function isDateLike(
+  value: unknown,
+  calendar: CalendarSystem,
+): value is { calendar: CalendarSystem; year: number; month: number; day: number } {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+
+  return (
+    record['calendar'] === calendar &&
+    typeof record['year'] === 'number' &&
+    typeof record['month'] === 'number' &&
+    typeof record['day'] === 'number'
+  );
+}

package/src/data.ts

@@ -0,0 +1,2 @@
+/** The raw BS table bundled with @nepdatejs/core, for tools that need the data itself. */
+export { BS_DATA, type GeneratedBsData } from './bs/data/years';

package/src/epoch.ts

@@ -0,0 +1,19 @@
+import { NepDateRangeError } from './errors';
+import type { EpochDay, Weekday } from './types';
+
+/** Brand a whole number of days since 1970-01-01 as an `EpochDay`. */
+export function toEpochDay(value: number): EpochDay {
+  if (!Number.isSafeInteger(value)) {
+    throw new NepDateRangeError(
+      'INVALID_ARGUMENT',
+      `${String(value)} is not a whole number of days.`,
+    );
+  }
+
+  return value as EpochDay;
+}
+
+/** The weekday of a day count. 1970-01-01 was a Thursday. */
+export function weekdayOf(epoch: EpochDay): Weekday {
+  return ((((epoch + 4) % 7) + 7) % 7) as Weekday;
+}