Class

ContextWatchdog (watchdog)

@ckeditor/ckeditor5-watchdog/src/contextwatchdog

class

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

    The watched item.

  • readonly

    context : null | Context

    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>

    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

    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>

    The creation method.

  • protected

    _destructor : ( Context ) => Promise<unknown>

    The destruction method.

  • protected

    _watchdogs : Map<string, EditorWatchdog<Editor>>

    A map of internal watchdogs for added items.

  • private

    _actionQueues : ActionQueues

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

  • private

    _context : null | TContext

    The current context instance.

  • private

    _contextConfig : ContextConfig | undefined

    The configuration for the Context.

  • private

    _contextProps : Set<unknown>

    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

    The watchdog configuration.

Methods

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

    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>

    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>

    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>

    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

    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

    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

    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

    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>

    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

    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

    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

    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

    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

    Returns the watchdog for a given item ID.

    Parameters

    itemId : string

    Item ID.

    Returns

    Watchdog
  • protected

    _restart() → Promise<unknown>

    Restarts the context watchdog.

    Returns

    Promise<unknown>
  • protected inherited

    _startErrorHandling() → void

    Starts error handling by attaching global error handlers.

    Returns

    void
  • protected inherited

    _stopErrorHandling() → void

    Stops error handling by detaching global error handlers.

    Returns

    void
  • private

    _create() → Promise<unknown>

    Initializes the context watchdog.

    Returns

    Promise<unknown>
  • private

    _destroy() → Promise<unknown>

    Destroys the context instance and all added items.

    Returns

    Promise<unknown>

Events

  • inherited

    error( eventInfo, <anonymous> )

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

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

    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 )

    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 )

    Fired when the watchdog state changed.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.