Cookbook & Recipes

// lib/apps/auth/permissions.dart - Declarative JWT Auth & RBAC
import 'package:bloom_framework/bloom_server.dart';
import 'package:bloom_rest/bloom_rest.dart';
import 'package:bloom_security/bloom_security.dart';

class IsOwnerOrStaff extends BloomPermission {
  const IsOwnerOrStaff();

  @override
  Future<bool> hasPermission(BloomRequest request) async {
    final user = request.context.get<AuthUser>('auth_user');
    if (user == null) return false;
    return user.isActive;
  }

  @override
  Future<bool> hasObjectPermission(BloomRequest request, dynamic object) async {
    final user = request.context.get<AuthUser>('auth_user');
    if (user == null) return false;
    if (user.isStaff || user.isSuperuser) return true;

    // Check if the current object belongs to the authenticated user
    if (object is OwnableModel) {
      return object.userId == user.id;
    }
    return false;
  }
}

// lib/realtime/hub.dart - Realtime WebSocket Hub & Query Invalidation
import 'dart:io';
import 'package:bloom_realtime/bloom_realtime.dart';

void setupRealtimeServer(HttpServer server) {
  final hub = BloomChannelHub();

  server.listen((HttpRequest request) async {
    if (request.uri.path == '/ws/realtime') {
      if (WebSocketTransformer.isUpgradeRequest(request)) {
        final socket = await WebSocketTransformer.upgrade(request);
        // Automatically manages channel subscriptions & dead-socket pruning
        hub.registerConnection(socket);
      }
    }
  });
}

// Emits an event that prompts client SWR caches to refetch stale queries
void notifyTaskUpdated(BloomChannelHub hub, int listId, int taskId) {
  hub.broadcast('lists:$listId', {
    'action': 'invalidated',
    'entity': 'todo_task',
    'taskId': taskId,
  });
}

// lib/jobs/email_worker.dart - Background Worker with Exponential Backoff
import 'package:bloom_jobs/bloom_jobs.dart';
import 'package:bloom_mail/bloom_mail.dart';

class SendWelcomeEmailJob extends BloomJob<Map<String, dynamic>> {
  @override
  String get name => 'send_welcome_email';

  @override
  int get maxRetries => 5;

  @override
  Duration get backoff => const Duration(seconds: 10);

  @override
  Future<void> perform(Map<String, dynamic> payload) async {
    final email = payload['email'] as String;
    final name = payload['name'] as String;

    final mailer = inject<BloomMailer>();
    await mailer.send(
      to: email,
      subject: 'Welcome to Bloom!',
      body: 'Hi $name, welcome aboard!',
    );
  }
}

// lib/features/todos/controllers/todo_controller.dart - Offline-First Synchronized Cache
import 'package:bloom_framework/bloom_data.dart';
import 'package:bloom_realtime/bloom_realtime.dart';

class TodoController extends BloomController {
  // SWR Query with local SQLite persistence
  late final tasksQuery = createQuery<List<TodoTask>>(
    queryKey: ['todos', 'list', listId],
    queryFn: () => inject<TodoApi>().fetchTasks(listId),
    staleTime: const Duration(minutes: 5),
    persister: inject<BloomStorageAdapter>(),
  );

  // Optimistic Mutation with automatic offline retry queue
  late final toggleTaskMutation = createMutation<TodoTask, int>(
    mutationFn: (taskId) => inject<TodoApi>().toggleComplete(taskId),
    offlineQueue: true,
    onMutate: (taskId) async {
      // Optimistically flip completion state in UI immediately
      final previous = tasksQuery.data.value;
      // ... update local signal cache
      return previous;
    },
    onError: (err, taskId, rollbackData) {
      // Rollback on network failure
      if (rollbackData != null) tasksQuery.data.value = rollbackData;
    },
  );

  @override
  void onInit() {
    // Automatically invalidate query cache when server pushes real-time events
    inject<BloomRealtimeClient>().invalidateQueriesOnBroadcast(
      channel: 'lists:$listId',
      key: ['todos', 'list', listId],
    );
  }
}

// lib/features/settings/theme_controller.dart - Dynamic Theme Switcher
import 'package:bloom_framework/bloom_core.dart';
import 'package:bloom_ui/bloom_ui.dart';

class ThemeController extends BloomController {
  late final activePreset = createSignal<BloomStylePreset>(BloomStylePreset.nova);
  late final isDarkMode = createSignal<bool>(true);

  void setPreset(BloomStylePreset preset) {
    activePreset.value = preset;
  }

  void toggleDarkMode() {
    isDarkMode.value = !isDarkMode.value;
  }
}