@hy_ong/zod-kit 0.1.16 → 0.2.1

package/dist/common/time.d.ts

@@ -0,0 +1,268 @@
+import { ZodString, ZodNullable } from 'zod';
+import { L as Locale } from '../config-CABSSvAp.js';
+
+/**
+ * @fileoverview Time validator for Zod Kit
+ *
+ * Provides comprehensive time validation with support for multiple time formats,
+ * hour/minute constraints, and advanced time-based validation options.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for time validation error messages
+ *
+ * @interface TimeMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when time format is invalid
+ * @property {string} [format] - Message when time doesn't match expected format
+ * @property {string} [min] - Message when time is before minimum allowed
+ * @property {string} [max] - Message when time is after maximum allowed
+ * @property {string} [hour] - Message when hour is outside allowed range
+ * @property {string} [minute] - Message when minute doesn't match step requirement
+ * @property {string} [second] - Message when second doesn't match step requirement
+ * @property {string} [includes] - Message when time doesn't contain required string
+ * @property {string} [excludes] - Message when time contains forbidden string
+ * @property {string} [customRegex] - Message when custom regex validation fails
+ * @property {string} [notInWhitelist] - Message when value is not in whitelist
+ */
+type TimeMessages = {
+    required?: string;
+    invalid?: string;
+    format?: string;
+    min?: string;
+    max?: string;
+    hour?: string;
+    minute?: string;
+    second?: string;
+    includes?: string;
+    excludes?: string;
+    customRegex?: string;
+    notInWhitelist?: string;
+};
+/**
+ * Supported time formats for validation
+ *
+ * @typedef {string} TimeFormat
+ *
+ * Available formats:
+ * - HH:mm: 24-hour format with leading zeros (14:30, 09:30)
+ * - HH:mm:ss: 24-hour format with seconds (14:30:45, 09:30:15)
+ * - hh:mm A: 12-hour format with AM/PM (02:30 PM, 09:30 AM)
+ * - hh:mm:ss A: 12-hour format with seconds and AM/PM (02:30:45 PM)
+ * - H:mm: 24-hour format without leading zeros (14:30, 9:30)
+ * - h:mm A: 12-hour format without leading zeros (2:30 PM, 9:30 AM)
+ */
+type TimeFormat = "HH:mm" | "HH:mm:ss" | "hh:mm A" | "hh:mm:ss A" | "H:mm" | "h:mm A";
+/**
+ * Configuration options for time validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface TimeOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {TimeFormat} [format="HH:mm"] - Expected time format
+ * @property {string} [min] - Minimum allowed time (e.g., "09:00")
+ * @property {string} [max] - Maximum allowed time (e.g., "17:00")
+ * @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 {number} [secondStep] - Required second intervals
+ * @property {string} [includes] - String that must be included in the time
+ * @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 {string[]} [whitelist] - Specific time 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, TimeMessages>} [i18n] - Custom error messages for different locales
+ */
+type TimeOptions<IsRequired extends boolean = true> = {
+    format?: TimeFormat;
+    min?: string;
+    max?: string;
+    minHour?: number;
+    maxHour?: number;
+    allowedHours?: number[];
+    minuteStep?: number;
+    secondStep?: number;
+    includes?: string;
+    excludes?: string | string[];
+    regex?: RegExp;
+    trimMode?: "trim" | "trimStart" | "trimEnd" | "none";
+    casing?: "upper" | "lower" | "none";
+    whitelist?: string[];
+    whitelistOnly?: boolean;
+    transform?: (value: string) => string;
+    defaultValue?: IsRequired extends true ? string : string | null;
+    i18n?: Partial<Record<Locale, Partial<TimeMessages>>>;
+};
+/**
+ * Type alias for time validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef TimeSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
+type TimeSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Regular expression patterns for time format validation
+ *
+ * @constant {Record<TimeFormat, RegExp>} TIME_PATTERNS
+ * @description Maps each supported time format to its corresponding regex pattern
+ */
+declare const TIME_PATTERNS: Record<TimeFormat, RegExp>;
+/**
+ * Parses a time string to minutes since midnight for comparison
+ *
+ * @param {string} timeStr - The time string to parse
+ * @param {TimeFormat} format - The expected time format
+ * @returns {number | null} Minutes since midnight (0-1439) or null if parsing fails
+ *
+ * @description
+ * Converts time strings to minutes since midnight for easy comparison and validation.
+ * Handles both 12-hour and 24-hour formats with proper AM/PM conversion.
+ *
+ * @example
+ * ```typescript
+ * parseTimeToMinutes("14:30", "HH:mm") // 870 (14*60 + 30)
+ * parseTimeToMinutes("2:30 PM", "h:mm A") // 870 (14*60 + 30)
+ * parseTimeToMinutes("12:00 AM", "hh:mm A") // 0 (midnight)
+ * parseTimeToMinutes("12:00 PM", "hh:mm A") // 720 (noon)
+ * ```
+ */
+declare const parseTimeToMinutes: (timeStr: string, format: TimeFormat) => number | null;
+/**
+ * Validates if a time string matches the specified format pattern
+ *
+ * @param {string} value - The time string to validate
+ * @param {TimeFormat} format - The expected time format
+ * @returns {boolean} True if the time matches the format pattern
+ *
+ * @description
+ * Performs regex pattern matching to validate time format.
+ * Does not validate actual time values (e.g., 25:00 would pass pattern but fail logic).
+ *
+ * @example
+ * ```typescript
+ * validateTimeFormat("14:30", "HH:mm") // true
+ * validateTimeFormat("2:30 PM", "h:mm A") // true
+ * validateTimeFormat("25:00", "HH:mm") // true (pattern matches)
+ * validateTimeFormat("14:30", "h:mm A") // false (wrong format)
+ * ```
+ */
+declare const validateTimeFormat: (value: string, format: TimeFormat) => boolean;
+/**
+ * Normalizes time to 24-hour format for internal processing
+ *
+ * @param {string} timeStr - The time string to normalize
+ * @param {TimeFormat} format - The current time format
+ * @returns {string | null} Normalized time string or null if parsing fails
+ *
+ * @description
+ * Converts time strings to a standardized 24-hour format for consistent processing.
+ * Handles AM/PM conversion and leading zero normalization.
+ *
+ * @example
+ * ```typescript
+ * normalizeTime("2:30 PM", "h:mm A") // "14:30"
+ * normalizeTime("12:00 AM", "hh:mm A") // "00:00"
+ * normalizeTime("9:30", "H:mm") // "09:30"
+ * normalizeTime("14:30:45", "HH:mm:ss") // "14:30:45"
+ * ```
+ */
+declare const normalizeTime: (timeStr: string, format: TimeFormat) => string | null;
+/**
+ * Creates a Zod schema for time 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 {TimeSchema<IsRequired>} Zod schema for time validation
+ *
+ * @description
+ * Creates a comprehensive time validator that supports multiple time formats,
+ * hour/minute constraints, step validation, and extensive customization options.
+ *
+ * Features:
+ * - Multiple time formats (24-hour, 12-hour, with/without seconds)
+ * - Time range validation (min/max)
+ * - Hour and minute constraints
+ * - Step validation (e.g., 15-minute intervals)
+ * - Whitelist/blacklist support
+ * - Custom regex patterns
+ * - String transformation and case handling
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic time validation (24-hour format)
+ * const basicSchema = time()
+ * basicSchema.parse("14:30") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("14:30") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ * basicSchema.parse("2:30 PM") // ✗ Invalid (wrong format)
+ *
+ * // 12-hour format with AM/PM
+ * const ampmSchema = time(false, { format: "hh:mm A" })
+ * ampmSchema.parse("02:30 PM") // ✓ Valid
+ * ampmSchema.parse("14:30") // ✗ Invalid (wrong format)
+ *
+ * // Business hours validation
+ * const businessHours = time({
+ *   format: "HH:mm",
+ *   minHour: 9,
+ *   maxHour: 17,
+ *   minuteStep: 15 // Only :00, :15, :30, :45
+ * })
+ * businessHours.parse("09:15") // ✓ Valid
+ * businessHours.parse("18:00") // ✗ Invalid (after maxHour)
+ * businessHours.parse("09:05") // ✗ Invalid (not 15-minute step)
+ *
+ * // Time range validation
+ * const timeRangeSchema = time(false, {
+ *   min: "09:00",
+ *   max: "17:00"
+ * })
+ * timeRangeSchema.parse("12:30") // ✓ Valid
+ * timeRangeSchema.parse("08:00") // ✗ Invalid (before min)
+ *
+ * // Allowed hours only
+ * const specificHours = time({
+ *   allowedHours: [9, 12, 15, 18]
+ * })
+ * specificHours.parse("12:30") // ✓ Valid
+ * specificHours.parse("11:30") // ✗ Invalid (hour not allowed)
+ *
+ * // Whitelist specific times
+ * const whitelistSchema = time(false, {
+ *   whitelist: ["09:00", "12:00", "17:00"],
+ *   whitelistOnly: true
+ * })
+ * whitelistSchema.parse("12:00") // ✓ Valid (in whitelist)
+ * whitelistSchema.parse("13:00") // ✗ Invalid (not in whitelist)
+ *
+ * // Optional with default
+ * const optionalSchema = time(false, {
+ *   defaultValue: "09:00"
+ * })
+ * optionalSchema.parse("") // ✓ Valid (returns "09:00")
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link TimeOptions} for all available configuration options
+ * @see {@link TimeFormat} for supported time formats
+ */
+declare function time<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TimeOptions<IsRequired>, 'required'>): TimeSchema<IsRequired>;
+
+export { TIME_PATTERNS, type TimeFormat, type TimeMessages, type TimeOptions, type TimeSchema, normalizeTime, parseTimeToMinutes, time, validateTimeFormat };

