india-pincode 1.0.0

package/README.md

@@ -0,0 +1,248 @@
+# india-pincode
+
+Ultra-fast npm package for **165,000+ Indian post offices** — lookup by pincode, state, district, office name, coordinates. O(1) HashMap performance. Works **standalone** or as a **NestJS module**.
+
+## Features
+
+- **165,627 post offices** across **37 states/UTs**, **750 districts**, **19,586 unique pincodes**
+- **O(1) lookups** — pincode, state, district, office name via pre-built HashMaps
+- **Geo search** — find nearby post offices by lat/lng with bounding-box pruning + Haversine
+- **Pagination** built-in — `limit`, `page`, `officeType`, `deliveryOnly` filters
+- **Summary APIs** — get pincode/district/state summaries in one call
+- **NestJS module** — `@Global()` module with injectable `PincodeService`
+- **Standalone** — zero dependencies for non-NestJS projects
+- **TypeScript first** — full type definitions, ESM + CJS dual output
+- **Lazy indexes** — built on first use, cached forever (< 200ms cold start)
+
+## Installation
+
+```bash
+npm install india-pincode
+```
+
+## Quick Start (Standalone)
+
+```typescript
+import { getIndiaPincode } from 'india-pincode';
+
+const pin = getIndiaPincode();
+
+// ─── O(1) Pincode Lookup ─────────────────────────────────
+const result = pin.getByPincode('110001');
+console.log(result.data);
+// [{ pincode: '110001', officeName: 'Baroda House', officeType: 'HO', ... }]
+
+// ─── Pincode Summary ─────────────────────────────────────
+const summary = pin.getPincodeSummary('400001');
+// { pincode: '400001', district: 'MUMBAI', state: 'MAHARASHTRA', offices: [...], deliveryOffices: 3 }
+
+// ─── By State (paginated) ────────────────────────────────
+const mh = pin.getByState('MAHARASHTRA', { limit: 10, page: 2 });
+console.log(mh.data);       // 10 records
+console.log(mh.total);      // total offices in Maharashtra
+console.log(mh.totalPages); // total pages
+
+// ─── Filter: only Head Post Offices that deliver ─────────
+pin.getByState('DELHI', { officeType: 'HO', deliveryOnly: true });
+
+// ─── By District ─────────────────────────────────────────
+pin.getByDistrict('PUNE', { limit: 20 });
+
+// ─── District Summary ────────────────────────────────────
+pin.getDistrictSummary('BANGALORE');
+// { district: 'BANGALORE', state: 'KARNATAKA', totalOffices: 120, totalPincodes: 85, pincodes: [...] }
+
+// ─── State Summary ───────────────────────────────────────
+pin.getStateSummary('KARNATAKA');
+// { state: 'KARNATAKA', totalDistricts: 31, totalOffices: 5200, totalPincodes: 3100, districts: [...] }
+
+// ─── Lists ───────────────────────────────────────────────
+pin.getAllStates();           // ['ANDHRA PRADESH', 'ASSAM', ...]
+pin.getAllDistricts();        // ['ADILABAD', 'AGAR MALWA', ...]
+pin.getDistrictsByState('UP') // ['AGRA', 'ALIGARH', ...]
+pin.getPincodesByState('GOA') // ['403001', '403002', ...]
+pin.getPincodesByDistrict('PUNE') // ['410501', '411001', ...]
+
+// ─── Search (free text) ─────────────────────────────────
+pin.search('Koramangala');
+pin.search('5600', { limit: 5 });
+
+// ─── Geo: Find Nearby ───────────────────────────────────
+const nearby = pin.findNearby(28.6353, 77.225, 5); // lat, lng, 5km radius
+// [{ ...office, distanceKm: 0.42 }, { ...office, distanceKm: 1.1 }, ...]
+
+// ─── Stats ───────────────────────────────────────────────
+pin.getTotalRecords();  // 165627
+pin.getTotalPincodes(); // 19586
+```
+
+## NestJS Integration
+
+### 1. Import the module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { PincodeModule } from 'india-pincode';
+
+@Module({
+  imports: [PincodeModule],
+})
+export class AppModule {}
+```
+
+### 2. Inject the service
+
+```typescript
+import { Controller, Get, Param, Query } from '@nestjs/common';
+import { PincodeService } from 'india-pincode';
+
+@Controller('pincode')
+export class PincodeController {
+  constructor(private readonly pincodeService: PincodeService) {}
+
+  @Get(':pincode')
+  getByPincode(@Param('pincode') pincode: string) {
+    return this.pincodeService.getByPincode(pincode);
+  }
+
+  @Get(':pincode/summary')
+  getSummary(@Param('pincode') pincode: string) {
+    return this.pincodeService.getPincodeSummary(pincode);
+  }
+
+  @Get('state/:state')
+  getByState(
+    @Param('state') state: string,
+    @Query('limit') limit?: number,
+    @Query('page') page?: number,
+  ) {
+    return this.pincodeService.getByState(state, { limit, page });
+  }
+
+  @Get('district/:district')
+  getByDistrict(@Param('district') district: string) {
+    return this.pincodeService.getByDistrict(district);
+  }
+
+  @Get('nearby')
+  findNearby(
+    @Query('lat') lat: number,
+    @Query('lng') lng: number,
+    @Query('radius') radius?: number,
+  ) {
+    return this.pincodeService.findNearby(lat, lng, radius);
+  }
+
+  @Get('search/:query')
+  search(@Param('query') query: string, @Query('limit') limit?: number) {
+    return this.pincodeService.search(query, { limit });
+  }
+
+  @Get('states')
+  getAllStates() {
+    return this.pincodeService.getAllStates();
+  }
+
+  @Get('districts/:state')
+  getDistricts(@Param('state') state: string) {
+    return this.pincodeService.getDistrictsByState(state);
+  }
+}
+```
+
+## API Reference
+
+### Core Lookups (O(1))
+
+| Method | Returns |
+|--------|---------|
+| `getByPincode(pincode, options?)` | `PaginatedResult<PostOffice>` |
+| `getPincodeSummary(pincode)` | `PincodeSummary \| null` |
+| `getByState(state, options?)` | `PaginatedResult<PostOffice>` |
+| `getByDistrict(district, options?)` | `PaginatedResult<PostOffice>` |
+| `getByOfficeName(name, options?)` | `PaginatedResult<PostOffice>` |
+
+### Summaries
+
+| Method | Returns |
+|--------|---------|
+| `getStateSummary(state)` | `StateSummary \| null` |
+| `getDistrictSummary(district)` | `DistrictSummary \| null` |
+
+### Lists
+
+| Method | Returns |
+|--------|---------|
+| `getAllStates()` | `string[]` |
+| `getAllDistricts()` | `string[]` |
+| `getDistrictsByState(state)` | `string[]` |
+| `getPincodesByState(state)` | `string[]` |
+| `getPincodesByDistrict(district)` | `string[]` |
+
+### Search & Geo
+
+| Method | Returns |
+|--------|---------|
+| `search(query, options?)` | `PaginatedResult<PostOffice>` |
+| `findNearby(lat, lng, radiusKm?, limit?)` | `NearbyResult[]` |
+
+### QueryOptions
+
+```typescript
+interface QueryOptions {
+  limit?: number;        // default: 100
+  page?: number;         // default: 1 (1-based)
+  officeType?: 'BO' | 'PO' | 'HO';
+  deliveryOnly?: boolean;
+}
+```
+
+### PostOffice
+
+```typescript
+interface PostOffice {
+  pincode: string;
+  officeName: string;
+  officeType: 'BO' | 'PO' | 'HO';  // Branch / Sub / Head
+  delivery: boolean;
+  district: string;
+  state: string;
+  circle: string;
+  region: string;
+  division: string;
+  latitude: number | null;
+  longitude: number | null;
+}
+```
+
+## Performance
+
+| Operation | Time | Notes |
+|-----------|------|-------|
+| Pincode lookup | **< 0.001ms** | O(1) HashMap |
+| State/District/Office lookup | **< 0.001ms** | O(1) indexed |
+| 100k pincode lookups | **~3ms** | Benchmarked |
+| Cold start (first call) | **~180ms** | Loads 165k records, builds indexes |
+| Subsequent calls | **< 0.05ms** | Everything cached |
+| Geo nearby (5km) | **~15ms** | Bounding-box pre-filter + Haversine |
+
+## Data
+
+The package ships with **165,627** post office records from India Post covering all states and union territories. Each record includes:
+
+- Circle, Region, Division names
+- Office name and type (HO/PO/BO)
+- Delivery status
+- District and State
+- Latitude/Longitude (where available)
+
+## Publishing to npm
+
+```bash
+npm login
+npm publish
+```
+
+## License
+
+MIT