@nodii/address

The canonical postal Address value-object + validator for the Nodii stack. A pure value-object library (no I/O): a type, a validator, and PII-field tagging. Geocoding / distributor resolution is not here — that stays in nodii-geo-service.

import {
  validateAddress,
  isValidAddress,
  AddressInvalid,
  ADDRESS_PII_FIELDS,
  type Address,
} from "@nodii/address";

const addr = validateAddress({
  line1: "221B Baker St",
  city: "London",
  country_code: "gb", // upper-cased to "GB"
});
// → { line1: "221B Baker St", city: "London", country_code: "GB" }

try {
  validateAddress({ line1: "x", city: "y", country_code: "ZZ" });
} catch (e) {
  if (e instanceof AddressInvalid) {
    e.code; // "ADDRESS_INVALID" → map to CUSTOMER_ADDRESS_INVALID
    e.reason; // "COUNTRY_CODE_INVALID"
    e.field; // "country_code"
  }
}

Shape

{ label?, line1, line2?, city, region?, postal_code?, country_code } — matches the gRPC Address message. country_code is ISO-3166-1 alpha-2 (validated against the assigned set). Required: line1, city, country_code.

Validation

validateAddress(input) trims string fields, upper-cases country_code, drops empty optionals, and throws AddressInvalid (.code, .reason, .field) on a missing required field or an invalid country code. isValidAddress is the non-throwing variant. Per-country postal/region format rules are intentionally out of scope (geo-service owns those).

PII

ADDRESS_PII_FIELDS lists the fields that are PII (line1, line2, city, region, postal_code) and must be encrypted under the owning subject's DEK at rest by the consumer (via @nodii/pii). label and country_code are not PII. This library never stores or encrypts.

Shipped in parity with nodii-address (Python) and nodii.co/nodii-libs/go/address.