@webster-pack/date-time

Date and time utilities for Node.js and TypeScript with built-in validation and timezone support. This package provides a safe and predictable way to construct date ranges using plain strings, making it ideal for APIs, databases, and backend services.

✨ Features

✅ Strict Validation –

Date (YYYY-MM-DD) and time (HH:mm) format validation

🌍 IANA Timezone Support –

Built-in timezone handling (defaults to UTC)

🕒 Automatic Normalization –

Smart start/end time adjustment for date ranges

🛡️ Defensive Programming –

Clear error messages and safe defaults

📦 Zero Dependencies –

Lightweight and self-contained

🧩 Backend Optimized –

Perfect for Node.js, NestJS, MongoDB, SQL databases

📦 Installation

bash

npm install @webster-pack/date-time

🚀 Quick Start

//typescript
import { buildDateRange } from "@webster-pack/date-time";

const range = buildDateRange({
  startDate: "2024-01-01",
  endDate: "2024-01-31"
});

if (range) {
  console.log(range.startDateTime); // 2024-01-01T00:00:00.000Z
  console.log(range.endDateTime);   // 2024-01-31T23:59:59.999Z
}

With Time and Timezone

//typescript
import { buildDateRange } from "@webster-pack/date-time";

const range = buildDateRange({
  startDate: "2024-01-01",
  endDate: "2024-01-01",
  startTime: "09:00",
  endTime: "18:30",
  timezone: "Asia/Kolkata"
});

if (range) {
  console.log(range.startDateTime); // 2024-01-01T03:30:00.000Z (UTC)
  console.log(range.endDateTime);   // 2024-01-01T13:00:00.000Z (UTC)
}

📖 API Reference

buildDateRange(options)

Constructs a date range with automatic time normalization. Parameters Parameter Type Required Description Format Default startDate string Yes Start date of the range YYYY-MM-DD - endDate string Yes End date of the range YYYY-MM-DD - startTime string No Start time of the range HH:mm "00:00" endTime string No End time of the range HH:mm "23:59" timezone string No IANA timezone identifier IANA format "UTC"

Return Value

//typescript

{
  startDateTime: Date;
  endDateTime: Date;
} | null

Returns null when:

• Any input format is invalid

• Timezone is not a valid IANA identifier

• startDateTime is after endDateTime

🔍 Validation Rules

Date Format

• Must strictly follow YYYY-MM-DD

• Validates day, month, and year ranges

• Examples: 2024-12-31, 2024-01-01

Time Format

• Must follow HH:mm (24-hour format)

• Hours: 00-23

• Minutes: 00-59

• Examples: 09:30, 14:45, 23:59

Timezone Support

• Must be a valid IANA timezone identifier

• Examples: "UTC", "Asia/Kolkata", "America/New_York", "Europe/London"

• Invalid timezones will return null

🎯 Use Cases

MongoDB Query

//typescript

    const range = buildDateRange({
       startDate: "2024-01-01",
       endDate: "2024-01-31",
       timezone: "UTC"
    });

    if (range) {
      await db.collection("orders").find({
         createdAt: {
           $gte: range.startDateTime,
           $lte: range.endDateTime
        }
     });
    }

SQL Query

//typescript

    const range = buildDateRange({
          startDate: "2024-01-01",
          endDate: "2024-01-31",
            startTime: "09:00",
  endTime: "17:00",
  timezone: "America/New_York"
});

if (range) {
  const query = `
    SELECT * FROM events 
    WHERE event_time BETWEEN $1 AND $2
  `;
  await pool.query(query, [range.startDateTime, range.endDateTime]);
}

API Request Validation

//typescript

import { buildDateRange } from "@webster-pack/date-time";

app.get("/analytics", (req, res) => {
  const range = buildDateRange({
    startDate: req.query.startDate as string,
    endDate: req.query.endDate as string,
    timezone: req.query.timezone as string || "UTC"
    });

  if (!range) {
    return res.status(400).json({ error: "Invalid date range parameters" });
  }
});

⚠️ Error Handling

The function returns null for invalid inputs instead of throwing exceptions, making it safe for use in APIs and services:

//typescript

const range = buildDateRange({
  startDate: "invalid-date",
  endDate: "2024-01-31"
});

if (!range) {
  // Handle invalid input gracefully
  console.log("Please provide valid dates in YYYY-MM-DD format");
}

🧪 Testing

The package includes comprehensive validation:

//typescript

// Valid inputs
buildDateRange({ startDate: "2024-01-01", endDate: "2024-01-31" }); // ✅

// Invalid date format
buildDateRange({ startDate: "01-01-2024", endDate: "2024-01-31" }); // ❌ null

// Invalid timezone
buildDateRange({ 
  startDate: "2024-01-01", 
  endDate: "2024-01-31",
  timezone: "Invalid/Timezone" 
}); // ❌ null

// Start date after end date
buildDateRange({ startDate: "2024-02-01", endDate: "2024-01-31" }); // ❌ null

📋 Requirements

Node.js 14 or higher

TypeScript 4.0 or higher (optional, but recommended)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. 📄 License

MIT © Webster Pack

🔗 Links

GitHub Repository

npm Package

Issue Tracker