@nepdatejs/core 0.0.0-bootstrap → 0.1.0

package/src/parse.ts

@@ -0,0 +1,67 @@
+import { createDate } from './create';
+import { NepDateRangeError } from './errors';
+import { fiscalYearRange } from './fiscal';
+import { toAsciiDigits } from './locale/index';
+import type { CalendarSystem, DateOf, FiscalYear } from './types';
+
+const YEAR_FIRST = /^(\d{4})[-./](\d{1,2})[-./](\d{1,2})$/;
+const COMPACT = /^(\d{4})(\d{2})(\d{2})$/;
+
+/**
+ * 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 function parseDate<C extends CalendarSystem>(
+  text: string | null | undefined,
+  calendar: C,
+): DateOf<C> | null {
+  try {
+    return parseDateStrict(text ?? '', calendar);
+  } catch {
+    return null;
+  }
+}
+
+/** Like parseDate, but throws a NepDateRangeError that says what is wrong. */
+export function parseDateStrict<C extends CalendarSystem>(
+  text: string,
+  calendar: C,
+): DateOf<C> {
+  const ascii = toAsciiDigits(text).trim();
+  const match = YEAR_FIRST.exec(ascii) ?? COMPACT.exec(ascii);
+  if (!match) {
+    throw new NepDateRangeError(
+      'INVALID_ARGUMENT',
+      `"${text}" is not a date written as YYYY-MM-DD.`,
+    );
+  }
+
+  return createDate(calendar, Number(match[1]), Number(match[2]), Number(match[3]));
+}
+
+/**
+ * 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 function parseFiscalYear(text: string | null | undefined): FiscalYear | null {
+  const match = /^(\d{4})\s*[-/.]\s*(\d{2,4})$/.exec(toAsciiDigits(text ?? '').trim());
+  if (!match) {
+    return null;
+  }
+  const start = Number(match[1]);
+  const end = match[2] ?? '';
+  const next = start + 1;
+  const expected =
+    end.length === 4
+      ? String(next)
+      : String(next % 10 ** end.length).padStart(end.length, '0');
+  if (end !== expected) {
+    return null;
+  }
+  try {
+    return fiscalYearRange(start);
+  } catch {
+    return null;
+  }
+}

package/src/projected.ts

@@ -0,0 +1,8 @@
+import { isProjectedBsYear } from './bs/table';
+import { toCalendar } from './convert';
+import type { CalendarDate } from './types';
+
+/** Whether the date's BS year is after the last year checked against a published calendar. */
+export function isProjected(date: CalendarDate): boolean {
+  return isProjectedBsYear(toCalendar(date, 'BS').year);
+}

package/src/time.ts

