tiny-date-ranger

> ⚡️ A zero-dependency JavaScript utility that parses natural language date ranges such as "last 7 days", "this month", or "Q3 2024" into exact JavaScript Date objects.
> TypeScript-first, locale-aware (en + fa), deterministic, and only ~1 KB gzipped.


---

🚀 Quick Start

$3

``bash
npm install tiny-date-ranger


or

yarn add tiny-date-ranger

or

pnpm add tiny-date-ranger
`

$3

`ts
import { parseRange } from "tiny-date-ranger";

const { start, end, label } = parseRange("last 7 days");

console.log({ start, end, label });
// → {
// start: 2025-10-26T00:00:00.000Z,
// end: 2025-11-02T23:59:59.999Z,
// label: "Last 7 days"
// }
`

---

📖 API

$3

Parses a natural language date range string and returns a range object.

`ts
parseRange(
input: string,
options?: {
now?: Date; // optional reference date (useful for testing)
weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6; // default: 1 (Monday)
locale?: "en" | "fa"; // default: "en"
}
): {
start: Date;
end: Date;
label: string;
};
`

Parameters:
- input (string): The natural language date range to parse
- options (optional object):
- now (Date): Reference date for relative calculations (defaults to current date/time)
- weekStartsOn (0-6): First day of the week (0 = Sunday, 1 = Monday, etc.). Default: 1
- locale ("en" | "fa"): Language for input parsing. Default: "en"

Returns:
- start (Date): Start of the range (time set to 00:00:00.000)
- end (Date): End of the range (time set to 23:59:59.999)
- label (string): Human-readable label for the range

---

📅 Supported Inputs

| English Input | Persian Alias (fa) | Description |
|--------------------|--------------------------|--------------------------------------|
| today | امروز | Current day |
| yesterday | دیروز | Previous day |
| last 7 days | ۷ روز گذشته, هفت روز گذشته | Last 7 days including today |
| last 30 days | — | Last 30 days including today |
| this week | این هفته | Current calendar week |
| last week | هفته قبل | Previous calendar week |
| this month | این ماه | Current month |
| last month | ماه قبل | Previous month |
| this quarter | این فصل | Current quarter (Q1-Q4) |
| Q1 2025 – Q4 2025 | — | Specific quarter of a year |
| ytd | — | Year-to-date (Jan 1 → today) |

> Note: All results are returned as local Date objects, with time clamped between 00:00:00.000 and 23:59:59.999.

---

💡 Examples

$3

`ts
import { parseRange } from "tiny-date-ranger";

// Today and yesterday
parseRange("today");
// → { start: 2025-11-02T00:00:00.000Z, end: 2025-11-02T23:59:59.999Z, label: "Today" }

parseRange("yesterday");
// → { start: 2025-11-01T00:00:00.000Z, end: 2025-11-01T23:59:59.999Z, label: "Yesterday" }

// Rolling periods
parseRange("last 7 days");
// → Last 7 days including today

parseRange("last 30 days");
// → Last 30 days including today
`

$3

`ts
// Week starting on Monday (default)
parseRange("this week");

// Week starting on Sunday
parseRange("this week", { weekStartsOn: 0 });

// Last week
parseRange("last week");
`

$3

`ts
// Current month
parseRange("this month");
// → Full current month (1st 00:00 to last day 23:59:59.999)

// Previous month
parseRange("last month");

// Quarters
parseRange("this quarter");
parseRange("Q1 2024");
parseRange("Q3 2024");
// → { start: 2024-07-01T00:00:00.000Z, end: 2024-09-30T23:59:59.999Z, label: "Q3 2024" }
`

$3

`ts
parseRange("ytd");
// → From January 1st of current year to today
`

$3

`ts
// Set locale to "fa"
parseRange("امروز", { locale: "fa" });
parseRange("این هفته", { locale: "fa" });
parseRange("ماه قبل", { locale: "fa" });
parseRange("۷ روز گذشته", { locale: "fa" });
`

$3

`ts
// Inject a fixed date for testing
const fixedDate = new Date("2025-06-15T12:00:00Z");
const result = parseRange("last 7 days", { now: fixedDate });

console.log(result.start.toISOString());
// → Always returns 2025-06-09T00:00:00.000Z (deterministic)
`

---

✨ Features

- ✅ Zero dependencies — ~1 KB gzipped, no bloat
- 🧠 Locale aware — Built-in support for English (en) and Persian (fa)
- 🧪 Deterministic — Injectable now parameter for predictable tests
- ⚙️ TypeScript-first — Full type definitions included
- 🌍 Universal — Works in Node.js, browsers, and edge runtimes
- 📦 Modern exports — ESM + CJS dual format
- 🕓 Future-proof — Design ready for upcoming Temporal API
- 🔧 Configurable — Customize week start day
- 🚀 Tree-shakeable — Only bundle what you use

---

🛠️ Use Cases

Perfect for:
- 📊 Analytics dashboards
- 📈 Data visualization tools
- 🗓️ Calendar and scheduling apps
- 📉 Reporting systems
- 🔍 Search filters with date ranges
- 📱 React/Vue/Angular date pickers
- ⚡ Next.js/Remix/SvelteKit apps

---

🏗️ How It Works

Understanding the library's architecture (great for contributors):

$3

`
Input String → Locale Mapping → Switch Case → Helper Functions → Date Range
`

$3


`ts
EN Map: "last 7 days" → "last_7"
FA Map: "۷ روز گذشته" → "last_7"
`

$3

`ts
parseRange("last 7 days", options)
↓
1. Normalize input (trim, lowercase)
2. Look up in locale maps (EN or FA)
3. Switch on the normalized key
4. Calculate start/end using helper functions
5. Return { start, end, label }
`

$3

`ts
floorDay() // Set to 00:00:00.000
ceilDay() // Set to 23:59:59.999
startOfWeek() // Calculate week start based on weekStartsOn
endOfWeek() // Calculate week end
startOfMonth() // First day of month
endOfMonth() // Last day of month
startOfQuarter()// First day of quarter (Q1-Q4)
endOfQuarter() // Last day of quarter
`

$3

- Quarters: Regex /^q([1-4])\s*(\d{4})$/ for "Q3 2024"
- YTD: From Jan 1 of current year to today
- Rolling periods: "last 7 days" includes today (goes back 6 days)

$3

`ts
parseRange("last 7 days", { now: new Date("2025-06-15") })

Step 1: Normalize → "last 7 days"
Step 2: EN Map lookup → "last_7"
Step 3: Switch case "last_7"
Step 4: Calculate:
- end = ceilDay(2025-06-15) → 2025-06-15T23:59:59.999Z
- start = floorDay(2025-06-15) - 6 days → 2025-06-09T00:00:00.000Z
Step 5: Return { start, end, label: "Last 7 days" }
`

---

🧪 Testing

The library includes comprehensive test coverage using Vitest:

`bash
pnpm test


or


npm test
`

Run tests in watch mode:
`bash
pnpm test:watch
`

Key testing features:
- Deterministic tests using the now option
- All supported inputs covered
- Edge cases (quarter boundaries, month/week transitions)
- Locale switching (en/fa)

---

📝 License

MIT © amirhossein693

---

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

---

📦 Related Projects

Looking for more date utilities?
- date-fns — Modern JavaScript date utility library
- dayjs — 2KB immutable date library
- luxon — Powerful date/time library

---

Made with ❤️ for the JavaScript community