@hy_ong/zod-kit 0.2.0 → 0.2.2

package/dist/common/datetime.d.cts

@@ -0,0 +1,301 @@
+import { ZodString, ZodNullable } from 'zod';
+import { L as Locale } from '../config-CABSSvAp.cjs';
+import dayjs from 'dayjs';
+
+/**
+ * @fileoverview DateTime validator for Zod Kit
+ *
+ * Provides comprehensive datetime validation with support for multiple formats,
+ * timezone handling, range validation, and internationalization.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for datetime validation error messages
+ *
+ * @interface DateTimeMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when datetime format is invalid
+ * @property {string} [format] - Message when datetime doesn't match expected format
+ * @property {string} [min] - Message when datetime is before minimum allowed
+ * @property {string} [max] - Message when datetime is after maximum allowed
+ * @property {string} [includes] - Message when datetime doesn't include required string
+ * @property {string} [excludes] - Message when datetime contains excluded string
+ * @property {string} [past] - Message when datetime must be in the past
+ * @property {string} [future] - Message when datetime must be in the future
+ * @property {string} [today] - Message when datetime must be today
+ * @property {string} [notToday] - Message when datetime must not be today
+ * @property {string} [weekday] - Message when datetime must be a weekday
+ * @property {string} [weekend] - Message when datetime must be a weekend
+ * @property {string} [hour] - Message when hour is outside allowed range
+ * @property {string} [minute] - Message when minute doesn't match step requirement
+ * @property {string} [customRegex] - Message when custom regex validation fails
+ * @property {string} [notInWhitelist] - Message when value is not in whitelist
+ */
+type DateTimeMessages = {
+    required?: string;
+    invalid?: string;
+    format?: string;
+    min?: string;
+    max?: string;
+    includes?: string;
+    excludes?: string;
+    past?: string;
+    future?: string;
+    today?: string;
+    notToday?: string;
+    weekday?: string;
+    weekend?: string;
+    hour?: string;
+    minute?: string;
+    customRegex?: string;
+    notInWhitelist?: string;
+};
+/**
+ * Supported datetime formats for validation
+ *
+ * @typedef {string} DateTimeFormat
+ *
+ * Standard formats:
+ * - YYYY-MM-DD HH:mm: ISO-style date with 24-hour time (2024-03-15 14:30)
+ * - YYYY-MM-DD HH:mm:ss: ISO-style date with seconds (2024-03-15 14:30:45)
+ * - YYYY-MM-DD hh:mm A: ISO-style date with 12-hour time (2024-03-15 02:30 PM)
+ * - YYYY-MM-DD hh:mm:ss A: ISO-style date with 12-hour time and seconds (2024-03-15 02:30:45 PM)
+ *
+ * Regional formats:
+ * - DD/MM/YYYY HH:mm: European format (15/03/2024 14:30)
+ * - DD/MM/YYYY HH:mm:ss: European format with seconds (15/03/2024 14:30:45)
+ * - DD/MM/YYYY hh:mm A: European format with 12-hour time (15/03/2024 02:30 PM)
+ * - MM/DD/YYYY HH:mm: US format (03/15/2024 14:30)
+ * - MM/DD/YYYY hh:mm A: US format with 12-hour time (03/15/2024 02:30 PM)
+ * - YYYY/MM/DD HH:mm: Alternative slash format (2024/03/15 14:30)
+ * - DD-MM-YYYY HH:mm: European dash format (15-03-2024 14:30)
+ * - MM-DD-YYYY HH:mm: US dash format (03-15-2024 14:30)
+ *
+ * Special formats:
+ * - ISO: ISO 8601 format (2024-03-15T14:30:45.000Z)
+ * - RFC: RFC 2822 format (Fri, 15 Mar 2024 14:30:45 GMT)
+ * - UNIX: Unix timestamp (1710508245)
+ */
+type DateTimeFormat = "YYYY-MM-DD HH:mm" | "YYYY-MM-DD HH:mm:ss" | "YYYY-MM-DD hh:mm A" | "YYYY-MM-DD hh:mm:ss A" | "DD/MM/YYYY HH:mm" | "DD/MM/YYYY HH:mm:ss" | "DD/MM/YYYY hh:mm A" | "MM/DD/YYYY HH:mm" | "MM/DD/YYYY hh:mm A" | "YYYY/MM/DD HH:mm" | "DD-MM-YYYY HH:mm" | "MM-DD-YYYY HH:mm" | "ISO" | "RFC" | "UNIX";
+/**
+ * Configuration options for datetime validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface DateTimeOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {DateTimeFormat} [format="YYYY-MM-DD HH:mm"] - Expected datetime format
+ * @property {string | Date} [min] - Minimum allowed datetime
+ * @property {string | Date} [max] - Maximum allowed datetime
+ * @property {number} [minHour] - Minimum allowed hour (0-23)
+ * @property {number} [maxHour] - Maximum allowed hour (0-23)
+ * @property {number[]} [allowedHours] - Specific hours that are allowed
+ * @property {number} [minuteStep] - Required minute intervals (e.g., 15 for :00, :15, :30, :45)
+ * @property {string} [timezone] - Timezone for parsing and validation (e.g., "Asia/Taipei")
+ * @property {string} [includes] - String that must be included in the datetime
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {RegExp} [regex] - Custom regex for validation (overrides format validation)
+ * @property {"trim" | "trimStart" | "trimEnd" | "none"} [trimMode="trim"] - Whitespace handling
+ * @property {"upper" | "lower" | "none"} [casing="none"] - Case transformation
+ * @property {boolean} [mustBePast] - Whether datetime must be in the past
+ * @property {boolean} [mustBeFuture] - Whether datetime must be in the future
+ * @property {boolean} [mustBeToday] - Whether datetime must be today
+ * @property {boolean} [mustNotBeToday] - Whether datetime must not be today
+ * @property {boolean} [weekdaysOnly] - Whether datetime must be a weekday (Monday-Friday)
+ * @property {boolean} [weekendsOnly] - Whether datetime must be a weekend (Saturday-Sunday)
+ * @property {string[]} [whitelist] - Specific datetime strings that are always allowed
+ * @property {boolean} [whitelistOnly=false] - If true, only values in whitelist are allowed
+ * @property {Function} [transform] - Custom transformation function applied before validation
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, DateTimeMessages>} [i18n] - Custom error messages for different locales
+ */
+type DateTimeOptions<IsRequired extends boolean = true> = {
+    format?: DateTimeFormat;
+    min?: string | Date;
+    max?: string | Date;
+    minHour?: number;
+    maxHour?: number;
+    allowedHours?: number[];
+    minuteStep?: number;
+    timezone?: string;
+    includes?: string;
+    excludes?: string | string[];
+    regex?: RegExp;
+    trimMode?: "trim" | "trimStart" | "trimEnd" | "none";
+    casing?: "upper" | "lower" | "none";
+    mustBePast?: boolean;
+    mustBeFuture?: boolean;
+    mustBeToday?: boolean;
+    mustNotBeToday?: boolean;
+    weekdaysOnly?: boolean;
+    weekendsOnly?: boolean;
+    whitelist?: string[];
+    whitelistOnly?: boolean;
+    transform?: (value: string) => string;
+    defaultValue?: IsRequired extends true ? string : string | null;
+    i18n?: Partial<Record<Locale, Partial<DateTimeMessages>>>;
+};
+/**
+ * Type alias for datetime validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef DateTimeSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
+type DateTimeSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Regular expression patterns for datetime format validation
+ *
+ * @constant {Record<DateTimeFormat, RegExp>} DATETIME_PATTERNS
+ * @description Maps each supported datetime format to its corresponding regex pattern
+ *
+ * Pattern explanations:
+ * - YYYY-MM-DD HH:mm: 4-digit year, 2-digit month, 2-digit day, 24-hour time
+ * - ISO: ISO 8601 format with optional milliseconds and timezone
+ * - RFC: RFC 2822 format with day name, date, time, and timezone
+ * - UNIX: 10-digit Unix timestamp
+ */
+declare const DATETIME_PATTERNS: Record<DateTimeFormat, RegExp>;
+/**
+ * Validates if a datetime string matches the specified format pattern
+ *
+ * @param {string} value - The datetime string to validate
+ * @param {DateTimeFormat} format - The expected datetime format
+ * @returns {boolean} True if the datetime is valid for the given format
+ *
+ * @description
+ * Performs both regex pattern matching and actual datetime parsing validation.
+ * Returns false if either the pattern doesn't match or the parsed datetime is invalid.
+ *
+ * @example
+ * ```typescript
+ * validateDateTimeFormat("2024-03-15 14:30", "YYYY-MM-DD HH:mm") // true
+ * validateDateTimeFormat("2024-03-15 25:30", "YYYY-MM-DD HH:mm") // false (invalid hour)
+ * validateDateTimeFormat("15/03/2024", "YYYY-MM-DD HH:mm") // false (wrong format)
+ * ```
+ */
+declare const validateDateTimeFormat: (value: string, format: DateTimeFormat) => boolean;
+/**
+ * Parses a datetime string into a dayjs object using the specified format
+ *
+ * @param {string} value - The datetime string to parse
+ * @param {DateTimeFormat} format - The expected datetime format
+ * @param {string} [timezone] - Optional timezone for parsing (e.g., "Asia/Taipei")
+ * @returns {dayjs.Dayjs | null} Parsed dayjs object or null if parsing fails
+ *
+ * @description
+ * Handles different datetime formats including ISO, RFC, Unix timestamps, and custom formats.
+ * Uses strict parsing mode for custom formats to ensure accuracy.
+ * Applies timezone conversion if specified.
+ *
+ * @example
+ * ```typescript
+ * parseDateTimeValue("2024-03-15 14:30", "YYYY-MM-DD HH:mm")
+ * // Returns dayjs object for March 15, 2024 at 2:30 PM
+ *
+ * parseDateTimeValue("1710508245", "UNIX")
+ * // Returns dayjs object for the Unix timestamp
+ *
+ * parseDateTimeValue("2024-03-15T14:30:45.000Z", "ISO")
+ * // Returns dayjs object for the ISO datetime
+ * ```
+ *
+ * @throws {Error} Returns null if parsing fails or datetime is invalid
+ */
+declare const parseDateTimeValue: (value: string, format: DateTimeFormat, timezone?: string) => dayjs.Dayjs | null;
+/**
+ * Normalizes a datetime string to the specified format
+ *
+ * @param {string} value - The datetime string to normalize
+ * @param {DateTimeFormat} format - The target datetime format
+ * @param {string} [timezone] - Optional timezone for formatting
+ * @returns {string | null} Normalized datetime string or null if parsing fails
+ *
+ * @description
+ * Parses the input datetime and formats it according to the specified format.
+ * Handles special formats like ISO, RFC, and Unix timestamps appropriately.
+ * Returns null if the input datetime cannot be parsed.
+ *
+ * @example
+ * ```typescript
+ * normalizeDateTimeValue("2024-3-15 2:30 PM", "YYYY-MM-DD HH:mm")
+ * // Returns "2024-03-15 14:30"
+ *
+ * normalizeDateTimeValue("1710508245", "ISO")
+ * // Returns "2024-03-15T14:30:45.000Z"
+ * ```
+ */
+declare const normalizeDateTimeValue: (value: string, format: DateTimeFormat, timezone?: string) => string | null;
+/**
+ * Creates a Zod schema for datetime validation with comprehensive options
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
+ * @returns {DateTimeSchema<IsRequired>} Zod schema for datetime validation
+ *
+ * @description
+ * Creates a comprehensive datetime validator that supports multiple formats, timezone handling,
+ * range validation, temporal constraints, and extensive customization options.
+ *
+ * Features:
+ * - Multiple datetime formats (ISO, RFC, Unix, regional formats)
+ * - Timezone support and conversion
+ * - Range validation (min/max datetime)
+ * - Hour and minute constraints
+ * - Temporal validation (past/future/today)
+ * - Weekday/weekend validation
+ * - Whitelist/blacklist support
+ * - Custom regex patterns
+ * - String transformation and case handling
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic datetime validation
+ * const basicSchema = datetime() // optional by default
+ * basicSchema.parse("2024-03-15 14:30") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("2024-03-15 14:30") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ *
+ * // Business hours validation
+ * const businessHours = datetime({
+ *   format: "YYYY-MM-DD HH:mm",
+ *   minHour: 9,
+ *   maxHour: 17,
+ *   weekdaysOnly: true
+ * })
+ *
+ * // Timezone-aware validation
+ * const timezoneSchema = datetime(false, {
+ *   timezone: "Asia/Taipei",
+ *   mustBeFuture: true
+ * })
+ *
+ * // Multiple format support
+ * const flexibleSchema = datetime(false, {
+ *   format: "DD/MM/YYYY HH:mm"
+ * })
+ * flexibleSchema.parse("15/03/2024 14:30") // ✓ Valid
+ *
+ * // Optional with default
+ * const optionalSchema = datetime(false, {
+ *   defaultValue: "2024-01-01 00:00"
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link DateTimeOptions} for all available configuration options
+ * @see {@link DateTimeFormat} for supported datetime formats
+ */
+declare function datetime<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<DateTimeOptions<IsRequired>, 'required'>): DateTimeSchema<IsRequired>;
+
+export { DATETIME_PATTERNS, type DateTimeFormat, type DateTimeMessages, type DateTimeOptions, type DateTimeSchema, datetime, normalizeDateTimeValue, parseDateTimeValue, validateDateTimeFormat };

