!Logo

ℂ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:

``bash
npm i @iamsquare/complex.js


or


pnpm i @iamsquare/complex.js
`

Quick Start

`typescript
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

$3

Complex numbers can be created in several ways:

`typescript
// 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);
`

$3

`typescript
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 }
`

$3

`typescript
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"
`

$3

`typescript
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);
`

$3

`typescript
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
`

$3

`typescript
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

$3

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

`bash
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:

`bash
cd docusaurus
pnpm build
`

Development

$3

Clone the repository and build the library:

`bash
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:

`bash
pnpm run build
`

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

$3

- 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