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

Summary

• Utility functions
  • Maths
  • Geometry
  • Colors
  • Functions
  • Strings
  • Query
  • DOM
  • Files
  • Random
  • PRNG
• Utility classes
  • Geometry
  • Curves
  • Paths
  • Colors
  • FrameRate
• Constants
• License

Utility functions

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;

snap(value, multiple)

Round a number up to a nearest multiple.

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

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

lerp(t, min, max)

Interpolate a value between two values using Linear interpolation (lerping).

• t: Normalized time value to interpolate.
• min: Minimum value.
• max: Maximum value.

lerp(t: number, min: number, max: 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;

triLerp(t, min, max, peak)

Interpolate a value between two values using Triangular interpolation.

• t: Normalized time value to interpolate.
• min: Minimum value.
• max: Maximum value.
• peak: Peak value controling the interpolation triangle shape.

triLerp(t: number, min: number, max: number, peak: number): number;

expLerp(t, min, max, exponent)

Interpolate a value using Exponential interpolation.

• t: Normalized time value to interpolate.
• min: Minimum value.
• max: Maximum value.
• power: Exponent controling the interpolation curve shape.

expLerp(t: number, min: number, max: number, power: number): number;

quadraticBezier(t, p1, cp, p2)

Interpolate a value using Quadratic Bézier interpolation.

• t: Normalized time value to interpolate.
• p1: Start point.
• cp: Control point.
• p2: End point.

quadraticBezier(t: number, p1: number, cp: number, p2: number): number;

cubicBezier(t, p1, cp1, cp2, p2)

Interpolate a value using Cubic Bézier interpolation.

• t: Normalized time value to interpolate.
• p1: Start point.
• cp1: First control point.
• cp2: Second control point.
• p2: End point.

cubicBezier(t: number, p1: number, cp1: number, cp2: number, p2: number): number;

catmullRom(t, p1, cp1, cp2, p2)

Interpolate a value using Catmull-Rom interpolation.

• t: Normalized time value to interpolate.
• p1: Start point.
• cp1: First control point.
• cp2: Second control point.
• p2: End point.

catmullRom(t: number, p1: number, cp1: number, cp2: number, p2: 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;

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-axis coordinate of the start point.
• y1: Y-axis coordinate of the start point.
• x2: X-axis coordinate of the end point.
• y2: Y-axis coordinate of the end point.

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

closestAngle(startAngle, endAngle)

Find the closest angle between to angles.

• startAngle: Start angle (in radians).
• endAngle: End angle (in radians).

closestAngle(startAngle: number, endAngle: number): number;

distance(x1, y1, x2, y2)

Calculate the distance between two points.

• x1: X-axis coordinate of the start point.
• y1: Y-axis coordinate of the start point.
• x2: X-axis coordinate of the end point.
• y2: Y-axis coordinate of the end 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;

Fit

type FitInput = {
  width: number;
  height: number;
};

type FitOutput = {
  left: number;
  top: number;
  width: number;
  height: number;
  scale: number;
};

cover(target, container)

Make a target fit a container (cover mode).

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

cover(target: FitInput, container: FitInput): FitOutput;

contain(target, container)

Make a target fit a container (contain mode).

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

contain(target: FitInput, container: FitInput): FitOutput;

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];

Functions

noop()

No-op function.

noop(): void;

wait(delay)

Promise wrapped setTimeout.

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

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

isDefined(value)

Check if a value is defined.

• value: Value to check.

isDefined(value: any): boolean;

debounce(callback, delay)

Create a debounced function that delays the execution of callback until a specified delay time has passed since the last call.

• callback: Function to debounce.
• delay: Delay (in milliseconds).

debounce(callback: Function, delay: number): Function;

throttle(callback, limit)

Create a throttled function that limits the execution of callback to once every limit time.

• callback: Function to throttle.
• limit: Minimum interval between two calls (in milliseconds).

throttle(callback: Function, limit: number): Function;

defer()

Deferred promise implementation.

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

now()

Polyfill for now() functions.

now(): number;

Strings

Cases

capitalize(string)

Capitalize a string.

• string: String to capitalize.

capitalize(string: string): string;

toKebabCase(string)

Convert a string to kebab-case: 'Hello world' -> 'hello-world'.

• string: String to convert.

toKebabCase(string: string): string;

toSnakeCase(string)

Convert a string to snake_case: 'Hello world' -> 'hello_world'.

• string: String to convert.

toSnakeCase(string: string): string;

toCamelCase(string)

Convert a string to camelCase: 'Hello world' -> 'helloWorld'.

• string: String to convert.

toCamelCase(string: string): string;

toPascalCase(string)

Convert a string to PascalCase: 'Hello world' -> 'HelloWorld'.

• string: String to convert.

toPascalCase(string: string): string;

toTrainCase(string)

Convert a string to Train-Case: 'Hello world' -> 'Hello-World'.

• string: String to convert.

toTrainCase(string: string): string;

toConstantCase(string)

Convert a string to CONSTANT_CASE: 'Hello world' -> 'HELLO_WORLD'.

• string: String to convert.

toConstantCase(string: string): string;

Paths

cleanPath(path)

Clean a path by removing its parameters.

• path: Path to clean.

cleanPath(path: string): string;

addTrailingSlash(path)

Convert a path by ensuring it has a trailing slash.

• path: Path to convert.

addTrailingSlash(path: string): string;

removeTrailingSlash(path)

Convert a path by ensuring it has not a trailing slash.

• path: Path to convert.

removeTrailingSlash(path: string): string;

Query parameters

getQuery(property)

Get a query parameter.

• property: Query property to check.

getQuery(property: string): string | null;

setQuery(property)

Set a query parameter.

• property: Query property to set.
• value: Value to set.

setQuery(property: string, value: string): void;

hasQuery(property)

Check if a query parameter exists.

• property: Query property to check.

hasQuery(property: string): boolean;

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;

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;

randomGaussian(mean, spread)

Generate a random number fitting a Gaussian (normal) distribution.

• [mean=0]: Central value.
• [spread=1]: Standard deviation.

randomGaussian(mean?: number, spread?: number): number;

onCircle(radius)

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

• [radius=1]: Radius of the circle.

onCircle(radius?: number): [number, number];

insideCircle(radius)

Produce a random 2D point inside a unit circle.

• [radius=1]: Radius of the circle.

insideCircle(radius?: number): [number, number];

onSphere(radius)

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

• [radius=1]: Radius of the sphere.

onSphere(radius?: number): [number, number, number];

insideSphere(radius)

Produce a random 3D point inside a sphere.

• [radius=1]: Radius of the sphere.

insideSphere(radius?: number): [number, 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 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;

randomGaussian(prng, mean, spread)

Generate a pseudo-random number fitting a Gaussian (normal) distribution.

• prng: PRNG parameters.
• [mean=0]: Central value.
• [spread=1]: Standard deviation.

randomGaussian(prng: string | object, mean?: number, spread?: number): number;

Utility classes

Geometry

See Geometry utility classes documentation here.

Vector2

Vector3

Curves

See Curves utility classes documentation here.

Curve

LineCurve

LineCurve3

PolylineCurve

PolylineCurve3

QuadraticBezierCurve

QuadraticBezierCurve3

CubicBezierCurve

CubicBezierCurve3

CatmullRomCurve

CatmullRomCurve3

SplineCurve

SplineCurve3

EllipseCurve

ArcCurve

Paths

See Paths utility classes documentation here.

Path

PathContext

PathSVG

Colors

See Colors utility classes documentation here.

Color

ColorScale

ColorPalette

Frame rate

See FrameRate utility class documentation here.

Constants

Maths

EPSILON

Geometry

PI

TWO_PI / TAU

HALF_PI

QUARTER_PI

Colors

W3CX11

License

MIT License, see LICENSE for details.