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 disk caching and offline fallback
UI-only error callbacks via SystemNotifier (use bifrostLogger for logs)
Write operations with automatic cache invalidation
Pluggable storage via StorageService
Pluggable logging via bifrostLogger
Pluggable HTTP performance metrics via PerformanceTracker
Global service locator (works with GetX, Provider, get_it, etc.)

Quick Start

Set the service locator:

bifrostServiceLocator = <T>() => Get.find<T>();

Implement the interfaces:

class MyAPI extends RestAPI { ... }
class MyStorage implements StorageService { ... }
class MyNotifier implements SystemNotifier { ... }
class MyConnectivity implements ConnectionChecker { ... }

Create your repository:

class UserRepo extends BifrostRepository {
  final api = MyAPI();

  Future<BifrostResult<User>> getUser(String id) => fetch(
    apiRequest: () => api.get('/users/$id'),
    model: const UserModel(),
  );

  Future<BifrostResult<List<User>>> getUsers() => fetch(
    apiRequest: () => api.get('/users'),
    model: const UserModel(),
  );

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

Classes

AnalyticsService: Event and user-property reporting.
AttributionService: Captures where an install came from, and forwards it so revenue can be segmented by it.
BifrostFailure<T>: The call failed for reason.
BifrostModel<T>: Everything BifrostRepository needs to know about a model type.
BifrostRepository: Base repository for REST API calls with optional caching and deserialization.
BifrostResult<T>: Outcome of a repository call.
BifrostSuccess<T>: The call succeeded and produced data.
ConnectionChecker: Interface for checking network connectivity.
DevelopmentFilter: Prints all logs with level >= Logger.level while in development mode (eg when asserts are evaluated, Flutter calls this debug mode).
EntitlementResult: Result of a purchase or restore.
EntitlementService: Access to what the user has paid for.
FakeUtils: Utility class for generating fake data based on field names.
GenerateFake: Annotation to trigger fake factory generation via build_runner.
HttpTrace: A single in-flight request being measured. Created by PerformanceTracker.startHttp.
LogFilter: An abstract filter of log messages.
Logger: Use instances of logger to send log messages to the LogPrinter.
LogOutput: Log output receives a OutputEvent from LogPrinter and sends it to the desired destination.
LogPrinter: An abstract handler of log events.
NoOpAnalyticsService: Default AnalyticsService — records nothing.
NoOpAttributionService: Default AttributionService — captures nothing.
NoOpEntitlementService: Default EntitlementService — no entitlements, every purchase cancelled.
NoOpNotifier: Default no-op notifier for tests or apps that handle errors in the UI layer.
NoOpPaywallPresenter: Default PaywallPresenter — shows nothing.
NoOpPerformanceTracker: Default PerformanceTracker — records nothing.
OnboardingController<T>: Drives a multi-step onboarding flow and reports its funnel.
ParseOnlyModel<T>: Adapter for models without a generated BifrostModel.
PaywallPresenter: Shows a paywall, whoever renders it.
PerformanceTracker: Hook for recording HTTP request performance.
PrettyPrinter: Default implementation of LogPrinter.
ProductionFilter: Prints all logs with level >= Logger.level even in production.
RestAPI: Base class for all REST API implementations.
SharedPrefService: SharedPreferences implementation of StorageService.
SimplePrinter: Outputs simple log messages:
StorageService: Abstract interface for local storage operations.
SystemNotifier: UI-only callbacks for global API error handling.

Enums

BifrostHttpMethod: HTTP method of an outgoing request.
CachePolicy: How BifrostRepository.fetch balances the network against the disk cache.
EntitlementOutcome: What happened when a purchase or restore was attempted.
FailureReason: Why a request failed.
Level: Levels to control logging output. Logging can be enabled to include all levels above certain Level.
PaywallOutcome: How a paywall closed.

Mixins

SharedPrefServiceMixin: Mixin for easy access to storage service.

Constants

generateFake → const GenerateFake: Convenient constant for the annotation
kDefaultFakeSeed → const int: Default seed for generated fake data.

Properties

bifrostFakeSeed ↔ int?: Seed used by FakeUtils. Defaults to kDefaultFakeSeed.
getter/setter pair
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
bifrostPerformanceTracker ↔ PerformanceTracker: Active performance tracker. Defaults to NoOpPerformanceTracker.
getter/setter pair
bifrostServiceLocator ↔ T Function<T>(): Global service locator function used by BifrostRepository to find dependencies.
getter/setter pair
bifrostUseFakes ↔ bool: When true, BifrostRepository.fetch returns model.fake() instead of calling the API.
getter/setter pair

Functions

failureReasonForStatus(int status) → FailureReason: Maps an HTTP status to its FailureReason.
setClientFactory(ClientFactory factory) → void: Set a custom client factory for all RestAPI instances.
useRealClient() → void: Reset to using real HTTP clients.

Typedefs

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

bifrosted library

Features

Quick Start

Classes

Enums

Mixins

Constants

Properties

Functions

Typedefs

bifrosted package

bifrosted library