> ## Documentation Index
> Fetch the complete documentation index at: https://persian-tools.usestrict.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Guide

> Learn how to use Persian Tools utilities in your applications

# Usage Guide

Persian Tools provides a comprehensive set of utilities for Persian language processing. This guide covers the fundamental patterns and best practices for using the library.

## Import Patterns

### Tree-Shaking (Recommended)

Import only the utilities you need for optimal bundle size:

```typescript theme={null}
import { numberToWords, isPersian, addCommas } from "persian-tools";

// Usage
const persianNumber = numberToWords(1234);
const isValidPersian = isPersian("سلام دنیا");
const formattedNumber = addCommas(1234567);
```

### Namespace Import

Import the entire library under a namespace:

```typescript theme={null}
import * as PersianTools from "persian-tools";

// Usage
const persianNumber = PersianTools.numberToWords(1234);
const isValidPersian = PersianTools.isPersian("سلام دنیا");
```

### CommonJS

For Node.js environments using CommonJS:

```javascript theme={null}
const { numberToWords, isPersian } = require("persian-tools");

// Usage
const persianNumber = numberToWords(1234);
const isValidPersian = isPersian("سلام دنیا");
```

## Core Patterns

### Number Processing

<CodeGroup>
  ```typescript Number to Words theme={null}
  import { numberToWords } from '@persian-tools/persian-tools';

  // Basic conversion
  numberToWords(1234); // "یک هزار و دویست و سی و چهار"

  // With ordinal suffix
  numberToWords(1234, { ordinal: true }); // "یک هزار و دویست و سی و چهارم"

  ```

  ```typescript Words to Number theme={null}
  import { wordsToNumber } from '@persian-tools/persian-tools';

  // Exact matching
  wordsToNumber('یک هزار و دویست و سی و چهار'); // 1234

  // Fuzzy matching
  wordsToNumber('یکهزار دویست سی چهار', { fuzzy: true }); // 1234
  ```

  ```typescript Digit Conversion theme={null}
  import { digitsEnToFa, digitsFaToEn } from "persian-tools";

  // English to Persian digits
  digitsEnToFa("1234567890"); // "۱۲۳۴۵۶۷۸۹۰"

  // Persian to English digits
  digitsFaToEn("۱۲۳۴۵۶۷۸۹۰"); // "1234567890"
  ```
</CodeGroup>

### Text Validation

<CodeGroup>
  ```typescript Persian Text theme={null}
  import { isPersian, isArabic } from '@persian-tools/persian-tools';

  // Check if text is Persian
  isPersian('سلام دنیا'); // true
  isPersian('Hello World'); // false

  // Check if text is Arabic
  isArabic('مرحبا بالعالم'); // true
  isArabic('سلام دنیا'); // false

  ```

  ```typescript Character Conversion theme={null}
  import { toPersianChars } from '@persian-tools/persian-tools';

  // Convert Arabic/English chars to Persian
  toPersianChars('علي'); // "علی" (Arabic ي to Persian ی)
  toPersianChars('كتاب'); // "کتاب" (Arabic ك to Persian ک)
  ```
</CodeGroup>

### Validation

<CodeGroup>
  ```typescript National ID theme={null}
  import { verifyIranianNationalId, getPlaceByIranNationalId } from '@persian-tools/persian-tools';

  // Verify Iranian National ID
  verifyIranianNationalId('0499370899'); // true
  verifyIranianNationalId('1234567890'); // false

  // Get place by National ID
  getPlaceByIranNationalId('0499370899'); // { city: 'خمین', province: 'مرکزی' }

  ```

  ```typescript Card Numbers theme={null}
  import { verifyCardNumber, getBankNameFromCardNumber } from '@persian-tools/persian-tools';

  // Verify card number
  verifyCardNumber('6274129005473742'); // true

  // Get bank name
  getBankNameFromCardNumber('6274129005473742'); // 'بانک پارسیان'
  ```
</CodeGroup>

## Configuration Options

Many utilities accept configuration objects for customized behavior:

### Number Conversion Options

```typescript theme={null}
import { numberToWords, wordsToNumber } from "persian-tools";

// Number to words with options
numberToWords(1234, {
	ordinal: true, // Add ordinal suffix
	currency: true, // Format as currency
	scale: "short", // Use short scale
});

// Words to number with fuzzy matching
wordsToNumber("یک هزار دویست", {
	fuzzy: true, // Enable fuzzy matching
	digits: "persian", // Accept Persian digits
});
```

### Text Processing Options

```typescript theme={null}
import { halfSpace, slugify } from "persian-tools";

// Half-space with custom options
halfSpace("کتاب ها", {
	cleanExtraSpaces: true,
	replaceNumbers: false,
});

// Slugify with options
slugify("عنوان مقاله ای", {
	separator: "-",
	lowercase: true,
	trim: true,
});
```

## Error Handling

Persian Tools utilities are designed to be robust and handle edge cases gracefully:

```typescript theme={null}
import { numberToWords, verifyIranianNationalId } from "persian-tools";

// Utilities return sensible defaults for invalid input
numberToWords(null); // ""
numberToWords(-1); // "" (negative numbers not supported)

// Validation utilities return boolean values
verifyIranianNationalId("invalid"); // false
verifyIranianNationalId(""); // false
```

## Performance Considerations

<AccordionGroup>
  <Accordion title="🚀 Lazy Loading" icon="bolt">
    Import utilities individually to enable tree-shaking and reduce bundle size.
  </Accordion>

  <Accordion title="📈 Caching" icon="cache">
    For repeated operations with the same input, consider implementing your own caching layer.
  </Accordion>

  <Accordion title="⚡ Batch Processing" icon="layer-group">
    For processing large datasets, process items in batches to avoid blocking the main thread.
  </Accordion>
</AccordionGroup>

## TypeScript Support

Persian Tools provides comprehensive TypeScript definitions:

```typescript theme={null}
import { numberToWords, NumberToWordsOptions } from "persian-tools";

// Type-safe options
const options: NumberToWordsOptions = {
	ordinal: true,
	currency: false,
};

const result: string = numberToWords(1234, options);
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Examples" icon="code-simple" href="/getting-started/examples">
    Explore practical examples and common use cases
  </Card>

  <Card title="Number Utilities" icon="calculator" href="/utilities/numbers/number-to-words">
    Learn about number processing utilities
  </Card>
</CardGroup>