rwanda-geo/dist/index.d.ts

Complete, typed, and lightweight dataset of Rwanda's administrative divisions - 5 provinces, 30 districts, 416 sectors, 2,148 cells, and 14,837 villages. Server-side only package for Node.js, Next.js, and backend applications.

/**
 * Core interface for all geographical units in Rwanda
 */
interface GeoUnit {
    id: number;
    code: string;
    name: string;
    slug: string;
    shortCode: string;
    parentCode?: string;
    center?: {
        lat: number;
        lng: number;
    };
}
/**
 * Province-level administrative unit
 */
interface Province extends GeoUnit {
    code: string;
}
/**
 * District-level administrative unit
 */
interface District extends GeoUnit {
    code: string;
    parentCode: string;
}
/**
 * Sector-level administrative unit
 */
interface Sector extends GeoUnit {
    code: string;
    parentCode: string;
}
/**
 * Cell-level administrative unit
 */
interface Cell extends GeoUnit {
    code: string;
    parentCode: string;
}
/**
 * Village-level administrative unit
 */
interface Village extends GeoUnit {
    code: string;
    parentCode: string;
}
/**
 * Union type for all administrative levels
 */
type AdministrativeUnit = Province | District | Sector | Cell | Village;
/**
 * Administrative level enumeration
 */
declare enum AdminLevel {
    PROVINCE = "province",
    DISTRICT = "district",
    SECTOR = "sector",
    CELL = "cell",
    VILLAGE = "village"
}
/**
 * GeoJSON Feature properties interface
 */
interface GeoJSONProperties {
    code: string;
    name: string;
    slug: string;
    parentCode?: string;
    level: AdminLevel;
}
/**
 * GeoJSON Feature interface
 */
interface GeoJSONFeature {
    type: 'Feature';
    properties: GeoJSONProperties;
    geometry: {
        type: string;
        coordinates: number[][][] | number[][][][];
    };
}
/**
 * GeoJSON FeatureCollection interface
 */
interface GeoJSONFeatureCollection {
    type: 'FeatureCollection';
    features: GeoJSONFeature[];
}

/**
 * Preload specific data files for immediate access
 * @param filenames - Array of filenames to preload
 */
declare function preloadData(filenames: string[]): void;
/**
 * Clear the data cache to free memory
 */
declare function clearDataCache(): void;
/**
 * Get cache statistics
 */
declare function getCacheStats(): {
    size: number;
    keys: string[];
};

/**
 * Get all provinces in Rwanda
 * @param options - Optional parameters including language preference
 * @returns Array of all provinces
 */
declare function getAllProvinces(options?: {
    language?: 'en' | 'rw';
}): Province[];
/**
 * Get all districts in Rwanda
 * @returns Array of all districts
 */
declare function getAllDistricts(): District[];
/**
 * Get all sectors in Rwanda
 * @returns Array of all sectors
 */
declare function getAllSectors(): Sector[];
/**
 * Get all cells in Rwanda
 * @returns Array of all cells
 */
declare function getAllCells(): Cell[];
/**
 * Get all villages in Rwanda
 * @returns Array of all villages
 */
declare function getAllVillages(): Village[];
/**
 * Get districts by province code
 * @param provinceCode - The province code (e.g., 'RW-01')
 * @returns Array of districts in the specified province
 */
declare function getDistrictsByProvince(provinceCode: string): District[];
/**
 * Get sectors by district code
 * @param districtCode - The district code (e.g., 'RW-D-01')
 * @returns Array of sectors in the specified district
 */
declare function getSectorsByDistrict(districtCode: string): Sector[];
/**
 * Get cells by sector code
 * @param sectorCode - The sector code (e.g., 'RW-S-001')
 * @returns Array of cells in the specified sector
 */
declare function getCellsBySector(sectorCode: string): Cell[];
/**
 * Get villages by cell code
 * @param cellCode - The cell code (e.g., 'RW-C-0001')
 * @returns Array of villages in the specified cell
 */
declare function getVillagesByCell(cellCode: string): Village[];
/**
 * Get a geographical unit by its code
 * @param code - The unique code of the unit
 * @returns The geographical unit or undefined if not found
 */
declare function getByCode(code: string): AdministrativeUnit | undefined;
/**
 * Get the complete hierarchy chain for a given code
 * @param code - The code of the unit to get hierarchy for
 * @returns Array of units from root (province) to the specified unit
 */
declare function getHierarchy(code: string): AdministrativeUnit[];
/**
 * Get all children of a given unit
 * @param parentCode - The parent unit code
 * @returns Array of child units
 */
declare function getChildren(parentCode: string): AdministrativeUnit[];
/**
 * Search for units by name (case-insensitive)
 * @param name - The name to search for
 * @returns Array of units matching the name
 */
