NamaskarJS

All-in-one JavaScript/TypeScript utility library for building Nepal-focused applications.

Documentation: nixfolio.com/namaskarjs

Installation

npm install namaskarjs

Features

• Date — Bikram Sambat (BS) and Gregorian (AD) date conversion
• Currency — Nepali Rupee formatting with Indian/Nepali digit grouping
• Phone — Nepal phone number validation, formatting, and provider detection
• Address — Nepal provinces, districts, and municipalities data (751 local units)
• Time — Nepal timezone (UTC+05:45) utilities
• Lorem — Meaningful Nepali placeholder text generation
• Shared — Nepali/Arabic digit conversion utilities

Quick Start

import {
  adToBs, bsToAd, formatBsDate,
  formatNPR, numberToWordsNPR,
  isValidNepalPhone, getPhoneProvider,
  getProvinces, getDistrictsByProvince, getMunicipalitiesByDistrict,
  nowInNepal, formatNepalTime,
  loremIpsum, sentences,
} from 'namaskarjs';

Or import individual modules for optimal tree-shaking:

import { adToBs, bsToAd } from 'namaskarjs/date';
import { formatNPR } from 'namaskarjs/currency';
import { getMunicipalitiesByDistrict } from 'namaskarjs/address';

Modules

Date

Convert between Bikram Sambat (BS) and Gregorian (AD) dates.

Supported range: BS 2000-2090 (AD 1943-2034 approx.)

import { adToBs, bsToAd, isValidBsDate, formatBsDate } from 'namaskarjs/date';

// AD to BS
adToBs('2023-04-14');           // '2080-01-01'
adToBs(new Date(2023, 3, 14)); // '2080-01-01'

// BS to AD
bsToAd('2080-01-01');           // '2023-04-14'

// Validate
isValidBsDate('2080-01-01');    // true
isValidBsDate('2080-13-01');    // false

// Format
formatBsDate('2080-01-15');                                      // '2080-01-15'
formatBsDate('2080-01-15', { format: 'long' });                  // '15 Baisakh 2080'
formatBsDate('2080-01-15', { locale: 'ne', format: 'long' });    // '१५ बैशाख २०८०'
formatBsDate('2080-01-15', { separator: '/' });                  // '2080/01/15'

Constants:

BS_MONTHS_EN  // ['Baisakh', 'Jestha', ..., 'Chaitra']
BS_MONTHS_NE  // ['बैशाख', 'जेठ', ..., 'चैत्र']
BS_MIN_YEAR   // 2000
BS_MAX_YEAR   // 2090
NEPALI_DIGITS // ['०', '१', '२', ..., '९']

Currency

Format Nepali Rupees with Indian/Nepali digit grouping.

import { formatNPR, numberToWordsNPR } from 'namaskarjs/currency';

formatNPR(1234567);                     // 'Rs. 12,34,567'
formatNPR(1500.5);                      // 'Rs. 1,500.50'
formatNPR(1234567, { prefix: 'NPR' });  // 'NPR 12,34,567'
formatNPR(1500, { showPaisa: true });   // 'Rs. 1,500.00'

numberToWordsNPR(150000);    // 'One Lakh Fifty Thousand Rupees'
numberToWordsNPR(12345678);  // 'One Crore Twenty Three Lakh Forty Five Thousand Six Hundred Seventy Eight Rupees'
numberToWordsNPR(100.50);    // 'One Hundred Rupees and Fifty Paisa'

Phone

Validate, format, and identify Nepal phone numbers.

import {
  isValidNepalPhone, normalizeNepalPhone,
  formatNepalPhone, getPhoneProvider,
} from 'namaskarjs/phone';

isValidNepalPhone('9841234567');        // true
isValidNepalPhone('+977-9841234567');   // true

normalizeNepalPhone('9841234567');      // '+977-9841234567'

formatNepalPhone('9841234567');                              // '9841-234567'
formatNepalPhone('9841234567', { style: 'international' });  // '+977-9841-234567'

getPhoneProvider('9841234567');  // 'NTC'
getPhoneProvider('9801234567');  // 'Ncell'
getPhoneProvider('9611234567');  // 'SmartCell'

Address

Access Nepal's complete administrative hierarchy: 7 provinces, 77 districts, and 751 municipalities.

import {
  getProvinces, getDistricts, getDistrictsByProvince,
  getMunicipalities, getMunicipalitiesByDistrict,
} from 'namaskarjs/address';

// Provinces
const provinces = getProvinces();
// [{ id: 1, name: 'Koshi', nepaliName: 'कोशी', capital: 'Biratnagar' }, ...]

// Districts
const districts = getDistricts(); // All 77 districts

const bagmatiDistricts = getDistrictsByProvince('Bagmati');
const bagmatiDistricts2 = getDistrictsByProvince(3); // same result

// Municipalities
const allMunicipalities = getMunicipalities(); // All 751 local units

const ktmMunicipalities = getMunicipalitiesByDistrict('Kathmandu');
// [{ id: 305, name: 'Kathmandu Metropolitan City', nepaliName: 'काठमाडौं महानगरपालिका', districtId: 27, type: 'metropolitan' }, ...]

