Forem: Guim

Flutter Dependency Inversion (programming to an interface)

Guim — Mon, 11 May 2026 08:04:00 +0000

Dependency Inversion is the practice of programming to an interface rather than a concrete implementation. In a standard approach, your business logic depends directly on specific tools or SDKs, making the code rigid and difficult to test. With Dependency Inversion, you define a "contract" (an interface) that describes what a service should do, and your application only interacts with that contract.

The Problem

Rigid Coupling: Your code is smeared with third-party SDKs. Swapping Firebase for Amplitude or Mixpanel requires editing every file that touches analytics.
Untestable Logic: Unit tests fail because they require a real Firebase instance to be initialized. You end up skipping tests or wasting hours on complex mocks.
No Substitutability: You can’t easily provide "Console Logging" for development and "Real SDKs" for production without if (kDebugMode) checks everywhere.

The Pattern — SOLID's "D"

High-level modules (your business logic) should not depend on low-level modules (the SDKs). Both should depend on abstractions (interfaces).

Domain Layer: Owns the interface (the "contract").
Infrastructure Layer: Implements the contract (the "details").
Application Layer: Wires it all together (via Riverpod in this example).

Implementation Guide

1. Define the Contract (Domain)

We use abstract interface class so consumers can only implements the contract — they can't extends it and inherit partial behavior. This keeps the contract pure: every method must be explicitly fulfilled.

Use Domain Primitives: Never leak third-party types (like a RevenueCat Package) through your interface. Use double, String, or your own domain entities.

abstract interface class IAnalytics {
  Future<void> logEvent({
    required String name,
    Map<String, Object>? properties,
  });

  Future<void> logPurchase({
    required String productId,
    required double amount,
    required String currencyCode,
  });
}

2. Create the Strategies (Infrastructure)

Create a Production version that talks to real SDKs and a Development version that simply logs to the console.

// Production: Wires up Firebase + Facebook
class ProductionAnalytics implements IAnalytics {
  final FirebaseAnalytics _firebase;
  ProductionAnalytics({FirebaseAnalytics? firebase})
    : _firebase = firebase ?? FirebaseAnalytics.instance;

  @override
  Future<void> logEvent({required String name, Map<String, Object>? properties}) =>
      _firebase.logEvent(name: name, parameters: properties);

  // ... other methods
}

// Development: Zero SDK dependencies, prints to console
class DevelopmentAnalytics implements IAnalytics {
  @override
  Future<void> logEvent({required String name, Map<String, Object>? properties}) async =>
      print('[Analytics] $name: $properties');
}

3. The Composition Root (Riverpod)

The provider acts as the single decision point for which implementation to use.

final analyticsProvider = Provider<IAnalytics>((ref) {
  // kDebugMode is a compile-time constant.
  // The unused branch is physically tree-shaken from your release binary!
  if (kDebugMode) {
    return DevelopmentAnalytics();
  }
  return ProductionAnalytics();
});

Why This Matters

Tree-Shaking: Because kDebugMode is a constant, DevelopmentAnalytics doesn't even exist in your production APK/IPA.
Instant Mocking: In your tests, simply override the provider with a TestAnalytics spy to verify logic without network calls.
Clean Boundaries: Your feature developers can track events without ever knowing (or caring) that Firebase is under the hood.

Flutter Actions (mutations)

Guim — Sun, 10 May 2026 18:01:00 +0000

One-shot operations as first-class state, with declarative listeners.

The Problem

Async operations triggered by the user (button taps, form submits) don't fit AsyncValue cleanly:

