flexibleDate()

Parses, validates, and formats dates flexibly with fallback, timezone, and formatting options.

Core Function

Date

Parsing

Syntax

flexibleDate(input, options)

Parameters

input
any

The input date value: string, number, Date, or null/undefined.

options
object

optional

Configuration for parsing and formatting.

format - Output format: "iso", "locale", "timestamp", or custom function
strict - Strict mode: throw error on invalid dates
fallback - Value to return if input is invalid
timezone - Timezone handling: "local", "utc", or offset like "+0300"
relative - Return relative time string like "3 days ago"
adjustDays - Add/subtract days from parsed date

Returns

string|number|Date|null

- Formatted date output or fallback.

Examples

Basic Date Parsing

// Parse various date formats
flexibleDate("2023-01-01"); // "2023-01-01T00:00:00.000Z"
flexibleDate("January 1, 2023"); // "2023-01-01T00:00:00.000Z"
flexibleDate(1672531200000); // "2023-01-01T00:00:00.000Z"
flexibleDate(new Date(2023, 0, 1)); // "2023-01-01T00:00:00.000Z"

Different Output Formats

const date = "2023-01-01T12:00:00Z";

// ISO format (default)
flexibleDate(date); // "2023-01-01T12:00:00.000Z"

// Locale format
flexibleDate(date, { format: "locale" }); // "1/1/2023, 12:00:00 PM"

// Timestamp
flexibleDate(date, { format: "timestamp" }); // 1672574400000

// Custom formatter
flexibleDate(date, { 
  format: (d) => d.toDateString() 
}); // "Sun Jan 01 2023"

Timezone Handling

const date = "2023-01-01T12:00:00Z";

// Local timezone
flexibleDate(date, { timezone: "local" });

// UTC timezone
flexibleDate(date, { timezone: "utc" });

// Specific timezone offset
flexibleDate(date, { timezone: "+0300" }); // UTC+3
flexibleDate(date, { timezone: "-0500" }); // UTC-5

Relative Time

// Get relative time strings
const now = new Date();
const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000);
const lastWeek = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);

flexibleDate(yesterday, { relative: true }); // "1 day ago"
flexibleDate(lastWeek, { relative: true }); // "7 days ago"

const oneHourAgo = new Date(now.getTime() - 60 * 60 * 1000);
flexibleDate(oneHourAgo, { relative: true }); // "1 hour ago"

Date Adjustment

const date = "2023-01-01";

// Add days
flexibleDate(date, { adjustDays: 7 }); // "2023-01-08T00:00:00.000Z"

// Subtract days
flexibleDate(date, { adjustDays: -3 }); // "2022-12-29T00:00:00.000Z"

// Combine with formatting
flexibleDate(date, { 
  adjustDays: 30, 
  format: "locale" 
}); // "1/31/2023, 12:00:00 AM"

Error Handling

// With fallback
flexibleDate("invalid-date", { 
  fallback: "No date available" 
}); // "No date available"

flexibleDate(null, { 
  fallback: new Date() 
}); // Current date

// Strict mode
try {
  flexibleDate("invalid-date", { strict: true });
} catch (error) {
  console.log("Invalid date input");
}

Complex Example

// Parse user input with comprehensive options
function parseUserDate(input) {
  return flexibleDate(input, {
    format: "locale",
    timezone: "utc",
    fallback: "Invalid date",
    strict: false,
    adjustDays: 0
  });
}

parseUserDate("2023-12-25"); // "12/25/2023, 12:00:00 AM"
parseUserDate("Christmas 2023"); // "Invalid date"
parseUserDate(1703462400000); // "12/25/2023, 12:00:00 AM"