const ktmMunicipalities2 = getMunicipalitiesByDistrict(27); // same result

Municipality types:

| Type | Count | Nepali | |------|-------|--------| | metropolitan | 6 | महानगरपालिका | | sub-metropolitan | 11 | उपमहानगरपालिका | | municipality | 276+ | नगरपालिका | | rural-municipality | 460+ | गाउँपालिका |

Time

Work with Nepal's UTC+05:45 timezone.

import { nowInNepal, toNepalTime, formatNepalTime } from 'namaskarjs/time';

const nepalNow = nowInNepal(); // Date adjusted to Nepal time

toNepalTime('2024-01-15T00:00:00Z'); // Date at 05:45 AM Nepal time

formatNepalTime(new Date(), { use12Hour: true });
// '2024-01-15 05:45 PM'

formatNepalTime(new Date(), { includeDate: false, includeSeconds: true });
// '17:45:30'

formatNepalTime(new Date(), { includeTime: false });
// '2024-01-15'

Constants:

NEPAL_TIMEZONE           // 'Asia/Kathmandu'
NEPAL_UTC_OFFSET_MINUTES // 345 (5 hours 45 minutes)

Lorem

Generate meaningful Nepali placeholder text for UI mockups and development.

Sentences are organized by themes (nature, culture, daily life, development, history, people) and grouped for coherent readability.

import { loremIpsum, sentences, paragraphs, words } from 'namaskarjs/lorem';

// Generate a block of Nepali text (1 paragraph, 5 sentences by default)
loremIpsum();

// Multiple paragraphs
loremIpsum({ paragraphCount: 3, sentenceCount: 4 });

// Get individual sentences
sentences({ count: 3 });
// ['हिमालको छायाँमा बसेको यो देश सधैं सुन्दर देखिन्छ।', ...]

// Get paragraphs as an array
paragraphs({ count: 2, sentencesPerParagraph: 4 });

// Get random Nepali words
words({ count: 10 });
// ['नेपाल', 'हिमाल', 'संस्कृति', ...]

Shared Utilities

import { toNepaliDigits, toArabicDigits } from 'namaskarjs';

toNepaliDigits('2080-01-15'); // '२०८०-०१-१५'
toNepaliDigits(2080);         // '२०८०'
toArabicDigits('२०८०');       // '2080'

API Reference

Date Module

| Function | Description | |----------|-------------| | adToBs(date: string \| Date) | Convert AD date to BS date string | | bsToAd(bsDate: string) | Convert BS date string to AD date string | | isValidBsDate(bsDate: string) | Check if a BS date is valid | | formatBsDate(bsDate: string, options?) | Format a BS date with locale support |

Currency Module

| Function | Description | |----------|-------------| | formatNPR(amount: number, options?) | Format number as Nepali Rupees | | numberToWordsNPR(amount: number) | Convert amount to words (Lakh/Crore system) |

Phone Module

| Function | Description | |----------|-------------| | isValidNepalPhone(phone: string) | Validate a Nepal phone number | | normalizeNepalPhone(phone: string) | Normalize to +977-XXXXXXXXXX format | | formatNepalPhone(phone: string, options?) | Format with grouping | | getPhoneProvider(phone: string) | Detect mobile provider (NTC, Ncell, etc.) |

Address Module

| Function | Description | |----------|-------------| | getProvinces() | Get all 7 provinces | | getDistricts() | Get all 77 districts | | getDistrictsByProvince(nameOrId) | Get districts filtered by province | | getMunicipalities() | Get all 751 municipalities | | getMunicipalitiesByDistrict(nameOrId) | Get municipalities filtered by district |

Time Module

| Function | Description | |----------|-------------| | nowInNepal() | Current time in Nepal timezone | | toNepalTime(date) | Convert any date to Nepal time | | formatNepalTime(date?, options?) | Format date/time in Nepal timezone |

Lorem Module

| Function | Description | |----------|-------------| | loremIpsum(options?) | Generate Nepali placeholder text | | sentences(options?) | Get an array of Nepali sentences | | paragraphs(options?) | Get an array of Nepali paragraphs | | words(options?) | Get random Nepali words |

Tree-Shaking

Import from subpath exports for optimal bundle size:

import { adToBs } from 'namaskarjs/date';
import { formatNPR } from 'namaskarjs/currency';
import { getMunicipalitiesByDistrict } from 'namaskarjs/address';

TypeScript

All functions are fully typed. Type exports are available:

import type { BsDate, BsFormatOptions } from 'namaskarjs/date';
import type { Province, District, Municipality } from 'namaskarjs/address';
import type { PhoneFormatOptions, NepalPhoneProvider } from 'namaskarjs/phone';
import type { LoremOptions, ParagraphOptions } from 'namaskarjs/lorem';
import type { NepalTimeFormatOptions } from 'namaskarjs/time';
import type { FormatNPROptions } from 'namaskarjs/currency';

Contributing

Contributions are welcome! Please open an issue or submit a pull request at github.com/nisch-dev/NamaskarJs.

License

MIT