toosoon-utils
v3.0.2
Published
Utility functions & classes
Downloads
24
Maintainers
Readme
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 spherephi
: 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]
- .colors:
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];
Frame rate
Utility class for controlling FPS calls.
Constructor
| Parameter | Type | Default | Description |
| --------- | -------- | ------- | ----------------------- |
| fps | number
| 30
| Frame per second limit. |
Properties
fps
Frame per second limit.
FrameRate.fps: number;
Methods
update()
Return true if elapsed time since last update is higher than current FPS.
FrameRate.update(): boolean;
Constants
EPSILON
PI
TWO_PI
HALF_PI
QUARTER_PI
W3CX11
License
MIT License, see LICENSE for details.