quantible

v0.3.5

Published

23 days ago

A versatile library for extracting and converting numerical values, units, currency, and mathematical expressions into their spoken word equivalents.

0High
0Medium
0Low

rinaldowouterson

number unit converter natural language spoken word quantity expression spoken words currency math text-to-speech tts numerical values

Quantible - Convert Numbers and Quantities to Spoken Words

Quantible is a versatile JavaScript library designed to convert numbers, quantities, and simple mathematical expressions into easily understandable spoken words. Whether you're building applications that require text-to-speech functionality, accessibility enhancements, or simply need to present numerical data in a more human-readable format, Quantible provides a robust and flexible solution.

Key Features

Comprehensive Quantity Conversion: Handles a wide range of numerical formats, including integers, decimals, negative numbers, currencies, units (e.g., meters, seconds), scientific expressions, and simple mathematical operations.
Flexible Usage: Supports multiple consumption methods including:
- CDN: Directly include in HTML for quick and easy use in web browsers.
- CommonJS (CJS): Integrate into Node.js projects and older JavaScript module systems.
- ECMAScript Modules (ESM): Utilize modern JavaScript module imports for optimized bundling and performance.
String Auto-Replacement: Effortlessly convert all or the first detected quantities within a string, simplifying text manipulation and dynamic content generation.
Extensive Examples: Clear and concise examples to quickly grasp the library's capabilities and integration methods.
Well-Documented and Tested: Thorough documentation and comprehensive test suite ensure reliability and ease of maintenance.
Lightweight and Performant: Optimized for minimal bundle size and efficient execution, ensuring a smooth user experience.

Examples

Quantible handles a wide spectrum of numerical and symbolic expressions, converting them into natural, spoken-word English.

🔢 Numbers, Decimals & Math

123 -> "one hundred twenty-three"
1.5 -> "one point five"
5 - 10 -> "five minus ten"
-5 + 10 -> "negative five plus ten"
1,234,567 -> "one million two hundred thirty-four thousand five hundred sixty-seven"

💰 Currencies (Symbol & Code)

$1,000 -> "one thousand dollars"
€50.00 -> "fifty euros"
100 ₩ -> "one hundred won"
123.45 USD -> "one hundred twenty-three dollars and forty-five cents"
$1.5 -> "one dollar and fifty cents" (Smart padding)

📏 Units & Scientific Notation

10m/s -> "ten meters per second"
15m/s² -> "fifteen meters per second squared"
5E-10 -> "five times ten to the power of negative ten"
1.23e-4 mol·L⁻¹·s⁻¹ -> "one point twenty-three times ten to the power of negative four moles per liter per second"

🏷️ Versioning & Identifiers

v2 -> "v two"
v3.2.1 -> "v three point two point one"
_5 -> "underscore five"
file_name_v2 -> "file underscore name underscore v two"

🔣 Abbreviations & Symbols (Normalization)

A & B -> "A and B"
e.g. -> "example given"
i.e. -> "that is"
[email protected] -> "test at example dot com" (Email normalization)
www.hello.com -> "double you double you double you dot hello dot com" (Website normalization)
Item #1 -> "Item hash one"

The autoReplaceAllMatches function demonstrates the power of Quantible by converting all quantities within a text:

Input Sentence:

"The new SSD offers 2TB capacity, costs $199.99, and runs at 5,400 RPM."

Output Sentence (after autoReplaceAllMatches):

"The new SSD offers two terabytes capacity, costs one hundred ninety-nine dollars and ninety-nine cents, and runs at five thousand four hundred revolutions per minute."

Installation

npm

For projects using npm or yarn:

npm install quantible

How to Consume Quantible

Quantible is designed to be versatile and easily integrated into various JavaScript environments. You can consume it in three primary ways: directly in HTML via CDN, using CommonJS require, or with modern ECMAScript import statements.

1. Directly in HTML via CDN

For the quickest integration into web pages, you can use a Content Delivery Network (CDN) to include Quantible directly in your HTML file. This method is ideal for simple projects or when you want to avoid complex build processes.

<!DOCTYPE html>
<html>
<head>
    <title>Quantible Example</title>
</head>
<body>
    <div id="output"></div>
    <script src="https://unpkg.com/quantible@latest/dist/index.iife.min.js"></script>
    <script>
        const inputString = "The price is $12.50 USD.";
        const spokenText = Quantible.convertQuantities.autoReplaceAllMatches(inputString);
        document.getElementById('output').textContent = spokenText;
    </script>
</body>
</html>

In this example:

We include Quantible by referencing the IIFE build from unpkg CDN: https://unpkg.com/quantible@latest/dist/index.iife.min.js.
The library is then globally accessible as Quantible.
We use Quantible.convertQuantities.autoReplaceAllMatches to process a string and display the spoken word output in the div#output element.

2. CommonJS (CJS) - `require`

For Node.js environments or projects using CommonJS modules, you can import Quantible using require.

const { convertQuantities, extractQuantities } = require('quantible');

const input = "25 EUR";
const extractedData = extractQuantities.firstMatch(input);
const spokenWord = convertQuantities.translateMatch(extractedData);

console.log(spokenWord); // Output: twenty-five euros

3. ECMAScript Modules (ESM) - `import`

For modern JavaScript projects and applications using ECMAScript modules, you can import Quantible using the import statement. This is the recommended approach for most modern JavaScript development.

import { convertQuantities, extractQuantities } from 'quantible';

const input = "100 km/h";
const extractedData = extractQuantities.firstMatch(input);
const spokenWord = convertQuantities.translateMatch(extractedData);

console.log(spokenWord); // Output: one hundred kilometers per hour

Choose the consumption method that best fits your project's environment and build process. Quantible is designed to be flexible and adaptable to your needs.

Example Usage

The following examples demonstrate key functions of Quantible.

Extracting and Translating a Quantity

import { convertQuantities, extractQuantities } from 'quantible';

const input = "123.45 USD";
const extractedData = extractQuantities.firstMatch(input);
const spokenWord = convertQuantities.translateMatch(extractedData);

console.log(spokenWord);
// Output: one hundred twenty-three dollars and forty-five cents

This example shows how to extract and translate the first quantity found in a string.

Auto-replacing all quantities in a string

import { convertQuantities } from 'quantible';

const inputReplaceAllMatches = "I have 5 USD and 10 EUR.";
const replacedString = convertQuantities.autoReplaceAllMatches(inputReplaceAllMatches);
console.log(replacedString); // Output: I have five dollars and ten euros.

This example demonstrates automatically replacing all quantities within a string.

Contributing

We welcome contributions to Quantible! Please see CONTRIBUTING.md for details on how to contribute.

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.