@recipher/i18n-postal-address

v0.8.12

Published

a year ago

A JavaScript library to produce international postal addresses formatted by region for node and the web

Downloads

386

0High
0Medium
0Low

recipher

address formatter i18n node postal web

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

yarn add i18n-postal-address

Usage

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
Portugal

Available 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
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.

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 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.

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 11238

Background

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

Query Address Data

PostalAddress

Forking / Contributing

Build

yarn build

Test

yarn test:unit

yarn test:functional