@hy_ong/zod-kit 0.0.5 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hy_ong/zod-kit",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Zod Kit",
   "keywords": [
     "hy_ong",

package/src/i18n/locales/en.json

@@ -112,6 +112,56 @@
       "notToday": "Date must not be today",
       "weekday": "Date must be a weekday (Monday-Friday)",
       "weekend": "Date must be a weekend (Saturday-Sunday)"
+    },
+    "time": {
+      "required": "Required",
+      "invalid": "Invalid time format",
+      "format": "Must be in ${format} format",
+      "min": "Time must be after ${min}",
+      "max": "Time must be before ${max}",
+      "hour": "Hour must be between ${minHour} and ${maxHour}",
+      "minute": "Minutes must be in ${minuteStep}-minute intervals",
+      "second": "Seconds must be in ${secondStep}-second intervals",
+      "includes": "Must include ${includes}",
+      "excludes": "Must not contain ${excludes}",
+      "customRegex": "Invalid time format",
+      "notInWhitelist": "Time is not in the allowed list"
+    },
+    "datetime": {
+      "required": "Required",
+      "invalid": "Invalid datetime format",
+      "format": "Must be in ${format} format",
+      "min": "DateTime must be after ${min}",
+      "max": "DateTime must be before ${max}",
+      "hour": "Hour must be between ${minHour} and ${maxHour}",
+      "minute": "Minutes must be in ${minuteStep}-minute intervals",
+      "includes": "Must include ${includes}",
+      "excludes": "Must not contain ${excludes}",
+      "past": "DateTime must be in the past",
+      "future": "DateTime must be in the future",
+      "today": "DateTime must be today",
+      "notToday": "DateTime must not be today",
+      "weekday": "DateTime must be a weekday (Monday-Friday)",
+      "weekend": "DateTime must be a weekend (Saturday-Sunday)",
+      "customRegex": "Invalid datetime format",
+      "notInWhitelist": "DateTime is not in the allowed list"
+    },
+    "file": {
+      "required": "Required",
+      "invalid": "Invalid file format",
+      "size": "File size must not exceed ${size}",
+      "minSize": "File size must be at least ${minSize}",
+      "maxSize": "File size must not exceed ${maxSize}",
+      "type": "File type must be one of: ${type}",
+      "extension": "File extension must be one of: ${extension}",
+      "extensionBlacklist": "File extension ${extension} is not allowed",
+      "name": "File name must match pattern ${pattern}",
+      "nameBlacklist": "File name must not match pattern ${pattern}",
+      "imageOnly": "Only image files are allowed",
+      "documentOnly": "Only document files are allowed",
+      "videoOnly": "Only video files are allowed",
+      "audioOnly": "Only audio files are allowed",
+      "archiveOnly": "Only archive files are allowed"
     }
   },
   "taiwan": {
@@ -137,6 +187,18 @@
       "required": "Required",
       "invalid": "Invalid Taiwan fax format",
       "notInWhitelist": "Not in allowed fax list"
+    },
+    "postalCode": {
+      "required": "Required",
+      "invalid": "Invalid Taiwan postal code",
+      "invalidFormat": "Invalid postal code format",
+      "invalidRange": "Postal code is outside valid range",
+      "legacy5DigitWarning": "5-digit postal codes are legacy format, consider using 6-digit format",
+      "format3Only": "Only 3-digit postal codes are allowed",
+      "format5Only": "Only 5-digit postal codes are allowed",
+      "format6Only": "Only 6-digit postal codes are allowed",
+      "invalidSuffix": "Invalid postal code suffix - must be 01-99 for 5-digit or 001-999 for 6-digit codes",
+      "deprecated5Digit": "5-digit postal codes are deprecated and no longer supported"
     }
   }
 }

package/src/i18n/locales/zh-TW.json

@@ -112,6 +112,56 @@
       "notToday": "不得為今天",
       "weekday": "必須為工作日（週一至週五）",
       "weekend": "必須為週末（週六至週日）"
