zod-ph

Philippine‑ready Zod validators and formatters for TypeScript applications.

Installation

npm install zod zod-ph

Quickstart

import { z } from 'zod';
import { phMobileNumber, phZipCode, phPesoAmount } from 'zod-ph';

const schema = z.object({
  mobile: phMobileNumber(),
  zip: phZipCode(),
  amount: phPesoAmount(),
});

// parse() throws if invalid
const data = schema.parse({
  mobile: '09171234567',
  zip: '6000',
  amount: 1250,
});

API Reference

Validators

All validators return a Zod schema that you can use with z.object(), z.string(), etc.

phMobileNumber(options?)

Validates Philippine mobile numbers.

Accepted formats
09xxxxxxxxx, +639xxxxxxxxx, 639xxxxxxxxx (plain digits, no dashes or spaces).

Parameters

| Option | Type | Default | Description | |----------|----------|-------------------------------------------|----------------------------| | message | string | 'Invalid Philippine mobile number' | Custom error message |

Returns
z.ZodString – refines the string using a regex.

Example

const schema = phMobileNumber();
schema.parse('09171234567');           // ok
schema.parse('+639171234567');         // ok
schema.parse('0917-123-4567');         // throws (dashes not allowed)

phLandline(options?)

Validates Philippine landline numbers. Supports area codes of 1–3 digits and subscriber numbers of 7–8 digits. Rejects mobile numbers (starting with 09).

Accepted formats
0281234567, (02) 8123 4567, 032-123-4567, +63 2 8123 4567.

Parameters

| Option | Type | Default | Description | |----------|----------|-------------------------------------------|----------------------------| | message | string | 'Invalid Philippine landline number' | Custom error message |

Returns
z.ZodString

Example

phLandline().parse('(02) 8123 4567');  // ok
phLandline().parse('09171234567');      // throws (mobile number)

phZipCode()

Validates a 4‑digit Philippine ZIP code. Does not check if the ZIP code actually exists.

Returns
z.ZodString – matches ^\\d{4}$

Example

phZipCode().parse('6000');   // ok
phZipCode().parse('123');    // throws

phPesoAmount()

Validates a Philippine peso amount as a positive number with at most two decimal places.

Returns
z.ZodNumber

Example

phPesoAmount().parse(1250);      // ok
phPesoAmount().parse(100.25);    // ok
phPesoAmount().parse(100.123);   // throws (more than 2 decimals)
phPesoAmount().parse(-5);        // throws (negative)

phCoordinates(options?)

Validates a { lat: number; lng: number } object. Can optionally check that the coordinates fall within the approximate Philippine bounding box (lat 4.5–21.5, lng 116–127).

Parameters

| Option | Type | Default | Description | |-----------------------------|-----------|---------|-----------------------------------------------| | requireInsidePhilippines | boolean | false | If true, restricts to PH approximate bounds |

Returns
z.ZodObject<{ lat: z.ZodNumber; lng: z.ZodNumber }>

Example

const inPH = phCoordinates({ requireInsidePhilippines: true });
inPH.parse({ lat: 14.5, lng: 121 });   // ok
inPH.parse({ lat: 0, lng: 121 });      // throws

phPersonName()

Validates a person name string. It must be trimmed, have no consecutive spaces, and only contain letters, hyphens, periods, apostrophes, and Ñ/ñ.

Returns
z.ZodString – min 1, max 200 characters.

Example

phPersonName().parse('Juan Dela Cruz');   // ok
phPersonName().parse('  Juan  ');         // throws (leading/trailing spaces)
phPersonName().parse('Juan  Dela');       // throws (double space)

Formatters

Formatters do not return Zod schemas; they transform or display values.

formatPeso(value, options?)

Formats a number as a Philippine peso string.

Parameters

| Option | Type | Default | Description | |-------------------------|-----------|---------|-----------------------------------| | value | number | required| Amount in decimal pesos | | options.symbol | string | '₱' | Currency symbol | | options.minimumFractionDigits | number | 2 | Minimum decimal places | | options.maximumFractionDigits | number | 2 | Maximum decimal places | | options.useGrouping | boolean | true | Whether to use thousands separators |

Returns
string

Example

formatPeso(1250);                            // "₱1,250.00"
formatPeso(1250, { minimumFractionDigits: 0 }); // "₱1,250"
formatPeso(1250.5);                          // "₱1,250.50"

normalizePHMobileNumber(input, format?)

Normalises a Philippine mobile number to a standard format. Throws if the input is invalid.

Parameters

| input | string | required | Raw mobile number (can include dashes, spaces, etc.) | | format | 'e164' \| 'local' \| 'digits' | 'e164' | Desired output format |

Returns
string

Example

normalizePHMobileNumber('0917-123-4567');           // "+639171234567"
normalizePHMobileNumber('+639171234567', 'local');  // "0917 123 4567"
normalizePHMobileNumber('09171234567', 'digits');   // "639171234567"

formatPHAddress(components)

Combines address components into a single display string.

Parameters

components object with optional fields:

• line1?: string
• line2?: string
• barangay?: string
• cityMunicipality?: string
• province?: string
• zipCode?: string
• region?: string

Returns
string

Example

formatPHAddress({
  line1: '123 Mabini St.',
  barangay: 'Lahug',
  cityMunicipality: 'Cebu City',
  province: 'Cebu',
  zipCode: '6000',
});
// "123 Mabini St., Brgy. Lahug, Cebu City, Cebu, 6000"

normalizeName(name)

Trims whitespace and collapses multiple spaces into one. Does not alter case.

Returns
string

Example

normalizeName('  Juan   Dela   Cruz  ');   // "Juan Dela Cruz"

Limitations

• Government ID validators (TIN, SSS, PhilHealth, etc.) are not included in this version. When added, they will check format only—they cannot verify official records.
• Coordinates are validated against an approximate bounding box. The library does not contain exact Philippine polygon boundaries.
• ZIP code validation checks the format (4 digits) but not actual existence.
• The package is under active development. Data‑based features (PSGC regions, provinces, barangays) will come in later releases.

Contributing

See CONTRIBUTING.md for guidelines. All validators must include unit tests using Vitest.

License

MIT – see LICENSE.