No idle state. AsyncValue starts in loading. But a login screen isn't loading until the user taps the button — it's idle. Forcing it into AsyncValue.data(null) is a lie that leaks into your UI logic.
Imperative side effects belong outside build. You want to navigate on success and show a toast on error. Doing that with ref.listen + a manual switch on AsyncValue is verbose and easy to get wrong (you'll forget the previous == next guard at least once).
Try/catch in widgets. Without a primitive, every submit handler ends up with try { await ... } catch (e) { showToast(e) } inline — which mixes domain errors with UI concerns and makes the widget untestable.
Double-submission. A button tapped twice fires the operation twice. Every action needs the same guard, and re-implementing it per-screen is how bugs ship.

The Pattern

An Action has three parts:

ActionState<T> — a sealed union: idle | loading | success(T) | error(Exception, StackTrace). The current state of the operation.
ActionHandler<T> — a Riverpod notifier mixin that runs the operation, manages the state transitions, and guards against double-submission.
listenAction — a WidgetRef extension that subscribes to lifecycle callbacks declaratively from inside build.

The widget watches the state for rendering (spinner, disabled button) and listens to the state for side effects (navigation, toasts). Same provider, two consumption styles.

Implementation Guide

1. The State (Sealed Union)

sealed class ActionState<T> {
  const ActionState();

  const factory ActionState.idle() = ActionIdle<T>;
  const factory ActionState.loading() = ActionLoading<T>;
  const factory ActionState.success(T value) = ActionSuccess<T>;
  const factory ActionState.error(Exception error, StackTrace stack) = ActionError<T>;

  bool get isIdle    => this is ActionIdle;
  bool get isLoading => this is ActionLoading;
  bool get isSuccess => this is ActionSuccess;
  bool get isError   => this is ActionError;
}

class ActionIdle<T>    extends ActionState<T> { const ActionIdle(); }
class ActionLoading<T> extends ActionState<T> { const ActionLoading(); }
class ActionSuccess<T> extends ActionState<T> { const ActionSuccess(this.data); final T data; }
class ActionError<T>   extends ActionState<T> {
  const ActionError(this.error, this.stackTrace);
  final Exception error;
  final StackTrace stackTrace;
}

The is* getters are the entire reason this exists. From a widget you can ask state.isLoading without pattern-matching every state.

2. The Handler (The Notifier Mixin)

ActionHandler wraps the operation in three guarantees: don't run twice, transition through loading, never throw.

mixin ActionHandler<T> on AutoDisposeNotifier<ActionState<T>> {
  Future<void> execute(Future<T> Function() fn) async {
    if (state.isLoading) return;       // double-submission guard

    state = const ActionLoading();
    state = await ActionState.guard(fn);
  }
}

ActionState.guard is a try/catch that converts a Future<T> into an ActionState<T> — success on completion, error on throw. The handler never rethrows: errors land in the state, where listeners can react.

3. The Action Provider

A real action — login — looks like this. It's a regular notifier that mixes in ActionHandler and exposes run(...) as the public entry point.

final loginActionProvider =
    NotifierProvider.autoDispose<LoginAction, ActionState<void>>(
  LoginAction.new,
  name: 'loginAction',
);

class LoginAction extends AutoDisposeNotifier<ActionState<void>>
    with ActionHandler<void> {
  @override
  ActionState<void> build() => const ActionIdle();

  Future<void> run({required String email, required String password}) =>
      execute(() async {
        final jwt = await ref.read(authRepository).login(
          email: Email(email),
          password: password,
        );
        ref.read(eventBusProvider).publish(UserLoggedIn(jwt));
      });
}

Pair Actions with the In-Process Domain Event Bus. The action handles the operation; the bus handles the consequences (analytics, profile sync, notifications). The action stays tiny and the side effects stay testable.

4. Consuming from the UI

The widget has two jobs: render the current state and react to transitions.

@override
Widget build(BuildContext context) {
  final isLoading = ref.watch(loginActionProvider).isLoading;

  ref.listenAction(
    loginActionProvider,
    onSuccess: (_) => context.go(HomeRoute.routePath),
    onError: (error, _) => context.showErrorToast(error),
  );

  return CustomButton(
    isLoading: isLoading,
    onPressed: () => ref.read(loginActionProvider.notifier).run(
      email: _email,
      password: _password,
    ),
    child: Text(context.l10n.loginSubmit),
  );
}

That's the whole API. watch for rendering, listenAction for side effects, read(...).run(...) to fire it.

5. The Listener Extension

extension ActionNotifierX on WidgetRef {
  void listenAction<T>(
    ProviderListenable<ActionState<T>> provider, {
    void Function(T data)? onSuccess,
    void Function(Exception error, StackTrace stack)? onError,
    void Function()? onLoading,
  }) {
    listen<ActionState<T>>(provider, (_, next) {
      switch (next) {
        case ActionLoading():            onLoading?.call();
        case ActionSuccess(:final data): onSuccess?.call(data);
        case ActionError(:final error, :final stackTrace):
          onError?.call(error, stackTrace);
        case ActionIdle(): break;
      }
    });
  }
}

Each callback is optional — most screens only need onError. The exhaustive switch over the sealed union means adding a new state at the type level forces every call site to handle it.

Why This Matters

Idle is real. Forms render correctly before the user has done anything. No fake loading: false, data: null checks.
No try/catch in widgets. Errors flow through the state and surface in onError. Domain errors stay in the domain layer.
Free double-tap protection. if (state.isLoading) return in the mixin means every action is debounced by construction.
Tree-shaped lifecycle. Side effects are declared at the top of build next to the state they depend on, not buried inside callbacks.
Testable. Override the provider with loginActionProvider.overrideWith(...) and pump states (idle → loading → error) to assert UI behavior.

Trade-offs to Consider

Not for queries. Actions are one-shot, user-initiated, and write-flavored. For server data that should auto-fetch and cache, use FutureProvider / AsyncNotifier — that's what AsyncValue is for.
One operation per provider. A UserAction with login(), logout(), and deleteAccount() methods sharing one state is a smell — they'd stomp on each other. Make them separate providers.
Result lifetime is short. With autoDispose, the success value lives only as long as the screen. If you need to persist the result (e.g. the JWT from login), publish it to a domain event or write it to a repository inside the action — don't read it from the action's state later.

Flutter Outbox Pattern

Guim — Thu, 07 May 2026 11:06:00 +0000

Persistent, idempotent retries for writes that absolutely must reach the server.

The Problem

Some writes are not allowed to fail silently:

The user just paid for something and you need to tell the server.
The user just sent a message in a chat that needs to actually reach the recipient.
The user just completed an exercise / lesson / quest, and the streak counter on the home screen would be lying if the server didn't get the update.
The user just submitted a form that triggers a downstream process you cannot recover from manually.

The naive shape of these flows looks like this:

// ❌ Naive write
Future<void> completeOrder(Cart cart) async {
  state = const ActionLoading();
  try {
    await _api.submitOrder(cart);
    state = const ActionSuccess();
  } on Exception catch (e, s) {
    state = ActionError(e, s);
  }
}

Every one of these scenarios will eventually break it:

Spotty connectivity. The user is on a train, in a tunnel, in an elevator. Their tap lands in the dead seconds between two cell towers. The button shows a red toast. They give up, or worse, they tap again — five seconds later — and now you have a duplicate write.
App killed mid-request. The OS evicted the process while the request was in flight. You have no idea whether the server received it. There is no retry; there isn't even a record that an attempt happened.
Transient 5xx / 502 from the load balancer. Common, expected, recoverable — and yet your app surfaces it to the user as if the order failed permanently.
Auth token expired mid-flight. Refresh-on-401 is a separate concern, but a write that hits a 401 should not be lost while the refresh happens; it should be retried after.
The user is offline by design. Modern apps are expected to record state locally and reconcile when the network returns. Without an outbox, your "offline support" is just "the screen renders without crashing."

A more elaborate fix — wrap the call in retry() with exponential backoff — addresses one of these (transient 5xx) and none of the others. A retry loop dies with the process. A retry loop doesn't survive being killed for memory pressure. A retry loop doesn't help when the user closes the app and reopens it three hours later on a different network.

The Pattern

The outbox separates the intent of a write from the act of performing it.

Action. A small, serializable value object describing what should happen (e.g. SendMessage, CompleteOrder). It carries an idempotency key (id), a discriminator (type), a creation timestamp, and a JSON payload.
Record. The persisted form of an action — what's actually written to disk. Identical fields plus an attemptCount. The repository deals only in records, never in feature-specific action subclasses.
Repository. A persistence interface (add / getAll / remove / incrementAttempts / clear) backed by anything durable: SharedPreferences, Hive, sqflite, the filesystem. Survives process death.
Handler. Per-feature code that knows how to replay one action type. Owns deserialization of the payload and decides whether to retry, give up, or remove the record.
Dispatcher. A dumb iterator. Reads pending records, looks up the handler for each type, calls it, catches whatever it throws. Coalesces concurrent flushes behind a single in-flight future.
Triggers. UI-layer hooks that fire dispatcher.flush() on cold start, on connectivity restored, on app resumed, and right after enqueue.

The producer and the consumer are decoupled. The feature that enqueues the action does not import the dispatcher; the dispatcher does not import any feature. The only shared types live in core/outbox/domain/.

┌──────────────┐   add()    ┌──────────────┐    flush()   ┌──────────────┐
│   Feature    ├───────────▶│  Repository  │◀─────────────┤  Dispatcher  │
│  (enqueues)  │            │  (durable)   │              │  (iterates)  │
└──────────────┘            └──────────────┘              └──────┬───────┘
                                                                 │ handle(record)
                                                                 ▼
                                                         ┌──────────────┐
                                                         │   Handler    │
                                                         │ (per-feature)│
                                                         └──────────────┘

Implementation Guide

1. The Action (Domain)

The base class is generic. It has no idea what any concrete action does — it just defines the contract every action must fulfill so the repository can persist it.

abstract class OutboxAction {
  const OutboxAction();

  /// Unique identifier for this action. Reused as the `Idempotency-Key`
  /// HTTP header so the server can dedupe retries of the same logical write.
  String get id;

  /// Discriminator used by the dispatcher to route this action to its
  /// handler. Must match the corresponding `OutboxHandler.type`.
  String get type;

  /// When the action was first enqueued. Used by handlers as the basis for
  /// "older than N days → drop" safety valves.
  DateTime get createdAt;

  /// Feature-defined JSON payload. The handler for [type] is the only code
  /// that ever interprets this map.
  Map<String, dynamic> toPayload();
}

A concrete action lives next to the feature that owns it. For a chat app:

class SendMessageAction extends OutboxAction {
  const SendMessageAction({
    required this.id,
    required this.conversationId,
    required this.body,
    required this.createdAt,
  });

  @override
  final String id;
  @override
  final DateTime createdAt;

  final String conversationId;
  final String body;

  @override
  String get type => 'send_message';

  @override
  Map<String, dynamic> toPayload() => {
        'conversation_id': conversationId,
        'body': body,
      };
}

Generate id client-side. Use Uuid().v4() or a ULID. The same id becomes the Idempotency-Key HTTP header when the handler eventually fires the request. If two retries hit the server, the second one is a no-op because the server recognizes the key. You don't need a dedupe table on the client — the server does it for you.

2. The Record (Wire/Storage Form)

The repository never sees SendMessageAction. It sees a record — strings and a JSON map — so the core layer can store and replay actions from any feature without importing feature code.

class OutboxRecord {
  const OutboxRecord({
    required this.id,
    required this.type,
    required this.payload,
    required this.createdAt,
    required this.attemptCount,
  });

  final String id;
  final String type;
  final Map<String, dynamic> payload;
  final DateTime createdAt;
  final int attemptCount;

  OutboxRecord copyWith({int? attemptCount}) => OutboxRecord(
        id: id,
        type: type,
        payload: payload,
        createdAt: createdAt,
        attemptCount: attemptCount ?? this.attemptCount,
      );

  Map<String, dynamic> toJson() => {
        'id': id,
        'type': type,
        'payload': payload,
        'created_at': createdAt.toUtc().toIso8601String(),
        'attempt_count': attemptCount,
      };

  factory OutboxRecord.fromJson(Map<String, dynamic> json) => OutboxRecord(
        id: json['id'] as String,
        type: json['type'] as String,
        payload: Map<String, dynamic>.from(json['payload'] as Map),
        createdAt: DateTime.parse(json['created_at'] as String).toUtc(),
        attemptCount: json['attempt_count'] as int? ?? 0,
      );
}

3. The Repository (Domain Interface)

abstract interface class IOutboxRepository {
  /// Enqueue an action. If an entry with the same id already exists it is
  /// replaced (idempotent enqueue).
  Future<void> add(OutboxAction action);

  /// All pending records, oldest first (FIFO).
  Future<List<OutboxRecord>> getAll();

  /// Remove the record with the given id. No-op if it does not exist.
  Future<void> remove(String id);

  /// Increment the attempt counter on the record with the given id.
  Future<void> incrementAttempts(String id);

  /// Wipe all records. Called on logout.
  Future<void> clear();
}

A SharedPreferences implementation is fine for the typical case — most apps queue 0 or 1 entries at a time, and reading/rewriting a tiny JSON array on every mutation is faster than spinning up a database. Scope the storage key by user id: a queue belongs to the account that produced it.

class SharedPreferencesOutboxRepository implements IOutboxRepository {
  SharedPreferencesOutboxRepository(this._prefs, this._currentUserId);

  final SharedPreferences _prefs;
  final String? Function() _currentUserId;

  String? get _key {
    final userId = _currentUserId();
    return userId == null ? null : 'outbox:$userId';
  }

  Future<List<OutboxRecord>> _readAll() async {
    final key = _key;
    if (key == null) return [];

    final raw = _prefs.getStringList(key) ?? const [];
    final records = <OutboxRecord>[];
    for (final entry in raw) {
      try {
        records.add(OutboxRecord.fromJson(jsonDecode(entry) as Map<String, dynamic>));
      } on Exception {
        // A corrupt entry must not poison the whole queue. Drop it.
      }
    }
    return records;
  }

  Future<void> _writeAll(String key, List<OutboxRecord> records) =>
      _prefs.setStringList(key, records.map((r) => jsonEncode(r.toJson())).toList());

  @override
  Future<void> add(OutboxAction action) async {
    final key = _key;
    if (key == null) throw StateError('Cannot enqueue without a logged-in user');

    final records = await _readAll()
      ..removeWhere((r) => r.id == action.id)
      ..add(OutboxRecord(
        id: action.id,
        type: action.type,
        payload: action.toPayload(),
        createdAt: action.createdAt,
        attemptCount: 0,
      ));
    await _writeAll(key, records);
  }

  // remove / incrementAttempts / clear / getAll — see full source.
}

Per-user scoping is not optional. If user A enqueues a write, then logs out and user B logs in on the same device, user B must not see (let alone replay) user A's queue. Either key by userId as shown above, or call clear() from your logout flow.

4. The Handler (Per-Feature)

This is the only place that knows what an action means. It owns deserialization, the HTTP call, and the give-up logic.

abstract class OutboxHandler {
  const OutboxHandler();

  /// Discriminator that matches `OutboxAction.type` / `OutboxRecord.type`.
  String get type;

  Future<void> handle(OutboxRecord record);
}

The error contract is the most important part of the whole pattern, and it's worth being explicit:

Outcome	Examples	What the handler does
Success	`200`, `201`, `204`	Remove record, return normally
Permanent failure	`400`, `404`, `409`, `422`	Log, remove record, return normally
Transient failure	Offline, `5xx`, timeout, `401`	Throw / rethrow — the dispatcher will retry

A concrete handler:

class SendMessageOutboxHandler extends OutboxHandler {
  SendMessageOutboxHandler({
    required this.api,
    required this.repository,
  });

  final ChatApi api;
  final IOutboxRepository repository;

  @override
  String get type => 'send_message';

  @override
  Future<void> handle(OutboxRecord record) async {
    // Safety valve: drop records that have been stuck for too long.
    if (DateTime.now().toUtc().difference(record.createdAt) > const Duration(days: 7)) {
      await repository.remove(record.id);
      return;
    }

    final conversationId = record.payload['conversation_id'] as String;
    final body = record.payload['body'] as String;

    try {
      await api.sendMessage(
        conversationId: conversationId,
        body: body,
        idempotencyKey: record.id, // 🔑 server dedupes on this
      );
      await repository.remove(record.id);
    } on ApiException catch (e) {
      if (e.isPermanent) {
        // 4xx (other than 401/408/429) — never going to succeed. Drop it.
        await repository.remove(record.id);
        return;
      }
      rethrow; // transient — let the dispatcher count the attempt and retry.
    }
  }
}

The handler — not the dispatcher — decides what counts as permanent. Different features have different rules: a 409 Conflict on "create resource" might mean "already exists, success"; a 409 on "complete checkout" might mean "drop, the user already paid." The dispatcher cannot possibly know which is which, so it doesn't try.

5. The Dispatcher

The dispatcher is intentionally dumb. It reads, routes, catches, increments. That's it.

class OutboxDispatcher {
  OutboxDispatcher({
    required IOutboxRepository repository,
    required List<OutboxHandler> handlers,
  })  : _repository = repository,
        _handlersByType = {for (final h in handlers) h.type: h};

  final IOutboxRepository _repository;
  final Map<String, OutboxHandler> _handlersByType;

  Future<void>? _inFlight;

  /// Triggers a flush. Concurrent callers receive the same future — at most
  /// one flush runs at a time.
  Future<void> flush() {
    return _inFlight ??= _doFlush().whenComplete(() => _inFlight = null);
  }

  Future<void> _doFlush() async {
    final records = await _repository.getAll();
    if (records.isEmpty) return;

    for (final record in records) {
      final handler = _handlersByType[record.type];
      if (handler == null) {
        // No handler registered (feature was removed?). Skip — don't crash.
        continue;
      }

      try {
        await handler.handle(record);
      } on Exception {
        // Transient failure: leave the record, count the attempt, move on.
        await _repository.incrementAttempts(record.id);
      }
    }
  }
}

Coalesce concurrent flushes. Without the in-flight mutex, a single connectivity-restored event arriving while the dispatcher is already working would cause every record to be replayed twice in parallel. Even with idempotency keys, that's wasteful at best and racy at worst (two concurrent remove calls). The _inFlight future is the simplest fix that works.

6. The Triggers

A flush should happen on every plausible "now would be a good time to retry" signal. The naive list is short:

App start (cold or warm) — drain anything stuck from the last session.
Connectivity restored — go from offline → online and the queue should drain.
App resumed — the user came back to the app; their attention is here, so should the work be.
Right after enqueue — the happy path. The user just tapped the button, the network is probably up, fire it now.

A small Flutter widget mounted at the router shell handles the first three:

class OutboxFlushTrigger extends ConsumerStatefulWidget {
  const OutboxFlushTrigger({required this.child, super.key});
  final Widget child;

  @override
  ConsumerState<OutboxFlushTrigger> createState() => _OutboxFlushTriggerState();
}

class _OutboxFlushTriggerState extends ConsumerState<OutboxFlushTrigger>
    with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    WidgetsBinding.instance.addPostFrameCallback((_) => _flush());
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.resumed) _flush();
  }

  void _flush() => ref.read(outboxDispatcherProvider).flush();

  @override
  Widget build(BuildContext context) {
    ref.listen<AsyncValue<bool>>(connectivityStatusProvider, (prev, next) {
      final wasOnline = prev?.value ?? false;
      final isOnline = next.value ?? false;
      if (!wasOnline && isOnline) _flush();
    });
    return widget.child;
  }
}

