tanisa/README.md

A utility to convert Malagasy 🇲🇬 numbers, dates, and times into their word representations.

# tanisa

[![npm version](https://badge.fury.io/js/tanisa.svg)](https://www.npmjs.com/package/tanisa)
![License](https://img.shields.io/badge/License-MIT-yellow.svg)

**Tanisa** is here to give those digits a voice, transforming them into elegant Malagasy words 🇲🇬.

**In simpler terms** : A utility to convert Malagasy numbers, dates, and times into their word representations.

## Features

- ✅ **Handles whole numbers** : From a humble "aotra" (zero) to numbers that make your calculator sweat.
- ✅ **Decimal support** : Gracefully converts those pesky fractions into spoken form.
- ✅ **Large number linguistics**: Tackles big numbers with the appropriate Malagasy terminology.
- ✅ **Date formatting** : Converts dates to Malagasy short or long spoken form.
- ✅ **Time formatting** : Converts times to Malagasy spoken time with the correct time-of-day period.
- ✅ **User-friendly API** : So intuitive, you'll feel like you've been speaking number-words your whole life.
- ✅ **Configurable options** : Customize conversion behaviour for decimals, date format, and time precision.
- 🛡️ **Error Handling** : Throws helpful errors when you try to feed it something it can't digest.

## Installation

```bash
yarn add tanisa
# or
npm install tanisa
```

## Usage

```ts
import { Tanisa } from 'tanisa'

const tanisa = new Tanisa()
```

---

## `.toWords(input, options?)`

Converts a number (or numeric string) to its Malagasy word representation.

```ts
tanisa.toWords(233) // "telo amby telopolo sy roanjato"
tanisa.toWords(18.3) // "valo ambin'ny folo faingo telo"
tanisa.toWords(0.008) // "aotra faingo aotra aotra valo"
tanisa.toWords(12_345_678_901)
// "iraika amby sivinjato sy valo arivo sy fito alina sy enina hetsy sy dimy tapitrisa
//  sy efatra safatsiroa sy telo tsitamboisa sy roa lavitrisa sy iray alinkisa"
```

### Options

| Option          | Type      | Default           | Description                                                                                                 |
| :-------------- | :-------- | :---------------- | :---------------------------------------------------------------------------------------------------------- |
| `ignoreDecimal` | `boolean` | `false`           | Ignore all digits after the decimal point.                                                                  |
| `decimalPlaces` | `number`  | `undefined` (all) | Maximum decimal digits to convert. Extra digits are truncated (not rounded). Set to `0` to ignore decimals. |

> If both `ignoreDecimal: true` and `decimalPlaces` are set, `ignoreDecimal` takes precedence.

```ts
tanisa.toWords('456.789', { ignoreDecimal: true }) // "enina amby dimampolo sy efajato"
tanisa.toWords('3.14567', { decimalPlaces: 2 }) // "telo faingo efatra ambin'ny folo"
tanisa.toWords('3.14567', { decimalPlaces: 2, ignoreDecimal: true }) // "telo"
```

---

## `.toDate(input, options?)`

Converts a date to Malagasy. Accepts a date string, a `Date` object, or a Unix timestamp (ms).

### Short format (default)

```ts
tanisa.toDate('2020-01-01') // "01 Janoary 2020"
tanisa.toDate('2022-12-25') // "25 Desambra 2022"
tanisa.toDate(new Date(2022, 11, 25)) // "25 Desambra 2022"
tanisa.toDate(1640390400000) // "25 Desambra 2021" (Unix ms)
tanisa.toDate('2020-01-15T10:30:00Z') // "15 Janoary 2020"
```

### Long format

```ts
tanisa.toDate('2020-01-01', { format: 'long' })
// "voalohan'ny volana Janoary, taona roapolo sy roa arivo"

tanisa.toDate('2022-12-25', { format: 'long' })
// "dimy amby roapolo Desambra, taona roa amby roapolo sy roa arivo"

tanisa.toDate('2000-06-10', { format: 'long' })
// "folo Jona, taona roa arivo"
```

### Options

| Option   | Type                | Default   | Description                                                                                                  |
| :------- | :------------------ | :-------- | :----------------------------------------------------------------------------------------------------------- |
| `format` | `'short' \| 'long'` | `'short'` | `'short'` — zero-padded day + month name + year. `'long'` — fully spoken day, month name, and year in words. |

---

## `.toTime(input, options?)`

Converts a time to Malagasy spoken form with the correct time-of-day period. Accepts a time string (`HH:MM`, `HH:MM:SS`), an ISO datetime string, a `Date` object, or a Unix timestamp (ms).

### Time periods

| Period     | Hours                              |
| :--------- | :--------------------------------- |
| maraina    | 01:00 – 09:59                      |
| antoandro  | 10:00 – 12:59                      |
| tolakandro | 13:00 – 16:59                      |
| hariva     | 17:00 – 19:59                      |
| alina      | 20:00 – 23:59 and midnight (00:xx) |

### Examples

```ts
tanisa.toTime('01:00') // "iray ora maraina"
tanisa.toTime('10:00') // "folo ora antoandro"
tanisa.toTime('13:00') // "iray ora tolakandro"
tanisa.toTime('17:00') // "dimy ora hariva"
tanisa.toTime('20:00') // "valo ora alina"
tanisa.toTime('00:00') // "roa ambin'ny folo ora alina"  (midnight)

tanisa.toTime('09:30') // "sivy ora sy telopolo minitra maraina"
tanisa.toTime('16:45') // "efatra ora sy dimy amby efapolo minitra tolakandro"
```

### Seconds precision

```ts
tanisa.toTime('14:30:45', { precision: 'seconds' })
// "roa ora sy telopolo minitra sy dimy amby efapolo segondra tolakandro"

tanisa.toTime('14:00:30', { precision: 'seconds' })
// "roa ora sy telopolo segondra tolakandro"
```

### Accepted input types

```ts
tanisa.toTime('14:30:00') // plain HH:MM:SS string
tanisa.toTime('2020-01-15T10:00:00Z') // ISO datetime string
tanisa.toTime(new Date(2022, 0, 1, 14, 30, 0)) // Date object
tanisa.toTime(new Date(2022, 0, 1, 14, 30, 0).getTime()) // Unix timestamp (ms)
```

### Options

| Option      | Type                     | Default     | Description                                                                                            |
| :---------- | :----------------------- | :---------- | :----------------------------------------------------------------------------------------------------- |
| `precision` | `'minutes' \| 'seconds'` | `'minutes'` | Include seconds in the output when `'seconds'`. Seconds are omitted if zero even with this option set. |

---

## Error handling

All three methods throw a `TypeError` for invalid or unparseable input, and a `RangeError` for out-of-range values:

```ts
tanisa.toWords('not a number') // throws TypeError
tanisa.toWords(-5) // throws RangeError
tanisa.toDate('2024-13-01') // throws TypeError  (month 13 is invalid)
tanisa.toTime('25:00') // throws TypeError  (hour 25 is invalid)
```

---

## Contribution

**Contributions are welcome!**

Feel free to check out the [CONTRIBUTING](https://github.com/nifaliana/tanisa/blob/main/CONTRIBUTING.md) file.

## License

This project is proudly released under the [MIT License](https://github.com/nifaliana/tanisa/blob/main/LICENSE)