@enact/core/handle/handle.d.ts

Enact is an open source JavaScript framework containing everything you need to create a fast, scalable mobile or web application.

// Type definitions for core/handle

type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
type Merge<M, N> = Omit<M, Extract<keyof M, keyof N>> & N;

/**
 * The signature for event handlers
 */
export interface EventHandler {
  (event: any): void;
}
/**
 * The signature for event handling functions supported by  `handle`  and related functions
 */
export interface HandlerFunction {
  (
    event: any,
    props: { [key: string]: any },
    context: { [key: string]: any },
  ): void;
}
/**
 * The signature for    parameter  `adapter`
 */
export interface EventAdapter {
  (
    event: any,
    props: { [key: string]: any },
    context: { [key: string]: any },
  ): any;
}
/**
 * Allows generating event handlers by chaining input functions to filter or short-circuit the
handling flow. Any input function that returns a falsy value will stop the chain.
 * 
 * The returned handler function has a  `finally()`  member that accepts a function and returns a new
handler function. The accepted function is called once the original handler completes regardless
of the returned value.
 */
export function handle(...handlers: HandlerFunction[]): EventHandler;
/**
 * Calls the first handler whose condition passes. Each branch must be passed as an array with the
first element being the condition function and the second being the handler function. The same
arguments are passed to both the condition function and the handler function. The value returned
from the handler is returned.
 * 
 * Example:
 * ```
const handler = oneOf(
	[forKey('enter'), handleEnter],
	[forKey('left'), handleLeft],
	[forKey('right'), handleRight]
);
```
 */
export function oneOf(
  ...handlers: [HandlerFunction, HandlerFunction][]
): HandlerFunction;
/**
 * A function that always returns  `true` . Optionally accepts a  `handler`  function which is called
before returning  `true` .
 * 
 * Example:
 * ```
// Used to coerce an existing function into a handler
const coercedHandler = handle(
  returnsTrue(doesSomething),
  willAlwaysBeCalled
);

// Used to emulate if/else blocks with `oneOf`
const ifElseHandler = oneOf(
	[forKey('enter'), handleEnter],
	[returnsTrue, handleOtherwise]
);
```
 */
export function returnsTrue(handler?: Function): HandlerFunction;
/**
 * Allows handling to continue if the value of  `prop`  on the event strictly equals  `value`
 * 
 * Example:
 * ```
import {forEventProp, handle} from '@enact/core/handle';

const logWhenXEqualsZero = handle(
  forEventProp('x', 0),
  (ev) => console.log('ev.x was equal to zero', ev)
);
```
 */
export function forEventProp(prop: string, value: any, ev: object): boolean;
/**
 * Allows handling to continue if the value of  `prop`  on the event strictly equals  `value`
 * 
 * Example:
 * ```
import {forEventProp, handle} from '@enact/core/handle';

const logWhenXEqualsZero = handle(
  forEventProp('x', 0),
  (ev) => console.log('ev.x was equal to zero', ev)
);
```
 */
export function forEventProp(prop: string): (value: any, ev: object) => boolean;
/**
 * Allows handling to continue if the value of  `prop`  on the event strictly equals  `value`
 * 
 * Example:
 * ```
import {forEventProp, handle} from '@enact/core/handle';

const logWhenXEqualsZero = handle(
  forEventProp('x', 0),
  (ev) => console.log('ev.x was equal to zero', ev)
);
```
 */
export function forEventProp(
  prop: string,
): (value: any) => (ev: object) => boolean;
/**
 * Allows handling to continue if the value of  `prop`  on the event strictly equals  `value`
 * 
 * Example:
 * ```
import {forEventProp, handle} from '@enact/core/handle';

const logWhenXEqualsZero = handle(
  forEventProp('x', 0),
  (ev) => console.log('ev.x was equal to zero', ev)
);
```
 */
