https://github.com/florianwendelborn/nullish-math
TypeScript Library for Basic Math Operations with Support for Null
https://github.com/florianwendelborn/nullish-math
javascript library math null-safety nullish typescript
Last synced: 4 months ago
JSON representation
TypeScript Library for Basic Math Operations with Support for Null
- Host: GitHub
- URL: https://github.com/florianwendelborn/nullish-math
- Owner: FlorianWendelborn
- License: mit
- Created: 2023-04-09T14:19:35.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-24T06:29:05.000Z (over 1 year ago)
- Last Synced: 2025-06-28T22:36:38.832Z (12 months ago)
- Topics: javascript, library, math, null-safety, nullish, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/nullish-math
- Size: 43.9 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license.md
Awesome Lists containing this project
README
# nullish-math
`nullish-math` is a lightweight TypeScript package that provides basic math operations with support for `null` and `undefined` values and an immutable, chainable API. It is useful when working with numeric data that may contain nullish values, as it ensures that any calculations involving nullish values result in `null` values.
## Installation
To install `nullish-math`, use one of the following commands:
```sh
bun add nullish-math
npm install nullish-math
pnpm add nullish-math
yarn add nullish-math
```
## Usage
To use `nullish-math`, simply import the `nm()` function from the package:
```ts
import { nm } from 'nullish-math'
```
You can then use the `nm()` function to create a new `NullishMath` object with an initial value:
```ts
const value = nm(42)
```
You can chain together multiple math operations using the `add()`, `subtract()`, `multiply()`, and `divide()` methods:
```ts
const result = nm(42).add(21).multiply(2).subtract(10).end() // 116
// null results in null
const result = nm(42).add(null).multiply(2).subtract(10).end() // null
// undefined results in null
const result = nm(undefined).add(21).multiply(2).subtract(10).end() // null
```
If any of the values passed to the math operation methods (`add()`, `subtract()`, `multiply()`, `divide()`) are nullish, the final value will be `null`.
## API
### `nm(value: number | null | undefined): NullishMath`
The `nm()` function creates a new `NullishMath` object with an initial value.
#### `add(number: NullishMath | number | null | undefined): NullishMath`
Returns a new instance of `NullishMath` with the sum of the current value and the given number.
#### `addMany(...nums: Array): NullishMath`
Returns a new instance of `NullishMath` with the sum of the current value and the given numbers.
#### `eq(toCompare: NullishMath | number | null | undefined): boolean`
Returns `true` if the result equals `toCompare`, treats null and undefined as equals.
#### `lt(toCompare: NullishMath | number | null | undefined): boolean | null`
Returns `true` if the result is strictly less than `toCompare`, returns `null` if either number is nullish.
#### `lte(toCompare: NullishMath | number | null | undefined): boolean | null`
Returns `true` if the result is less than or equal to `toCompare`, returns `null` if either number is nullish.
#### `gt(toCompare: NullishMath | number | null | undefined): boolean | null`
Returns `true` if the result is strictly greater than `toCompare`, returns `null` if either number is nullish.
#### `gte(toCompare: NullishMath | number | null | undefined): boolean | null`
Returns `true` if the result is greater than or equal to `toCompare`, returns `null` if either number is nullish.
#### `neq(toCompare: NullishMath | number | null | undefined): boolean`
Returns `true` if the result doesn’t equal `toCompare`, treats null and undefined as equals.
#### `subtract(number: NullishMath | number | null | undefined): NullishMath`
Returns a new instance of `NullishMath` with the difference of the current value and the given number.
#### `subtractMany(...nums: Array): NullishMath`
Returns a new instance of `NullishMath` with the difference of the current value and the given numbers.
#### `multiply(number: NullishMath | number | null | undefined): NullishMath`
Returns a new instance of `NullishMath` with the product of the current value and the given number.
#### `multiplyMany(...nums: Array): NullishMath`
Returns a new instance of `NullishMath` with the product of the current value and the given numbers.
#### `divide(number: NullishMath | number | null | undefined): NullishMath`
Returns a new instance of `NullishMath` with the quotient of the current value and the given number.
#### `divideMany(...nums: Array): NullishMath`
Returns a new instance of `NullishMath` with the quotient of the current value and the given numbers.
#### `end(): number | null`
Returns the final value of the `NullishMath` instance. If any of the values passed to the math operation methods are `null` or `undefined`, the final value will be `null`.
### `NullishMath.average(Array, options?: { treatNullishAsZero?: boolean }): NullishMath`
Calculates the average of the provided numbers. By default, `null`s are excluded from the average. This can be changed by setting the `treatNullishAsZero` option. With this flag, nullish numbers get counted as a `0` and thus impact the average.
### `NullishMath.max(Array): NullishMath`
Calculates the maximum of the provided numbers. Ignores `null` and `undefined`. Returns `null` if no proper number was provided
### `NullishMath.min(Array): NullishMath`
Calculates the minimum of the provided numbers. Ignores `null` and `undefined`. Returns `null` if no proper number was provided
### `NullishMath.unwrap(NullishMath | number | null | undefined): number | null`
Converts the input to either `number | null`. General-purpose equivalent of `nm.end()`
## Development
`nullish-math` uses [`bun`](https://bun.sh)
```sh
bun install
# bun run test
```