@nhtio/validation 0.1.0-master-952eca46 → 0.1.0-master-b4207fd6

package/private/schemas/datetime.d.ts

@@ -1,654 +0,0 @@
-import { DateTime } from 'luxon';
-import { ExtensionFactory, CustomHelpers, Reference } from 'joi';
-import type { Dayjs } from 'dayjs';
-import type { Tokens } from '../types';
-import type { AnySchema } from '../schemas';
-import type { Zone, LocaleOptions, DateObjectUnits, ZoneOptions, ToISOTimeOptions, ToISODateOptions, ToSQLOptions, ToRelativeOptions } from 'luxon';
-type CallbackOrValue<T> = T | ((dt: DateTime, helpers: CustomHelpers) => T);
-export declare const messages: {
-    'datetime.base': string;
-    'datetime.exactly': string;
-    'datetime.equals': string;
-    'datetime.after': string;
-    'datetime.greater': string;
-    'datetime.before': string;
-    'datetime.less': string;
-    'datetime.afterOrEqual': string;
-    'datetime.min': string;
-    'datetime.beforeOrEqual': string;
-    'datetime.max': string;
-    'datetime.weekend': string;
-    'datetime.weekday': string;
-};
-/**
- * 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, opts?: ZoneOptions): this;
-    /**
-     * Formats the datetime using a custom format string during validation.
-     *
-     * @param format - The format string (Luxon format tokens) or callback function
-     * @returns The schema instance for method chaining
-     *
-     * @example Static format
-     * ```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"
-     * ```
-     *
-     * @example Callback function (serializable)
-     * ```typescript
-     * const schema = joi.datetime().toFormat((dt, helpers) =>
-     *   dt.year > 2000 ? 'yyyy-MM-dd' : 'MM/dd/yy'
-     * )
-     * ```
-     */
-    toFormat(format: CallbackOrValue<Tokens>): this;
-    /**
-     * Formats the datetime using locale-specific formatting during validation.
-     *
-     * @param formatOpts - Locale formatting options or callback function
-     * @returns The schema instance for method chaining
-     *
-     * @example Static options
-     * ```typescript
-     * const schema = joi.datetime().toLocalizedString({ month: 'long', day: 'numeric' })
-     * const result = schema.validate('2023-07-15T15:30:00Z')
-     * // Returns: "July 15" (or localized equivalent)
-     * ```
-     *
-     * @example Callback function (serializable)
-     * ```typescript
-     * const schema = joi.datetime().toLocalizedString((dt, helpers) => ({
-     *   month: dt.month > 6 ? 'long' : 'short',
-     *   day: 'numeric'
-     * }))
-     * ```
-     */
-    toLocalizedString(formatOpts: CallbackOrValue<LocaleOptions>): this;
-    /**
-     * Converts the datetime to ISO 8601 string format during validation.
-     *
-     * @param opts - Options for ISO string formatting or callback function
-     * @returns The schema instance for method chaining
-     *
-     * @example Static options
-     * ```typescript
-     * const schema = joi.datetime().toISO({ suppressMilliseconds: true })
-     * const result = schema.validate('July 15, 2023 3:30 PM')
-     * // Returns: "2023-07-15T15:30:00Z"
-     * ```
-     *
-     * @example Callback function (serializable)
-     * ```typescript
-     * const schema = joi.datetime().toISO((dt, helpers) => ({
-     *   suppressMilliseconds: true,
-     *   extendedZone: dt.year > 1970,
-     *   precision: 'seconds'
-     * }))
-     * ```
-     */
-    toISO(opts?: CallbackOrValue<ToISOTimeOptions>): this;
-    /**
-     * Converts the datetime to ISO date format (YYYY-MM-DD) during validation.
-     *
-     * @param opts - Options for ISO date formatting or callback function
-     * @returns The schema instance for method chaining
-     *
-     * @example Static options
-     * ```typescript
-     * const schema = joi.datetime().toISODate()
-     * const result = schema.validate('July 15, 2023 3:30 PM')
-     * // Returns: "2023-07-15"
-     * ```
-     *
-     * @example Callback function (serializable)
-     * ```typescript
-     * const schema = joi.datetime().toISODate((dt, helpers) => ({
-     *   format: dt.year > 2000 ? 'extended' : 'basic'
-     * }))
-     * ```
-     */
-    toISODate(opts?: CallbackOrValue<ToISODateOptions>): 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.
-     *
-     * @param opts - Options for ISO time formatting or callback function
-     * @returns The schema instance for method chaining
-     *
-     * @example Static options
-     * ```typescript
-     * const schema = joi.datetime().toISOTime({ suppressMilliseconds: true })
-     * const result = schema.validate('2023-07-15T15:30:00Z')
-     * // Returns: "15:30:00Z"
-     * ```
-     *
-     * @example Callback function (serializable)
-     * ```typescript
-     * const schema = joi.datetime().toISOTime((dt, helpers) => ({
-     *   suppressMilliseconds: dt.millisecond === 0
-     * }))
-     * ```
-     */
-    toISOTime(opts?: CallbackOrValue<ToISOTimeOptions>): 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.
-     *
-     * @param opts - Options for SQL time formatting or callback function
-     * @returns The schema instance for method chaining
-     *
-     * @example Static options
-     * ```typescript
-     * const schema = joi.datetime().toSQLTime({ includeZone: true })
-     * const result = schema.validate('2023-07-15T15:30:45.123Z')
-     * // Returns: "15:30:45.123 Z"
-     * ```
-     *
-     * @example Callback function (serializable)
-     * ```typescript
-     * const schema = joi.datetime().toSQLTime((dt, helpers) => ({
-     *   includeZone: dt.zone.name !== 'UTC'
-     * }))
-     * ```
-     */
-    toSQLTime(opts?: CallbackOrValue<ToSQLOptions>): this;
-    /**
-     * Converts the datetime to SQL datetime format during validation.
-     *
-     * @param opts - Options for SQL formatting or callback function
-     * @returns The schema instance for method chaining
-     *
-     * @example Static options
-     * ```typescript
-     * const schema = joi.datetime().toSQL({ includeZone: false })
-     * const result = schema.validate('2023-07-15T15:30:45.123Z')
-     * // Returns: "2023-07-15 15:30:45.123"
-     * ```
-     *
-     * @example Callback function (serializable)
-     * ```typescript
-     * const schema = joi.datetime().toSQL((dt, helpers) => ({
-     *   includeZone: dt.zone.name !== 'UTC'
-     * }))
-     * ```
-     */
-    toSQL(opts?: CallbackOrValue<ToSQLOptions>): 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.
-     *
-     * @param opts - Options for object conversion or callback function
-     * @returns The schema instance for method chaining
-     *
-     * @example Static options
-     * ```typescript
-     * const schema = joi.datetime().toObject({ includeConfig: true })
-     * const result = schema.validate('2023-07-15T15:30:00Z')
-     * // Returns: { year: 2023, month: 7, day: 15, hour: 15, minute: 30, second: 0, millisecond: 0 }
-     * ```
-     *
-     * @example Callback function (serializable)
-     * ```typescript
-     * const schema = joi.datetime().toObject((dt, helpers) => ({
-     *   includeConfig: dt.year > 2000
-     * }))
-     * ```
-     */
-    toObject(opts?: CallbackOrValue<{
-        includeConfig?: boolean;
-    }>): 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.
-     *
-     * @param opts - Options for relative time formatting or callback function
-     * @returns The schema instance for method chaining
-     *
-     * @example Static options
-     * ```typescript
-     * const schema = joi.datetime().toRelative({ base: DateTime.now() })
-     * const result = schema.validate('2023-07-15T15:30:00Z')
-     * // Returns: "2 hours ago" (relative to current time)
-     * ```
-     *
-     * @example Callback function (serializable)
-     * ```typescript
-     * const schema = joi.datetime().toRelative((dt, helpers) => ({
-     *   base: dt.year > 2020 ? DateTime.now() : DateTime.fromISO('2020-01-01')
-     * }))
-     * ```
-     */
-    toRelative(opts?: CallbackOrValue<ToRelativeOptions>): 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;
-export {};