https://github.com/ericrovell/rational
Rational is rational numbers library written in JavaScript
https://github.com/ericrovell/rational
fractions math numbers rational-numbers
Last synced: 5 months ago
JSON representation
Rational is rational numbers library written in JavaScript
- Host: GitHub
- URL: https://github.com/ericrovell/rational
- Owner: EricRovell
- License: mit
- Created: 2021-07-22T20:14:17.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-03-22T12:47:52.000Z (almost 2 years ago)
- Last Synced: 2025-08-08T15:58:45.553Z (5 months ago)
- Topics: fractions, math, numbers, rational-numbers
- Language: TypeScript
- Homepage:
- Size: 299 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Rational
Rational is JavaScript library for rational numbers manipulations.
## Features
- Build-in Types;
- Dependency-free;
- Extendable;
- Feature rich;
- Immutable;
- Simple chainable API;
- Types included;
- Works in a browser and Node.js;
## Getting started
Package available via [npm](https://www.npmjs.com/package/@ericrovell/rational):
```
npm i @ericrovell/rational
```
```js
import { rational } from "@ericrovell/rational";
rational(2, 3).toString(); // -> "2/3"
rational([ 2, 3] ).toString(); // -> "2/3"
rational({ n: 2, d: 3 }).toString(); // -> "2/3"
```
## Parsing
rational(input)
Parses the given input and created a new `Rational` instance.
```js
rational(1, 2);
rational(0.5);
rational([ 1, 2 ]);
rational([ 1 ]);
rational({ n: 1, d: 2 });
rational("1/2");
rational("-1/2");
rational("+3/-2");
rational(".(1)");
rational("-0.1(2)");
rational("1.23(456)");
rational("1.12'5''");
rational("7'5''");
```
### Supported input
(n?: int = 0, d?: int = 1)
Parses the given input from *two integer arguments* and returns a new `Rational` instance.
```js
rational(1, 2); // 1/2
rational(5); // 5/1
```
(input: float)
Parses the given *float* and returns a new `Rational` instance.
```js
rational(0.5); // 1/2
```
(input: [ n: int = 0, d?: int = 1 ])
Parses the given ratio from *(2-integer tuple)* and returns a new `Rational` instance.
```js
rational([]); // 0/1
rational([ 2 ]); // 2/1
rational([ 1, 2 ]); // 1/2
```
(input: { int?: number = 0, n: int, d?: int = 1 })
Parses the given `Fraction` object and returns a new `Rational` instance.
```js
rational({ n: -1, d: 2 }); // -1/2
rational({ int: -1, n: 2, d: 3 }); // -1 2/3
```
Note: integral part if specified determines the sign of the result.
```js
rational({ int: -1, n: -2, d: 3 }); // -1 2/3
```
(input: StringFraction)
Parses the given *fractional* string in form `{sign?}{int?} {sign?}{numerator}/{sign?}{denominator}` and returns a new `Rational` instance.
```js
rational("1/2"); // 1/2
rational("1 1/2"); // 1 1/2
rational("-2 1/4"); // -2 1/4
```
Note: integral part if specified determines the sign of the result.
```js
rational("-2 -1/4"); // -2 1/4
```
(input: RepeatingDecimal)
Parses the given `RepeatingDecimal` object and returns a new `Rational` instance.
```js
rational({ sign: -1, int: 1, nonrepeat: "2", repeat: "3" }); // -7/30
rational({ repeat: 5 }); // 5/9
```
(input: StringRepeatingDecimal)
Parses the given *repeating decimal* string in form `{sign?}{int?}.{non-repeating}?({repeating})` and returns a new `Rational` instance.
```js
rational(".(1)"); // 1/9
rational("-0.1(2)"); // -2/15
```
(input: Degrees)
Parses the given `Degrees` object and returns a new `Rational` instance.
```js
rational({ deg: 1, min: 1, sec: 1 }); // 3661/3600
rational({ sec: 7 }); // 7/60
```
(input: StringDegrees)
Parses the given *degrees* string in form `{sign?}{degrees?}.{minutes'?}{seconds''?}` and returns a new `Rational` instance.
```js
rational("1.12'5''") // 173/144
rational("-1.2'5''") // -149/144
rational("7'5''") // 17/144
rational("-2'5''") // -5/144
```
## API
.abs
Returns the absolute value of the rational number as new `Rational` instance.
```js
rational(0, 2).abs.toString(); // -> "0/2"
rational(-1, 2).abs.toString(); // -> "1/2"
rational(1, -2).abs.toString(); // -> "1/2"
rational(-1, -2).abs.toString(); // -> "1/2"
rational(1, 2).abs.toString(); // -> "1/2"
```
.add(Rational | Input)
Performs the addition and returns the sum as new `Rational` instance.
```js
rational(1, 2)
.add(1, 4)
.toString(); // -> "3/4"
rational(1, 2)
.add(rational(1, 4))
.toString(); // -> "3/4"
```
.ceil(places = 0)
Returns the rational number rounded up to the next largest decimal place.
```js
rational(29, 7).ceil() // -> 5
rational(29, 7).ceil(1) // -> 4.2
rational(29, 7).ceil(2) // -> 4.15
```
.compare(Rational | Input)
Compares the rational number with another. Results are interpreted as:
- comparable is greater -> 1;
- comparable is smaller -> -1;
- comparable is equal -> 0.
```js
rational(1, 2).compare(2, 4); // -> 0
rational(1, 2).compare(3, 4); // -> -1
rational(1, 2).compare(1, 4); // -> 1
```
Non-strict inequalities can be performed as such:
```js
rational.compare(1/2) >= 0 the same as >=
rational.compare(1/2) <= 0 the same as <=
```
.continued
Returns the [continued fraction](https://en.wikipedia.org/wiki/Continued_fraction) representation of the rational.
The first element holds the integral part.
```js
rational(415, 93).continued // -> [ 4, 2, 6, 7 ]
```
.denominator
Returns the denominator value of the rational number.
```js
rational(1, 2).denominator; // -> 2
```
.div(Rational | Input)
Performs the division and returns the quotient as new `Rational` instance.
```js
rational(1, 2)
.div(1, 4)
.toString(); // -> "2/1"
rational(1, 2)
.div(rational(1, 4))
.toString(); // -> "2/1"
```
.divisible(Rational | Input)
Checks if two rational numbers are divisible.
```js
rational(1, 2).divisible(1, 4) // -> true
rational(5, 8).divisible(2, 7) // -> false
```
.floor(places = 0)
Returns the rational number rounded down to the next smallest or equal decimal place.
```js
rational(29, 7).floor() // -> 4
rational(29, 7).floor(1) // -> 4.1
rational(29, 7).floor(2) // -> 4.14
```
.fractionalPart
Returns the fractional part of the rational number as a new `Rational` instance.
```js
rational(1, 2).fractionalPart.toString(); // -> "1/2"
rational(3, 2).fractionalPart.toString(); // -> "1/2"
```
.gcd(Rational | Input)
Calculates the [GCD](https://en.wikipedia.org/wiki/Greatest_common_divisor) of two rational numbers and returns a new `Rational` instance.
```js
rational(5, 8).gcd(3, 7) // 1/56
rational(2, 3).gcd(7, 5) // 1/15
```
.integralPart
Returns the integral part of the rational number.
```js
rational(1, 2).integralPart; // -> 0
rational(3, 2).integralPart; // -> 1
```
.lcm(Rational | Input)
Calculates the [LCM](https://en.wikipedia.org/wiki/Least_common_multiple) of two rational numbers and returns a new `Rational` instance.
```js
rational(5, 8).lcm(3, 7) // 15/1
```
.mathmod(Rational | Input)
Calculates the [mathematical correct modulo](https://en.wikipedia.org/wiki/Modulo_(mathematics)) of two rational numbers.
```js
rational("-13/3").mathmod("7/8") // -> 1/24
rational("-13/7").mathmod("19/11") // -> 123/77
```
.mod(Rational | Input)
Calculates the modulo of two rational numbers.
```js
rational("13/3").mod("7/8").toString() // -> "5/6"
rational("13/7").mod("19/11").toString() // -> "10/77"
```
.mul(Rational | Input)
Performs the multiplication and returns the product as new `Rational` instance.
```js
rational(1, 2)
.mul(1, 4)
.toString(); // -> "1/8"
rational(1, 2)
.mul(rational(1, 4))
.toString(); // -> "1/8"
```
.numerator
Returns the numerator value of the rational number.
```js
rational(1, 2).numerator; // -> 1
```
.opposite
Returns the opposite rational number as new `Rational` instance.
```js
rational(0, 2).opposite.toString(); // -> "0/2"
rational(-1, 2).opposite.toString(); // -> "1/2"
rational(1, -2).opposite.toString(); // -> "1/2"
rational(-1, -2).opposite.toString(); // -> "-1/2"
rational(1, 2).opposite.toString(); // -> "-1/2"
```
.proper
Returns the boolean indicating if the rational number could be represented as [proper](https://en.wikipedia.org/wiki/Fraction#Proper_and_improper_fractions) fraction.
```js
rational(1, 2).proper; // -> true;
rational(3, 2).proper; // -> false;
```
.pow(Rational | Input)
Calculates the exponentiation result of two rational numbers.
If the result is rational returns a new `Rational` instance.
If the result **irrational** the `null` returned instead.
```js
rational(27).pow(2, 3)?.toString() // -> "9/1"
rational(2).pow(1, 2)?.toString() // -> null
```
.reciprocal
Returns the [reciprocal](https://en.wikipedia.org/wiki/Fraction#Reciprocals_and_the_%22invisible_denominator%22) as new `Rational` instance.
```js
rational(1, 2).reciprocal.toString(); // -> "2/1";
rational(3, 2).reciprocal.toString(); // -> "3/2";
```
.repeating
Returns the boolean indicating if the rational number could be represents a [repeating decimal](https://en.wikipedia.org/wiki/Repeating_decimal).
```js
rational(1, 3).repeating; // -> true;
rational(1, 4).repeating; // -> false;
```
.round(places = 0)
Returns the rational number rounded to fixed decimal places.
```js
rational(23, 8).round() // -> 3
rational(23, 8).round(1) // -> 2.9
rational(23, 8).round(2) // -> 2.88
```
.sign
Returns the sign of the rational number.
```js
rational(0, 2).sign; // -> 0
rational(-1, 2).sign; // -> -1
rational(1, -2).sign; // -> -1
rational(-1, -2).sign; // -> 1
rational(1, 2).sign; // -> 1
```
.sub(Rational | Input)
Performs the subtraction and returns the difference as new `Rational` instance.
```js
rational(1, 2)
.sub(1, 4)
.toString(); // -> "1/4"
rational(1, 2)
.sub(rational(1, 4))
.toString(); // -> "1/4"
```
.toString(proper = false, places?: number)
Returns a `Ratio` string representation.
```js
rational(1, 2).toString() // -> "1/2";
rational("1 1/2").toString() // -> "3/2";
rational({ int: 1, n: 1, d: 3}).toString() // -> "4/3";
rational("0.12(34)").toString() // -> "611/4950";
```
To get a proper fraction string, use the first argument:
```js
rational("1 1/2").toString(true) // -> "1 1/2";
rational(1, 2).toString(true) // -> "1/2";
rational({ int: 1, n: 1, d: 3 }).toString(true) // -> "1 1/3";
```
If the second argument is provided, the decimal string is returned.
The value represents number of places:
```js
rational(1, 2).toString(false, 1) // -> "0.5";
rational("1 1/2").toString(false, 5) // -> "1.5";
```
In case the rational is a repeating decimal, it's representation is preserved:
```js
rational("1 1/3").toString(false, 5) // -> "1.(3)";
```
.valid
Returns a boolean indicating the parsing operation success.
On failed attempt the rational number defaults to 0.
```js
rational(1, 2).valid; // -> true
rational("hi!").valid; // -> false
```
.valueOf(places = 15)
Returns a rational number decimal approximation:
```js
rational(1, 2).valueOf() // -> 0.5;
rational("1 1/2").valueOf() // -> 1.5;
rational({ int: 1, n: 1, d: 3}).valueOf(5) // -> 1.33333;
rational("0.12(34)").valueOf() // -> 0.123434343434343;
```
Method is useful for coercion:
```js
rational(1, 2) + rational(1, 4) // -> 0.75
+rational(1, 5) // -> 0.2
```
## Extending
To extend the functionality for your needs, [extend](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/extends) the parent `Rational` class:
```js
import { Rational } from "@ericrovell/rational";
class RationalExtended extends Rational {
constructor(input: Input = 0, denominator = 1) {
super(input, denominator);
}
get ratio() {
return [ this.numerator, this.denominator ];
}
}
const instance = new RationalExtended(1, 2);
instance.ratio; // -> [ 1, 2 ]
```
## Types
Tha package includes all necessary types useful for all possible valid input options are available for import:
```ts
export type {
Degrees,
Fraction,
Ratio,
RepeatingDecimal,
StringDegrees,
StringFraction,
StringRepeatingDecimal
} from "@ericrovell/rational";
```
## Tests
To run the tests use the `npm run test` command.