Toosoon-utils NPM

TOOSOON UTILS

Utility functions & classes.

Installation

Yarn:

$ yarn add toosoon-utils

NPM:

$ npm install toosoon-utils

Usage

import { lerp } from 'toosoon-utils/maths';

console.log(lerp(0.5, 0, 5)); // 2.5

Utility functions

Colors

normalizeHexString(hex)

Normalize an hexadecimal string.

hex: Hexadecimal string.

normalizeHexString(hex: string): string;

rgbToHex(rgb)

Convert RGB to hexadecimal.

rgb: RGB color.

rgbToHex([r, g, b]: [number, number, number]): number;

rgbToHexString(rgb)

Convert RGB to hexadecimal string.

rgb: RGB color.

rgbToHexString([r, g, b]: [number, number, number]): string;

hexToRgb(hex)

Convert hexadecimal to RGB.

hex: Hexadecimal color.

hexToRgb(hex: number | string): [number, number, number];

lighten(hex, amount)

Lighten a color.

hex: Hexadecimal color.
[amount=0]: Amount of the color offset.

lighten(hex: string, amount?: number): string;

darken(hex, amount)

Darken a color.

hex: Hexadecimal color.
[amount=0]: Amount of the color offset.

darken(hex: string, amount?: number): string;

normalizeHslString(hsl)

Normalize an HSL string.

hsl: HSL string (format: 'hsl(360, 100%, 100%)').

normalizeHslString(hsl: string): [number, number, number];

rgbToHsl(rgb)

Convert RGB to HSL.

rgb: RGB color.

rgbToHsl([r, g, b]: [number, number, number]): [number, number, number];

hslToRgb(hsl)

Convert HSL to RGB.

hsl: HSL color.

hslToRgb([h, s, l]: [number, number, number]): [number, number, number];

rgbToHsb(rgb)

Convert RGB to HSB.

rgb: RGB color.

rgbToHsb([r, g, b]: [number, number, number]): [number, number, number];

hsbToRgb(hsb)

Convert HSB to RGB.

hsb: HSB color.

hsbToRgb([h, s, b]: [number, number, number]): [number, number, number];

labToHcl(lab)

Convert LAB to HCL.

lab: LAB color.

labToHcl([l, a, b]: [number, number, number]): [number, number, number];

hclToLab(hcl)

Convert HCL to LAB.

hcl: HCL color.

hclToLab([h, c, l]: [number, number, number]): [number, number, number];

labToRgb(lab)

Convert LAB to RGB.

lab: LAB color.

labToRgb([l, a, b]: [number, number, number]): [number, number, number];

rgbToLab(rgb)

Convert RGB to LAB.

rgb: RGB color.

rgbToLab([r, g, b]: [number, number, number]): [number, number, number];

deltaE(labA, labB)

Get the delta from two LAB colors.

labA: First LAB color.
labB: Second LAB color.

deltaE(labA: [number, number, number], labB: [number, number, number]): number;

rgbToHcl(rgb)

Convert RGB to HCL.

rgb: RGB color.

rgbToHcl([r, g, b]: [number, number, number]): [number, number, number];

hclToRgb(hcl)

Convert HCL to RGB.

hcl: HCL color.

hclToRgb([h, c, l]: [number, number, number]): [number, number, number];

DOM

closest(element, selector)

Find the closest parent that matches a selector.

element: Target element.
selector: Selector or parent to match.

closest(element: Element | null, selector: Element | string): Element | null;

createCanvas(width, height)

Create a canvas and 2d context.

width: Width of the canvas.
height: Height of the canvas.

createCanvas(width: number, height: number): { canvas: HTMLCanvasElement; ctx: CanvasRenderingContext2D };

injectStyles(styles)

Inject CSS styles in document.head.

styles: CSS styles to inject.

injectStyles(styles: string): void;

Files

download(blob, filename)

Download a Blob object into user files.

blob: Blob object to download.
filename: Downloaded file name.

download(blob: Blob, filename: string): void;

upload(onLoad)

Upload a file from user files.

onLoad: Callback called once the file is loaded.
[accept=''] MIME type the file input should accept.

upload(onLoad: (dataUrl: string) => void, accept?: string): void;

Functions

noop()

No-op function.

noop(): void;

wait(timeout)

Promise wrapped setTimeout.

[timeout=0]: Time to wait (in milliseconds).

wait(timeout?: number): Promise<void>;

defer()

Deferred promise implementation.

defer<T>(): Deferred<T>;

