Class

Watchdog (watchdog)

@ckeditor/ckeditor5-watchdog/src/watchdog

class

A watchdog for CKEditor 5 editors.

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

Filtering

Properties

  • 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,
  • editor : Editor

    readonly

    The current editor instance.

  • state : 'initializing' | 'ready' | 'crashed' | 'crashedPermanently' | 'destroyed'

    observable

    Specifies the state of the editor handled by the watchdog. The state can be one of the following values:

    • initializing - before the first initialization, and after crashes, before the editor is ready,
    • ready - a state when a user can interact with the editor,
    • crashed - a state when an error occurs - it quickly changes to initializing or crashedPermanently depending on how many and how frequency errors have been caught recently,
    • crashedPermanently - a state when the watchdog stops reacting to errors and keeps the editor crashed,
    • destroyed - a state when the editor is manually destroyed by the user after calling watchdog.destroy()
  • _now

    protected

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

  • _config : Object | undefined

    private

    The editor configuration.

  • _crashNumberLimit : Number

    private

    Related:

  • _creator : function

    private

    The editor creation method.

  • _data : Object.<String, String>

    private

    The latest saved editor data represented as a root name -> root data object.

  • _destructor : function

    private

    The editor destruction method.

  • _editor : Editor

    private

    The current editor instance.

  • _elementOrData : HTMLElement | String | Object.<(String | String)>

    private

    The editor source element or data.

  • _lastDocumentVersion : Number

    private

    The last document version.

  • _minimumNonErrorTimePeriod : Number

    private

    Related:

  • _throttledSave : function

    private

    Throttled save method. The save() method is called the specified saveInterval after throttledSave() is called, unless a new action happens in the meantime.

Methods

  • constructor( [ config ] )

    Parameters

    [ config ] : WatchdogConfig

    The watchdog plugin configuration.

  • _shouldRestartEditor()

    Checks if the editor should be restared or if it should be marked as crashed.

  • create( elementOrData, [ config ] ) → Promise

    Creates a watched editor instance using the creator passed to the setCreator() method or the Watchdog.for() helper.

    Parameters

    elementOrData : HTMLElement | String | Object.<(String | String)>
    [ config ] : EditorConfig

    Returns

    Promise
  • destroy() → Promise

    Destroys the current editor instance by using the destructor passed to the setDestructor() method and sets state to destroyed.

    Returns

    Promise
  • setCreator( creator )

    Sets the function that is responsible for the editor creation. It expects a function that should return a promise.

    watchdog.setCreator( ( element, config ) => ClassicEditor.create( element, config ) );

    Parameters

    creator : function
  • setDestructor( destructor )

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

    watchdog.setDestructor( editor => {
        // Do something before the editor is destroyed.
    
        return editor
            .destroy()
            .then( () => {
                // Do something after the editor is destroyed.
            } );
    } );

    Parameters

    destructor : function
  • _boundErrorHandler()

    private

    Checks if the event error comes from the editor that is handled by the watchdog (by checking the error context) and restarts the editor.

  • _destroy()

    private

    Destroys the current editor instance by using the destructor passed to the setDestructor() method.

  • _getData() → Object.<String, String>

    private

    Returns the editor data.

    Returns

    Object.<String, String>
  • _handleError( error, evt )

    private

    Checks if the error comes from the editor that is handled by the watchdog (by checking the error context) and restarts the editor. It reacts to CKEditorError errors only.

    Parameters

    error : Error

    Error.

    evt : ErrorEvent | PromiseRejectionEvent

    Error event.

    Fires

  • _isErrorComingFromThisEditor( error )

    private

    Traverses both structures to find out whether the error context is connected with the current editor.

    Parameters

    error : CKEditorError
  • _restart() → Promise

    private

    Restarts the editor instance. This method is called whenever an editor error occurs. It fires the restart event and changes the state to initializing.

    Returns

    Promise

    Fires

  • _save()

    private

    Saves the editor data, so it can be restored after the crash even if the data cannot be fetched at the moment of the crash.

  • _shouldReactToError( error )

    private

    Checks whether the error should be handled.

    Parameters

    error : Error

    Error

Static methods

  • for( Editor, [ watchdogConfig ] )

    static

    A shorthand method for creating an instance of the watchdog. For the full usage, see the Watchdog class description.

    Usage:

    const watchdog = Watchdog.for( ClassicEditor );
    
    watchdog.create( elementOrData, config );

    Parameters

    Editor : *

    The editor class.

    [ watchdogConfig ] : WatchdogConfig

    The watchdog plugin configuration.

Events

  • change:state( eventInfo, name, value, oldValue )

    Fired when the state property changed value.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (state).

    value : 'initializing' | 'ready' | 'crashed' | 'crashedPermanently' | 'destroyed'

    New value of the state property with given key or null, if operation should remove property.

    oldValue : 'initializing' | 'ready' | 'crashed' | 'crashedPermanently' | 'destroyed'

    Old value of the state property with given key or null, if property was not set before.

  • error( eventInfo )

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

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

  • restart( eventInfo )

    Fired after the watchdog restarts the error in case of a crash.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.