@nhtio/validation 0.1.0-master-5ddd6b01

package/private/schemas/datetime.d.ts

@@ -0,0 +1,562 @@
+import { DateTime } from 'luxon';
+import { Dayjs } from 'dayjs';
+import type { Tokens } from '../types';
+import type { AnySchema } from '../schemas';
+import type { Zone, LocaleOptions, DateObjectUnits } from 'luxon';
+import type { ExtensionFactory, Reference } from 'joi';
+/**
+ * Types that can be parsed into a DateTime object.
+ *
+ * Supports Luxon DateTime objects, JavaScript Date objects, Day.js objects,
+ * ISO strings, Unix timestamps, and Luxon DateObjectUnits.
+ *
+ * @example
+ * ```typescript
+ * const schema = joi.datetime()
+ *
+ * // All of these are valid Parseable types:
+ * schema.validate('2023-01-01T00:00:00Z')  // ISO string
+ * schema.validate(1672531200000)           // Unix timestamp
+ * schema.validate(new Date())              // JavaScript Date
+ * schema.validate(DateTime.now())          // Luxon DateTime
+ * schema.validate({ year: 2023, month: 1, day: 1 }) // DateObjectUnits
+ * ```
+ */
+export type Parseable = DateTime | Date | Dayjs | string | number | DateObjectUnits;
+/**
+ * Schema for datetime validation with comprehensive formatting and comparison methods.
+ *
+ * Extends the base AnySchema to provide datetime-specific validation rules including
+ * comparisons (before/after), weekend/weekday checks, timezone conversions, and
+ * various output formatting options.
+ *
+ * @template TSchema - The output type after validation and potential transformation
+ *
+ * @example
+ * ```typescript
+ * const schema: DatetimeSchema = joi.datetime()
+ *   .after('2023-01-01')
+ *   .toUTC()
+ *   .toISO()
+ *
+ * const result = schema.validate('2023-06-15T10:30:00Z')
+ * // Returns ISO string in UTC timezone
+ * ```
+ */
+export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
+    /**
+     * Validates that the datetime is exactly equal to the specified limit.
+     * Uses strict equality comparison (===) between DateTime objects.
+     *
+     * @param limit - The datetime value to compare against
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().exactly('2023-01-01T00:00:00Z')
+     * schema.validate('2023-01-01T00:00:00Z') // Valid
+     * schema.validate('2023-01-01T00:00:01Z') // Invalid
+     * ```
+     */
+    exactly(limit: Parseable | Reference): this;
+    /**
+     * Validates that the datetime is equal to the specified limit.
+     * Uses loose equality comparison (==) between DateTime objects.
+     *
+     * @param limit - The datetime value to compare against
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().equals('2023-01-01T00:00:00Z')
+     * schema.validate('2023-01-01T00:00:00.000Z') // Valid (same moment)
+     * ```
+     */
+    equals(limit: Parseable | Reference): this;
+    /**
+     * Validates that the datetime is after the specified limit.
+     *
+     * @param limit - The datetime value that the input must be after
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().after('2023-01-01T00:00:00Z')
+     * schema.validate('2023-01-02T00:00:00Z') // Valid
+     * schema.validate('2022-12-31T23:59:59Z') // Invalid
+     * ```
+     */
+    after(limit: Parseable | Reference): this;
+    /**
+     * Validates that the datetime is greater than the specified limit.
+     * Alias for `after()`.
+     *
+     * @param limit - The datetime value that the input must be greater than
+     * @returns The schema instance for method chaining
+     */
+    greater(limit: Parseable | Reference): this;
+    /**
+     * Validates that the datetime is before the specified limit.
+     *
+     * @param limit - The datetime value that the input must be before
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().before('2023-12-31T23:59:59Z')
+     * schema.validate('2023-06-15T12:00:00Z') // Valid
+     * schema.validate('2024-01-01T00:00:00Z') // Invalid
+     * ```
+     */
+    before(limit: Parseable | Reference): this;
+    /**
+     * Validates that the datetime is less than the specified limit.
+     * Alias for `before()`.
+     *
+     * @param limit - The datetime value that the input must be less than
+     * @returns The schema instance for method chaining
+     */
+    less(limit: Parseable | Reference): this;
+    /**
+     * Validates that the datetime is after or equal to the specified limit.
+     *
+     * @param limit - The datetime value that the input must be after or equal to
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().afterOrEqual('2023-01-01T00:00:00Z')
+     * schema.validate('2023-01-01T00:00:00Z') // Valid (equal)
+     * schema.validate('2023-01-02T00:00:00Z') // Valid (after)
+     * schema.validate('2022-12-31T23:59:59Z') // Invalid
+     * ```
+     */
+    afterOrEqual(limit: Parseable | Reference): this;
+    /**
+     * Validates that the datetime is greater than or equal to the specified limit.
+     * Alias for `afterOrEqual()`.
+     *
+     * @param limit - The minimum datetime value
+     * @returns The schema instance for method chaining
+     */
+    min(limit: Parseable | Reference): this;
+    /**
+     * Validates that the datetime is before or equal to the specified limit.
+     *
+     * @param limit - The datetime value that the input must be before or equal to
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().beforeOrEqual('2023-12-31T23:59:59Z')
+     * schema.validate('2023-12-31T23:59:59Z') // Valid (equal)
+     * schema.validate('2023-06-15T12:00:00Z') // Valid (before)
+     * schema.validate('2024-01-01T00:00:00Z') // Invalid
+     * ```
+     */
+    beforeOrEqual(limit: Parseable | Reference): this;
+    /**
+     * Validates that the datetime is less than or equal to the specified limit.
+     * Alias for `beforeOrEqual()`.
+     *
+     * @param limit - The maximum datetime value
+     * @returns The schema instance for method chaining
+     */
+    max(limit: Parseable | Reference): this;
+    /**
+     * Validates that the datetime falls on a weekend day.
+     * Based on the configured weekend days in Luxon settings (default: Saturday and Sunday).
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().weekend()
+     * schema.validate('2023-07-01T12:00:00Z') // Valid if Saturday
+     * schema.validate('2023-07-03T12:00:00Z') // Invalid if Monday
+     * ```
+     */
+    weekend(): this;
+    /**
+     * Validates that the datetime falls on a weekday (non-weekend day).
+     * Based on the configured weekend days in Luxon settings.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().weekday()
+     * schema.validate('2023-07-03T12:00:00Z') // Valid if Monday
+     * schema.validate('2023-07-01T12:00:00Z') // Invalid if Saturday
+     * ```
+     */
+    weekday(): this;
+    /**
+     * Converts the datetime to UTC timezone during validation.
+     * The output will be a DateTime object in UTC.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toUTC()
+     * const result = schema.validate('2023-07-15T10:30:00-05:00')
+     * // Returns DateTime in UTC: 2023-07-15T15:30:00Z
+     * ```
+     */
+    toUTC(): this;
+    /**
+     * Converts the datetime to local timezone during validation.
+     * The output will be a DateTime object in the system's local timezone.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toLocal()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns DateTime in local timezone
+     * ```
+     */
+    toLocal(): this;
+    /**
+     * Sets the timezone for the datetime during validation.
+     *
+     * @param zone - The timezone to set (IANA timezone name or Luxon Zone object)
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().setZone('America/New_York')
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns DateTime in Eastern timezone
+     * ```
+     */
+    setZone(zone: string | Zone): this;
+    /**
+     * Formats the datetime using a custom format string during validation.
+     *
+     * @param format - The format string (Luxon format tokens)
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toFormat('yyyy-MM-dd HH:mm:ss')
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: "2023-07-15 15:30:00"
+     * ```
+     */
+    toFormat(format: Tokens): this;
+    /**
+     * Formats the datetime using locale-specific formatting during validation.
+     *
+     * @param formatOpts - Locale formatting options
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toLocaleString({ month: 'long', day: 'numeric' })
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: "July 15" (or localized equivalent)
+     * ```
+     */
+    toLocalizedString(formatOpts: LocaleOptions): this;
+    /**
+     * Converts the datetime to ISO 8601 string format during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toISO()
+     * const result = schema.validate('July 15, 2023 3:30 PM')
+     * // Returns: "2023-07-15T15:30:00.000Z"
+     * ```
+     */
+    toISO(): this;
+    /**
+     * Converts the datetime to ISO date format (YYYY-MM-DD) during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toISODate()
+     * const result = schema.validate('July 15, 2023 3:30 PM')
+     * // Returns: "2023-07-15"
+     * ```
+     */
+    toISODate(): this;
+    /**
+     * Converts the datetime to ISO week date format during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toISOWeekDate()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: "2023-W28-6"
+     * ```
+     */
+    toISOWeekDate(): this;
+    /**
+     * Converts the datetime to ISO time format during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toISOTime()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: "15:30:00.000Z"
+     * ```
+     */
+    toISOTime(): this;
+    /**
+     * Converts the datetime to RFC 2822 format during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toRFC2822()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: "Sat, 15 Jul 2023 15:30:00 +0000"
+     * ```
+     */
+    toRFC2822(): this;
+    /**
+     * Converts the datetime to HTTP date format during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toHTTP()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: "Sat, 15 Jul 2023 15:30:00 GMT"
+     * ```
+     */
+    toHTTP(): this;
+    /**
+     * Converts the datetime to SQL date format (YYYY-MM-DD) during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toSQLDate()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: "2023-07-15"
+     * ```
+     */
+    toSQLDate(): this;
+    /**
+     * Converts the datetime to SQL time format (HH:mm:ss.SSS) during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toSQLTime()
+     * const result = schema.validate('2023-07-15T15:30:45.123Z')
+     * // Returns: "15:30:45.123"
+     * ```
+     */
+    toSQLTime(): this;
+    /**
+     * Converts the datetime to SQL datetime format during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toSQL()
+     * const result = schema.validate('2023-07-15T15:30:45.123Z')
+     * // Returns: "2023-07-15 15:30:45.123 Z"
+     * ```
+     */
+    toSQL(): this;
+    /**
+     * Converts the datetime to milliseconds since Unix epoch during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toMillis()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: 1689433800000
+     * ```
+     */
+    toMillis(): this;
+    /**
+     * Converts the datetime to seconds since Unix epoch during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toSeconds()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: 1689433800.0
+     * ```
+     */
+    toSeconds(): this;
+    /**
+     * Converts the datetime to Unix timestamp (seconds as integer) during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toUnixInteger()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: 1689433800
+     * ```
+     */
+    toUnixInteger(): this;
+    /**
+     * Converts the datetime to JSON string format during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toJSON()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: "2023-07-15T15:30:00.000Z"
+     * ```
+     */
+    toJSON(): this;
+    /**
+     * Converts the datetime to BSON format during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toBSON()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: Date object for BSON serialization
+     * ```
+     */
+    toBSON(): this;
+    /**
+     * Converts the datetime to a plain object representation during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toObject()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: { year: 2023, month: 7, day: 15, hour: 15, minute: 30, second: 0, millisecond: 0 }
+     * ```
+     */
+    toObject(): this;
+    /**
+     * Converts the datetime to a JavaScript Date object during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toJSDate()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: Date object
+     * ```
+     */
+    toJSDate(): this;
+    /**
+     * Converts the datetime to a relative time string during validation.
+     *
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().toRelative()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns: "2 hours ago" (relative to current time)
+     * ```
+     */
+    toRelative(): this;
+    /**
+     * Sets the locale for the datetime during validation.
+     *
+     * @param locale - The locale code (e.g., 'en-US', 'fr-FR')
+     * @returns The schema instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.datetime().setLocale('fr-FR').toLocaleString()
+     * const result = schema.validate('2023-07-15T15:30:00Z')
+     * // Returns localized string in French
+     * ```
+     */
+    setLocale(locale: string): this;
+}
+/**
+ * Joi extension factory for datetime validation using Luxon.
+ *
+ * Creates a comprehensive datetime validation schema that can parse various input formats
+ * (ISO strings, Unix timestamps, JavaScript Dates, Day.js objects, etc.) and convert them
+ * to Luxon DateTime objects. Provides extensive validation rules for comparisons, formatting,
+ * timezone handling, and output transformations.
+ *
+ * The schema automatically handles timezone conversion to UTC by default for consistent
+ * datetime handling across different environments. All parsing attempts maintain UTC timezone
+ * unless explicitly overridden.
+ *
+ * @param this - The Joi root instance
+ * @param joi - The Joi root instance for creating base schemas
+ * @returns Joi extension configuration object
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import Joi from 'joi'
+ * import { datetime } from './datetime'
+ *
+ * const extendedJoi = Joi.extend(datetime)
+ *
+ * const schema = extendedJoi.datetime()
+ * const result = schema.validate('2023-07-15T15:30:00Z')
+ * // Returns { value: DateTime, error: undefined }
+ * ```
+ *
+ * @example With Validation Rules
+ * ```typescript
+ * const schema = extendedJoi.datetime()
+ *   .after('2023-01-01')
+ *   .before('2024-01-01')
+ *   .weekday()
+ *
+ * schema.validate('2023-07-17T10:00:00Z') // Valid (Monday in 2023)
+ * schema.validate('2023-07-15T10:00:00Z') // Invalid (Saturday)
+ * ```
+ *
+ * @example With Output Formatting
+ * ```typescript
+ * const schema = extendedJoi.datetime()
+ *   .toUTC()
+ *   .toISO()
+ *
+ * const result = schema.validate('2023-07-15T10:30:00-05:00')
+ * // Returns: "2023-07-15T15:30:00.000Z"
+ * ```
+ *
+ * @example Supported Input Formats
+ * ```typescript
+ * const schema = extendedJoi.datetime()
+ *
+ * // All of these are valid inputs:
+ * schema.validate('2023-07-15T15:30:00Z')        // ISO string
+ * schema.validate('Sat, 15 Jul 2023 15:30:00 GMT') // RFC2822
+ * schema.validate(1689433800000)                   // Unix timestamp (ms)
+ * schema.validate(new Date())                      // JavaScript Date
+ * schema.validate(DateTime.now())                  // Luxon DateTime
+ * schema.validate({ year: 2023, month: 7, day: 15 }) // DateObjectUnits
+ * ```
+ */
+export declare const datetime: ExtensionFactory;