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

Installation

npm install tiny-date-ranger
# or
yarn add tiny-date-ranger
# or
pnpm add tiny-date-ranger

Usage

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

parseRange(input, options?)

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

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

Basic Usage

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

Weekly Ranges

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

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

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

Monthly & Quarterly

// 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" }

Year-to-Date

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

Persian (فارسی)

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

Deterministic Testing

// 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):

Flow Overview

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

1. Locale Mapping

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

2. Core Logic (parseRange)

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. Helper Functions

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

4. Special Cases

• 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)

Example Walkthrough

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:

pnpm test
# or
npm test

Run tests in watch mode:

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