+    },
+    "time": {
+      "required": "必填",
+      "invalid": "無效的時間格式",
+      "format": "必須為 ${format} 格式",
+      "min": "時間不得早於 ${min}",
+      "max": "時間不得晚於 ${max}",
+      "hour": "小時必須介於 ${minHour} 與 ${maxHour} 之間",
+      "minute": "分鐘必須為 ${minuteStep} 分鐘間隔",
+      "second": "秒數必須為 ${secondStep} 秒間隔",
+      "includes": "必須包含「${includes}」",
+      "excludes": "不得包含「${excludes}」",
+      "customRegex": "無效的時間格式",
+      "notInWhitelist": "時間不在允許清單中"
+    },
+    "datetime": {
+      "required": "必填",
+      "invalid": "無效的日期時間格式",
+      "format": "必須為 ${format} 格式",
+      "min": "日期時間不得早於 ${min}",
+      "max": "日期時間不得晚於 ${max}",
+      "hour": "小時必須介於 ${minHour} 與 ${maxHour} 之間",
+      "minute": "分鐘必須為 ${minuteStep} 分鐘間隔",
+      "includes": "必須包含「${includes}」",
+      "excludes": "不得包含「${excludes}」",
+      "past": "必須為過去的日期時間",
+      "future": "必須為未來的日期時間",
+      "today": "必須為今天",
+      "notToday": "不得為今天",
+      "weekday": "必須為工作日（週一至週五）",
+      "weekend": "必須為週末（週六至週日）",
+      "customRegex": "無效的日期時間格式",
+      "notInWhitelist": "日期時間不在允許清單中"
+    },
+    "file": {
+      "required": "必填",
+      "invalid": "無效的檔案格式",
+      "size": "檔案大小不得超過 ${size}",
+      "minSize": "檔案大小至少 ${minSize}",
+      "maxSize": "檔案大小不得超過 ${maxSize}",
+      "type": "檔案類型必須為：${type}",
+      "extension": "副檔名必須為：${extension}",
+      "extensionBlacklist": "不允許使用副檔名 ${extension}",
+      "name": "檔案名稱必須符合格式 ${pattern}",
+      "nameBlacklist": "檔案名稱不得符合格式 ${pattern}",
+      "imageOnly": "僅允許圖片檔案",
+      "documentOnly": "僅允許文件檔案",
+      "videoOnly": "僅允許影片檔案",
+      "audioOnly": "僅允許音訊檔案",
+      "archiveOnly": "僅允許壓縮檔案"
     }
   },
   "taiwan": {
@@ -137,6 +187,18 @@
       "required": "必填",
       "invalid": "無效的傳真號碼格式",
       "notInWhitelist": "不在允許的傳真號碼清單中"
+    },
+    "postalCode": {
+      "required": "必填",
+      "invalid": "無效的郵遞區號",
+      "invalidFormat": "郵遞區號格式錯誤",
+      "invalidRange": "郵遞區號超出有效範圍",
+      "legacy5DigitWarning": "5 碼郵遞區號為舊式格式，建議使用 6 碼格式",
+      "format3Only": "僅允許 3 碼郵遞區號",
+      "format5Only": "僅允許 5 碼郵遞區號",
+      "format6Only": "僅允許 6 碼郵遞區號",
+      "invalidSuffix": "無效的郵遞區號後碼 - 5 碼格式須為 01-99，6 碼格式須為 001-999",
+      "deprecated5Digit": "5 碼郵遞區號已棄用且不再支援"
     }
   }
 }

package/src/index.ts

@@ -1,14 +1,18 @@
 export * from "./validators/common/boolean"
 export * from "./validators/common/date"
+export * from "./validators/common/datetime"
 export * from "./validators/common/email"
+export * from "./validators/common/file"
 export * from "./validators/common/id"
 export * from "./validators/common/number"
 export * from "./validators/common/password"
 export * from "./validators/common/text"
+export * from "./validators/common/time"
 export * from "./validators/common/url"
 export * from "./validators/taiwan/business-id"
 export * from "./validators/taiwan/national-id"
 export * from "./validators/taiwan/mobile"
+export * from "./validators/taiwan/postal-code"
 export * from "./validators/taiwan/tel"
 export * from "./validators/taiwan/fax"
 export * from "./config"

package/src/validators/common/boolean.ts

