• Public
  • Public/Protected
  • All

Class ConversationSet

Manage a set of conversations. The conversations usually relate to a single peer.

This class doesn't provide any communication methods itself, it simply tracks the state associated with a conversation.

A conversation can be created with newConversation, which returns a unique ID that can be serialised, and later used to refer to the conversation. Each conversation is associated with a caller-supplied ResponseHandler. The ResponseHandler receives a sequence of callbacks for the conversation according to a well-defined life cycle, allowing it to manage the associated application state.

If respond is called with the ID of an active conversation, the supplied response will be passed to ResponseHandler.onResponse. For every conversation, the response handler will receive an initial ResponseHandler.onOpen call, followed by one or more onResponse calls. If onResponse returns true, the conversation will be closed normally and no further calls will be made to the handler for that conversation. Returning true from onResponse is the only way to close a conversation normally (rather than discard it). This places the onus on the handler to determine when the conversation finishes normally, based on the received message and/or its own state.

A conversation can be 'discarded' to close it in an abnormal fashion. discardAll discards all of the conversations owned by this conversation set. Once called, this conversation set enters a 'discarded' state, and new conversations will be discarded immediately after they are opened. Individual conversations can be discarded with discard. Whichever method is used to discard a conversation, ResponseHandler.onDiscard will be the final call to the handler for that conversation.

Finally, if ResponseHandler.onOpen or ResponseHandler.onResponse throws an exception, the conversation will complete exceptionally. The exception is logged at debug level and re-thrown.

The ways a conversation can close are summarised in the following table.

Cause Close type How close is reported
`ResponseHandler.onResponse()` returns true Closed normally Not reported
`ResponseHandler.onOpen()` throws exception Closed exceptionally Exception is re-thrown to caller of `newConversation()`.
Debug log message
`ResponseHandler.onResponse()` throws exception Closed exceptionally Exception is re-thrown to caller of `respond()`.
Debug log message
Discarded `ResponseHandler.onDiscard()` is called.


  • ConversationSet




  • Create a conversation set


    • idGenerator: IdGenerator

      the generator function for conversation ID

    Returns ConversationSet


Private conversations

conversations: object

An object that contains conversation indexed by their conversation ID

Type declaration

Private Optional discardReason

discardReason: any

If defined, the reason for discarding a conversation

Private nextCID

nextCID: IdGenerator

The generator function for conversation ID


Private completedExceptionally

  • Complete a conversation exceptionally.


    Returns void


  • Discard the specified conversation.

    This method will discard the conversation specified by the provided ID, notifying the corresponding handler's ResponseHandler.onDiscard method.

    Subsequent calls to this method have no effect.

    If there is no conversation with the given id, this method has no effect.


    • cid: ConversationId

      the conversation ID to discard

    • reason: any

      why the conversation was discarded

    Returns void


  • discardAll(reason: any): void
  • Discard all conversations in this set.

    When this method returns, all current conversations will have been discarded, notifying their corresponding handlers, and new conversations will be discarded immediately. Calling newConversation will immediately call the supplied handler's ResponseHandler.onDiscard.

    Subsequent calls to this method have no effect.


    • reason: any

      why the conversation set was discarded

    Returns void


  • Open a new conversation.


    Returns Promise<ConversationId>

    the ID that can be used to refer to the conversation.


  • Notify the handler of a response.


    an error if the conversation is not found


    Returns void


  • Variant of respond that does nothing if there is no open conversation with the given ID.


    Returns void


  • size(): number
  • Get the size of the conversation set

    Returns number

    the number of conversations that have been created and not discarded