arkyn
ChangelogGuides
docs / services / validate-date-service

ValidateDateService

The ValidateDateService is a service class for validating date components and input formats. It provides methods to validate date parts (year, month, day), validate input format strings, and parse date parts according to a given format, used internally by parseToDate, formatDate, and validateDate to keep their date-part parsing consistent.

Import

ts

import { ValidateDateService } from "@arkyn/shared/validateDateService";
Learn how subpath and root imports differ in How do I use imports.

Method validateDateParts(year, month, day)

Validates the components of a date (year, month, and day). This method performs comprehensive validation including leap year rules and month-specific day limits.

year (required)

The year to validate (must be exactly 4 digits)
Type: number

month (required)

The month to validate (must be between 1 and 12) |
Type: number

day (required)

The day to validate (must be valid for the given month)
Type: number

Usage example

typescript

import { ValidateDateService } from "@arkyn/shared/validateDateService";


const service = new ValidateDateService();


service.validateDateParts(2024, 2, 29); // Valid leap year date
service.validateDateParts(2024, 1, 15); // Valid regular date

Method validateInputFormat(format)

Validates that a given format string is one of the supported input formats.

format (required)

The format string to validate
Type: brazilianDate | usDate | isoDate | timestamp

Usage example

typescript

import { ValidateDateService } from "@arkyn/shared/validateDateService";


const service = new ValidateDateService();


service.validateInputFormat("brazilianDate"); // Valid
service.validateInputFormat("usDate"); // Valid
service.validateInputFormat("isoDate"); // Valid (deprecated alias for "usDate")
service.validateInputFormat("timestamp"); // Valid

Method parseDateParts(dateParts, inputFormat)

Added in v3.0.12. Reorders a numeric date-parts array according to inputFormat into a validated { year, month, day } object, running each value through validateDateParts before returning. This is the single implementation shared internally by parseToDate, formatDate (both @arkyn/shared), and validateDate (@arkyn/server), previously each had its own copy-pasted reordering logic.

dateParts (required)

The split numeric date components, in the order they appear in the original input string (not yet reordered).
Type: number[]

inputFormat (required)

Type: DateInputFormat (brazilianDate | usDate | isoDate | timestamp)

Usage example

typescript

import { ValidateDateService } from "@arkyn/shared/validateDateService";


const service = new ValidateDateService();


service.parseDateParts([25, 12, 2023], "brazilianDate");
// { year: 2023, month: 12, day: 25 }


service.parseDateParts([12, 25, 2023], "usDate");
// { year: 2023, month: 12, day: 25 }

DateInputFormat type

Added in v3.0.12 and exported from @arkyn/shared. It's the union accepted as inputFormat by formatDate, parseToDate, ValidateDateService.validateInputFormat, ValidateDateService.parseDateParts, and @arkyn/server's validateDate.

typescript

type DateInputFormat = "brazilianDate" | "isoDate" | "usDate" | "timestamp";
  • "brazilianDate": DD/MM/YYYY.
  • "usDate": MM-DD-YYYY. New name in v3.0.12.
  • "isoDate": MM-DD-YYYY, a deprecated alias of "usDate". It was never ISO 8601. The deprecation is JSDoc-only, no runtime warning is emitted.
  • "timestamp": YYYY-MM-DD, the actual ISO 8601 date format.

Errors

The service performs validation and may throw errors in the following scenarios:

validateDateParts errors

  • Year should be four digits: Thrown when the year doesn't have exactly 4 digits (e.g., 999 or 10000).
  • Month should be between 1 and 12: Thrown when the month is less than 1 or greater than 12.
  • Day should be between 1 and 31: Thrown when the day is less than 1 or greater than 31.
  • Day X is not valid for {Month}: Thrown when the day exceeds the maximum number of days for the specified month (e.g., April 31).
  • Day 29 is not valid for February {year} (non-leap year): Thrown when February 29 is specified for a non-leap year.

typescript

const service = new ValidateDateService();


service.validateDateParts(2023, 2, 29);
// Throws: "Day 29 is not valid for February 2023 (non-leap year)"


service.validateDateParts(2024, 4, 31);
// Throws: "Day 31 is not valid for April"


service.validateDateParts(99, 1, 15);
// Throws: "Year should be four digits"

validateInputFormat errors

Invalid input format: {format}: Thrown when the provided format is not one of the valid formats ("brazilianDate", "usDate", "isoDate", "timestamp").

typescript

const service = new ValidateDateService();


service.validateInputFormat("invalidFormat");
// Throws: "Invalid input format: invalidFormat"

parseDateParts errors

Propagates the same errors as validateDateParts above, since it validates the reordered parts before returning them.

typescript

const service = new ValidateDateService();


service.parseDateParts([30, 2, 2023], "brazilianDate");
// Throws: "Day 30 is not valid for February"

Notes

The service uses the standard leap year calculation: a year is a leap year if it is divisible by 4, except for century years which must be divisible by 400. For example, 2000 was a leap year, but 1900 was not.
Each month has its specific day limits validated: January (31), February (28 or 29), March (31), April (30), May (31), June (30), July (31), August (31), September (30), October (31), November (30), December (31).
The year validation requires exactly 4 digits, accepting years from 1000 to 9999. Single, double, or triple-digit years will be rejected.
This service is used internally by other date parsing utilities such as parseToDate to ensure input consistency before processing.
On this page
    arkyn