@@ -0,0 +1,186 @@
+import { getConfig } from './config';
+import { fromIsoTimestamp, toCalendar } from './convert';
+import { adDate } from './create';
+import { NepDateRangeError } from './errors';
+import { formatNumber, getLocale, toAsciiDigits } from './locale/index';
+import type { AdDate, CalendarDate, LocaleCode } from './types';
+
+/** A time of day, 00:00–23:59. Frozen like dates. */
+export interface TimeOfDay {
+  readonly hour: number;
+  readonly minute: number;
+}
+
+export function timeOfDay(hour: number, minute = 0): TimeOfDay {
+  if (!isValidTime(hour, minute)) {
+    throw new NepDateRangeError(
+      'INVALID_ARGUMENT',
+      `${String(hour)}:${String(minute)} is not a time of day.`,
+    );
+  }
+
+  return Object.freeze({ hour, minute });
+}
+
+export function isValidTime(hour: number, minute: number): boolean {
+  return (
+    Number.isInteger(hour) &&
+    Number.isInteger(minute) &&
+    hour >= 0 &&
+    hour <= 23 &&
+    minute >= 0 &&
+    minute <= 59
+  );
+}
+
+/** -1, 0 or 1. */
+export function compareTimes(a: TimeOfDay, b: TimeOfDay): -1 | 0 | 1 {
+  return Math.sign(a.hour * 60 + a.minute - (b.hour * 60 + b.minute)) as -1 | 0 | 1;
+}
+
+/**
+ * "14:30", "2:30 pm", "2 PM", "1430", "१४:३०", "२:३० अपराह्न" → TimeOfDay.
+ * Null when the text is not a time.
+ */
+export function parseTime(text: string | null | undefined): TimeOfDay | null {
+  let value = toAsciiDigits(text ?? '')
+    .trim()
+    .toLowerCase();
+  let meridiem: 'am' | 'pm' | null = null;
+  for (const code of ['en', 'ne'] as const) {
+    const { am, pm } = getLocale(code).time;
+    for (const [word, kind] of [
+      [am.toLowerCase(), 'am'],
+      [pm.toLowerCase(), 'pm'],
+      [am.toLowerCase().replace(/(.)/g, '$1.'), 'am'],
+      [pm.toLowerCase().replace(/(.)/g, '$1.'), 'pm'],
+    ] as const) {
+      if (value.endsWith(word)) {
+        meridiem = kind;
+        value = value.slice(0, -word.length).trim();
+        break;
+      }
+    }
+    if (meridiem) {
+      break;
+    }
+  }
+  const match =
+    /^(\d{1,2})(?:[:.](\d{2}))?$/.exec(value) ?? /^(\d{2})(\d{2})$/.exec(value);
+  if (!match) {
+    return null;
+  }
+  let hour = Number(match[1]);
+  const minute = Number(match[2] ?? 0);
+  if (meridiem) {
+    if (hour < 1 || hour > 12) {
+      return null;
+    }
+    hour = (hour % 12) + (meridiem === 'pm' ? 12 : 0);
+  }
+
+  return isValidTime(hour, minute) ? timeOfDay(hour, minute) : null;
+}
+
+/** "14:30" (24-hour) or "2:30 PM" (hour12), in the locale's digits and words. */
+export function formatTime(
+  time: TimeOfDay,
+  options: { readonly hour12?: boolean; readonly locale?: LocaleCode } = {},
+): string {
+  const minute = String(time.minute).padStart(2, '0');
+  if (!options.hour12) {
+    return formatNumber(
+      `${String(time.hour).padStart(2, '0')}:${minute}`,
+      options.locale,
+    );
+  }
+  const { am, pm } = getLocale(options.locale).time;
+  const hour = time.hour % 12 === 0 ? 12 : time.hour % 12;
+
+  return `${formatNumber(`${hour}:${minute}`, options.locale)} ${time.hour < 12 ? am : pm}`;
+}
+
+/**
+ * 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 function toIsoDateTime(
+  date: CalendarDate,
+  time: TimeOfDay,
+  timeZone: string = getConfig().timeZone,
+): string {
+  const { year, month, day } = toCalendar(date, 'AD');
+  if (year < 0 || year > 9999) {
+    throw new NepDateRangeError(
+      'INVALID_ARGUMENT',
+      `AD year ${year} cannot be written in ISO form.`,
+    );
+  }
+  const wall = Date.UTC(year, month - 1, day, time.hour, time.minute);
+  const first = offsetMinutes(wall, timeZone);
+  const offset = offsetMinutes(wall - first * 60_000, timeZone);
+  const sign = offset < 0 ? '-' : '+';
+  const abs = Math.abs(offset);
+  const pad = (value: number, length = 2): string => String(value).padStart(length, '0');
+
+  return `${pad(year, 4)}-${pad(month)}-${pad(day)}T${pad(time.hour)}:${pad(time.minute)}:00${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`;
+}
+
+/**
+ * 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 function fromIsoDateTime(
+  value: string | null | undefined,
+  timeZone: string = getConfig().timeZone,
+): { readonly date: AdDate; readonly time: TimeOfDay } | null {
+  const zoned = fromIsoTimestamp(value, timeZone);
+  if (zoned) {
+    const time = parseTime(zoned.time);
+    return time ? { date: zoned.date, time } : null;
+  }
+  const local = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::\d{2}(?:\.\d+)?)?$/.exec(
+    value ?? '',
+  );
+  if (!local) {
+    return null;
+  }
+  try {
+    return {
+      date: adDate(Number(local[1]), Number(local[2]), Number(local[3])),
+      time: timeOfDay(Number(local[4]), Number(local[5])),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Minutes the zone is ahead of UTC at an instant. */
+function offsetMinutes(instant: number, timeZone: string): number {
+  let parts: Intl.DateTimeFormatPart[];
+  try {
+    parts = new Intl.DateTimeFormat('en-US', {
+      timeZone,
+      hourCycle: 'h23',
+      year: 'numeric',
+      month: 'numeric',
+      day: 'numeric',
+      hour: 'numeric',
+      minute: 'numeric',
+    }).formatToParts(new Date(instant));
+  } catch {
+    throw new NepDateRangeError('INVALID_ARGUMENT', `"${timeZone}" is not a time zone.`);
+  }
+  const part = (type: Intl.DateTimeFormatPartTypes): number =>
+    Number(parts.find((item) => item.type === type)?.value ?? 0);
+  const wall = Date.UTC(
+    part('year'),
+    part('month') - 1,
+    part('day'),
+    part('hour'),
+    part('minute'),
+  );
+
+  return Math.round((wall - Math.floor(instant / 60_000) * 60_000) / 60_000);
+}

package/src/types.ts

@@ -0,0 +1,61 @@
+/** The two calendars this library knows. */
+export 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.
+ */
+export type EpochDay = number & { readonly __brand: 'EpochDay' };
+
+/** 0 = Sunday … 6 = Saturday. */
+export type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+/** 1 = Baisakh/January … 12 = Chaitra/December. */
+export type MonthNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+
+/** A Gregorian (AD) calendar day. Create with `adDate()`; always frozen. */
+export 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. */
+export interface BsDate {
+  readonly calendar: 'BS';
+  readonly year: number;
+  readonly month: MonthNumber;
+  readonly day: number;
+}
+
+export type CalendarDate = AdDate | BsDate;
+
+/** The date type of a calendar: `DateOf<'BS'>` is `BsDate`. */
+export 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). */
+export 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`. */
+export type LocaleCode = 'en' | 'ne' | (string & Record<never, never>);
+
+/** Nepal's fiscal year: 1 Shrawan to the last day of Asar. */
+export 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;
+}