@fr0st/core
v2.1.7
Published
FrostCore is a free, open-source utility library for JavaScript.
Downloads
13
Maintainers
Readme
FrostCore
FrostCore is a free, open-source utility library for JavaScript.
It is a tiny (~2kb gzipped) and modern library, providing various methods for manipulating arrays, functions, objects & more.
Table Of Contents
Installation
In Browser
<script type="text/javascript" src="/path/to/frost-core.min.js"></script>
Using NPM
npm i @fr0st/core
In Node.js:
import * as _ from '@fr0st/core';
Arrays
Difference
Create a new array containing the values of the first array, that do not exist in any of the additional passed arrays.
array
is the array you wish to filter.
Any additional arguments supplied will be used to test for the values of the first array.
const diff = _.diff(array, ...arrays);
Intersect
Create a new array containing the unique values that exist in all of the passed arrays.
All arguments supplied to this method will be tested for intersections.
const intersect = _.intersect(...arrays);
Merge
Merge the values from one or more arrays or array-like objects onto an array.
array
is the array you wish to merge onto.
Any additional arguments supplied will be merged onto the first array.
_.merge(array, ...arrays);
Random Value
Return a random value from an array.
array
is the array you wish to retrieve a value from.
const randomValue = _.randomValue(array);
Range
Return an array containing a range of values.
start
is a number indicating the first value of the sequence.end
is a number indicating where the sequence will end.step
is a number indicating the increment between values in the sequence, and will default to 1.
const range = _.range(start, end, step);
Unique
Remove duplicate elements in an array.
array
is the array you wish to remove duplicates from.
const unique = _.unique(array);
Wrap
Create an array from any value.
value
is the value you wish to create an array from.
const array = _.wrap(value);
Functions
Animation
Create a wrapped version of a function that executes at most once per animation frame (using the most recent arguments passed to it).
callback
is the function you wish to wrap.options
is an object containing options for executing the function.leading
is a boolean indicating whether you wish the function to execute on the leading edge of the animation frame, and will default to false.
const animation = _.animation(callback, options);
The returned animation function has a cancel method which will cancel the callback.
animation.cancel();
Compose
Create a wrapped function that will execute each callback in reverse order, passing the result from each function to the previous.
Any arguments supplied will be added to the chain of callbacks.
const composed = _.compose(...callbacks);
Curry
Create a wrapped version of a function, that will return new functions until the number of total arguments passed reaches the arguments length of the original function (at which point the function will execute).
callback
is the function you wish to wrap.
const curried = _.curry(callback);
Debounce
Create a wrapped version of a function that executes once per wait period (using the most recent arguments passed to it).
callback
is the function you wish to wrap.wait
is the number of milliseconds to wait between executions, and will default to 0.options
is an object containing options for executing the function.leading
is a boolean indicating whether you wish the function to execute on the leading edge of the wait period, and will default to false.trailing
is a boolean indicating whether you wish the function to execute on the trailing edge of the wait period, and will default to true.
const debounced = _.debounce(callback, wait, options);
The returned debounced function has a cancel method which will cancel the (trailing) callback.
debounced.cancel();
Evaluate
Evaluate a value from a function or value.
value
is the value to evaluate.
const result = _.evaluate(value);
Once
Create a wrapped version of a function that will only ever execute once. Subsequent calls to the wrapped function will return the result of the initial call.
callback
is the function you wish to wrap.
const once = _.once(callback);
Partial
Create a wrapped version of a function with predefined arguments.
callback
is the function you wish to wrap.
Any additional arguments supplied will be passed on as default arguments to the wrapped function. Specify undefined for a default argument to allow that argument to be sent to the wrapped function.
const partial = _.partial(callback, ...defaultArgs);
Pipe
Create a wrapped function that will execute each callback in order, passing the result from each function to the next.
Any arguments supplied will be added to the chain of callbacks.
const piped = _.pipe(...callbacks);
Throttle
Create a wrapped version of a function that executes at most once per wait period (using the most recent arguments passed to it).
callback
is the function you wish to wrap.wait
is the number of milliseconds to wait between executions, and will default to 0.options
is an object containing options for executing the function.leading
is a boolean indicating whether you wish the function to execute on the leading edge of the wait period, and will default to true.trailing
is a boolean indicating whether you wish the function to execute on the trailing edge of the wait period, and will default to true.
const throttled = _.throttle(callback, wait, options);
The returned throttled function has a cancel method which will cancel the (trailing) callback.
throttled.cancel();
Times
Execute a function a specified number of times.
callback
is the function you wish to execute.amount
is the number of times you wish the function to execute.
_.times(callback, amount);
Math
Clamp
Clamp a value between a min and max.
value
is the number you wish to clamp.min
is the number which will be the minimum of the clamped value, and will default to 0.max
is the number which will be the maximum of the clamped value, and will default to 1.
const clamp = _.clamp(value, min, max);
Clamp Percent
Clamp a value between 0 and 100.
value
is the number you wish to clamp.
const clampPercent = _.clampPercent(value);
Distance
Get the distance between two vectors.
x1
is the number to be used as the first X co-ordinate.y1
is the number to be used as the first Y co-ordinate.x2
is the number to be used as the second X co-ordinate.y2
is the number to be used as the second Y co-ordinate.
const dist = _.dist(x1, y1, x2, y2);
Inverse Linear Interpolation
Inverse linear interpolation from one value to another.
min
is the number to be used as the minimum of the "lerped" amount.max
is the number to be used as the maximum of the "lerped" amount.value
is the value to inverse interpolate.
const lerp = _.inverseLerp(min, max, value);
Length
Get the length of an X,Y vector.
x
is the number to be used as the X co-ordinate.y
is the number to be used as the Y co-ordinate.
const len = _.len(x, y);
Linear Interpolation
Linear interpolation from one value to another.
min
is the number to be used as the minimum of the "lerped" amount.max
is the number to be used as the maximum of the "lerped" amount.amount
is the amount to interpolate (between 0 and 1).
const lerp = _.lerp(min, max, amount);
Map
Map a value from one range to another.
value
is the number you wish to map.fromMin
is the number to be used as the minimum value of the current range.fromMax
is the number to be used as the maximum value of the current range.toMin
is the number to be used as the minimum value of the target range.toMax
is the number to be used as the maximum value of the target range.
const map = _.map(value, fromMin, fromMax, toMin, toMax);
Random
Return a random floating-point number.
a
is the number to be used as the minimum value (inclusive).b
is the number to be used as the maximum value (exclusive).
If b
is omitted, this function will return a random number between 0 (inclusive) and a
(exclusive).
If both arguments are omitted, this function will return a random number between 0 (inclusive) and 1 (exclusive).
const random = _.random(a, b);
To Step
Round a number to a specified step-size.
value
is the number you wish to constrain to a specified "step".step
is the number to be used as the minimum step-size.
const toStep = _.toStep(value, step);
Objects
Extend
Merge the values from one or more objects onto an object (recursively).
object
is the object you are merging to.
Any additional arguments supplied will be merged onto the first object.
_.extend(object, ...objects);
Flatten
Flatten an object using dot notation.
object
is the object you are flattening.
const flattened = _.flatten(object);
Forget Dot
Remove a specified key from an object using dot notation.
object
is the object you wish to remove a key from.key
is a string using dot notation, indicating the key to remove.
_.forgetDot(object, key);
Get Dot
Retrieve the value of a specified key from an object using dot notation.
object
is the object you wish to retrieve a value from.key
is a string using dot notation, indicating the key to retrieve.defaultValue
is the default value to return if the key does not exist, and will default to undefined.
const value = _.getDot(object, key, defaultValue);
Has Dot
Returns true if a specified key exists in an object using dot notation.
object
is the object you wish to test for a key.key
is a string using dot notation, indicating the key to test for.
const hasKey = _.hasDot(object, key);
Pluck Dot
Retrieve values of a specified key from an array of objects using dot notation.
objects
is the array of objects you wish to retrieve values from.key
is a string using dot notation, indicating the key to retrieve.defaultValue
is the default value to return if the key does not exist, and will default to undefined.
const values = _.pluckDot(objects, key, defaultValue);
Set Dot
Set a specified value of a key for an object using dot notation.
object
is the object you wish to set a value for.key
is a string using dot notation, indicating the key to set the value.value
is the value you wish to set the key to.options
is an object containing options for setting the value.overwrite
is a boolean indicating whether you wish to overwrite an existing key, and will default to true.
_.setDot(object, key, value, options);
Strings
Camel Case
Convert a string to camelCase.
string
is the string you wish to transform to camelCase.
const camelCase = _.camelCase(string);
Capitalize
Convert the first character of string to upper case and the remaining to lower case.
string
is the string you wish to capitalize.
const capitalized = _.capitalize(string);
Escape
Convert HTML special characters in a string to their corresponding HTML entities.
string
is the string you wish to escape.
const escape = _.escape(string);
Escape RegExp
Escape a string for use in RegExp.
string
is the string you wish to escape.
const escapeRegExp = _.escapeRegExp(string);
Humanize
Convert a string to a humanized form.
string
is the string you wish to humanize.
const humanized = _.humanize(string);
Kebab Case
Convert a string to kebab-case.
string
is the string you wish to transform to kebab-case.
const kebabCase = _.kebabCase(string);
Pascal Case
Convert a string to PascalCase.
string
is the string you wish to transform to PascalCase.
const pascalCase = _.pascalCase(string);
Random String
Return a random string.
length
is the length of the random string, and will default to 16.characters
is a sequence of characters to generate the string from, and will default to 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWYXZ0123456789'.
const randomString = _.randomString(length, characters);
Snake Case
Convert a string to snake_case.
string
is the string you wish to transform to snake_case.
const snakeCase = _.snakeCase(string);
Unescape
Convert HTML entities in a string to their corresponding characters.
string
is the string you wish to unescape.
const unescape = _.unescape(string);
Testing
Is Array
Returns true is the value is an array.
value
is the value you wish to test.
const isArray = _.isArray(value);
Is Array Like
Returns true is the value is array-like.
value
is the value you wish to test.
const isArrayLike = _.isArrayLike(value);
Is Boolean
Returns true if the value is a boolean.
value
is the value you wish to test.
const isBoolean = _.isBoolean(value);
Is Document
Returns true is the value is a Document.
value
is the value you wish to test.
const isDocument = _.isDocument(value);
Is Element
Returns true is the value is a HTMLElement.
value
is the value you wish to test.
const isElement = _.isElement(value);
Is Fragment
Returns true if the value is a DocumentFragment.
const isFragment = _.isFragment(value);
Is Function
Returns true if the value is a function.
value
is the value you wish to test.
const isFunction = _.isFunction(value);
Is NaN
Returns true if the value is NaN.
value
is the value you wish to test.
const isNaN = _.isNaN(value);
Is Node
Returns true is the value is a Node.
value
is the value you wish to test.
const isNode = _.isNode(value);
Is Null
Returns true if the value is null.
value
is the value you wish to test.
const isNull = _.isNull(value);
Is Numeric
Returns true if the value is numeric.
value
is the value you wish to test.
const isNumeric = _.isNumeric(value);
Is Object
Returns true if the value is an object.
value
is the value you wish to test.
const isObject = _.isObject(value);
Is Plain Object
Returns true if the value is a plain object.
value
is the value you wish to test.
const isPlainObject = _.isPlainObject(value);
Is Shadow
Returns true if the value is a ShadowRoot.
const isShadow = _.isShadow(value);
Is Text
Returns true if the value is a text Node.
const isText = _.isText(value);
Is String
Returns true if the value is a string.
value
is the value you wish to test.
const isString = _.isString(value);
Is Undefined
Returns true if the value is undefined.
value
is the value you wish to test.
const isUndefined = _.isUndefined(value);
Is Window
Returns true if the value is a Window.
value
is the value you wish to test.
const isWindow = _.isWindow(value);