lib-bdphone

Validate, normalize, and format Bangladesh mobile phone numbers for Node.js projects.

Why this package is useful

• Handles Bangladesh mobile numbers in real-world input formats (01, 880, +880, mixed characters)
• Returns structured validation with operator info for easier backend and UI handling
• Includes advanced refactor tools (trim start/end digits, add prefix/suffix, custom separators)
• Lightweight utility with built-in TypeScript definitions and automated tests
• Ships both CJS and ESM entry points for modern Node.js projects

Quick Start (30 seconds)

const {
  validateBdPhoneNumber,
  formatBdPhoneNumber,
  getBdPhoneOperator
} = require("lib-bdphone");

console.log(validateBdPhoneNumber("+880 1615-928286"));
console.log(formatBdPhoneNumber("01615928286", "e164"));
console.log(getBdPhoneOperator("01615928286"));

ESM usage:

import { parseBdPhoneNumber } from "lib-bdphone";

console.log(parseBdPhoneNumber("+8801615928286"));

Features

• Validates Bangladesh mobile numbers (local and international forms)
• Ensures local format has 11 digits and starts with valid prefixes (01[3-9])
• Supports input cleanup (+880 1712-345678, 8801712345678, 01712345678, etc.)
• Returns multiple output formats: local, international, E.164, pretty, and masked
• Supports custom refactor flow (remove from start/end and add your own prefix/suffix)
• Provides clear validation error reasons with typed reasonCode
• Includes stable parse output via parseBdPhoneNumber()

Installation

npm install lib-bdphone

For React hook/component support:

npm install react

Usage

const {
  REASON_CODES,
  validateBdPhoneNumber,
  isValidBdPhoneNumber,
  formatBdPhoneNumber,
  normalizeBdPhoneNumber,
  parseBdPhoneNumber,
  customizeBdPhoneNumber,
  refactorBdPhoneNumber,
  getBdPhoneOperator,
  isBdPhoneOperator
} = require("lib-bdphone");

const number = "01712345678";

// 1) Basic validity
console.log(isValidBdPhoneNumber(number));
// true

console.log(isValidBdPhoneNumber("1712345678", { allowMissingLeadingZero: false }));
// false

console.log(isValidBdPhoneNumber("01812345678", { expectedOperator: "Robi" }));
// true

console.log(isValidBdPhoneNumber("01612345678", { expectedOperator: "Airtel" }));
// true

console.log(isValidBdPhoneNumber("01612345678", { expectedOperator: "Robi Group" }));
// true

// 2) Full validation object
console.log(validateBdPhoneNumber(number));
// {
//   isValid: true,
//   input: '01712345678',
//   local: '01712345678',
//   international: '8801712345678',
//   e164: '+8801712345678',
//   pretty: '017-123-45678',
//   masked: '017****5678',
//   operatorCode: '17',
//   operator: 'Grameenphone'
// }

console.log(validateBdPhoneNumber("01212345678"));
// {
//   isValid: false,
//   input: '01212345678',
//   reason: 'Invalid Bangladesh mobile operator code.',
//   reasonCode: 'INVALID_OPERATOR_CODE'
// }

// 3) All output formats
console.log(formatBdPhoneNumber(number, "local"));
// 01712345678

console.log(formatBdPhoneNumber(number, "international"));
// 8801712345678

console.log(formatBdPhoneNumber(number, "e164"));
// +8801712345678

console.log(formatBdPhoneNumber(number, "pretty"));
// 017-123-45678

console.log(formatBdPhoneNumber(number, "masked"));
// 017****5678

// 4) Normalize (default and custom)
console.log(normalizeBdPhoneNumber("+880 1712-345678"));
// +8801712345678

console.log(normalizeBdPhoneNumber("+880 1712-345678", { format: "pretty" }));
// 017-123-45678

// 5) Operator detection/check
console.log(getBdPhoneOperator(number));
// Grameenphone

console.log(isBdPhoneOperator(number, "gp"));
// true

console.log(isBdPhoneOperator(number, "robi"));
// false

console.log(isBdPhoneOperator("01612345678", "Airtel"));
// true

console.log(isBdPhoneOperator("01612345678", "Robi Group"));
// true

// 6) Stable parse output
console.log(parseBdPhoneNumber("+8801615928286"));
// {
//   input: '+8801615928286',
//   cleaned: '01615928286',
//   isValid: true,
//   e164: '+8801615928286',
//   national: '01615928286',
//   carrierGuess: 'Airtel',
//   reasonCode: null,
//   reason: null
// }

// 7) Custom refactor: remove digits + add your own prefix
console.log(customizeBdPhoneNumber("01615928286", { removeFromStart: 1, prefix: "+880" }));
// +8801615928286

console.log(customizeBdPhoneNumber("1615928286", { removeFromStart: 0, prefix: "+880" }));
// +8801615928286

console.log(customizeBdPhoneNumber("8801615928286", { removeFromStart: 1, base: "local", prefix: "+880" }));
// +8801615928286

console.log(customizeBdPhoneNumber("+8801615928286", { removeFromStart: 1, prefix: "+880" }));
// +8801615928286

console.log(customizeBdPhoneNumber("01615928286", { removeFromStart: 1, removeFromEnd: 2, prefix: "X" }));
// X16159282

console.log(refactorBdPhoneNumber("01615928286", { removeFromStart: 1, prefix: "880" }));
// 8801615928286

