ℂomplex.js

A powerful, type-safe complex numbers library for JavaScript and TypeScript. Works seamlessly in browsers and Node.js.

Complex.js provides a comprehensive set of operations and functions for complex number arithmetic, trigonometry, hyperbolic functions, and more. Built with TypeScript, it includes full type definitions out of the box.

Features

• Complete Complex Number Operations - Addition, subtraction, multiplication, division, and more
• Trigonometric Functions - sin, cos, tan, sec, csc, cot and their inverses
• Hyperbolic Functions - sinh, cosh, tanh, sech, csch, coth and their inverses
• Mathematical Functions - Exponentiation, logarithms, powers, square roots, principal values (n-th roots)
• Numerically Stable - Uses robust floating-point comparisons (combining absolute and relative error) and stable algorithms to handle precision errors
• TypeScript Support - Full type definitions included, no @types package needed
• Universal - Works in both browsers and Node.js
• Zero Dependencies - Lightweight and fast
• Multiple Representations - Create from Cartesian, polar, or numeric coordinates

Installation

Install Complex.js using npm or pnpm:

npm i @iamsquare/complex.js
# or
pnpm i @iamsquare/complex.js

Quick Start

import { Complex, add, sum, multiply, sin, exp } from '@iamsquare/complex.js';

// Create complex numbers
const z = new Complex(1, -1);
const w = new Complex({ x: 1, y: -3 });
const k = new Complex({ r: 1, p: Math.PI / 2 });

// Perform operations
const addition = add(z, w);
const total = sum(z, w, k);
const product = multiply(z, w);
const sine = sin(z);
const exponential = exp(z);

console.log(addition.toString()); // => "2 - 4i"

Usage

Creating Complex Numbers

Complex numbers can be created in several ways:

// Numeric arguments (real, imaginary)
const z = new Complex(1, -1);

// Cartesian coordinates
const w = new Complex({ x: 1, y: -3 });

// Polar coordinates (radius, phase in radians)
const k = new Complex({ r: 1, p: Math.PI / 2 });

// From another Complex number
const zz = new Complex(z);

Accessing Parts

const z = new Complex(3, 4);

// Get real and imaginary parts
const realPart = z.getRe(); // 3
const imagPart = z.getIm(); // 4

// Convert to different representations
const cartesian = z.toCartesian(); // { x: 3, y: 4 }
const polar = z.toPolar(); // { r: 5, p: 0.9272952180016122 }

Basic Arithmetic Operations

import { Complex, add, sum, subtract, multiply, divide, negate } from '@iamsquare/complex.js';

const z = new Complex(1, -1);
const w = new Complex(1, -3);

// Addition
const addition = add(z, w);
console.log(addition.toString()); // => "2 - 4i"

// Sum multiple numbers
const z1 = new Complex(1, 2);
const z2 = new Complex(3, 4);
const z3 = new Complex(5, 6);
const total = sum(z1, z2, z3);
console.log(total.toString()); // => "9 + 12i"

// Subtraction
const diff = subtract(z, w);
console.log(diff.toString()); // => "0 + 2i"

// Multiplication
const product = multiply(z, w);
console.log(product.toString()); // => "-2 - 4i"

// Division
const quotient = divide(z, w);
console.log(quotient.toString()); // => "0.4 + 0.2i"

// Negation
const negated = negate(z);
console.log(negated.toString()); // => "-1 + 1i"

Mathematical Functions

import {
  Complex,
  exp,
  log,
  pow,
  sqrt,
  principal,
  sin,
  cos,
  tan,
  sinh,
  cosh,
  tanh,
  asin,
  asinh,
} from '@iamsquare/complex.js';

const z = new Complex(1, 1);

// Exponential and logarithmic functions
const e = exp(z);
const ln = log(z);
const power = pow(z, new Complex(2, 0));
const root = sqrt(z);
const cubeRoot = principal(z, 3);

// Trigonometric functions
const sine = sin(z);
const cosine = cos(z);
const tangent = tan(z);

// Hyperbolic functions
const hypSine = sinh(z);
const hypCosine = cosh(z);
const hypTangent = tanh(z);

// Inverse functions
const arcSine = asin(z);
const arcHyperSine = asinh(z);

Utility Operations

import {
  Complex,
  modulus,
  argument,
  conjugate,
  unit,
  equals,
  isApproximatelyEqual,
  isReal,
  isZero,
} from '@iamsquare/complex.js';

const z = new Complex(3, 4);

// Modulus (absolute value)
const mod = modulus(z); // 5

// Argument (phase)
const arg = argument(z); // 0.9272952180016122

// Complex conjugate
const conj = conjugate(z); // 3 - 4i

// Unit vector
const unitVec = unit(z); // 0.6 + 0.8i

// Equality checks (uses epsilon-based comparison for floating-point precision)
const isEqual = equals(z, new Complex(3, 4)); // true
const isRealNum = isReal(z); // false
const isZeroNum = isZero(z); // false

// Compare floating-point numbers
const approxEqual = isApproximatelyEqual(0.1 + 0.2, 0.3); // true

Predefined Constants

Complex.ZERO; // 0
Complex.ONE; // 1
Complex.I; // i (imaginary unit)
Complex.PI; // π
Complex.HALFPI; // π/2
Complex.E; // e (Euler's number)
Complex.INFINITY; // ∞
Complex.NAN; // NaN
Complex.EPSILON; // Machine epsilon

📖 Documentation

Comprehensive documentation is available at https://complex-js.iamsquare.it.

The documentation includes:

• Complete API reference
• Detailed examples
• Mathematical background
• Usage guides

Local Documentation Development

The documentation website is built using Docusaurus. To work with the documentation locally:

cd docusaurus
pnpm install
pnpm start

This starts a local development server. Most changes are reflected live without restarting the server.

To build the documentation:

cd docusaurus
pnpm build

Development

Building from Source

Clone the repository and build the library:

git clone https://github.com/iamsquare/complex.js.git
cd complex.js
pnpm install
pnpm run prod

pnpm run prod runs tests with coverage and builds the library only if all tests pass. To build without testing:

pnpm run build

Note: This project uses pnpm as its package manager. The preinstall script will enforce this.

Available Scripts

• pnpm test - Run tests
• pnpm test:watch - Run tests in watch mode
• pnpm test:coverage - Run tests with coverage
• pnpm build - Build the library
• pnpm lint - Run ESLint
• pnpm lint:fix - Fix ESLint issues
• pnpm prod - Clean, test with coverage, and build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Please read our Contributing Guide for details on our development process and how to submit pull requests.

License

This project is licensed under the MIT License.

Built With

• TypeScript - Main language
• Vitest - Testing framework
• Rollup - Module bundler
• Docusaurus - Documentation website framework
• pnpm - Fast, disk space efficient package manager

---

Made with ❤️ by iamsquare