feat: add support for zero fractional in currency (#2182)

* feat: add support for zero fractional in currency

* test: improve test coverage for ToWordsCore

Author: mastermunj

CHANGELOG.md

@@ -4,10 +4,9 @@ All notable changes to this project will be documented in this file. See [commit
 
 ## [5.2.1](https://github.com/mastermunj/to-words/compare/v5.2.0...v5.2.1) (2026-03-04)
 
-
 ### Bug Fixes
 
-* add codeowners ([ea5e648](https://github.com/mastermunj/to-words/commit/ea5e6484edf0127647692089d0a48d2cfe291ff3))
+- add codeowners ([ea5e648](https://github.com/mastermunj/to-words/commit/ea5e6484edf0127647692089d0a48d2cfe291ff3))
 
 ## [5.2.0](https://github.com/mastermunj/to-words/compare/v5.1.0...v5.2.0) (2026-03-04)
 

README.md

@@ -244,6 +244,10 @@ tw.convert(452.36, { currency: true, ignoreDecimal: true });
 // Ignore zero currency
 tw.convert(0.36, { currency: true, ignoreZeroCurrency: true });
 // "Thirty Six Paise Only"
+
+// Show fractional unit even when zero (string input preserves .00)
+tw.convert('452.00', { currency: true, includeZeroFractional: true });
+// "Four Hundred Fifty Two Rupees And Zero Paise Only"
 ```
 
 **Functional — `toCurrency()` shorthand:**
@@ -689,6 +693,7 @@ interface ToWordsOptions {
     ignoreDecimal?: boolean; // Default: false
     ignoreZeroCurrency?: boolean; // Default: false
     doNotAddOnly?: boolean; // Default: false
+    includeZeroFractional?: boolean; // Default: false
     currencyOptions?: {
       name: string;
       plural: string;
@@ -800,13 +805,14 @@ detectLocale('en-GB'); // custom fallback if detection fails
 
 ### Converter Options
 
-| Option               | Type    | Default   | Description                                                  |
-| -------------------- | ------- | --------- | ------------------------------------------------------------ |
-| `currency`           | boolean | false     | Convert as currency with locale-specific formatting          |
-| `ignoreDecimal`      | boolean | false     | Ignore fractional part when converting                       |
-| `ignoreZeroCurrency` | boolean | false     | Skip zero main currency (e.g., show only "Thirty Six Paise") |
-| `doNotAddOnly`       | boolean | false     | Omit "Only" suffix in currency mode                          |
-| `currencyOptions`    | object  | undefined | Override locale's default currency settings                  |
+| Option                  | Type    | Default   | Description                                                                                      |
+| ----------------------- | ------- | --------- | ------------------------------------------------------------------------------------------------ |
+| `currency`              | boolean | false     | Convert as currency with locale-specific formatting                                              |
+| `ignoreDecimal`         | boolean | false     | Ignore fractional part when converting                                                           |
+| `ignoreZeroCurrency`    | boolean | false     | Skip zero main currency (e.g., show only "Thirty Six Paise")                                     |
+| `doNotAddOnly`          | boolean | false     | Omit "Only" suffix in currency mode                                                              |
+| `includeZeroFractional` | boolean | false     | When input is a string like `"123.00"`, include "And Zero Paise" even though the decimal is zero |
+| `currencyOptions`       | object  | undefined | Override locale's default currency settings                                                      |
 
 ### Common Options Example
 

__tests__/ToWordsCore.test.ts

@@ -8,6 +8,7 @@ describe('ToWordsCore - DefaultConverterOptions', () => {
       ignoreDecimal: false,
       ignoreZeroCurrency: false,
       doNotAddOnly: false,
+      includeZeroFractional: false,
     });
   });
 });
@@ -655,4 +656,32 @@ describe('ToWordsCore - internal coverage via subclass', () => {
     const result = core.convert(100, { currency: false });
     expect(result).toBe('One Hundred');
   });
+
+  test('includeZeroFractional uses fractionalUnit.numberSpecificForms[0] when defined (line 527)', async () => {
+    const { default: EnInLocale } = await import('../src/locales/en-IN');
+    const core = new ToWordsCore();
+    core.setLocale(EnInLocale);
+
+    const result = core.convert('5.00', {
+      currency: true,
+      includeZeroFractional: true,
+      currencyOptions: {
+        name: 'Rupee',
+        plural: 'Rupees',
+        singular: 'Rupee',
+        symbol: '₹',
+        fractionalUnit: {
+          name: 'Paisa',
+          plural: 'Paise',
+          singular: 'Paisa',
+          symbol: '',
+          numberSpecificForms: {
+            0: 'Zero Paise Special',
+          },
+        },
+      },
+    });
+
+    expect(result).toBe('Five Rupees And Zero Paise Special Only');
+  });
 });

__tests__/af-ZA.test.ts

@@ -158,6 +158,27 @@ const testFloats: [number, string][] = [
   [37.683, 'Sewe En Dertig Punt Ses Honderd Drie En Tagtig'],
 ];
 
+describe('Test with options = { currency: true, includeZeroFractional: true }', () => {
+  const testIncludeZeroFractional: [number | string, string][] = [
+    [123, `Een Honderd Drie En Twintig Rand`],
+    ['123', `Een Honderd Drie En Twintig Rand`],
+    ['123.0', `Een Honderd Drie En Twintig Rand En Nul Sente`],
+    ['123.00', `Een Honderd Drie En Twintig Rand En Nul Sente`],
+    ['0.00', `Nul Rand En Nul Sente`],
+    ['-123.00', `Negatief Een Honderd Drie En Twintig Rand En Nul Sente`],
+    ['37.68', `Sewe En Dertig Rand En Agt En Sestig Sente`],
+  ];
+
+  test.concurrent.each(testIncludeZeroFractional)('convert %s => %s', (input, expected) => {
+    expect(
+      toWords.convert(input, {
+        currency: true,
+        includeZeroFractional: true,
+      }),
+    ).toBe(expected);
+  });
+});
+
 describe('Test Floats with options = {}', () => {
   test.concurrent.each(testFloats)('convert %d => %s', (input, expected) => {
     expect(toWords.convert(input as number)).toBe(expected);

__tests__/am-ET.test.ts

@@ -144,6 +144,27 @@ const testFloats: [number, string][] = [
   [37.683, 'ሰላሳ ሰባት ነጥብ ስድስት መቶ ሰማንያ ሦስት'],
 ];
 
+describe('Test with options = { currency: true, includeZeroFractional: true }', () => {
+  const testIncludeZeroFractional: [number | string, string][] = [
+    [123, `አንድ መቶ ሃያ ሦስት ብር ብቻ`],
+    ['123', `አንድ መቶ ሃያ ሦስት ብር ብቻ`],
+    ['123.0', `አንድ መቶ ሃያ ሦስት ብር እና ዜሮ ሳንቲም ብቻ`],
+    ['123.00', `አንድ መቶ ሃያ ሦስት ብር እና ዜሮ ሳንቲም ብቻ`],
+    ['0.00', `ዜሮ ብር እና ዜሮ ሳንቲም ብቻ`],
+    ['-123.00', `አሉታዊ አንድ መቶ ሃያ ሦስት ብር እና ዜሮ ሳንቲም ብቻ`],
+    ['37.68', `ሰላሳ ሰባት ብር እና ስድሳ ስምንት ሳንቲም ብቻ`],
+  ];
+
+  test.concurrent.each(testIncludeZeroFractional)('convert %s => %s', (input, expected) => {
+    expect(
+      toWords.convert(input, {
+        currency: true,
+        includeZeroFractional: true,
+      }),
+    ).toBe(expected);
+  });
+});
+
 describe('Test Floats with options = {}', () => {
   test.concurrent.each(testFloats)('convert %d => %s', (input, expected) => {
     expect(toWords.convert(input as number)).toBe(expected);

__tests__/ar-AE.test.ts

@@ -133,6 +133,27 @@ const testFloats: [number, string][] = [
   [37.683, 'سبعة و ثلاثون فاصلة ستمائة و ثلاثة و ثمانون'],
 ];
 
+describe('Test with options = { currency: true, includeZeroFractional: true }', () => {
+  const testIncludeZeroFractional: [number | string, string][] = [
+    [123, `مائة و ثلاثة و عشرون درهم فقط لا غير`],
+    ['123', `مائة و ثلاثة و عشرون درهم فقط لا غير`],
+    ['123.0', `مائة و ثلاثة و عشرون درهم و صفر فلس فقط لا غير`],
+    ['123.00', `مائة و ثلاثة و عشرون درهم و صفر فلس فقط لا غير`],
+    ['0.00', `صفر درهم و صفر فلس فقط لا غير`],
+    ['-123.00', `سالب مائة و ثلاثة و عشرون درهم و صفر فلس فقط لا غير`],
+    ['37.68', `سبعة و ثلاثون درهم و ثمانية و ستون فلس فقط لا غير`],
+  ];
+
+  test.concurrent.each(testIncludeZeroFractional)('convert %s => %s', (input, expected) => {
+    expect(
+      toWords.convert(input, {
+        currency: true,
+        includeZeroFractional: true,
+      }),
+    ).toBe(expected);
+  });
+});
+
 describe('Test Floats with options = {}', () => {
   test.each(testFloats)('convert %d => %s', (input, expected) => {
     expect(toWords.convert(input as number)).toBe(expected);

__tests__/ar-LB.test.ts

@@ -133,6 +133,27 @@ const testFloats: [number, string][] = [
   [37.683, 'سبعة و ثلاثون فاصلة ستمائة و ثلاثة و ثمانون'],
 ];
 
+describe('Test with options = { currency: true, includeZeroFractional: true }', () => {
+  const testIncludeZeroFractional: [number | string, string][] = [
+    [123, `مائة و ثلاثة و عشرون ليرات فقط لا غير`],
+    ['123', `مائة و ثلاثة و عشرون ليرات فقط لا غير`],
+    ['123.0', `مائة و ثلاثة و عشرون ليرات و صفر قروش فقط لا غير`],
+    ['123.00', `مائة و ثلاثة و عشرون ليرات و صفر قروش فقط لا غير`],
+    ['0.00', `صفر ليرات و صفر قروش فقط لا غير`],
+    ['-123.00', `سالب مائة و ثلاثة و عشرون ليرات و صفر قروش فقط لا غير`],
+    ['37.68', `سبعة و ثلاثون ليرات و ثمانية و ستون قروش فقط لا غير`],
+  ];
+
+  test.concurrent.each(testIncludeZeroFractional)('convert %s => %s', (input, expected) => {
+    expect(
+      toWords.convert(input, {
+        currency: true,
+        includeZeroFractional: true,
+      }),
+    ).toBe(expected);
+  });
+});
+
 describe('Test Floats with options = {}', () => {
   test.each(testFloats)('convert %d => %s', (input, expected) => {
     expect(toWords.convert(input as number)).toBe(expected);

__tests__/ar-MA.test.ts

@@ -133,6 +133,27 @@ const testFloats: [number, string][] = [
   [37.683, 'سبعة و ثلاثون فاصلة ستمائة و ثلاثة و ثمانون'],
 ];
 
+describe('Test with options = { currency: true, includeZeroFractional: true }', () => {
+  const testIncludeZeroFractional: [number | string, string][] = [
+    [123, `مائة و ثلاثة و عشرون درهم فقط لا غير`],
+    ['123', `مائة و ثلاثة و عشرون درهم فقط لا غير`],
+    ['123.0', `مائة و ثلاثة و عشرون درهم و صفر سنتيم فقط لا غير`],
+    ['123.00', `مائة و ثلاثة و عشرون درهم و صفر سنتيم فقط لا غير`],
+    ['0.00', `صفر درهم و صفر سنتيم فقط لا غير`],
+    ['-123.00', `سالب مائة و ثلاثة و عشرون درهم و صفر سنتيم فقط لا غير`],
+    ['37.68', `سبعة و ثلاثون درهم و ثمانية و ستون سنتيم فقط لا غير`],
+  ];
+
+  test.concurrent.each(testIncludeZeroFractional)('convert %s => %s', (input, expected) => {
+    expect(
+      toWords.convert(input, {
+        currency: true,
+        includeZeroFractional: true,
+      }),
+    ).toBe(expected);
+  });
+});
+
 describe('Test Floats with options = {}', () => {
   test.each(testFloats)('convert %d => %s', (input, expected) => {
     expect(toWords.convert(input as number)).toBe(expected);

__tests__/ar-SA.test.ts

@@ -133,6 +133,27 @@ const testFloats: [number, string][] = [
   [37.683, 'سبعة و ثلاثون فاصلة ستمائة و ثلاثة و ثمانون'],
 ];
 
+describe('Test with options = { currency: true, includeZeroFractional: true }', () => {
+  const testIncludeZeroFractional: [number | string, string][] = [
+    [123, `مائة و ثلاثة و عشرون ريال فقط لا غير`],
+    ['123', `مائة و ثلاثة و عشرون ريال فقط لا غير`],
+    ['123.0', `مائة و ثلاثة و عشرون ريال و صفر هللة فقط لا غير`],
+    ['123.00', `مائة و ثلاثة و عشرون ريال و صفر هللة فقط لا غير`],
+    ['0.00', `صفر ريال و صفر هللة فقط لا غير`],
+    ['-123.00', `سالب مائة و ثلاثة و عشرون ريال و صفر هللة فقط لا غير`],
+    ['37.68', `سبعة و ثلاثون ريال و ثمانية و ستون هللة فقط لا غير`],
+  ];
+
+  test.concurrent.each(testIncludeZeroFractional)('convert %s => %s', (input, expected) => {
+    expect(
+      toWords.convert(input, {
+        currency: true,
+        includeZeroFractional: true,
+      }),
+    ).toBe(expected);
+  });
+});
+
 describe('Test Floats with options = {}', () => {
   test.each(testFloats)('convert %d => %s', (input, expected) => {
     expect(toWords.convert(input as number)).toBe(expected);

__tests__/az-AZ.test.ts

@@ -144,6 +144,27 @@ const testFloats: [number, string][] = [
   [37.683, 'Otuz Yeddi Nöqtə Altı Yüz Səksən Üç'],
 ];
 
+describe('Test with options = { currency: true, includeZeroFractional: true }', () => {
+  const testIncludeZeroFractional: [number | string, string][] = [
+    [123, `Bir Yüz İyirmi Üç Manat`],
+    ['123', `Bir Yüz İyirmi Üç Manat`],
+    ['123.0', `Bir Yüz İyirmi Üç Manat Və Sıfır Qəpik`],
+    ['123.00', `Bir Yüz İyirmi Üç Manat Və Sıfır Qəpik`],
+    ['0.00', `Sıfır Manat Və Sıfır Qəpik`],
+    ['-123.00', `Mənfi Bir Yüz İyirmi Üç Manat Və Sıfır Qəpik`],
+    ['37.68', `Otuz Yeddi Manat Və Altmış Səkkiz Qəpik`],
+  ];
+
+  test.concurrent.each(testIncludeZeroFractional)('convert %s => %s', (input, expected) => {
+    expect(
+      toWords.convert(input, {
+        currency: true,
+        includeZeroFractional: true,
+      }),
+    ).toBe(expected);
+  });
+});
+
 describe('Test Floats with options = {}', () => {
   test.concurrent.each(testFloats)('convert %d => %s', (input, expected) => {
     expect(toWords.convert(input as number)).toBe(expected);