declare function searchByName(name: string): AdministrativeUnit[];
/**
 * Search for units by slug (case-insensitive)
 * @param slug - The slug to search for
 * @returns Array of units matching the slug
 */
declare function searchBySlug(slug: string): AdministrativeUnit[];
/**
 * Get all units at a specific administrative level
 * @param level - The administrative level to filter by
 * @returns Array of units at the specified level
 */
declare function getByLevel(level: 'province' | 'district' | 'sector' | 'cell' | 'village'): AdministrativeUnit[];
/**
 * Get the total count of units at each administrative level
 * @returns Object with counts for each level
 */
declare function getCounts(): {
    provinces: number;
    districts: number;
    sectors: number;
    cells: number;
    villages: number;
    total: number;
};
/**
 * Check if a code is valid
 * @param code - The code to validate
 * @returns True if the code is valid
 */
declare function isValidCode(code: string): boolean;
/**
 * Get the administrative level of a code
 * @param code - The code to check
 * @returns The administrative level or undefined if invalid
 */
declare function getCodeLevel(code: string): 'province' | 'district' | 'sector' | 'cell' | 'village' | undefined;
/**
 * Get summary statistics
 * @returns Summary object with counts
 */
declare function getSummary(): {
    provinces: number;
    districts: number;
    sectors: number;
    cells: number;
    villages: number;
};
/**
 * Get the complete hierarchy chain for a given code
 * @param code - The code of the unit to get hierarchy for
 * @returns Array of units from root (province) to the specified unit
 */
declare function getFullHierarchy(code: string): AdministrativeUnit[];
/**
 * Get direct children of a given unit
 * @param parentCode - The parent unit code
 * @returns Array of child units
 */
declare function getDirectChildren(parentCode: string): AdministrativeUnit[];
/**
 * Get siblings of a given unit
 * @param code - The unit code
 * @returns Array of sibling units
 */
declare function getSiblings(code: string): AdministrativeUnit[];
/**
 * Get all descendants of a given unit
 * @param parentCode - The parent unit code
 * @returns Array of all descendant units
 */
declare function getAllDescendants(parentCode: string): AdministrativeUnit[];
/**
 * Fuzzy search for units by name with scoring
 * @param query - The search query
 * @param threshold - Maximum distance for a match (default: 3)
 * @param limit - Maximum number of results (default: 10)
 * @returns Array of units with scores
 */
declare function fuzzySearchByName(query: string, threshold?: number, limit?: number): Array<{
    unit: AdministrativeUnit;
    score: number;
}>;
/**
 * Search for units by partial code
 * @param partialCode - The partial code to search for
 * @param limit - Maximum number of results (default: 20)
 * @returns Array of units matching the partial code
 */
declare function searchByPartialCode(partialCode: string, limit?: number): AdministrativeUnit[];
/**
 * Get smart suggestions for autocomplete
 * @param query - The search query
 * @param limit - Maximum number of suggestions (default: 10)
 * @returns Array of suggestions with match types
 */
declare function getSuggestions(query: string, limit?: number): Array<{
    unit: AdministrativeUnit;
    type: 'exact' | 'fuzzy' | 'partial';
    matchField: 'name' | 'code' | 'slug';
}>;
/**
 * Validate parent-child relationship
 * @param parentCode - The parent unit code
 * @param childCode - The child unit code
 * @returns Validation result
 */
declare function validateParentChildRelationship(parentCode: string, childCode: string): {
    isValid: boolean;
    error?: string;
    parentLevel?: string;
    childLevel?: string;
};
/**
 * Validate code format
 * @param code - The code to validate
 * @returns Validation result
 */
declare function validateCodeFormat(code: string): {
    isValid: boolean;
    error?: string;
    level?: string;
    format?: string;
};
/**
 * Validate hierarchy integrity
 * @returns Validation result with issues
 */
declare function validateHierarchyIntegrity(): {
    isValid: boolean;
    issues: Array<{
        type: 'orphaned' | 'invalid_parent' | 'circular_reference' | 'missing_unit';
        message: string;
        code?: string;
    }>;
    summary: {
        totalUnits: number;
        orphanedUnits: number;
        invalidParents: number;
        circularReferences: number;
        missingUnits: number;
    };
};
/**
 * Validate unit properties
 * @param unit - The unit to validate
 * @returns Validation result
 */
declare function validateUnitProperties(unit: AdministrativeUnit): {
    isValid: boolean;
    issues: string[];
};

/**
 * Check which data files are available
 * @returns Object indicating which data files are available
 */
declare function getAvailableData(): {
    provinces: boolean;
    districts: boolean;
    sectors: boolean;
    cells: boolean;
    villages: boolean;
};

/**
 * Load and decompress a gzipped JSON file
 * @param filename - The name of the JSON file (without .gz extension)
 * @returns The parsed JSON data
 */
