india-pincode 2.4.0 → 2.5.0

package/dist/pincode-lookup-CUR8-tsY.d.ts

@@ -0,0 +1,150 @@
+declare enum ErrorCode {
+    INVALID_PINCODE = "INVALID_PINCODE",
+    PINCODE_NOT_FOUND = "PINCODE_NOT_FOUND",
+    STATE_NOT_FOUND = "STATE_NOT_FOUND",
+    DISTRICT_NOT_FOUND = "DISTRICT_NOT_FOUND",
+    INVALID_COORDINATES = "INVALID_COORDINATES",
+    INVALID_INPUT = "INVALID_INPUT",
+    NO_RESULTS = "NO_RESULTS"
+}
+interface ApiError {
+    code: ErrorCode;
+    message: string;
+    suggestions?: string[];
+}
+interface ApiResponse<T> {
+    success: boolean;
+    data: T | null;
+    error?: ApiError;
+}
+interface PostOffice {
+    pincode: string;
+    area: string;
+    officeType: OfficeType;
+    delivery: boolean;
+    district: string;
+    state: string;
+    country: string;
+    circle: string;
+    region: string;
+    division: string;
+    latitude: number | null;
+    longitude: number | null;
+}
+type OfficeType = 'BO' | 'SO' | 'HO' | 'PO' | 'GPO';
+interface QueryOptions {
+    /** Max results to return (default: 100) */
+    limit?: number;
+    /** Page number, 1-based (default: 1) */
+    page?: number;
+    /** Filter by office type */
+    officeType?: OfficeType;
+    /** Filter only delivery offices */
+    deliveryOnly?: boolean;
+}
+interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+interface NearbyResult extends PostOffice {
+    distanceKm: number;
+}
+interface AreaInfo {
+    pincode: string;
+    area: string;
+    latitude: number | null;
+    longitude: number | null;
+}
+interface PincodeSummary {
+    pincode: string;
+    district: string;
+    state: string;
+    country: string;
+    areas: AreaInfo[];
+    deliveryAreas: number;
+    hasCoordinates: boolean;
+}
+interface DistrictSummary {
+    district: string;
+    state: string;
+    country: string;
+    totalAreas: number;
+    totalPincodes: number;
+    pincodes: string[];
+}
+interface StateSummary {
+    state: string;
+    country: string;
+    totalDistricts: number;
+    totalAreas: number;
+    totalPincodes: number;
+    districts: string[];
+}
+
+/**
+ * - Geo-nearby → Haversine with early bounding-box pruning.
+ * - All responses wrapped in ApiResponse with proper error codes.
+ */
+declare class IndiaPincode {
+    private _data;
+    private _byPincode;
+    private _byState;
+    private _byDistrict;
+    private _byArea;
+    constructor(data: PostOffice[]);
+    private isValidPincode;
+    private loadRuntimeData;
+    private indexByPincode;
+    private indexByState;
+    private indexByDistrict;
+    private indexByArea;
+    private buildIndex;
+    private paginate;
+    /** Get all post offices for a pincode. Returns error for invalid/missing pincodes. */
+    getByPincode(pincode: string, options?: QueryOptions): ApiResponse<PaginatedResult<PostOffice>>;
+    /** Get a complete summary for a pincode. */
+    getPincodeSummary(pincode: string): ApiResponse<PincodeSummary>;
+    /** Get all post offices in a state. */
+    getByState(state: string, options?: QueryOptions): ApiResponse<PaginatedResult<PostOffice>>;
+    /** Get a summary for a state — districts, pincode count, etc. */
+    getStateSummary(state: string): ApiResponse<StateSummary>;
+    /** Get all unique state names. */
+    getAllStates(): string[];
+    /** Get all post offices in a district. */
+    getByDistrict(district: string, options?: QueryOptions): ApiResponse<PaginatedResult<PostOffice>>;
+    /** Get a summary for a district. */
+    getDistrictSummary(district: string): ApiResponse<DistrictSummary>;
+    /** Get all districts for a state. */
+    getDistrictsByState(state: string): ApiResponse<string[]>;
+    /** Get all unique district names. */
+    getAllDistricts(): string[];
+    /** Get post offices by exact area name (case-insensitive). */
+    getByArea(name: string, options?: QueryOptions): ApiResponse<PaginatedResult<PostOffice>>;
+    /** Get all pincodes in a state. */
+    getPincodesByState(state: string): ApiResponse<string[]>;
+    /** Get all pincodes in a district. */
+    getPincodesByDistrict(district: string): ApiResponse<string[]>;
+    /**
+     * Search across pincode, area name, district, state.
+     * Returns early once limit is reached — no wasted iteration.
+     */
+    search(query: string, options?: QueryOptions): ApiResponse<PaginatedResult<PostOffice>>;
+    /**
+     * Find post offices near a given coordinate.
+     * Uses bounding-box pre-filter + Haversine for accuracy.
+     * Returns sorted by distance ascending.
+     */
+    findNearby(lat: number, lng: number, radiusKm?: number, limit?: number): ApiResponse<NearbyResult[]>;
+    /** Total number of post office records loaded. */
+    getTotalRecords(): number;
+    /** Total number of unique pincodes. */
+    getTotalPincodes(): number;
+    /** Clear all cached data and indexes — reloads fresh on next call. */
+    /** Clear all cached indexes — rebuilds on next call. */
+    clearCache(): void;
+}
+
+export { type ApiError as A, type DistrictSummary as D, ErrorCode as E, IndiaPincode as I, type NearbyResult as N, type OfficeType as O, type PaginatedResult as P, type QueryOptions as Q, type StateSummary as S, type ApiResponse as a, type AreaInfo as b, type PincodeSummary as c, type PostOffice as d };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "india-pincode",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Ultra-fast lookup for Indian pincode data — state, city, district, latitude, longitude. Works standalone or as a NestJS module.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -8,8 +8,14 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "browser": "./dist/browser.mjs",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.mjs",
+      "require": "./dist/browser.js"
     }
   },
   "files": [
@@ -47,7 +53,9 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
-  "dependencies": {},
+  "dependencies": {
+    "pako": "^2.1.0"
+  },
   "peerDependencies": {
     "@nestjs/common": ">=9.0.0",
     "reflect-metadata": ">=0.1.0",