persian-tools

Keep the persian-tools published bundle small, tree-shakable, and side-effect-free. Use whenever a change might add or grow the bundle — a new dataset, a new module, a new dependency, or a refactor that moves code between files. Also use when "JS bundle" or "Type definitions" size-limit checks fail in CI. Covers the .skip.ts convention, sideEffects: false, the 860 kB JS / 100 kB types budget, and how to investigate which symbols pushed it over.

Validate, parse, or generate Iranian identity and financial identifiers — National ID (کد ملی), Legal ID (شناسه ملی حقوقی), Sheba/IBAN, debit card number, bill ID/payment ID, mobile and landline phone numbers, license plates. Use whenever the user asks to "verify a card number", "validate national id", "check sheba", "parse iban", "bill validation", "generate a fake national id for tests", or otherwise touches Iranian identifier checksums and the data tables behind them.

Author a new utility module under src/modules/ of the persian-tools library. Use when the user asks to "add a new module", "create a utility", "implement a feature", "add a function to persian-tools", or wants to extend the public API with a new Persian/Iranian text or validation helper. Encodes the exact directory layout, export rules, JSDoc tags, error-message format, and index.ts wiring that the rest of the codebase already uses.

Write Vitest test files for persian-tools modules that match the repo's existing patterns. Use when adding a test alongside a new module, writing regression tests for a bug fix, or extending coverage. Encodes the exact assertion shape used for thrown errors ("PersianTools: <fn> - <reason>"), the parameterized-case style, the edge-case checklist (empty / Persian-only / Arabic-only / mixed / ZWNJ), and where to put the file.

Domain knowledge for processing Persian (Farsi) text correctly inside the persian-tools codebase. Use whenever the work touches Persian or Arabic strings, half-space (ZWNJ), RTL direction, digit conversion, character normalization, or "looks Persian but isn't" bugs. Triggers on requests mentioning Farsi, Persian text, half-space, نیم‌فاصله, ZWNJ, Arabic vs Persian characters, ی vs ي, ک vs ك, digit conversion, ۰-۹, or RTL.

Cut a release of @persian-tools/persian-tools — version bump, changelog generation, bundle verification, and publish to npm. Use when the user asks to "release", "publish", "ship a new version", "tag a release", "bump version", or "release beta". Encodes the exact `standard-version`-driven flow, Conventional Commits requirement, the pre-release validation sequence, and the difference between stable and beta releases.

Append the Persian ordinal suffix to a Persian word so "سه" becomes "سوم", "دو" becomes "دوم", etc. Use when generating ordinal phrases ("نفر سوم", "صفحه پنجم") from cardinal Persian number words. Triggers on mentions of addOrdinalSuffix, Persian ordinal, "سوم/پنجم/سیزدهم", ordinal Farsi suffix.

Parse and validate Iranian utility bills (water, electricity, gas, landline, mobile, municipal, tax, traffic fines) given a bill ID + payment ID pair, or a combined barcode. Use when implementing bill-pay flows, validating user-entered bill numbers, or extracting bill type and amount. Triggers on mentions of Bill class, قبض, billId, paymentId, شناسه قبض, شناسه پرداخت, bill barcode, utility bill validation.

Add or strip thousands-separator commas in numeric strings, with support for Persian-digit input. Use when formatting money amounts, prices, or quantities for display, or parsing back a comma-formatted string into a number. Triggers on requests mentioning addCommas, removeCommas, thousands separator, formatNumber, or formatting numeric output.

Convert digits between Persian (۰-۹), Arabic-Indic (٠-٩), and English (0-9) numeral systems. Use when normalizing user input that may contain mixed numeral systems, formatting numbers for Persian/Arabic display, or pattern-matching numeric content. Triggers on requests mentioning Persian digits, Farsi numbers, Arabic-Indic digits, digit conversion, autoConvert, ۰-۹, ٠-٩, faToEn, enToFa, arToFa, or normalizing numeric strings.

Extract Iranian card numbers from free-form text — supports Persian/Arabic digits, separators (dashes, underscores, spaces), fuzzy matching for masked/typo'd cards, optional validation and bank lookup, and large-text optimization. Use when scraping chat logs, OCR output, payment confirmation emails, or any unstructured input for card numbers. Triggers on mentions of extractCardNumber, parse card numbers from text, card extraction, fuzzy card detection.

