https://github.com/iamsquare/complex.js
A simple complex numbers library written in Typescript.
https://github.com/iamsquare/complex.js
complex-numbers javascript library math node typescript
Last synced: 3 months ago
JSON representation
A simple complex numbers library written in Typescript.
- Host: GitHub
- URL: https://github.com/iamsquare/complex.js
- Owner: iamsquare
- License: mit
- Created: 2018-08-30T23:10:01.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2025-11-11T03:13:05.000Z (8 months ago)
- Last Synced: 2025-11-23T07:29:52.150Z (7 months ago)
- Topics: complex-numbers, javascript, library, math, node, typescript
- Language: TypeScript
- Homepage: https://complex-js.iamsquare.it/
- Size: 989 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# [ℂomplex.js](https://complex-js.iamsquare.it)
[](https://www.npmjs.com/package/@iamsquare/complex.js)
[](https://github.com/iamsquare/complex.js/issues)
[](https://github.com/iamsquare/complex.js/blob/master/LICENSE)
[](https://nodei.co/npm/@iamsquare/complex.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](https://www.npmjs.com/package/@iamsquare/complex.js) or [pnpm](https://pnpm.io/):
```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
### Creating Complex Numbers
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);
```
### Accessing Parts
```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 }
```
### Basic Arithmetic Operations
```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"
```
### Mathematical Functions
```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);
```
### Utility Operations
```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
```
### Predefined Constants
```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](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](https://docusaurus.io/). 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
### Building from Source
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](https://pnpm.io/) 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](.github/CONTRIBUTING.md) for details on our development process and how to submit pull requests.
## License
This project is licensed under the [MIT License](LICENSE).
## Built With
- [TypeScript](https://www.typescriptlang.org/) - Main language
- [Vitest](https://vitest.dev/) - Testing framework
- [Rollup](https://rollupjs.org/) - Module bundler
- [Docusaurus](https://docusaurus.io/) - Documentation website framework
- [pnpm](https://pnpm.io/) - Fast, disk space efficient package manager
---
Made with ❤️ by [iamsquare](https://iamsquare.it)