https://github.com/vladkens/fractions-math
🐍🔢 Implementing fractions module from The Python Standard Library on TypeScript.
https://github.com/vladkens/fractions-math
cjs esm fractions math npm-modules printer rational-numbers unicode
Last synced: 26 days ago
JSON representation
🐍🔢 Implementing fractions module from The Python Standard Library on TypeScript.
- Host: GitHub
- URL: https://github.com/vladkens/fractions-math
- Owner: vladkens
- License: mit
- Created: 2023-05-31T10:34:29.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-06-01T16:36:49.000Z (about 3 years ago)
- Last Synced: 2024-03-15T15:08:46.612Z (about 2 years ago)
- Topics: cjs, esm, fractions, math, npm-modules, printer, rational-numbers, unicode
- Language: TypeScript
- Homepage: https://npm.im/fractions-math
- Size: 42 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
- Codeowners: .github/codeowners
Awesome Lists containing this project
README
# fractions-math
[
](https://npmjs.org/package/fractions-math)
[
](https://packagephobia.now.sh/result?p=fractions-math)
[
](https://npmjs.org/package/fractions-math)
[
](https://github.com/vladkens/fractions-math/blob/main/LICENSE)
[
](https://buymeacoffee.com/vladkens)
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
```sh
npm i fractions-math
```
```sh
yarn add fractions-math
```
## Usage
```ts
import { Fraction, fraq, fraqOrNull, gcd } from "fractions-math"
```
### Create fractions
**`fraq`** converts strings, numbers, tuples, and existing fractions into a `Fraction`.
```ts
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.
```ts
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.
```ts
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.
```ts
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.
```ts
fraq("15/10").toString() // -> "15/10"
fraq("15/10").reduce().toString() // -> "3/2"
```
**`limit`** finds a nearby fraction with a bounded denominator.
```ts
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.
```ts
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.
```ts
gcd(24, 36) // -> 12
gcd(999, 1000) // -> 1
```
### Format output
**`toString` / `toNumber` / `toPair`** convert fractions into the shape you need.
```ts
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.
```ts
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.
```ts
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
```ts
type Fraq = Fraction | [number, number] | number | string
```