The fourth trigger — fire-on-enqueue — lives in the feature itself, typically inside the Action that produced the record:

class SendMessageAction extends AutoDisposeNotifier<ActionState<void>>
    with ActionHandler<void> {
  @override
  ActionState<void> build() => const ActionIdle();

  Future<void> run({required String conversationId, required String body}) =>
      execute(() async {
        final action = SendMessageOutboxAction(
          id: const Uuid().v4(),
          conversationId: conversationId,
          body: body,
          createdAt: DateTime.now().toUtc(),
        );

        // 1. Persist intent. This is the commit point.
        await ref.read(outboxRepositoryProvider).add(action);

        // 2. Update local state immediately so the UI feels instant.
        ref.read(eventBusProvider).publish(MessageQueued(action));

        // 3. Best-effort: try the network now. If it fails, the dispatcher
        //    will pick the record up on the next trigger.
        await ref.read(outboxDispatcherProvider).flush();
      });
}

The user sees their message in the conversation immediately (step 2), regardless of whether the network call succeeds. From their perspective, sending is instantaneous — a property you cannot get from a naive write.

7. Composition Root (Riverpod)

final outboxRepositoryProvider = Provider<IOutboxRepository>((ref) {
  return SharedPreferencesOutboxRepository(
    ref.read(sharedPreferencesProvider),
    () => ref.read(currentUserIdProvider),
  );
}, name: 'outboxRepository');

