feat: v2.0.0 — zero-dependency rewrite with new lookup APIs and TypeScript support

[karthi-21]

Summary

This PR upgrades the package from v1.0.2 to v2.0.0, fixing critical bugs that made the package completely non-functional for many users, eliminating 41 runtime dependencies, and adding new features that are commonly requested.

Bug fixes (were breaking the package)

• Critical: broken exports — module.exports = getAllHsn | getCodeByTxt | getDesByCode used bitwise OR on functions, which evaluates to 0. Nothing was exported. Fixed to module.exports = { getAllHsn, getCodeByTxt, getDesByCode, ... }.
• Broken file path — sourceFile: 'code_list.xlsx' used a relative path that broke whenever the package was called from any directory other than the package root. Fixed with path.join(__dirname, ...).
• Crashes on null/undefined input — getCodeByTxt(null) and getDesByCode(undefined) threw unhandled TypeErrors. Now throws a descriptive error with the parameter name.

Performance overhaul — 0 runtime dependencies (was 41)

convert-excel-to-json pulled in 41 transitive packages just to parse one static file at runtime. The Excel is now pre-converted to data/hsn_codes.json at build time via scripts/build-data.js. At runtime, index.js does a simple require('./data/hsn_codes.json') — no parsing overhead, no extra installs.

convert-excel-to-json is moved to devDependencies. Users installing this package get zero extra dependencies.

The parsed result is also cached in memory so repeated calls don't re-read the file.

New API methods

Method	Description
getHsnByExactCode(code)	Strict single-result lookup — returns the entry or undefined
isValidHsnCode(code)	Boolean validation, safe on null/undefined — useful for GST form validation
getHsnChapter(chapter)	Returns all codes under a 2-digit chapter (e.g. '52' for cotton)
searchHsn(query, options)	Advanced search with matchType (contains/startsWith/exact) and limit/offset pagination
getStats()	Dataset metadata — version, lastUpdated, totalCodes, chapterCount, source

TypeScript support

Added index.d.ts with full type definitions for all exported functions and interfaces (HsnCode, SearchOptions, HsnStats). No @types/ package needed.

Tests

Added Jest test suite — 35 tests, 98% coverage. Covers all functions including edge cases (null, undefined, empty string, numeric input, no match).

package.json improvements

• "types": "index.d.ts" — TypeScript auto-discovery
• "files" whitelist — only index.js, index.d.ts, data/ are published; scripts and tests are excluded
• "engines": { "node": ">=14" }
• Expanded keywords for npm discoverability (HSN, GST, India GST, CBIC, WCO, harmonized system, etc.)
• "dependencies": {} — zero runtime deps

Test plan

• npm install hsn-code-package installs with zero extra packages
• getAllHsn() returns 12,604 entries
• getCodeByTxt('cotton') returns matching entries
• isValidHsnCode(null) returns false without throwing
• getHsnChapter('52') returns cotton chapter codes
• searchHsn('silk', { limit: 5 }) returns at most 5 results
• TypeScript consumers get type hints without any @types/ install
• npm test passes all 35 tests

https://claude.ai/code/session_01V2bGsWhrzxeEpoV8BJyZMi

---

Generated by Claude Code