Package Exports

malaysia-parliament-dun

Readme

Malaysia Parliament DUN

A Comprehensive NPM Package of Malaysia Parliament (Parlimen) and State Assembly (DUN) Constituencies, based on GE15 2022, available in JSON format.

Overview

malaysia-parliament-dun is an npm package that provides a complete list of Malaysia's Parliament (Parlimen) and State Legislative Assembly (DUN - Dewan Undangan Negeri) constituencies, based on the 15th General Election (GE15) 2022. It covers all 13 states and 3 federal territories, with 222 parliament seats and 600 DUN seats.

Installation
Imports
Usage
TypeScript Support
Testing
Data Source
Contributing
License

Installation

NPM

npm i malaysia-parliament-dun

Yarn

yarn add malaysia-parliament-dun

CDN via jsDelivr

<!-- Regular version -->
<script src="https://cdn.jsdelivr.net/npm/malaysia-parliament-dun@1.1.1/dist/malaysia-parliament-dun.js"></script>

<!-- Minified version -->
<script src="https://cdn.jsdelivr.net/npm/malaysia-parliament-dun@1.1.1/dist/malaysia-parliament-dun.min.js"></script>

Imports

ES Modules (Recommended)

For modern JavaScript environments with ES module support:

import {
  getStates,
  getParliaments,
  getDuns,
  getDunsByState,
  findParliament,
  findDun,
  getStateByParliament,
  getStateByDun,
  getParliamentByDun,
  searchAll,
  getRandomState,
  getRandomParliament,
  getRandomDun,
} from "malaysia-parliament-dun";

CommonJS

For Node.js environments or legacy applications:

const {
  getStates,
  getParliaments,
  getDuns,
  getDunsByState,
  findParliament,
  findDun,
  getStateByParliament,
  getStateByDun,
  getParliamentByDun,
  searchAll,
  getRandomState,
  getRandomParliament,
  getRandomDun,
} = require("malaysia-parliament-dun");

Script Tag

Once you've included the library via the script tag, you can access its functions in two ways:

Destructuring

You can destructure the desired functions from window.malaysiaParliamentDun:

const {
  getStates,
  getParliaments,
  getDuns,
  getDunsByState,
  findParliament,
  findDun,
  getStateByParliament,
  getStateByDun,
  getParliamentByDun,
  searchAll,
  getRandomState,
  getRandomParliament,
  getRandomDun,
} = window.malaysiaParliamentDun;

Direct Access

Alternatively, you can call the functions directly using the malaysiaParliamentDun object:

const states = window.malaysiaParliamentDun.getStates();
const parliaments = window.malaysiaParliamentDun.getParliaments("Kelantan");
const duns = window.malaysiaParliamentDun.getDuns("Kelantan", "Rantau Panjang");
const parliament = window.malaysiaParliamentDun.findParliament("Rantau Panjang");
const dun = window.malaysiaParliamentDun.findDun("Apam Putra");
const state = window.malaysiaParliamentDun.getStateByParliament("P023");
const stateByDun = window.malaysiaParliamentDun.getStateByDun("Apam Putra");
const parliamentByDun = window.malaysiaParliamentDun.getParliamentByDun("Apam Putra");
const results = window.malaysiaParliamentDun.searchAll("Kelantan");

Usage

getStates

Returns an array of all state names.

Example usage:

const states = getStates();

Example result:

[
  "Johor",
  "Kedah",
  "Kelantan",
  "Melaka",
  "Negeri Sembilan",
  "Pahang",
  "Perak",
  "Perlis",
  "Pulau Pinang",
  "Sabah",
  "Sarawak",
  "Selangor",
  "Terengganu",
  "Wp Kuala Lumpur",
  "Wp Labuan",
  "Wp Putrajaya",
]

getParliaments

Returns all parliament seats for a given state.

Parameters:

stateName (string): The name of the state.

Example usage:

const parliaments = getParliaments("Kelantan");

Example result:

[
  {
    "code": "P019",
    "name": "Tumpat",
    "dun": [
      { "code": "N01", "name": "Salor" },
      { "code": "N02", "name": "Chetok" },
      { "code": "N03", "name": "Pangkalan Kubor" },
      { "code": "N04", "name": "Pengkalan Pasir" }
    ]
  },
  ...
]

getDuns

Returns all DUN seats for a given state and parliament.

Parameters:

stateName (string): The name of the state.
parliamentName (string): The name or code of the parliament seat.

Example usage:

const duns = getDuns("Kelantan", "Rantau Panjang");

// Also works with parliament code
const dunsByCode = getDuns("Kelantan", "P023");

Example result:

[
  { "code": "N14", "name": "Bukit Tuku" },
  { "code": "N15", "name": "Gual Periok" },
  { "code": "N16", "name": "Apam Putra" }
]

getDunsByState

Returns all DUN seats across all parliaments for a given state.

Parameters:

stateName (string): The name of the state.

Example usage:

const duns = getDunsByState('Kelantan');

Example result:

[
  { "code": "N01", "name": "Salor" },
  { "code": "N02", "name": "Chetok" },
  { "code": "N03", "name": "Pangkalan Kubor" },
  ...
]

Returns [] for federal territories (no DUN seats) or invalid state.

findParliament

Finds parliament seat(s) by name or code. Supports exact match, partial match, and batch processing.

Parameters:

query (string | string[]): The parliament name or code to search for. Can be a single string or an array of strings.
isExactMatch (boolean, optional): If true (default), performs exact match. If false, performs partial match.

Example usage:

// Exact search by name
const result = findParliament("Rantau Panjang");

// Exact search by code
const byCode = findParliament("P023");

// Partial search
const partial = findParliament("Rantau", false);

// Batch processing
const batch = findParliament(["Rantau Panjang", "Tumpat"]);

Example result for exact search:

{
  "found": true,
  "state": "Kelantan",
  "code": "P023",
  "name": "Rantau Panjang",
  "dun": [
    { "code": "N14", "name": "Bukit Tuku" },
    { "code": "N15", "name": "Gual Periok" },
    { "code": "N16", "name": "Apam Putra" }
  ]
}

Example result for partial search:

{
  "found": true,
  "results": [
    {
      "state": "Kelantan",
      "code": "P023",
      "name": "Rantau Panjang",
      "dun": [...]
    },
    {
      "state": "Negeri Sembilan",
      "code": "P124",
      "name": "Rembau",
      "dun": [...]
    },
    ...
  ]
}

Example result for batch processing:

{
  "found": true,
  "results": [
    {
      "state": "Kelantan",
      "code": "P023",
      "name": "Rantau Panjang",
      "dun": [...]
    },
    {
      "state": "Kelantan",
      "code": "P019",
      "name": "Tumpat",
      "dun": [...]
    }
  ]
}

Example result if not found:

{
  "found": false
}

findDun

Finds DUN seat(s) by name or code. Supports exact match, partial match, and batch processing.

Parameters:

query (string | string[]): The DUN name or code to search for. Can be a single string or an array of strings.
isExactMatch (boolean, optional): If true (default), performs exact match. If false, performs partial match.

Example usage:

// Exact search by name
const result = findDun("Apam Putra");

// Partial search
const partial = findDun("Kota", false);

// Batch processing
const batch = findDun(["Apam Putra", "Gual Periok"]);

Example result for exact search:

{
  "found": true,
  "state": "Kelantan",
  "parliament": "Rantau Panjang",
  "parliamentCode": "P023",
  "code": "N16",
  "name": "Apam Putra"
}

Example result for partial search:

{
  "found": true,
  "results": [
    {
      "state": "Johor",
      "parliament": "Kota Tinggi",
      "parliamentCode": "P158",
      "code": "N41",
      "name": "Kota Tinggi"
    },
    {
      "state": "Sabah",
      "parliament": "Kota Belud",
      "parliamentCode": "P171",
      "code": "N02",
      "name": "Tempasuk"
    },
    ...
  ]
}

Example result if not found:

{
  "found": false
}

getStateByParliament

Returns the state name for a given parliament code or name.

Parameters:

parliament (string): The parliament code (e.g. "P023") or name (e.g. "Rantau Panjang").

Example usage:

// By parliament code
const state = getStateByParliament("P023");

// By parliament name
const stateByName = getStateByParliament("Rantau Panjang");

Example result:

"Kelantan"

Returns null if not found:

getStateByParliament("InvalidParliament"); // null

getStateByDun

Returns the state, parliament name, and parliament code for a given DUN name.

Parameters:

dun (string): The DUN name to search for.

Example usage:

const result = getStateByDun("Apam Putra");

Example result:

{
  "state": "Kelantan",
  "parliament": "Rantau Panjang",
  "parliamentCode": "P023"
}

Returns null if not found:

getStateByDun("InvalidDun"); // null

getParliamentByDun

Returns the parliament seat details that contains a given DUN name.

Parameters:

dun (string): The DUN name to search for.

Example usage:

const result = getParliamentByDun("Apam Putra");

Example result:

{
  "state": "Kelantan",
  "code": "P023",
  "name": "Rantau Panjang",
  "dun": [
    { "code": "N14", "name": "Bukit Tuku" },
    { "code": "N15", "name": "Gual Periok" },
    { "code": "N16", "name": "Apam Putra" }
  ]
}