package/dist/common/time.js

@@ -0,0 +1,15 @@
+import {
+  TIME_PATTERNS,
+  normalizeTime,
+  parseTimeToMinutes,
+  time,
+  validateTimeFormat
+} from "../chunk-P2NONIMS.js";
+import "../chunk-ZBOQCXD4.js";
+export {
+  TIME_PATTERNS,
+  normalizeTime,
+  parseTimeToMinutes,
+  time,
+  validateTimeFormat
+};

package/dist/common/url.cjs

@@ -0,0 +1,7 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkJBNCMS42cjs = require('../chunk-JBNCMS42.cjs');
+require('../chunk-YWV2BBXN.cjs');
+
+
+exports.url = _chunkJBNCMS42cjs.url;

package/dist/common/url.d.cts

@@ -0,0 +1,196 @@
+import { ZodString, ZodNullable } from 'zod';
+import { L as Locale } from '../config-CABSSvAp.cjs';
+
+/**
+ * @fileoverview URL validator for Zod Kit
+ *
+ * Provides comprehensive URL validation with protocol filtering, domain control,
+ * port validation, path constraints, and localhost handling.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for URL validation error messages
+ *
+ * @interface UrlMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when URL format is invalid
+ * @property {string} [min] - Message when URL is too short
+ * @property {string} [max] - Message when URL is too long
+ * @property {string} [includes] - Message when URL doesn't contain required string
+ * @property {string} [excludes] - Message when URL contains forbidden string
+ * @property {string} [protocol] - Message when protocol is not allowed
+ * @property {string} [domain] - Message when domain is not allowed
+ * @property {string} [domainBlacklist] - Message when domain is blacklisted
+ * @property {string} [port] - Message when port is not allowed
+ * @property {string} [pathStartsWith] - Message when path doesn't start with required string
+ * @property {string} [pathEndsWith] - Message when path doesn't end with required string
+ * @property {string} [hasQuery] - Message when query parameters are required
+ * @property {string} [noQuery] - Message when query parameters are forbidden
+ * @property {string} [hasFragment] - Message when fragment is required
+ * @property {string} [noFragment] - Message when fragment is forbidden
+ * @property {string} [localhost] - Message when localhost is forbidden
+ * @property {string} [noLocalhost] - Message when localhost is required
+ */
+type UrlMessages = {
+    required?: string;
+    invalid?: string;
+    min?: string;
+    max?: string;
+    includes?: string;
+    excludes?: string;
+    protocol?: string;
+    domain?: string;
+    domainBlacklist?: string;
+    port?: string;
+    pathStartsWith?: string;
+    pathEndsWith?: string;
+    hasQuery?: string;
+    noQuery?: string;
+    hasFragment?: string;
+    noFragment?: string;
+    localhost?: string;
+    noLocalhost?: string;
+};
+/**
+ * Configuration options for URL validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface UrlOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {number} [min] - Minimum length of URL
+ * @property {number} [max] - Maximum length of URL
+ * @property {string} [includes] - String that must be included in URL
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {string[]} [protocols] - Allowed protocols (e.g., ["https", "http"])
+ * @property {string[]} [allowedDomains] - Domains that are allowed
+ * @property {string[]} [blockedDomains] - Domains that are blocked
+ * @property {number[]} [allowedPorts] - Ports that are allowed
+ * @property {number[]} [blockedPorts] - Ports that are blocked
+ * @property {string} [pathStartsWith] - Path must start with this string
+ * @property {string} [pathEndsWith] - Path must end with this string
+ * @property {boolean} [mustHaveQuery] - Whether URL must have query parameters
+ * @property {boolean} [mustNotHaveQuery] - Whether URL must not have query parameters
+ * @property {boolean} [mustHaveFragment] - Whether URL must have fragment
+ * @property {boolean} [mustNotHaveFragment] - Whether URL must not have fragment
+ * @property {boolean} [allowLocalhost=true] - Whether to allow localhost URLs
+ * @property {boolean} [blockLocalhost] - Whether to explicitly block localhost URLs
+ * @property {Function} [transform] - Custom transformation function for URL strings
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, UrlMessages>} [i18n] - Custom error messages for different locales
+ */
+type UrlOptions<IsRequired extends boolean = true> = {
+    min?: number;
+    max?: number;
+    includes?: string;
+    excludes?: string | string[];
+    protocols?: string[];
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+    allowedPorts?: number[];
+    blockedPorts?: number[];
+    pathStartsWith?: string;
+    pathEndsWith?: string;
+    mustHaveQuery?: boolean;
+    mustNotHaveQuery?: boolean;
+    mustHaveFragment?: boolean;
+    mustNotHaveFragment?: boolean;
+    allowLocalhost?: boolean;
+    blockLocalhost?: boolean;
+    transform?: (value: string) => string;
+    defaultValue?: IsRequired extends true ? string : string | null;
+    i18n?: Partial<Record<Locale, Partial<UrlMessages>>>;
+};
+/**
+ * Type alias for URL validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef UrlSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
+type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Creates a Zod schema for URL validation with comprehensive constraints
+ *
+ * @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 {UrlSchema<IsRequired>} Zod schema for URL validation
+ *
+ * @description
+ * Creates a comprehensive URL validator with protocol filtering, domain control,
+ * port validation, path constraints, and localhost handling.
+ *
+ * Features:
+ * - RFC-compliant URL format validation
+ * - Protocol whitelist/blacklist (http, https, ftp, etc.)
+ * - Domain whitelist/blacklist with subdomain support
+ * - Port validation and filtering
+ * - Path prefix/suffix validation
+ * - Query parameter requirements
+ * - Fragment requirements
+ * - Localhost detection and control
+ * - Length validation
+ * - Content inclusion/exclusion
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic URL validation
+ * const basicSchema = url() // optional by default
+ * basicSchema.parse("https://example.com") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("https://example.com") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ *
+ * // HTTPS only
+ * const httpsSchema = url(false, { protocols: ["https"] })
+ * httpsSchema.parse("https://example.com") // ✓ Valid
+ * httpsSchema.parse("http://example.com") // ✗ Invalid
+ *
+ * // Domain restriction
+ * const domainSchema = url(false, {
+ *   allowedDomains: ["company.com", "trusted.org"]
+ * })
+ * domainSchema.parse("https://app.company.com") // ✓ Valid (subdomain)
+ * domainSchema.parse("https://example.com") // ✗ Invalid
+ *
+ * // Block localhost
+ * const noLocalhostSchema = url(false, { blockLocalhost: true })
+ * noLocalhostSchema.parse("https://example.com") // ✓ Valid
+ * noLocalhostSchema.parse("http://localhost:3000") // ✗ Invalid
+ *
+ * // API endpoints with path requirements
+ * const apiSchema = url(false, {
+ *   pathStartsWith: "/api/",
+ *   mustHaveQuery: true
+ * })
+ * apiSchema.parse("https://api.com/api/users?page=1") // ✓ Valid
+ *
+ * // Port restrictions
+ * const portSchema = url(false, {
+ *   allowedPorts: [80, 443, 8080]
+ * })
+ * portSchema.parse("https://example.com:443") // ✓ Valid
+ * portSchema.parse("https://example.com:3000") // ✗ Invalid
+ *
+ * // Optional with default
+ * const optionalSchema = url(false, {
+ *   defaultValue: null
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link UrlOptions} for all available configuration options
+ */
+declare function url<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<UrlOptions<IsRequired>, 'required'>): UrlSchema<IsRequired>;
+
+export { type UrlMessages, type UrlOptions, type UrlSchema, url };

