Convert real-world dates into the Forgotten Realms (Faerûn) calendar format
npm install faerun-dateConvert real-world dates into the Forgotten Realms (Faerûn) calendar format.
Inspired by Dungeons & Dragons and the Harptos calendar.
faerun-date is a JavaScript library that transforms standard dates into the calendar system of Faerûn.
It includes months, 10-day weeks (tendays), seasonal cycles, and Faerûnian holidays like Greengrass and Midsummer.
> ⚠️ Note: This is a simplified model of the Harptos calendar. All months are fixed at 30 days, holidays are added to the count, and leap years are every 4 years (Shieldmeet). Day names are placeholders, not canonical.
---
- 📅 Converts real-world dates to Faerûn calendar dates
- 🗓️ Supports Faerûn-specific months and festivals
- 🌱 Seasonal calculation (Spring, Summer, Autumn, Winter)
- 📆 Week number support (Faerûn “tendays”)
- 🕊️ Leap years with Shieldmeet (every 4 years, simplified)
---
``bash`
npm install faerun-dateor
bun add faerun-date
---
`js
import FaerunDate from 'faerun-date';
const date = new Date(1492, 4, 5); // 5 Mirtul 1492 (months are 0-based)
const faeDate = new FaerunDate(date, { faerunYear: 1492 });
console.log(faeDate.toLocaleString());
// Example: "Far, 05 Mirtul 1492 DR – Season: Spring – Week 19"
console.log(faeDate.getWeekOfYear());
// 19
`
---
Creates a new Faerûn date from a real-world Date. { faerunYear?: number }
Options:
---
`
Far, 05 Mirtul 1492 DR – Season: Spring – Week 19
---
, Far, Tar, Sar, Rai, Zor, Kyth, Hamar, Ith, Alt.> Note: These labels are not canon; they represent tendays.
---
$3
Returns the Faerûnian month name.---
$3
Returns the season:
Winter, Spring, Summer, or Autumn.---
$3
Returns the current year in Dale Reckoning (DR), if provided via options.
Otherwise returns null.---
$3
Returns the name of the festival (Greengrass, Midwinter, etc.)
if the date matches one, otherwise null.---
$3
Returns the week (tenday) number of the year.---
$3
Returns a calendar-style string:
- [Festival] Greengrass if the date is a festival
- 05 Mirtul otherwise---
$3
Returns true if divisible by 4.---
$3
Constructs a FaerunDate from a date string.---
$3
Shortcut to .toLocaleString().---
🧰 CLI Tool: Compare Weeks
This package includes a CLI tool to compare Gregorian weeks with Faerûn tendays.
`bash
npx faerun-compare-weeks --year 1489 --weeks 10
`Example output:
Gregorian Week → Faerûn Tenday Correspondence for year 1489
Week 01 → Tenday 01 (Mon Jan 01 1489)
Week 02 → Tenday 02 (Mon Jan 08 1489)
...
$3
- – Starting Gregorian year (default: current)
- --weeks – Number of weeks to display (default: 20)> Note: Gregorian weeks in the CLI are calculated with a simplified formula (
new Date(year, 0, (week-1)*7+1)); not ISO‑8601.---
⚠️ Limitations
- All months are fixed at 30 days (simplification).
- Leap years are every 4 years (Shieldmeet).
- Day names are placeholders, not canon.
- Faerûn year (DR) must be passed manually in
options`. ---
Released under the MIT License.
© 2025 Cantilux