Returns null if not found:

getParliamentByDun("InvalidDun"); // null

searchAll

Universal search function that searches across states, parliaments, and DUNs in a single query. Supports partial matching.

Parameters:

query (string): The search query to match against states, parliament names/codes, and DUN names/codes.

What it searches:

States: Searches state names for partial matches
Parliaments: Searches parliament names and codes for partial matches
DUNs: Searches DUN names and codes for partial matches

Example usage:

// Search for a state
const stateSearch = searchAll("Kelantan");

// Search for parliaments with partial name
const parliamentSearch = searchAll("Rantau");

// Search for DUNs with partial name
const dunSearch = searchAll("Apam");

// Search by parliament code
const codeSearch = searchAll("P023");

Example 1: Searching for a state name

searchAll("Kelantan")

Result:

{
  "found": true,
  "states": ["Kelantan"],
  "parliaments": [],
  "duns": []
}

Example 2: Searching for parliaments with partial term

searchAll("Rantau")

Result:

{
  "found": true,
  "states": [],
  "parliaments": [
    {
      "state": "Kelantan",
      "code": "P023",
      "name": "Rantau Panjang",
      "dun": [...]
    }
  ],
  "duns": []
}

Example 3: Searching for DUNs with partial term

searchAll("Apam")

Result:

{
  "found": true,
  "states": [],
  "parliaments": [],
  "duns": [
    {
      "state": "Kelantan",
      "parliament": "Rantau Panjang",
      "parliamentCode": "P023",
      "code": "N16",
      "name": "Apam Putra"
    }
  ]
}

Example 4: Searching by parliament code

searchAll("P023")

Result:

{
  "found": true,
  "states": [],
  "parliaments": [
    {
      "state": "Kelantan",
      "code": "P023",
      "name": "Rantau Panjang",
      "dun": [...]
    }
  ],
  "duns": []
}

Example 5: No matches found

searchAll("XYZNoMatch")

Result:

{
  "found": false,
  "states": [],
  "parliaments": [],
  "duns": []
}

Use Cases:

Search bars: One search covers states, parliaments, and DUNs
Auto-complete: Get suggestions across all constituency types
Data validation: Check if input exists anywhere in Malaysia's electoral data
Flexible lookup: No need to know if user is searching for a state, parliament, or DUN

getRandomState

Returns a random state name. Useful for testing and demos.

const state = getRandomState();
// e.g. "Selangor"

getRandomParliament

Returns a random parliament seat. Optionally filter by state.

Parameters:

stateName (string, optional): Limit to a specific state.

// Random from any state
const parliament = getRandomParliament();

// Random from Kelantan
const kelantanParliament = getRandomParliament('Kelantan');

Example result:

{
  "code": "P023",
  "name": "Rantau Panjang",
  "dun": [...]
}

Returns null if an invalid state is provided.

getRandomDun

Returns a random DUN seat. Optionally filter by state and/or parliament.

Parameters:

stateName (string, optional): Limit to a specific state.
parliamentName (string, optional): Limit to a specific parliament.

// Random from anywhere
const dun = getRandomDun();

// Random from Kelantan
const kelantanDun = getRandomDun('Kelantan');

// Random from specific parliament
const specificDun = getRandomDun('Kelantan', 'Rantau Panjang');

Example result:

{ "code": "N16", "name": "Apam Putra" }

Returns null if an invalid state or parliament is provided.

TypeScript Support

malaysia-parliament-dun provides TypeScript type declarations out-of-the-box. All exported functions and interfaces are fully typed.

Available interfaces:

import type {
  Dun,
  Parliament,
  State,
  ParliamentSearchResult,
  DunSearchResult,
  SearchAllResult,
} from "malaysia-parliament-dun";

Testing

The library is equipped with unit tests to ensure its functionality and reliability. We utilize the Jest testing framework for this purpose.

Running the Tests

Ensure you have all dependencies installed:

npm ci

Run the test command:

npm test

Watch Mode

For active development, you can run tests in watch mode:

npm run test:watch

Test Coverage

npm run test:coverage

Note: The coverage directory is not included in the repository as it is generated on-the-fly whenever tests are run with coverage.

Data Source

This package is built on the data from the Malaysia Parliament DUN GitHub repository. It is closely associated with and relies on the JSON data available in this repository. For the most up-to-date constituency information, refer to the original repository.

Contributing

If you find any inaccuracies, typos, or missing data, we welcome contributions! Please feel free to open an issue or submit a pull request.

License

This repository is licensed under the ISC License. See the LICENSE file for more details.