Is there a way to insert an event as the first element in the queue of pending events?

[xgirones]

I need it to trigger first a state transition, and then process all the events in the event queue from the target state.

[nsk90]

Hi, no the library does not provide such an option.

https://github.com/nsk90/kstatemachine/blob/897195f421a6fd797eda539fd3f3c4e27883038d/kstatemachine/src/commonMain/kotlin/ru/nsk/kstatemachine/PendingEventHandler.kt#L21

Here is QueuedPendingIntentHendler, maybe you can copy it's implementation and add the required method as a public member.
But I am not sure that it is good design.

Could you provide a code sample of your usecase?
Why you cannot just call processEvent in required order?

[xgirones]

Thanks! I've added a new class deriving from QueuePendingEventHandler with a public method as you suggest and it works quite well!

interface DequeuePendingEventHandler : QueuePendingEventHandler {
    // Hacky method for internal use.
    suspend fun addFirst(eventAndArgument: EventAndArgument<*>)
}

private class DequeuePendingEventHandlerImpl(private val machine: StateMachine) : DequeuePendingEventHandler {
    private val queue = ArrayDeque<EventAndArgument<*>>()

    override suspend fun checkEmpty() = check(queue.isEmpty()) { "Event queue is not empty, internal error" }

    override suspend fun onPendingEvent(eventAndArgument: EventAndArgument<*>) {
        machine.log {
            "$machine queued event ${eventAndArgument.event::class.simpleName} with argument ${eventAndArgument.argument}"
        }
        queue.add(eventAndArgument)
    }

    override suspend fun nextEventAndArgument() = queue.removeFirstOrNull()

    override suspend fun clear() = queue.clear()

    override suspend fun addFirst(eventAndArgument: EventAndArgument<*>) {
        machine.log {
            "$machine inserted first event ${eventAndArgument.event::class.simpleName} with argument ${eventAndArgument.argument}"
        }
        queue.addFirst(eventAndArgument)
    }

fun StateMachine.dequeuePendingEventHandler(): DequeuePendingEventHandler = DequeuePendingEventHandlerImpl(this)
suspend fun StateMachine.forwardEvent(event: Event, argument: Any? = null) =
    (pendingEventHandler as DequeuePendingEventHandler).addFirst(EventAndArgument(event, argument))
}

Then, in the BuildingStateMachine block I set the pendingEventHandler as

pendingEventHandler = dequeuePendingEventHandler() // Allow for hacky event forwarding.

I use the new functionality in this way:

// --------------------------------------------------------------------
// Any event marked as InitializationEvent must be forwarded to the initialization state
transitionOn<CameraPlaygroundStateMachineEvent>("CompositeRunningState.Initialization"){
    guard = {
        event is InitializationEvent
    }
    targetState = { initializationState() }
    onTriggered {
        this@buildRunningState.forwardEvent(it.event, it.argument)
    }
}

I agree that this isn't probably a good design, but helps me to keep all the initialization related code localized in a single state. It would be great if it could be specified in the transition that the event is to be consumed by the target state.

To provide more context on my use case - I am building an Android app with Jetpack Compose. When configuration changes like device rotation occur, I get a sequence of shutdown and initialization events that I prefer to handle in the context of my initialization state.

Thanks again for the quick response and great library!