eircode-js v0.1.4

EircodeJS

EircodeJS is a JavaScript library for parsing and validating Eircodes (Irish postcodes).

EircodeJS has the following goals:

Methods

Using the static Eircode.parse method we can parse some input:

var EircodeJS = require('eircode-js');
var result = EircodeJS.parse('A65F4E2');

This will return a ParseResult object.

With ParseResult you can check if the Eircode is valid and access its parts:

if (result.hasEircode()) {
    console.log('Routing Key = ', result.routingKey());
    console.log('Unique Identifier = ', result.uniqueIdentifier());
}

You can get a plain object containing all the parsed properties using toJSON:

console.log(result.toJSON());

This will output something like:

{
    hasEircode: true,
    eircode: 'A65F4E2',
    hasRoutingKey: true,
    routingKey: 'A65',
    hasUniqueIdentifier: true,
    uniqueIdentifier: 'F4E2',
    error: null,
    logs: []
}

The properties on the object (and the matching methods on ParseResult) are:

An example error object is the following:

{
    message: 'Unique Identifier cannot contain "!"',
    inputPos: 5,
    outputPos: 4
}

In this example inputPos differs from outputPos because a whitespace character in the input was skipped over.

The error object contains the following properties:

Browser Support

EircodeJS should work in all environments with a decent JavaScript runtime.

An issue in the following browsers is considered a bug in EircodeJS:

• The last two versions of Chrome, Firefox, Safari and Opera
• The mobile browsers in jQuery Mobile's A-grade list
• Internet Explorer 6 and later

Note that these guarantees don't apply to secondary resources such as the demo site, examples or integrations with other validation libraries.

Eircode Specification

I have compiled the following unofficial Eircode specification based on the information that's been released to date (see References).

An example of a valid Eircode is:

• A65F4E2

In this example:

• A65 is the Routing Key
• F4E2 is the Unique Identifier

The Routing Key:

• Begins with an allowed letter
• Followed by two digits

The only exception is 'D6W' which is a valid Routing Key.

The Unique Identifier:

• Contains four allowed characters

An allowed character is either an allowed letter or a digit.

An allowed letter is an alphabetic character, excluding:

• B, G, I, J, L, M, O, Q, S, U, Z

A digit is any of 0 to 9.

Terminology

A valid Eircode, Routing Key or Unique Identifier follows the patterns laid out in the specification. Note that a valid Eircode may be unused in real life, may have been discontinued, may map to a geographic area without any dwellings, etc. Checking if an Eircode is deliverable is different to checking if it is valid.

The canonical form of an Eircode has letters uppercased and spaces and non-valid characters removed. For example, A65F4E2 is the canonical form of both a65 F4E2 and A-65-F4E2. The ParseResult properties routingKey, uniqueIdentifier and eircode will always contain either the canonical form or an empty string (if invalid).

References

• Eircode is the name of Ireland’s new national postcode system (Fretwell.ie)
• Prepare your business for Eircode (Eircode.ie)

License

This project is released under the MIT License.

Attribution is appreciated but not required.