# @swim/util

> Interfaces for ordering, equality, hashing, type conversions, functional maps, interpolators, scales, iterators, builders, key-value maps, caches, and assertions

Latest version **4.0.0** (published 2024-06-09) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @swim/util
pnpm add @swim/util
yarn add @swim/util
bun add @swim/util
```

## Health

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

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

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2024-06-09 |
| First published | 2019-02-18 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 783.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Chris Sachs |
| Maintainers | cwjames19, ajay-gov, c9r |

## Links

- npm: https://www.npmjs.com/package/@swim/util
- Repository: https://github.com/swimos/swim-js
- Homepage: https://github.com/swimos/swim-js/tree/main/swim-core/swim-util
- Issues: https://github.com/swimos/swim-js/issues
- npm.io page: https://npm.io/package/@swim/util

## Dependencies (1)

- [tslib](https://npm.io/package/tslib.md) >= 2.5

## Recent versions

- 4.0.0 (latest) — 2024-06-09
- 4.0.0-dev.20240413 (dev) — 2024-04-13
- 4.0.0-dev.20210927.3 — 2024-04-04
- 4.0.0-dev.20230923 — 2023-09-23
- 4.0.0-dev.20220527.3 — 2022-05-27
- 4.0.0-dev.20220527.2 — 2022-05-27
- 4.0.0-dev.20220527.1 — 2022-05-27
- 4.0.0-dev.20220527 — 2022-05-27
- 4.0.0-dev.20210927.2 — 2021-11-11
- 4.0.0-dev.20210927.1 — 2021-09-27
- 4.0.0-dev.20210927 — 2021-09-27
- 4.0.0-dev.20210923 — 2021-09-23
- 4.0.0-dev.20210920 — 2021-09-20
- 4.0.0-dev.20210826 — 2021-08-26
- 3.11.1 — 2021-08-17
- … 21 more at https://npm.io/package/@swim/util/versions

## README

# [![Swim](https://docs.swimos.org/readme/breach-marlin-blue-wide.svg)](https://www.swimos.org) Swim Util Library

The Swim Util library provides interfaces for ordering, equality, hashing,
type conversions, functional maps, interpolators, scales, iterators, builders,
key-value maps, caches, and assertions.

## Overview

### Ordering, equality, and hashing

Swim Util exports `Comparable`, `Equals`, and `HashCode` interfaces that can
be implemented by ordered, equatable, and hash-able classes, respectively.

```typescript
export interface Comparable<T> {
  compareTo(that: T): number;
}
export interface Equals {
  equals(that: unknown): boolean;
}
export interface HashCode extends Equals {
  hashCode(): number;
}
```

The exported `Objects` object supports generic comparison, equality testing,
and hashing of arbitrary JavaScript values, including primitives, arrays, and
objects.

`Objects.compare(x: unknown, y: unknown): 0 | 1 | -1` returns the relative
sort order of two comparable values. If `x` implements `Comparable`, then
`Objects.compare` delegates to `x`'s `compareTo` method. If `x` and `y` are
both numbers, or both strings, they are compared lexicographically. If `x`
and `y` are both arrays, then each corresponding element is compared, in turn,
using `Objects.compare`. If `x` and `y` are both objects, then each entry is
compared first by key, then by value, using `Objects.compare`. Values of
incompatible types sort in a deterministic order based on type.

`Objects.equal(x: unknown, y: unknown): boolean` returns `true` if two values
are equivalent. If `x` implements `Equals`, then `Objects.equal` delegates to
`x`'s `equals` method. If `x` and `y` are both primitives, then they are
compared by value. If `x` and `y` are both arrays, then each corresponding
element is tested for equality, in turn, using `Objects.equal`. If `x` and `y`
are both objects, then each entry is tested for equality furst by key, then by
value, using `Objects.equal`.

`Objects.hash(x: unknown): number` returns a consistent hash code for `x`.
If `x` implements `HashCode`, then `Objects.hash` delegate's to `x`'s
`hashCode` method. If `x` is a primitive, it is hashed using the `Murmur3`
hashing algorithm. If `x` is an array, each element is hashed individually
using `Objects.hash`, and the hash codes of all elements get mixed together.
If `x` is an object, each entry has its key and value hashed using
`Objects.hash`, and the hash codes of all entries get mixed together.

The exported `Murmur3` object implements the 32-bit
[MurmurHash](https://en.wikipedia.org/wiki/MurmurHash) algorithm, version 3.

### Builder interfaces

The exported `Builder` interface abstracts over construction of collections.
And the `PairBuilder` interface abstracts over construction of key-value maps,
and other pair-containing collections.

```typescript
export interface Builder<I, O> {
  push(...inputs: I[]): void;
  build(): O;
}
export interface PairBuilder<K, V, O> {
  add(key: K, value: V): void;
  build(): O;
}
```

### Map interfaces

Swim Util defines three key-value map interfaces: an ES6-compatible `Map`
interface, as well as an `OrderedMap` interface, and a `ReducedMap` interface.
An `OrderedMap` has its entries sorted by key order. A `ReducedMap` is an
`OrderedMap` that memoizes partial combinations of sub-elements to support
efficient, incremental reduction of continuously mutating datasets.

### Assertions

The exported `Assert` interface provides a common API for constraint testing
and contract enforcement. The exported `assert` singleton provides a default
`Assert` implementation that throws `AssertException` on assert failure.

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