Enact
Edit on GitHub

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
Job(fn, timeout)
2 Params
fn Function

Function to execute as the requested job.

timeout Number

The number of milliseconds to wait before starting the job.

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 on Job, calling promise() again with a new Promise will block execution of the job until that new Promise resolves. Any previous Promises will still resolve normally but will not trigger job execution.

Unlike other methods on Job, promise() returns a Promise which is the result of calling then() on the passed promise. That Promise resolves with either the result of job execution or undefined if Promise was superseded by a subsequent Promise 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 milliseconds

1 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 the timeout 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 for timeout 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});
See: MDN input types doc
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 if arg is a function, or a function that returns arg

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 if tag 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.

See: MDN input types doc
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. If callback returns null, the child will be removed from the result. If null 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 or Date.now

ArrayBooleanFunctionModuleNumberObjectString