Look up the capital city of an Iranian province by its Persian name (e.g. "خراسان رضوی" → "مشهد"). Use when displaying capital info next to a province name, or building dropdowns/forms keyed by province. Triggers on mentions of findCapitalByProvince, capital of province, مرکز استان, پایتخت استان.

Resolve a GPS coordinate (longitude, latitude) to the Iranian province it falls inside, using GeoJSON polygon containment. Returns both Persian and English province names. Use when geo-tagging user locations, routing deliveries by province, or annotating uploaded points-of-interest. Triggers on mentions of findProvinceFromCoordinate, geocode Iran, GPS to province, استان از مختصات, polygon containment.

Resolve the issuing Iranian bank's Persian name from a card number by looking up its 6-digit BIN prefix. Use when displaying "Card from بانک سامان" next to a captured card number. Triggers on mentions of getBankNameFromCardNumber, bank from card, BIN lookup, نام بانک از شماره کارت.

Look up the registering city and province for an Iranian National ID by its leading 3-digit prefix. Use when displaying provenance information alongside a National ID in admin tools or KYC flows. Triggers on requests about getPlaceByIranNationalId, city from national id, province from کد ملی, محل صدور.

Insert Zero-Width Non-Joiner (ZWNJ, U+200C, نیم‌فاصله) characters between Persian words and their prefixes/suffixes/compound parts according to Persian typography rules. Use when prettifying user-entered Persian text, preparing copy for typesetting, or fixing کلمات بد جدا شده. Triggers on requests mentioning half-space, نیم‌فاصله, ZWNJ, Persian typography, "می‌خواهم vs می خواهم", prefix/suffix joining, or compound word formatting.

Detect whether a string is in the Arabic script or contains Arabic characters. Use when separating Arabic from Persian/Farsi input, validating that text is Arabic before applying Arabic-specific NLP, or routing multilingual input. Triggers on mentions of isArabic, hasArabic, Arabic detection, Arabic script validation, or "is this Arabic vs Persian".

Detect whether a string is Persian (Farsi) or contains Persian characters, and normalize Arabic-script characters to their Persian equivalents. Use when validating Persian input, deciding whether to apply Persian-specific formatting, or auto-converting Arabic characters typed on an Arabic keyboard. Triggers on requests mentioning isPersian, hasPersian, isFarsi, autoArabicToPersian, Farsi detection, Persian validation, or "is this text Persian".

Validate Iranian Legal IDs (شناسه ملی حقوقی, 11-digit company identifiers) using the official check-digit algorithm. Use when verifying company registration numbers in B2B forms or invoices. Triggers on requests mentioning verifyIranianLegalId, شناسه ملی, شناسه حقوقی, legal id, Iranian company id.

Parse Persian money phrases ("یک میلیون تومان", "دو هزار ریال", "سه تومن" colloquial) into a number, with toman/rial unit detection and optional cross-currency conversion. Use when parsing user-typed prices, voice/chat input for money amounts, or invoice OCR results. Triggers on mentions of moneyWordsToNumber, rialsWordsToNumber, tomansWordsToNumber, پارس پول, money words, toman, rial, تومان, ریال, قیمت به حروف.

Validate and generate Iranian National IDs (کد ملی, 10-digit). Use when verifying a user's submitted National ID, generating valid synthetic IDs for tests/fixtures, or checking whether a 3-digit prefix corresponds to a registered city. Triggers on requests mentioning national id, کد ملی, verifyIranianNationalId, createIranianNationalId, کد ملی validation, or Iranian identity number.

Parse Iranian license plates (cars and motorcycles) — normalize the input, classify the plate type and category (personal, government, taxi, diplomat, etc.), and resolve the trailing 2-digit code to a province. Use when parsing OCR output from license-plate cameras or validating user-entered plates in vehicle-registration apps. Triggers on mentions of getNumberPlateInfo, پلاک, license plate Iran, car plate, motorcycle plate, شماره پلاک.

Convert a number (integer up to Number.MAX_SAFE_INTEGER) into its Persian-words representation, with optional ordinal suffix. Use when generating invoice text, receipt amounts in words, reading numbers aloud, or accessibility output. Triggers on mentions of numberToWords, number to Persian words, to Persian words, ordinal Persian, "say this number in Farsi", or invoice amount in letters.

