numberify-converter/README.md

Convert numbers from text in various languages into their numeric equivalent.

# Numberify Converter

`numberify-converter` is a simple, lightweight package for converting numbers written in text form (currently supporting English and French) into their numeric equivalents. This can be useful for localization, natural language processing, or any scenario where you need to handle numbers written in natural language.

## Table of Contents

1. [Features](#features)
2. [Installation](#installation)
3. [Usage](#usage)
4. [API Documentation](#api-documentation)
5. [Supported Languages](#supported-languages)
6. [Error Handling](#error-handling)
7. [Contributing](#contributing)
8. [Testing](#testing)
9. [License](#license)

---


## Features

- **Convert Numbers in Natural Language**: Transform numbers written in text (e.g., "two hundred and twenty-three") into their numeric equivalent (`223`).
- **Multiple Language Support**: Currently supports English (`en`) and French (`fr`).
- **TypeScript Ready**: Fully typed for seamless TypeScript integration.
- **Lightweight**: Minimal dependencies to keep your project lean.

---


## Installation

You can install the package via `npm` or `yarn`:

### Using npm:

```bash
npm install numberify-converter
```

### Using Yarn:

```bash
yarn add numberify-converter
```

---


## Usage

After installing, you can use the `numberifyString` function to convert numbers from text to numeric format. Here's an example for both English and French.

### Basic Example:

```typescript
import { numberifyString } from "numberify-converter";

// Convert from French
const frenchNumber = numberifyString("deux cent vingt-trois", "fr"); // Outputs: 223

// Convert from English
const englishNumber = numberifyString("two hundred and twenty-three", "en"); // Outputs: 223
```

### Usage in a React Project:

```tsx
import React from "react";
import { numberifyString } from "numberify-converter";

const NumberConverter = () => {
  const textNumber = "deux cent vingt-trois";
  const numericValue = numberifyString(textNumber, "fr");

  return (
    <div>
      <p>
        The number "{textNumber}" in numeric form is: {numericValue}
      </p>
    </div>
  );
};

export default NumberConverter;
```

---


## API Documentation

### `numberifyString(text: string, lang: string): string`

- **text**: The number string written in natural language (e.g., "two hundred and twenty-three").
- **lang**: The language code of the number string. Supported values are `"en"` for English and `"fr"` for French.

#### Example:

```typescript
const result = numberifyString("two hundred and fifty", "en"); // Output: "250"
```

---


## Supported Languages

Currently, `numberify-converter` supports two languages:

- English (`en`)
- French (`fr`)

### Example for French:

```typescript
const result = numberifyString("cent cinquante", "fr"); // Output: "150"
```

### Example for English:

```typescript
const result = numberifyString("one hundred fifty", "en"); // Output: "150"
```

More languages may be added in future updates. Feel free to contribute!

---


## Error Handling

The function will return an empty string (`""`) if the input cannot be parsed correctly or the language is unsupported.

### Example of Handling Errors:

```typescript
try {
  const result = numberifyString("invalid text", "en");
  if (!result) throw new Error("Unable to convert text to number");
} catch (error) {
  console.error(error.message); // Outputs: Unable to convert text to number
}
```

---


## Contributing

We welcome contributions! Here's how you can contribute:

### 1. Fork the repository

Start by forking this repository to your GitHub account.

### 2. Clone the forked repository

```bash
git clone https://github.com/your-username/numberify-converter.git
```

### 3. Install dependencies

Install all dependencies for development:

```bash
npm install
# or
yarn install
```

### 4. Make your changes

Create a new branch for your feature:

```bash
git checkout -b feature/new-language-support
```

### 5. Test your changes

Run the tests to ensure everything works as expected:

```bash
npm run test
# or
yarn test
```

### 6. Commit your changes

```bash
git commit -m "Add support for a new language"
```

### 7. Push and create a pull request

Push your changes to your forked repository and create a pull request.

```bash
git push origin feature/new-language-support
```

In your pull request, describe the changes you've made and why they are important.

---


## Testing

To ensure the package works as expected, we use **Jest** for testing.

### Running Tests:

```bash
npm run test
# or
yarn test
```

Tests are located in the `tests/` directory, and you can add new test cases as needed.

#### Example Test (Jest):

```typescript
test("Convert numbers from French", () => {
  expect(numberifyString("deux cent vingt-trois", "fr")).toBe("223");
});

test("Convert numbers from English", () => {
  expect(numberifyString("two hundred and twenty-three", "en")).toBe("223");
});
```

---


## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.