Class

Watchdog (watchdog)

@ckeditor/ckeditor5-watchdog/src/watchdog

class internal

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

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

Filtering

Properties

  • readonly

    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,
  • 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().
  • internal readonly

    _item : unknown

    The watched item.

  • private

    _boundErrorHandler : ( ErrorEvent | PromiseRejectionEvent ) => void

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

  • private

    _crashNumberLimit : number

  • private

    _listeners : Record<string, Array<( any ) => void>>

    A dictionary of event emitter listeners.

  • private

    _minimumNonErrorTimePeriod : number

  • private

    _now : () => number

    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.

Methods

  • constructor( config )

    Parameters

    config : WatchdogConfig

    The watchdog plugin configuration.

  • destroy() → void

    Destroys the watchdog and releases the resources.

    Returns

    void
  • 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
  • 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
  • internal

    _isErrorComingFromThisItem( error ) → boolean

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

    Parameters

    error : CKEditorError

    Returns

    boolean
  • protected

    _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

    _restart() → Promise<unknown>

    The method responsible for restarting the watched item.

    Returns

    Promise<unknown>
  • protected

    _startErrorHandling() → void

    Starts error handling by attaching global error handlers.

    Returns

    void
  • protected

    _stopErrorHandling() → void

    Stops error handling by detaching global error handlers.

    Returns

    void
  • private

    _handleError( error, evt ) → void

    Checks if an error comes from the watched item and restarts it. It reacts to CKEditorError errors only.

    Parameters

    error : Error

    Error.

    evt : ErrorEvent | PromiseRejectionEvent

    An error event.

    Returns

    void

    Fires

  • private

    _shouldReactToError( error ) → boolean

    Checks whether an error should be handled by the watchdog.

    Parameters

    error : Error

    An error that was caught by the error handling process.

    Returns

    boolean
  • private

    _shouldRestart() → boolean

    Checks if the watchdog should restart the underlying item.

    Returns

    boolean

Events

  • 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
  • stateChange( eventInfo )

    Fired when the watchdog state changed.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.