india-state-district
Version:
A lightweight TypeScript library for handling Indian states and districts data with type safety, geolocation support, and easy integration
140 lines (139 loc) • 4.42 kB
TypeScript
import { GeolocationResult, GeolocationOptions } from "../types";
/**
* IndiaStateDistrict class provides functionality to manage and retrieve
* Indian states and their districts data.
*
* @class
* @description
* This class handles operations related to Indian states and districts,
* including getting state lists, district lists, and managing current state selection.
*
* @example
* ```typescript
* const india = new IndiaStateDistrict();
* const districts = india.setStateCode('KA'); // Get Karnataka districts
* ```
*/
export declare class IndiaStateDistrict {
/** Raw data containing state codes and their districts */
private rawData;
/** Currently selected state code */
private currentStateCode;
/**
* Initializes a new instance of IndiaStateDistrict
* Loads the state and district data internally
*/
constructor();
/**
* Sets the current state code and returns its districts
*
* @param stateCode - The code of the state to set (e.g., 'KA' for Karnataka)
* @returns Array of district names for the selected state
* @throws Error if the state code is invalid
*
* @example
* ```typescript
* const districts = india.setStateCode('KA');
* console.log(districts); // ['Bangalore', 'Mysore', ...]
* ```
*/
setStateCode(stateCode: string): string[];
/**
* Gets the districts of the currently selected state
*
* @returns Array of district names for the current state
* If no state is selected, returns an empty array
*/
getDistricts(): string[];
/**
* Gets detailed information about the currently selected state
*
* @returns Object containing state code, name, and districts
* Returns null if no state is selected
*/
getCurrentState(): {
code: string;
name: string;
districts: string[];
} | null;
/**
* Gets all available state codes
*
* @returns Array of state codes (e.g., ['AP', 'KA', 'TN', ...])
*/
getAllStateCodes(): string[];
/**
* Gets all states with their codes and names
*
* @returns Array of objects containing state codes and names
*/
getAllStates(): Array<{
code: string;
name: string;
}>;
/**
* Gets comprehensive data for all states including their districts
*
* @returns Array of objects containing state codes, names, and their districts
*/
getAllStatesWithDistricts(): Array<{
code: string;
name: string;
districts: string[];
}>;
/**
* Gets districts for any state code without changing the current state
*
* @param stateCode - The code of the state to get districts for
* @returns Array of district names for the specified state
* Returns empty array if state code is invalid
*/
getDistrictsForState(stateCode: string): string[];
/**
* Resets the current state selection
*/
reset(): void;
/**
* Detects user's state from browser geolocation
* Uses navigator.geolocation API and reverse geocoding
*
* @param options - Geolocation options (timeout, accuracy, etc.)
* @returns Promise resolving to GeolocationResult with state info
* @throws GeolocationError if detection fails
*
* @example
* ```typescript
* const india = new IndiaStateDistrict();
* try {
* const result = await india.detectStateFromLocation();
* console.log(result.state); // 'Karnataka'
* console.log(result.stateCode); // 'KA'
* } catch (error) {
* console.error(error.message);
* }
* ```
*/
detectStateFromLocation(options?: GeolocationOptions): Promise<GeolocationResult>;
/**
* Wraps navigator.geolocation.getCurrentPosition in a Promise
* @private
*/
private getCurrentPosition;
/**
* Finds state code by checking if coordinates fall within state boundaries
* Checks smaller regions first to handle overlapping boundaries
* @private
*/
private findStateByCoordinates;
/**
* Creates a GeolocationError object
* @private
*/
private createGeolocationError;
/**
* Checks if geolocation is supported in the current environment
*
* @returns boolean indicating geolocation support
*/
isGeolocationSupported(): boolean;
}