Skip to content

Commit 78f27dc

Browse files
cblanccblanc
authored
Merge pull request #30 from ideal-postcodes/2.0.0
2.0.0
2 parents 9ad2653 + 87d0356 commit 78f27dc

27 files changed

+5498
-733
lines changed

‎.gitignore‎

Lines changed: 62 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,64 @@
1-
node_modules
1+
#
2+
# Logs
3+
logs
4+
*.log
5+
npm-debug.log*
6+
yarn-debug.log*
7+
yarn-error.log*
8+
9+
# Runtime data
10+
pids
11+
*.pid
12+
*.seed
13+
*.pid.lock
14+
15+
# Directory for instrumented libs generated by jscoverage/JSCover
16+
lib-cov
17+
18+
# Coverage directory used by tools like istanbul
19+
coverage
20+
21+
# nyc test coverage
222
.nyc_output
23+
24+
# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
25+
.grunt
26+
27+
# Bower dependency directory (https://bower.io/)
28+
bower_components
29+
30+
# node-waf configuration
31+
.lock-wscript
32+
33+
# Compiled binary addons (https://nodejs.org/api/addons.html)
34+
build/Release
35+
36+
# Dependency directories
37+
node_modules/
38+
jspm_packages/
39+
40+
# TypeScript v1 declaration files
41+
typings/
42+
43+
# Optional npm cache directory
44+
.npm
45+
46+
# Optional eslint cache
47+
.eslintcache
48+
49+
# Optional REPL history
50+
.node_repl_history
51+
52+
# Output of 'npm pack'
53+
*.tgz
54+
55+
# dotenv environment variables file
56+
.env
57+
58+
dist
59+
60+
.cache
61+
362
.DS_Store
63+
docs
64+

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,16 @@
22

33
Any changes, including backwards incompatible changes will be listed here
44

