@kodex-data/prototypes/docs/README.big.md

A library of TypeScript prototypes that extend built-in types in JavaScript, providing additional functionality to make development easier and more efficient. This library includes prototypes for working with big numbers, Ethereum Virtual Machine (EVM) fu

# @kodex-data/big-prototypes

`@kodex-data/big-prototypes` is a library for extending the global `String` and `Number` prototypes with additional functionality related to big numbers and fractions.

## Installation

You can install `@kodex-data/big-prototypes` using `yarn` or `npm`:

```shell
yarn add @kodex-data/big-prototypes 
```

or

```shell
npm install @kodex-data/big-prototypes 
```

## Usage

After importing the package, the global `String` and `Number` prototypes will be extended with the following methods:

### String

* `toBN(base?: number): BigNumber`: Converts a string to a BigNumber instance.
* `shiftedBy(n: number): string`: Shifts the decimal point of a string by `n` places to the right.
* `shiftedBy(n: number, asBN: undefined | false | null): string`: Shifts the decimal point of a string by `n` places to the right, returning a string value.
* `shiftedBy(n: number, asBN: true): BigNumber`: Shifts the decimal point of a string by `n` places to the right, returning a BigNumber instance.
* `toFraction(): Fraction<string>`: Converts a string to a fraction.
* `toFraction(asBigInt: true): Fraction<BigNumberJS>`: Converts a string to a fraction, returning a `Fraction` instance with `BigNumberJS` values.
* `toFraction(asBigInt?: false): Fraction<string>`: Converts a string to a fraction, returning a `Fraction` instance with string values.
* `toFraction(asBigInt?: boolean | false): Fraction<string | BigNumberJS>`: Converts a string to a fraction, returning a `Fraction` instance with either string or `BigNumberJS` values, depending on the `asBigInt` argument.
* `prettyNum(): string`: Formats a string number with commas for thousands separators.

### Number

* `toBN(): BigNumber`: Converts a number to a BigNumber instance.
* `toUint(add0x?: boolean): string`: Converts a number to an unsigned integer string.
* `shiftedBy(n: number): string`: Shifts the decimal point of a number by `n` places to the right, returning a string value.
* `shiftedBy(n: number, asBN: boolean): BigNumber`: Shifts the decimal point of a number by `n` places to the right, returning a BigNumber instance.
* `noExponents(): string`: Removes scientific notation from a number.
* `prettyNum(): string`: Formats a number with commas for thousands separators.

### Example

```ts
import '@kodex-data/big-prototypes'
const { mul, div } = '0.3'.toFraction()
console.log({ mul, div }) 
```

Output:

```css
{ mul: '3/10', div: '10/3' }
```

## Definitions

```typescript
declare global {
    interface String {
        toBN(base?: number): BigNumber;
        shiftedBy(n: number): string;
        shiftedBy(n: number, asBN: undefined | false | null): string;
        shiftedBy(n: number, asBN: true): BigNumber;
        toFraction(): Fraction<string>;
        toFraction(asBigInt: true): Fraction<BigNumberJS>;
        toFraction(asBigInt?: false): Fraction<string>;
        toFraction(asBigInt?: boolean | false): Fraction<string | BigNumberJS>;
        prettyNum(): string;
    }
    interface Number {
        toBN(): BigNumber;
        toUint(add0x?: boolean): string;
        shiftedBy(n: number): string;
        shiftedBy(n: number, asBN: boolean): BigNumber;
        noExponents(): string;
        prettyNum(): string;
    }
}
```