package/dist/common/datetime.d.ts

@@ -0,0 +1,301 @@
+import { ZodString, ZodNullable } from 'zod';
+import { L as Locale } from '../config-CABSSvAp.js';
+import dayjs from 'dayjs';
+
+/**
+ * @fileoverview DateTime validator for Zod Kit
+ *
+ * Provides comprehensive datetime validation with support for multiple formats,
+ * timezone handling, range validation, and internationalization.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for datetime validation error messages
+ *
+ * @interface DateTimeMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when datetime format is invalid
+ * @property {string} [format] - Message when datetime doesn't match expected format
+ * @property {string} [min] - Message when datetime is before minimum allowed
+ * @property {string} [max] - Message when datetime is after maximum allowed
+ * @property {string} [includes] - Message when datetime doesn't include required string
+ * @property {string} [excludes] - Message when datetime contains excluded string
+ * @property {string} [past] - Message when datetime must be in the past
+ * @property {string} [future] - Message when datetime must be in the future
+ * @property {string} [today] - Message when datetime must be today
+ * @property {string} [notToday] - Message when datetime must not be today
+ * @property {string} [weekday] - Message when datetime must be a weekday
+ * @property {string} [weekend] - Message when datetime must be a weekend
+ * @property {string} [hour] - Message when hour is outside allowed range
+ * @property {string} [minute] - Message when minute doesn't match step requirement
+ * @property {string} [customRegex] - Message when custom regex validation fails
+ * @property {string} [notInWhitelist] - Message when value is not in whitelist
+ */
+type DateTimeMessages = {
+    required?: string;
+    invalid?: string;
+    format?: string;
+    min?: string;
+    max?: string;
+    includes?: string;
+    excludes?: string;
+    past?: string;
+    future?: string;
+    today?: string;
+    notToday?: string;
+    weekday?: string;
+    weekend?: string;
+    hour?: string;
+    minute?: string;
+    customRegex?: string;
+    notInWhitelist?: string;
+};
+/**
+ * Supported datetime formats for validation
+ *
+ * @typedef {string} DateTimeFormat
+ *
+ * Standard formats:
+ * - YYYY-MM-DD HH:mm: ISO-style date with 24-hour time (2024-03-15 14:30)
+ * - YYYY-MM-DD HH:mm:ss: ISO-style date with seconds (2024-03-15 14:30:45)
+ * - YYYY-MM-DD hh:mm A: ISO-style date with 12-hour time (2024-03-15 02:30 PM)
+ * - YYYY-MM-DD hh:mm:ss A: ISO-style date with 12-hour time and seconds (2024-03-15 02:30:45 PM)
+ *
+ * Regional formats:
+ * - DD/MM/YYYY HH:mm: European format (15/03/2024 14:30)
+ * - DD/MM/YYYY HH:mm:ss: European format with seconds (15/03/2024 14:30:45)
+ * - DD/MM/YYYY hh:mm A: European format with 12-hour time (15/03/2024 02:30 PM)
+ * - MM/DD/YYYY HH:mm: US format (03/15/2024 14:30)
+ * - MM/DD/YYYY hh:mm A: US format with 12-hour time (03/15/2024 02:30 PM)
+ * - YYYY/MM/DD HH:mm: Alternative slash format (2024/03/15 14:30)
+ * - DD-MM-YYYY HH:mm: European dash format (15-03-2024 14:30)
+ * - MM-DD-YYYY HH:mm: US dash format (03-15-2024 14:30)
+ *
+ * Special formats:
+ * - ISO: ISO 8601 format (2024-03-15T14:30:45.000Z)
+ * - RFC: RFC 2822 format (Fri, 15 Mar 2024 14:30:45 GMT)
+ * - UNIX: Unix timestamp (1710508245)
+ */
+type DateTimeFormat = "YYYY-MM-DD HH:mm" | "YYYY-MM-DD HH:mm:ss" | "YYYY-MM-DD hh:mm A" | "YYYY-MM-DD hh:mm:ss A" | "DD/MM/YYYY HH:mm" | "DD/MM/YYYY HH:mm:ss" | "DD/MM/YYYY hh:mm A" | "MM/DD/YYYY HH:mm" | "MM/DD/YYYY hh:mm A" | "YYYY/MM/DD HH:mm" | "DD-MM-YYYY HH:mm" | "MM-DD-YYYY HH:mm" | "ISO" | "RFC" | "UNIX";
+/**
+ * Configuration options for datetime validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface DateTimeOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {DateTimeFormat} [format="YYYY-MM-DD HH:mm"] - Expected datetime format
+ * @property {string | Date} [min] - Minimum allowed datetime
+ * @property {string | Date} [max] - Maximum allowed datetime
+ * @property {number} [minHour] - Minimum allowed hour (0-23)
+ * @property {number} [maxHour] - Maximum allowed hour (0-23)
+ * @property {number[]} [allowedHours] - Specific hours that are allowed
+ * @property {number} [minuteStep] - Required minute intervals (e.g., 15 for :00, :15, :30, :45)
+ * @property {string} [timezone] - Timezone for parsing and validation (e.g., "Asia/Taipei")
+ * @property {string} [includes] - String that must be included in the datetime
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {RegExp} [regex] - Custom regex for validation (overrides format validation)
+ * @property {"trim" | "trimStart" | "trimEnd" | "none"} [trimMode="trim"] - Whitespace handling
+ * @property {"upper" | "lower" | "none"} [casing="none"] - Case transformation
+ * @property {boolean} [mustBePast] - Whether datetime must be in the past
+ * @property {boolean} [mustBeFuture] - Whether datetime must be in the future
+ * @property {boolean} [mustBeToday] - Whether datetime must be today
+ * @property {boolean} [mustNotBeToday] - Whether datetime must not be today
+ * @property {boolean} [weekdaysOnly] - Whether datetime must be a weekday (Monday-Friday)
+ * @property {boolean} [weekendsOnly] - Whether datetime must be a weekend (Saturday-Sunday)
+ * @property {string[]} [whitelist] - Specific datetime strings that are always allowed
+ * @property {boolean} [whitelistOnly=false] - If true, only values in whitelist are allowed
+ * @property {Function} [transform] - Custom transformation function applied before validation
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, DateTimeMessages>} [i18n] - Custom error messages for different locales
+ */
+type DateTimeOptions<IsRequired extends boolean = true> = {
+    format?: DateTimeFormat;
+    min?: string | Date;
+    max?: string | Date;
+    minHour?: number;
+    maxHour?: number;
+    allowedHours?: number[];
+    minuteStep?: number;
+    timezone?: string;
+    includes?: string;
+    excludes?: string | string[];
+    regex?: RegExp;
+    trimMode?: "trim" | "trimStart" | "trimEnd" | "none";
+    casing?: "upper" | "lower" | "none";
+    mustBePast?: boolean;
+    mustBeFuture?: boolean;
+    mustBeToday?: boolean;
+    mustNotBeToday?: boolean;
+    weekdaysOnly?: boolean;
+    weekendsOnly?: boolean;
+    whitelist?: string[];
+    whitelistOnly?: boolean;
+    transform?: (value: string) => string;
+    defaultValue?: IsRequired extends true ? string : string | null;
+    i18n?: Partial<Record<Locale, Partial<DateTimeMessages>>>;
+};
+/**
+ * Type alias for datetime validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef DateTimeSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
+type DateTimeSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Regular expression patterns for datetime format validation
+ *
+ * @constant {Record<DateTimeFormat, RegExp>} DATETIME_PATTERNS
+ * @description Maps each supported datetime format to its corresponding regex pattern
+ *
+ * Pattern explanations:
+ * - YYYY-MM-DD HH:mm: 4-digit year, 2-digit month, 2-digit day, 24-hour time
+ * - ISO: ISO 8601 format with optional milliseconds and timezone
+ * - RFC: RFC 2822 format with day name, date, time, and timezone
+ * - UNIX: 10-digit Unix timestamp
+ */
+declare const DATETIME_PATTERNS: Record<DateTimeFormat, RegExp>;
+/**
+ * Validates if a datetime string matches the specified format pattern
+ *
+ * @param {string} value - The datetime string to validate
+ * @param {DateTimeFormat} format - The expected datetime format
+ * @returns {boolean} True if the datetime is valid for the given format
+ *
+ * @description
+ * Performs both regex pattern matching and actual datetime parsing validation.
+ * Returns false if either the pattern doesn't match or the parsed datetime is invalid.
+ *
+ * @example
+ * ```typescript
+ * validateDateTimeFormat("2024-03-15 14:30", "YYYY-MM-DD HH:mm") // true
+ * validateDateTimeFormat("2024-03-15 25:30", "YYYY-MM-DD HH:mm") // false (invalid hour)
+ * validateDateTimeFormat("15/03/2024", "YYYY-MM-DD HH:mm") // false (wrong format)
+ * ```
+ */
+declare const validateDateTimeFormat: (value: string, format: DateTimeFormat) => boolean;
+/**
+ * Parses a datetime string into a dayjs object using the specified format
+ *
+ * @param {string} value - The datetime string to parse
+ * @param {DateTimeFormat} format - The expected datetime format
+ * @param {string} [timezone] - Optional timezone for parsing (e.g., "Asia/Taipei")
+ * @returns {dayjs.Dayjs | null} Parsed dayjs object or null if parsing fails
+ *
+ * @description
+ * Handles different datetime formats including ISO, RFC, Unix timestamps, and custom formats.
+ * Uses strict parsing mode for custom formats to ensure accuracy.
+ * Applies timezone conversion if specified.
+ *
+ * @example
+ * ```typescript
+ * parseDateTimeValue("2024-03-15 14:30", "YYYY-MM-DD HH:mm")
+ * // Returns dayjs object for March 15, 2024 at 2:30 PM
+ *
+ * parseDateTimeValue("1710508245", "UNIX")
+ * // Returns dayjs object for the Unix timestamp
+ *
+ * parseDateTimeValue("2024-03-15T14:30:45.000Z", "ISO")
+ * // Returns dayjs object for the ISO datetime
+ * ```
+ *
+ * @throws {Error} Returns null if parsing fails or datetime is invalid
+ */
+declare const parseDateTimeValue: (value: string, format: DateTimeFormat, timezone?: string) => dayjs.Dayjs | null;
+/**
+ * Normalizes a datetime string to the specified format
+ *
+ * @param {string} value - The datetime string to normalize
+ * @param {DateTimeFormat} format - The target datetime format
+ * @param {string} [timezone] - Optional timezone for formatting
+ * @returns {string | null} Normalized datetime string or null if parsing fails
+ *
+ * @description
+ * Parses the input datetime and formats it according to the specified format.
+ * Handles special formats like ISO, RFC, and Unix timestamps appropriately.
+ * Returns null if the input datetime cannot be parsed.
+ *
+ * @example
+ * ```typescript
+ * normalizeDateTimeValue("2024-3-15 2:30 PM", "YYYY-MM-DD HH:mm")
+ * // Returns "2024-03-15 14:30"
+ *
+ * normalizeDateTimeValue("1710508245", "ISO")
+ * // Returns "2024-03-15T14:30:45.000Z"
+ * ```
+ */
+declare const normalizeDateTimeValue: (value: string, format: DateTimeFormat, timezone?: string) => string | null;
+/**
+ * Creates a Zod schema for datetime validation with comprehensive options
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
+ * @returns {DateTimeSchema<IsRequired>} Zod schema for datetime validation
+ *
+ * @description
+ * Creates a comprehensive datetime validator that supports multiple formats, timezone handling,
+ * range validation, temporal constraints, and extensive customization options.
+ *
+ * Features:
+ * - Multiple datetime formats (ISO, RFC, Unix, regional formats)
+ * - Timezone support and conversion
+ * - Range validation (min/max datetime)
+ * - Hour and minute constraints
+ * - Temporal validation (past/future/today)
+ * - Weekday/weekend validation
+ * - Whitelist/blacklist support
+ * - Custom regex patterns
+ * - String transformation and case handling
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic datetime validation
+ * const basicSchema = datetime() // optional by default
+ * basicSchema.parse("2024-03-15 14:30") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("2024-03-15 14:30") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ *
+ * // Business hours validation
+ * const businessHours = datetime({
+ *   format: "YYYY-MM-DD HH:mm",
+ *   minHour: 9,
+ *   maxHour: 17,
+ *   weekdaysOnly: true
+ * })
+ *
+ * // Timezone-aware validation
+ * const timezoneSchema = datetime(false, {
+ *   timezone: "Asia/Taipei",
+ *   mustBeFuture: true
+ * })
+ *
+ * // Multiple format support
+ * const flexibleSchema = datetime(false, {
+ *   format: "DD/MM/YYYY HH:mm"
+ * })
+ * flexibleSchema.parse("15/03/2024 14:30") // ✓ Valid
+ *
+ * // Optional with default
+ * const optionalSchema = datetime(false, {
+ *   defaultValue: "2024-01-01 00:00"
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link DateTimeOptions} for all available configuration options
+ * @see {@link DateTimeFormat} for supported datetime formats
+ */
+declare function datetime<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<DateTimeOptions<IsRequired>, 'required'>): DateTimeSchema<IsRequired>;
+
+export { DATETIME_PATTERNS, type DateTimeFormat, type DateTimeMessages, type DateTimeOptions, type DateTimeSchema, datetime, normalizeDateTimeValue, parseDateTimeValue, validateDateTimeFormat };

package/dist/common/datetime.js

@@ -0,0 +1,15 @@
+import {
+  DATETIME_PATTERNS,
+  datetime,
+  normalizeDateTimeValue,
+  parseDateTimeValue,
+  validateDateTimeFormat
+} from "../chunk-ZXUMK2RR.js";
+import "../chunk-6AAP4LPF.js";
+export {
+  DATETIME_PATTERNS,
+  datetime,
+  normalizeDateTimeValue,
+  parseDateTimeValue,
+  validateDateTimeFormat
+};

package/dist/common/email.cjs

@@ -0,0 +1,7 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkHMSM6FFAcjs = require('../chunk-HMSM6FFA.cjs');
+require('../chunk-UCOXAZJF.cjs');
+
+
+exports.email = _chunkHMSM6FFAcjs.email;