export function forEventProp(prop: string, value: any): (ev: object) => boolean;
/**
 * Forwards the event to a function at  `name`  on  `props` . If the specified prop is  `undefined`  or
is not a function, it is ignored. The return value of the forwarded function is ignored and
 `true`  is always returned instead.
 * 
 * Example:
 * ```
import {forward, handle} from '@enact/core/handle';

const forwardAndLog = handle(
  forward('onClick'),
  (ev) => console.log('event forwarded to onClick from props', ev)
);
```
 */
export function forward(name: string, ev: object, props: object): true;
/**
 * Forwards the event to a function at  `name`  on  `props` . If the specified prop is  `undefined`  or
is not a function, it is ignored. The return value of the forwarded function is ignored and
 `true`  is always returned instead.
 * 
 * Example:
 * ```
import {forward, handle} from '@enact/core/handle';

const forwardAndLog = handle(
  forward('onClick'),
  (ev) => console.log('event forwarded to onClick from props', ev)
);
```
 */
export function forward(name: string): (ev: object, props: object) => true;
/**
 * Forwards the event to a function at  `name`  on  `props` . If the specified prop is  `undefined`  or
is not a function, it is ignored. The return value of the forwarded function is ignored and
 `true`  is always returned instead.
 * 
 * Example:
 * ```
import {forward, handle} from '@enact/core/handle';

const forwardAndLog = handle(
  forward('onClick'),
  (ev) => console.log('event forwarded to onClick from props', ev)
);
```
 */
export function forward(name: string): (ev: object) => (props: object) => true;
/**
 * Forwards the event to a function at  `name`  on  `props` . If the specified prop is  `undefined`  or
is not a function, it is ignored. The return value of the forwarded function is ignored and
 `true`  is always returned instead.
 * 
 * Example:
 * ```
import {forward, handle} from '@enact/core/handle';

const forwardAndLog = handle(
  forward('onClick'),
  (ev) => console.log('event forwarded to onClick from props', ev)
);
```
 */
export function forward(name: string, ev: object): (props: object) => true;
/**
 * Calls  `event.preventDefault()`  and returns  `true` .
 * 
 * Example:
 * ```
import {handle, preventDefault} from '@enact/core/handle';

const preventAndLog = handle(
  preventDefault,
  (ev) => console.log('preventDefault called', ev)
);
```
 */
export function preventDefault(ev: object): true;
/**
 * Calls  `event.stopPropagation()`  and returns  `true`
 * 
 * Example:
 * ```
import {handle, stop} from '@enact/core/handle';

const stopAndLog = handle(
  stop,
  (ev) => console.log('stopPropagation called', ev)
);
```
 */
export function stop(ev: object): true;
/**
 * Calls  `event.stopImmediatePropagation()`  and returns  `true`
 * 
 * Example:
 * ```
import {handle, stopImmediate} from '@enact/core/handle';

const stopImmediateAndLog = handle(
  stopImmediate,
  (ev) => console.log('stopImmediatePropagation called', ev)
);
```
 */
export function stopImmediate(ev: object): true;
/**
 * Allows event handling to continue if  `event.keyCode === value` .
 * 
 * Example:
 * ```
import {forKeyCode, handle} from '@enact/core/handle';

const logForEscapeKey = handle(
  forKeyCode(27),
  (ev) => console.log('Escape key pressed down', ev)
);
```
 */
export function forKeyCode(value: number, ev: object): boolean;
/**
 * Allows event handling to continue if  `event.keyCode === value` .
 * 
 * Example:
 * ```
import {forKeyCode, handle} from '@enact/core/handle';

const logForEscapeKey = handle(
  forKeyCode(27),
  (ev) => console.log('Escape key pressed down', ev)
);
```
 */
export function forKeyCode(value: number): (ev: object) => boolean;
/**
 * Allows handling to continue if the event's keyCode is mapped to  `name`  within
  .
 * 
 * Example:
 * ```
import {forKey, handle} from '@enact/core/handle';

const logForEnterKey = handle(
  forKey('enter'),
  (ev) => console.log('Enter key pressed down', ev)
);
```
 */
