india-pincode 2.5.0 → 2.5.1

package/README.md

@@ -1,18 +1,29 @@
 # india-pincode
 
-Ultra-fast npm package for **165,000+ Indian post offices** — lookup by pincode, state, district, area, coordinates. O(1) HashMap performance. Works **standalone** or as a **NestJS module**.
+Ultra-fast npm package for **165,000+ Indian post offices** — lookup by pincode, state, district, area, coordinates. O(1) HashMap performance. Works everywhere: **React**, **Next.js**, **Node.js**, **NestJS**, and any JavaScript/TypeScript project.
+
+## Works With
+
+| Environment | Import |
+|---|---|
+| **React / Vue / Angular / Browser** | `import { getIndiaPincode } from 'india-pincode/browser'` |
+| **Node.js / Express / Fastify** | `import { getIndiaPincode } from 'india-pincode'` |
+| **NestJS** | `import { PincodeModule, PincodeService } from 'india-pincode'` |
+| **Next.js (Server)** | `import { getIndiaPincode } from 'india-pincode'` |
+| **Next.js (Client)** | `import { getIndiaPincode } from 'india-pincode/browser'` |
 
 ## Features
 
+- **Universal** — works in both frontend (React, Vue, Angular) and backend (Node.js, NestJS, Express)
 - **165,000+ post offices** across **36 states/UTs**, **750 districts**, **19,500+ unique pincodes**
 - **O(1) lookups** — pincode, state, district, area via pre-built HashMaps
+- **Smart suggestions** — fuzzy "Did you mean?" for typos (`chnadigarh` → `CHANDIGARH`)
 - **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
-- **Error handling** — all responses wrapped in `ApiResponse<T>` with typed error codes
+- **Error handling** — all responses wrapped in `ApiResponse<T>` with typed error codes and suggestions
 - **Data validation** — sanitized, deduplicated, stripped office suffixes (B.O, S.O, H.O, etc.)
 - **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)
 
@@ -22,6 +33,50 @@ Ultra-fast npm package for **165,000+ Indian post offices** — lookup by pincod
 npm install india-pincode
 ```
 
+---
+
+## React / Browser Usage
+
+```tsx
+import { useEffect, useState } from 'react';
+import { getIndiaPincode } from 'india-pincode/browser';
+
+function PincodeSearch() {
+  const [result, setResult] = useState(null);
+
+  useEffect(() => {
+    async function lookup() {
+      const pin = await getIndiaPincode(); // async — loads data via fetch
+      const res = pin.getByPincode('110001');
+      if (res.success) setResult(res.data);
+    }
+    lookup();
+  }, []);
+
+  return <pre>{JSON.stringify(result, null, 2)}</pre>;
+}
+```
+
+> **Note:** The browser version uses `fetch` + `pako` to decompress data — no Node.js APIs needed. The `getIndiaPincode()` call is **async** (returns a Promise). After initialization, all lookups are synchronous and instant.
+
+---
+
+## Node.js / Express Usage
+
+```typescript
+import { getIndiaPincode } from 'india-pincode';
+
+const pin = getIndiaPincode(); // sync — loads data from filesystem
+
+// All the same methods work:
+pin.getByPincode('110001');
+pin.getByState('MAHARASHTRA');
+pin.search('Koramangala');
+pin.findNearby(28.6353, 77.225, 5);
+```
+
+---
+
 ## Quick Start (Standalone)
 
 ```typescript
@@ -247,9 +302,9 @@ All lookup methods return `ApiResponse<T>`:
 |--------|---------|
 | `getAllStates()` | `string[]` |
 | `getAllDistricts()` | `string[]` |
-| `getDistrictsByState(state)` | `string[]` |
-| `getPincodesByState(state)` | `string[]` |
-| `getPincodesByDistrict(district)` | `string[]` |
+| `getDistrictsByState(state)` | `ApiResponse<string[]>` |
+| `getPincodesByState(state)` | `ApiResponse<string[]>` |
+| `getPincodesByDistrict(district)` | `ApiResponse<string[]>` |
 
 ### Search & Geo
 
@@ -339,6 +394,39 @@ All data is validated and sanitized at load time:
 | Subsequent calls | **< 0.05ms** | Everything cached |
 | Geo nearby (5km) | **~15ms** | Bounding-box pre-filter + Haversine |
 
+## Smart Suggestions
+
+All error responses include helpful suggestions when possible:
+
+```typescript
+// Typo in state name → fuzzy match
+pin.getByState('chnadigarh');
+// error.suggestions: ['CHANDIGARH']
+
+// Area name used as district → cross-index lookup
+pin.getByDistrict('motihari');
+// error.suggestions: ['PURBI CHAMPARAN']
+
+// Invalid pincode (too long) → extracts valid substrings
+pin.getByPincode('8454013');
+// error.suggestions: ['845401']
+
+// Partial pincode → prefix match
+pin.getByPincode('11000');
+// error.suggestions: ['110001', '110002', '110003', '110007', '110009']
+```
+
+## Browser vs Node.js — Key Differences
+
+| | Node.js | Browser (React, etc.) |
+|---|---|---|
+| **Import** | `from 'india-pincode'` | `from 'india-pincode/browser'` |
+| **Init** | `getIndiaPincode()` (sync) | `await getIndiaPincode()` (async) |
+| **Data loading** | Reads `.gz` file from disk | Fetches `.gz` via `fetch()` |
+| **Decompression** | Node.js `zlib` | `pako` (browser-safe) |
+| **API methods** | Identical | Identical |
+| **Bundle size** | N/A (server) | ~12 KB + 3.3 MB data (loaded on demand) |
+
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "india-pincode",
-  "version": "2.5.0",
-  "description": "Ultra-fast lookup for Indian pincode data — state, city, district, latitude, longitude. Works standalone or as a NestJS module.",
+  "version": "2.5.1",
+  "description": "Ultra-fast Indian pincode lookup — 165K+ post offices, state, district, geo search. Works in React, Node.js, NestJS, and any JS/TS project.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -40,7 +40,12 @@
     "state",
     "city",
     "district",
-    "geocode"
+    "geocode",
+    "react",
+    "browser",
+    "frontend",
+    "nextjs",
+    "express"
   ],
   "author": "Deepak Kumar",
   "license": "MIT",