# address

Build and validate postal addresses

Canonical URL: https://docs.paradoc.dev/sdk/primitives/address/

Build and validate postal addresses with structured components. The Address primitive provides a standardized structure for capturing location information.

## Examples

### Creating addresses

```ts
// Object pattern
const addr = p.address({
  line1: '123 Main Street',
  locality: 'New York',
  region: 'NY',
  postalCode: '10001',
  country: 'US'
})

// Builder pattern
const addr = p.address()
  .line1('123 Main Street')
  .line2('Suite 400')
  .locality('New York')
  .region('NY')
  .postalCode('10001')
  .country('US')
  .build()

// Copy and modify
const updated = p.address()
  .from(addr)
  .line2('Suite 500')
  .build()
```

### Parsing external data

```ts
// Parse unknown input (throws on error)
const addr = p.address.parse(jsonData)

// Safe parsing (returns result object)
const result = p.address.safeParse(jsonData)
if (result.success) {
  console.log(`${result.data.locality}, ${result.data.region}`)
} else {
  console.error(result.error.message)
}
```

### Using with forms

```ts
const form = p.form({
  name: 'shipping',
  fields: {
    shippingAddress: { type: 'address', label: 'Shipping Address' }
  }
})

const filled = form.fill({
  fields: {
    shippingAddress: p.address()
      .line1('456 Oak Avenue')
      .locality('Los Angeles')
      .region('CA')
      .postalCode('90001')
      .country('US')
      .build()
  }
})
```

## API

### Object Pattern

```ts
p.address(input: Address): Address
```

Pass an Address object for validation. Returns the validated Address or throws on error.

```ts
const addr = p.address({
  line1: '123 Main St',
  locality: 'Boston',
  region: 'MA',
  postalCode: '02101',
  country: 'US'
})
```

### Builder Pattern

Chain methods to build an Address value incrementally:

Start with `p.address()`. Each method returns `AddressBuilder` and can be chained.

| Method | Description |
| --- | --- |
| `line1(value: string)` | Set primary street address |
| `line2(value: string \| undefined)` | Set secondary address (apt, suite) |
| `locality(value: string)` | Set city or town |
| `region(value: string)` | Set state, province, or region |
| `postalCode(value: string)` | Set postal or ZIP code |
| `country(value: string)` | Set country code (ISO 3166-1 alpha-2) |
| `from(value: Address)` | Initialize from existing Address |

Terminal methods return `Address`.

| Method | Description |
| --- | --- |
| `build()` | Build and validate |

### Static Methods

| Method | Returns | Description |
| --- | --- | --- |
| `parse(input: unknown)` | `Address` | Parse unknown input (throws on error) |
| `safeParse(input: unknown)` | `Result<Address>` | Parse unknown input (returns result object) |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `line1` | `string` | Primary street address line. |
| `line2` | `string?` | Secondary address line (apartment, suite, unit). |
| `locality` | `string` | City, town, or locality name. |
| `region` | `string` | State, province, or region. |
| `postalCode` | `string` | Postal code or ZIP code. |
| `country` | `string` | Country code (ISO 3166-1 alpha-2 recommended). |

## Validation

The Address primitive validates:

* `line1` must be 1–200 characters
* `locality` must be 1–200 characters
* `region` must be 1–100 characters
* `postalCode` must be 3–20 uppercase letters, digits, spaces, or hyphens
* `country` must be 2–100 characters
* `line2` is optional and at most 200 characters

```ts
// Valid
p.address({
  line1: '123 Main St',
  locality: 'NYC',
  region: 'NY',
  postalCode: '10001',
  country: 'US'
})

// With optional line2
p.address({
  line1: '123 Main St',
  line2: 'Apt 4B',
  locality: 'NYC',
  region: 'NY',
  postalCode: '10001',
  country: 'US'
})

// Invalid - throws Error
p.address({ line1: '123 Main St' })
```

## Related

* [Primitives Overview](/sdk/primitives) - All available primitives
* [Address Field](/sdk/artifacts/form/field#entity) - Address field type
* [Address Schema](/schemas/primitives/address) - JSON Schema definition