# TOOSOON Utils Utility functions & classes. [![NPM](https://nodei.co/npm/toosoon-utils.png)](https://nodei.co/npm/toosoon-utils/) ## Installation Yarn: ```properties $ yarn add toosoon-utils ``` NPM: ```properties $ npm install toosoon-utils ``` ## Usage ```ts import { lerp } from 'toosoon-utils/math'; lerp(0.5, 0, 5); // 2.5 ``` ## Summary - [Utility functions](#utility-functions) - [Math](#math-functions) - [Geometry](#geometry-functions) - [Color](#color-functions) - [Functions](#functions-functions) - [String](#string-functions) - [Query](#query-functions) - [DOM](#dom-functions) - [File](#file-functions) - [Random](#random-functions) - [Utility classes](#utility-classes) - [Geometry](#geometry-classes) - [Curves](#curves-classes) - [Paths](#paths-classes) - [Color](#color-classes) - [Performance](#performance-class) - [Constants](#constants) - [License](#license) ## Utility functions ### Math ##### `isEven(value)` Check if a number is even. - `value`: Value to check. ```ts isEven(value: number): boolean; ``` ##### `isOdd(value)` Check if a number is odd. - `value`: Value to check. ```ts isOdd(value: number): boolean; ``` ##### `isPowerOf2(value)` Check if a number is a power of 2. - `value`: Value to check. ```ts isPowerOf2(value: number): boolean; ``` ##### `toPowerOf2(value)` Compute the closest greater power of 2 from a number. - `value`: Value to compute power of 2 for. ```ts toPowerOf2(value: number): number; ``` ##### `sign(value)` Return the sign (positive or negative) of a number. - `value`: Value to check. ```ts sign(value: number): number; ``` ##### `clamp(value, min?, max?)` Constrain a number between two bounds. - `value`: Value to constrain. - `[min=0]`: Minimum boundary. - `[max=1]`: Maximum boundary. ```ts 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. ```ts snap(value: number, multiple?: number): number; ``` ##### `lerp(t, min, max)` Interpolate a number between two bounds using Linear interpolation (lerping). - `t`: Normalized time value to interpolate. - `min`: Minimum boundary. - `max`: Maximum boundary. ```ts lerp(t: number, min: number, max: number): number; ``` ##### `normalize(value, min, max)` Normalize a number between two bounds. - `value`: Value to normalize. - `min`: Minimum boundary. - `max`: Maximum boundary. ```ts 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. ```ts map(value: number, currentMin: number, currentMax: number, targetMin: number, targetMax: number): number; ``` ##### `triLerp(t, min, max, peak)` Interpolate a number between two values using Triangular interpolation. - `t`: Normalized time value to interpolate. - `min`: Minimum boundary. - `max`: Maximum boundary. - `peak`: Peak value controling the interpolation triangle shape. ```ts triLerp(t: number, min: number, max: number, peak: number): number; ``` ##### `expLerp(t, min, max, power)` Interpolate a number between two bounds using Exponential interpolation. - `t`: Normalized time value to interpolate. - `min`: Minimum boundary. - `max`: Maximum boundary. - `power`: Exponent controling the interpolation curve shape. ```ts expLerp(t: number, min: number, max: number, power: number): number; ``` ##### `quadraticBezier(t, p1, cp, p2)` Interpolate a number using Quadratic Bézier interpolation. - `t`: Normalized time value to interpolate. - `p1`: Start point. - `cp`: Control point. - `p2`: End point. ```ts quadraticBezier(t: number, p1: number, cp: number, p2: number): number; ``` ##### `cubicBezier(t, p1, cp1, cp2, p2)` Interpolate a number 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. ```ts cubicBezier(t: number, p1: number, cp1: number, cp2: number, p2: number): number; ``` ##### `catmullRom(t, p1, cp1, cp2, p2)` Interpolate a number using Catmull-Rom interpolation. - `t`: Normalized time value to interpolate. - `p1`: Start point. - `cp1`: First control point. - `cp2`: Second control point. - `p2`: End point. ```ts catmullRom(t: number, p1: number, cp1: number, cp2: number, p2: 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 exponent. ```ts parabola(x: number, power?: number): number; ``` ##### `step(value, edge)` Compare two numbers. - `value`: Value to compare to the edge. - `edge`: Value of the edge. ```ts step(value: number, edge: number): number; ``` > The order of arguments is not the same as the one used in the GLSL language. ##### `smoothstep(value, min?, max?)` Interpolate a number between two bounds using Hermite interpolation. - `value`: Value to interpolate. - `[min=0]`: Minimum boundary. - `[max=1]`: Maximum boundary. ```ts smoothstep(value: number, min?: number, max?: number): number; ``` > The order of arguments is not the same as the one used in the GLSL language. ##### `fract(value)` Compute the fractional part of a number. - `value`: Value to compute the fractional part of. ```ts fract(value: number): number; ``` ##### `mod(value, modulo)` Compute the value of a number modulo another. - `value`: Value to modulate. - `modulo`: Value to modulate by. ```ts mod(value: number, modulo: number): number; ``` ##### `pingPong(value, length)` Move back and forth a number between 0 and a length, so that it is never larger than length and never smaller than 0. - `value`: Value to modulate. - `length`: Total length. ```ts pingPong(value: number, length: number): number; ``` ##### `sum(numbers)` Compute the sum of an array of numbers. - `numbers`: Array of numbers to compute the sum from. ```ts sum(numbers: number[]): number; ``` ##### `average(numbers)` Compute the average of an array of numbers. - `numbers`: Array of numbers to compute the average from. ```ts average(numbers: 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). ```ts damp(value: number, target: number, damping: number, delta: number): number; ``` ### Geometry ##### `toDegrees(radians)` Convert a radians angle into degrees. - `radians`: Angle in radians. ```ts toDegrees(radians: number): number; ``` ##### `toRadians(degrees)` Convert a degrees angle into radians. - `degrees`: Angle in degrees. ```ts toRadians(degrees: number): number; ``` ##### `angle(x1, y1, x2, y2)` Compute the angle (in radians) 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. ```ts angle(x1: number, y1: number, x2: number, y2: number): number; ``` ##### `closestAngle(startAngle, endAngle)` Compute the closest angle (in radians) between two angles. - `startAngle`: Start angle (in radians). - `endAngle`: End angle (in radians). ```ts closestAngle(startAngle: number, endAngle: number): number; ``` ##### `distance(x1, y1, x2, y2)` Compute 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. ```ts distance(x1: number, y1: number, x2: number, y2: number): number; ``` ##### `diagonal(width, height)` Compute the length of the diagonal of a rectangle. - `width`: Width of the rectangle. - `height`: Height of the rectangle. ```ts diagonal(width: number, height: number): number; ``` #### Fit ```ts 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. ```ts 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. ```ts contain(target: FitInput, container: FitInput): FitOutput; ``` ### Color ##### `normalizeHexString(hex)` Normalize an hexadecimal string. - `hex`: Hexadecimal string. ```ts normalizeHexString(hex: string): string; ``` ##### `rgbToHex(rgb)` Convert RGB to hexadecimal. - `rgb`: RGB color. ```ts rgbToHex([r, g, b]: [number, number, number]): number; ``` ##### `rgbToHexString(rgb)` Convert RGB to hexadecimal string. - `rgb`: RGB color. ```ts rgbToHexString([r, g, b]: [number, number, number]): string; ``` ##### `hexToRgb(hex)` Convert hexadecimal to RGB. - `hex`: Hexadecimal color. ```ts hexToRgb(hex: number | string): [number, number, number]; ``` ##### `lighten(hex, amount?)` Lighten a color. - `hex`: Hexadecimal color. - `[amount=0]`: Amount of the color offset. ```ts lighten(hex: string, amount?: number): string; ``` ##### `darken(hex, amount?)` Darken a color. - `hex`: Hexadecimal color. - `[amount=0]`: Amount of the color offset. ```ts darken(hex: string, amount?: number): string; ``` ##### `normalizeHslString(hsl)` Normalize an HSL string. - `hsl`: HSL string (format: `'hsl(360, 100%, 100%)'`). ```ts normalizeHslString(hsl: string): [number, number, number]; ``` ##### `rgbToHsl(rgb)` Convert RGB to HSL. - `rgb`: RGB color. ```ts rgbToHsl([r, g, b]: [number, number, number]): [number, number, number]; ``` ##### `hslToRgb(hsl)` Convert HSL to RGB. - `hsl`: HSL color. ```ts hslToRgb([h, s, l]: [number, number, number]): [number, number, number]; ``` ##### `rgbToHsb(rgb)` Convert RGB to HSB. - `rgb`: RGB color. ```ts rgbToHsb([r, g, b]: [number, number, number]): [number, number, number]; ``` ##### `hsbToRgb(hsb)` Convert HSB to RGB. - `hsb`: HSB color. ```ts hsbToRgb([h, s, b]: [number, number, number]): [number, number, number]; ``` ##### `labToHcl(lab)` Convert L*a*b\* to HCL. - `lab`: L*a*b\* color. ```ts labToHcl([l, a, b]: [number, number, number]): [number, number, number]; ``` ##### `hclToLab(hcl)` Convert HCL to L\*a\*b\*. - `hcl`: HCL color. ```ts hclToLab([h, c, l]: [number, number, number]): [number, number, number]; ``` ##### `labToRgb(lab)` Convert L\*a\*b\* to RGB. - `lab`: L\*a\*b\* color. ```ts labToRgb([l, a, b]: [number, number, number]): [number, number, number]; ``` ##### `rgbToLab(rgb)` Convert RGB to L\*a\*b\*. - `rgb`: RGB color. ```ts rgbToLab([r, g, b]: [number, number, number]): [number, number, number]; ``` ##### `deltaE(lab1, lab2)` Get the delta from two L\*a\*b\* colors. - `lab1`: First L\*a\*b\* color. - `lab2`: Second L\*a\*b\* color. ```ts deltaE(lab1: [number, number, number], lab2: [number, number, number]): number; ``` ##### `rgbToHcl(rgb)` Convert RGB to HCL. - `rgb`: RGB color. ```ts rgbToHcl([r, g, b]: [number, number, number]): [number, number, number]; ``` ##### `hclToRgb(hcl)` Convert HCL to RGB. - `hcl`: HCL color. ```ts hclToRgb([h, c, l]: [number, number, number]): [number, number, number]; ``` ### Functions ##### `noop()` No-op function. ```ts noop(): void; ``` ##### `wait(delay?)` Promise wrapped setTimeout. - `[delay=0]`: Time to wait (in milliseconds). ```ts wait(delay?: number): Promise; ``` ##### `isDefined(value)` Check if a value is defined. - `value`: Value to check. ```ts isDefined(value: T): boolean; ``` ##### `debounce(callback, delay)` Create a debounced function that delays the execution of a given callback until a specified delay time has passed since the last call. - `callback`: Function to debounce. - `delay`: Delay (in milliseconds). ```ts debounce(callback: T, delay: number): Function; ``` ##### `throttle(callback, limit)` Create a throttled function that limits the execution of a given callback to once every specified limit time. - `callback`: Function to throttle. - `limit`: Minimum interval between two calls (in milliseconds). ```ts throttle(callback: T, limit: number): Function; ``` ##### `now()` Polyfill for `now()` functions. ```ts now(): number; ``` ### String #### Case ##### `capitalize(string)` Capitalize a string. - `string`: String to capitalize. ```ts capitalize(string: string): string; ``` ##### `toKebabCase(string)` Convert a string to kebab-case: 'Hello world' -> 'hello-world'. - `string`: String to convert. ```ts toKebabCase(string: string): string; ``` ##### `toSnakeCase(string)` Convert a string to snake_case: 'Hello world' -> 'hello_world'. - `string`: String to convert. ```ts toSnakeCase(string: string): string; ``` ##### `toCamelCase(string)` Convert a string to camelCase: 'Hello world' -> 'helloWorld'. - `string`: String to convert. ```ts toCamelCase(string: string): string; ``` ##### `toPascalCase(string)` Convert a string to PascalCase: 'Hello world' -> 'HelloWorld'. - `string`: String to convert. ```ts toPascalCase(string: string): string; ``` ##### `toTrainCase(string)` Convert a string to Train-Case: 'Hello world' -> 'Hello-World'. - `string`: String to convert. ```ts toTrainCase(string: string): string; ``` ##### `toConstantCase(string)` Convert a string to CONSTANT_CASE: 'Hello world' -> 'HELLO_WORLD'. - `string`: String to convert. ```ts toConstantCase(string: string): string; ``` #### Path ##### `cleanPath(path)` Clean a path by removing its parameters. - `path`: Path to clean. ```ts cleanPath(path: string): string; ``` ##### `addTrailingSlash(path)` Convert a path by ensuring it has a trailing slash. - `path`: Path to convert. ```ts addTrailingSlash(path: string): string; ``` ##### `removeTrailingSlash(path)` Convert a path by ensuring it has not a trailing slash. - `path`: Path to convert. ```ts removeTrailingSlash(path: string): string; ``` ### Query parameters ##### `getQuery(property)` Get a query parameter. - `property`: Query property to check. ```ts getQuery(property: string): string | null; ``` ##### `setQuery(property, value)` Set a query parameter. - `property`: Query property to set. - `value`: Value to set. ```ts setQuery(property: string, value: string): void; ``` ##### `hasQuery(property)` Check if a query parameter exists. - `property`: Query property to check. ```ts 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. ```ts closest(element: Element | null, selector: Element | null | string): Element | null; ``` ### File ##### `load(file)` Load a file. - `file`: File to load. ```ts async load(file: File): Promise; ``` ##### `download(blob, params)` Download a Blob object into user files. - `blob`: Blob object to download. - `params`: Download parameters. - `params.filename`: Downloaded file name. ```ts download(blob: Blob, params: { filename: string }): void; ``` ##### `upload(onLoad, accept?)` Upload a file from user files. - `onLoad`: Callback called once the file is loaded. - `[accept='']` MIME type the file input should accept. ```ts upload(onLoad: (dataUrl: string) => void, accept?: string): void; ``` ##### `share(blob, params)` Share a Blob object with the user's device. - `blob`: Blob object to share. - `params`: Share parameters. - `params.filename`: Shared file name. ```ts async share(blob: Blob, params: { filename: string } & ShareData): Promise; ``` ### Random ##### `randomBoolean(probability?)` Generate a random boolean (true or false). - `[probability=0.5]`: Probability to get true. ```ts randomBoolean(probability?: number): boolean; ``` ##### `randomSign(probability?)` Generate a random sign (1 or -1). - `[probability=0.5]`: Probability to get 1. ```ts randomSign(probability?: number): number; ``` ##### `randomFloat(min?, max?, precision?)` 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. ```ts 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. ```ts randomInt(min: number, max: number): number; ``` ##### `randomHexColor()` Generate a random hexadecimal color. ```ts randomHexColor(): string; ``` ##### `randomItem(array)` Pick a random item from an array. - `array`: Array to pick the item from. ```ts randomItem(array: T[]): T | undefined; ``` ##### `randomObjectProperty(object)` Pick a random property value from an object. - `object`: Object to pick the property from. ```ts randomObjectProperty(object: Record): T | undefined; ``` ##### `randomIndex(weights)` Select a random index from an array of weighted items. - `weights`: Array of weights. ```ts randomIndex(weights: number[]): number; ``` ##### `randomGaussian(mean?, spread?)` Generate a random number fitting a Gaussian (normal) distribution. - `[mean=0]`: Mean (central) value of the distribution. - `[spread=1]`: Spread (standard deviation) of the distribution. ```ts 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. ```ts onCircle(radius?: number): [number, number]; ``` ##### `insideCircle(radius?)` Produce a random 2D point inside a unit circle. - `[radius=1]`: Radius of the circle. ```ts insideCircle(radius?: number): [number, number]; ``` ##### `onSphere(radius?)` Produce a random 3D point on the surface of a sphere. - `[radius=1]`: Radius of the sphere. ```ts onSphere(radius?: number): [number, number, number]; ``` ##### `insideSphere(radius?)` Produce a random 3D point inside a sphere. - `[radius=1]`: Radius of the sphere. ```ts insideSphere(radius?: number): [number, number, number]; ``` ## Utility classes ### Geometry See Geometry utility classes documentation [here](./docs/GEOMETRY.md). #### [Vector2](./docs//GEOMETRY.md#vector-2) #### [Vector3](./docs//GEOMETRY.md#vector-3) ### Curves See Curves utility classes documentation [here](./docs/CURVES.md). #### [Curve](./docs/CURVES.md#curve) #### [LineCurve](./docs/CURVES.md#line-curve) #### [LineCurve3](./docs/CURVES.md#line-curve-3) #### [PolylineCurve](./docs/CURVES.md#polyline-curve) #### [PolylineCurve3](./docs/CURVES.md#polyline-curve-3) #### [QuadraticBezierCurve](./docs/CURVES.md#quadratic-bezier-curve) #### [QuadraticBezierCurve3](./docs/CURVES.md#quadratic-bezier-curve-3) #### [CubicBezierCurve](./docs/CURVES.md#cubic-bezier-curve) #### [CubicBezierCurve3](./docs/CURVES.md#cubic-bezier-curve-3) #### [CatmullRomCurve](./docs/CURVES.md#catmull-rom-curve) #### [CatmullRomCurve3](./docs/CURVES.md#catmull-rom-curve-3) #### [SplineCurve](./docs/CURVES.md#spline-curve) #### [SplineCurve3](./docs/CURVES.md#spline-curve-3) #### [EllipseCurve](./docs/CURVES.md#ellipse-curve) #### [ArcCurve](./docs/CURVES.md#arc-curve) ### Paths See Paths utility classes documentation [here](./docs/PATHS.md). #### [Path](./docs/PATHS.md#path) #### [PathContext](./docs/PATHS.md#path-context) #### [PathSVG](./docs/PATHS.md#path-svg) ### Color See Color utility classes documentation [here](./docs/COLOR.md). #### [Color](./docs/COLOR.md#color) #### [ColorScale](./docs/COLOR.md#color-scale) #### [ColorPalette](./docs/COLOR.md#color-palette) ### Performance See Performance utility classes documentation [here](./docs/PERFORMANCE.md). #### [FrameRate](./docs/PERFORMANCE.md#frame-rate) ## Constants ### Math `EPSILON` ### Geometry `PI` `TWO_PI` / `TAU` `HALF_PI` `QUARTER_PI` `RAD2DEG` `DEG2RAD` ### Color `COLORS` ## License MIT License, see [LICENSE](https://github.com/toosoon-dev/toosoon-utils/tree/master/LICENSE) for details.