fractions-math

Python-style fractions for TypeScript, with exact arithmetic, string parsing, and mixed-number output.

• 1.5 KB brotli. dist/main.mjs is 1489 bytes brotli and 1632 bytes gzip.
• Exact math. Add, subtract, multiply, divide, compare, and reduce without floating-point drift.
• Flexible input. Parse 1/2, 1 1/2, 0.125, tuples, numbers, or existing Fraction instances.
• Readable output. Print fractions as 3/4, 1 1/2, or Unicode forms like 1½.

Unlike generic math helpers, this stays close to Python's fractions module and includes ASCII/Unicode formatting that libraries usually leave out.

Install

npm i fractions-math

yarn add fractions-math

Usage

import { Fraction, fraq, fraqOrNull, gcd } from "fractions-math"

Create fractions

fraq converts strings, numbers, tuples, and existing fractions into a Fraction.

fraq(2).toPair() // -> [2, 1]
fraq([3, 4]).toPair() // -> [3, 4]
fraq("1 1/2").toPair() // -> [3, 2]
fraq("0.125").reduce().toPair() // -> [1, 8]

new Fraction gives you explicit control over numerator, denominator, and optional reduction.

new Fraction(5, 10).toPair() // -> [5, 10]
new Fraction(5, 10, true).toPair() // -> [1, 2]
new Fraction(-3, 4).toString() // -> "-3/4"

fraqOrNull returns null instead of throwing on invalid input.

fraqOrNull("1/2")?.toString() // -> "1/2"
fraqOrNull("nope") // -> null

Do exact arithmetic

add / sub / mul / div keep results as fractions instead of falling back to floats.

const price = fraq("1 1/2")

price.add("1/4").toString() // -> "7/4"
price.sub("1/2").toString() // -> "1"
price.mul(3).toString() // -> "9/2"
price.div("3/4").toString() // -> "2"

reduce normalizes a fraction only when you want it.

fraq("15/10").toString() // -> "15/10"
fraq("15/10").reduce().toString() // -> "3/2"

limit finds a nearby fraction with a bounded denominator.

fraq(Math.PI).limit(1000).toString() // -> "355/113"
fraq("0.3333").limit(16).toString() // -> "1/3"

Compare values

eq / lt / lte / gt / gte compare rational values directly.

fraq("1/2").eq(0.5) // -> true
fraq("1/2").lt("2/3") // -> true
fraq("3/4").gte("6/8") // -> true

gcd is also exported if you need integer greatest common divisor logic.

gcd(24, 36) // -> 12
gcd(999, 1000) // -> 1

Format output

toString / toNumber / toPair convert fractions into the shape you need.

const f = fraq("3/2")

f.toString() // -> "3/2"
f.toNumber() // -> 1.5
f.toPair() // -> [3, 2]

toParts splits a value into sign, whole number, numerator, and denominator.

fraq("7/4").toParts() // -> { s: 1, c: 1, n: 3, d: 4 }
fraq("-1/2").toParts() // -> { s: -1, c: 0, n: 1, d: 2 }

toAscii / toUnicode print friendly mixed fractions.

fraq("3/2").toAscii() // -> "1 1/2"
fraq("3/2").toUnicode() // -> "1½"
fraq("1/64").toAscii() // -> "1"
fraq("1/64").toAscii(64) // -> "1/64"
fraq("1/64").toUnicode(64) // -> "¹⁄₆₄"

API

type Fraq = Fraction | [number, number] | number | string