@hy_ong/zod-kit 0.2.0 → 0.2.2

package/dist/taiwan/national-id.d.ts

@@ -0,0 +1,214 @@
+import { ZodString, ZodNullable } from 'zod';
+import { L as Locale } from '../config-CABSSvAp.js';
+
+/**
+ * @fileoverview Taiwan National ID (身分證/居留證) validator for Zod Kit
+ *
+ * Provides validation for Taiwan National ID cards (身分證) and
+ * Resident Certificates (居留證) with support for both old and new formats.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for national ID validation error messages
+ *
+ * @interface TwNationalIdMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when national ID format or checksum is invalid
+ */
+type TwNationalIdMessages = {
+    required?: string;
+    invalid?: string;
+};
+/**
+ * Types of Taiwan national identification documents
+ *
+ * @typedef {"citizen" | "resident" | "both"} NationalIdType
+ *
+ * Available types:
+ * - citizen: National ID card (身分證字號) for Taiwan citizens
+ * - resident: Resident certificate (居留證號) for foreign residents
+ * - both: Accept both citizen and resident IDs
+ */
+type NationalIdType = "citizen" | "resident" | "both";
+/**
+ * Configuration options for Taiwan national ID validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface TwNationalIdOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {NationalIdType} [type="both"] - Type of ID to accept
+ * @property {boolean} [allowOldResident=true] - Whether to accept old-style resident certificates
+ * @property {Function} [transform] - Custom transformation function for ID
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, TwNationalIdMessages>} [i18n] - Custom error messages for different locales
+ */
+type TwNationalIdOptions<IsRequired extends boolean = true> = {
+    type?: NationalIdType;
+    allowOldResident?: boolean;
+    transform?: (value: string) => string;
+    defaultValue?: IsRequired extends true ? string : string | null;
+    i18n?: Partial<Record<Locale, Partial<TwNationalIdMessages>>>;
+};
+/**
+ * Type alias for national ID validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef TwNationalIdSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
+type TwNationalIdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Validates Taiwan citizen national ID card (身分證字號)
+ *
+ * @param {string} value - The citizen ID to validate
+ * @returns {boolean} True if the citizen ID is valid
+ *
+ * @description
+ * Validates Taiwan citizen ID format: 1 letter + 1 gender digit (1-2) + 8 digits
+ * Uses checksum algorithm with city code conversion and weighted sum.
+ *
+ * Format: [A-Z][1-2]XXXXXXXX
+ * - First letter: City/county code
+ * - Second digit: Gender (1=male, 2=female)
+ * - Last 8 digits: Serial number + checksum
+ *
+ * @example
+ * ```typescript
+ * validateCitizenId("A123456789") // true/false based on checksum
+ * validateCitizenId("A323456789") // false (invalid gender digit)
+ * ```
+ */
+declare const validateCitizenId: (value: string) => boolean;
+/**
+ * Validates old-style Taiwan resident certificate (舊式居留證號)
+ *
+ * @param {string} value - The old-style resident ID to validate
+ * @returns {boolean} True if the old-style resident ID is valid
+ *
+ * @description
+ * Validates old-style resident ID format: 1 letter + 1 gender letter + 8 digits
+ * Uses checksum algorithm with city code and gender code conversion.
+ *
+ * Format: [A-Z][ABCD]XXXXXXXX
+ * - First letter: City/county code
+ * - Second letter: Gender code (A/C=male, B/D=female)
+ * - Last 8 digits: Serial number + checksum
+ *
+ * @example
+ * ```typescript
+ * validateOldResidentId("AA12345678") // true/false based on checksum
+ * validateOldResidentId("AE12345678") // false (invalid gender letter)
+ * ```
+ */
+declare const validateOldResidentId: (value: string) => boolean;
+/**
+ * Validates new-style Taiwan resident certificate (新式居留證號)
+ *
+ * @param {string} value - The new-style resident ID to validate
+ * @returns {boolean} True if the new-style resident ID is valid
+ *
+ * @description
+ * Validates new-style resident ID format: 1 letter + 1 type digit + 8 digits
+ * Uses the same checksum algorithm as citizen IDs.
+ *
+ * Format: [A-Z][89]XXXXXXXX
+ * - First letter: City/county code
+ * - Second digit: Type indicator (8 or 9)
+ * - Last 8 digits: Serial number + checksum
+ *
+ * @example
+ * ```typescript
+ * validateNewResidentId("A812345678") // true/false based on checksum
+ * validateNewResidentId("A712345678") // false (invalid type digit)
+ * ```
+ */
+declare const validateNewResidentId: (value: string) => boolean;
+/**
+ * Main validation function for Taiwan national IDs
+ *
+ * @param {string} value - The national ID to validate
+ * @param {NationalIdType} [type="both"] - Type of ID to accept
+ * @param {boolean} [allowOldResident=true] - Whether to accept old-style resident certificates
+ * @returns {boolean} True if the national ID is valid
+ *
+ * @description
+ * Validates Taiwan national IDs based on the specified type and options.
+ * Supports citizen IDs, resident certificates (both old and new styles).
+ *
+ * @example
+ * ```typescript
+ * validateTaiwanNationalId("A123456789", "citizen") // Citizen ID only
+ * validateTaiwanNationalId("A812345678", "resident") // Resident ID only
+ * validateTaiwanNationalId("A123456789", "both") // Accept any valid format
+ * validateTaiwanNationalId("AA12345678", "both", false) // Reject old resident format
+ * ```
+ */
+declare const validateTaiwanNationalId: (value: string, type?: NationalIdType, allowOldResident?: boolean) => boolean;
+/**
+ * Creates a Zod schema for Taiwan National ID validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {TwNationalIdOptions<IsRequired>} [options] - Configuration options for national ID validation
+ * @returns {TwNationalIdSchema<IsRequired>} Zod schema for national ID validation
+ *
+ * @description
+ * Creates a comprehensive Taiwan National ID validator that supports both
+ * citizen IDs and resident certificates with configurable validation rules.
+ *
+ * Features:
+ * - Citizen ID validation (身分證字號)
+ * - Resident certificate validation (居留證號, old and new formats)
+ * - Configurable ID type acceptance
+ * - Automatic case conversion to uppercase
+ * - Checksum verification
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ * - Optional field support
+ *
+ * @example
+ * ```typescript
+ * // Accept any valid Taiwan ID
+ * const anyIdSchema = twNationalId()
+ * anyIdSchema.parse("A123456789") // ✓ Valid citizen ID
+ * anyIdSchema.parse("A812345678") // ✓ Valid new resident ID
+ * anyIdSchema.parse("AA12345678") // ✓ Valid old resident ID
+ *
+ * // Citizen IDs only
+ * const citizenSchema = twNationalId(false, { type: "citizen" })
+ * citizenSchema.parse("A123456789") // ✓ Valid
+ * citizenSchema.parse("A812345678") // ✗ Invalid (resident ID)
+ *
+ * // Resident IDs only (new format only)
+ * const residentSchema = twNationalId(false, {
+ *   type: "resident",
+ *   allowOldResident: false
+ * })
+ * residentSchema.parse("A812345678") // ✓ Valid
+ * residentSchema.parse("AA12345678") // ✗ Invalid (old format)
+ *
+ * // Optional with custom transformation
+ * const optionalSchema = twNationalId(false, {
+ *   transform: (value) => value.replace(/[^A-Z0-9]/g, '') // Remove special chars
+ * })
+ *
+ * // With custom error messages
+ * const customSchema = twNationalId(false, {
+ *   i18n: {
+ *     en: { invalid: "Please enter a valid Taiwan National ID" },
+ *     'zh-TW': { invalid: "請輸入有效的身分證或居留證號碼" }
+ *   }
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link TwNationalIdOptions} for all available configuration options
+ * @see {@link NationalIdType} for supported ID types
+ * @see {@link validateTaiwanNationalId} for validation logic details
+ */
+declare function twNationalId<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TwNationalIdOptions<IsRequired>, 'required'>): TwNationalIdSchema<IsRequired>;
+
+export { type NationalIdType, type TwNationalIdMessages, type TwNationalIdOptions, type TwNationalIdSchema, twNationalId, validateCitizenId, validateNewResidentId, validateOldResidentId, validateTaiwanNationalId };

