Date Converter Guide

The date converter utilities provide pure standalone functions for converting date strings directly between the Gregorian calendar and the Bikram Sambat calendar. These functions operate without creating full class instances, making them suitable for high throughput batch processing, database migrations, and backend service integration.

When to Use Helper Functions vs. the NepaliDate ClassCopy Anchor Link

Timezone Drift PreventionCopy Anchor Link

One of the most frequent bugs when converting dates in distributed environments is single-day shifting caused by local server timezones.

For example, parsing "2024-11-01" using new Date("2024-11-01") in a system running in UTC-5 (Eastern Time) produces 2024-10-31 19:00:00, which erroneously converts to the previous Nepali date.

ADtoBS and BStoAD internally enforce strict UTC parsing via Date.UTC:

• "2024-11-01" is always resolved at 2024-11-01T00:00:00.000Z.
• Conversions produce identical results regardless of whether your code runs in Tokyo (UTC+9), Kathmandu (UTC+5:45), London (UTC+0), or San Francisco (UTC-8).

Input Format StandardCopy Anchor Link

Both conversion functions enforce the ISO-8601 standard date format:

YYYY-MM-DD

• Years must be 4 digits.
• Months must be 2 zero-padded digits (01 to 12).
• Days must be 2 zero-padded digits (01 to 32).

Passing strings with non-standard delimiters or single digits (e.g. 2081-7-5 or 2081/07/05) will throw an explicit format error.

Error Handling & DateConversionErrorCopy Anchor Link

All conversion errors throw a descriptive exception or an instance of DateConversionError containing the underlying cause:

import { ADtoBS } from "nepali-date-library";

try {
  const bsDate = ADtoBS("invalid-date-string");
} catch (error) {
  if (error instanceof Error) {
    console.error(error.message); // "Invalid date format. Expected format: YYYY-MM-DD"
  }
}

Next StepsCopy Anchor Link

Explore the individual function references:

• ADtoBS(): Convert Gregorian AD strings to Bikram Sambat BS.
• BStoAD(): Convert Bikram Sambat BS strings to Gregorian AD.