final outboxHandlersProvider = Provider<List<OutboxHandler>>((ref) => [
      ref.watch(sendMessageOutboxHandlerProvider),
      ref.watch(completeOrderOutboxHandlerProvider),
      // Add new handlers here.
    ], name: 'outboxHandlers');

final outboxDispatcherProvider = Provider<OutboxDispatcher>((ref) {
  return OutboxDispatcher(
    repository: ref.read(outboxRepositoryProvider),
    handlers: ref.read(outboxHandlersProvider),
  );
}, name: 'outboxDispatcher');

The handler list is intentionally explicit. Adding a new outbox-backed action means touching this file — that's the trade-off for a statically-known, easily-tested set of participants.

Why This Matters

For offline-first architectures

An outbox is the offline write story. Without it, "offline support" usually means "the screen renders cached data" — which is the read side. Writes require durability, and durability requires a queue.

The user's intent survives any failure mode. Process kill, OS upgrade, dead battery, plane mode — the record is on disk before the request fires. Whatever happens to the network or the process, the next launch will re-attempt.
Optimistic UI is safe. You can update local state the instant the action is enqueued because you know the server will hear about it eventually. Without an outbox, optimistic updates are a lie that gets caught the moment the user looks at another device.
Reconciliation is centralized. All your "what's stuck and should we retry it?" logic lives in one place. Every feature gets it for free instead of reinventing per-screen retry loops with their own subtly-different semantics.