export function forKey(name: string, ev: object): boolean;
/**
 * Allows handling to continue if the event's keyCode is mapped to  `name`  within
  .
 * 
 * Example:
 * ```
import {forKey, handle} from '@enact/core/handle';

const logForEnterKey = handle(
  forKey('enter'),
  (ev) => console.log('Enter key pressed down', ev)
);
```
 */
export function forKey(name: string): (ev: object) => boolean;
/**
 * Allows handling to continue if the value of  `prop`  on the props strictly equals  `value` .
 * 
 * Example:
 * ```
import {forProp, handle} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  (ev) => console.log('checked prop is true', ev)
);
```
 */
export function forProp(
  prop: string,
  value: any,
  ev: object,
  props: object,
): boolean;
/**
 * Allows handling to continue if the value of  `prop`  on the props strictly equals  `value` .
 * 
 * Example:
 * ```
import {forProp, handle} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  (ev) => console.log('checked prop is true', ev)
);
```
 */
export function forProp(
  prop: string,
): (value: any, ev: object, props: object) => boolean;
/**
 * Allows handling to continue if the value of  `prop`  on the props strictly equals  `value` .
 * 
 * Example:
 * ```
import {forProp, handle} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  (ev) => console.log('checked prop is true', ev)
);
```
 */
export function forProp(
  prop: string,
): (value: any) => (ev: object, props: object) => boolean;
/**
 * Allows handling to continue if the value of  `prop`  on the props strictly equals  `value` .
 * 
 * Example:
 * ```
import {forProp, handle} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  (ev) => console.log('checked prop is true', ev)
);
```
 */
export function forProp(
  prop: string,
): (value: any) => (ev: object) => (props: object) => boolean;
/**
 * Allows handling to continue if the value of  `prop`  on the props strictly equals  `value` .
 * 
 * Example:
 * ```
import {forProp, handle} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  (ev) => console.log('checked prop is true', ev)
);
```
 */
export function forProp(
  prop: string,
): (value: any, ev: object) => (props: object) => boolean;
/**
 * Allows handling to continue if the value of  `prop`  on the props strictly equals  `value` .
 * 
 * Example:
 * ```
import {forProp, handle} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  (ev) => console.log('checked prop is true', ev)
);
```
 */
export function forProp(
  prop: string,
  value: any,
): (ev: object, props: object) => boolean;
/**
 * Allows handling to continue if the value of  `prop`  on the props strictly equals  `value` .
 * 
 * Example:
 * ```
import {forProp, handle} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  (ev) => console.log('checked prop is true', ev)
);
```
 */
export function forProp(
  prop: string,
  value: any,
): (ev: object) => (props: object) => boolean;
/**
 * Allows handling to continue if the value of  `prop`  on the props strictly equals  `value` .
 * 
 * Example:
 * ```
import {forProp, handle} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  (ev) => console.log('checked prop is true', ev)
);
```
 */
export function forProp(
  prop: string,
  value: any,
  ev: object,
): (props: object) => boolean;
/**
 * Logs the event, props, and context optionally preceded by a custom message. Will only log in
development mode.
 * 
 * Example:
 * ```
import {forProp, handle, log} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  log('checked props is true')
);
```
 */
export function log(message: string, ev: object, args?: any[]): true;
/**
 * Logs the event, props, and context optionally preceded by a custom message. Will only log in
development mode.
 * 
 * Example:
 * ```
import {forProp, handle, log} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  log('checked props is true')
);
```
 */
export function log(message: string): (ev: object, args?: any[]) => true;
/**
 * Logs the event, props, and context optionally preceded by a custom message. Will only log in
development mode.
 * 
 * Example:
 * ```
import {forProp, handle, log} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  log('checked props is true')
);
```
 */
