Date Utilities

Purpose: Unified parsing, validation, formatting, and serialization of dates and date-times using a subset of Moment.js format patterns for configuration and output.

What You Get

1. Parse inbound strings to native Date.
2. Serialize Date / epoch / string into normalized date or date-time strings.
3. Validate user input against expected formats.
4. Format values in either exact (configured) or friendly locale-aware styles.
5. Produce ISO (UTC) outputs when required.

Configuration (optional)

1. locale: BCP-47 locale applied to formatting.
2. longDateFormat: Only tokens L (date) and LTS (time with seconds) are honored (legacy compatibility).
3. exactDateFormat / exactTimeFormat / exactDateTimeFormat: Accept Moment.js format strings to override default patterns.
4. formatIsoDateTimeInTimeZone: Force serialization in a specific zone.
5. formatIsoDateTimeInUtc: Force UTC with trailing Z. (If neither zone flag is set, original components are preserved.)

Input Types Accepted Everywhere

1. Native Date
2. Number (milliseconds or seconds epoch; seconds auto-detected)
3. String (ISO or previously formatted)

Core Functions (Summary)

Parsing / Serialization:

1. deserializeDate(text): Returns Date or null.
2. serializeDate(value, format?): Returns date string (default MM/DD/YYYY).
3. serializeDateTime(value, format?): Returns date-time string (default MM/DD/YYYY HH:mm:ss).

Validation:

1. validateDate(text, format?): true if matches (or ISO when no format).
2. validateDateTime(text, format?): same for date-time.

Formatting (auto-applies locale and config):

1. formatDate(value)
2. formatDateTime(value)
3. formatExactDate(value)
4. formatExactTime(value)
5. formatExactDateTime(value)
6. formatFriendlyDate(value)
7. formatFriendlyDateTime(value)
8. formatFriendlyDateTimeNow(value): Relative (e.g. 3 minutes ago).
9. formatISODate(value): Full ISO UTC with milliseconds.
10. formatISODateTime(value): ISO UTC without milliseconds.

Behavior Notes

1. Exact format functions prefer explicit exact* config; otherwise fallback locale presets.
2. Friendly variants use medium presets.
3. Seconds in time outputs depend on longDateFormat containing LTS unless an exact pattern overrides.
4. Validation is strict: supply the expected format when not ISO.
5. Zone handling for serialization: explicit target zone (formatIsoDateTimeInTimeZone) overrides UTC flag, which overrides unchanged behavior.

Moment Format Scope

Only limited tokens (L, LTS) and locale passthrough are honored; do not rely on broader Moment formatting semantics. Custom formats should use Moment.js style tokens (e.g. MM/DD/YYYY, HH:mm:ss).

When To Use Which

1. Need user-facing display: formatFriendlyDate* functions.
2. Need guaranteed stable machine string: formatISODateTime or serializeDateTime with explicit format.
3. Accepting user input: validateDate / validateDateTime, then deserializeDate.

Errors / Nulls

1. Falsy or invalid parse input → null (deserialize).
2. Validation failure → false (validate functions).
3. Formatting with invalid value may yield empty string.

Minimal Example (conceptual)

deserializeDate("2025-10-21")
serializeDateTime(new Date())
formatFriendlyDateTimeNow(new Date())
formatExactDateTime(new Date())