For high-stakes writes

Even an online-only app benefits from the outbox for the writes you cannot afford to lose:

Payments and purchases. "We charged your card but didn't record it" is a class of bug that bankrupts trust. The outbox guarantees the record outlives the network call.
Anti-cheat / progress writes. A user who lost their streak because the server didn't get the "completed" event will not stay a user for long. Idempotent retries fix this without server changes.
Sequenced writes. Some flows have a strict order — "submit form, then upload attachments." Encoding that as two outbox actions (with the second waiting on the first to complete) gives you durable ordering for free.
Crash safety. Even on a perfect network, the OS can kill your app between "send request" and "see response." Without an outbox, that window is a hole. With one, you simply re-attempt the next time the app is opened.

Architectural benefits

The dispatcher is dumb. Per-feature give-up logic stays in the handler, where it belongs. The core layer never grows feature-specific branches.
Features stay decoupled. A new feature wanting offline-safe writes implements one handler and registers it. Nothing in the core has to change.
Testable in isolation. Each handler is a unit test (given a record with payload X, the API was called with Y, and the record was removed). The dispatcher is also a unit test (given two pending records, both handlers were invoked). The repository swaps for an in-memory fake.

Trade-offs to Consider

Eventual consistency. The user's local view (optimistic) and the server's view diverge for a window of time. If a permanent failure later discards the record, you owe the user a "we couldn't send this" message and a way to undo or retry. Don't pretend everything is fine forever.
Idempotency is a server contract. This pattern requires your backend to honor Idempotency-Key (or an equivalent client_request_id field). If duplicate retries cause duplicate side effects on the server, the entire "at-least-once" model collapses into "at-least-once means at-least-twice." Coordinate with your backend team before adopting.
Not for reads. The outbox is write-only. For caching server data, use a normal repository with a stale-while-revalidate strategy.
Not for huge payloads. A multi-megabyte file upload doesn't belong in SharedPreferences. Either store the file path and stream from disk in the handler, or use a real database with blob support.
Ordering is FIFO per queue, not per resource. If you need strict ordering across two different action types (e.g. "create resource" then "update it"), encode the ordering inside one of the handlers — don't rely on the order the dispatcher iterates.
Storage growth requires a safety valve. A stuck record (a 5xx that never resolves, a server bug that returns transient errors forever) will accumulate attemptCount indefinitely. Drop records older than N days, or after M attempts, in the handler. Otherwise, you get a queue that never drains.

