{"id":20573315,"url":"https://github.com/joaocarmo/i18n-postal-address","last_synced_at":"2025-04-05T15:05:42.701Z","repository":{"id":32681990,"uuid":"137814056","full_name":"joaocarmo/i18n-postal-address","owner":"joaocarmo","description":"A JavaScript library to produce international postal addresses formatted by region","archived":false,"fork":false,"pushed_at":"2025-03-17T21:28:48.000Z","size":1673,"stargazers_count":29,"open_issues_count":10,"forks_count":11,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T14:06:39.071Z","etag":null,"topics":["i18n","javascript","js","node","nodejs","postal-addresses"],"latest_commit_sha":null,"homepage":"https://joaocarmo.com/i18n-postal-address-playground","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joaocarmo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-18T22:40:32.000Z","updated_at":"2025-01-11T16:30:21.000Z","dependencies_parsed_at":"2023-12-25T22:26:27.230Z","dependency_job_id":"a6b5d98b-426b-43d9-b6ad-9c1bb65ead22","html_url":"https://github.com/joaocarmo/i18n-postal-address","commit_stats":{"total_commits":73,"total_committers":6,"mean_commits":"12.166666666666666","dds":0.452054794520548,"last_synced_commit":"ff2681218aee47f4ec2019d0c185907f04c55e3b"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaocarmo%2Fi18n-postal-address","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaocarmo%2Fi18n-postal-address/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaocarmo%2Fi18n-postal-address/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaocarmo%2Fi18n-postal-address/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joaocarmo","download_url":"https://codeload.github.com/joaocarmo/i18n-postal-address/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353731,"owners_count":20925329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["i18n","javascript","js","node","nodejs","postal-addresses"],"created_at":"2024-11-16T05:26:55.621Z","updated_at":"2025-04-05T15:05:42.682Z","avatar_url":"https://github.com/joaocarmo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# i18n-postal-address\n\n[![npm version](https://badge.fury.io/js/i18n-postal-address.svg)](https://badge.fury.io/js/i18n-postal-address)\n![Tests](https://github.com/joaocarmo/i18n-postal-address/workflows/Tests/badge.svg)\n\nA JavaScript library to produce international postal addresses formatted by\nregion for Node.js and the web.\n\n**Try it out in the [playground]!**\n\n## Installation\n\n```sh\nnpm install i18n-postal-address\n\n# or\n\npnpm add i18n-postal-address\n```\n\n## Usage\n\n### As an ESM module (web)\n\nLoad **i18n-postal-address** directly from [skypack][skypack] (CDN).\n\n```html\n\u003cscript type=\"module\"\u003e\n  import PostalAddress from 'https://cdn.skypack.dev/i18n-postal-address'\n\u003c/script\u003e\n```\n\nDemo available in [codepen][codepen].\n\n### On the web (self-hosted)\n\nIt's exposed through the _window_ global object as explained below.\n\n`index.html`\n\n```html\n\u003chead\u003e\n  \u003cscript type=\"text/javascript\" src=\"./postal-address.js\"\u003e\u003c/script\u003e\n  \u003cscript type=\"text/javascript\" src=\"./app.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n```\n\n`app.js`\n\n```js\n// Define myAddress\nvar PostalAddress = window.PostalAddress.default\nvar myAddress = new PostalAddress()\n\n// ...\n```\n\n### With a bundler / Node.js\n\nWith a bundler (e.g. webpack) or in Node.js you can just require / import it.\n\n```js\nimport PostalAddress from 'i18n-postal-address'\n\n// Define myAddress\nconst myAddress = new PostalAddress()\n```\n\n## Example\n\nThe methods can be chained one after the other for a cleaner code.\n\n```js\nconst myAddressPersonal = new PostalAddress()\n\nmyAddressPersonal\n  .setAddress1('Rua do Pastel, 19')\n  .setCity('Aveiro')\n  .setCountry('Portugal')\n  .setFirstName('John')\n  .setHonorific('Mr.')\n  .setLastName('Pestana')\n  .setPostalCode('2700-242')\n  .setSecondName('Lopes')\n  .setFormat({\n    country: 'AR',\n    type: 'personal',\n  })\n\nconsole.log(myAddressPersonal.toArray())\n\nconsole.log(myAddressPersonal.toString())\n```\n\n`toArray()`\n\n```txt\n[ [ 'Mr.', 'John', 'Lopes' ],\n  [ 'Pestana' ],\n  [ 'Rua do Pastel, 19' ],\n  [ '2700-242', 'Aveiro' ],\n  [ 'Portugal' ] ]\n```\n\n`toString()`\n\n```txt\nMr. John Lopes\nPestana\nRua do Pastel, 19\n2700-242 Aveiro\nPortugal\n```\n\n## Available Class Methods\n\n### Address Attributes\n\n```js\nsetAddress1(string)\nsetAddress2(string)\nsetAddressNum(string)\nsetCity(string)\nsetCompanyName(string)\nsetCountry(string)\nsetDo(string)\nsetDong(string)\nsetFirstLastName(string)\nsetFirstName(string)\nsetGu(string)\nsetHonorific(string)\nsetJobTitle(string)\nsetLastName(string)\nsetPostalCode(string)\nsetPrefecture(string)\nsetProvince(string)\nsetRegion(string)\nsetRepublic(string)\nsetSecondLastName(string)\nsetSecondName(string)\nsetSi(string)\nsetState(string)\nsetTitle(string)\n```\n\n### Options\n\nThese affect the output format\n\n```js\n/*\n  Input one country and one type,\n  Define whether text transformations should be executed\n\n  country: 'CA' | ...\n  type: 'business' | 'english' | 'default' | 'french' | 'personal'\n  useTransforms: true | false\n*/\n\nconst postalAddress = new PostalAddress()\n\npostalAddress.setFormat({ country, type, useTransforms })\n```\n\n### Custom Formats\n\nAdditional formats can be added or existing ones can be replaced\n\n```js\n/*\n  The country should be an uppercase ISO 3166-1 alpha-2 code\n\n  The format should be an array of array of strings or objects\n    - The strings should be valid attribute names\n    - The objects should contain the attribute (required)\n    - The objects may contain an array of transforming functions that will be\n      applied sequentially over the given attribute with the following signature\n        (string) =\u003e string\n*/\n\nconst addCommaAfter = (value) =\u003e `${value},`\n\nconst postalAddress = new PostalAddress()\n\npostalAddress.addFormat({\n  country: 'PT',\n  format: [\n    [{ attribute: 'lastName', transforms: [addCommaAfter] }, 'firstName'],\n    ['city', 'postalCode'],\n    ['country'],\n  ],\n})\n```\n\n#### Valid attributes\n\n```txt\naddress1\naddress2\naddressNum\ncity\ncompanyName\ncountry\ncountryAlpha2\ndo\ndong\nfirstLastName\nfirstName\ngu\nhonorific\njobTitle\nlastName\npostalCode\nprefecture\nprovince\nregion\nrepublic\nsecondLastName\nsecondName\nsi\nstate\ntitle\n```\n\n## Experimental string parsing\n\nIf you're interested in parsing a string into an object, you can use the new\nexperimental support for parsing addresses using some existing libraries.\nHowever, note that these are optional and not required for the primary\nfunctionality of this library.\n\n### libpostal\n\nThis is the most complete and comprehensive library for parsing addresses. You\nneed to be using the **node** version as it's not supported on the web.\n\n#### Optional Requirements for libpostal Support\n\nIf you wish to utilize the `libpostal` experimental features, follow these\nsteps:\n\n1. Install [libpostal][libpostal] following their installation instructions, or\n   execute [this script][install-libpostal] if you're on a \\*nix machine.\n2. Install [node-postal][node-postal] as an **optional** dependency in your\n   project, _after installing libpostal_. This is not required for the core\n   functionality but only if you want to use the `libpostal` features.\n\nRemember, these steps are optional and are only for users interested in the\nexperimental string parsing feature.\n\n#### Experimental usage\n\nNotice the import is slightly different, you should import this library as\n`i18n-postal-address/strings`.\n\n```js\nconst PostalAddress = require('i18n-postal-address/strings').default\n\nconst postalAddress = new PostalAddress()\n\npostalAddress.fromString(\n  'Barboncino 781 Franklin Ave, Crown Heights, Brooklyn, NY 11238',\n)\n\nconsole.log(postalAddress.toString())\n```\n\n```txt\nBarboncino 781 Franklin Ave\nCrown Heights Brooklyn\nNY 11238\n```\n\n## Background\n\n### Why\n\nThe [libpostal][libpostal] library is not available on the web.\n\nNeed to present postal addresses for different regions worldwide stored in\nindividual parts (company name, address, postal code, city, county, country,\n...).\n\n### Inspiration\n\n**Disclaimer:** It doesn't mean this library tries to recreate any of these\n\nMSDN \u003e ... \u003e Globalization and Localization \u003e\n[Appendix V International Address Formats][msappendix]\n\n[Query Address Data][qad]\n\n[PostalAddress][pa]\n\n## Forking / Contributing\n\nBuild\n\n```sh\npnpm build\n```\n\nTest\n\n```sh\npnpm test:unit\n\npnpm test:functional\n```\n\n\u003c!-- References --\u003e\n\n[codepen]: https://codepen.io/joaocarmo/pen/bGeOVQw\n[install-libpostal]: ./scripts/install-libpostal.sh\n[libpostal]: https://github.com/openvenues/libpostal\n[msappendix]: https://msdn.microsoft.com/en-us/library/cc195167.aspx\n[node-postal]: https://github.com/openvenues/node-postal\n[pa]: https://schema.org/PostalAddress\n[playground]: https://joaocarmo.com/i18n-postal-address-playground\n[qad]: http://i18napis.appspot.com/address\n[skypack]: https://skypack.dev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoaocarmo%2Fi18n-postal-address","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoaocarmo%2Fi18n-postal-address","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoaocarmo%2Fi18n-postal-address/lists"}