core/util
A collection of utility methods.
import util from '@enact/core/util';
Members
JobClass
Provides a convenient way to manage timed execution of functions.
import {Job} from '@enact/core/util';
Constructor
Methods
- idle({…args})undefined
Executes job when the CPU is idle.
0 or more Params
- args Any
- optional
Any args passed are forwarded to the callback
Returns
- undefined
- idleUntil(timeout, {…args})undefined
Executes job when the CPU is idle, or when the timeout is reached, whichever occurs first.
1 or more Params
- timeout Number
The number of milliseconds to wait before executing the job. This guarantees that the job is run, if a positive value is specified.
- args Any
- optional
Any args passed are forwarded to the callback
Returns
- undefined
- promise(promise)Promise
Starts the job when
promise
resolves.The job execution is tied to the resolution of the last
Promise
passed. Like other methods onJob
, callingpromise()
again with a newPromise
will block execution of the job until that newPromise
resolves. Any previousPromise
s will still resolve normally but will not trigger job execution.Unlike other methods on
Job
,promise()
returns aPromise
which is the result of callingthen()
on the passedpromise
. ThatPromise
resolves with either the result of job execution orundefined
ifPromise
was superseded by a subsequentPromise
passed as described above.1 Param
- promise Promise
The promise that must resolve before the job is executed
Returns
- Promise
- start({…args})undefined
Starts the job.
0 or more Params
- args Any
- optional
Any args passed are forwarded to the callback
Returns
- undefined
- startAfter(timeout, {…args})undefined
Starts the job in
timeout
milliseconds1 or more Params
- timeout Number
The number of milliseconds to wait before starting the job. This supersedes the timeout set at construction.
- args Any
- optional
Any args passed are forwarded to the callback
Returns
- undefined
- startRaf({…args})undefined
Executes job before the next repaint.
0 or more Params
- args Any
- optional
Any args passed are forwarded to the callback
Returns
- undefined
- startRafAfter(timeout, {…args})undefined
Executes job before the next repaint after a given amount of timeout.
1 or more Params
- timeout Number
The number of milliseconds to wait before running
requestAnimationFrame
.
- args Any
- optional
Any args passed are forwarded to the callback
Returns
- undefined
- stop()undefined
Stops the job.
Returns
- undefined
- throttle(…args)undefined
Executes the job immediately, then prevents any other calls to
throttle()
from running until thetimeout
configured at construction passes.1 or more Params
- args Any
Any args passed are forwarded to the callback
Returns
- undefined
- throttleUntil(timeout, {…args})undefined
Executes the job immediately, then prevents any other calls to
throttle()
from running fortimeout
milliseconds.1 or more Params
- timeout Number
The number of milliseconds to wait before allowing the job to be ran again. This supersedes the timeout set at construction.
- args Any
- optional
Any args passed are forwarded to the callback
Returns
- undefined
capFunction
cap( str )String
Capitalizes a given string (not locale-aware).
1 Param
- str String
The string to capitalize.
Returns
- String
The capitalized string.
clampFunction
clamp( min, max, value )Number
Limits value
to be between min
and max
.
If min
is greater than max
, min
is returned.
3 Params
- min Number
The minimum value of the range
- max Number
The maximum value of the range
- value Number
The value that must be within the range
Returns
- Number
The clamped value
coerceArrayFunction
coerceArray( array )Array
If arg
is array-like, return it. Otherwise returns a single element array containing arg
.
Example:
const returnsArray = coerceArray(0); // [0]
const returnsArg = coerceArray([0]); // [0]
const returnsObjArg = coerceArray({0: 'zeroth', length: 1});
1 Param
- array Any
Array or value
Returns
- Array
Either
array
or[array]
coerceFunctionFunction
coerceFunction( arg )Function
If arg
is a function, return it. Otherwise returns a function that returns arg
.
Example:
const returnsZero = coerceFunction(0);
const returnsArg = coerceFunction(() => 0);
1 Param
- arg Any
Function or value
Returns
- Function
Either
arg
ifarg
is a function, or a function that returnsarg
extractAriaPropsFunction
extractAriaProps( props )Object
Removes ARIA-related props from props
and returns them in a new object.
Specifically, it removes the role
prop and any prop prefixed with aria-
. This is useful when
redirecting ARIA-related props from a non-focusable root element to a focusable child element.
1 Param
- props Object
Props object
Returns
- Object
ARIA-related props
isRenderableFunction
isRenderable( tag )Boolean
Loosely determines if tag
is a renderable component (either a string or a function).
1 Param
- tag Any
Component to test
Returns
- Boolean
true
iftag
is either a string or a function
mapAndFilterChildrenFunction
mapAndFilterChildren( children, callback, {filter} )Any
Maps over the children
, discarding any null
children before and after calling the callback.
A replacement for React.Children.map
.
2 or more Params
- children Any
Children to map over
- callback Function
Function to apply to each child. Will not be called if the child is
null
. Ifcallback
returnsnull
, the child will be removed from the result. Ifnull
is returned, the item will not be included in the final output, regardless of the filter function.
- filter Function
- optional
Filter function applied after mapping.
Returns
- Any
The processed children or the value of
children
if not an array.
memoizeFunction
memoize( fn )Function
Creates a function that memoizes the result of fn
.
Note that this function is a naive implementation and only checks the first argument for memoization.
1 Param
- fn Function
The function to have its output memoized.
Returns
- Function
The new memoized function.
mergeClassNameMapsFunction
mergeClassNameMaps( baseMap, additiveMap, {allowedClassNames} )Object
Merges two class name maps into one.
The resulting map will only contain the class names defined in the baseMap
and will be appended
with the value from additiveMap
if it exists. Further, allowedClassNames
may optionally limit
which keys will be merged from additiveMap
into baseMap
.
Example:
// merges all matching class names from additiveMap1 with baseMap1
const newMap1 = mergeClassNameMaps(baseMap1, additiveMap1);
// merge only 'a' and 'b' class names from additiveMap2 with baseMap2
const newMap2 = mergeClassNameMaps(baseMap2, additiveMap2, ['a', 'b']);
2 or more Params
- baseMap Object
The source mapping of logical class name to physical class name
- additiveMap Object
Mapping of logical to physical class names which are concatenated with
baseMap
where the logical names match
- allowedClassNames ArrayString
- optional
Array of logical class names that can be augmented. When set, the logical class name must exist in
baseMap
,additiveMap
, and this array to be concatenated.
Returns
- Object
The merged class name map.
perfNowFunction
perfNow( )Number
Gets the current timestamp of either window.performance.now
or Date.now
Returns
- Number
The timestamp from
window.performance.now
orDate.now
shallowEqualFunction
shallowEqual( a, b )Boolean
Performs shallow comparison for given objects.
2 Params
- a Obejct
An object to compare.
- b Obejct
An object to compare.
Returns
- Boolean
true
if the values of all keys are strictly equal.