@hy_ong/zod-kit 0.0.5 → 0.0.6

package/src/validators/common/email.ts

@@ -1,7 +1,31 @@
+/**
+ * @fileoverview Email validator for Zod Kit
+ *
+ * Provides comprehensive email validation with domain filtering, business email
+ * validation, disposable email detection, and extensive customization options.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
 import { z, ZodNullable, ZodString } from "zod"
 import { t } from "../../i18n"
 import { getLocale, type Locale } from "../../config"
 
+/**
+ * Type definition for email validation error messages
+ *
+ * @interface EmailMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when email format is invalid
+ * @property {string} [minLength] - Message when email is too short
+ * @property {string} [maxLength] - Message when email is too long
+ * @property {string} [includes] - Message when email doesn't contain required string
+ * @property {string} [domain] - Message when email domain is not allowed
+ * @property {string} [domainBlacklist] - Message when email domain is blacklisted
+ * @property {string} [businessOnly] - Message when free email providers are not allowed
+ * @property {string} [noDisposable] - Message when disposable email addresses are not allowed
+ */
 export type EmailMessages = {
   required?: string
   invalid?: string
@@ -14,6 +38,27 @@ export type EmailMessages = {
   noDisposable?: string
 }
 
+/**
+ * Configuration options for email validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface EmailOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {string | string[]} [domain] - Allowed domain(s) for email addresses
+ * @property {string[]} [domainBlacklist] - Domains that are not allowed
+ * @property {number} [minLength] - Minimum length of email address
+ * @property {number} [maxLength] - Maximum length of email address
+ * @property {string} [includes] - String that must be included in the email
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {boolean} [allowSubdomains=true] - Whether to allow subdomains in domain validation
+ * @property {boolean} [businessOnly=false] - If true, reject common free email providers
+ * @property {boolean} [noDisposable=false] - If true, reject disposable email addresses
+ * @property {boolean} [lowercase=true] - Whether to convert email to lowercase
+ * @property {Function} [transform] - Custom transformation function for email strings
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, EmailMessages>} [i18n] - Custom error messages for different locales
+ */
 export type EmailOptions<IsRequired extends boolean = true> = {
   required?: IsRequired
   domain?: string | string[]
@@ -31,8 +76,76 @@ export type EmailOptions<IsRequired extends boolean = true> = {
   i18n?: Record<Locale, EmailMessages>
 }
 
+/**
+ * Type alias for email validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef EmailSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 export type EmailSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
+/**
+ * Creates a Zod schema for email validation with comprehensive filtering options
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {EmailOptions<IsRequired>} [options] - Configuration options for email validation
+ * @returns {EmailSchema<IsRequired>} Zod schema for email validation
+ *
+ * @description
+ * Creates a comprehensive email validator with domain filtering, business email
+ * validation, disposable email detection, and extensive customization options.
+ *
+ * Features:
+ * - RFC-compliant email format validation
+ * - Domain whitelist/blacklist support
+ * - Business email validation (excludes free providers)
+ * - Disposable email detection
+ * - Subdomain support configuration
+ * - Length validation
+ * - Content inclusion/exclusion
+ * - Automatic lowercase conversion
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic email validation
+ * const basicSchema = email()
+ * basicSchema.parse("user@example.com") // ✓ Valid
+ *
+ * // Domain restriction
+ * const domainSchema = email({
+ *   domain: ["company.com", "organization.org"]
+ * })
+ * domainSchema.parse("user@company.com") // ✓ Valid
+ * domainSchema.parse("user@gmail.com") // ✗ Invalid
+ *
+ * // Business emails only (no free providers)
+ * const businessSchema = email({ businessOnly: true })
+ * businessSchema.parse("user@company.com") // ✓ Valid
+ * businessSchema.parse("user@gmail.com") // ✗ Invalid
+ *
+ * // No disposable emails
+ * const noDisposableSchema = email({ noDisposable: true })
+ * noDisposableSchema.parse("user@company.com") // ✓ Valid
+ * noDisposableSchema.parse("user@10minutemail.com") // ✗ Invalid
+ *
+ * // Domain blacklist
+ * const blacklistSchema = email({
+ *   domainBlacklist: ["spam.com", "blocked.org"]
+ * })
+ *
+ * // Optional with default
+ * const optionalSchema = email({
+ *   required: false,
+ *   defaultValue: null
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link EmailOptions} for all available configuration options
+ */
 export function email<IsRequired extends boolean = true>(options?: EmailOptions<IsRequired>): EmailSchema<IsRequired> {
   const {
     required = true,

package/src/validators/common/file.ts

@@ -0,0 +1,384 @@
+/**
+ * @fileoverview File validator for Zod Kit
+ *
+ * Provides comprehensive file validation with MIME type filtering, size validation,
+ * extension validation, and extensive customization options.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+import { z, ZodNullable, ZodType } from "zod"
+import { t } from "../../i18n"
+import { getLocale, type Locale } from "../../config"
+
+/**
+ * Type definition for file validation error messages
+ *
+ * @interface FileMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when file format is invalid
+ * @property {string} [size] - Message when file size exceeds limit
+ * @property {string} [minSize] - Message when file size is too small
+ * @property {string} [maxSize] - Message when file size exceeds maximum
+ * @property {string} [type] - Message when file type is not allowed
+ * @property {string} [extension] - Message when file extension is not allowed
+ * @property {string} [extensionBlacklist] - Message when file extension is blacklisted
+ * @property {string} [name] - Message when file name doesn't match pattern
+ * @property {string} [nameBlacklist] - Message when file name matches blacklisted pattern
+ * @property {string} [imageOnly] - Message when only image files are allowed
+ * @property {string} [documentOnly] - Message when only document files are allowed
+ * @property {string} [videoOnly] - Message when only video files are allowed
+ * @property {string} [audioOnly] - Message when only audio files are allowed
+ * @property {string} [archiveOnly] - Message when only archive files are allowed
+ */
+export type FileMessages = {
+  required?: string
+  invalid?: string
+  size?: string
+  minSize?: string
+  maxSize?: string
+  type?: string
+  extension?: string
+  extensionBlacklist?: string
+  name?: string
+  nameBlacklist?: string
+  imageOnly?: string
+  documentOnly?: string
+  videoOnly?: string
+  audioOnly?: string
+  archiveOnly?: string
+}
+
+/**
+ * Configuration options for file validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface FileOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {number} [maxSize] - Maximum file size in bytes
+ * @property {number} [minSize] - Minimum file size in bytes
+ * @property {string | string[]} [type] - Allowed MIME type(s)
+ * @property {string[]} [typeBlacklist] - MIME types that are not allowed
+ * @property {string | string[]} [extension] - Allowed file extension(s)
+ * @property {string[]} [extensionBlacklist] - File extensions that are not allowed
+ * @property {RegExp | string} [namePattern] - Pattern that file name must match
+ * @property {RegExp | string | Array<RegExp | string>} [nameBlacklist] - Pattern(s) that file name must not match
+ * @property {boolean} [imageOnly=false] - If true, only allow image files
+ * @property {boolean} [documentOnly=false] - If true, only allow document files
+ * @property {boolean} [videoOnly=false] - If true, only allow video files
+ * @property {boolean} [audioOnly=false] - If true, only allow audio files
+ * @property {boolean} [archiveOnly=false] - If true, only allow archive files
+ * @property {boolean} [caseSensitive=false] - Whether extension matching is case-sensitive
+ * @property {Function} [transform] - Custom transformation function for File objects
+ * @property {File | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, FileMessages>} [i18n] - Custom error messages for different locales
+ */
+export type FileOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  maxSize?: number
+  minSize?: number
+  type?: string | string[]
+  typeBlacklist?: string[]
+  extension?: string | string[]
+  extensionBlacklist?: string[]
+  namePattern?: RegExp | string
+  nameBlacklist?: RegExp | string | Array<RegExp | string>
+  imageOnly?: boolean
+  documentOnly?: boolean
+  videoOnly?: boolean
+  audioOnly?: boolean
+  archiveOnly?: boolean
+  caseSensitive?: boolean
+  transform?: (value: File) => File
+  defaultValue?: IsRequired extends true ? File : File | null
+  i18n?: Record<Locale, FileMessages>
+}
+
+/**
+ * Type alias for file validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef FileSchema
+ * @description Returns ZodType<File> if required, ZodNullable<ZodType<File>> if optional
+ */
+export type FileSchema<IsRequired extends boolean> = IsRequired extends true ? ZodType<File> : ZodNullable<ZodType<File>>
+
+/**
+ * Creates a Zod schema for file validation with comprehensive filtering options
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {FileOptions<IsRequired>} [options] - Configuration options for file validation
+ * @returns {FileSchema<IsRequired>} Zod schema for file validation
+ *
+ * @description
+ * Creates a comprehensive file validator with MIME type filtering, size validation,
+ * extension validation, and extensive customization options.
+ *
+ * Features:
+ * - File size validation (min/max)
+ * - MIME type whitelist/blacklist support
+ * - File extension whitelist/blacklist support
+ * - File name pattern validation
+ * - Predefined file category filters (image, document, video, audio, archive)
+ * - Case-sensitive/insensitive extension matching
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic file validation
+ * const basicSchema = file()
+ * basicSchema.parse(new File(["content"], "test.txt"))
+ *
+ * // Size restrictions
+ * const sizeSchema = file({
+ *   maxSize: 1024 * 1024, // 1MB
+ *   minSize: 1024 // 1KB
+ * })
+ *
+ * // Extension restrictions
+ * const imageSchema = file({
+ *   extension: [".jpg", ".png", ".gif"],
+ *   maxSize: 5 * 1024 * 1024 // 5MB
+ * })
+ *
+ * // MIME type restrictions
+ * const documentSchema = file({
+ *   type: ["application/pdf", "application/msword"],
+ *   maxSize: 10 * 1024 * 1024 // 10MB
+ * })
+ *
+ * // Image files only
+ * const imageOnlySchema = file({ imageOnly: true })
+ *
+ * // Document files only
+ * const docOnlySchema = file({ documentOnly: true })
+ *
+ * // Name pattern validation
+ * const patternSchema = file({
+ *   namePattern: /^[a-zA-Z0-9_-]+\.(pdf|doc|docx)$/,
+ *   maxSize: 5 * 1024 * 1024
+ * })
+ *
+ * // Optional with default
+ * const optionalSchema = file({
+ *   required: false,
+ *   defaultValue: null
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link FileOptions} for all available configuration options
+ */
+export function file<IsRequired extends boolean = true>(options?: FileOptions<IsRequired>): FileSchema<IsRequired> {
+  const {
+    required = true,
+    maxSize,
+    minSize,
+    type,
+    typeBlacklist,
+    extension,
+    extensionBlacklist,
+    namePattern,
+    nameBlacklist,
+    imageOnly = false,
+    documentOnly = false,
+    videoOnly = false,
+    audioOnly = false,
+    archiveOnly = false,
+    caseSensitive = false,
+    transform,
+    defaultValue,
+    i18n,
+  } = options ?? {}
+
+  // Helper function to get custom message or fallback to default i18n
+  const getMessage = (key: keyof FileMessages, 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.file.${key}`, params)
+  }
+
+  // Predefined file type categories
+  const imageTypes = ["image/jpeg", "image/jpg", "image/png", "image/gif", "image/webp", "image/svg+xml", "image/bmp", "image/tiff"]
+  const documentTypes = [
+    "application/pdf",
+    "application/msword",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/vnd.ms-excel",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.ms-powerpoint",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    "text/plain",
+    "text/csv",
+  ]
+  const videoTypes = ["video/mp4", "video/mpeg", "video/quicktime", "video/x-msvideo", "video/x-ms-wmv", "video/webm", "video/ogg"]
+  const audioTypes = ["audio/mpeg", "audio/wav", "audio/ogg", "audio/aac", "audio/webm", "audio/mp3", "audio/x-wav"]
+  const archiveTypes = ["application/zip", "application/x-rar-compressed", "application/x-7z-compressed", "application/x-tar", "application/gzip"]
+
+  const actualDefaultValue = defaultValue ?? null
+
+  const baseSchema = z.preprocess(
+    (val) => {
+      if (val === "" || val === null || val === undefined) {
+        return actualDefaultValue
+      }
+
+      if (!(val instanceof File)) {
+        return val
+      }
+
+      let processed = val
+
+      if (transform) {
+        processed = transform(processed)
+      }
+
+      return processed
+    },
+    z.union([z.instanceof(File).refine(() => true, { message: getMessage("invalid") }), z.null()])
+  )
+
+  const schema = baseSchema
+    .refine((val) => required === false || val !== null, {
+      message: getMessage("required"),
+    })
+    .refine((val) => val === null || val instanceof File, {
+      message: getMessage("invalid"),
+    })
+    .refine((val) => val === null || minSize === undefined || val.size >= minSize, {
+      message: getMessage("minSize", { minSize: formatFileSize(minSize || 0) }),
+    })
+    .refine((val) => val === null || maxSize === undefined || val.size <= maxSize, {
+      message: getMessage("maxSize", { maxSize: formatFileSize(maxSize || 0) }),
+    })
+    .refine((val) => val === null || !imageOnly || imageTypes.includes(val.type), {
+      message: getMessage("imageOnly"),
+    })
+    .refine((val) => val === null || !documentOnly || documentTypes.includes(val.type), {
+      message: getMessage("documentOnly"),
+    })
+    .refine((val) => val === null || !videoOnly || videoTypes.includes(val.type), {
+      message: getMessage("videoOnly"),
+    })
+    .refine((val) => val === null || !audioOnly || audioTypes.includes(val.type), {
+      message: getMessage("audioOnly"),
+    })
+    .refine((val) => val === null || !archiveOnly || archiveTypes.includes(val.type), {
+      message: getMessage("archiveOnly"),
+    })
+    .refine(
+      (val) => {
+        if (val === null || !typeBlacklist || typeBlacklist.length === 0) return true
+        return !typeBlacklist.includes(val.type)
+      },
+      {
+        message: getMessage("type", { type: typeBlacklist?.join(", ") || "" }),
+      }
+    )
+    .refine(
+      (val) => {
+        if (val === null || type === undefined) return true
+        const allowedTypes = Array.isArray(type) ? type : [type]
+        return allowedTypes.includes(val.type)
+      },
+      {
+        message: getMessage("type", { type: Array.isArray(type) ? type.join(", ") : type || "" }),
+      }
+    )
+    .refine(
+      (val) => {
+        if (val === null || extensionBlacklist === undefined || extensionBlacklist.length === 0) return true
+        const fileExtension = getFileExtension(val.name, caseSensitive)
+        const normalizedBlacklist = extensionBlacklist.map((ext) => normalizeExtension(ext, caseSensitive))
+        return !normalizedBlacklist.includes(fileExtension)
+      },
+      {
+        message: getMessage("extensionBlacklist", { extension: extensionBlacklist?.join(", ") || "" }),
+      }
+    )
+    .refine(
+      (val) => {
+        if (val === null || extension === undefined) return true
+        const fileName = val.name
+        const fileExtension = getFileExtension(fileName, caseSensitive)
+        const allowedExtensions = Array.isArray(extension) ? extension : [extension]
+        const normalizedExtensions = allowedExtensions.map((ext) => normalizeExtension(ext, caseSensitive))
+        return normalizedExtensions.includes(fileExtension)
+      },
+      {
+        message: getMessage("extension", { extension: Array.isArray(extension) ? extension.join(", ") : extension || "" }),
+      }
+    )
+    .refine(
+      (val) => {
+        if (val === null || namePattern === undefined) return true
+        const pattern = typeof namePattern === "string" ? new RegExp(namePattern) : namePattern
+        return pattern.test(val.name)
+      },
+      {
+        message: getMessage("name", { pattern: namePattern?.toString() || "" }),
+      }
+    )
+    .refine(
+      (val) => {
+        if (val === null || nameBlacklist === undefined) return true
+        const blacklistPatterns = Array.isArray(nameBlacklist) ? nameBlacklist : [nameBlacklist]
+        for (const blacklistPattern of blacklistPatterns) {
+          const pattern = typeof blacklistPattern === "string" ? new RegExp(blacklistPattern) : blacklistPattern
+          if (pattern.test(val.name)) {
+            return false
+          }
+        }
+        return true
+      },
+      {
+        message: getMessage("nameBlacklist", { pattern: "" }),
+      }
+    )
+
+  return schema as unknown as FileSchema<IsRequired>
+}
+
+/**
+ * Helper function to get file extension
+ */
+function getFileExtension(fileName: string, caseSensitive: boolean): string {
+  const lastDotIndex = fileName.lastIndexOf(".")
+  if (lastDotIndex === -1) return ""
+
+  const extension = fileName.substring(lastDotIndex)
+  return caseSensitive ? extension : extension.toLowerCase()
+}
+
+/**
+ * Helper function to normalize extension for comparison
+ */
+function normalizeExtension(extension: string, caseSensitive: boolean): string {
+  const normalized = extension.startsWith(".") ? extension : `.${extension}`
+  return caseSensitive ? normalized : normalized.toLowerCase()
+}
+
+/**
+ * Helper function to format file size in human-readable format
+ */
+function formatFileSize(bytes: number): string {
+  const units = ["B", "KB", "MB", "GB", "TB"]
+  let size = bytes
+  let unitIndex = 0
+
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024
+    unitIndex++
+  }
+
+  return `${Math.round(size * 100) / 100} ${units[unitIndex]}`
+}