package/dist/common/url.d.ts

@@ -0,0 +1,196 @@
+import { ZodString, ZodNullable } from 'zod';
+import { L as Locale } from '../config-CABSSvAp.js';
+
+/**
+ * @fileoverview URL validator for Zod Kit
+ *
+ * Provides comprehensive URL validation with protocol filtering, domain control,
+ * port validation, path constraints, and localhost handling.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for URL validation error messages
+ *
+ * @interface UrlMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when URL format is invalid
+ * @property {string} [min] - Message when URL is too short
+ * @property {string} [max] - Message when URL is too long
+ * @property {string} [includes] - Message when URL doesn't contain required string
+ * @property {string} [excludes] - Message when URL contains forbidden string
+ * @property {string} [protocol] - Message when protocol is not allowed
+ * @property {string} [domain] - Message when domain is not allowed
+ * @property {string} [domainBlacklist] - Message when domain is blacklisted
+ * @property {string} [port] - Message when port is not allowed
+ * @property {string} [pathStartsWith] - Message when path doesn't start with required string
+ * @property {string} [pathEndsWith] - Message when path doesn't end with required string
+ * @property {string} [hasQuery] - Message when query parameters are required
+ * @property {string} [noQuery] - Message when query parameters are forbidden
+ * @property {string} [hasFragment] - Message when fragment is required
+ * @property {string} [noFragment] - Message when fragment is forbidden
+ * @property {string} [localhost] - Message when localhost is forbidden
+ * @property {string} [noLocalhost] - Message when localhost is required
+ */
+type UrlMessages = {
+    required?: string;
+    invalid?: string;
+    min?: string;
+    max?: string;
+    includes?: string;
+    excludes?: string;
+    protocol?: string;
+    domain?: string;
+    domainBlacklist?: string;
+    port?: string;
+    pathStartsWith?: string;
+    pathEndsWith?: string;
+    hasQuery?: string;
+    noQuery?: string;
+    hasFragment?: string;
+    noFragment?: string;
+    localhost?: string;
+    noLocalhost?: string;
+};
+/**
+ * Configuration options for URL validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface UrlOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {number} [min] - Minimum length of URL
+ * @property {number} [max] - Maximum length of URL
+ * @property {string} [includes] - String that must be included in URL
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {string[]} [protocols] - Allowed protocols (e.g., ["https", "http"])
+ * @property {string[]} [allowedDomains] - Domains that are allowed
+ * @property {string[]} [blockedDomains] - Domains that are blocked
+ * @property {number[]} [allowedPorts] - Ports that are allowed
+ * @property {number[]} [blockedPorts] - Ports that are blocked
+ * @property {string} [pathStartsWith] - Path must start with this string
+ * @property {string} [pathEndsWith] - Path must end with this string
+ * @property {boolean} [mustHaveQuery] - Whether URL must have query parameters
+ * @property {boolean} [mustNotHaveQuery] - Whether URL must not have query parameters
+ * @property {boolean} [mustHaveFragment] - Whether URL must have fragment
+ * @property {boolean} [mustNotHaveFragment] - Whether URL must not have fragment
+ * @property {boolean} [allowLocalhost=true] - Whether to allow localhost URLs
+ * @property {boolean} [blockLocalhost] - Whether to explicitly block localhost URLs
+ * @property {Function} [transform] - Custom transformation function for URL strings
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, UrlMessages>} [i18n] - Custom error messages for different locales
+ */
+type UrlOptions<IsRequired extends boolean = true> = {
+    min?: number;
+    max?: number;
+    includes?: string;
+    excludes?: string | string[];
+    protocols?: string[];
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+    allowedPorts?: number[];
+    blockedPorts?: number[];
+    pathStartsWith?: string;
+    pathEndsWith?: string;
+    mustHaveQuery?: boolean;
+    mustNotHaveQuery?: boolean;
+    mustHaveFragment?: boolean;
+    mustNotHaveFragment?: boolean;
+    allowLocalhost?: boolean;
+    blockLocalhost?: boolean;
+    transform?: (value: string) => string;
+    defaultValue?: IsRequired extends true ? string : string | null;
+    i18n?: Partial<Record<Locale, Partial<UrlMessages>>>;
+};
+/**
+ * Type alias for URL validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef UrlSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
+type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Creates a Zod schema for URL validation with comprehensive constraints
+ *
+ * @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 {UrlSchema<IsRequired>} Zod schema for URL validation
+ *
+ * @description
+ * Creates a comprehensive URL validator with protocol filtering, domain control,
+ * port validation, path constraints, and localhost handling.
+ *
+ * Features:
+ * - RFC-compliant URL format validation
+ * - Protocol whitelist/blacklist (http, https, ftp, etc.)
+ * - Domain whitelist/blacklist with subdomain support
+ * - Port validation and filtering
+ * - Path prefix/suffix validation
+ * - Query parameter requirements
+ * - Fragment requirements
+ * - Localhost detection and control
+ * - Length validation
+ * - Content inclusion/exclusion
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic URL validation
+ * const basicSchema = url() // optional by default
+ * basicSchema.parse("https://example.com") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("https://example.com") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ *
+ * // HTTPS only
+ * const httpsSchema = url(false, { protocols: ["https"] })
+ * httpsSchema.parse("https://example.com") // ✓ Valid
+ * httpsSchema.parse("http://example.com") // ✗ Invalid
+ *
+ * // Domain restriction
+ * const domainSchema = url(false, {
+ *   allowedDomains: ["company.com", "trusted.org"]
+ * })
+ * domainSchema.parse("https://app.company.com") // ✓ Valid (subdomain)
+ * domainSchema.parse("https://example.com") // ✗ Invalid
+ *
+ * // Block localhost
+ * const noLocalhostSchema = url(false, { blockLocalhost: true })
+ * noLocalhostSchema.parse("https://example.com") // ✓ Valid
+ * noLocalhostSchema.parse("http://localhost:3000") // ✗ Invalid
+ *
+ * // API endpoints with path requirements
+ * const apiSchema = url(false, {
+ *   pathStartsWith: "/api/",
+ *   mustHaveQuery: true
+ * })
+ * apiSchema.parse("https://api.com/api/users?page=1") // ✓ Valid
+ *
+ * // Port restrictions
+ * const portSchema = url(false, {
+ *   allowedPorts: [80, 443, 8080]
+ * })
+ * portSchema.parse("https://example.com:443") // ✓ Valid
+ * portSchema.parse("https://example.com:3000") // ✗ Invalid
+ *
+ * // Optional with default
+ * const optionalSchema = url(false, {
+ *   defaultValue: null
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link UrlOptions} for all available configuration options
+ */
+declare function url<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<UrlOptions<IsRequired>, 'required'>): UrlSchema<IsRequired>;
+
+export { type UrlMessages, type UrlOptions, type UrlSchema, url };