@@ -1,7 +1,26 @@
+/**
+ * @fileoverview Boolean validator for Zod Kit
+ *
+ * Provides flexible boolean validation with support for various truthy/falsy values,
+ * strict mode validation, and comprehensive transformation options.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
 import { z, ZodBoolean, ZodNullable, ZodType } from "zod"
 import { t } from "../../i18n"
 import { getLocale, type Locale } from "../../config"
 
+/**
+ * Type definition for boolean validation error messages
+ *
+ * @interface BooleanMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [shouldBeTrue] - Message when value should be true but isn't
+ * @property {string} [shouldBeFalse] - Message when value should be false but isn't
+ * @property {string} [invalid] - Message when value is not a valid boolean
+ */
 export type BooleanMessages = {
   required?: string
   shouldBeTrue?: string
@@ -9,6 +28,21 @@ export type BooleanMessages = {
   invalid?: string
 }
 
+/**
+ * Configuration options for boolean validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface BooleanOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {boolean | null} [defaultValue] - Default value when input is empty
+ * @property {boolean} [shouldBe] - Specific boolean value that must be matched
+ * @property {unknown[]} [truthyValues] - Array of values that should be treated as true
+ * @property {unknown[]} [falsyValues] - Array of values that should be treated as false
+ * @property {boolean} [strict=false] - If true, only accepts actual boolean values
+ * @property {Function} [transform] - Custom transformation function for boolean values
+ * @property {Record<Locale, BooleanMessages>} [i18n] - Custom error messages for different locales
+ */
 export type BooleanOptions<IsRequired extends boolean = true> = {
   required?: IsRequired
   defaultValue?: IsRequired extends true ? boolean : boolean | null
@@ -20,8 +54,68 @@ export type BooleanOptions<IsRequired extends boolean = true> = {
   i18n?: Record<Locale, BooleanMessages>
 }
 
+/**
+ * Type alias for boolean validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef BooleanSchema
+ * @description Returns ZodBoolean if required, ZodNullable<ZodBoolean> if optional
+ */
 export type BooleanSchema<IsRequired extends boolean> = IsRequired extends true ? ZodBoolean : ZodNullable<ZodBoolean>
 
+/**
+ * Creates a Zod schema for boolean validation with flexible value interpretation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {BooleanOptions<IsRequired>} [options] - Configuration options for boolean validation
+ * @returns {BooleanSchema<IsRequired>} Zod schema for boolean validation
+ *
+ * @description
+ * Creates a flexible boolean validator that can interpret various values as true/false,
+ * supports strict mode for type safety, and provides comprehensive transformation options.
+ *
+ * Features:
+ * - Flexible truthy/falsy value interpretation
+ * - Strict mode for type safety
+ * - Custom transformation functions
+ * - Specific boolean value requirements
+ * - Comprehensive internationalization
+ * - Default value support
+ *
+ * @example
+ * ```typescript
+ * // Basic boolean validation
+ * const basicSchema = boolean()
+ * basicSchema.parse(true) // ✓ Valid
+ * basicSchema.parse("true") // ✓ Valid (converted to true)
+ *
+ * // Strict mode (only actual booleans)
+ * const strictSchema = boolean({ strict: true })
+ * strictSchema.parse(true) // ✓ Valid
+ * strictSchema.parse("true") // ✗ Invalid
+ *
+ * // Must be true
+ * const mustBeTrueSchema = boolean({ shouldBe: true })
+ * mustBeTrueSchema.parse(true) // ✓ Valid
+ * mustBeTrueSchema.parse(false) // ✗ Invalid
+ *
+ * // Custom truthy/falsy values
+ * const customSchema = boolean({
+ *   truthyValues: ["yes", "on", 1],
+ *   falsyValues: ["no", "off", 0]
+ * })
+ * customSchema.parse("yes") // ✓ Valid (converted to true)
+ *
+ * // Optional with default
+ * const optionalSchema = boolean({
+ *   required: false,
+ *   defaultValue: false
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link BooleanOptions} for all available configuration options
+ */
 export function boolean<IsRequired extends boolean = true>(options?: BooleanOptions<IsRequired>): BooleanSchema<IsRequired> {
   const {
     required = true,

package/src/validators/common/date.ts

@@ -1,3 +1,13 @@
+/**
+ * @fileoverview Date validator for Zod Kit
+ *
+ * Provides comprehensive date validation with format support, range validation,
+ * temporal constraints, and weekday/weekend filtering using dayjs library.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
 import { z, ZodNullable, ZodString } from "zod"
 import { t } from "../../i18n"
 import { getLocale, type Locale } from "../../config"
@@ -8,12 +18,33 @@ import isSameOrBefore from "dayjs/plugin/isSameOrBefore"
 import isToday from "dayjs/plugin/isToday"
 import weekday from "dayjs/plugin/weekday"
 
+// Initialize dayjs plugins for extended date functionality
 dayjs.extend(isSameOrAfter)
 dayjs.extend(isSameOrBefore)
 dayjs.extend(customParseFormat)
 dayjs.extend(isToday)
 dayjs.extend(weekday)
 
+/**
+ * Type definition for date validation error messages
+ *
+ * @interface DateMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when date is invalid
+ * @property {string} [format] - Message when date doesn't match expected format
+ * @property {string} [min] - Message when date is before minimum allowed
+ * @property {string} [max] - Message when date is after maximum allowed
+ * @property {string} [includes] - Message when date string doesn't contain required text
+ * @property {string} [excludes] - Message when date string contains forbidden text
+ * @property {string} [past] - Message when date must be in the past
+ * @property {string} [future] - Message when date must be in the future
+ * @property {string} [today] - Message when date must be today
+ * @property {string} [notToday] - Message when date must not be today
+ * @property {string} [weekday] - Message when date must be a weekday
+ * @property {string} [notWeekday] - Message when date must not be a weekday
+ * @property {string} [weekend] - Message when date must be a weekend
+ * @property {string} [notWeekend] - Message when date must not be a weekend
+ */
 export type DateMessages = {
   required?: string
   invalid?: string
@@ -32,6 +63,28 @@ export type DateMessages = {
   notWeekend?: string
 }
 
+/**
+ * Configuration options for date validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface DateOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {string} [min] - Minimum allowed date (in same format as specified)
+ * @property {string} [max] - Maximum allowed date (in same format as specified)
+ * @property {string} [format="YYYY-MM-DD"] - Date format for parsing and validation
+ * @property {string} [includes] - String that must be included in the date
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {boolean} [mustBePast] - Whether date must be in the past
+ * @property {boolean} [mustBeFuture] - Whether date must be in the future
+ * @property {boolean} [mustBeToday] - Whether date must be today
+ * @property {boolean} [mustNotBeToday] - Whether date must not be today
+ * @property {boolean} [weekdaysOnly] - Whether date must be a weekday (Monday-Friday)
+ * @property {boolean} [weekendsOnly] - Whether date must be a weekend (Saturday-Sunday)
+ * @property {Function} [transform] - Custom transformation function for date strings
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, DateMessages>} [i18n] - Custom error messages for different locales
+ */
 export type DateOptions<IsRequired extends boolean = true> = {
   required?: IsRequired
   min?: string
@@ -50,8 +103,83 @@ export type DateOptions<IsRequired extends boolean = true> = {
   i18n?: Record<Locale, DateMessages>
 }
 
+/**
+ * Type alias for date validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef DateSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 export type DateSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
+/**
+ * Creates a Zod schema for date validation with temporal constraints
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {DateOptions<IsRequired>} [options] - Configuration options for date validation
+ * @returns {DateSchema<IsRequired>} Zod schema for date validation
+ *
+ * @description
+ * Creates a comprehensive date validator with format support, range validation,
+ * temporal constraints, and weekday/weekend filtering using dayjs library.
+ *
+ * Features:
+ * - Flexible date format parsing (default: YYYY-MM-DD)
+ * - Range validation (min/max dates)
+ * - Temporal validation (past/future/today)
+ * - Weekday/weekend filtering
+ * - Content inclusion/exclusion
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ * - Strict date parsing with format validation
+ *
+ * @example
+ * ```typescript
+ * // Basic date validation (YYYY-MM-DD)
+ * const basicSchema = date()
+ * basicSchema.parse("2024-03-15") // ✓ Valid
+ * basicSchema.parse("2024-13-01") // ✗ Invalid (month 13)
+ *
+ * // Custom format
+ * const customFormatSchema = date({ format: "DD/MM/YYYY" })
+ * customFormatSchema.parse("15/03/2024") // ✓ Valid
+ * customFormatSchema.parse("2024-03-15") // ✗ Invalid (wrong format)
+ *
+ * // Date range validation
+ * const rangeSchema = date({
+ *   min: "2024-01-01",
+ *   max: "2024-12-31"
+ * })
+ * rangeSchema.parse("2024-06-15") // ✓ Valid
+ * rangeSchema.parse("2023-12-31") // ✗ Invalid (before min)
+ *
+ * // Future dates only
+ * const futureSchema = date({ mustBeFuture: true })
+ * futureSchema.parse("2030-01-01") // ✓ Valid (assuming current date < 2030)
+ * futureSchema.parse("2020-01-01") // ✗ Invalid (past date)
+ *
+ * // Weekdays only (Monday-Friday)
+ * const weekdaySchema = date({ weekdaysOnly: true })
+ * weekdaySchema.parse("2024-03-15") // ✓ Valid (if Friday)
+ * weekdaySchema.parse("2024-03-16") // ✗ Invalid (if Saturday)
+ *
+ * // Business date validation
+ * const businessSchema = date({
+ *   format: "YYYY-MM-DD",
+ *   mustBeFuture: true,
+ *   weekdaysOnly: true
+ * })
+ *
+ * // Optional with default
+ * const optionalSchema = date({
+ *   required: false,
+ *   defaultValue: "2024-01-01"
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link DateOptions} for all available configuration options
+ */
 export function date<IsRequired extends boolean = true>(options?: DateOptions<IsRequired>): DateSchema<IsRequired> {
   const {
     required = true,