@hy_ong/zod-kit 0.0.5 → 0.0.6

package/src/validators/common/id.ts

@@ -1,7 +1,39 @@
+/**
+ * @fileoverview ID validator for Zod Kit
+ *
+ * Provides comprehensive ID validation with support for multiple ID formats,
+ * auto-detection, custom patterns, and flexible validation 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 ID validation error messages
+ *
+ * @interface IdMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when ID format is invalid
+ * @property {string} [minLength] - Message when ID is too short
+ * @property {string} [maxLength] - Message when ID is too long
+ * @property {string} [numeric] - Message when numeric ID format is invalid
+ * @property {string} [uuid] - Message when UUID format is invalid
+ * @property {string} [objectId] - Message when MongoDB ObjectId format is invalid
+ * @property {string} [nanoid] - Message when Nano ID format is invalid
+ * @property {string} [snowflake] - Message when Snowflake ID format is invalid
+ * @property {string} [cuid] - Message when CUID format is invalid
+ * @property {string} [ulid] - Message when ULID format is invalid
+ * @property {string} [shortid] - Message when ShortId format is invalid
+ * @property {string} [customFormat] - Message when custom regex format is invalid
+ * @property {string} [includes] - Message when ID doesn't contain required string
+ * @property {string} [excludes] - Message when ID contains forbidden string
+ * @property {string} [startsWith] - Message when ID doesn't start with required string
+ * @property {string} [endsWith] - Message when ID doesn't end with required string
+ */
 export type IdMessages = {
   required?: string
   invalid?: string
@@ -22,17 +54,54 @@ export type IdMessages = {
   endsWith?: string
 }
 
+/**
+ * Supported ID types for validation
+ *
+ * @typedef {string} IdType
+ *
+ * Available types:
+ * - numeric: Pure numeric IDs (1, 123, 999999)
+ * - uuid: UUID v4 format (xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx)
+ * - objectId: MongoDB ObjectId (24-character hexadecimal)
+ * - nanoid: Nano ID format (21-character URL-safe)
+ * - snowflake: Twitter Snowflake (19-digit number)
+ * - cuid: CUID format (25-character starting with 'c')
+ * - ulid: ULID format (26-character case-insensitive)
+ * - shortid: ShortId format (7-14 character URL-safe)
+ * - auto: Auto-detect format from the value
+ */
 export type IdType =
-  | "numeric" // 純數字 ID (1, 123, 999999)
-  | "uuid" // UUID v4 格式
-  | "objectId" // MongoDB ObjectId (24位16進制)
+  | "numeric" // Pure numeric IDs (1, 123, 999999)
+  | "uuid" // UUID v4 format
+  | "objectId" // MongoDB ObjectId (24-character hexadecimal)
   | "nanoid" // Nano ID
-  | "snowflake" // Twitter Snowflake (19位數字)
-  | "cuid" // CUID 格式
-  | "ulid" // ULID 格式
-  | "shortid" // ShortId 格式
-  | "auto" // 自動檢測格式
+  | "snowflake" // Twitter Snowflake (19-digit number)
+  | "cuid" // CUID format
+  | "ulid" // ULID format
+  | "shortid" // ShortId format
+  | "auto" // Auto-detect format
 
+/**
+ * Configuration options for ID validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface IdOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {IdType} [type="auto"] - Expected ID type or auto-detection
+ * @property {number} [minLength] - Minimum length of ID
+ * @property {number} [maxLength] - Maximum length of ID
+ * @property {IdType[]} [allowedTypes] - Multiple allowed ID types (overrides type)
+ * @property {RegExp} [customRegex] - Custom regex pattern (overrides type validation)
+ * @property {string} [includes] - String that must be included in ID
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {string} [startsWith] - String that ID must start with
+ * @property {string} [endsWith] - String that ID must end with
+ * @property {boolean} [caseSensitive=true] - Whether validation is case-sensitive
+ * @property {Function} [transform] - Custom transformation function for ID
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, IdMessages>} [i18n] - Custom error messages for different locales
+ */
 export type IdOptions<IsRequired extends boolean = true> = {
   required?: IsRequired
   type?: IdType
@@ -50,9 +119,21 @@ export type IdOptions<IsRequired extends boolean = true> = {
   i18n?: Record<Locale, IdMessages>
 }
 
+/**
+ * Type alias for ID validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef IdSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 export type IdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
-// ID 格式的正則表達式
+/**
+ * Regular expression patterns for different ID formats
+ *
+ * @constant {Record<string, RegExp>} ID_PATTERNS
+ * @description Maps each ID type to its corresponding regex pattern
+ */
 const ID_PATTERNS = {
   numeric: /^\d+$/,
   uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
@@ -64,7 +145,26 @@ const ID_PATTERNS = {
   shortid: /^[A-Za-z0-9_-]{7,14}$/,
 } as const
 
-// 檢測 ID 類型（按照特異性排序，避免誤判）
+/**
+ * Detects the ID type of a given value using pattern matching
+ *
+ * @param {string} value - The ID value to analyze
+ * @returns {IdType | null} The detected ID type or null if no pattern matches
+ *
+ * @description
+ * Attempts to identify the ID type by testing against known patterns.
+ * Patterns are ordered by specificity to avoid false positives.
+ * More specific patterns (UUID, ObjectId) are tested before generic ones (numeric, shortid).
+ *
+ * @example
+ * ```typescript
+ * detectIdType("550e8400-e29b-41d4-a716-446655440000") // "uuid"
+ * detectIdType("507f1f77bcf86cd799439011") // "objectId"
+ * detectIdType("V1StGXR8_Z5jdHi6B-myT") // "nanoid"
+ * detectIdType("123456789") // "numeric"
+ * detectIdType("invalid-id") // null
+ * ```
+ */
 const detectIdType = (value: string): IdType | null => {
   // 按優先順序檢查（從最具體到最通用）
   const orderedTypes: Array<[IdType, RegExp]> = [
@@ -86,7 +186,25 @@ const detectIdType = (value: string): IdType | null => {
   return null
 }
 
-// 驗證特定 ID 類型
+/**
+ * Validates if a value matches the specified ID type
+ *
+ * @param {string} value - The ID value to validate
+ * @param {IdType} type - The expected ID type
+ * @returns {boolean} True if the value matches the specified type
+ *
+ * @description
+ * Validates a specific ID type using regex patterns or auto-detection.
+ * For "auto" type, uses detectIdType to check if any known pattern matches.
+ *
+ * @example
+ * ```typescript
+ * validateIdType("123456", "numeric") // true
+ * validateIdType("abc123", "numeric") // false
+ * validateIdType("550e8400-e29b-41d4-a716-446655440000", "uuid") // true
+ * validateIdType("invalid-uuid", "uuid") // false
+ * ```
+ */
 const validateIdType = (value: string, type: IdType): boolean => {
   if (type === "auto") {
     return detectIdType(value) !== null
@@ -95,6 +213,80 @@ const validateIdType = (value: string, type: IdType): boolean => {
   return pattern ? pattern.test(value) : false
 }
 
+/**
+ * Creates a Zod schema for ID validation with comprehensive format support
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IdOptions<IsRequired>} [options] - Configuration options for ID validation
+ * @returns {IdSchema<IsRequired>} Zod schema for ID validation
+ *
+ * @description
+ * Creates a comprehensive ID validator with support for multiple ID formats,
+ * auto-detection, custom patterns, and flexible validation options.
+ *
+ * Features:
+ * - Multiple ID format support (UUID, ObjectId, Snowflake, etc.)
+ * - Auto-detection of ID types
+ * - Custom regex pattern support
+ * - Length validation
+ * - Content validation (includes, excludes, startsWith, endsWith)
+ * - Case sensitivity control
+ * - Multiple allowed types
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect ID format
+ * const autoSchema = id()
+ * autoSchema.parse("550e8400-e29b-41d4-a716-446655440000") // ✓ Valid (UUID)
+ * autoSchema.parse("507f1f77bcf86cd799439011") // ✓ Valid (ObjectId)
+ * autoSchema.parse("123456") // ✓ Valid (numeric)
+ *
+ * // Specific ID type
+ * const uuidSchema = id({ type: "uuid" })
+ * uuidSchema.parse("550e8400-e29b-41d4-a716-446655440000") // ✓ Valid
+ * uuidSchema.parse("invalid-uuid") // ✗ Invalid
+ *
+ * // Multiple allowed types
+ * const multiSchema = id({ allowedTypes: ["uuid", "objectId"] })
+ * multiSchema.parse("550e8400-e29b-41d4-a716-446655440000") // ✓ Valid (UUID)
+ * multiSchema.parse("507f1f77bcf86cd799439011") // ✓ Valid (ObjectId)
+ * multiSchema.parse("123456") // ✗ Invalid (numeric not allowed)
+ *
+ * // Custom regex pattern
+ * const customSchema = id({ customRegex: /^CUST_\d{6}$/ })
+ * customSchema.parse("CUST_123456") // ✓ Valid
+ * customSchema.parse("invalid") // ✗ Invalid
+ *
+ * // Content validation
+ * const prefixSchema = id({
+ *   type: "auto",
+ *   startsWith: "user_",
+ *   minLength: 10
+ * })
+ * prefixSchema.parse("user_123456") // ✓ Valid
+ *
+ * // Case insensitive
+ * const caseInsensitiveSchema = id({
+ *   type: "uuid",
+ *   caseSensitive: false
+ * })
+ * caseInsensitiveSchema.parse("550E8400-E29B-41D4-A716-446655440000") // ✓ Valid
+ *
+ * // Optional with default
+ * const optionalSchema = id({
+ *   required: false,
+ *   defaultValue: null
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link IdOptions} for all available configuration options
+ * @see {@link IdType} for supported ID types
+ * @see {@link detectIdType} for auto-detection logic
+ * @see {@link validateIdType} for type-specific validation
+ */
 export function id<IsRequired extends boolean = true>(options?: IdOptions<IsRequired>): IdSchema<IsRequired> {
   const {
     required = true,
@@ -255,5 +447,25 @@ export function id<IsRequired extends boolean = true>(options?: IdOptions<IsRequ
   return schema as unknown as IdSchema<IsRequired>
 }
 
-// Export utility functions for external use
+/**
+ * Utility functions and constants exported for external use
+ *
+ * @description
+ * These utilities can be used independently for ID validation, type detection,
+ * and pattern matching without creating a full Zod schema.
+ *
+ * @example
+ * ```typescript
+ * import { detectIdType, validateIdType, ID_PATTERNS } from './id'
+ *
+ * // Detect ID type
+ * const type = detectIdType("550e8400-e29b-41d4-a716-446655440000") // "uuid"
+ *
+ * // Validate specific type
+ * const isValid = validateIdType("123456", "numeric") // true
+ *
+ * // Access regex patterns
+ * const uuidPattern = ID_PATTERNS.uuid
+ * ```
+ */
 export { detectIdType, validateIdType, ID_PATTERNS }

package/src/validators/common/number.ts

@@ -1,7 +1,35 @@
+/**
+ * @fileoverview Number validator for Zod Kit
+ *
+ * Provides comprehensive number validation with type constraints, range validation,
+ * precision control, and advanced parsing features including comma-separated numbers.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
 import { z, ZodNullable, ZodNumber } from "zod"
 import { t } from "../../i18n"
 import { getLocale, type Locale } from "../../config"
 
+/**
+ * Type definition for number validation error messages
+ *
+ * @interface NumberMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when value is not a valid number
+ * @property {string} [integer] - Message when integer is required but float provided
+ * @property {string} [float] - Message when float is required but integer provided
+ * @property {string} [min] - Message when number is below minimum value
+ * @property {string} [max] - Message when number exceeds maximum value
+ * @property {string} [positive] - Message when positive number is required
+ * @property {string} [negative] - Message when negative number is required
+ * @property {string} [nonNegative] - Message when non-negative number is required
+ * @property {string} [nonPositive] - Message when non-positive number is required
+ * @property {string} [multipleOf] - Message when number is not a multiple of specified value
+ * @property {string} [finite] - Message when finite number is required
+ * @property {string} [precision] - Message when number has too many decimal places
+ */
 export type NumberMessages = {
   required?: string
   invalid?: string
@@ -18,6 +46,28 @@ export type NumberMessages = {
   precision?: string
 }
 
+/**
+ * Configuration options for number validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface NumberOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {number} [min] - Minimum allowed value
+ * @property {number} [max] - Maximum allowed value
+ * @property {number | null} [defaultValue] - Default value when input is empty
+ * @property {"integer" | "float" | "both"} [type="both"] - Type constraint for the number
+ * @property {boolean} [positive] - Whether number must be positive (> 0)
+ * @property {boolean} [negative] - Whether number must be negative (< 0)
+ * @property {boolean} [nonNegative] - Whether number must be non-negative (>= 0)
+ * @property {boolean} [nonPositive] - Whether number must be non-positive (<= 0)
+ * @property {number} [multipleOf] - Number must be a multiple of this value
+ * @property {number} [precision] - Maximum number of decimal places allowed
+ * @property {boolean} [finite=true] - Whether to reject Infinity and -Infinity
+ * @property {Function} [transform] - Custom transformation function for number values
+ * @property {boolean} [parseCommas=false] - Whether to parse comma-separated numbers (e.g., "1,234")
+ * @property {Record<Locale, NumberMessages>} [i18n] - Custom error messages for different locales
+ */
 export type NumberOptions<IsRequired extends boolean = true> = {
   required?: IsRequired
   min?: number
@@ -36,8 +86,83 @@ export type NumberOptions<IsRequired extends boolean = true> = {
   i18n?: Record<Locale, NumberMessages>
 }
 
+/**
+ * Type alias for number validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef NumberSchema
+ * @description Returns ZodNumber if required, ZodNullable<ZodNumber> if optional
+ */
 export type NumberSchema<IsRequired extends boolean> = IsRequired extends true ? ZodNumber : ZodNullable<ZodNumber>
 
+/**
+ * Creates a Zod schema for number validation with comprehensive constraints
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {NumberOptions<IsRequired>} [options] - Configuration options for number validation
+ * @returns {NumberSchema<IsRequired>} Zod schema for number validation
+ *
+ * @description
+ * Creates a comprehensive number validator with type constraints, range validation,
+ * precision control, and advanced parsing features including comma-separated numbers.
+ *
+ * Features:
+ * - Type constraints (integer, float, or both)
+ * - Range validation (min/max)
+ * - Sign constraints (positive, negative, non-negative, non-positive)
+ * - Multiple-of validation
+ * - Precision control (decimal places)
+ * - Finite number validation
+ * - Comma-separated number parsing
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic number validation
+ * const basicSchema = number()
+ * basicSchema.parse(42) // ✓ Valid
+ * basicSchema.parse("42") // ✓ Valid (converted to number)
+ *
+ * // Integer only
+ * const integerSchema = number({ type: "integer" })
+ * integerSchema.parse(42) // ✓ Valid
+ * integerSchema.parse(42.5) // ✗ Invalid
+ *
+ * // Range validation
+ * const rangeSchema = number({ min: 0, max: 100 })
+ * rangeSchema.parse(50) // ✓ Valid
+ * rangeSchema.parse(150) // ✗ Invalid
+ *
+ * // Positive numbers only
+ * const positiveSchema = number({ positive: true })
+ * positiveSchema.parse(5) // ✓ Valid
+ * positiveSchema.parse(-5) // ✗ Invalid
+ *
+ * // Multiple of constraint
+ * const multipleSchema = number({ multipleOf: 5 })
+ * multipleSchema.parse(10) // ✓ Valid
+ * multipleSchema.parse(7) // ✗ Invalid
+ *
+ * // Precision control
+ * const precisionSchema = number({ precision: 2 })
+ * precisionSchema.parse(3.14) // ✓ Valid
+ * precisionSchema.parse(3.14159) // ✗ Invalid
+ *
+ * // Comma-separated parsing
+ * const commaSchema = number({ parseCommas: true })
+ * commaSchema.parse("1,234.56") // ✓ Valid (parsed as 1234.56)
+ *
+ * // Optional with default
+ * const optionalSchema = number({
+ *   required: false,
+ *   defaultValue: 0
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link NumberOptions} for all available configuration options
+ */
 export function number<IsRequired extends boolean = true>(options?: NumberOptions<IsRequired>): NumberSchema<IsRequired> {
   const {
     required = true,

package/src/validators/common/password.ts

@@ -1,7 +1,36 @@
+/**
+ * @fileoverview Password validator for Zod Kit
+ *
+ * Provides comprehensive password validation with strength analysis, character requirements,
+ * security checks, and protection against common weak passwords.
+ *
+ * @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 password validation error messages
+ *
+ * @interface PasswordMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [min] - Message when password is too short
+ * @property {string} [max] - Message when password is too long
+ * @property {string} [uppercase] - Message when uppercase letters are required
+ * @property {string} [lowercase] - Message when lowercase letters are required
+ * @property {string} [digits] - Message when digits are required
+ * @property {string} [special] - Message when special characters are required
+ * @property {string} [noRepeating] - Message when repeating characters are forbidden
+ * @property {string} [noSequential] - Message when sequential characters are forbidden
+ * @property {string} [noCommonWords] - Message when common passwords are forbidden
+ * @property {string} [minStrength] - Message when password strength is insufficient
+ * @property {string} [excludes] - Message when password contains forbidden strings
+ * @property {string} [includes] - Message when password doesn't contain required string
+ * @property {string} [invalid] - Message when password doesn't match custom regex
+ */
 export type PasswordMessages = {
   required?: string
   min?: string
@@ -19,8 +48,42 @@ export type PasswordMessages = {
   invalid?: string
 }
 
+/**
+ * Password strength levels used for validation
+ *
+ * @typedef {"weak" | "medium" | "strong" | "very-strong"} PasswordStrength
+ * @description
+ * - weak: Basic passwords with minimal requirements
+ * - medium: Passwords with some character variety
+ * - strong: Passwords with good character variety and length
+ * - very-strong: Passwords with excellent character variety, length, and complexity
+ */
 export type PasswordStrength = "weak" | "medium" | "strong" | "very-strong"
 
+/**
+ * Configuration options for password validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface PasswordOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {number} [min] - Minimum length of password
+ * @property {number} [max] - Maximum length of password
+ * @property {boolean} [uppercase] - Whether uppercase letters are required
+ * @property {boolean} [lowercase] - Whether lowercase letters are required
+ * @property {boolean} [digits] - Whether digits are required
+ * @property {boolean} [special] - Whether special characters are required
+ * @property {boolean} [noRepeating] - Whether to forbid repeating characters (3+ in a row)
+ * @property {boolean} [noSequential] - Whether to forbid sequential characters (abc, 123)
+ * @property {boolean} [noCommonWords] - Whether to forbid common weak passwords
+ * @property {PasswordStrength} [minStrength] - Minimum required password strength
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {string} [includes] - String that must be included in password
+ * @property {RegExp} [regex] - Custom regex pattern for validation
+ * @property {Function} [transform] - Custom transformation function for password
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, PasswordMessages>} [i18n] - Custom error messages for different locales
+ */
 export type PasswordOptions<IsRequired extends boolean = true> = {
   required?: IsRequired
   min?: number
@@ -41,9 +104,21 @@ export type PasswordOptions<IsRequired extends boolean = true> = {
   i18n?: Record<Locale, PasswordMessages>
 }
 
+/**
+ * Type alias for password validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef PasswordSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 export type PasswordSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
-// Common weak passwords to check against
+/**
+ * List of common weak passwords to check against
+ *
+ * @constant {string[]} COMMON_PASSWORDS
+ * @description Contains frequently used weak passwords that should be avoided
+ */
 const COMMON_PASSWORDS = [
   "password",
   "123456",
@@ -63,7 +138,31 @@ const COMMON_PASSWORDS = [
   "princess",
 ]
 
-// Helper function to calculate password strength
+/**
+ * Calculates password strength based on various criteria
+ *
+ * @param {string} password - The password to analyze
+ * @returns {PasswordStrength} The calculated strength level
+ *
+ * @description
+ * Analyzes password strength using multiple factors:
+ * - Length bonuses (8+, 12+, 16+ characters)
+ * - Character variety (lowercase, uppercase, digits, special characters)
+ * - Deductions for repeating or sequential patterns
+ *
+ * Scoring system:
+ * - 0-2 points: weak
+ * - 3-4 points: medium
+ * - 5-6 points: strong
+ * - 7+ points: very-strong
+ *
+ * @example
+ * ```typescript
+ * calculatePasswordStrength("password") // "weak"
+ * calculatePasswordStrength("Password123") // "medium"
+ * calculatePasswordStrength("MyStr0ng!P@ssw0rd") // "very-strong"
+ * ```
+ */
 const calculatePasswordStrength = (password: string): PasswordStrength => {
   let score = 0
 
@@ -88,6 +187,79 @@ const calculatePasswordStrength = (password: string): PasswordStrength => {
   return "very-strong"
 }
 
+/**
+ * Creates a Zod schema for password validation with comprehensive security checks
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {PasswordOptions<IsRequired>} [options] - Configuration options for password validation
+ * @returns {PasswordSchema<IsRequired>} Zod schema for password validation
+ *
+ * @description
+ * Creates a comprehensive password validator with strength analysis, character requirements,
+ * security checks, and protection against common weak passwords.
+ *
+ * Features:
+ * - Length validation (min/max)
+ * - Character requirements (uppercase, lowercase, digits, special)
+ * - Security checks (no repeating, no sequential patterns)
+ * - Common password detection
+ * - Strength analysis with configurable minimum levels
+ * - Content inclusion/exclusion
+ * - Custom regex patterns
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic password validation
+ * const basicSchema = password()
+ * basicSchema.parse("MyPassword123!") // ✓ Valid
+ *
+ * // Strong password requirements
+ * const strongSchema = password({
+ *   min: 12,
+ *   uppercase: true,
+ *   lowercase: true,
+ *   digits: true,
+ *   special: true,
+ *   minStrength: "strong"
+ * })
+ *
+ * // No common passwords
+ * const secureSchema = password({
+ *   noCommonWords: true,
+ *   noRepeating: true,
+ *   noSequential: true
+ * })
+ * secureSchema.parse("password123") // ✗ Invalid (common password)
+ * secureSchema.parse("aaa123") // ✗ Invalid (repeating characters)
+ * secureSchema.parse("abc123") // ✗ Invalid (sequential characters)
+ *
+ * // Custom requirements
+ * const customSchema = password({
+ *   min: 8,
+ *   includes: "@", // Must contain @
+ *   excludes: ["admin", "user"], // Cannot contain these words
+ *   regex: /^(?=.*[A-Z])(?=.*[a-z])(?=.*\d)/ // Custom pattern
+ * })
+ *
+ * // Minimum strength requirement
+ * const strengthSchema = password({ minStrength: "very-strong" })
+ * strengthSchema.parse("weak") // ✗ Invalid (insufficient strength)
+ * strengthSchema.parse("MyVeryStr0ng!P@ssw0rd2024") // ✓ Valid
+ *
+ * // Optional with default
+ * const optionalSchema = password({
+ *   required: false,
+ *   defaultValue: null
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link PasswordOptions} for all available configuration options
+ * @see {@link PasswordStrength} for strength level definitions
+ * @see {@link calculatePasswordStrength} for strength calculation logic
+ */
 export function password<IsRequired extends boolean = true>(options?: PasswordOptions<IsRequired>): PasswordSchema<IsRequired> {
   const {
     required = true,