core/util

Edit on GitHub

A collection of utility methods.

Members

Job Class

Provides a convenient way to manage timed execution of functions.

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.

Returns

Methods

idle({...args})

→ undefined

Executes job when the CPU is idle.

1 Param

Optional • args ...Any: 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.

2 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.

Optional • args ...Any: 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.

1 Param

Optional • args ...Any: Any args passed are forwarded to the callback

Returns

undefined

startAfter(timeout, {...args})

→ undefined

Starts the job in timeout milliseconds

2 Params

timeout Number: The number of milliseconds to wait before starting the job. This supersedes the timeout set at construction.

Optional • args ...Any: Any args passed are forwarded to the callback

Returns

undefined

startRaf({...args})

→ undefined

Executes job before the next repaint.

1 Param

Optional • args ...Any: 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.

2 Params

timeout Number: The number of milliseconds to wait before running requestAnimationFrame.

Optional • args ...Any: Any args passed are forwarded to the callback

Returns

undefined

stop()

→ undefined

Stops the job.

0 Params

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 Param

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.

2 Params

timeout Number: The number of milliseconds to wait before allowing the job to be ran again. This supersedes the timeout set at construction.

Optional • args ...Any: Any args passed are forwarded to the callback

Returns

undefined

applyDefaultProps Function

applyDefaultProps( target, defaultProps, {keys} ) → Object

Applies default values for keys that are undefined on target.

When keys is provided, only those keys are considered. This avoids Object.keys on the hot path (e.g. core/kind render).

3 Params

target Object: Props object to update in place

defaultProps Object: Default value object

Optional • keys Array(String): Optional precomputed key list

Returns

Object: The updated target

cap Function

cap( str ) → String

Capitalizes a given string (not locale-aware).

1 Param

str String: The string to capitalize.

Returns

String: The capitalized string.

checkPropTypes Function

checkPropTypes( component, props, {prevProps} ) → undefined

Checks the prop types of a component.

It only performs the check when __DEV__ is true.

3 Params

component Object: The component instance to check.

props Object: The component props to check.

Optional • prevProps Object: The previous props to compare against.

Returns

undefined

clamp Function

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

coerceArray Function

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]

coerceFunction Function

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

extractAriaProps Function

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

isRenderable Function

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

mapAndFilterChildren Function

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.

3 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.

Optional • filter Function: Filter function applied after mapping.

Returns

Any: The processed children or the value of children if not an array.

memoize Function

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.

mergeClassNameMaps Function

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']);

3 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

Optional • allowedClassNames Array(String): 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.

normalizePublicClassNames Function

normalizePublicClassNames( {publicClassNames}, {css} ) → Array(String)  |  Boolean  |  String  |  undefined

Normalizes a publicClassNames config value into an array of logical class names.

2 Params

Optional • publicClassNames Boolean | String | Array(String): The public class names config

Optional • css Object: Component CSS map used when publicClassNames is true

Returns

Array(String) | Boolean | String | undefined: Normalized class name list, or the original value when no normalization applies

perfNow Function

perfNow(  ) → Number

Gets the current timestamp of either window.performance.now or Date.now

0 Params

Returns

Number: The timestamp from window.performance.now or Date.now

setDefaultProps Function

setDefaultProps( props, defaultProps ) → Object

Sets props that are missing or undefined to default values

2 Params

props Object: Props object

defaultProps Object default: {}: Default value object

Returns

Object: Props with default values

shallowEqual Function

shallowEqual( a, b ) → Boolean

Performs shallow comparison for given objects.

2 Params

a Object: An object to compare.

b Object: An object to compare.

Returns

Boolean: true if the values of all keys are strictly equal.

usePrevious Function

usePrevious( value ) → Any

A custom hook that returns the previous value of a variable.

1 Param

value Any: The value to track.

Returns

Any: The value from the previous render.