Using the SDK

Axiom Core is built on a reactive architecture. Unlike standard REST clients that return a one-time Future, every Axiom request is a Stream that can emit multiple states (e.g., Cache Hit followed by Network Refresh).

Initialization

The SDK must be initialized once, typically in your main() function. This boots the native Rust engine and prepares the persistent cache.

import 'package:path_provider/path_provider.dart';
import 'package:my_app/axiom_generated/axiom_sdk.dart';

late final AxiomSdk sdk;

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Use path_provider to get a safe directory for the Rust 'Sled' database
  final dbDir = await getApplicationSupportDirectory();

  sdk = await AxiomSdk.create(
    baseUrl: "https://api.myapp.com",
    dbPath: dbDir.path,
  );

  runApp(const MyApp());
}

Making Requests

Methods in the SDK return an AxiomQuery<T>. This object represents a managed query that is identified by a unique key (based on the endpoint and arguments).

Standard "Future-like" Execution

If you just want a single result (standard async/await), use the .unwrap() extension:

final user = await sdk.getUser(userId: 1).unwrap();

Stream-based Execution

For reactive UI components, you listen to the .stream. This is powerful when using Stale-While-Revalidate policies, as you receive the cached data instantly while the network update happens in the background.

sdk.getUser(userId: 1).stream.listen((state) {
  if (state.isLoading) print("Loading...");
  if (state.hasData) print("Data from ${state.source.name}: ${state.data}");
  if (state.hasError) print("Error: ${state.error}");
});

The Query Manager

Axiom uses an internal Query Manager to deduplicate requests. If two different widgets request getUser(userId: 1) at the same time, the runtime executes only one network call and broadcasts the result to both.

• query.refresh(): Invalidates the current cache and forces a fresh network fetch.
• query.prefetch(): Fetches data into the cache without needing a UI listener.