date-fns-jalali

Common errors

• TypeError: format is not a function

  cause Attempting to use CommonJS `require()` syntax or incorrect named import when the library primarily supports ES Modules, or a bundler issue.
  fix Ensure you are using `import { format } from 'date-fns-jalali';` for ES Modules. If in a CommonJS environment, verify your build process handles ESM imports correctly or check if a specific CJS export is available (less common for this library).

• RangeError: Invalid time value

  cause This error often occurs when date functions receive arguments that do not represent valid date components (e.g., incorrect month or day numbers for the Jalali calendar, or an invalid type passed to `newDate`).
  fix Double-check the arguments passed to `newDate` and other date manipulation functions, ensuring they are within the valid ranges for Jalali year, month, and day. Remember that Jalali months are typically 1-12, and days vary by month and leap year.

• ReferenceError: faIR is not defined

  cause A locale object (like `faIR` for Farsi/Persian) was used in a formatting function but was not correctly imported or provided to the function's options.
  fix Import the required locale explicitly using `import faIR from 'date-fns-jalali/locale/fa-IR';` and pass it to functions that accept a `locale` option, e.g., `format(date, 'PPP', { locale: faIR })`.

Warnings

• breaking In version `4.0.0-0`, the logic for weekend and business days was changed. Only Friday is now considered a weekend day, which may affect calculations involving business days or weekend checks.
  Fix: Review any existing logic that relies on `isWeekend` or `isBusinessDay` functions and adjust expectations or custom weekend definitions accordingly.
• gotcha date-fns-jalali frequently rebases to the upstream date-fns library. This means that breaking changes, new features, or behavior shifts introduced in major or minor versions of `date-fns` will propagate to `date-fns-jalali`. Users should consult `date-fns` release notes in addition to `date-fns-jalali`'s.
  Fix: Always check the `date-fns` changelog for the corresponding version when upgrading `date-fns-jalali`. Thoroughly test date-related logic after any upgrade.
• gotcha When working with Jalali dates, use `newDate` provided by `date-fns-jalali` instead of the native `new Date()` constructor. Mixing them can lead to unexpected behavior or incorrect calendar calculations.
  Fix: Consistently use `newDate(year, month, day)` for creating Jalali calendar dates and convert to/from Gregorian `Date` objects when interacting with other JavaScript APIs if necessary. The `format` function can still accept native `Date` objects for formatting.

Install

• npm install date-fns-jalali npm
• yarn add date-fns-jalali yarn
• pnpm add date-fns-jalali pnpm

Imports

• format
  wrong:

  const format = require('date-fns-jalali').format;

  correct:

  import { format } from 'date-fns-jalali';

  date-fns-jalali is primarily designed for ESM usage. CommonJS `require` might lead to issues depending on your build configuration.
• newDate
  wrong:

  import newDate from 'date-fns-jalali/newDate';

  correct:

  import { newDate } from 'date-fns-jalali';

  `newDate` is the library's factory function for creating Jalali calendar dates, analogous to `new Date()` for Gregorian dates. Individual functions are not typically default exports from subpaths.
• faIR locale
  wrong:

  import { faIR } from 'date-fns-jalali';

  correct:

  import faIR from 'date-fns-jalali/locale/fa-IR';

  Locales are usually imported as default exports from specific subpaths to enable tree-shaking and only include necessary translations.

Quickstart

This quickstart demonstrates basic date formatting from Gregorian to Jalali, creating a new Jalali date object, and sorting dates using `date-fns-jalali`'s core functions.

import { compareAsc, format, newDate } from "date-fns-jalali";

// Format a Gregorian Date to Jalali string
const gregorianDate = new Date(2014, 1, 11); // February 11, 2014
console.log(`Gregorian date (${gregorianDate.toLocaleDateString()}) formatted to Jalali: ${format(gregorianDate, "yyyy-MM-dd")}`);
// Expected output: '1392-11-22'

// Create a new Jalali Date object
const jalaliDate = newDate(1392, 10, 22); // Jalali 1392 Bahman 22
console.log(`New Jalali date (1392/10/22): ${jalaliDate.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric'})}`);
// Expected output: a Date object representing Tue Feb 11 2014 00:00:00

// Format the Jalali Date object with a specific Jalali format (assuming locale is applied or inferred)
console.log(`Formatted Jalali date: ${format(jalaliDate, "yyyy MMMM d")}`);
// Expected output: '1392 بهمن 22'

// Sort an array of Gregorian dates using date-fns-jalali's compare function
const dates = [
  new Date(1995, 6, 2),
  new Date(1987, 1, 11),
  new Date(1989, 6, 10),
];
dates.sort(compareAsc);
console.log('Sorted dates:', dates.map(d => d.toLocaleDateString()));
// Expected output: [Feb 11 1987, Jul 10 1989, Jul 02 1995]