@wollybeard/kit

Appearance

Num.Ratio ​

Num / Ratio

Import ​

typescript
import { Num } from '@wollybeard/kit'

// Access via namespace
Num.Ratio.someFunction()
typescript
import * as Num from '@wollybeard/kit/num'

// Access via namespace
Num.Ratio.someFunction()

Functions ​

[F] is ​

typescript
(value: unknown): boolean
Source

Parameters:

  • value - The value to check

Returns: True if value is a Ratio

Type predicate to check if value is a Ratio.

[F] from ​

typescript
(numerator: Int, denominator: NonZero): Ratio
Source

Parameters:

  • numerator - The top number
  • denominator - The bottom number (non-zero)

Returns: The simplified ratio

Construct a Ratio from numerator and denominator. Automatically simplifies to lowest terms and normalizes sign.

[F] fromDecimal ​

typescript
(value: number, maxDenominator?: number = 10000): Ratio
Source

Parameters:

  • value - The decimal number
  • maxDenominator - Maximum denominator to use (default: 10000)

Returns: The ratio approximation

Convert a decimal number to a Ratio with specified precision. Useful for converting floats to exact ratios.

[F] simplify ​

typescript
(ratio: Ratio): Ratio
Source

Parameters:

  • ratio - The ratio to simplify

Returns: The simplified ratio

Simplify a ratio to lowest terms. Note: from() already does this, but this is useful for ratios from other sources.

[F] toDecimal ​

typescript
(ratio: Ratio): number
Source

Parameters:

  • ratio - The ratio to convert

Returns: The decimal representation

Convert ratio to decimal number. Note: This may lose precision for ratios like 1/3.

[F] add ​

typescript
(a: Ratio, b: Ratio): Ratio
Source

Parameters:

  • a - First ratio
  • b - Second ratio

Returns: The sum as a simplified ratio

Add two ratios. Result is automatically simplified.

[F] subtract ​

typescript
(a: Ratio, b: Ratio): Ratio
Source

Parameters:

  • a - First ratio
  • b - Second ratio

Returns: The difference as a simplified ratio

Subtract two ratios. Result is automatically simplified.

[F] multiply ​

typescript
(a: Ratio, b: Ratio): Ratio
Source

Parameters:

  • a - First ratio
  • b - Second ratio

Returns: The product as a simplified ratio

Multiply two ratios. Result is automatically simplified.

[F] divide ​

typescript
(a: Ratio, b: Ratio): Ratio
Source

Parameters:

  • a - First ratio (dividend)
  • b - Second ratio (divisor, must be non-zero)

Returns: The quotient as a simplified ratio

Throws:

  • Error if b is zero

Divide two ratios. Result is automatically simplified.

[F] compare ​

typescript
(a: Ratio, b: Ratio): 0 | 1 | -1
Source

Parameters:

  • a - First ratio
  • b - Second ratio

Returns: -1, 0, or 1

Compare two ratios. Returns -1 if a

b, 0 if a = b, 1 if a

b.

[F] reciprocal ​

typescript
(ratio: Ratio): Ratio
Source

Parameters:

  • ratio - The ratio to invert

Returns: The reciprocal

Throws:

  • Error if ratio is zero

Get the reciprocal (inverse) of a ratio.

[F] toMixedNumber ​

typescript
(ratio: Ratio): { whole: Int; fraction: Ratio; }
Source

Parameters:

  • ratio - The ratio to convert

Returns: Object with whole and fractional parts

Convert ratio to mixed number representation. Returns whole part and fractional part.

Constants ​

[C] fromWith ​

typescript
;((denominator: NonZero) => (numerator: Int) => Ratio)
Source

Create a function that constructs ratios with a fixed numerator. Useful for creating unit fractions.

[C] fromOn ​

typescript
;((numerator: Int) => (denominator: NonZero) => Ratio)
Source

Create a function that constructs ratios with a fixed denominator. Useful for working with common denominators.

[C] addOn ​

typescript
;((a: Ratio) => (b: Ratio) => Ratio)
Source

Create a function that adds a specific ratio. Useful for repeated additions.

[C] addWith ​

typescript
;((b: Ratio) => (a: Ratio) => Ratio)
Source

Create a function that adds to a specific ratio. Useful for accumulating values.

[C] subtractWith ​

typescript
;((a: Ratio) => (b: Ratio) => Ratio)
Source

Create a function that subtracts from a specific ratio. Useful for calculating remainders.

[C] subtractOn ​

typescript
;((a: Ratio) => (b: Ratio) => Ratio)
Source

Create a function that subtracts a specific ratio. Useful for repeated subtractions.

[C] multiplyOn ​

typescript
;((a: Ratio) => (b: Ratio) => Ratio)
Source

Create a function that multiplies by a specific ratio. Useful for scaling.

[C] multiplyWith ​

typescript
;((b: Ratio) => (a: Ratio) => Ratio)
Source

Create a function that multiplies a specific ratio. Useful for applying ratios to values.

[C] divideWith ​

typescript
;((a: Ratio) => (b: Ratio) => Ratio)
Source

Create a function that divides from a specific ratio. Useful for finding proportions.

[C] divideOn ​

typescript
;((a: Ratio) => (b: Ratio) => Ratio)
Source

Create a function that divides by a specific ratio. Useful for repeated divisions.

[C] compareOn ​

typescript
;((a: Ratio) => (b: Ratio) => 0 | 1 | -1)
Source

Create a function that compares against a specific ratio. Useful for filtering or sorting.

[C] compareWith ​

typescript
;((b: Ratio) => (a: Ratio) => 0 | 1 | -1)
Source

Create a function that compares a specific ratio. Useful for finding where a ratio fits in a range.

Types ​

[∩] Ratio ​

typescript
type Ratio = {
  readonly numerator: Int
  readonly denominator: NonZero
} & { [RatioBrand]: true }
Source

Ratio (rational number)

  • a number expressible as p/q where q ≠ 0.

Ratios provide exact arithmetic without floating-point errors, making them ideal for:

  • Financial calculations (no lost pennies)
  • Music theory (frequency ratios like 3:2 for perfect fifth)
  • Aspect ratios and proportions
  • Probability calculations
  • Any domain requiring exact fractional values