High-performance IFSC code lookup utilities backed by SQLite for Node.js - TypeScript SDK from IFSCFinder project
npm install ifscfinder-tsHigh-performance IFSC code lookup utilities backed by SQLite for Node.js applications. TypeScript port of the canonical Python implementation with full API parity.
- Lightning-fast lookups: Sub-millisecond query times with embedded SQLite
- Built-in caching: LRU cache for 40x speedup on repeated queries
- Zero-config: Bundled database covering India's complete banking network
- Type-safe: Full TypeScript support with comprehensive type definitions
- Node-first: Optimized for Node.js 18+ with ESM and CommonJS support
- API parity: Consistent interface with Python implementation
``bash`
npm install ifscfinder-ts
Note for pnpm users: better-sqlite3 requires native bindings. After installation, run:
`bash`
pnpm rebuild better-sqlite3
Or use npm instead of pnpm for automatic native module compilation.
`typescript
import { lookup, ifscToBank, search } from 'ifscfinder-ts';
// Basic lookup
const details = lookup('SBIN0000001');
console.log(details);
// {
// CODE: 'SBIN0000001',
// BANK: 'STATE BANK OF INDIA',
// BRANCH: 'KOLKATA MAIN',
// ADDRESS: 'SAMRIDDHI BHAWAN, 1 STRAND ROAD, KOLKATA 700 001',
// CITY1: 'KOLKATA',
// CITY2: 'KOLKATA',
// STATE: 'WEST BENGAL'
// }
// Field-specific helpers
const bank = ifscToBank('HDFC0000001');
console.log(bank); // 'HDFC BANK'
// Search by bank, branch, city, or state
const results = search({ bank: 'HDFC BANK', state: 'MAHARASHTRA' }, { limit: 10 });
`
Lookup IFSC code details with caching.
Parameters:
- ifscCode - 11-character IFSC code (case-insensitive)
Returns:
- Object with IFSC details or null if not found/invalid
Example:
`typescript`
const details = lookup('SBIN0000001');
if (details) {
console.log(details.BANK, details.BRANCH);
}
Convenience functions for extracting specific fields:
- ifscToBank(ifscCode: string): string | null - Get bank nameifscToBranch(ifscCode: string): string | null
- - Get branch nameifscToAddress(ifscCode: string): string | null
- - Get addressifscToCity1(ifscCode: string): string | null
- - Get city (primary)ifscToCity2(ifscCode: string): string | null
- - Get city (secondary)ifscToState(ifscCode: string): string | null
- - Get stateifscToStdCode(ifscCode: string): string | null
- - Get STD code
Search for IFSC codes by bank, branch, city, or state.
Parameters:
- params - Search criteria ({ bank?, branch?, city?, state? })options
- - Optional configuration:limit
- - Maximum results (default: 100)exact
- - Exact match vs LIKE search (default: true)
Returns:
- Array of matching IFSC details
Example:
`typescript
// Exact match
const results = search({ bank: 'STATE BANK OF INDIA' });
// Partial match with limit
const results = search(
{ bank: 'HDFC' },
{ exact: false, limit: 50 }
);
// Combined filters
const results = search({
state: 'MAHARASHTRA',
city: 'MUMBAI'
});
`
Normalize and validate an IFSC code.
Parameters:
- code - IFSC code to normalize
Returns:
- Uppercase normalized code or null if invalid
Validation Rules:
- Must be exactly 11 characters
- Must be alphanumeric
- Converted to uppercase
Clear the lookup cache. Call this when the database is updated or to free memory.
`typescript
type IfscDetails = Partial<{
CODE: string;
BANK: string;
BRANCH: string;
ADDRESS: string;
CITY1: string;
CITY2: string;
STATE: string;
STD_CODE: string;
}>;
type SearchParams = {
bank?: string;
branch?: string;
city?: string;
state?: string;
};
type SearchOptions = {
limit?: number; // Default: 100
exact?: boolean; // Default: true
};
`
Benchmarks on Node.js 22 (Apple M1):
| Operation | Performance |
|-----------|-------------|
| Uncached lookup | ~0.015ms per query |
| Cached lookup | ~0.0004ms per query |
| Cache speedup | 37.5x faster |
| Throughput (uncached) | ~66,000 ops/sec |
| Throughput (cached) | ~2,500,000 ops/sec |
Python Baseline (for comparison):
- Uncached: 0.01ms (136,845 ops/sec)
- Cached: 0.00ms (5,526,092 ops/sec)
- Cache speedup: 40.4x
TypeScript implementation achieves ~48% of Python's uncached performance and ~45% of cached performance, which is excellent for a JavaScript runtime.
The package bundles a 42MB SQLite database covering all Indian banks and branches. The database is included in the npm package and requires no external dependencies or downloads.
Database configuration:
- WAL mode enabled for concurrent access
- 1MB cache size
- Prepared statements for optimal performance
`bashInstall dependencies
npm install
Project Structure
clients/typescript/
├── src/
│ ├── index.ts # Public API
│ ├── db.ts # SQLite provider
│ ├── cache.ts # LRU cache
│ ├── normalize.ts # Validation
│ ├── search.ts # Search implementation
│ └── types.ts # TypeScript types
├── tests/
│ ├── lookup.spec.ts
│ └── search.spec.ts
├── benchmarks/
│ └── bench.ts
└── assets/
└── ifsc.db # Bundled database
API Parity with Python
This TypeScript implementation maintains strict API parity with the Python package:
| Feature | Python | TypeScript |
|---------|--------|------------|
| Field names | UPPERCASE | ✅ UPPERCASE |
| Null handling | Omit empty keys | ✅ Omit empty keys |
| Validation | 11-char alphanumeric | ✅ 11-char alphanumeric |
| Caching | LRU cache | ✅ LRU cache |
| Database | SQLite + WAL | ✅ SQLite + WAL |
Requirements
- Node.js >= 18
- No additional dependencies required (better-sqlite3 included)
Related Projects
- Python: ifscfinder - Canonical implementation
- Go: Coming soon
- Rust: Coming soon
Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run
and npm run typecheck`See the main repository for contribution guidelines.
LGPL-2.1 License
Copyright (c) 2024 Akshat Kotpalliwar. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
See the LICENSE file for full terms.
- Repository: https://github.com/IntegerAlex/IFSCFinder
- Issues: https://github.com/IntegerAlex/IFSCFinder/issues
- Documentation: https://github.com/IntegerAlex/IFSCFinder/wiki
- NPM: https://www.npmjs.com/package/ifscfinder-ts (coming soon)