Validate Iranian mobile numbers, normalize between formats (`0...`, `+98...`, `0098...`), extract the 4-digit operator prefix, and look up operator name plus province coverage. Use when validating SMS gateway input, building contact forms, or showing operator info next to a number. Triggers on mentions of isPhoneNumberValid, phoneNumberDetail, phoneNumberNormalizer, getPhoneNumberPrefix, ایرانسل, همراه اول, mobile validation, +98.

Calculate the structured (years/months/days/hours/minutes/seconds) breakdown of time remaining until a target Gregorian date, plus a stringified Persian phrase and an `isFinished` flag. Use when implementing countdown widgets, event timers, or deadline displays. Triggers on mentions of remainingTime, countdown Persian, زمان باقی‌مانده, time until, deadline.

Strip Persian ordinal endings (مین, ام, اُم, م, plus irregular forms like سوم → سه, یازدهم → یازده) from a Persian word, leaving the cardinal form. Use when canonicalizing user-typed ordinals before lookup or comparison. Triggers on mentions of removeOrdinalSuffix, strip Persian ordinal, "سوم → سه", "یازدهم → یازده", canonical Persian number word.

Validate and parse Iranian Sheba codes (IBAN — "IR" + 24 digits) and resolve them to bank info plus, for many banks, the underlying account number. Use when validating IBAN entry in wire-transfer forms, displaying bank name from an IBAN, or extracting account number for legacy systems. Triggers on mentions of sheba, شبا, IBAN, isShebaValid, getShebaInfo, Iranian IBAN, bank from IBAN.

Generate URL-safe slugs from Persian text, with options for separator, lowercase, max length, custom replacements, and Persian digit handling. Use when building URL paths from article titles, file names from user-typed strings, or anchor IDs. Triggers on mentions of slugify, createSlug, URL-safe Persian, slug from Farsi, prettify URL.

Run a full multi-dimensional analysis on Persian text — character/word counts, language ratios, readability, sentiment, keyword extraction, formality, and quality scoring. Use when building Persian writing assistants, content moderation, SEO scoring, or post-editor analytics. Triggers on mentions of analyzeText, textAnalyzer, Persian text analysis, تحلیل متن, readability Farsi, sentiment Persian, getTextSummary.

Convert a Jalali (Persian) date-time string ("yyyy/mm/dd hh:mm:ss") into a human-readable "time ago" phrase in Persian ("اکنون", "5 دقیقه قبل", "حدود 1 سال قبل"). Use when displaying activity timestamps in Persian UIs. Triggers on mentions of timeAgo, چند دقیقه قبل, زمان نسبی, Jalali time ago, Persian relative time.

Normalize Arabic-script characters (ي, ى, ك) and Arabic diacritics inside a Persian string to their Persian-script equivalents (ی, ک), while preserving Arabic text inside `{{...}}` template segments. Use when sanitizing user input from Arabic keyboards, normalizing for storage/comparison, or preparing text for Persian-only matching. Triggers on requests to "normalize Persian characters", "fix Arabic chars in Persian", "clean ي ك", or "toPersianChars".

Decode percent-encoded Persian (or any non-ASCII) URLs into a human-readable form, optionally replacing spaces with a separator. Use when displaying URLs in UI, logging, or generating slugs from copy-pasted percent-encoded URLs. Triggers on requests mentioning urlFix, URLfix, decode Persian URL, percent-encoded farsi, or "make this URL readable".

Validate Iranian bank debit/credit card numbers (16 digits) using both the Luhn checksum and the Iranian BIN prefix list. Use when validating card-number entry in payment forms, or pre-flighting before calling a PSP. Triggers on requests mentioning verifyCardNumber, Iranian card validation, شماره کارت, Luhn check, BIN check.

Parse Persian number words ("سه هزار دویست و دوازده") into a number, with optional fuzzy typo correction and configurable output digit system. Use when parsing spoken/typed amounts, voice transcripts, or any free-form Persian numeric input. Triggers on mentions of wordsToNumber, parse Persian words, Farsi to number, fuzzy Persian number, "سه هزار" parsing.