# ContextWatchdog

class

A watchdog for the [`Context`](module_core_context-Context.md) class.

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/contextwatchdog.ts#L25)

<a id="type-parameters">

## Type parameters

### `TContext: extends Context`

<a id="properties">

## Properties

<a id="member-_item">

### `_item: unknown`

The watched item.

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

<a id="member-context">

### `context: Context | null` _(readonly)_

The context instance. Keep in mind that this property might be changed when the context watchdog restarts, so do not keep this instance internally. Always operate on the `ContextWatchdog#context` property.

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

<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` _(inherited)_

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-_creator">

### `_creator: ( config: ContextConfig ) => Promise<TContext>` _(protected)_

The creation method.

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

#### Related:

* [ContextWatchdog#setCreator](#function-setCreator)

<a id="member-_destructor">

### `_destructor: ( context: Context ) => Promise<unknown>` _(protected)_

The destruction method.

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

#### Related:

* [ContextWatchdog#setDestructor](#function-setDestructor)

<a id="member-_watchdogs">

### `_watchdogs: Map<string, EditorWatchdog<Editor>>` _(protected)_

A map of internal watchdogs for added items.

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

<a id="member-_actionQueues">

### `_actionQueues: ActionQueues` _(private)_

An action queue, which is used to handle async functions queuing.

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

<a id="member-_context">

### `_context: TContext | null` _(private)_

The current context instance.

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

<a id="member-_contextConfig">

### `_contextConfig?: ContextConfig` _(private)_

The configuration for the [`Context`](module_core_context-Context.md).

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

<a id="member-_contextProps">

### `_contextProps: Set<unknown>` _(private)_

Context properties (nodes/references) that are gathered during the initial context creation and are used to distinguish the origin of an error.

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

<a id="member-_watchdogConfig">

### `_watchdogConfig: WatchdogConfig` _(private)_

The watchdog configuration.

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

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor( Context = { Context.create }, watchdogConfig )`

The context watchdog class constructor.

```typescript
const watchdog = new ContextWatchdog( Context );

await watchdog.create( contextConfiguration );

await watchdog.add( item );
```

See the [Watchdog feature guide](../features/watchdog.md) to learn more how to use this feature.

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

#### Type parameters

* `TContext: extends Context`

#### Parameters

* `Context: object`

  The [`Context`](module_core_context-Context.md) class.

  Properties

  * `Context.create: Promise<TContext>`

* `watchdogConfig: WatchdogConfig`

  The watchdog configuration.

  Defaults to `{}`

<a id="function-add">

### `add( itemConfigurationOrItemConfigurations ) → Promise<unknown>`