Pair with Actions and the Domain Event Bus. The Action handles the user-facing operation. The outbox makes that operation durable. The event bus tells the rest of the app it happened. The three patterns compose: Action.run() → outbox.add() → eventBus.publish(...) → dispatcher.flush(). Each layer does one thing, and "the message I just sent" is reliably reflected in every screen that cares.

Lazy Load Images with Vanilla Javascript

Guim — Mon, 06 May 2019 21:00:29 +0000

What is Lazy Loading?

Surely many of you have already heard that Google Chrome is going to add Lazy Loading in a native way with HTML tags, for images and iframes.

What Lazy Loading basically means is not to load the content of these images until the user does not have them in the field of view. In this way, an image located at the end of the web page will never be loaded if the user does not reach that point. With this solution, we save loading time and gain speed.

In this tutorial we'll lazy load 30 images, previously fetched from an API. First, we'll write the HTML, then the JS code and finally we'll implement some basic CSS to have a beautiful result. Here you have a demo:

Our HTML skeleton

This is our index.html file. It just has a title, a loading spinner and an empty div where we'll put all the images from the API.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Lazy Loading Images</title>

    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
    <h1>Lazy Loading Images</h1>

    <!-- Images Container -->
    <div id="imagesContainer"></div>

    <!-- Loading spinner -->
    <div class="lds-roller" id="lds-roller">
      <div></div>
      <div></div>
      <div></div>
      <div></div>
      <div></div>
      <div></div>
      <div></div>
      <div></div>
    </div>

    <!-- Our custom JS code -->
    <script src="main.js"></script>
  </body>
</html>

At this point, our page is empty. Let's create our main.js file, grab some images and lazy load them.

Here is where the magic happens

As this file will be more complex, let's split the code into smaller parts so we can deeply understand each of them. All of the following code it's written in the main.js file.

window.onload = () => {
  // Get 30 random images
  fetch('https://picsum.photos/v2/list?limit=30')
    .then(function(response) {
      return response.json();
    })
    .then(function(myJson) {
      // Call the createImages function to generate the HTML code
      createImages(myJson);
      // Remove the loading spinner
      document.getElementById('lds-roller').remove();
    })
    .catch(err => {
      console.log(err);
    });
};

This first function will be triggered ones the window is ready. We use the fetch API to get the images from an external API. This API response us with a JSON file containing all the url's to the images. With this url's we can now create our HTML code.

function createImages(imgs) {
  for (let i of imgs) {
    // Create an image HTML tag
    const image = document.createElement('img');
    image.setAttribute('data-lazy', i.download_url);
    image.classList.add('lazy-loading');
    document.getElementById('imagesContainer').appendChild(image);
  }
  // Sets an observer for each image
  lazyTargets = document.querySelectorAll('.lazy-loading');
  lazyTargets.forEach(lazyLoad);
}

Note that we're not setting the src attribute of the images. We're creating a data-lazy one. This way, the images don't request any data when they are created. Now let's do the lazy-loading function. This function will use the intersection observer API to know when each image is on the view. Then it'll replace the src attribute with the data-lazy one.

function lazyLoad(target) {
  const obs = new IntersectionObserver((entries, observer) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        const img = entry.target;
        const src = img.getAttribute('data-lazy');

        img.setAttribute('src', src);
        img.classList.add('fadeIn');

        observer.disconnect();
      }
    });
  });
  obs.observe(target);
}

Let's make it pretty

Now I've put some basic CSS to make things prettier. The file referenced in the HTML is style.css.

html,
body {
  margin: 0;
  padding: 0;
  width: 100%;
}

h1 {
  text-align: center;
  font-family: sans-serif;
  font-weight: 200;
}

#imagesContainer {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  margin: auto;
  width: 680px;
}

#imagesContainer img {
  width: 300px;
  min-height: 200px;
  margin: 20px;
  box-shadow: 5px 10px 15px;
}

@keyframes fadeIn {
  from {
    opacity: 0;
  }

  to {
    opacity: 1;
  }
}

.fadeIn {
  animation-name: fadeIn;
  animation-duration: 3s;
}

So that's all! Here's the link of CodePen. See you soon!

My React components repository

Guim — Mon, 11 Mar 2019 09:00:44 +0000

Hey there, I just uploaded a Github repository in which I'll be uploading some of the React components I use the most. Most of them are made by me, others from Internet code but with own modifications.

Go to the repo!

The components

Here you have a complete list of all the components. As I upload new components I will update the list.

Navbar: Sticky navbar that hides when scrolling down.
Loading Indicator: Loading indicator with only CSS.
Flipping Cards: Cards that flip when click.

Usage

You can browse this repo online or download it and run it to see a live demo of all of the components. There's a server with one root route which contains all components. Follow these steps:

Clone the repo by typing: git clone https://github.com/GuimG/my-react-components.git.
Go into the folder in your terminal and run the app by typing: npm run start.
Go to your browser and search for: http://localhost:3000.

