Functional Weave
Code in Python

form.address@1.0.0

README.md

3,394 bytes · view raw

# form.address

The checks behind an address form, in TypeScript, Python and Rust, so the
browser and the API refuse the same addresses with the same words
(`react.form.address-fields` renders the form and shows these errors).

- **`validateAddress(address)`** checks every field and returns all the errors
  at once, in form order (line1, line2, town, region, postcode, country), each
  naming the field to mark. When valid it returns the address to store:
  trimmed, empty optional lines as `null`, the country code upper case, and
  the postcode in its standard form (`sw1a2aa` is `SW1A 2AA`). It never
  throws: an unknown or missing country is the country field's error.
- **`addressFormat(country)`** says how the form for a country asks: the label
  for its postcode (Postcode, ZIP code, PIN code, Eircode, Postal code) and its
  region (County, State, Province, Prefecture, Canton...), whether the postcode
  is required, an example for the hint, and whether the UK pattern applies. It
  throws `unknown country` for a code that is not ISO 3166-1 alpha-2.

## The rules

| Field | Rule | Message |
|-------|------|---------|
| line1 | required, at most 100 characters | Enter address line 1, typically the building and street |
| line2 | optional, at most 100 | Address line 2 must be 100 characters or less |
| town | required, at most 100 | Enter town or city |
| region | optional, at most 100 | `<regionLabel>` must be 100 characters or less |
| postcode | required where `postcodeRequired`; the country's format | Enter postcode / Enter a real ZIP code |
| country | one of the 249 ISO 3166-1 alpha-2 codes | Select a country |

The wording is the GOV.UK Design System's address pattern. Lengths count
Unicode code points, so "Zürich" is 6. Whitespace trimmed is ASCII only, the
same in every language.

**UK postcodes** (GB and the Crown Dependencies GG, JE and IM, which use Royal
Mail's format) are checked and normalised by `validation.uk-postcode`, so the
letter rules it knows apply, and GIR 0AA is accepted.

**Other countries**: the postcode's ASCII letters are upper-cased (spacing is
kept as typed), then matched against the country's pattern in
`data/countries.json` with `text.pattern-match`, the same subset of regular
expressions a browser's `pattern` attribute takes, so the component can put the
pattern on the input too. 45 countries have a pattern (US, CA, the EU
states, AU, NZ, IN, JP, CN, BR, MX, ZA, SG, KR...). A country without one
accepts 1 to 12 letters, digits, spaces and hyphens, and does not require a
postcode. Ireland's Eircode is optional, as most Irish forms make it.

## What it does not do

A well-formed address is not a real one: this checks shape, not existence. Only
an address lookup (Royal Mail PAF in the UK, USPS, Eircode's finder) can say
an address exists; it is network work, and a gap in the `forms` suite. Address
lines are not split or reordered for a country's postal format, and a region is
free text, not checked against a list of states.

Country names are the English short names from ISO 3166-1 (`Türkiye`,
`Côte d'Ivoire`, `Korea` as `South Korea`).

## Notices

Error message wording follows the GOV.UK Design System. Portions derived from GOV.UK Frontend (https://github.com/alphagov/govuk-frontend), Copyright (c) 2017 Crown Copyright (Government Digital Service), under the MIT License; the full notice is in NOTICE.