# Watchdog

class

An abstract watchdog class that handles most of the error handling process and the state of the underlying component.

See the [Watchdog feature guide](../features/watchdog.md) to learn the rationale behind it and how to use it.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L21)

<a id="properties">

## Properties

<a id="member-crashes">

### `crashes: Array<object>` _(readonly)_

An array of crashes saved as an object with the following properties:

* `message`: `String`,
* `stack`: `String`,
* `date`: `Number`,
* `filename`: `String | undefined`,
* `lineno`: `Number | undefined`,
* `colno`: `Number | undefined`,

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L32)

<a id="member-state">

### `state: WatchdogState`

Specifies the state of the item watched by the watchdog. The state can be one of the following values:

* `initializing` – Before the first initialization, and after crashes, before the item is ready.
* `ready` – A state when the user can interact with the item.
* `crashed` – A state when an error occurs. It quickly changes to `initializing` or `crashedPermanently` depending on how many and how frequent errors have been caught recently.
* `crashedPermanently` – A state when the watchdog stops reacting to errors and keeps the item it is watching crashed,
* `destroyed` – A state when the item is manually destroyed by the user after calling `watchdog.destroy()`.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L53)

<a id="member-_item">

### `_item: unknown` _(internal)_

The watched item.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L94)

<a id="member-_boundErrorHandler">

### `_boundErrorHandler: ( evt: ErrorEvent | PromiseRejectionEvent ) => void` _(private)_

Checks if the event error comes from the underlying item and restarts the item.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L74)

<a id="member-_crashNumberLimit">

### `_crashNumberLimit: number` _(private)_

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L58)

#### Related:

* [WatchdogConfig](module_watchdog_watchdog-WatchdogConfig.md)

<a id="member-_listeners">

### `_listeners: Record<string, Array<( args: any ) => void>>` _(private)_

A dictionary of event emitter listeners.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L99)

<a id="member-_minimumNonErrorTimePeriod">

### `_minimumNonErrorTimePeriod: number` _(private)_

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L69)

#### Related:

* [WatchdogConfig](module_watchdog_watchdog-WatchdogConfig.md)

<a id="member-_now">

### `_now: () => number` _(private)_

Returns the result of the `Date.now()` call. It can be overridden in tests to mock time as some popular approaches like `sinon.useFakeTimers()` do not work well with error handling.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L64)

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( config )`

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L104)

#### Parameters

* `config: WatchdogConfig`

  The watchdog plugin configuration.

<a id="function-destroy">

### `destroy() → void`

Destroys the watchdog and releases the resources.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L133)

#### Returns

* `void`

<a id="function-off">

### `off( eventName, callback ) → void`

Stops listening to the specified event name by removing the callback from event listeners.

Note that this method differs from the CKEditor 5's default `EventEmitterMixin` implementation.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L164)

#### Parameters

* `eventName: keyof WatchdogEventMap`

  The event name.

* `callback: unknown`

  A callback which will be removed from event listeners.

#### Returns

* `void`

<a id="function-on">

### `on( eventName, callback ) → void`

Starts listening to a specific event name by registering a callback that will be executed whenever an event with a given name fires.

Note that this method differs from the CKEditor 5's default `EventEmitterMixin` implementation.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L148)

#### Type parameters

* `K: extends keyof WatchdogEventMap`

#### Parameters

* `eventName: K`

  The event name.

* `callback: WatchdogEventCallback<K>`

  A callback which will be added to event listeners.

#### Returns

* `void`

<a id="function-_isErrorComingFromThisItem">

### `_isErrorComingFromThisItem( error ) → boolean` _(internal)_

Traverses the error context and the watched item to find out whether the error should be handled by the given item.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L87)

#### Parameters

* `error: CKEditorError`

#### Returns

* `boolean`

<a id="function-_fire">

### `_fire( eventName, args ) → void` _(protected)_

Fires an event with a given event name and arguments.

Note that this method differs from the CKEditor 5's default `EventEmitterMixin` implementation.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L174)

#### Type parameters

* `K: extends keyof WatchdogEventMap`

#### Parameters

* `eventName: K`
* `args: WatchdogEventArgs<K>`

#### Returns

* `void`

<a id="function-_restart">

### `_restart() → Promise<unknown>` _(protected)_

The method responsible for restarting the watched item.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L79)

#### Returns

* `Promise<unknown>`

<a id="function-_startErrorHandling">

### `_startErrorHandling() → void` _(protected)_

Starts error handling by attaching global error handlers.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L185)

#### Returns

* `void`

<a id="function-_stopErrorHandling">

### `_stopErrorHandling() → void` _(protected)_

Stops error handling by detaching global error handlers.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L193)

#### Returns

* `void`

<a id="function-_handleError">

### `_handleError( error, evt ) → void` _(private)_

Checks if an error comes from the watched item and restarts it. It reacts to [`CKEditorError` errors](module_utils_ckeditorerror-CKEditorError.md) only.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L206)

#### Parameters

* `error: Error`

  Error.

* `evt: ErrorEvent | PromiseRejectionEvent`

  An error event.

#### Returns

* `void`

#### Fires

* [error](#event-error)

<a id="function-_shouldReactToError">

### `_shouldReactToError( error ) → boolean` _(private)_

Checks whether an error should be handled by the watchdog.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L244)

#### Parameters

* `error: Error`

  An error that was caught by the error handling process.

#### Returns

* `boolean`

<a id="function-_shouldRestart">

### `_shouldRestart() → boolean` _(private)_

Checks if the watchdog should restart the underlying item.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L264)

#### Returns

* `boolean`

<a id="events">

## Events

<a id="event-error">

### `error( eventInfo, <anonymous> )`

Fired when a new [`CKEditorError`](module_utils_ckeditorerror-CKEditorError.md) error connected to the watchdog instance occurs and the watchdog will react to it.

```typescript
watchdog.on( 'error', ( evt, { error, causesRestart } ) => {
	console.log( 'An error occurred.' );
} );
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L290)

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `<anonymous>: WatchdogErrorEventData`

<a id="event-stateChange">

### `stateChange( eventInfo )`

Fired when the watchdog state changed.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/src/watchdog.ts#L308)

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)