bifrosted library

Bifrosted - The rainbow bridge connecting your app to APIs.

A lightweight, opinionated REST API client and repository pattern for Dart/Flutter.

Features

  • Abstract REST API client with GET, POST, PUT, PATCH, DELETE
  • Repository pattern with automatic caching and memory singleton cache
  • Offline-first support with cache fallback
  • System-wide error notification via SystemNotifier
  • Write operations with automatic cache invalidation
  • Pluggable storage via StorageService
  • Pluggable logging via BifrostLogger
  • Global service locator (works with GetX, Provider, get_it, etc.)

Quick Start

  1. Set the service locator:
bifrostServiceLocator = <T>() => Get.find<T>();
  1. Implement the interfaces:
class MyAPI extends RestAPI { ... }
class MyStorage implements StorageService { ... }
class MyNotifier implements SystemNotifier { ... }
class MyConnectivity implements ConnectionChecker { ... }
  1. Create your repository:
class UserRepo extends BifrostRepository {
  final api = MyAPI();

  Future<User?> getUser(String id) => fetch<User>(
    apiRequest: () => api.get('/users/$id'),
    fromJson: User.fromJson,
  );

  Future<User?> createUser(User user) => mutate<User>(
    apiRequest: () => api.post('/users', body: user.toJson()),
    fromJson: User.fromJson,
    invalidateKeys: ['users_list'],
  );
}

Classes

BifrostRepository
Base repository for REST API calls with optional caching and deserialization.
ConnectionChecker
Interface for checking network connectivity.
FakeUtils
Utility class for generating fake data based on field names.
GenerateFake
Annotation to trigger fake factory generation via build_runner.
Logger
Use instances of logger to send log messages to the LogPrinter.
NoOpNotifier
Default no-op notifier that does nothing. Useful for testing or when you don't need notifications.
RestAPI
Base class for all REST API implementations.
StorageService
Abstract interface for local storage operations.
SystemNotifier
Interface for handling system-wide API events.

Enums

Level
Levels to control logging output. Logging can be enabled to include all levels above certain Level.

Constants

generateFake → const GenerateFake
Convenient constant for the annotation

Properties

bifrostJsonDecode ↔ Future Function(String body)
Global JSON decode function used by BifrostRepository.
getter/setter pair
bifrostLogger ↔ Logger
Default logger instance for bifrost.
getter/setter pair
bifrostServiceLocator ↔ T Function<T>()
Global service locator function used by BifrostRepository to find dependencies.
getter/setter pair

Functions

setClientFactory(ClientFactory factory) → void
Set a custom client factory for all RestAPI instances.
useMockClient({bool shouldFail = false, int failStatusCode = 400, Map<String, dynamic> responseFactory(Request request)?}) → void
Configure all RestAPI instances to use a mock client.
useRealClient() → void
Reset to using real HTTP clients.

Typedefs

ClientFactory = Client Function()
Factory function type for creating HTTP clients.

Exceptions / Errors

DeserializationException
Exception thrown when JSON deserialization fails.