postcodex-lib-ts

postcodex-lib-ts is a JavaScript/TypeScript library that connects to the Postcodex API to fetch postcode-related information.

Table of Contents

• Installation
• Usage
  • Initialization
  • Fetch Data (Promise)
  • Fetch Data (Callback)
• API Reference
  • ApiServiceConfig
  • ApiServiceResponse
  • Callback
• Development
• License

Installation

To use this library, install it via npm:

npm install postcodex-lib-ts

Usage

Initialization

To use the ApiService, you need to instantiate it using the singleton pattern with your API configuration (e.g., API token).

import ApiService from 'postcodex-lib-ts';

const apiService = ApiService.getInstance({
token: 'your_api_token'
});

Fetch Data (Promise)

You can fetch postcode data using a promise-based approach with the fetchData method. This function takes a postcode as input and returns a promise that resolves with the postcode data.

apiService.fetchData('EC1A 1BB')
.then(data => {
console.log('Postcode data:', data);
})
.catch(error => {
console.error('Error fetching postcode data:', error);
});

Fetch Data (Callback)

If you prefer to use callbacks, the fetchDataWithCallback method allows you to fetch data for a given API endpoint and handle the response using a callback function.

apiService.fetchDataWithCallback('EC1A-1BB', (data) => {
  if (data) {
    console.log('Postcode data (callback):', data);
  } else {
    console.error('Error fetching postcode data with callback');
  }
});

API Reference

ApiServiceConfig

|Property|Type|Description| |---|---|---| |token|string|Your Postcodex API token.|

ApiServiceResponse

An example response object returned by the API looks like this:

{
    "postcode": "EC1A 1BB",
    "postTown": "London",
    "dependentLocality": "",
    "doubleDependentLocality": "",
    "thoroughfare": "St. Martin's Le Grand",
    "dependentThoroughfare": "",
    "buildingNumber": "1",
    "buildingName": "",
    "subBuildingName": "",
    "poBox": "",
    "departmentName": "",
    "OrganisationName": "",
    "udprn": "123456789",
    "postcodeType": "S",
    "suOrganisationIdentifier": "",
    "deliveryPointSuffix": "1A",
    "addressLine1": "1 St. Martin's Le Grand",
    "addressLine2": "",
    "addressLine3": "",
    "addressLine4": "",
    "addressDescription": ""
}

Callback

The callback function signature used in fetchDataWithCallback is:

type Callback = (response: ApiServiceResponse | null) => void;

• response: The postcode data fetched from the API. Will be null in case of an error.

Development

To work on the project locally:

1. Clone the repository.

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

For development builds, you can use:

npm run build:dev

To build for production:

npm run build:prod

Local tests

• Please check the demo folder with an integration example

• You can test the demo by opening the index.html file or use docker

  cd demo;
  docker run -p 80:80 -v $(pwd)/..:/usr/share/nginx/html nginx

• then open http://localhost/demo

Environment Variables

Make sure to set the LOOKUP_URL environment variable in a .env file or directly in your environment. This variable is used as the base URL for API requests.

Example .env file:

LOOKUP_URL=https://api.postcodex.com

You will also need to provide your API token when instantiating the service in your application.

License

This project is licensed under the ISC License.

Integration Guide

Here’s a step-by-step guide on how to integrate postcodex-lib-ts into your project.

1. Install the Package

Install the library using npm:

npm install postcodex-lib-ts

2. Setup Environment Variables

Create a .env file at the root of your project if you haven't already, and add the LOOKUP_URL for the API:

LOOKUP_URL=https://api.postcodex.com

3. Using the Library in Your Code

Once installed, import and configure the ApiService in your project:

import ApiService from 'postcodex-lib-ts';

// Initialize the API service with your token
const apiService = ApiService.getInstance({
    token: 'your_api_token'
});

// Fetch postcode data using the promise-based method
apiService.fetchData('SW1A 1AA')
    .then(data => {
        console.log('Postcode data:', data);
    })
    .catch(error => {
        console.error('Error:', error);
    });

Alternatively, if you prefer using a callback-based approach:

apiService.fetchDataWithCallback('SW1A-1AA', (data) => {
    if (data) {
        console.log('Postcode data (callback):', data);
    } else {
        console.error('Error fetching postcode data with callback');
    }
});

4. Build and Deploy

You can build your project using:

npm run build

For production-ready builds:

npm run build:prod

This generates the bundled files that are ready to be published or deployed in a production environment.

Publish npm package

This should be done with postcodex login

npm login

After the prod build need to update the publish folder.

• rename publish.js file to index.js
• update package.json
• update README instructions

npm publish

Contribution guidelines

• Writing tests
• Code review
• Other guidelines

Who do I talk to?

• Repo owner or admin
• Other community or team contact