# Helpers

### AO Event Handlers & Helpers

All event handlers receive the same arguments: `(instance = {}, ...args)`. The instance contains two objects, `{ state = {}, h = {} }` with `state` being the current AO state, and `h` being a helper object.

The provided helpers are:

- `clearAllTimeouts()` - clears all pending order submit/cancel timeouts

- `debug(str, ...args)` - for logging information to the console, tagged by AO GID

- `emitSelf(eventName, ...args)` - triggers an event on the 'self' section

- `emitSelfAsync(eventName, ...args)` - same as `emitSelf` but operates on next tick

- `emit(eventName, ...args)` - raw event emitter, i.e. `emit('life:start')`

- `emitAsync(eventName, ...args)` - same as `emit` but operates on next tick

- `notifyUI(level, message)` - generates and sends a notification which appears on the Bitfinex UI

- `cancelOrderWithDelay(state, delay, order)` - takes current algo state, delay in ms

- `cancelAllOrdersWithDelay(state, delay)` - cancels all active atomic orders on the AO state, delay in ms

- `submitOrderWithDelay(state, delay, order)` - takes current algo state, submits a new order, delay in ms

- `declareEvent(instance, host, eventName, path)` - declares an internal AO event, see section below

- `declareChannel(instance, host, channel, filter)` - declares a required data channel, see section below

- `updateState(instance, update)` - update the current state for an AO instance

Source:
  - host/gen_helpers.js, line 33

### Methods

#### (inner) cancelAllOrdersWithDelay(state, delay) → {object}

Source:
  - host/gen_helpers.js, line 242

Cancels all orders currently on the AO state after the specified delay

##### Example

    await cancelAllOrdersWithDelay(state, 100)

##### Parameters:

Name | Type | Description
--- | --- | ---
`state` | object | current AO instance state
`delay` | number | in ms

##### Returns:

nextState

Type
  object

#### (inner) cancelOrderWithDelay(state, delay, order) → {object}

Source:
  - host/gen_helpers.js, line 211

Cancels the provided order after a delay, and removes it from the active order set.

##### Example

    await cancelOrderWithDelay(state, 100, order)

##### Parameters:

Name | Type | Description
--- | --- | ---
`state` | object | current AO instance state
`delay` | number | in ms
`order` | object | order model or array

##### Returns:

nextState

Type
  object

#### (inner) clearAllTimeouts()

Source:
  - host/gen_helpers.js, line 83

Clear all timeouts for pending order submits/cancellations, called automatically by the algo host on teardown.

#### (inner) debug(str, …args)

Source:
  - host/gen_helpers.js, line 102

Logs a string to the console, tagged by AO id/gid

##### Example

    debug('submitting order %s in %dms', order.toString(), delay)

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`str` | string |  | format string
`args` | any | <repeatable> | passed to debug()

#### (inner) declareChannel(instance, aoHost, channel, filter) → {object}

Source:
  - host/gen_helpers.js, line 369

Assigns a data channel to the provided AO instance

##### Example

    await declareChannel(instance, host, 'trades', { symbol })

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | object | full AO instance, with state/h
`aoHost` | object | unused, here for common signature
`channel` | string | channel name, i.e. 'ticker'
`filter` | object | channel spec, i.e. { symbol: 'tBTCUSD' }

##### Returns:

nextState

Type
  object

#### (inner) declareEvent(instance, aoHost, eventName, path)

Source:
  - host/gen_helpers.js, line 348

Hooks up the listener for a new event on the 'self' section

##### Example

    declareEvent(instance, host, 'self:interval_tick', 'interval_tick')

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | object | full AO instance, with state/h
`aoHost` | object | algo host instance
`eventName` | string | name of event to declare
`path` | string | on the 'self' section

#### (inner) emit(eventName, …eventArgs) → {Promise}

Source:
  - host/gen_helpers.js, line 155

Triggers a generic event

##### Example

    await emit('exec:order:submit:all', gid, [order], submitDelay)

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`eventName` | string |  | name of event to emit
`eventArgs` | any | <repeatable> | args passed to all handlers

##### Returns:

p - resolves when all handlers complete

Type
  Promise

#### (inner) emitAsync(eventName, …eventArgs) → {Promise}

Source:
  - host/gen_helpers.js, line 169

Like `emit` but operates after a timeout

##### Example

    await emitAsync('exec:order:submit:all', gid, [order], submitDelay)

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`eventName` | string |  | name of event to emit
`eventArgs` | any | <repeatable> | args passed to all handlers

##### Returns:

p - resolves when all handlers complete

Type
  Promise

#### (inner) emitSelf(eventName, …eventArgs) → {Promise}

Source:
  - host/gen_helpers.js, line 115

Triggeres an event on the 'self' section

##### Example

    await emitSelf('submit_orders')

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`eventName` | string |  | name of event to emit
`eventArgs` | any | <repeatable> | args passed to all handlers

##### Returns:

p - resolves when all handlers complete

Type
  Promise

#### (inner) emitSelfAsync(eventName, …eventArgs) → {Promise}

Source:
  - host/gen_helpers.js, line 129

Like `emitSelf` but operates after a timeout

##### Example

    await emitSelfAsync('submit_orders')

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`eventName` | string |  | name of event to emit
`eventArgs` | any | <repeatable> | args passed to all handlers

##### Returns:

p - resolves when all handlers complete

Type
  Promise

#### (inner) notifyUI(level, message) → {Promise}

Source:
  - host/gen_helpers.js, line 195

Triggers an UI notification, sent out via the active websocket connection

##### Example

    await notifyUI('info', `Scheduled tick in ${delay}s`)

##### Parameters:

Name | Type | Description
--- | --- | ---
`level` | string | 'info', 'success', 'error', 'warning'
`message` | string | notification content

##### Returns:

p - resolves when all handlers complete

Type
  Promise

#### (inner) submitOrderWithDelay(state, delay, order, attempt) → {object}

Source:
  - host/gen_helpers.js, line 280

Submits an order after a delay, and adds it to the active order set on the AO state. Emits errors if the order fails to submit; retries up to MAX_SUBMIT_ATTEMPTS in the case of balance evaluation errors.

##### Example

    await submitOrderWithDelay(state, 100, order)

##### Parameters:

Name | Type | Description
--- | --- | ---
`state` | object | current AO instance state
`delay` | number | delay in milliseconds
`order` | object | order model
`attempt` | number | attempt count, max is 10 (set as a constant)

##### Returns:

nextState

Type
  object

#### (inner) updateState(instance, update) → {object}

Source:
  - host/gen_helpers.js, line 393

Updates the state for the provided AO instance

##### Example

    await updateState(instance, { remainingAmount })

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | object | full AO instance, with state/h
`update` | object | new state

##### Returns:

nextState

Type
  object