Options
All
  • Public
  • Public/Protected
  • All
Menu

Library @swim/util

@swim/util

package documentation chat

@swim/util is a lightweight utility library for TypeScript applications, providing interfaces and implementations for: ordering, equality, and hashing; type conversions; iterators; builders; maps; caches; and assertions. @swim/util is written in TypeScript, but can be used from either TypeScript or JavaScript. @swim/util is part of the @swim/core framework.

Overview

Ordering, equality, and hashing

@swim/util exports Comparable, Equals, and HashCode interfaces that can be implemented by ordered, equatable, and hashable classes, respectively.

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 algorithm, version 3.

Type conversions

@swim/util provides two generic interfaces for converting between loosely JavaScript values, and strongly typed TypeScript values, called FromAny and ToAny.

export interface FromAny<T, U = T> {
  fromAny(value: T | U): T;
}
export interface ToAny<T> {
  toAny(): T;
}

FromAny is implicitly implemented by classes that have a static fromAny method that converts a loosely typed JavaScript value into a strongly typed TypeScript value. FromAny is implemented by many @swim/ui classes, and is used to abstract over the conversion of loosely typed values to strongly typed values. For example, @swim/view's MemberAnimator classes leverage FromAny to generically convert loosely typed animator arguments to strongly typed, tweenable values.

ToAny is implemented by classes that have a tonAny method that returns a loosely typed JavaScript value. ToAny is used to abstract over the conversion of strongly typed values to loosely typed values.

Iterator interfaces

@swim/util exports an ES6-compatible Iterator interface, as well as a Cursor base class for positioned iterators.

export interface Iterator<T> {
  next(): {value?: T, done: boolean};
}

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.

export interface Builder<I, O> {
  push(...inputs: I[]): void;
  bind(): O;
}
export interface PairBuilder<K, V, O> {
  add(key: K, value: V): void;
  bind(): 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.

Cache implementations

HashGenCacheMap and HashGenCacheSet implement efficient hashed generational caches that discard the least recently used value with the worst hit rate per hash bucket.

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.

Installation

npm

For an npm-managed project, npm install @swim/util to make it a dependency. TypeScript sources will be installed into node_modules/@swim/util/main. Transpiled JavaScript and TypeScript definition files install into node_modules/@swim/util/lib/main. And a pre-built UMD script can be found in node_modules/@swim/util/dist/main/swim-util.js.

Browser

Browser applications can load swim-core.js, which comes bundled with the @swim/util library, directly from the SwimOS CDN.

<!-- Development -->
<script src="https://cdn.swimos.org/js/latest/swim-core.js"></script>

<!-- Production -->
<script src="https://cdn.swimos.org/js/latest/swim-core.min.js"></script>

Alternatively, the standalone swim-system.js script may be loaded from the SwimOS CDN, which bundles @swim/util together with all other @swim/system libraries.

<!-- Development -->
<script src="https://cdn.swimos.org/js/latest/swim-system.js"></script>

<!-- Production -->
<script src="https://cdn.swimos.org/js/latest/swim-system.min.js"></script>

Usage

ES6/TypeScript

@swim/util can be imported as an ES6 module from TypeScript and other ES6-compatible environments.

import * as util from "@swim/util";

CommonJS/Node.js

@swim/util can also be used as a CommonJS module in Node.js applications.

var util = require("@swim/util");

Browser

When loaded by a web browser, the swim-core.js script adds all @swim/util library exports to the global swim namespace.

The swim-system.js script also adds all @swim/util library exports to the global swim namespace, making it a drop-in replacement for swim-core.js when additional @swim/system libraries are needed.

Index

Classes

Interfaces

Type aliases

Variables

Functions

Type aliases

ByteOrder

ByteOrder: "BE" | "LE"

Variables

Const Arrays

Arrays: { empty: ReadonlyArray<never>; compare: any; equal: any; equivalent: any; hash: any; inserted: any; removed: any }

Type declaration

  • Readonly empty: ReadonlyArray<never>
  • compare: function
    • compare(x: undefined | null | ArrayLike<unknown>, y: undefined | null | ArrayLike<unknown>): number

    • Parameters

      • x: undefined | null | ArrayLike<unknown>
      • y: undefined | null | ArrayLike<unknown>

      Returns number

  • equal: function
    • equal(x: undefined | null | ArrayLike<unknown>, y: undefined | null | ArrayLike<unknown>): boolean

    • Parameters

      • x: undefined | null | ArrayLike<unknown>
      • y: undefined | null | ArrayLike<unknown>

      Returns boolean

  • equivalent: function
    • equivalent(x: undefined | null | ArrayLike<unknown>, y: undefined | null | ArrayLike<unknown>, epsilon?: number): boolean

