phone

Build and validate phone numbers. The Phone primitive captures phone numbers with optional type classification and extension.

Examples

Creating phone numbers

// Object pattern
const phone = p.phone({
  number: '+14155552671'
})

// Builder pattern
const phone = p.phone()
  .number('+14155552671')
  .type('mobile')
  .extension('123')
  .build()

// Copy and modify
const updated = p.phone()
  .from(phone)
  .type('work')
  .build()

Parsing external data

// Parse unknown input (throws on error)
const phone = p.phone.parse(jsonData)

// Safe parsing (returns result object)
const result = p.phone.safeParse(jsonData)
if (result.success) {
  console.log(`Phone: ${result.data.number}`)
} else {
  console.error(result.error.message)
}

Using with forms

const form = p.form({
  name: 'contact',
  fields: {
    mobilePhone: { type: 'phone', label: 'Mobile Phone' },
    workPhone: { type: 'phone', label: 'Work Phone' }
  }
})

const filled = form.fill({
  fields: {
    mobilePhone: p.phone()
      .number('+14155552671')
      .type('mobile')
      .build(),
    workPhone: p.phone()
      .number('+14155551234')
      .type('work')
      .extension('567')
      .build()
  }
})

API

Object Pattern

p.phone(input: Phone): Phone

Pass a Phone object for validation. Returns the validated Phone or throws on error.

const phone = p.phone({ number: '+442071234567' })

Builder Pattern

Chain methods to build a Phone value incrementally:

All methods return PhoneBuilder and are chainable.

p.phone()

number: (value: string) => PhoneBuilder

Set phone number (E.164 format required)

type: (value: string | undefined) => PhoneBuilder

Set phone type (mobile, home, work, etc.)

extension: (value: string | undefined) => PhoneBuilder

Set extension number

from: (value: Phone) => PhoneBuilder

Initialize from existing Phone

build: () => Phone

Build and validate

Static Methods

parse: (input: unknown) => Phone

Parse unknown input (throws on error)

safeParse: (input: unknown) => Result<Phone>

Parse unknown input (returns result object)

Properties

number: string

Phone number. E.164 format required (+[country][number]).

type: string?

Type of phone (mobile, home, work, fax).

extension: string?

Extension number for business lines.

E.164 Format

Phone numbers must use E.164:

+[country code][subscriber number]

Country	Format	Example
USA/Canada	+1XXXXXXXXXX	+14155552671
UK	+44XXXXXXXXXX	+442071234567
Germany	+49XXXXXXXXX	+4930123456
Japan	+81XXXXXXXXX	+81312345678
Australia	+61XXXXXXXXX	+61212345678

Phone Types

Type	Description
`mobile`	Mobile/cell phone
`home`	Residential landline
`work`	Business/office line
`fax`	Fax machine
`other`	Other phone type

Validation

The Phone primitive validates:

number must be 8–16 characters, start with +, and otherwise contain digits
type and extension are optional

// Valid
p.phone({ number: '+14155552671' })
p.phone({
  number: '+14155552671',
  type: 'mobile'
})
p.phone({
  number: '+14155551234',
  type: 'work',
  extension: '567'
})

// Invalid - throws Error
p.phone({})

p.phone({ number: '' })

Primitives Overview - All available primitives
Address - Physical address
Phone Field - Phone field type
Phone Schema - JSON Schema definition

phone
Last updated on