reslib 1.0.0

package/build/validator/rules/date.d.ts

@@ -0,0 +1,551 @@
+/**
+ * @summary A validation decorator that ensures a property contains a valid date value.
+ * @description
+ * Validates that the decorated property represents a date that can be parsed into a JavaScript Date object.
+ * Accepts Date instances, ISO date strings, and numeric timestamps as valid inputs.
+ *
+ * @example
+ * ```typescript
+ * class Event {
+ *   @IsDate()
+ *   eventDate: Date;
+ * }
+ *
+ * const event = new Event();
+ * event.eventDate = new Date(); // ✓ Valid
+ * event.eventDate = '2024-01-01'; // ✓ Valid
+ * event.eventDate = 1640995200000; // ✓ Valid (timestamp)
+ * event.eventDate = 'invalid'; // ✗ Invalid
+ * ```
+ *
+ * @returns A property decorator function for date validation.
+ *
+ * @public
+ */
+export declare const IsDate: () => PropertyDecorator;
+/**
+ * @summary A validation decorator that ensures a date property occurs after a specified reference date.
+ * @description
+ * Validates that the decorated property's date value is strictly greater than the provided comparison date.
+ * Useful for ensuring events or deadlines occur after a minimum date.
+ *
+ * @param date - The reference date to compare against. Accepts Date object, ISO string, or timestamp.
+ *
+ * @example
+ * ```typescript
+ * class Event {
+ *   @IsDateAfter(new Date('2024-01-01'))
+ *   eventDate: Date;
+ * }
+ *
+ * const event = new Event();
+ * event.eventDate = new Date('2024-01-02'); // ✓ Valid (after reference)
+ * event.eventDate = '2024-06-15'; // ✓ Valid
+ * event.eventDate = new Date('2023-12-31'); // ✗ Invalid (before reference)
+ * event.eventDate = '2024-01-01'; // ✗ Invalid (same date, not after)
+ * ```
+ *
+ * @returns A property decorator function for date-after validation.
+ *
+ * @public
+ */
+export declare const IsDateAfter: (date: ValidatorDate) => PropertyDecorator;
+/**
+ * @summary A validation decorator that ensures a date property occurs before a specified reference date.
+ * @description
+ * Validates that the decorated property's date value is strictly less than the provided comparison date.
+ * Useful for ensuring submissions or events occur before a maximum deadline.
+ *
+ * @param date - The reference date to compare against. Accepts Date object, ISO string, or timestamp.
+ *
+ * @example
+ * ```typescript
+ * class Deadline {
+ *   @IsDateBefore(new Date('2024-12-31'))
+ *   submissionDate: Date;
+ * }
+ *
+ * const deadline = new Deadline();
+ * deadline.submissionDate = new Date('2024-12-30'); // ✓ Valid (before reference)
+ * deadline.submissionDate = '2024-06-15'; // ✓ Valid
+ * deadline.submissionDate = new Date('2025-01-01'); // ✗ Invalid (after reference)
+ * deadline.submissionDate = '2024-12-31'; // ✗ Invalid (same date, not before)
+ * ```
+ *
+ * @returns A property decorator function for date-before validation.
+ *
+ * @public
+ */
+export declare const IsDateBefore: (date: ValidatorDate) => PropertyDecorator;
+/**
+ * @summary A validation decorator that ensures a date property falls within a specified date range.
+ * @description
+ * Validates that the decorated property's date value is between the start and end dates (inclusive).
+ * Useful for restricting dates to specific periods like vacation seasons or business quarters.
+ *
+ * @param minDate - The earliest allowed date in the range. Accepts Date object, ISO string, or timestamp.
+ * @param maxDate - The latest allowed date in the range. Accepts Date object, ISO string, or timestamp.
+ *
+ * @example
+ * ```typescript
+ * class Vacation {
+ *   @IsDateBetween(new Date('2024-01-01'), new Date('2024-12-31'))
+ *   vacationDate: Date;
+ * }
+ *
+ * const vacation = new Vacation();
+ * vacation.vacationDate = new Date('2024-06-15'); // ✓ Valid (within range)
+ * vacation.vacationDate = '2024-01-01'; // ✓ Valid (inclusive start)
+ * vacation.vacationDate = '2024-12-31'; // ✓ Valid (inclusive end)
+ * vacation.vacationDate = new Date('2023-12-31'); // ✗ Invalid (before range)
+ * vacation.vacationDate = '2025-01-01'; // ✗ Invalid (after range)
+ * ```
+ *
+ * @returns A property decorator function for date-between validation.
+ *
+ * @public
+ */
+export declare const IsDateBetween: (minDate: ValidatorDate, maxDate: ValidatorDate) => PropertyDecorator;
+/**
+ * @summary A validation decorator that ensures a date property matches a specific date (ignoring time).
+ * @description
+ * Validates that the decorated property's date value matches the reference date, comparing only
+ * year, month, and day components while ignoring hours, minutes, seconds, and milliseconds.
+ * Useful for date-only equality checks like birthdays or anniversaries.
+ *
+ * @param date - The reference date to match against. Accepts Date object, ISO string, or timestamp.
+ *
+ * @example
+ * ```typescript
+ * class Birthday {
+ *   @IsSameDate(new Date('1990-01-01'))
+ *   birthDate: Date;
+ * }
+ *
+ * const birthday = new Birthday();
+ * birthday.birthDate = new Date('1990-01-01T10:30:00Z'); // ✓ Valid (time ignored)
+ * birthday.birthDate = '1990-01-01'; // ✓ Valid
+ * birthday.birthDate = new Date('1990-01-02T00:00:00Z'); // ✗ Invalid (different date)
+ * birthday.birthDate = '1990-01-02'; // ✗ Invalid
+ * ```
+ *
+ * @returns A property decorator function for same-date validation.
+ *
+ * @public
+ */
+export declare const IsSameDate: (date: ValidatorDate) => PropertyDecorator;
+/**
+ * @summary A validation decorator that ensures a date property is in the future.
+ * @description
+ * Validates that the decorated property's date value occurs after the current moment.
+ * Useful for validating future events, appointments, or deadlines that haven't passed yet.
+ *
+ * @example
+ * ```typescript
+ * class Appointment {
+ *   @IsFutureDate()
+ *   appointmentDate: Date;
+ * }
+ *
+ * const appointment = new Appointment();
+ * appointment.appointmentDate = new Date(Date.now() + 86400000); // Tomorrow - ✓ Valid
+ * appointment.appointmentDate = '2025-01-01'; // ✓ Valid
+ * appointment.appointmentDate = new Date(Date.now() - 86400000); // Yesterday - ✗ Invalid
+ * appointment.appointmentDate = new Date(); // Now - ✗ Invalid (not strictly future)
+ * ```
+ *
+ * @returns A property decorator function for future-date validation.
+ *
+ * @public
+ */
+export declare const IsFutureDate: () => PropertyDecorator;
+/**
+ * @summary A validation decorator that ensures a date property is in the past.
+ * @description
+ * Validates that the decorated property's date value occurs before the current moment.
+ * Useful for validating historical events, past occurrences, or completed deadlines.
+ *
+ * @example
+ * ```typescript
+ * class HistoricalEvent {
+ *   @IsPastDate()
+ *   eventDate: Date;
+ * }
+ *
+ * const event = new HistoricalEvent();
+ * event.eventDate = new Date(Date.now() - 86400000); // Yesterday - ✓ Valid
+ * event.eventDate = '2020-01-01'; // ✓ Valid
+ * event.eventDate = new Date(Date.now() + 86400000); // Tomorrow - ✗ Invalid
+ * event.eventDate = new Date(); // Now - ✗ Invalid (not strictly past)
+ * ```
+ *
+ * @returns A property decorator function for past-date validation.
+ *
+ * @public
+ */
+export declare const IsPastDate: () => PropertyDecorator;
+declare module '../types' {
+    interface ValidatorRuleParamTypes {
+        /**
+         * @summary Validates that the field contains a valid date value.
+         * @description
+         * Ensures the input represents a valid date that can be parsed into a JavaScript Date object.
+         * Accepts Date instances, ISO date strings, and numeric timestamps.
+         *
+         * @example
+         * ```typescript
+         * // Valid date inputs
+         * await Validator.validate({
+         *   value: new Date(),
+         *   rules: ['Date']
+         * }); // ✓ Valid
+         *
+         * await Validator.validate({
+         *   value: '2024-01-01T10:30:00Z',
+         *   rules: ['Date']
+         * }); // ✓ Valid
+         *
+         * await Validator.validate({
+         *   value: 1640995200000, // Unix timestamp
+         *   rules: ['Date']
+         * }); // ✓ Valid
+         *
+         * // Invalid inputs
+         * await Validator.validate({
+         *   value: 'invalid-date-string',
+         *   rules: ['Date']
+         * }); // ✗ Invalid
+         *
+         * await Validator.validate({
+         *   value: null,
+         *   rules: ['Date']
+         * }); // ✗ Invalid
+         *
+         * await Validator.validate({
+         *   value: {},
+         *   rules: ['Date']
+         * }); // ✗ Invalid
+         * ```
+         *
+         * @example
+         * ```typescript
+         * // Class validation usage
+         * class Event {
+         *   @IsRequired()
+         *   @IsDate()
+         *   eventDate: Date;
+         * }
+         * ```
+         *
+         * @public
+         */
+        Date: ValidatorRuleParams<[]>;
+        /**
+         * @summary Validates that the date occurs after a specified reference date.
+         * @description
+         * Checks if the input date is strictly greater than the provided comparison date.
+         * Both dates are converted to Date objects for comparison.
+         *
+         * @param date - The reference date to compare against. Accepts Date object, ISO string, or timestamp.
+         *
+         * @example
+         * ```typescript
+         * // Valid examples (date must be after reference)
+         * await Validator.validate({
+         *   value: new Date('2024-01-02'),
+         *   rules: ['DateAfter[2024-01-01]']
+         * }); // ✓ Valid
+         *
+         * await Validator.validate({
+         *   value: '2024-06-15T12:00:00Z',
+         *   rules: ['DateAfter[2024-01-01]']
+         * }); // ✓ Valid
+         *
+         * // Invalid examples
+         * await Validator.validate({
+         *   value: new Date('2023-12-31'),
+         *   rules: ['DateAfter[2024-01-01]']
+         * }); // ✗ Invalid (before reference)
+         *
+         * await Validator.validate({
+         *   value: '2024-01-01T23:59:59Z',
+         *   rules: ['DateAfter[2024-01-01]']
+         * }); // ✗ Invalid (same date, not after)
+         *
+         * await Validator.validate({
+         *   value: 'invalid-date',
+         *   rules: ['DateAfter[2024-01-01]']
+         * }); // ✗ Invalid (invalid input date)
+         * ```
+         *
+         * @example
+         * ```typescript
+         * // Class validation with dynamic reference
+         * class Event {
+         *   @IsDateAfter(new Date('2024-01-01'))
+         *   eventDate: Date;
+         * }
+         * ```
+         *
+         * @public
+         */
+        DateAfter: ValidatorRuleParams<[date: ValidatorDate]>;
+        /**
+         * @summary Validates that the date occurs before a specified reference date.
+         * @description
+         * Checks if the input date is strictly less than the provided comparison date.
+         * Both dates are converted to Date objects for comparison.
+         *
+         * @param date - The reference date to compare against. Accepts Date object, ISO string, or timestamp.
+         *
+         * @example
+         * ```typescript
+         * // Valid examples (date must be before reference)
+         * await Validator.validate({
+         *   value: new Date('2023-12-31'),
+         *   rules: ['DateBefore[2024-01-01]']
+         * }); // ✓ Valid
+         *
+         * await Validator.validate({
+         *   value: '2023-06-15T12:00:00Z',
+         *   rules: ['DateBefore[2024-01-01]']
+         * }); // ✓ Valid
+         *
+         * // Invalid examples
+         * await Validator.validate({
+         *   value: new Date('2024-01-02'),
+         *   rules: ['DateBefore[2024-01-01]']
+         * }); // ✗ Invalid (after reference)
+         *
+         * await Validator.validate({
+         *   value: '2024-01-01T00:00:01Z',
+         *   rules: ['DateBefore[2024-01-01]']
+         * }); // ✗ Invalid (same date, not before)
+         *
+         * await Validator.validate({
+         *   value: 'invalid-date',
+         *   rules: ['DateBefore[2024-01-01]']
+         * }); // ✗ Invalid (invalid input date)
+         * ```
+         *
+         * @example
+         * ```typescript
+         * // Class validation with deadline
+         * class Deadline {
+         *   @IsDateBefore(new Date('2024-12-31'))
+         *   submissionDate: Date;
+         * }
+         * ```
+         *
+         * @public
+         */
+        DateBefore: ValidatorRuleParams<[date: ValidatorDate]>;
+        /**
+         * @summary Validates that the date falls within a specified date range (inclusive).
+         * @description
+         * Checks if the input date is greater than or equal to the start date and
+         * less than or equal to the end date. All dates are converted to Date objects.
+         *
+         * @param minDate - The minimum/earliest allowed date. Accepts Date object, ISO string, or timestamp.
+         * @param maxDate - The maximum/latest allowed date. Accepts Date object, ISO string, or timestamp.
+         *
+         * @example
+         * ```typescript
+         * // Valid examples (within range inclusive)
+         * await Validator.validate({
+         *   value: new Date('2024-06-15'),
+         *   rules: ['DateBetween[2024-01-01,2024-12-31]']
+         * }); // ✓ Valid
+         *
+         * await Validator.validate({
+         *   value: '2024-01-01T00:00:00Z', // Start boundary
+         *   rules: ['DateBetween[2024-01-01,2024-12-31]']
+         * }); // ✓ Valid
+         *
+         * await Validator.validate({
+         *   value: '2024-12-31T23:59:59Z', // End boundary
+         *   rules: ['DateBetween[2024-01-01,2024-12-31]']
+         * }); // ✓ Valid
+         *
+         * // Invalid examples
+         * await Validator.validate({
+         *   value: new Date('2023-12-31'),
+         *   rules: ['DateBetween[2024-01-01,2024-12-31]']
+         * }); // ✗ Invalid (before range)
+         *
+         * await Validator.validate({
+         *   value: '2025-01-01',
+         *   rules: ['DateBetween[2024-01-01,2024-12-31]']
+         * }); // ✗ Invalid (after range)
+         *
+         * await Validator.validate({
+         *   value: 'invalid-date',
+         *   rules: ['DateBetween[2024-01-01,2024-12-31]']
+         * }); // ✗ Invalid (invalid input date)
+         * ```
+         *
+         * @example
+         * ```typescript
+         * // Class validation for vacation period
+         * class Vacation {
+         *   @IsDateBetween(new Date('2024-01-01'), new Date('2024-12-31'))
+         *   vacationDate: Date;
+         * }
+         * ```
+         *
+         * @public
+         */
+        DateBetween: ValidatorRuleParams<[
+            minDate: ValidatorDate,
+            maxDate: ValidatorDate
+        ]>;
+        /**
+         * @summary Validates that the date matches a specific date (ignoring time components).
+         * @description
+         * Compares only the date parts (year, month, day) of the input and reference dates,
+         * ignoring hours, minutes, seconds, and milliseconds. Useful for date-only equality checks.
+         *
+         * @param date - The reference date to match against. Accepts Date object, ISO string, or timestamp.
+         *
+         * @example
+         * ```typescript
+         * // Valid examples (same date regardless of time)
+         * await Validator.validate({
+         *   value: new Date('2024-01-01T10:30:45Z'),
+         *   rules: ['SameDate[2024-01-01]']
+         * }); // ✓ Valid (time ignored)
+         *
+         * await Validator.validate({
+         *   value: '2024-01-01',
+         *   rules: ['SameDate[2024-01-01T23:59:59Z]']
+         * }); // ✓ Valid (time ignored)
+         *
+         * // Invalid examples
+         * await Validator.validate({
+         *   value: new Date('2024-01-02T00:00:00Z'),
+         *   rules: ['SameDate[2024-01-01]']
+         * }); // ✗ Invalid (different date)
+         *
+         * await Validator.validate({
+         *   value: '2024-01-01T10:30:00Z',
+         *   rules: ['SameDate[2024-01-02]']
+         * }); // ✗ Invalid (different date)
+         *
+         * await Validator.validate({
+         *   value: 'invalid-date',
+         *   rules: ['SameDate[2024-01-01]']
+         * }); // ✗ Invalid (invalid input date)
+         * ```
+         *
+         * @example
+         * ```typescript
+         * // Class validation for specific birthday
+         * class Birthday {
+         *   @IsSameDate(new Date('1990-01-01'))
+         *   birthDate: Date;
+         * }
+         * ```
+         *
+         * @public
+         */
+        SameDate: ValidatorRuleParams<[date: ValidatorDate]>;
+        /**
+         * @summary Validates that the date is in the future relative to the current time.
+         * @description
+         * Checks if the input date occurs after the current moment (now).
+         * Useful for validating future events, deadlines, or appointments.
+         *
+         * @example
+         * ```typescript
+         * // Valid examples (future dates)
+         * await Validator.validate({
+         *   value: new Date(Date.now() + 86400000), // Tomorrow
+         *   rules: ['FutureDate']
+         * }); // ✓ Valid
+         *
+         * await Validator.validate({
+         *   value: '2025-01-01T00:00:00Z',
+         *   rules: ['FutureDate']
+         * }); // ✓ Valid
+         *
+         * // Invalid examples
+         * await Validator.validate({
+         *   value: new Date(Date.now() - 86400000), // Yesterday
+         *   rules: ['FutureDate']
+         * }); // ✗ Invalid (past date)
+         *
+         * await Validator.validate({
+         *   value: new Date(), // Current time
+         *   rules: ['FutureDate']
+         * }); // ✗ Invalid (not strictly future)
+         *
+         * await Validator.validate({
+         *   value: 'invalid-date',
+         *   rules: ['FutureDate']
+         * }); // ✗ Invalid (invalid input date)
+         * ```
+         *
+         * @example
+         * ```typescript
+         * // Class validation for future appointments
+         * class Appointment {
+         *   @IsFutureDate()
+         *   appointmentDate: Date;
+         * }
+         * ```
+         *
+         * @public
+         */
+        FutureDate: ValidatorRuleParams<[]>;
+        /**
+         * @summary Validates that the date is in the past relative to the current time.
+         * @description
+         * Checks if the input date occurs before the current moment (now).
+         * Useful for validating historical events or past occurrences.
+         *
+         * @example
+         * ```typescript
+         * // Valid examples (past dates)
+         * await Validator.validate({
+         *   value: new Date(Date.now() - 86400000), // Yesterday
+         *   rules: ['PastDate']
+         * }); // ✓ Valid
+         *
+         * await Validator.validate({
+         *   value: '2020-01-01T00:00:00Z',
+         *   rules: ['PastDate']
+         * }); // ✓ Valid
+         *
+         * // Invalid examples
+         * await Validator.validate({
+         *   value: new Date(Date.now() + 86400000), // Tomorrow
+         *   rules: ['PastDate']
+         * }); // ✗ Invalid (future date)
+         *
+         * await Validator.validate({
+         *   value: new Date(), // Current time
+         *   rules: ['PastDate']
+         * }); // ✗ Invalid (not strictly past)
+         *
+         * await Validator.validate({
+         *   value: 'invalid-date',
+         *   rules: ['PastDate']
+         * }); // ✗ Invalid (invalid input date)
+         * ```
+         *
+         * @example
+         * ```typescript
+         * // Class validation for historical events
+         * class HistoricalEvent {
+         *   @IsPastDate()
+         *   eventDate: Date;
+         * }
+         * ```
+         *
+         * @public
+         */
+        PastDate: ValidatorRuleParams<[]>;
+    }
+}
+type ValidatorDate = string | Date | number;
+export {};