NASA Planetary Mission

    i18n-postal-address
    TypeScript icon, indicating that this package has built-in type declarations

    0.7.0 • Public • Published

    i18n-postal-address

    npm version Tests Total alerts Language grade: JavaScript

    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.

    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.

    Requirements

    1. Install libpostal following their installation instructions, or execute this script if you're on a *nix machine
    2. Install node-postal as a dependency in your project, after installing libpostal

    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

    Install

    npm i i18n-postal-address

    DownloadsWeekly Downloads

    4,065

    Version

    0.7.0

    License

    MIT

    Unpacked Size

    251 kB

    Total Files

    19

    Last publish

    Collaborators

    • joaocarmo