# @canvas-js/utils

> [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg)](https://github.com/RichardLitt/standard-readme) [![license](https://img.shields.io/github/license/canvasxyz/utils)](https://opensource.org/licenses/MIT) [

Latest version **1.0.0** (published 2025-03-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @canvas-js/utils
pnpm add @canvas-js/utils
yarn add @canvas-js/utils
bun add @canvas-js/utils
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2025-03-19 |
| First published | 2024-04-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 0 |
| Unpacked size | 14.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Canvas Technologies, Inc. |
| Maintainers | joelg, raykyri, rjwebb |

## Links

- npm: https://www.npmjs.com/package/@canvas-js/utils
- Repository: https://github.com/canvasxyz/utils
- Homepage: https://github.com/canvasxyz/utils#readme
- Issues: https://github.com/canvasxyz/utils/issues
- npm.io page: https://npm.io/package/@canvas-js/utils

## Recent versions

- 1.0.0 (latest) — 2025-03-19
- 0.14.0-next.1 (next) — 2025-01-29
- 0.10.0-beta.3 (beta) — 2024-06-27
- 0.10.0-alpha.1 (alpha) — 2024-05-21
- 0.13.14 — 2025-01-29
- 0.13.13 — 2025-01-29
- 0.13.12 — 2025-01-23
- 0.13.11 — 2025-01-22
- 0.14.0-next.0 — 2025-01-16
- 0.13.10 — 2025-01-09
- 0.13.9 — 2024-12-17
- 0.13.8-next.1 — 2024-12-14
- 0.13.8-next.0 — 2024-12-13
- 0.13.7 — 2024-12-12
- 0.13.6 — 2024-12-11
- … 53 more at https://npm.io/package/@canvas-js/utils/versions

## README

# @canvas-js/utils

[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg)](https://github.com/RichardLitt/standard-readme) [![license](https://img.shields.io/github/license/canvasxyz/utils)](https://opensource.org/licenses/MIT) [![NPM version](https://img.shields.io/npm/v/@canvas-js/utils)](https://www.npmjs.com/package/@canvas-js/utils) ![TypeScript types](https://img.shields.io/npm/types/@canvas-js/utils)

This repo is for utility methods and types related to JavaScript programming in general.

Anything that is only used by a single package should go in that package's src/utils.ts file; and anything that is related to a specific feature or domain should go in its own utility package.

## Table of contents

- [API](#api)
  - [`assert`](#assert)
  - [`Awaitable`](#awaitable)
  - [`JSONValue`](#jsonvalue)
  - [`JSValue`](#jsvalue)
  - [`deepEqual`](#deepequal)
  - [`mapEntries`](#mapentries)
  - [`mapKeys`](#mapkeys)
  - [`mapValues`](#mapvalues)
  - [`replaceUndefined`](#replaceendefined)
  - [`stripUndefined`](#stripendefined)
  - [`signalInvalidType`](#signalinvalidtype)
  - [`zip`](#zip)
- [License](#license)

## API

### `assert`

```ts
export function assert(condition: unknown, message?: string): asserts condition
```

### `Awaitable`

```ts
export type Awaitable<T> = T | Promise<T>
```

### `JSONValue`

```ts
export type JSONValue =
  | null
  | boolean
  | number
  | string
  | JSONArray
  | JSONObject

export interface JSONArray extends Array<JSONValue> {}
export interface JSONObject {
  [key: string]: JSONValue
}
```

### `JSValue`

```ts
export type JSValue =
  | undefined
  | null
  | boolean
  | number
  | string
  | Uint8Array
  | JSArray
  | JSObject

export interface JSArray extends Array<JSValue> {}
export interface JSObject {
  [key: string]: JSValue
}

export function isArray(value: JSValue): value is JSArray
export function isObject(value: JSValue): value is JSObject

export type JSType =
  | "undefined"
  | "null"
  | "boolean"
  | "number"
  | "string"
  | "Uint8Array"
  | "Array"
  | "Object"

export function typeOf(value: JSValue): JSType
```

### `deepEqual`

```ts
export function deepEqual(a: JSValue, b: JSValue): boolean
```

### `mapEntries`

```ts
export function mapEntries<K extends string, S, T>(
  object: Record<K, S>,
  map: (entry: [key: K, value: S]) => T,
): Record<K, T>
```

### `mapKeys`

```ts
export function mapKeys<K extends string, S, T>(
  object: Record<K, S>,
  map: (key: K) => T,
): Record<K, T>
```

### `mapValues`

```ts
export function mapValues<K extends string, S, T>(
  object: Record<K, S>,
  map: (value: S) => T,
): Record<K, T>
```

### `replaceUndefined`

```ts
/** Recursively replace every `undefined` with `null` in ararys and objects */
export function replaceUndefined(value: JSValue, inPlace = false): JSValue
```

### `stripUndefined`

```ts
/** Recursively remove every object entry with value `undefined` */
export function stripUndefined(value: JSValue, inPlace = false): JSValue
```

### `signalInvalidType`

```ts
export function signalInvalidType(type: never): never
```

### `zip`

```ts
export type Zip<E> = E extends Iterable<any>[]
  ? { [k in keyof E]: E[k] extends Iterable<infer T> ? T : E[k] }
  : never

export function zip<E extends Iterable<any>[]>(
  ...args: E
): Iterable<[...Zip<E>, number]>
```

## License

MIT © Canvas Technologies, Inc.

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