# integer

> Native 64-bit integers with overflow protection.

Latest version **4.0.0** (published 2020-04-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install integer
pnpm add integer
yarn add integer
bun add integer
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2020-04-21 |
| First published | 2013-07-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/integer) |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 80.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| GitHub stars | 19 |
| Author | Joshua Wise |
| Maintainers | joshuawise |
| Keywords | integer, 64-bit, 64bit, int, overflow, native |

## Links

- npm: https://www.npmjs.com/package/integer
- Repository: https://github.com/JoshuaWise/integer
- Homepage: https://github.com/JoshuaWise/integer#readme
- Issues: https://github.com/JoshuaWise/integer/issues
- npm.io page: https://npm.io/package/integer

## Dependencies (2)

- [bindings](https://npm.io/package/bindings.md) ^1.5.0
- [prebuild-install](https://npm.io/package/prebuild-install.md) ^5.3.3

## Alternatives

- [eslint-plugin-sonarjs](https://npm.io/package/eslint-plugin-sonarjs.md) — 2.9M weekly downloads
- [eslint-config-expo](https://npm.io/package/eslint-config-expo.md) — 1.5M weekly downloads
- [@matter/protocol](https://npm.io/package/@matter/protocol.md) — 63.5K weekly downloads
- [@eventcatalog/linter](https://npm.io/package/@eventcatalog/linter.md) — 24.8K weekly downloads
- [@inrupt/eslint-config-base](https://npm.io/package/@inrupt/eslint-config-base.md) — 4.5K weekly downloads

## Recent versions

- 4.0.0 (latest) — 2020-04-21
- 3.0.1 — 2020-02-24
- 3.0.0 — 2020-02-24
- 2.1.0 — 2018-10-04
- 2.0.1 — 2018-10-04
- 2.0.0 — 2018-09-17
- 1.0.7 — 2018-09-17
- 1.0.6 — 2018-09-17
- 1.0.5 — 2018-06-13
- 1.0.4 — 2018-06-13
- 1.0.3 — 2018-01-20
- 1.0.1 — 2017-06-06
- 1.0.0 — 2017-06-02
- 0.2.0 — 2017-05-31
- 0.0.2 — 2013-07-26
- … 1 more at https://npm.io/package/integer/versions

## README

# integer [![Build Status](https://travis-ci.org/JoshuaWise/integer.svg?branch=master)](https://travis-ci.org/JoshuaWise/integer)

Native 64-bit signed integers in Node.js.

- All standard operators (arithmetic, bitwise, logical)
- Protection from overflow and unsafe numbers
- Always immutable
- Other useful utilities

## Installation

```bash
npm install --save integer
```

> You must be using Node.js v10 or above. Prebuilt binaries are available for [LTS versions](https://nodejs.org/en/about/releases/) + Linux/OSX.

## Usage

```js
var Integer = require('integer');

var a = Integer('7129837312139827189');
var b = a.subtract(1).shiftRight(3);
assert(b.equals('891229664017478398'));
```

## Overflow protection

We will not let you perform operations that would result in overflow. If you try to create an `Integer` that cannot be represented in 64-bits (signed), we will throw a `RangeError`.

```js
// These will each throw a RangeError
var tooBig = Integer(13897283129).multiply(13897283129);
var tooSmall = Integer.MIN_VALUE.subtract(1);
var divideByZero = Integer(123).divide(0);
var alsoTooBig = Integer('4029384203948203948923');

// You are also protected against two's complement overflow (this will throw a RangeError)
var twosComplement = Integer.MIN_VALUE.divide(-1);
```

## Unsafe number protection

It's easy to convert between me and regular JavaScript numbers.

```js
var int = Integer(12345);
assert(int instanceof Integer);

var num = Number(int); // same as int.toNumber()
assert(typeof num === 'number');
```

However, we will prevent you from converting an `Integer` to an unsafe number, and vice-versa. To learn more about unsafe numbers, [click here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger).

```js
// This will throw a RangeError
var unsafe = Integer(Number.MAX_SAFE_INTEGER + 1);

// This is okay
var int = Integer(Number.MAX_SAFE_INTEGER).plus(1);

// But this will throw a RangeError
var unsafe = int.toNumber();
```

# API

### Integer(*value*) -> *Integer*

Casts a value to an `Integer`. If the value cannot be converted safely and losslessly, a `RangeError` is thrown.

```js
var a = Integer();
var b = Integer(12345);
var c = Integer('12345');
assert(a.equals(0));
assert(b.equals(c));
```

### Integer.fromNumber(*number*, [*defaultValue*]) -> *Integer*

Casts a regular number to an `Integer`.

If the number is unsafe the `defaultValue` is used instead (or a `RangeError` is thrown if no `defaultValue` was provided).

```js
Integer.fromNumber(12345, 0); // results in Integer(12345)
Integer.fromNumber(Number.MAX_SAFE_INTEGER + 1, 0); // results in Integer(0)
```

### Integer.fromString(*string*, [*radix*, [*defaultValue*]]) -> *Integer*

Casts a string to an `Integer`. The string is assumed to be [base-10](https://en.wikipedia.org/wiki/Radix) unless a different `radix` is specified.

If conversions fails the `defaultValue` is used instead (or a `RangeError` is thrown if no `defaultValue` was provided).

```js
var hexColor = 'ff55dd';
var int = Integer.fromString(hexColor, 16, 'ffffff');
```

### Integer.fromBits(*lowBits*, [*highBits*]) -> *Integer*

Creates an `Integer` by concatenating two regular 32-bit signed integers. The `highBits` are optional and default to `0`.

```js
var int = Integer.fromBits(0x40, 0x20);
int.toString(16); // => '2000000040'
```

## Arithmetic operations

####     .add/plus(*other*) -> *Integer*
####     .subtract/sub/minus(*other*) -> *Integer*
####     .multiply/mul/times(*other*) -> *Integer*
####     .divide/div/divideBy/dividedBy/over(*other*) -> *Integer*
####     .modulo/mod(*other*) -> *Integer*

Performs the arithmetic operation and returns a new `Integer`. The argument must either be a number, a base-10 string, or an `Integer`. If the operation results in overflow, a `RangeError` is thrown.

####     .negate/neg() -> *Integer*

Returns the unary negation (`-value`) of the `Integer`.

####     .abs/absoluteValue() -> *Integer*

Returns the absolute value of the `Integer`.

## Bitwise operations

####     .and(*other*) -> *Integer*
####     .or(*other*) -> *Integer*
####     .xor(*other*) -> *Integer*
####     .not() -> *Integer*

Performs the bitwise operation and returns a new `Integer`. The argument must either be a number, a base-10 string, or an `Integer`.

####     .shiftLeft/shl(*numberOfBits*) -> *Integer*
####     .shiftRight/shr(*numberOfBits*) -> *Integer*

Shifts the `Integer` by specified number of bits and returns the result.

## Logical operations

####     .equals/eq/isEqualTo(*other*) -> *boolean*
####     .notEquals/neq/isNotEqualTo/doesNotEqual(*other*) -> *boolean*
####     .greaterThan/gt/isGreaterThan(*other*) -> *boolean*
####     .lessThan/lt/isLessThan(*other*) -> *boolean*
####     .greaterThanOrEquals/gte/isGreaterThanOrEqualTo(*other*) -> *boolean*
####     .lessThanOrEquals/lte/isLessThanOrEqualTo(*other*) -> *boolean*

Performs the logical operation and returns `true` or `false`. The argument must either be a number, a base-10 string, or an `Integer`.

####     .compare(*other*) -> *number*

Compares the value of the `Integer` and `other`, resulting in:
- `-1` if `this` is less than `other`
- `1` if `this` is greater than `other`
- `0` if `this` is equal to `other`

## Converting to other values

####     .toString([*radix*]) -> *string*

Converts the `Integer` to a string. A base-10 string is returned unless a different `radix` is specified.

####     .valueOf/toNumber() -> *number*

Converts the `Integer` to a regular number. If the `Integer` is not within the safe range, a `RangeError` is thrown.

####     .toNumberUnsafe() -> *number*

Converts the `Integer` to a regular number, **even if the conversion would result in a loss of precision**. This method will never throw an error.

## Other utility

####     .bitSizeAbs() -> *number*

Returns the number of bits necessary to hold the absolute value of the `Integer`.

```js
Integer(0).bitSizeAbs(); // => 1
Integer(128).bitSizeAbs(); // => 8
Integer(-255).bitSizeAbs(); // => 8
Integer.fromString('4fffffffffff', 16).bitSizeAbs(); // => 47
```

####     .isEven() -> *boolean*
####     .isOdd() -> *boolean*
####     .isPositive() -> *boolean*
####     .isNegative() -> *boolean*
####     .isZero() -> *boolean*
####     .isNonZero/isNotZero() -> *boolean*

These methods are self-explanatory.

####     .isSafe() -> *boolean*
####     .isUnsafe() -> *boolean*

Returns whether or not the `Integer` is within the safe range. If it's not within the safe range, trying to convert it to a regular number would result in a `RangeError` being thrown.

The safe range is defined as `n >= Number.MIN_SAFE_INTEGER && n <= Number.MAX_SAFE_INTEGER`.

#### Integer.isInstance(*value*) -> *boolean*

Determines if the given value is an `Integer` object.

#### Getters

- **.low -> _number_** - the lower 32-bits of the `Integer`
- **.high -> _number_** - the upper 32-bits of the `Integer`

#### Constants

- **Integer.MAX_VALUE** - maximum value of an `Integer`
- **Integer.MIN_VALUE** - minimum value of an `Integer`
- **Integer.ZERO** - an `Integer` with a value of `0`
- **Integer.ONE** - an `Integer` with a value of `1`
- **Integer.NEG_ONE** - an `Integer` with a value of `-1`

## License

[MIT](https://github.com/JoshuaWise/integer/blob/master/LICENSE)

---
_Source: https://npm.io/package/integer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._