    • Parameters

      • x: undefined | null | ArrayLike<unknown>
      • y: undefined | null | ArrayLike<unknown>
      • Optional epsilon: number

      Returns boolean

  • hash: function
    • hash(x: undefined | null | ArrayLike<unknown>): number

    • Parameters

      • x: undefined | null | ArrayLike<unknown>

      Returns number

  • inserted: function
    • inserted<T>(newElement: T, oldArray: undefined | null | readonly T[]): readonly T[]

    • Type parameters

      • T

      Parameters

      • newElement: T
      • oldArray: undefined | null | readonly T[]

      Returns readonly T[]

  • removed: function
    • removed<T_1>(oldElement: T_1, oldArray: undefined | null | readonly T_1[]): readonly T_1[]

    • Type parameters

      • T_1

      Parameters

      • oldElement: T_1
      • oldArray: undefined | null | readonly T_1[]

      Returns readonly T_1[]

Const Booleans

Booleans: { compare: any; hash: any }

Type declaration

  • compare: function
    • compare(x: undefined | null | boolean, y: undefined | null | boolean): number

    • Parameters

      • x: undefined | null | boolean
      • y: undefined | null | boolean

      Returns number

  • hash: function
    • hash(x: undefined | null | boolean): number

    • Parameters

      • x: undefined | null | boolean

      Returns number

ByteOrder

ByteOrder: { BigEndian: ByteOrder; LittleEndian: ByteOrder; NativeOrder: ByteOrder }

Type declaration

Compare

Compare: { is: any }

Type declaration

    • (x: unknown, y: unknown): number

    • Parameters

      • x: unknown
      • y: unknown

      Returns number

  • is: function
    • is(object: unknown): object is Compare

    • Parameters

      • object: unknown

      Returns object is Compare

Const Constructors

Constructors: { compare: any; hash: any }

Type declaration

  • compare: function
    • compare(x: undefined | null | Function, y: undefined | null | Function): number

    • Parameters

      • x: undefined | null | Function
      • y: undefined | null | Function

      Returns number

  • hash: function
    • hash(x: undefined | null | Function): number

    • Parameters

      • x: undefined | null | Function

      Returns number

Equals

Equals: { is: any }

Type declaration

    • (x: unknown, y: unknown): boolean

    • Parameters

      • x: unknown
      • y: unknown

      Returns boolean

  • is: function
    • is(object: unknown): object is Equals

    • Parameters

      • object: unknown

      Returns object is Equals

Equivalent

Equivalent: { Epsilon: number; is: any }

Type declaration

    • (x: unknown, y: unknown, epsilon?: number): boolean

    • Parameters

      • x: unknown
      • y: unknown
      • Optional epsilon: number

      Returns boolean

  • Epsilon: number
  • is: function

    • Parameters

      • object: unknown

      Returns object is Equivalent

FromAny

FromAny: { is: any }

Type declaration

  • is: function
    • is<T, U>(object: unknown): object is FromAny<T, U>

    • Type parameters

      • T

      • U = never

      Parameters

      • object: unknown

      Returns object is FromAny<T, U>

Const Functions

Functions: { compare: any; hash: any }

Type declaration

  • compare: function
    • compare(x: undefined | null | Function, y: undefined | null | Function): number

    • Parameters

      • x: undefined | null | Function
      • y: undefined | null | Function

      Returns number

  • hash: function
    • hash(x: undefined | null | Function): number

    • Parameters

      • x: undefined | null | Function

      Returns number

HashCode

HashCode: { is: any }

Type declaration

    • (x: undefined | null | HashCode): number

    • Parameters

      Returns number

  • is: function
    • is(object: unknown): object is HashCode

    • Parameters

      • object: unknown

      Returns object is HashCode

Const Identity

Identity: { compare: any; hash: any }

Type declaration

  • compare: function
    • compare(x: undefined | null | object, y: undefined | null | object): number

    • Parameters

      • x: undefined | null | object
      • y: undefined | null | object

      Returns number

  • hash: function
    • hash(x: undefined | null | object): number

    • Parameters

      • x: undefined | null | object

      Returns number

Const Murmur3

Murmur3: { mash: any; mix: any; mixString: any; mixStringBE: any; mixStringLE: any; mixUInt8ArrayLE: any; mixUint8Array: any; mixUint8ArrayBE: any; rotl: any }

Type declaration

  • mash: function
    • mash(code: number): number

    • Parameters

      • code: number

      Returns number

  • mix: function
    • mix(code: number, value: number): number

    • Parameters

      • code: number
      • value: number