Now you can see all of the components in your browser. There's a title on each one (except for the navbar which is fixed in all the page). If you like some specific component search it in the components folder by its title.

Last words

Hope this helps you. If you want any component in specific and it's not here, leave a comment and I'll try to do it ASAP.

Dynamic document head with React Helmet

Guim — Thu, 07 Mar 2019 19:18:47 +0000

Helmet is a React component that allows us to manage all of the changes to the document head. For example, let's say we're doing a social network. On the main page we may want the website title something like "My Social Network", but if we go to a user's profile the title should look like this: "User's name/Id - My Social Network".

Usage example

import React from 'react';
import { Helmet } from 'react-helmet';
import { Switch, Route } from 'react-router-dom';

import PageOne from 'containers/PageOne';
import PageTwo from 'containers/PageTwo';

const App = () => (
  <div className="app">
    <Helmet>
      <title>My App</title>
      <meta charSet="utf-8" />
      <meta name="description" content="A React.js application" />
    </Helmet>
    <Switch>
      <Route exact path="/" component={PageOne} />
      <Route path="/page-2" component={PageTwo} />
    </Switch>
  </div>
);

export default App;

Here's an example of a very basic app. As we can see, the title of the page will be My App. But this app has different routes. Let's say we want to change the title and the description for the /page-2 route, but we want to maintain the charset encoding. We can easily do it like this:

import React from 'react';
import { Helmet } from 'react-helmet';

export default class PageTwo extends React.Component {
  <div className="page-two">
    <Helmet>
      <title>Page 2</title>
      <meta name="description" content="This is a different description for this route." />
    </Helmet>
    <h1>Page 2</h1>
  </div>
);

As we only defined the title and the description in this second component, they'll be the only two values overwritten from the app itself. The charset won't change as we didn't define a new one.

The output title of this example is: Page 2

Using templates and default title

We can go a step ahead and make use of the properties that Helmet provides to us. For example the titleTemplate and the defaultTitle. We'll repeat the example above but now we'll establish these two props in the App's head.

import React from 'react';
import { Helmet } from 'react-helmet';

const App = () => (
  <div className="app">
    <Helmet titleTemplate="%s - My App" defaultTitle="My App">
      <meta name="description" content="A React.js aapplication" />
    </Helmet>
    <h1>My App</h1>
  </div>
);

export default App;

At this point, if we change to another component and we don't change the title, as the default title is My App this will be the output. Let's change it with the PageTwo component like before.

import React from 'react';
import { Helmet } from 'react-helmet';

export default class PageTwo extends React.Component {
  <div className="page-two">
    <Helmet>
      <title>Page 2</title>
      <meta name="description" content="This is a different description for this route." />
    </Helmet>
    <h1>Page 2</h1>
  </div>
);

Now the output title will be Page 2 - My App since we established the template. The %s is substituted by the string we pass on the title tag.

This is a very easy tutorial but I think it's very helpful for those who didn't know this component. Hope you enjoyed it! If you have any doubt leave it in the comments below. You can read the whole documentation in their Github.

Hide menu when scrolling in React.js

Guim — Sun, 10 Feb 2019 11:26:32 +0000

In this tutorial, I will explain how to make a navbar that is hidden or displayed when we scroll on the page. This is a version for React.js that uses the State of the component to know at all times what is the current state of our navbar.

The component

Now we will see what parts our component needs. First of all, as we said that we will save the position of the scroll in our State, we will create a new value for the State inside the constructor(), which will take the initial value of the offset of the page.

Of course, we will also need the render() method that will return a nav with all the navbar items inside. Here's a first look:

import React, { Component } from "react";
import classnames from "classnames";

export default class Navbar extends Component {
  constructor(props) {
    super(props);

    this.state = {
      prevScrollpos: window.pageYOffset,
      visible: true
    };
  }

  render() {
    return (
      <nav
        className={classnames("navbar", {
          "navbar--hidden": !this.state.visible
        })}
      >
        <a href="#">Item 1</a>
        <a href="#">Item 2</a>
        <a href="#">Item 3</a>
      </nav>
    );
  }
}

Here's the CSS:

.navbar {
  width: 100%;
  padding: 10px;
  position: fixed;
  top: 0;
  transition: top 0.6s;
}

.navbar--hidden {
  top: -50px;
}

Perfect, our component is ready to be viewed in a browser but does not yet have the behavior we want. Let's go for it!

First, we'll need to do the function that hides or displays the navbar. It will be called as if it was an event. It will see if the current offset is greater or less than the previous offset, depending on whether we scroll up or down. If the offset is bigger, we are going up, therefore it will display the menu. On the contrary, it is going to hide it. This show/hide behavior is managed by the visible state variable.

handleScroll = () => {
  const { prevScrollpos } = this.state;

  const currentScrollPos = window.pageYOffset;
  const visible = prevScrollpos > currentScrollPos;

  this.setState({
    prevScrollpos: currentScrollPos,
    visible
  });
};

Now the function is done. But we need to call it every time the user scrolls on the screen. We will use life cycle methods to add and remove that listener in the scroll.

componentDidMount() {
  window.addEventListener("scroll", this.handleScroll);
}

componentWillUnmount() {
  window.removeEventListener("scroll", this.handleScroll);
}

And with this, we finish our component. Next, I show all the whole code. I hope you liked it, I'll be uploading content more often. See you soon!

import React, { Component } from "react";
import classnames from "classnames";

export default class Navbar extends Component {
  constructor(props) {
    super(props);

    this.state = {
      prevScrollpos: window.pageYOffset,
      visible: true
    };
  }