declare function loadGzippedJson<T>(filename: string): T;
/**
 * Load and decompress a gzipped JSON file with error handling
 * @param filename - The name of the JSON file (without .gz extension)
 * @returns The parsed JSON data or null if loading fails
 */
declare function loadGzippedJsonSafe<T>(filename: string): T | null;

/**
 * Rwanda-Geo: Complete administrative divisions dataset for Rwanda
 *
 * ⚠️ SERVER-SIDE ONLY PACKAGE
 * This package uses Node.js built-in modules (fs, zlib, path) and cannot be used
 * in client-side applications. Use in:
 * - Node.js servers
 * - Next.js server components and API routes
 * - Build-time data generation
 *
 * For client-side usage, create API endpoints that use this package.
 */

declare const _default: {
    loadGzippedJson: typeof loadGzippedJson;
    loadGzippedJsonSafe: typeof loadGzippedJsonSafe;
    AdminLevel: typeof AdminLevel;
    getAllProvinces(options?: {
        language?: "en" | "rw";
    }): Province[];
    getAllDistricts(): District[];
    getAllSectors(): Sector[];
    getAllCells(): Cell[];
    getAllVillages(): Village[];
    getDistrictsByProvince(provinceCode: string): District[];
    getSectorsByDistrict(districtCode: string): Sector[];
    getCellsBySector(sectorCode: string): Cell[];
    getVillagesByCell(cellCode: string): Village[];
    getByCode(code: string): AdministrativeUnit | undefined;
    getHierarchy(code: string): AdministrativeUnit[];
    getChildren(parentCode: string): AdministrativeUnit[];
    searchByName(name: string): AdministrativeUnit[];
    searchBySlug(slug: string): AdministrativeUnit[];
    getByLevel(level: "province" | "district" | "sector" | "cell" | "village"): AdministrativeUnit[];
    getCounts(): {
        provinces: number;
        districts: number;
        sectors: number;
        cells: number;
        villages: number;
        total: number;
    };
    isValidCode(code: string): boolean;
    getCodeLevel(code: string): "province" | "district" | "sector" | "cell" | "village" | undefined;
    getSummary(): {
        provinces: number;
        districts: number;
        sectors: number;
        cells: number;
        villages: number;
    };
    getFullHierarchy(code: string): AdministrativeUnit[];
    getDirectChildren(parentCode: string): AdministrativeUnit[];
    getSiblings(code: string): AdministrativeUnit[];
    getAllDescendants(parentCode: string): AdministrativeUnit[];
    fuzzySearchByName(query: string, threshold?: number, limit?: number): Array<{
        unit: AdministrativeUnit;
        score: number;
    }>;
    searchByPartialCode(partialCode: string, limit?: number): AdministrativeUnit[];
    getSuggestions(query: string, limit?: number): Array<{
        unit: AdministrativeUnit;
        type: "exact" | "fuzzy" | "partial";
        matchField: "name" | "code" | "slug";
    }>;
    validateParentChildRelationship(parentCode: string, childCode: string): {
        isValid: boolean;
        error?: string;
        parentLevel?: string;
        childLevel?: string;
    };
    validateCodeFormat(code: string): {
        isValid: boolean;
        error?: string;
        level?: string;
        format?: string;
    };
    validateHierarchyIntegrity(): {
        isValid: boolean;
        issues: Array<{
            type: "orphaned" | "invalid_parent" | "circular_reference" | "missing_unit";
            message: string;
            code?: string;
        }>;
        summary: {
            totalUnits: number;
            orphanedUnits: number;
            invalidParents: number;
            circularReferences: number;
            missingUnits: number;
        };
    };
    validateUnitProperties(unit: AdministrativeUnit): {
        isValid: boolean;
        issues: string[];
    };
    getAvailableData(): {
        provinces: boolean;
        districts: boolean;
        sectors: boolean;
        cells: boolean;
        villages: boolean;
    };
    preloadData: typeof preloadData;
    clearDataCache: typeof clearDataCache;
    getCacheStats: typeof getCacheStats;
};

export { AdminLevel, type AdministrativeUnit, type Cell, type District, type GeoJSONFeature, type GeoJSONFeatureCollection, type GeoJSONProperties, type GeoUnit, type Province, type Sector, type Village, clearDataCache, _default as default, fuzzySearchByName, getAllCells, getAllDescendants, getAllDistricts, getAllProvinces, getAllSectors, getAllVillages, getAvailableData, getByCode, getByLevel, getCacheStats, getCellsBySector, getChildren, getCodeLevel, getCounts, getDirectChildren, getDistrictsByProvince, getFullHierarchy, getHierarchy, getSectorsByDistrict, getSiblings, getSuggestions, getSummary, getVillagesByCell, isValidCode, loadGzippedJson, loadGzippedJsonSafe, preloadData, searchByName, searchByPartialCode, searchBySlug, validateCodeFormat, validateHierarchyIntegrity, validateParentChildRelationship, validateUnitProperties };