nig-utils/dist/geo/index.d.ts

A fully-typed, production-grade utility library for Nigerian developers

interface State {
    name: string;
    capital: string;
    geoZone: string;
    lgas: string[];
    majorCities: string[];
}
interface GeoZone {
    name: string;
    states: string[];
    description: string;
}
interface City {
    name: string;
    state: string;
    type: "capital" | "major" | "minor";
}
/**
 * Get all Nigerian states
 *
 * @public
 * @returns Array of all Nigerian state names
 *
 * @example
 * ```typescript
 * getStates(); // ['Abia', 'Adamawa', 'Akwa Ibom', 'Anambra', ...]
 * ```
 */
declare function getStates(): string[];
/**
 * Get LGAs for a specific state
 *
 * @public
 * @param state - State name
 * @returns Array of LGA names for the state
 *
 * @example
 * ```typescript
 * getLGAs('Lagos'); // ['Agege', 'Ajeromi-Ifelodun', 'Alimosho', ...]
 * ```
 */
declare function getLGAs(state: string): string[];
/**
 * Get major cities for a specific state
 *
 * @public
 * @param state - State name
 * @returns Array of major city names for the state
 *
 * @example
 * ```typescript
 * getCities('Lagos'); // ['Lagos', 'Ikeja', 'Victoria Island', ...]
 * ```
 */
declare function getCities(state: string): string[];
/**
 * Get the capital city of a state
 *
 * @public
 * @param state - State name
 * @returns Capital city name
 *
 * @example
 * ```typescript
 * getCapital('Lagos'); // 'Ikeja'
 * ```
 */
declare function getCapital(state: string): string;
/**
 * Get the geopolitical zone of a state
 *
 * @public
 * @param state - State name
 * @returns Geopolitical zone name
 *
 * @example
 * ```typescript
 * getGeoZone('Lagos'); // 'South West'
 * ```
 */
declare function getGeoZone(state: string): string;
/**
 * Get all states in a geopolitical zone
 *
 * @public
 * @param geoZone - Geopolitical zone name
 * @returns Array of state names in the zone
 *
 * @example
 * ```typescript
 * getStatesByZone('South West'); // ['Ekiti', 'Lagos', 'Ogun', ...]
 * ```
 */
declare function getStatesByZone(geoZone: string): string[];
/**
 * Get all geopolitical zones
 *
 * @public
 * @returns Array of geopolitical zone names
 *
 * @example
 * ```typescript
 * getGeoZones(); // ['North Central', 'North East', 'North West', ...]
 * ```
 */
declare function getGeoZones(): string[];
/**
 * Get detailed information about a state
 *
 * @public
 * @param state - State name
 * @returns State object with complete information or null if not found
 *
 * @example
 * ```typescript
 * getStateInfo('Lagos');
 * // {
 * //   name: 'Lagos',
 * //   capital: 'Ikeja',
 * //   geoZone: 'South West',
 * //   lgas: ['Agege', 'Ajeromi-Ifelodun', ...],
 * //   majorCities: ['Lagos', 'Ikeja', 'Victoria Island', ...]
 * // }
 * ```
 */
declare function getStateInfo(state: string): State | null;
/**
 * Get detailed information about a geopolitical zone
 *
 * @public
 * @param geoZone - Geopolitical zone name
 * @returns GeoZone object with complete information
 *
 * @example
 * ```typescript
 * getZoneInfo('South West');
 * // {
 * //   name: 'South West',
 * //   states: ['Ekiti', 'Lagos', 'Ogun', ...],
 * //   description: 'Known for commerce, education, and cultural heritage.'
 * // }
 * ```
 */
declare function getZoneInfo(geoZone: string): GeoZone | null;
/**
 * Search for states by name (case-insensitive)
 *
 * @public
 * @param query - Search query
 * @returns Array of matching state names
 *
 * @example
 * ```typescript
 * searchStates('lag'); // ['Lagos']
 * searchStates('kan'); // ['Kano', 'Katsina', 'Kebbi']
 * ```
 */
declare function searchStates(query: string): string[];
/**
 * Search for cities by name (case-insensitive)
 *
 * @public
 * @param query - Search query
 * @returns Array of matching city names with their states
 *
 * @example
 * ```typescript
 * searchCities('lag'); // [{name: 'Lagos', state: 'Lagos'}, ...]
 * ```
 */
declare function searchCities(query: string): City[];
/**
 * Get all cities in Nigeria
 *
 * @public
 * @returns Array of all cities with their states
 *
 * @example
 * ```typescript
 * getAllCities(); // [{name: 'Lagos', state: 'Lagos'}, ...]
 * ```
 */
declare function getAllCities(): City[];
/**
 * Validate if a state name is valid
 *
 * @public
 * @param state - State name to validate
 * @returns True if state exists
 *
 * @example
 * ```typescript
 * isValidState('Lagos'); // true
 * isValidState('Invalid'); // false
 * ```
 */
declare function isValidState(state: string): boolean;
/**
 * Validate if a geopolitical zone name is valid
 *
 * @public
 * @param geoZone - Geopolitical zone name to validate
 * @returns True if zone exists
 *
 * @example
 * ```typescript
 * isValidGeoZone('South West'); // true
 * isValidGeoZone('Invalid'); // false
 * ```
 */
declare function isValidGeoZone(geoZone: string): boolean;

export { type City, type GeoZone, type State, getAllCities, getCapital, getCities, getGeoZone, getGeoZones, getLGAs, getStateInfo, getStates, getStatesByZone, getZoneInfo, isValidGeoZone, isValidState, searchCities, searchStates };