OpenParable
Skip to content
← Back to skills

wordsToNumber

Development

wordsToNumber is an Agent Skill for development published in the persian-tools/persian-tools repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/persian-tools/persian-tools/blob/HEAD/skills/wordsToNumber/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/wordstonumber, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

wordsToNumber — Persian words → number

import { wordsToNumber } from "@persian-tools/persian-tools";
// CommonJS
const { wordsToNumber } = require("@persian-tools/persian-tools");

Public exports

function wordsToNumber(words: string, config?: WordsToNumberOptions): string | number;

interface WordsToNumberOptions {
  digits?: "en" | "fa" | "ar";           // output digit system (default "en")
  addCommas?: boolean;                    // format result with thousands commas
  fuzzy?: boolean;                        // run typo correction via fastest-levenshtein
  autoConvertDigitsToEn?: boolean;        // normalize Persian/Arabic digits in input (default true)
  autoConvertArabicCharsToPersian?: boolean; // ي → ی, ك → ک before parsing (default true)
}

Function overloads narrow the return type:

  • addCommas: true → returns string
  • digits: "fa" | "ar" → returns string
  • Otherwise → returns number
  • Falsy input → returns "" (string)

Basic usage

import { wordsToNumber } from "@persian-tools/persian-tools";

wordsToNumber("سه هزار دویست و دوازده");      // 3212
wordsToNumber("دوازده هزار");                  // 12000
wordsToNumber("منفی یک میلیون");               // -1000000
wordsToNumber("");                              // ""

Output formatting

wordsToNumber("دوازده هزار", { addCommas: true });  // "12,000"
wordsToNumber("دوازده هزار", { digits: "fa" });     // "۱۲۰۰۰"
wordsToNumber("دوازده هزار", { digits: "ar" });     // "١٢٠٠٠"
wordsToNumber("دوازده هزار", { digits: "fa", addCommas: true }); // "۱۲,۰۰۰"

Fuzzy mode — typo correction

When fuzzy: true, common Persian misspellings are corrected via the TYPO_LIST table (src/modules/wordsToNumber/constants.ts) plus Levenshtein matching against the vocabulary.

wordsToNumber("یگصد و بنجاه هزار", { fuzzy: true });   // 150000
wordsToNumber("یگصد و بنجاه هزار");                     // would mis-parse without fuzzy

Use fuzzy mode sparingly — it makes the parse non-deterministic and slower. Good for voice-transcript input, bad for high-volume API endpoints with structured input.

Auto-normalization (on by default)

  • autoConvertDigitsToEn: true runs autoConvertDigitsToEN on the input first, so "۱۲ هزار" and "١٢ هزار" both work as if you typed "12 هزار".
  • autoConvertArabicCharsToPersian: true runs autoArabicToPersian so "یكصد" (with Arabic kaf) is corrected before lookup.

Disable these only if you have already normalized upstream and want to skip the work.

Joiners and prefixes

Tokens are split on whitespace. The joiner و is filtered out (src/modules/wordsToNumber/index.ts tokenize helper). Number-prefix words (e.g. منفی) are handled via PREFIXES. Unknown tokens are silently skipped — the function tries to extract as much numeric meaning as it can rather than throwing.

wordsToNumber("یک هزار ناقص");           // 1000 — "ناقص" is unknown and skipped
wordsToNumber("نامعلوم");                  // 0 — no recognizable tokens

This is important to remember: wordsToNumber rarely throws and rarely returns null. A non-throwing return doesn't mean the input was clean. If you need strict validation, run the result back through numberToWords and compare.

Common pitfalls

  • Output type depends on options. Use the overloads to keep TypeScript inference correct, or cast at the call site:
    const n = wordsToNumber(input) as number;
    const s = wordsToNumber(input, { addCommas: true }) as string;
    
  • Empty/falsy input returns "" (string), not 0 or null. Different from many parsers — guard with a truthy check before doing math.
  • Silent token skipping means you cannot use this to validate that input is only numeric words. Use a positive check (e.g. round-trip through numberToWords).
  • digits: "persian" does not exist. Some older docs say so. The accepted values are "en" | "fa" | "ar".

References

  • Tests: test/wordsToNumber-fuzzy.spec.ts plus inline cases in numberToWords spec
  • Inverse: numberToWords skill
  • Related: moneyWordsToNumber skill (currency-aware wrapper)