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.