Doran

The Open Source Persian Calendar Ecosystem

📖 Documentation · 🧭 Examples · ⚛️ React demo · 💚 Vue demo · 🧡 Svelte demo · 🅰️ Angular demo · 🌐 Vanilla demo

دوران — A complete, accurate, and developer-friendly toolkit for the Solar Hijri (Persian / Jalali) calendar.

Doran is a TypeScript monorepo that provides everything you need to work with the Persian calendar: a rock-solid date engine, natural-language parsing, holiday datasets, calendar components for React/Vue/Svelte/Angular, and a design system — all tree-shakeable, strongly typed, and immutable.

Packages

Package	Description	Status
@doranjs/core	Immutable DoranDate, conversions, arithmetic, format	✅
@doranjs/nlp	Persian natural-language date parsing	✅
@doranjs/holidays	Iranian official & religious holidays	✅
@doranjs/react	RTL-first, accessible React calendar components	✅
@doranjs/vue	v-model calendar components + headless composables	✅
@doranjs/svelte	bind:value calendar components + headless stores	✅
@doranjs/angular	Standalone components + ControlValueAccessor bindings	✅
@doranjs/wc	Framework-agnostic Web Components for plain HTML	✅
@doranjs/zod	Zod schema factory for Persian date validation	✅
@doranjs/ui	Minimal, themeable design system	✅

Quick start

pnpm add @doranjs/core

import { DoranDate } from '@doranjs/core';

const today = DoranDate.now();

today.format('YYYY/MM/DD'); // ۱۴۰۵/۰۳/۱۱ → "1405/03/11"
today.addDays(10).format('dddd D MMMM YYYY');
today.toGregorian(); // native Date

DoranDate.fromGregorian(new Date());

Parse Persian dates from free text — including Finglish and keyboard-layout typos:

import { parse } from '@doranjs/nlp';

parse('جمعه ساعت ۷ شب'); // → { date, confidence, matched }
parse('بیست و یکم خرداد'); // compound number words
parse('اواخر اسفند'); // anchored months
parse('farda'); // Finglish → فردا
parse('tvnh'); // keyboard left in English → فردا

Documentation

• Docs site — bilingual (فارسی by default, with an English locale at /en/).
• Getting started · Architecture · API reference
• Examples & live demos — runnable React, Vue, Svelte, Angular, and Vanilla / Web Component playgrounds.

Development

This repo uses pnpm workspaces and Turborepo.

pnpm install        # install all workspace dependencies
pnpm build          # build every package
pnpm test           # run the full test suite
pnpm lint           # lint everything
pnpm typecheck      # type-check everything
pnpm dev            # watch mode across packages

See CONTRIBUTING.md for the full contributor guide.

Architecture

Doran follows domain-driven package boundaries with strict dependency direction:

@doranjs/ui   @doranjs/react   @doranjs/wc ─┐
                                        ├──▶ @doranjs/core ◀── @doranjs/nlp
@doranjs/holidays ─────────────────────────┘

@doranjs/core has zero runtime dependencies and no knowledge of UI, locale data lives at the edges, and every public type is exported. Read the full architecture guide.

License

MIT © Doran Contributors