now()

Polyfill for now() functions.

now(): number;

Geometry

toDegrees(radians)

Convert a radians value into degrees.

radians: Angle in radians.

toDegrees(radians: number): number;

toRadians(degrees)

Convert a degrees value into radians.

degrees: Angle in degrees.

toRadians(degrees: number): number;

angle(x1, y1, x2, y2)

Calculate the angle from a point to another.

x1: X value of the first point.
y1: Y value of the first point.
x2: X value of the second point.
y2: Y value of the second point.

angle(x1: number, y1: number, x2: number, y2: number): number;

closestAngle(source, target)

Find the closest angle between to angles.

source: Source angle in radians.
target: Target angle in radians.

closestAngle(source: number, target: number): number;

distance(x1, y1, x2, y2)

Calculate the distance between two points.

x1: X coord of the first point.
y1: Y coord of the first point.
x2: X coord of the second point.
y2: Y coord of the second point.

distance(x1: number, y1: number, x2: number, y2: number): number;

diagonal(width, height)

Calculate the length of the diagonal of a rectangle.

width: Width of the rectangle.
height: Height of the rectangle.

diagonal(width: number, height: number): number;

radToSphere(radius, phi, theta)

Convert radians to a 3D point on the surface of a unit sphere.

radius: Radius of the sphere
phi: Polar angle from the y (up) axis 0, PI
theta: Equator angle around the y (up) axis 0, 2*PI
[target]: Target vector

radToSphere(radius: number, phi: number, theta: number, target?: Vector3): Vector3;

cover(target, container)

Make a target fit a container (cover mode).

target: Dimension of the target.
container: Dimension of the container.

cover(target: object, container: object): object;

contain(target, container)

Make a target fit a container (contain mode).

target: Dimension of the target.
container: Dimension of the container.

contain(target: object, container: object): object;

Maths

isEven(value)

Check if a number is even.

value: Value to check.

isEven(value: number): boolean;

isOdd(value)

Check if a number is odd.

value: Value to check.

isOdd(value: number): boolean;

isPowerOf2(value)

Check if a number is a power of 2.

value: Value to check.

isPowerOf2(value: number): boolean;

toPowerOf2(value)

Find closest power of 2 that fits a number.

value: Incoming value.
[mode='ceil']: Can be 'floor', 'ceil' or 'round'.

toPowerOf2(value: number, mode?: string): number;

sign(value)

Return the sign (positive or negative) of a number.

value: Value to check.

sign(value: number): number;

clamp(value, min, max)

Clamp a value between two bounds.

value: Value to clamp.
[min=0]: Minimum boundary.
[max=1]: Maximum boundary.

clamp(value: number, min?: number, max?: number): number;

lerp(value, min, max)

Linear interpolation between two values (lerping).

value: Normalized value to interpolate.
min: Minimum value.
max: Maximum value.

lerp(value: number, min: number, max: number): number;

triLerp(value, min, max, target)

Triangular interpolation between two values.

value: Normalized value to interpolate.
min: Minimum value.
max: Maximum value.
target: Triangle target value.

triLerp(value: number, min: number, max: number, target: number): number;

expLerp(value, currentMin, currentMax, targetMin, targetMax)

Exponential interpolation between two values.

value: Value to interpolate.
currentMin: Lower bound of the value's current range.
currentMax: Upper bound of the value's current range.
targetMin: Lower bound of the value's target range.
targetMax: Upper bound of the value's target range.

expLerp(value: number, currentMin: number, currentMax: number, targetMin: number, targetMax: number): number;

normalize(value, min, max)

Normalize a value between two bounds.

value: Value to normalize.
min: Minimum boundary.
max: Maximum boundary.

normalize(value: number, min: number, max: number): number;

map(value, currentMin, currentMax, targetMin, targetMax)

Re-map a number from one range to another.

value: Value to re-map.
currentMin: Lower bound of the value's current range.
currentMax: Upper bound of the value's current range.
targetMin: Lower bound of the value's target range.
targetMax: Upper bound of the value's target range.

map(value: number, currentMin: number, currentMax: number, targetMin: number, targetMax: number): number;

roundTo(value, multiple)

Round a number up to a nearest multiple.

value: Value to round.
[multiple=1]: Multiple to round to.

roundTo(value: number, multiple?: number): number;

modAbs(value, length)

Modulo absolute a value based on a length.

value: Value to modulate.
length: Total length.

modAbs(value: number, length: number): number;

