@hy_ong/zod-kit 0.0.4 → 0.0.6

package/src/validators/common/boolean.ts

@@ -0,0 +1,191 @@
+/**
+ * @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
+  shouldBeFalse?: string
+  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
+  shouldBe?: boolean
+  truthyValues?: unknown[]
+  falsyValues?: unknown[]
+  strict?: boolean
+  transform?: (value: boolean) => boolean
+  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,
+    defaultValue = null,
+    shouldBe,
+    truthyValues = [true, "true", 1, "1", "yes", "on"],
+    falsyValues = [false, "false", 0, "0", "no", "off"],
+    strict = false,
+    transform,
+    i18n,
+  } = options ?? {}
+
+  // Helper function to get custom message or fallback to default i18n
+  const getMessage = (key: keyof BooleanMessages, params?: Record<string, any>) => {
+    if (i18n) {
+      const currentLocale = getLocale()
+      const customMessages = i18n[currentLocale]
+      if (customMessages && customMessages[key]) {
+        const template = customMessages[key]!
+        return template.replace(/\$\{(\w+)}/g, (_, k) => params?.[k] ?? "")
+      }
+    }
+    return t(`common.boolean.${key}`, params)
+  }
+
+  let result: ZodType = z.preprocess(
+    (val) => {
+      if (val === "" || val === undefined || val === null) return defaultValue
+
+      if (strict && typeof val !== "boolean" && val !== null) {
+        return val // Let it fail in validation
+      }
+
+      // Check truthy values
+      if (truthyValues.includes(val)) {
+        let processed = true
+        if (transform) processed = transform(processed)
+        return processed
+      }
+
+      // Check falsy values
+      if (falsyValues.includes(val)) {
+        let processed = false
+        if (transform) processed = transform(processed)
+        return processed
+      }
+
+      return val
+    },
+    z.union([z.literal(true), z.literal(false), z.literal(null)])
+  )
+
+  if (required && defaultValue === null) {
+    result = result.refine((val) => val !== null, { message: getMessage("required") })
+  }
+
+  if (shouldBe === true) {
+    result = result.refine((val) => val === true, { message: getMessage("shouldBeTrue") })
+  } else if (shouldBe === false) {
+    result = result.refine((val) => val === false, { message: getMessage("shouldBeFalse") })
+  }
+
+  if (strict) {
+    result = result.refine(
+      (val) => {
+        return val === null || typeof val === "boolean"
+      },
+      { message: getMessage("invalid") }
+    )
+  }
+
+  return result as IsRequired extends true ? ZodBoolean : ZodNullable<ZodBoolean>
+}

package/src/validators/common/date.ts

@@ -0,0 +1,299 @@
+/**
+ * @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"
+import dayjs from "dayjs"
+import customParseFormat from "dayjs/plugin/customParseFormat"
+import isSameOrAfter from "dayjs/plugin/isSameOrAfter"
+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
+  format?: string
+  min?: string
+  max?: string
+  includes?: string
+  excludes?: string
+  past?: string
+  future?: string
+  today?: string
+  notToday?: string
+  weekday?: string
+  notWeekday?: string
+  weekend?: string
+  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
+  max?: string
+  format?: string
+  includes?: string
+  excludes?: string | string[]
+  mustBePast?: boolean
+  mustBeFuture?: boolean
+  mustBeToday?: boolean
+  mustNotBeToday?: boolean
+  weekdaysOnly?: boolean
+  weekendsOnly?: boolean
+  transform?: (value: string) => string
+  defaultValue?: IsRequired extends true ? string : string | null
+  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,
+    min,
+    max,
+    format = "YYYY-MM-DD",
+    includes,
+    excludes,
+    mustBePast,
+    mustBeFuture,
+    mustBeToday,
+    mustNotBeToday,
+    weekdaysOnly,
+    weekendsOnly,
+    transform,
+    defaultValue = null,
+    i18n,
+  } = options ?? {}
+
+  const actualDefaultValue = defaultValue ?? (required ? "" : null)
+
+  // Helper function to get custom message or fallback to default i18n
+  const getMessage = (key: keyof DateMessages, params?: Record<string, any>) => {
+    if (i18n) {
+      const currentLocale = getLocale()
+      const customMessages = i18n[currentLocale]
+      if (customMessages && customMessages[key]) {
+        const template = customMessages[key]!
+        return template.replace(/\$\{(\w+)}/g, (_, k) => params?.[k] ?? "")
+      }
+    }
+    return t(`common.date.${key}`, params)
+  }
+
+  // Preprocessing function with transformations
+  const preprocessFn = (val: unknown) => {
+    if (val === "" || val === null || val === undefined) {
+      return actualDefaultValue
+    }
+
+    let processed = String(val).trim()
+
+    if (transform) {
+      processed = transform(processed)
+    }
+
+    return processed
+  }
+
+  const baseSchema = required ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
+
+  const schema = baseSchema.refine((val) => {
+    if (val === null) return true
+
+    // Required check
+    if (required && (val === "" || val === "null" || val === "undefined")) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
+    }
+
+    // Format validation
+    if (val !== null && !dayjs(val, format, true).isValid()) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("format", { format }), path: [] }])
+    }
+
+    const dateObj = dayjs(val, format)
+
+    // Range checks
+    if (val !== null && min !== undefined && !dateObj.isSameOrAfter(dayjs(min, format))) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("min", { min }), path: [] }])
+    }
+    if (val !== null && max !== undefined && !dateObj.isSameOrBefore(dayjs(max, format))) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("max", { max }), path: [] }])
+    }
+
+    // String content checks
+    if (val !== null && includes !== undefined && !val.includes(includes)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("includes", { includes }), path: [] }])
+    }
+    if (val !== null && excludes !== undefined) {
+      const excludeList = Array.isArray(excludes) ? excludes : [excludes]
+      for (const exclude of excludeList) {
+        if (val.includes(exclude)) {
+          throw new z.ZodError([{ code: "custom", message: getMessage("excludes", { excludes: exclude }), path: [] }])
+        }
+      }
+    }
+
+    // Time-based validations
+    const today = dayjs().startOf('day')
+    const targetDate = dateObj.startOf('day')
+
+    if (val !== null && mustBePast && !targetDate.isBefore(today)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("past"), path: [] }])
+    }
+    if (val !== null && mustBeFuture && !targetDate.isAfter(today)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("future"), path: [] }])
+    }
+    if (val !== null && mustBeToday && !targetDate.isSame(today)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("today"), path: [] }])
+    }
+    if (val !== null && mustNotBeToday && targetDate.isSame(today)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("notToday"), path: [] }])
+    }
+
+    // Weekday/weekend validations
+    if (val !== null && weekdaysOnly && (dateObj.day() === 0 || dateObj.day() === 6)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("weekday"), path: [] }])
+    }
+    if (val !== null && weekendsOnly && dateObj.day() !== 0 && dateObj.day() !== 6) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("weekend"), path: [] }])
+    }
+
+    return true
+  })
+
+  return schema as unknown as DateSchema<IsRequired>
+}