package/dist/taiwan/national-id.js

@@ -0,0 +1,15 @@
+import {
+  twNationalId,
+  validateCitizenId,
+  validateNewResidentId,
+  validateOldResidentId,
+  validateTaiwanNationalId
+} from "../chunk-COYKBWTI.js";
+import "../chunk-6AAP4LPF.js";
+export {
+  twNationalId,
+  validateCitizenId,
+  validateNewResidentId,
+  validateOldResidentId,
+  validateTaiwanNationalId
+};

package/dist/taiwan/passport.cjs

@@ -0,0 +1,9 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+var _chunkZNJLWJX3cjs = require('../chunk-ZNJLWJX3.cjs');
+require('../chunk-UCOXAZJF.cjs');
+
+
+
+exports.twPassport = _chunkZNJLWJX3cjs.twPassport; exports.validateTaiwanPassport = _chunkZNJLWJX3cjs.validateTaiwanPassport;

package/dist/taiwan/passport.d.cts

@@ -0,0 +1,19 @@
+import { ZodString, ZodNullable } from 'zod';
+import { L as Locale } from '../config-CABSSvAp.cjs';
+
+type PassportType = "ordinary" | "diplomatic" | "official" | "travel" | "any";
+type TwPassportMessages = {
+    required?: string;
+    invalid?: string;
+};
+type TwPassportOptions<IsRequired extends boolean = true> = {
+    passportType?: PassportType;
+    transform?: (value: string) => string;
+    defaultValue?: IsRequired extends true ? string : string | null;
+    i18n?: Partial<Record<Locale, Partial<TwPassportMessages>>>;
+};
+type TwPassportSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+declare const validateTaiwanPassport: (value: string) => boolean;
+declare function twPassport<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TwPassportOptions<IsRequired>, "required">): TwPassportSchema<IsRequired>;
+
+export { type PassportType, type TwPassportMessages, type TwPassportOptions, type TwPassportSchema, twPassport, validateTaiwanPassport };