pingPong(value, length)

Move back and forth a value between 0 and length, so that it is never larger than length and never smaller than 0.

value: Value to modulate.
length: Total length.

pingPong(value: number, length: number): number;

smoothstep(value, min, max)

Smooth a value using cubic Hermite interpolation.

value: Value to smooth.
[min=0]: Minimum boundary.
[max=1]: Maximum boundary.

smoothstep(value: number, min?: number, max?: number): number;

parabola(x, power)

Re-map the 0, 1 interval into 0, 1 parabola, such that corners are remaped to 0 and the center to 1.

x: Normalized coordinate on X axis.
[power=1]: Parabola power.

parabola(x: number, power?: number): number;

sum(array)

Return the sum of numbers.

array: Array of numbers.

sum(array: number[]): number;

average(array)

Return the average of numbers.

array: Array of numbers.

average(array: number[]): number;

damp(value, target, damping, delta)

Smoothly interpolate a number toward another.

value: Value to interpolate.
target: Destination of the interpolation.
damping: A higher value will make the movement more sudden, and a lower value will make the movement more gradual.
delta: Delta time (in seconds).

damp(value: number, target: number, damping: number, delta: number): number;

Pseudo-Random Number Generator (PRNG)

PRNG Algorithms

Credits: Seeding random number generator

cyrb128(seed)

Produce a 128-bit hash value from a string.

seed: Initial seed state.

cyrb128(prng: string | object): [number, number, number, number];

sfc32(a, b, c, d)

Simple Fast Counter, Generator with a 128-bit state.

sfc32(a: number, b: number, c: number, d: number): number;

splitmix32(a)

SplitMix32, Generator with a 32-bit state.

splitmix32(a: number): number;

mulberry32(a)

Mulberry32, Generator with a 32-bit state.

mulberry32(a: number): number;

jsf32(a, b, c, d)

Jenkins' Small Fast, Generator with a 32-bit state.

jsf32(a: number, b: number, c: number, d: number): number;

xoshiro128ss(a, b, c, d)

xoshiro128**, Generator with a 128-bit state.

xoshiro128ss(a: number, b: number, c: number, d: number): number;

PRNG functions

Thanks to the above algorithms, a seed-based version of most of the random functions are exist with additionnal parameters for a seed string and a PRNG algorithm function.

PRNG parameters:

type PRNGParameters = string | { seed: string; algorithm: (...args: number[]) => number };

random(prng)

Generate a pseudo-random number in the interval 0, 1. It is the PRNG equivalent of Math.random().

prng: PRNG parameters.

random(prng: PRNGParameters): number;

randomBoolean(prng)

Generate a pseudo-random boolean (true or false).

prng: PRNG parameters.
[probability=0.5]: Probability to get true.

randomBoolean(prng: PRNGParameters, probability?: number): boolean;

randomSign(prng)

Generate a pseudo-random sign (1 or -1).

prng: PRNG parameters.
[probability=0.5]: Probability to get 1.

randomSign(prng: PRNGParameters, probability?: number): number;

randomFloat(prng, min, max)

Generate a pseudo-random floating-point number within a specified range.

prng: PRNG parameters.
[min=0]: Minimum boundary.
[max=1]: Maximum boundary.
[precision=2]: Number of digits after the decimal point.

randomFloat(prng: PRNGParameters, min?: number, max?: number, precision?: number): number;

randomInt(prng, min, max)

Generate a pseudo-random integer number within a specified range.

prng: PRNG parameters.
min: Minimum boundary.
max: Maximum boundary.

randomInt(prng: PRNGParameters, min: number, max: number): number;

randomHexColor(prng)

Generate a pseudo-random hexadecimal color.

prng: PRNG parameters.

randomHexColor(prng: PRNGParameters): string;

randomItem(prng, array)

Pick a pseudo-random item from a given array.

prng: PRNG parameters.
array: Array to pick the item from.

randomItem<T>(prng: PRNGParameters, array: T[]): T | undefined;

randomObjectProperty(prng)

Pick a pseudo-random property value from a given object.

prng: PRNG parameters.
object: Object to pick the property from.

randomObjectProperty<T>(prng: PRNGParameters, object: Record<string, T>): T | undefined;

randomIndex(prng)

Select a pseudo-random index from an array of weighted items.

prng: PRNG parameters.
weights: Array of weights.

randomIndex(prng: string | object, weights: number[]): number;

Random

randomBoolean(probability)

Generate a random boolean (true or false).