console.log(customizeBdPhoneNumber("01615928286", { removeFromStart: 1, suffix: "-RAW" }));
// 1615928286-RAW

console.log(customizeBdPhoneNumber("01615928286", {
  removeFromStart: 1,
  prefix: "+880",
  separator: " ",
  suffix: "BD",
  suffixSeparator: " #"
}));
// +880 1615928286 #BD

React Usage (lib-bdphone/react)

Hook example:

import { useBdPhone } from "lib-bdphone/react";

export function ExampleHookForm() {
  const phone = useBdPhone({
    initialValue: "+8801615928286",
    normalizeOnBlur: true,
    normalizeFormat: "e164"
  });

  return (
    <div>
      <input value={phone.value} onChange={phone.onChange} onBlur={phone.onBlur} />
      <p>Valid: {String(phone.isValid)}</p>
      <p>Carrier: {phone.carrierGuess || "N/A"}</p>
      <p>E.164: {phone.e164 || "N/A"}</p>
    </div>
  );
}

Component example:

import { BdPhoneInput } from "lib-bdphone/react";

export function ExampleComponent() {
  return (
    <BdPhoneInput
      placeholder="Enter BD phone"
      normalizeOnBlur
      normalizeFormat="e164"
      onValueChange={(value, parsed) => {
        console.log(value);
        console.log(parsed);
      }}
    />
  );
}

React exports:

• useBdPhone(config?)
• BdPhoneInput

API

validateBdPhoneNumber(input, options?)

Returns a detailed validation object.

Success:

{
  isValid: true,
  input: '01712345678',
  local: '01712345678',
  international: '8801712345678',
  e164: '+8801712345678',
  pretty: '017-123-45678',
  masked: '017****5678',
  operatorCode: '17',
  operator: 'Grameenphone'
}

Failure:

{
  isValid: false,
  input: 'abc',
  reason: 'Phone number cannot contain letters.',
  reasonCode: 'LETTER_NOT_ALLOWED'
}

isValidBdPhoneNumber(input, options?)

Returns true or false.

formatBdPhoneNumber(input, format?, options?)

Returns a formatted string when valid, otherwise null.

Supported format values:

• local -> 01712345678
• international -> 8801712345678
• e164 -> +8801712345678
• pretty -> 017-123-45678
• masked -> 017****5678

normalizeBdPhoneNumber(input, options?)

Shortcut for returning one normalized format.

• Default format is e164
• You can pass options.format

parseBdPhoneNumber(input, options?)

Returns a stable parse contract for app-level consumption:

{
  input: '+8801615928286',
  cleaned: '01615928286',
  isValid: true,
  e164: '+8801615928286',
  national: '01615928286',
  carrierGuess: 'Airtel',
  reasonCode: null,
  reason: null
}

Available reason codes are exported as REASON_CODES:

• REQUIRED
• LETTER_NOT_ALLOWED
• INVALID_PLUS_POSITION
• MISSING_DIGITS
• UNSUPPORTED_COUNTRY_CODE
• INVALID_LENGTH
• INVALID_START
• INVALID_OPERATOR_CODE
• UNSUPPORTED_OPERATOR
• OPERATOR_MISMATCH

customizeBdPhoneNumber(input, options?)

Transforms a valid number by removing digits from start/end and adding your custom prefix/suffix.

Options:

• base: local (default), core, international
• removeFromStart: number of digits to cut from the beginning
• removeFromEnd: number of digits to cut from the end
• prefix: your custom prefix string (for example +880, 880, X)
• separator: text inserted between prefix and final number
• suffix: your custom suffix string (for example -RAW, -BD)
• suffixSeparator: text inserted between final number and suffix

Example:

customizeBdPhoneNumber("01615928286", { removeFromStart: 1, prefix: "+880" });
// +8801615928286

refactorBdPhoneNumber(input, options?)

Alias of customizeBdPhoneNumber.

getBdPhoneOperator(input, options?)

Returns operator name for a valid number, otherwise null.

Possible return values:

• Grameenphone (013, 017)
• Airtel (016)
• Robi (018)
• Banglalink (014, 019)
• Teletalk (015)

isBdPhoneOperator(input, operatorName, options?)

Checks whether a number belongs to a specific operator.

Accepted names/aliases include:

• grameenphone, gp
• airtel
• robi
• robi group, robigroup, robi airtel, airtel robi
• banglalink, bl
• teletalk, tt

Options

• allowMissingLeadingZero (default: true)
  • Allows input like 1712345678 and converts it to local form 01712345678
• expectedOperator (optional)
  • Example: validateBdPhoneNumber('01612345678', { expectedOperator: 'Airtel' })
  • Group example: validateBdPhoneNumber('01612345678', { expectedOperator: 'Robi Group' })

Use Cases

• Form validation in Node.js, Express, and Next.js APIs
• CRM/contact imports that need normalization to a single format
• Telecom/operator-aware business rules (routing, segmentation, analytics)
• Data export pipelines that require custom prefix/suffix output

Support This Project

• Star the repository to help more developers discover it
• Share your use case and code snippets in issues/discussions
• Open a feature request if you need additional Bangladesh number rules
• Use the launch content kit at docs/launch-post-templates.md to promote updates

Author

• Rajin

GitHub

• Repository: https://github.com/Rajin-257/lib-bdphone.git
• Issues: https://github.com/Rajin-257/lib-bdphone/issues

License

MIT