CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

ContextWatchdog (watchdog)

@ckeditor/ckeditor5-watchdog/src/contextwatchdog

class
See source

A watchdog for the Context class.

See the Watchdog feature guide to learn the rationale behind it and how to use it.

Filtering

Type parameters

Properties

  • _item : unknown

    See source

    The watched item.

  • readonly

    context : null | Context

    See source

    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.

  • readonly inherited

    crashes : Array<object>

    See source

    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,

  • inherited

    state : WatchdogState

    See source

    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().

  • protected

    _creator : ( ContextConfig ) => Promise<TContext>

    See source

    The creation method.

  • protected

    _destructor : ( Context ) => Promise<unknown>

    See source

    The destruction method.

  • protected

    _watchdogs : Map<string, EditorWatchdog<Editor>>

    See source

    A map of internal watchdogs for added items.

  • private

    _actionQueues : ActionQueues

    See source

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

  • private

    _context : null | TContext

    See source

    The current context instance.

  • private

    _contextConfig : ContextConfig | undefined

    See source

    The configuration for the Context.

  • private

    _contextProps : Set<unknown>

    See source

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

  • private readonly

    _watchdogConfig : WatchdogConfig

    See source

    The watchdog configuration.

Methods

  • constructor( Context = { Context.create }, watchdogConfig )

    See source

    The context watchdog class constructor.

    const watchdog = new ContextWatchdog( Context );

await watchdog.create( contextConfiguration );

await watchdog.add( item );

    See the Watchdog feature guide to learn more how to use this feature.

    Type parameters

    TContext : extends [object Object] = default

    Parameters

    Context : object

    The Context class.

    Properties
    Context.create : Promise<TContext>
    watchdogConfig : WatchdogConfig

    The watchdog configuration.

    Defaults to {}

  • add( itemConfigurationOrItemConfigurations ) → Promise<unknown>

    See source

    Adds items to the watchdog. Once created, instances of these items will be available using the getItem method.

    Items can be passed together as an array of objects:

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

    Or one by one as objects:

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

    Then an instance can be retrieved using the getItem method:

    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.

    Parameters

    itemConfigurationOrItemConfigurations : ArrayOrItem<WatchdogItemConfiguration>

    An item configuration object or an array of item configurations.

    Returns

    Promise<unknown>

  • create( contextConfig ) → Promise<unknown>

    See source

    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.

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

    Parameters

    contextConfig : ContextConfig

    The context configuration. See Context.

    Defaults to {}

    Returns

    Promise<unknown>

  • destroy() → Promise<unknown>

    See source

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

    await watchdog.destroy();

    Returns

    Promise<unknown>

  • getItem( itemId ) → unknown

    See source

    Returns an item instance with the given itemId.

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

    Parameters

    itemId : string

    The item ID.

    Returns

    unknown

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

  • getItemState( itemId ) → WatchdogState

    See source

    Gets the state of the given item. See state for a list of available states.

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

    Parameters

    itemId : string

    Item ID.

    Returns

    WatchdogState

    The state of the item.

  • inherited

    off( eventName, callback ) → void

    See source

    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.

    Parameters

    eventName : keyof EventMap

    The event name.

    callback : unknown

    A callback which will be removed from event listeners.

    Returns

    void

  • inherited

    on( eventName, callback ) → void

    See source

    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.

    Type parameters

    K : extends keyof EventMap

    Parameters

    eventName : K

    The event name.

    callback : EventCallback<K>

    A callback which will be added to event listeners.

    Returns

    void

  • remove( itemIdOrItemIds ) → Promise<unknown>

    See source

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

    await watchdog.remove( 'editor1' );

    Or

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

    Parameters

    itemIdOrItemIds : ArrayOrItem<string>

    Item ID or an array of item IDs.

    Returns

    Promise<unknown>

  • setCreator( creator ) → void

    See source

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

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

    Parameters

    creator : ( ContextConfig ) => Promise<TContext>

    Returns

    void

  • setDestructor( destructor ) → void

    See source

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

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

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

    Parameters

    destructor : ( Context ) => Promise<unknown>

    Returns

    void

  • internal

    _isErrorComingFromThisItem( error ) → boolean

    See source

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

    Parameters

    error : CKEditorError

    Returns

    boolean

  • protected inherited

    _fire( eventName, args ) → void

    See source

    Fires an event with a given event name and arguments.

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

    Type parameters

    K : extends keyof EventMap

    Parameters

    eventName : K
    args : EventArgs<K>

    Returns

    void

  • protected

    _getWatchdog( itemId ) → Watchdog

    See source

    Returns the watchdog for a given item ID.

    Parameters

    itemId : string

    Item ID.

    Returns

    Watchdog

  • protected

    _restart() → Promise<unknown>

    See source

    Restarts the context watchdog.

    Returns

    Promise<unknown>

  • protected inherited

    _startErrorHandling() → void

    See source

    Starts error handling by attaching global error handlers.

    Returns

    void

  • protected inherited

    _stopErrorHandling() → void

    See source

    Stops error handling by detaching global error handlers.

    Returns

    void

  • private

    _create() → Promise<unknown>

    See source

    Initializes the context watchdog.

    Returns

    Promise<unknown>

  • private

    _destroy() → Promise<unknown>

    See source

    Destroys the context instance and all added items.

    Returns

    Promise<unknown>

Events

  • inherited

    error( eventInfo, <anonymous> )

    See source

    Fired when a new CKEditorError error connected to the watchdog instance occurs and the watchdog will react to it.

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

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    <anonymous> : WatchdogErrorEventData

  • itemError( eventInfo, <anonymous> )

    See source

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

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

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    <anonymous> : ContextWatchdogItemErrorEventData

  • itemRestart( eventInfo, <anonymous> )

    See source

    Fired after an item has been restarted.

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

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    <anonymous> : ContextWatchdogItemRestartEventData

  • restart( eventInfo )

    See source

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

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

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

  • inherited

    stateChange( eventInfo )

    See source

    Fired when the watchdog state changed.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.