📅 faerun-date

Convert 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, the world of the Forgotten Realms (Dungeons & Dragons). It includes accurate mapping of months, 10-day weeks, seasonal cycles, and unique Faerûnian holidays like Greengrass and Midsummer.

Perfect for RPG tools, worldbuilding projects, and immersive D&D experiences.

---

✨ Features

• 📅 Converts real-world dates to Faerûn calendar dates
• 🗓️ Supports Faerûn-specific months and festivals
• 🌱 Includes seasonal calculation (Spring, Summer, Autumn, Winter)
• 📆 Week number support: calculates the week of the year (1–53)
• 🕊️ Leap years (with Shieldmeet) fully supported

---

📦 Installation

With npm

npm install faerun-date

With bun

bun add faerun-date

🧙 Usage

import { FaerunDate } from 'faerun-date';

const date = new Date(1492, 4, 5); // 5 Mirtul 1492 DR (month is 0-based)
const faeDate = new FaerunDate(date);

console.log(faeDate.toLocaleString());
// "Godsday, 5 Mirtul 1492 DR – Season: Spring – Week 19"

console.log(faeDate.getWeekOfYear());
// 19

📚 API

new FaerunDate(date)

Creates a new Faerûn date from a real-world Date object or a structured object with day, month, and year.

---

toLocaleString()

Returns a human-readable string representing the Faerûn date.

Example:

Godsday, 5 Mirtul 1492 DR – Season: Spring – Week 19

---

getWeekday()

Returns the name of the day of the week
(e.g. Godsday, Earthday, Kythorn, etc.)

---

getMonth()

Returns the name of the month

---

getSeason()

Returns the current season:
Winter, Spring, Summer, or Autumn.

---

getFaerunYear()

Returns the current year in Dale Reckoning (DR).

---

getFestival()

Returns the name of the festival (e.g. Greengrass, Midwinter)
if the date matches one. Returns null otherwise.

---

getWeekOfYear()

Returns the week number in the Faerûn calendar year.

• Week 1 starts on 1 Hammer
• Festivals are included in the day/week count
• Leap years (with Shieldmeet) are supported

🧰 CLI Tool: Compare Weeks

This package includes a CLI tool to compare Gregorian calendar weeks with Faerûn tendays.

Useful for Dungeon Masters who want to align real-world weeks with in-game Faerûn time.

🔧 Usage

After installing the package (or using bun link / npm link):

npx faerun-compare-weeks
# or with custom options:
npx faerun-compare-weeks --year 1489 --weeks 30

You can also run it directly if you're developing locally:

bun run bin/compare-weeks.js --year 1491 --weeks 15

🧩 Options

• --year <YYYY> – The Gregorian year to compare (default: current year)
• --weeks <N> – Number of Gregorian weeks to display (default: 20)

📋 Output Example

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)
Week 03 → Tenday 03 (Mon Jan 15 1489)
...
Week 15 → Tenday 10 (Mon Apr 07 1489)

🧙 Ideal for planning weekly D&D sessions, synchronizing downtime, or tracking Faerûn time progression alongside real-world calendars.

📜 License

Released under the MIT License.
© 2025 Cantilux