5+
## 2.0.0 (12/02/2019)
6+
7+
- *Breaking Change*: Require minimum node.js of 8.0.0
8+
- Ported to typescript (now exports typings)
9+
- Provides a cleaner, more modern API to extract and parse while supporting old methods
10+
- Add static methods to extract single datapoints
11+
- Add a ValidPostcode class with accessor methods which can be destructured
12+
- Updated documentation: [postcodejs.ideal-postcodes.dev](https://postcodejs.ideal-postcodes.dev)
13+
- Added benchmarking
14+
515
## 1.0.1 (12/02/2019)
616

717
- Add runkit example

‎README.md‎

Lines changed: 120 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,125 @@
1-
[![CircleCI](https://circleci.com/gh/ideal-postcodes/postcode.svg?style=svg)](https://circleci.com/gh/ideal-postcodes/postcode) [![Coverage Status](https://coveralls.io/repos/github/ideal-postcodes/postcode/badge.svg?branch=master)](https://coveralls.io/github/ideal-postcodes/postcode?branch=master) ![Dependencies](https://img.shields.io/david/ideal-postcodes/postcode.svg?style=flat) ![Size](https://img.shields.io/bundlephobia/min/postcode.svg?style=flat)
1+
<h1 align="center">
2+
<img src="https://img.ideal-postcodes.co.uk/Postcode.js%[email protected]" alt="Postcode.js">
3+
</h1>
24

3-
# Postcode
5+
> Validate & parse UK postcodes
46
7+
[![CircleCI](https://circleci.com/gh/ideal-postcodes/postcode.svg?style=svg)](https://circleci.com/gh/ideal-postcodes/postcode)
8+
[![Coverage Status](https://coveralls.io/repos/github/ideal-postcodes/postcode/badge.svg?branch=master)](https://coveralls.io/github/ideal-postcodes/postcode?branch=master)
9+
![Dependencies](https://img.shields.io/david/ideal-postcodes/postcode.svg?style=flat)
10+
![Size](https://img.shields.io/bundlephobia/min/postcode.svg?style=flat)
11+
![Downloads](https://img.shields.io/npm/dm/postcode.svg)
512
[![Try postcode on RunKit](https://badge.runkitcdn.com/postcode.svg)](https://npm.runkit.com/postcode)
613

7-
Utility methods for UK Postcodes.
14+
Utility methods for UK Postcodes, including validating the shape of a postcode, extracting postcode elements (like incodes, outcodes, areas and [more](#Definitions)).
815

9-
Included is a test suite that tests against all postcodes listed in the Ordnance Survey's postcode dataset as of January 2014.
16+
Tested against ~1.7 million postcodes on ONSPD.
17+
18+
## Features
19+
20+
- [Check](#validate) whether a postcode conforms to the [correct format](https://en.wikipedia.org/wiki/Postcodes_in_the_United_Kingdom#Formatting)
21+
- [Extract](#parse) useful elements of a postcode like incode, outcode, sector
22+
- [Single purpose static methods](#static-methods)
23+
- Tested against a list of ~1.7 million postcodes listed on ONS Postcode Directory
24+
25+
## Links
26+
27+
- [GitHub Repository](https://github.com/ideal-postcodes/openapi)
28+
- [API Documentation](https://postcodejs.ideal-postcodes.dev)
29+
- [Try postcode.js on RunKit](https://npm.runkit.com/postcode)
30+
- [Postcode element definitions](#definitions)
31+
- [Caveat on postcode validation](#note-on-postcode-Validation)
32+
- [NPM Package](https://www.npmjs.com/package/postcode)
1033

1134
## Getting Started
1235

13-
Install with `npm install postcode`
36+
### Installation
37+
38+
```bash
39+
npm install postcode
40+
```
41+
42+
### Wield
43+
44+
```javascript
45+
import Postcode from "postcode";
46+
```
47+
48+
### Validate
49+
50+
```javascript
51+
Postcode.isValid("AA1 1AB"); // => true
52+
```
53+
54+
### Parse
55+
56+
Pass a string to `Postcode.parse`. This will return a valid or invalid postcode instance which can be easily destructured.
57+
58+
#### Valid Postcode
59+
60+
```
61+
const {
62+
normalised, // => "SW1A 2AA"
63+
outcode, // => "SW1A"
64+
incode, // => "2AA"
65+
area, // => "SW"
66+
district, // => "SW1"
67+
unit, // => "AA"
68+
sector, // => "SW1A 2"
69+
subDistrict, // => "SW1A"
70+
valid, // => true
71+
} = Postcode.parse("Sw1A 2aa");
72+
```
73+
74+
#### Invalid postcode
1475

15-
Create an instance of Postcode to perform utility methods, like so
76+
```
77+
const {
78+
normalised, // => null
79+
outcode, // => null
80+
incode, // => null
81+
area, // => null
82+
district, // => null
83+
unit, // => null
84+
sector, // => null
85+
subDistrict, // => null
86+
valid, // => false
87+
} = Postcode.parse(" Oh no, ): ");
88+
```
89+
90+
#### Accessor Overview
91+
92+
| Postcode | .outcode | .incode | .area | .district | .subDistrict | .sector | .unit |
93+
|----------|----------|---------|-------|-----------|--------------|---------|-------|
94+
| AA9A 9AA | AA9A | 9AA | AA | AA9 | AA9A | AA9A 9 | AA |
95+
| A9A 9AA | A9A | 9AA | A | A9 | A9A | A9A 9 | AA |
96+
| A9 9AA | A9 | 9AA | A | A9 | `null` | A9 9 | AA |
97+
| A99 9AA | A99 | 9AA | A | A99 | `null` | A99 9 | AA |
98+
| AA9 9AA | AA9 | 9AA | AA | AA9 | `null` | AA9 9 | AA |
99+
| AA99 9AA | AA99 | 9AA | AA | AA99 | `null` | AA99 9 | AA |
100+
101+
### Static Methods
102+
103+
If you're just after a single value, you would be better served by calling a static method on `Postcode`.
104+
105+
```javascript
106+
Postcode.isValid("Sw1A 2aa"); // => true
107+
108+
Postcode.toNormalised("Sw1A 2aa"); // => "SW1A 2AA"
109+
Postcode.toOutcode("Sw1A 2aa"); // => "SW1A"
110+
Postcode.toIncode("Sw1A 2aa"); // => "2AA"
111+
Postcode.toArea("Sw1A 2aa"); // => "AA"
112+
Postcode.toDistrict("Sw1A 2aa"); // => "SW1"
113+
Postcode.toSubDistrict("Sw1A 2aa"); // => "SW1A"
114+
Postcode.toSector("Sw1A 2aa"); // => "SW1A 2"
115+
Postcode.toUnit("Sw1A 2aa"); // => "AA"
116+
```
117+
118+
### Older API
119+
120+
Below documents the old validation API, which continues to be supported.
121+
122+
Create an instance of Postcode to perform utility methods, like so:
16123

17124
```javascript
18125
const Postcode = require("postcode");
@@ -91,23 +198,20 @@ The postcode sector is made up of the postcode district, the single space, and t
91198

92199
The postcode unit is two characters added to the end of the postcode sector. Each postcode unit generally represents a street, part of a street, a single address, a group of properties, a single property, a sub-section of the property, an individual organisation or (for instance Driver and Vehicle Licensing Agency) a subsection of the organisation. The level of discrimination is often based on the amount of mail received by the premises or business. Examples of postcode units include "NY" (from "SW1W 0NY"), "GZ" (from "PO16 7GZ"), "HF" (from "GU16 7HF"), or "JQ" (from "L1 8JQ").
93200

94-
Sources:
95-
96-
- https://en.wikipedia.org/wiki/Postcodes_in_the_United_Kingdom#Formatting
97-
- https://en.wikipedia.org/wiki/London_postal_district#Numbered_divisions
98-
99-
## Testing
100-
101-
```npm test```
102-
103201
## Note on Postcode Validation
104202

105203
Postcodes cannot be validated just with a regular expression. Proper postcode validation requires having a full list of postcodes to check against. Relying on a regex will produce false postives/negatives.
106204

107205
A complete list of Postcodes can be obtained from the ONS Postcode Directory, which is updated every 3 months.
108206

207+
## Testing
208+
209+
```bash
210+
npm test
211+
```
212+
109213
## License
110214

111215
MIT
112216

113-
Contains Ordnance Survey Data © Crown Copyright & Database Right 2014
217+
Contains Ordnance Survey Data © Crown Copyright & Database Right

0 commit comments

Comments
 (0)