eircode-js
v0.1.4
Published
A JavaScript library for working with Eircodes
Downloads
118
Maintainers
Readme
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:
| Name | Type | Description |
| --- | --- | ----------- |
| hasEircode
| bool | Whether the input was a complete and valid Eircode. |
| eircode
| string | The complete Eircode in canonical form if hasEircode
is true. An empty string otherwise. |
| hasRoutingKey
| bool | Whether the input had a valid Routing Key. |
| routingKey
| string | The Routing Key in canonical form if hasRoutingKey
is true. An empty string otherwise. |
| hasUniqueIdentifier
| bool | Whether the input had a valid Unique Identifier. Will be true iff hasEircode
is true. |
| uniqueIdentifier
| string | The Unique Identifier in canonical form if hasUniqueIdentifier
is true. An empty string otherwise. |
| error
| object / null | If the Eircode could not be parsed then an object containing the error details. null otherwise. |
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:
| Name | Type | Description |
| --- | --- | ----------- |
| message
| string | A human readable message describing the error. |
| inputPos
| int | The position in the input string where the error occurred. Or -1 if there is no applicable position. inputPos
will equal the length of the input string if more input was expected. |
| outputPos
| int | The position in the output string (the canonical form) where the error occurred. Or -1 if there is no applicable position. Will never be greater than seven. |
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 KeyF4E2
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.