  // Adds an event listener when the component is mount.
  componentDidMount() {
    window.addEventListener("scroll", this.handleScroll);
  }

  // Remove the event listener when the component is unmount.
  componentWillUnmount() {
    window.removeEventListener("scroll", this.handleScroll);
  }

  // Hide or show the menu.
  handleScroll = () => {
    const { prevScrollpos } = this.state;

    const currentScrollPos = window.pageYOffset;
    const visible = prevScrollpos > currentScrollPos;

    this.setState({
      prevScrollpos: currentScrollPos,
      visible
    });
  };

  render() {
    return (
      <nav
        className={classnames("navbar", {
          "navbar--hidden": !this.state.visible
        })}
      >
        <a href="#">Item 1</a>
        <a href="#">Item 2</a>
        <a href="#">Item 3</a>
      </nav>
    );
  }
}

How To Serve Node.js Applications with Nginx on a Raspberry

Guim — Wed, 30 Jan 2019 17:35:03 +0000

This is a tutorial of how I made my own server with Nginx to serve Node.js applications using a Raspberry Pi on my local network. I did it to have my own development server in my local network before committing any changes to the production host. We’ll go through all the steps so you can easily make your own too.

Prerequisites and specifications

For this tutorial, I suppose you have a Rasberry Pi with the Raspbian OS installed, root access to the board, another computer connected on the same network, and access to your Wifi app.

Board model: Raspberry Pi 3 B+
Board OS: Raspbian
Board CPU: ARMv7l

Install and run Nginx

To install Nginx and start the service on your Raspberry, open the terminal and type the following commands:

sudo apt-get update
sudo apt-get install nginx
sudo systemctl start nginx

Now your Nginx server is up and running. To check if the server is working properly, we can open a web browser from another computer and search for our Raspberry local IP. If you don’t know whats your Raspberry local IP open a new terminal and type:

hostname -I

In my case, it’s 192.168.0.173. So the address I have to search for will be http://192.168.0.173. Here you can see the default landing page of Nginx.

Congratulations, your Nginx server is working. Now we have to serve Node.js applications instead of static HTML files. How?

Install Node.js and NPM

Obviously, to work with Node.js, we first need to install Node.js packages and NPM (node package manager). We’ll also update NPM to the latest version. To do so, open a new terminal and type:

sudo apt-get install nodejs
sudo apt-get install npm
npm install -g npm

To check if both Node.js and NPM are installed properly, run the following commands:

nodejs -v
npm -v

Now that we have Nginx running and Node.js installed, it’s time to make our first Node app. The app will be a simple "Hello World" to check if Node and Nginx have good communication. Let’s write the app.

Create a Node.js app

In your home directory create a new folder called server. In this folder, we’ll create our Node.js app. Let’s write the index.js file.

const express = require("express");
const app = express();

// The HelloWorld
app.get("/", (req, res) => {
  res.send("Hello from Node.js!");
});

const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`App listening on http://localhost:${port}`);
});

Save this file in the server directory we created before. To make this app work, we need to install the express packages. Open a terminal, go to your server folder and use NPM to install them:

cd ~/server
npm init -y
npm install express --save

What we did is to initialize NPM and install the express packages. Now we can run the app with Node.js:

nodejs index.js

If you open a browser in your Raspberry and search for http://localhost:3000 you’ll see this Node "Hello World".

Nginx Proxy to the app

Our app is now running in port 3000. But what we want is to redirect all the HTTP requests in port 80 (the Nginx server) to the port 3000 (the Node.js app). We can do this modifying the default configuration file of Nginx.

server {
        listen 80 default_server;
        listen [::]:80 default_server;

        root /var/www/html;

        index index.html index.htm index.nginx-debian.html;

        server_name _;

        location / {
                proxy_pass http://localhost:3000;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection 'upgrade';
                proxy_set_header Host $host;
                proxy_cache_bypass $http_upgrade;
        }
}

Copy this configuration, delete all the text in your config file and paste it. To edit your default file type:

sudo nano /etc/nginx/sites-enabled/default

When you’re finished editing type crtl+X to save changes before exit. Don’t forget to restart your Nginx service:

sudo systemctl restart nginx

Now your Nginx is redirecting your HTTP requests to your localhost app. If we visit http://192.168.0.173 again (the address where Nginx is listening to) we now have to see the Node “Hello World”.

Configure IP tables

The only problem right now is we can access the app via http://localhost (thanks to Nginx) but still with http://localhost:3000 (the Node.js direct access). We don’t want this port 3000 open to anyone.

Imagine in the future you want to redirect all port 80 connections to port 443 because you transport personal data and you need an SSL certificate. People could still connect to port 3000 an omit this encrypted connection.

To solve this we just need to change two rules in our IP tables. The first one will allow localhost (the Raspberry) to connect to port 3000. The second one will deny access to anyone else. Open the terminal and type this:

iptables -A INPUT -p tcp -s localhost --dport 3000 -j ACCEPT
iptables -A INPUT -p tcp --dport 3000 -j DROP

DHCP IP reservation

Another thing you may want to do is to reserve an IP for your Raspberry. So your device has the same IP address every time it connects to your Wifi.

Open your Wifi app visiting: http://192.168.0.1 (This is your routers address)
Log in with the user and password printed on the bottom of the router.
There is a section called Advanced Networking.
Search for the DHCP IP reservations.
Click add device and search for your Raspberry.
Change the last number of the IP address to your will.

Last words

I hope this tutorial was useful for you. If you had any trouble in any of the steps just leave it in the comments below and I’ll do my best to help you. Thanks!