Adds items to the watchdog. Once created, instances of these items will be available using the [`getItem`](#function-getItem) method.

Items can be passed together as an array of objects:

```typescript
await watchdog.add( [ {
	id: 'editor1',
	type: 'editor',
	config: {
		attachTo: document.querySelector( '#editor' ),
		plugins: [ Essentials, Paragraph, Bold, Italic ],
		toolbar: [ 'bold', 'italic', 'alignment' ]
	},
	creator: config => ClassicEditor.create( config )
} ] );
```

Or one by one as objects:

```typescript
await watchdog.add( {
	id: 'editor1',
	type: 'editor',
	config: {
		attachTo: document.querySelector( '#editor' ),
		plugins: [ Essentials, Paragraph, Bold, Italic ],
		toolbar: [ 'bold', 'italic', 'alignment' ]
	},
	creator: config => ClassicEditor.create( config )
} );
```

Then an instance can be retrieved using the [`getItem`](#function-getItem) method:

```typescript
const editor1 = watchdog.getItem( 'editor1' );
```

Note that this method can be called multiple times, but for performance reasons it is better to pass all items together.

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

#### Parameters

* `itemConfigurationOrItemConfigurations: ArrayOrItem<ContextWatchdogItemConfiguration>`

  An item configuration object or an array of item configurations.

#### Returns

* `Promise<unknown>`

<a id="function-create">

### `create( contextConfig ) → Promise<unknown>`

Initializes the context watchdog. Once it is created, the watchdog takes care about recreating the context and the provided items, and starts the error handling mechanism.

```typescript
await watchdog.create( {
	plugins: []
} );
```

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

#### Parameters

* `contextConfig: ContextConfig`

  The context configuration. See [`Context`](module_core_context-Context.md).

  Defaults to `{}`

#### Returns

* `Promise<unknown>`

<a id="function-destroy">

### `destroy() → Promise<unknown>`

Destroys the context watchdog and all added items. Once the context watchdog is destroyed, new items cannot be added.

```typescript
await watchdog.destroy();
```

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

#### Returns

* `Promise<unknown>`

<a id="function-getItem">

### `getItem( itemId ) → unknown`

Returns an item instance with the given `itemId`.

```typescript
const editor1 = watchdog.getItem( 'editor1' );
```

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

#### Parameters

* `itemId: string`

  The item ID.

#### Returns

* `unknown`

  The item instance or `undefined` if an item with a given ID has not been found.

<a id="function-getItemState">

### `getItemState( itemId ) → WatchdogState`

Gets the state of the given item. See [`state`](#member-state) for a list of available states.

```typescript
const editor1State = watchdog.getItemState( 'editor1' );
```

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

#### Parameters

* `itemId: string`

  Item ID.

#### Returns

* `WatchdogState`

  The state of the item.

<a id="function-off">

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

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` _(inherited)_

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-remove">

### `remove( itemIdOrItemIds ) → Promise<unknown>`

Removes and destroys item(s) with given ID(s).

```typescript
await watchdog.remove( 'editor1' );
```

Or

```typescript
await watchdog.remove( [ 'editor1', 'editor2' ] );
```

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

#### Parameters

* `itemIdOrItemIds: ArrayOrItem<string>`

  Item ID or an array of item IDs.

#### Returns

* `Promise<unknown>`

<a id="function-setCreator">

### `setCreator( creator ) → void`

Sets the function that is responsible for the context creation. It expects a function that should return a promise (or `undefined`).

```typescript
watchdog.setCreator( config => Context.create( config ) );
```

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

#### Parameters

* `creator: ( config: ContextConfig ) => Promise<TContext>`

#### Returns

* `void`

<a id="function-setDestructor">

### `setDestructor( destructor ) → void`

Sets the function that is responsible for the context destruction. Overrides the default destruction function, which destroys only the context instance. It expects a function that should return a promise (or `undefined`).

```typescript
watchdog.setDestructor( context => {
	// Do something before the context is destroyed.

	return context
		.destroy()
		.then( () => {
			// Do something after the context is destroyed.
		} );
} );
```

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

#### Parameters

* `destructor: ( context: Context ) => Promise<unknown>`

#### Returns

* `void`

<a id="function-_isErrorComingFromThisItem">

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

Checks whether an error comes from the context instance and not from the item instances.

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

#### 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-_getWatchdog">

### `_getWatchdog( itemId ) → Watchdog` _(protected)_

Returns the watchdog for a given item ID.

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

#### Parameters

* `itemId: string`

  Item ID.

#### Returns

* `Watchdog`

<a id="function-_restart">

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

Restarts the context watchdog.

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

#### 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-_create">

### `_create() → Promise<unknown>` _(private)_

Initializes the context watchdog.

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

#### Returns

* `Promise<unknown>`

<a id="function-_destroy">

### `_destroy() → Promise<unknown>` _(private)_

Destroys the context instance and all added items.

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

#### Returns

* `Promise<unknown>`

<a id="events">

## Events

<a id="event-error">

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

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-itemError">

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

Fired when a new error occurred in one of the added items.

```typescript
watchdog.on( 'itemError', ( evt, { error, itemId } ) => {
	console.log( `An error occurred in an item with the '${ itemId }' ID.` );
} );
```

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

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `<anonymous>: ContextWatchdogItemErrorEventData`

<a id="event-itemRestart">

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

Fired after an item has been restarted.

```typescript
watchdog.on( 'itemRestart', ( evt, { itemId } ) => {
		console.log( 'An item with with the '${ itemId }' ID has been restarted.' );
	} );
```

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

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

* `<anonymous>: ContextWatchdogItemRestartEventData`

<a id="event-restart">

### `restart( eventInfo )`

Fired after the watchdog restarts the context and the added items because of a crash.

```typescript
watchdog.on( 'restart', () => {
	console.log( 'The context has been restarted.' );
} );
```

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

#### Parameters

* `eventInfo: EventInfo`

  An object containing information about the fired event.

<a id="event-stateChange">

### `stateChange( eventInfo )` _(inherited)_

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)