or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

arithmetic.mdcomparison-utility.mdconversion-formatting.mdindex.mdmathematical-functions.md
tile.json

tessl/npm-fraction-js

A comprehensive JavaScript library for precise rational number arithmetic using BigInt representation.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/fraction.js@5.3.x

To install, run

npx @tessl/cli install tessl/npm-fraction-js@5.3.0

index.mddocs/

Fraction.js

Fraction.js is a comprehensive JavaScript library that provides precise rational number arithmetic using BigInt representation to overcome floating-point precision limitations. The library enables developers to perform accurate calculations with fractions, convert decimal numbers to their exact fractional representations, and handle mathematical operations without the rounding errors inherent in floating-point arithmetic.

Package Information

  • Package Name: fraction.js
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install fraction.js

Core Imports

import Fraction from "fraction.js";

For CommonJS:

const Fraction = require("fraction.js");

For ESM with named import:

import { Fraction } from "fraction.js";

Basic Usage

import Fraction from "fraction.js";

// Create fractions from various inputs
const f1 = new Fraction(1, 3);        // 1/3
const f2 = new Fraction("0.333");     // Approximate 1/3
const f3 = new Fraction("0.(3)");     // Exact 1/3 with repeating decimal
const f4 = new Fraction([2, 7]);      // 2/7
const f5 = new Fraction({n: 5, d: 8}); // 5/8

// Perform arithmetic operations
const sum = f1.add(f5);               // 1/3 + 5/8 = 23/24
const product = f2.mul(f4);           // Chain operations
const result = product.div(2).simplify();

// Convert to different formats
console.log(sum.toString());          // "0.958(3)"
console.log(sum.toFraction());        // "23/24"
console.log(sum.valueOf());           // 0.9583333333333334

Architecture

Fraction.js is built around several key components:

  • BigInt Precision: Uses BigInt internally for arbitrary precision arithmetic, avoiding JavaScript's floating-point limitations
  • Multiple Input Formats: Supports strings (including repeating decimals), numbers, arrays, objects, and BigInt values
  • Immutable Operations: All arithmetic operations return new Fraction instances, preserving the original
  • Automatic Simplification: Fractions are automatically reduced to lowest terms using GCD computation
  • Chainable API: Methods can be chained together for complex calculations

Capabilities

Arithmetic Operations

Core arithmetic operations including addition, subtraction, multiplication, division, and exponentiation. All operations maintain precision and return simplified fractions.

function add(num: FractionInput): Fraction;
function add(numerator: number | bigint, denominator: number | bigint): Fraction;

function sub(num: FractionInput): Fraction;
function sub(numerator: number | bigint, denominator: number | bigint): Fraction;

function mul(num: FractionInput): Fraction;
function mul(numerator: number | bigint, denominator: number | bigint): Fraction;

function div(num: FractionInput): Fraction;
function div(numerator: number | bigint, denominator: number | bigint): Fraction;

function pow(exponent: FractionInput): Fraction | null;
function pow(numerator: number | bigint, denominator: number | bigint): Fraction | null;

Arithmetic Operations

Mathematical Functions

Advanced mathematical operations including modulo, GCD, LCM, logarithms, and utility functions like absolute value and negation.

function mod(): Fraction;
function mod(num: FractionInput): Fraction;

function gcd(num: FractionInput): Fraction;
function gcd(numerator: number | bigint, denominator: number | bigint): Fraction;

function lcm(num: FractionInput): Fraction;
function lcm(numerator: number | bigint, denominator: number | bigint): Fraction;

function log(base: FractionInput): Fraction | null;
function log(numerator: number | bigint, denominator: number | bigint): Fraction | null;

function abs(): Fraction;
function neg(): Fraction;
function inverse(): Fraction;

Mathematical Functions

Comparison and Utility

Comparison operations and utility functions for testing equality, ordering, divisibility, and rounding operations.

function equals(num: FractionInput): boolean;
function lt(num: FractionInput): boolean;
function lte(num: FractionInput): boolean;
function gt(num: FractionInput): boolean;
function gte(num: FractionInput): boolean;
function compare(num: FractionInput): number;
function divisible(num: FractionInput): boolean;

function ceil(places?: number): Fraction;
function floor(places?: number): Fraction;
function round(places?: number): Fraction;
function roundTo(num: FractionInput): Fraction;

Comparison and Utility

Conversion and Formatting

Methods for converting fractions to various string and numeric representations, including decimal, fractional, LaTeX, and continued fraction formats.

function valueOf(): number;
function toString(decimalPlaces?: number): string;
function toFraction(showMixed?: boolean): string;
function toLatex(showMixed?: boolean): string;
function toContinued(): bigint[];
function clone(): Fraction;
function simplify(eps?: number): Fraction;

Conversion and Formatting

Types

class Fraction {
  constructor();
  constructor(num: FractionInput);
  constructor(numerator: number | bigint, denominator: number | bigint);
  
  // Instance properties
  s: bigint;  // Sign (-1n or 1n)
  n: bigint;  // Numerator (always positive)
  d: bigint;  // Denominator (always positive)
}

// Input types
type FractionInput = 
  | Fraction
  | number
  | bigint
  | string
  | [number | bigint | string, number | bigint | string]
  | NumeratorDenominator;

interface NumeratorDenominator {
  n: number | bigint;
  d: number | bigint;
  s?: number | bigint;  // Optional sign
}

Error Handling

The library throws specific errors for invalid operations:

  • Division by Zero: When attempting to create a fraction with denominator 0
  • Invalid argument: For invalid input formats or values
  • Non-Integer Parameter: When integer values are required but non-integers are provided
try {
  const invalid = new Fraction(1, 0); // Throws "Division by Zero"
} catch (error) {
  console.error(error.message);
}