tanisa

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

yarn add tanisa
# or
npm install tanisa

Usage

import { Tanisa } from 'tanisa'

const tanisa = new Tanisa()

.toWords(input, options?)

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

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.

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)

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

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

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

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

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:

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 file.

License

This project is proudly released under the MIT License