i18n-postal-address

!Tests

A JavaScript library to produce international postal addresses formatted by
region for Node.js and the web.

Try it out in the [playground]!

Installation

``sh
npm install i18n-postal-address

or

pnpm add i18n-postal-address
`

Usage

$3

Load i18n-postal-address directly from [skypack][skypack] (CDN).

`html

`

Demo available in [codepen][codepen].

$3

It's exposed through the _window_ global object as explained below.

index.html

`html




`

app.js

`js
// Define myAddress
var PostalAddress = window.PostalAddress.default
var myAddress = new PostalAddress()

// ...
`

$3

With a bundler (e.g. webpack) or in Node.js you can just require / import it.

`js
import PostalAddress from 'i18n-postal-address'

// Define myAddress
const myAddress = new PostalAddress()
`

Example

The methods can be chained one after the other for a cleaner code.

`js
const myAddressPersonal = new PostalAddress()

myAddressPersonal
.setAddress1('Rua do Pastel, 19')
.setCity('Aveiro')
.setCountry('Portugal')
.setFirstName('John')
.setHonorific('Mr.')
.setLastName('Pestana')
.setPostalCode('2700-242')
.setSecondName('Lopes')
.setFormat({
country: 'AR',
type: 'personal',
})

console.log(myAddressPersonal.toArray())

console.log(myAddressPersonal.toString())
`

toArray()

`txt
[ [ 'Mr.', 'John', 'Lopes' ],
[ 'Pestana' ],
[ 'Rua do Pastel, 19' ],
[ '2700-242', 'Aveiro' ],
[ 'Portugal' ] ]
`

toString()

`txt
Mr. John Lopes
Pestana
Rua do Pastel, 19
2700-242 Aveiro
Portugal
`

Available Class Methods

$3

`js
setAddress1(string)
setAddress2(string)
setAddressNum(string)
setCity(string)
setCompanyName(string)
setCountry(string)
setDo(string)
setDong(string)
setFirstLastName(string)
setFirstName(string)
setGu(string)
setHonorific(string)
setJobTitle(string)
setLastName(string)
setPostalCode(string)
setPrefecture(string)
setProvince(string)
setRegion(string)
setRepublic(string)
setSecondLastName(string)
setSecondName(string)
setSi(string)
setState(string)
setTitle(string)
`

$3

These affect the output format

`js
/*
Input one country and one type,
Define whether text transformations should be executed

country: 'CA' | ...
type: 'business' | 'english' | 'default' | 'french' | 'personal'
useTransforms: true | false
*/

const postalAddress = new PostalAddress()

postalAddress.setFormat({ country, type, useTransforms })
`

$3

Additional formats can be added or existing ones can be replaced

`js
/*
The country should be an uppercase ISO 3166-1 alpha-2 code

The format should be an array of array of strings or objects
- The strings should be valid attribute names
- The objects should contain the attribute (required)
- The objects may contain an array of transforming functions that will be
applied sequentially over the given attribute with the following signature
(string) => string
*/

const addCommaAfter = (value) => ${value},

const postalAddress = new PostalAddress()

postalAddress.addFormat({
country: 'PT',
format: [
[{ attribute: 'lastName', transforms: [addCommaAfter] }, 'firstName'],
['city', 'postalCode'],
['country'],
],
})
`

#### Valid attributes

`txt
address1
address2
addressNum
city
companyName
country
countryAlpha2
do
dong
firstLastName
firstName
gu
honorific
jobTitle
lastName
postalCode
prefecture
province
region
republic
secondLastName
secondName
si
state
title
`

Experimental string parsing

If you're interested in parsing a string into an object, you can use the new
experimental support for parsing addresses using some existing libraries.
However, note that these are optional and not required for the primary
functionality of this library.

$3

This is the most complete and comprehensive library for parsing addresses. You
need to be using the node version as it's not supported on the web.

#### Optional Requirements for libpostal Support

If you wish to utilize the libpostal experimental features, follow these
steps:

1. Install [libpostal][libpostal] following their installation instructions, or
execute [this script][install-libpostal] if you're on a \*nix machine.
2. Install [node-postal][node-postal] as an optional dependency in your
project, _after installing libpostal_. This is not required for the core
functionality but only if you want to use the libpostal features.

Remember, these steps are optional and are only for users interested in the
experimental string parsing feature.

#### Experimental usage

Notice the import is slightly different, you should import this library as
i18n-postal-address/strings.

`js
const PostalAddress = require('i18n-postal-address/strings').default

const postalAddress = new PostalAddress()

postalAddress.fromString(
'Barboncino 781 Franklin Ave, Crown Heights, Brooklyn, NY 11238',
)

console.log(postalAddress.toString())
`

`txt
Barboncino 781 Franklin Ave
Crown Heights Brooklyn
NY 11238
`

Background

$3

The [libpostal][libpostal] library is not available on the web.

Need to present postal addresses for different regions worldwide stored in
individual parts (company name, address, postal code, city, county, country,
...).

$3

Disclaimer: It doesn't mean this library tries to recreate any of these

MSDN > ... > Globalization and Localization >
[Appendix V International Address Formats][msappendix]

[Query Address Data][qad]

[PostalAddress][pa]

Forking / Contributing

Build

`sh
pnpm build
`

Test

`sh
pnpm test:unit

pnpm test:functional
``

[codepen]: https://codepen.io/joaocarmo/pen/bGeOVQw
[install-libpostal]: ./scripts/install-libpostal.sh
[libpostal]: https://github.com/openvenues/libpostal
[msappendix]: https://msdn.microsoft.com/en-us/library/cc195167.aspx
[node-postal]: https://github.com/openvenues/node-postal
[pa]: https://schema.org/PostalAddress
[playground]: https://joaocarmo.com/i18n-postal-address-playground
[qad]: http://i18napis.appspot.com/address
[skypack]: https://skypack.dev