@dolphfi_/haiti-utils

English | Français | Kreyòl Ayisyen

Haiti Utils

haiti-utils is a lightweight, zero-dependency npm package that provides simple and reliable utilities for working with Haitian geographical data.

Why use haiti-utils?

• Save Time: Stop searching for and hardcoding lists of departments, communes, or postal codes.
• Reliable Data: Access a complete and structured dataset for all 10 departments.
• Easy to Use: A simple and intuitive API that is fully typed with TypeScript.
• Case-Insensitive: All search functions are case-insensitive for a better developer experience.

Installation

npm install haiti-utils
# or
yarn add haiti-utils
# or
bun add haiti-utils

Usage

Here are a few examples of how to use the package.

Get a list of all departments

import { getDepartments } from 'haiti-utils';

const departments = getDepartments();
console.log(departments);
// Output: ["Artibonite", "Centre", ...]

Get the communes of a specific department

import { getCommunes } from 'haiti-utils';

// The search is case-insensitive
const communes = getCommunes('Ouest'); 
console.log(communes);
// Output: ["Arcahaie", "Cabaret", ...]

Get the postal code of a commune

import { getPostalCode } from 'haiti-utils';

// The search is case-insensitive for both department and commune
const postalCode = getPostalCode('Ouest', 'Pétion-Ville');
console.log(postalCode);
// Output: "HT6122"

const notFound = getPostalCode('Nord', 'InvalidCommune');
console.log(notFound);
// Output: null

Get all data

import { getAllData } from 'haiti-utils';

const allData = getAllData();
console.log(allData[0].department); // "Artibonite"
console.log(allData[0].communes[0].name); // "Dessalines"

Validate a phone number

import { validatePhoneNumber } from 'haiti-utils';

validatePhoneNumber('+509 34 56 78 90'); // true
validatePhoneNumber('55555555'); // false

Format a phone number

import { formatPhoneNumber } from 'haiti-utils';

// Default format (international)
formatPhoneNumber('34567890'); // "+509 34 56 78 90"

// National format
formatPhoneNumber('+509 34.56.78.90', { format: 'national' }); // "3456-7890"

// Compact format
formatPhoneNumber('34567890', { format: 'compact' }); // "+50934567890"

// Invalid number
formatPhoneNumber('12345'); // null

API Reference

getDepartments(): string[]

Returns a list of all department names.

getCommunes(department: string): string[]

Returns a list of all communes for a given department. The search is case-insensitive. Returns an empty array if the department is not found.

getPostalCode(department: string, commune: string): string | null

Returns the postal code for a specific commune within a department. The search is case-insensitive for both department and commune. Returns null if not found or not available.

getAllData(): DepartmentData[]

Returns the complete dataset of all departments and their communes.

validatePhoneNumber(phoneNumber: string): boolean

Validates a Haitian phone number. It handles common formats, including the +509 country code, and ignores spaces or hyphens. Returns true if the number is valid, false otherwise.

formatPhoneNumber(phoneNumber: string, options?: { format: 'international' | 'national' | 'compact' }): string | null

Formats a Haitian phone number into a consistent, readable format. If the number is invalid, it returns null. The default format is international.

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

Sponsor

Si ou jwenn pake haiti-utils itil, ou ka sipòte devlopman li.

Become a Sponsor on GitHub