      Returns number

  • mixString: function
    • mixString(code: number, string: string): number

    • Parameters

      • code: number
      • string: string

      Returns number

  • mixStringBE: function
    • mixStringBE(code: number, string: string): number

    • Parameters

      • code: number
      • string: string

      Returns number

  • mixStringLE: function
    • mixStringLE(code: number, string: string): number

    • Parameters

      • code: number
      • string: string

      Returns number

  • mixUInt8ArrayLE: function
    • mixUInt8ArrayLE(code: number, array: Uint8Array): number

    • Parameters

      • code: number
      • array: Uint8Array

      Returns number

  • mixUint8Array: function
    • mixUint8Array(code: number, array: Uint8Array): number

    • Parameters

      • code: number
      • array: Uint8Array

      Returns number

  • mixUint8ArrayBE: function
    • mixUint8ArrayBE(code: number, array: Uint8Array): number

    • Parameters

      • code: number
      • array: Uint8Array

      Returns number

  • rotl: function
    • rotl(value: number, distance: number): number

    • Parameters

      • value: number
      • distance: number

      Returns number

Const Numbers

Numbers: { compare: any; equal: any; equivalent: any; hash: any }

Type declaration

  • compare: function
    • compare(x: undefined | null | number, y: undefined | null | number): number

    • Parameters

      • x: undefined | null | number
      • y: undefined | null | number

      Returns number

  • equal: function
    • equal(x: undefined | null | number, y: undefined | null | number): boolean

    • Parameters

      • x: undefined | null | number
      • y: undefined | null | number

      Returns boolean

  • equivalent: function
    • equivalent(x: undefined | null | number, y: undefined | null | number, epsilon?: number): boolean

    • Parameters

      • x: undefined | null | number
      • y: undefined | null | number
      • Optional epsilon: number

      Returns boolean

  • hash: function
    • hash(x: undefined | null | number): number

    • Parameters

      • x: undefined | null | number

      Returns number

Const Objects

Objects: { compare: any; equal: any; equivalent: any; hash: any }

Type declaration

  • compare: function
    • compare(x: undefined | null | object, y: undefined | null | object): number

    • Parameters

      • x: undefined | null | object
      • y: undefined | null | object

      Returns number

  • equal: function
    • equal(x: undefined | null | object, y: undefined | null | object): boolean

    • Parameters

      • x: undefined | null | object
      • y: undefined | null | object

      Returns boolean

  • equivalent: function
    • equivalent(x: undefined | null | object, y: undefined | null | object, epsilon?: number): boolean

    • Parameters

      • x: undefined | null | object
      • y: undefined | null | object
      • Optional epsilon: number

      Returns boolean

  • hash: function
    • hash(x: undefined | null | object): number

    • Parameters

      • x: undefined | null | object

      Returns number

Const Random

Random: { fillBytes: any }

Type declaration

  • fillBytes: function
    • fillBytes(array: Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array): void

    • Parameters

      • array: Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array

      Returns void

Const Strings

Strings: { compare: any; hash: any }

Type declaration

  • compare: function
    • compare(x: undefined | null | string, y: undefined | null | string): number

    • Parameters

      • x: undefined | null | string
      • y: undefined | null | string

      Returns number

  • hash: function
    • hash(x: undefined | null | string): number

    • Parameters

      • x: undefined | null | string

      Returns number

ToAny

ToAny: { is: any }

Type declaration

  • is: function
    • is<T>(object: unknown): object is ToAny<T>

    • Type parameters

      • T

      Parameters

      • object: unknown

      Returns object is ToAny<T>

Const Values

Values: { compare: any; equal: any; equivalent: any; hash: any }

Type declaration

  • compare: function
    • compare(x: unknown, y: unknown): number

    • Parameters

      • x: unknown
      • y: unknown

      Returns number

  • equal: function
    • equal(x: unknown, y: unknown): boolean

    • Parameters

      • x: unknown
      • y: unknown

      Returns boolean

  • equivalent: function
    • equivalent(x: unknown, y: unknown, epsilon?: number): boolean

    • Parameters

      • x: unknown
      • y: unknown
      • Optional epsilon: number

      Returns boolean

  • hash: function
    • hash(x: unknown): number

    • Parameters

      • x: unknown

      Returns number

Const assert

assert: Assert & AssertFunction

Functions

Const Lazy

  • Lazy<T>(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>): void | TypedPropertyDescriptor<T>

  • Type parameters

    • T

    Parameters

    • target: Object
    • propertyKey: string | symbol
    • descriptor: TypedPropertyDescriptor<T>

    Returns void | TypedPropertyDescriptor<T>

Generated using TypeDoc