joaocarmo
i18n-postal-address
A JavaScript library to produce international postal addresses formatted by region for Node.js and the web.
Try it out in the playground!
Installation
npm install i18n-postal-address
# or
pnpm add i18n-postal-addressUsage
As an ESM module (web)
Load i18n-postal-address directly from skypack (CDN).
<script type="module">
import PostalAddress from 'https://cdn.skypack.dev/i18n-postal-address'
</script>Demo available in codepen.
On the web (self-hosted)
It's exposed through the window global object as explained below.
index.html
<head>
<script type="text/javascript" src="./postal-address.js"></script>
<script type="text/javascript" src="./app.js"></script>
</head>app.js
// Define myAddress
var PostalAddress = window.PostalAddress.default
var myAddress = new PostalAddress()
// ...With a bundler / Node.js
With a bundler (e.g. webpack) or in Node.js you can just require / import it.
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.
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()
[ [ 'Mr.', 'John', 'Lopes' ],
[ 'Pestana' ],
[ 'Rua do Pastel, 19' ],
[ '2700-242', 'Aveiro' ],
[ 'Portugal' ] ]toString()
Mr. John Lopes
Pestana
Rua do Pastel, 19
2700-242 Aveiro
PortugalAvailable Class Methods
Address Attributes
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)Options
These affect the output format
/*
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 })Custom Formats
Additional formats can be added or existing ones can be replaced
/*
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
address1
address2
addressNum
city
companyName
country
countryAlpha2
do
dong
firstLastName
firstName
gu
honorific
jobTitle
lastName
postalCode
prefecture
province
region
republic
secondLastName
secondName
si
state
titleExperimental 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.
libpostal
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:
- Install libpostal following their installation instructions, or execute this script if you're on a *nix machine.
- Install 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
libpostalfeatures.
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.
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())Barboncino 781 Franklin Ave
Crown Heights Brooklyn
NY 11238Background
Why
The 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, ...).
Inspiration
Disclaimer: It doesn't mean this library tries to recreate any of these
MSDN > ... > Globalization and Localization > Appendix V International Address Formats
Forking / Contributing
Build
pnpm buildTest
pnpm test:unit
pnpm test:functional