export function log(message: string): (ev: object) => (args?: any[]) => true;
/**
 * Logs the event, props, and context optionally preceded by a custom message. Will only log in
development mode.
 * 
 * Example:
 * ```
import {forProp, handle, log} from '@enact/core/handle';

const logWhenChecked = handle(
  forProp('checked', true),
  log('checked props is true')
);
```
 */
export function log(message: string, ev: object): (args?: any[]) => true;
/**
 * Invokes a method by name on the component to which    is bound.
 * 
 * If the methods exist on the object, it is called with the event, props, and context and its
return value is returned.
 * 
 * If the method does not exist or handle isn't bound to an instance, it returns  `false` .
 * 
 * Example:
 * ```
import {call, handle, forProp} from '@enact/core/handle';

const incrementIfEnabled = handle(
  forProp('disabled', false),
  call('increment')
);

class Counter extends React.Component {
  constructor () {
    super();

    this.handleIncrement = incrementIfEnabled.bind(this);
  }

  render () {
    // ...
  }
}
```
 */
export function call(method: string): HandlerFunction;
/**
 * Adapts an event with  `adapter`  before calling  `handler` .
 * 
 * The  `adapter`  function receives the same arguments as any handler. The value returned from
 `adapter`  is passed as the first argument to  `handler`  with the remaining arguments kept the
same. This is often useful to generate a custom event payload before forwarding on to a callback.
 * 
 * Example:
 * ```
import {adaptEvent, forward} from '@enact/core/handle';

// calls the onChange callback with an event payload containing a type and value member
const incrementAndChange = adaptEvent(
	(ev, props) => ({
	  type: 'onChange',
	  value: props.value + 1
	}),
	forward('onChange')
)
```
 */
export function adaptEvent(
  adapter: EventAdapter,
  handler: HandlerFunction,
): HandlerFunction;
/**
 * Adapts an event with  `adapter`  before calling  `handler` .
 * 
 * The  `adapter`  function receives the same arguments as any handler. The value returned from
 `adapter`  is passed as the first argument to  `handler`  with the remaining arguments kept the
same. This is often useful to generate a custom event payload before forwarding on to a callback.
 * 
 * Example:
 * ```
import {adaptEvent, forward} from '@enact/core/handle';

// calls the onChange callback with an event payload containing a type and value member
const incrementAndChange = adaptEvent(
	(ev, props) => ({
	  type: 'onChange',
	  value: props.value + 1
	}),
	forward('onChange')
)
```
 */
export function adaptEvent(
  adapter: EventAdapter,
): (handler: HandlerFunction) => HandlerFunction;
/**
 * Creates a handler that will forward the event to a function at  `name`  on  `props` .
 * 
 * If  `adapter`  is not specified, a new event payload will be generated with a  `type`  member with
the  `name`  of the custom event. If  `adapter`  is specified, the  `type`  member is added to the
value returned by  `adapter` .
 * 
 * The  `adapter`  function receives the same arguments as any handler. The value returned from
 `adapter`  is passed as the first argument to  `handler`  with the remaining arguments kept the
same. This is often useful to generate a custom event payload before forwarding on to a callback.
 * 
 * Example:
 * ```
import {forwardCustom} from '@enact/core/handle';

// calls the onChange callback with the event: {type: 'onChange'}
const forwardChange = forwardCustom('onChange');

// calls the onChange callback with the event: {type: 'onChange', index}
const forwardChangeWithIndex = forwardCustom('onChange', (ev, {index}) => ({index}));
```
 */
export function forwardCustom(
  name: string,
  adapter?: EventAdapter,
): HandlerFunction;
/**
 * Accepts a handler and returns the logical complement of the value returned from the handler.
 * 
 * Example:
 * ```
import {forProp, forward, not, handle} from '@enact/core/handle';

// calls the onChange callback when disabled is not true
const handleChange = handle(
 not(forProp('disabled', true)),
 forward('onChange')
)
```
 */
export function not(handler: HandlerFunction): HandlerFunction;

export default handle;