Data, Networking & Storage

Neon Framework comes with built-in data persistence and networking abstractions located in package:neon_framework/storage.dart and package:neon_framework/networking.dart. You do not need third-party dependencies for common mobile data pipelines.

1. Key-Value Store

For storing user preferences, theme options, or authentication tokens, Neon provides NeonKeyValueStore.

import 'package:neon_framework/storage.dart';

final kvStore = NeonKeyValueStore();

// Storing values
await kvStore.setString('auth_token', 'neon_jwt_token_xyz');
await kvStore.setBool('is_dark_mode', true);
await kvStore.setInt('login_count', 42);

// Retrieving values
final token = await kvStore.getString('auth_token');
final isDark = await kvStore.getBool('is_dark_mode') ?? true;

2. SQLite Database with Migrations

Neon includes a structured SQLite interface with built-in schema migration support:

import 'package:neon_framework/storage.dart';

final db = NeonDatabase(
  name: 'app_database.db',
  version: 2,
  migrations: [
    NeonMigration(
      version: 1,
      up: (db) async {
        await db.execute('''
          CREATE TABLE tasks (
            id TEXT PRIMARY KEY,
            title TEXT NOT NULL,
            is_completed INTEGER NOT NULL
          )
        ''');
      },
    ),
    NeonMigration(
      version: 2,
      up: (db) async {
        await db.execute('ALTER TABLE tasks ADD COLUMN created_at INTEGER');
      },
    ),
  ],
);

// Querying data
final rows = await db.query(
  'tasks',
  where: 'is_completed = ?',
  whereArgs: [0],
);

3. HTTP Client with Interceptors

Neon provides an HTTP client with request/response interceptors, header management, and automatic JSON decoding:

import 'package:neon_framework/networking.dart';

final httpClient = NeonHttpClient(
  baseUrl: 'https://api.myapp.com/v1',
  interceptors: [
    NeonAuthInterceptor(getToken: () => kvStore.getString('auth_token')),
    NeonLoggingInterceptor(),
  ],
);

// Perform a GET request
final response = await httpClient.get<Map<String, dynamic>>('/dashboard');
print('User profile: ${response.data}');

// Perform a POST request
final postRes = await httpClient.post(
  '/tasks',
  body: {'title': 'Finish Neon documentation'},
);

4. WebSocket Client with Auto-Reconnect

For real-time chat, notifications, and live status feeds, use NeonWebSocketClient:

final wsClient = NeonWebSocketClient(
  url: 'wss://api.myapp.com/live',
  reconnectPolicy: NeonReconnectPolicy.exponentialBackoff(
    maxAttempts: 5,
    initialDelay: Duration(seconds: 1),
  ),
);

// Connect and listen to incoming frames
wsClient.messages.listen((message) {
  print('Received live message: $message');
});

// Send message
wsClient.send({'type': 'subscribe', 'channel': 'notifications'});

5. Cache Policies

Neon provides native caching strategies for offline-first resilience:

| Strategy | Behavior | | :--- | :--- | | CacheFirst | Serves local cache if available; requests network only on cache miss. | | NetworkFirst | Attempts network fetch; falls back to cached data on network failure. | | StaleWhileRevalidate | Immediately returns cached data for instant UI render, then fetches fresh data in background. |

final cachedResult = await httpClient.get(
  '/feed',
  cachePolicy: NeonCachePolicy.staleWhileRevalidate(maxAge: Duration(hours: 1)),
);