package/dist/taiwan/passport.d.ts

@@ -0,0 +1,19 @@
+import { ZodString, ZodNullable } from 'zod';
+import { L as Locale } from '../config-CABSSvAp.js';
+
+type PassportType = "ordinary" | "diplomatic" | "official" | "travel" | "any";
+type TwPassportMessages = {
+    required?: string;
+    invalid?: string;
+};
+type TwPassportOptions<IsRequired extends boolean = true> = {
+    passportType?: PassportType;
+    transform?: (value: string) => string;
+    defaultValue?: IsRequired extends true ? string : string | null;
+    i18n?: Partial<Record<Locale, Partial<TwPassportMessages>>>;
+};
+type TwPassportSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+declare const validateTaiwanPassport: (value: string) => boolean;
+declare function twPassport<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TwPassportOptions<IsRequired>, "required">): TwPassportSchema<IsRequired>;
+
+export { type PassportType, type TwPassportMessages, type TwPassportOptions, type TwPassportSchema, twPassport, validateTaiwanPassport };

package/dist/taiwan/passport.js

@@ -0,0 +1,9 @@
+import {
+  twPassport,
+  validateTaiwanPassport
+} from "../chunk-QICQ6YEY.js";
+import "../chunk-6AAP4LPF.js";
+export {
+  twPassport,
+  validateTaiwanPassport
+};

package/dist/taiwan/postal-code.cjs