[probability=0.5]: Probability to get true.

randomBoolean(probability?: number): boolean;

randomSign(probability)

Generate a random sign (1 or -1).

[probability=0.5]: Probability to get 1.

randomSign(probability?: number): number;

randomFloat(min, max)

Generate a random floating-point number within a specified range.

[min=0]: Minimum boundary.
[max=1]: Maximum boundary.
[precision=2]: Number of digits after the decimal point.

randomFloat(min?: number, max?: number, precision?: number): number;

randomInt(min, max)

Generate a random integer number within a specified range.

min: Minimum boundary.
max: Maximum boundary.

randomInt(min: number, max: number): number;

randomHexColor()

Generate a random hexadecimal color.

randomHexColor(): string;

randomItem(array)

Pick a random item from a given array.

array: Array to pick the item from.

randomItem<T>(array: T[]): T | undefined;

randomObjectProperty(object)

Pick a random property value from a given object.

object: Object to pick the property from.

randomObjectProperty<T>(object: Record<string, T>): T | undefined;

randomIndex(weights)

Select a random index from an array of weighted items.

weights: Array of weights.

randomIndex(weights: number[]): number;

onCircle(radius)

Produce a random 2D point around the perimiter of a unit circle.

[radius=1]: Radius of the circle.
[target]: Target vector.

onCircle(radius?: number, target?: Vector2): Vector2;

insideCircle(radius)

Produce a random 2D point inside a unit circle.

[radius=1]: Radius of the circle.
[target] Target vector.

insideCircle(radius?: number, target?: Vector2): Vector2;

onSphere(radius)

Produce a random 3D point on the surface of a unit sphere.

[radius=1]: Radius of the sphere.
[target]: Target vector.

onSphere(radius?: number, target?: Vector3): Vector3;

insideSphere(radius)

Produce a random 3D point inside a unit sphere.

[radius=1]: Radius of the sphere.
[target]: Target vector.

insideSphere(radius?: number, target?: Vector3): Vector3;

Strings

capitalize(string)

Capitalize a string.

string: String to capitalize.

capitalize(string: string): string;

cleanPath(path)

Clean a path by removing params.

path: Path to clean.

cleanPath(path: string): string;

Utility classes

Color scale

Utility class for generating color scales and interpolating between colors.

new ColorScale(input, target)
- .colors: Array<[number, number, number]>
- static .generate(input, target, length): Array<[number, number, number]>
- static .interpolate(inputColor, targetColor, value): [number, number, number]

Constructor

Parameter	Type	Default	Description
input	`ColorRepresentation`		Input color representation.
target	`ColorRepresentation`		Target color representation.
length	`number`	`5`	Amount of colors composing the color scale.
settings	`ColorScaleSettings`	`{ colorSpace: 'rgb' }`	Color scale generation settings.
settings.colorSpace	`'rgb' \\| 'hsl' \\| 'hsb' \\| 'hcl'`	`'rgb'`	Color scale color space.

HCL color scales

HCL color scales come with a bunch of other settings, so when settings.colorSpace is equal to 'hcl', the following settings are parameterable:

Parameter	Type	Default	Description
settings.mode	`'qualitative' \\| 'sequential' \\| 'diverging'`		Color scale mode.
settings.triangular	`number`		Triangular interpolation `target` value.
settings.powerStrength	`number`	`1`	Interpolation power strength value.
settings.hueOffset	`number`	`0`	Target color hue offset.
settings.chromaOffset	`number`	`0`	Target color chroma offset.
settings.luminanceOffset	`number`	`0`	Target color luminance offset.

Learn more about HCL-Based Color Palettes.

Properties

colors

Array of colors composing the color scale.

ColorScale.colors: Array<[number, number, number]>;

Methods

`static` generate(input, target, length)

Static method for generating a color scale.

input: Input color representation.
target: Target color representation.
length: Amount of colors composing the color scale.
[settings]: Color scale generation settings.

static ColorScale.generate(
  input: ColorRepresentation,
  target: ColorRepresentation,
  length: number,
  settings?: ColorScaleSettings
): Array<[number, number, number]>;

`static` interpolate(inputColor, targetColor, value)

Static method for interpolating between colors.

inputColor: Input color.
targetColor: Target color.
value: Interpolation normalized value.
[settings]: Color scale settings.

static ColorScale.interpolate(
  inputColor: [number, number, number],
  targetColor: [number, number, number],
  value: number,
  settings?: ColorScaleSettings
): [number, number, number];