emitSideEffect method

void emitSideEffect(JEffect effect)

Emits a one-time JEffect to the UI.

This can be used for side effects like showing a dialog, toast, or navigation. Awaitable effects without a listener complete with StateError. Fire-and-forget effects without listeners are dropped, as with a broadcast stream. Emitting after disposal completes the effect with StateError and throws that error synchronously.

With a positive effectBufferSize, an effect emitted while no listener is attached is retained instead, awaitable ones included, and delivered in emission order shortly after the next listener subscribes. Each effect is delivered once, to whoever listens first. When the buffer is full the oldest retained effect is discarded and completed with StateError. Retained awaitable effects stay pending: use a timeout, or disposal, which fails them. Already completed awaitable effects are skipped on delivery. This is meant for effects emitted before the UI attaches, such as from onInit.

Implementation

void emitSideEffect(JEffect effect) {
  if (!mounted) {
    final error = StateError(
      'Cannot emit an effect after controller disposal.',
    );
    _failEffect(effect, error);
    throw error;
  }
  final hasListener = _sideEffectController.hasListener;
  // Keep emission order while earlier effects still wait to be delivered.
  final buffer =
      _effectBufferSize > 0 && (!hasListener || _bufferedEffects.isNotEmpty);
  if (effect is! JFireAndForgetEffect) {
    if (!hasListener && !buffer) {
      _failEffect(effect, _missingListenerError(effect));
      return;
    }
    _trackEffect(effect);
  }
  if (buffer) {
    _bufferEffect(effect);
  } else {
    _sideEffectController.add(effect);
  }
  JObserver.notifyEffectEmitted(effect);
}