@@ -0,0 +1,17 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+
+var _chunkJOLSGZGNcjs = require('../chunk-JOLSGZGN.cjs');
+require('../chunk-UCOXAZJF.cjs');
+
+
+
+
+
+
+
+exports.VALID_3_DIGIT_PREFIXES = _chunkJOLSGZGNcjs.VALID_3_DIGIT_PREFIXES; exports.twPostalCode = _chunkJOLSGZGNcjs.twPostalCode; exports.validate3DigitPostalCode = _chunkJOLSGZGNcjs.validate3DigitPostalCode; exports.validate5DigitPostalCode = _chunkJOLSGZGNcjs.validate5DigitPostalCode; exports.validate6DigitPostalCode = _chunkJOLSGZGNcjs.validate6DigitPostalCode; exports.validateTaiwanPostalCode = _chunkJOLSGZGNcjs.validateTaiwanPostalCode;

package/dist/taiwan/postal-code.d.cts

@@ -0,0 +1,237 @@
+import { ZodString, ZodNullable } from 'zod';
+import { L as Locale } from '../config-CABSSvAp.cjs';
+
+/**
+ * @fileoverview Taiwan Postal Code validator for Zod Kit
+ *
+ * Provides comprehensive validation for Taiwan postal codes with support for
+ * 3-digit, 5-digit (legacy), and 6-digit (current) formats based on official
+ * Chunghwa Post specifications.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for postal code validation error messages
+ *
+ * @interface TwPostalCodeMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when postal code format is invalid
+ * @property {string} [invalidFormat] - Message when format doesn't match expected pattern
+ * @property {string} [invalidRange] - Message when postal code is outside valid range
+ * @property {string} [legacy5DigitWarning] - Warning message for 5-digit legacy format
+ * @property {string} [format3Only] - Message when only 3-digit format is allowed
+ * @property {string} [format5Only] - Message when only 5-digit format is allowed
+ * @property {string} [format6Only] - Message when only 6-digit format is allowed
+ */
+type TwPostalCodeMessages = {
+    required?: string;
+    invalid?: string;
+    invalidFormat?: string;
+    invalidRange?: string;
+    legacy5DigitWarning?: string;
+    format3Only?: string;
+    format5Only?: string;
+    format6Only?: string;
+    invalidSuffix?: string;
+    deprecated5Digit?: string;
+};
+/**
+ * Postal code format types supported in Taiwan
+ *
+ * @typedef {"3" | "5" | "6" | "3+5" | "3+6" | "5+6" | "all"} TwPostalCodeFormatType
+ *
+ * Available formats:
+ * - "3": 3-digit basic postal codes (100-982)
+ * - "5": 5-digit postal codes (3+2 format, legacy)
+ * - "6": 6-digit postal codes (3+3 format, current standard)
+ * - "3+5": Accept both 3-digit and 5-digit formats
+ * - "3+6": Accept both 3-digit and 6-digit formats (recommended)
+ * - "5+6": Accept both 5-digit and 6-digit formats
+ * - "all": Accept all formats (3, 5, and 6 digits)
+ */
+type TwPostalCodeFormatType = "3" | "5" | "6" | "3+5" | "3+6" | "5+6" | "all";
+/**
+ * Configuration options for Taiwan postal code validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface TwPostalCodeOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {TwPostalCodeFormatType} [format="3+6"] - Which postal code formats to accept
+ * @property {boolean} [strictValidation=true] - Enable strict validation against known postal code ranges
+ * @property {boolean} [allowDashes=true] - Whether to allow dashes in postal codes (e.g., "100-01" or "100-001")
+ * @property {boolean} [warn5Digit=true] - Whether to show warning for 5-digit legacy format
+ * @property {string[]} [allowedPrefixes] - Specific 3-digit prefixes to allow (if strictValidation is true)
+ * @property {string[]} [blockedPrefixes] - Specific 3-digit prefixes to block
+ * @property {Function} [transform] - Custom transformation function for postal codes
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, TwPostalCodeMessages>} [i18n] - Custom error messages for different locales
+ */
+type TwPostalCodeOptions<IsRequired extends boolean = true> = {
+    format?: TwPostalCodeFormatType;
+    strictValidation?: boolean;
+    allowDashes?: boolean;
+    warn5Digit?: boolean;
+    allowedPrefixes?: string[];
+    blockedPrefixes?: string[];
+    transform?: (value: string) => string;
+    defaultValue?: IsRequired extends true ? string : string | null;
+    i18n?: Partial<Record<Locale, Partial<TwPostalCodeMessages>>>;
+    strictSuffixValidation?: boolean;
+    deprecate5Digit?: boolean;
+};
+/**
+ * Type alias for postal code validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef TwPostalCodeSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
+type TwPostalCodeSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Valid 3-digit postal code prefixes for Taiwan
+ * Based on official Chunghwa Post data (2024)
+ */
+declare const VALID_3_DIGIT_PREFIXES: string[];
+/**
+ * Validates 3-digit Taiwan postal code
+ *
+ * @param {string} value - The 3-digit postal code to validate
+ * @param {boolean} strictValidation - Whether to validate against known postal code list
+ * @param {string[]} allowedPrefixes - Specific prefixes to allow (overrides strictValidation)
+ * @param {string[]} blockedPrefixes - Specific prefixes to block
+ * @returns {boolean} True if the postal code is valid
+ */
+declare const validate3DigitPostalCode: (value: string, strictValidation?: boolean, allowedPrefixes?: string[], blockedPrefixes?: string[]) => boolean;
+/**
+ * Validates 5-digit Taiwan postal code (legacy format)
+ *
+ * @param {string} value - The 5-digit postal code to validate
+ * @param {boolean} strictValidation - Whether to validate the 3-digit prefix
+ * @param {boolean} strictSuffixValidation - Whether to validate the 2-digit suffix
+ * @param {string[]} allowedPrefixes - Specific prefixes to allow
+ * @param {string[]} blockedPrefixes - Specific prefixes to block
+ * @returns {boolean} True if the postal code is valid
+ */
+declare const validate5DigitPostalCode: (value: string, strictValidation?: boolean, strictSuffixValidation?: boolean, allowedPrefixes?: string[], blockedPrefixes?: string[]) => boolean;
+/**
+ * Validates 6-digit Taiwan postal code (current format)
+ *
+ * @param {string} value - The 6-digit postal code to validate
+ * @param {boolean} strictValidation - Whether to validate the 3-digit prefix
+ * @param {boolean} strictSuffixValidation - Whether to validate the 3-digit suffix
+ * @param {string[]} allowedPrefixes - Specific prefixes to allow
+ * @param {string[]} blockedPrefixes - Specific prefixes to block
+ * @returns {boolean} True if the postal code is valid
+ */
+declare const validate6DigitPostalCode: (value: string, strictValidation?: boolean, strictSuffixValidation?: boolean, allowedPrefixes?: string[], blockedPrefixes?: string[]) => boolean;
+/**
+ * Main validation function for Taiwan postal codes
+ *
+ * @param {string} value - The postal code to validate
+ * @param {TwPostalCodeFormatType} format - Which formats to accept
+ * @param {boolean} strictValidation - Whether to validate against known postal codes
+ * @param {boolean} strictSuffixValidation - Whether to validate suffix ranges
+ * @param {boolean} allowDashes - Whether dashes/spaces are allowed and should be removed
+ * @param {string[]} allowedPrefixes - Specific prefixes to allow
+ * @param {string[]} blockedPrefixes - Specific prefixes to block
+ * @returns {boolean} True if the postal code is valid
+ */
+declare const validateTaiwanPostalCode: (value: string, format?: TwPostalCodeFormatType, strictValidation?: boolean, strictSuffixValidation?: boolean, allowDashes?: boolean, allowedPrefixes?: string[], blockedPrefixes?: string[]) => boolean;
+/**
+ * Creates a Zod schema for Taiwan postal code validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {TwPostalCodeOptions<IsRequired>} [options] - Configuration options for postal code validation
+ * @returns {TwPostalCodeSchema<IsRequired>} Zod schema for postal code validation
+ *
+ * @description
+ * Creates a comprehensive Taiwan postal code validator that supports multiple formats
+ * and provides extensive configuration options for different validation scenarios.
+ *
+ * Features:
+ * - 3-digit, 5-digit, and 6-digit postal code format support
+ * - Strict validation against official postal code ranges
+ * - Legacy 5-digit format with optional warnings
+ * - Custom prefix allowlist/blocklist support
+ * - Dash and space handling in postal codes
+ * - Automatic normalization and formatting
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ * - Optional field support
+ *
+ * @example
+ * ```typescript
+ * // Accept 3-digit or 6-digit formats (recommended)
+ * const modernSchema = twPostalCode()
+ * modernSchema.parse("100")     // ✓ Valid 3-digit
+ * modernSchema.parse("100001")  // ✓ Valid 6-digit
+ * modernSchema.parse("10001")   // ✗ Invalid (5-digit not allowed)
+ *
+ * // Accept all formats
+ * const flexibleSchema = twPostalCode(false, { format: "all" })
+ * flexibleSchema.parse("100")     // ✓ Valid
+ * flexibleSchema.parse("10001")   // ✓ Valid
+ * flexibleSchema.parse("100001")  // ✓ Valid
+ *
+ * // Only 6-digit format (current standard)
+ * const modernOnlySchema = twPostalCode(false, { format: "6" })
+ * modernOnlySchema.parse("100001") // ✓ Valid
+ * modernOnlySchema.parse("100")    // ✗ Invalid
+ *
+ * // With dashes allowed
+ * const dashSchema = twPostalCode(false, { allowDashes: true })
+ * dashSchema.parse("100-001")  // ✓ Valid (normalized to "100001")
+ * dashSchema.parse("100-01")   // ✓ Valid if 5-digit format allowed
+ *
+ * // Specific areas only
+ * const taipeiSchema = twPostalCode(false, {
+ *   allowedPrefixes: ["100", "103", "104", "105", "106"]
+ * })
+ * taipeiSchema.parse("100001") // ✓ Valid (Taipei area)
+ * taipeiSchema.parse("200001") // ✗ Invalid (not in allowlist)
+ *
+ * // Block specific areas
+ * const blockedSchema = twPostalCode(false, {
+ *   blockedPrefixes: ["999"] // Block test codes
+ * })
+ *
+ * // With warning for legacy format
+ * const warnSchema = twPostalCode(false, {
+ *   format: "all",
+ *   warn5Digit: true
+ * })
+ * // Will validate but may show warning for 5-digit codes
+ *
+ * // Optional with custom transformation
+ * const optionalSchema = twPostalCode(false, {
+ *   transform: (value) => value.replace(/\D/g, '') // Remove non-digits
+ * })
+ *
+ * // Strict suffix validation for real postal codes
+ * const strictSchema = twPostalCode(false, {
+ *   format: "6",
+ *   strictSuffixValidation: true // Validates suffix range 001-999
+ * })
+ * strictSchema.parse("100001") // ✓ Valid
+ * strictSchema.parse("100000") // ✗ Invalid (suffix 000 not allowed)
+ *
+ * // Deprecate 5-digit codes entirely
+ * const modern2024Schema = twPostalCode(false, {
+ *   format: "all",
+ *   deprecate5Digit: true // Throws error for any 5-digit code
+ * })
+ * modern2024Schema.parse("100001") // ✓ Valid 6-digit
+ * modern2024Schema.parse("10001")  // ✗ Error: deprecated format
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link TwPostalCodeOptions} for all available configuration options
+ * @see {@link TwPostalCodeFormatType} for supported formats
+ * @see {@link validateTaiwanPostalCode} for validation logic details
+ */
+declare function twPostalCode<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TwPostalCodeOptions<IsRequired>, 'required'>): TwPostalCodeSchema<IsRequired>;
+
+export { type TwPostalCodeFormatType, type TwPostalCodeMessages, type TwPostalCodeOptions, type TwPostalCodeSchema, VALID_3_DIGIT_PREFIXES, twPostalCode, validate3DigitPostalCode, validate5DigitPostalCode, validate6DigitPostalCode, validateTaiwanPostalCode };