common_utils2 #

A production-focused Flutter utilities package: push / local / in-app notifications, storage (Hive CE, secure storage, shared preferences), connectivity, logging, a type-safe Result, countries & dial codes, currency, validators, media & files, location, and a set of everyday extensions.

Upgrading from 3.x? Read UPGRADING.md — 4.0.0 needs Flutter 3.47 / Dart 3.13 and has a few small API changes.

Contents #

1. Requirements & installation
2. Quick start
3. Module map — what to use when
4. Notifications
5. Result & error handling
6. Storage
7. Connectivity
8. Logging
9. Countries, dial codes & currency
10. Validators & extensions
11. Media, images & files
12. Location
13. Performance helpers
14. Name collisions to know about
15. Platform setup checklist

1. Requirements & installation #

dependencies:
  common_utils2: ^4.0.0
  material_ui: ^1.4.0   # Flutter 3.47+: Material lives here now

The package's widgets use package:material_ui/material_ui.dart. New apps should import material_ui instead of package:flutter/material.dart (existing apps can run dart fix --apply --code=migrate_design_widgets).

import 'package:common_utils2/common_utils2.dart';

2. Quick start #

Initialise the services you use once, in main(), before runApp. Everything is optional — only call what you need.

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Core services
  LoggerService.init(logLevel: LogLevel.debug);
  await StorageService.init();                         // SharedPreferences
  await SecureStorageService.init(namespace: 'myapp'); // tokens & secrets
  await HiveStorageService.init();                     // larger offline data
  await DeviceInfoHelper.init();
  await NetworkConnectivity.init();

  // Push + in-app notifications (needs Firebase for push)
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  final utils = await CommonUtilsInitializer.initialize(
    notificationConfig: NotificationConfig.withDefaults(
      requestPermissionOnInit: false, // ask later, in context
      onTokenRefreshed: (token) => api.saveDeviceToken(token),
    ),
  );

  Bloc.observer = LoggerService.getBlocObserver();

  runApp(MultiBlocProvider(providers: utils.providers, child: const MyApp()));
}

3. Module map — what to use when #

4. Notifications #

4.1 Setup #

await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);

await CommonNotificationService.instance.initialize(
  NotificationConfig.withDefaults(
    androidIcon: '@drawable/ic_notification', // white on transparent
    extraChannels: const [
      NotificationChannelDef(
        id: 'calls',
        name: 'Calls',
        description: 'Incoming voice and video calls',
        importance: Importance.max,
      ),
    ],
    requestPermissionOnInit: false,
    onTokenRefreshed: (token) async => api.saveDeviceToken(token),
    onNotificationTap: (payload) async {
      final link = payload.deepLink;
      if (link == null) return false;  // fall through to payloadHandler
      router.push(link);
      return true;                     // handled
    },
  ),
);

Default channels: general, orders, messages, promotions, alerts. Add your own with extraChannels. The server chooses the channel with data.channel.

4.2 Ask for permission in context #

// e.g. on an onboarding screen that explains why
final allowed = await CommonNotificationService.instance.requestPermission();

4.3 Cold start (app opened from a notification) #

The router isn't ready during initialize, so the tap is stored. Consume it once your router can navigate:

redirect: (context, state) {
  final tap = CommonNotificationService.instance.consumePendingTap();
  if (tap?.deepLink != null) return tap!.deepLink;
  return null;
}

Works for both FCM and local notifications (new in 4.0).

4.4 Payload conventions #

Everything in FCM data lands in payload.data. Recognised keys:

Typed access: payload.get<double>('amount'), payload.typed(MyModel.fromJson).

4.5 Per-category mute (new) #

final prefs = CommonNotificationService.instance.preferences;
await prefs.setMuted('promotions', true);
prefs.isMuted('promotions');              // true
prefs.changes.listen(syncToBackend);      // keep your server in sync
await prefs.switchScope(activeAccountId); // per-account preferences

Muting stops the app from displaying foreground and local notifications on that channel. Background FCM notification messages are drawn by the OS, so also store the preference server-side and skip sending.

4.6 In-app inbox, badge & centre #

CommonUtilsInitializer creates a NotificationCubit and, by default, pipes every foreground push into it.

NotificationBadge(child: Icon(Icons.notifications_outlined));   // total unread
NotificationBadge(channelId: 'orders', child: Icon(Icons.receipt)); // per category

context.read<NotificationCubit>().switchScope(accountId); // per-account inbox
context.read<NotificationCubit>().markChannelRead('orders');
state.unreadByChannel; // {'orders': 2, 'messages': 5}

Toasts over any screen:

MaterialApp.router(builder: (c, child) => InAppNotificationOverlay(child: child!));
InAppNotificationController.instance.show(title: 'Saved', body: 'Draft stored offline');

4.7 Custom routing class #

Implement INotificationHandler for larger apps and pass it as payloadHandler. Order of evaluation: config callback → handler → default behaviour. Replace at runtime with setHandler.

4.8 Logout #

await CommonNotificationService.instance.unsubscribeAll();
await CommonNotificationService.instance.deleteToken();

5. Result & error handling #

final result = await Result.guard(() => repo.fetchProfile());

switch (result) {
  case Success(:final data):   show(data);
  case Failure(:final message): showError(message);
}

• Result.guard / Result.guardSync capture errors and stack traces; non-Exception errors are wrapped, so building a failure never throws.
• Put a typed error in exception (anything that implements Exception) and read it with result.exceptionOrNull.
• mapError turns raw errors into friendly messages:

Result.guard(
  () => api.call(),
  mapError: (e, st) => (message: 'Could not reach the server', exception: MyNetworkFailure()),
);

Also: map, flatMap, fold, when, onSuccess, onFailure, getOrDefault, getOrElse, recover, dataOrNull, errorOrNull, stackTraceOrNull.

6. Storage #

await StorageService.instance.setBool('onboarded', true);
StorageService.instance.getBoolOrDefault('onboarded', false);

await SecureStorageService.instance.setString('refresh_token', token);

await HiveStorageService.instance.setUser(accountId);            // opens user_<id> box
await HiveStorageService.instance.setGlobalBool('seen_intro', true);

New apps: call SecureStorageService.init(namespace: 'yourapp') so values never collide with another app. Leaving the defaults keeps the 3.x (grascope_*) location, which is only needed for existing installs.

7. Connectivity #

await NetworkConnectivity.init(onConnectivityChanged: (s) => print(s.isConnected));
NetworkConnectivity.isConnected;
NetworkConnectivity.onConnectivityChanged.listen((status) { ... });
await NetworkConnectivity.getConnectionQuality(); // excellent/good/fair/poor
await NetworkConnectivity.waitForConnection(timeout: const Duration(seconds: 10));

hasInternetConnection() is now bounded by a 3-second timeout, so a slow or captive network can't stall start-up.

8. Logging #

LoggerService.init(logLevel: LogLevel.debug, enabled: !kReleaseMode);
final log = LoggerService.instance;
log.info('Loaded');
log.error('Failed', error, stackTrace);
Bloc.observer = LoggerService.getBlocObserver();

GoRouter(observers: [TalkerRouteObserver(LoggerService.instance.talker)]);
// In-app log viewer: TalkerScreen(talker: LoggerService.instance.talker)

9. Countries, dial codes & currency #

CountryData.all;                 // 194 countries, offline
CountryData.byCode['NG'];        // Country
CountryData.search('nig');       // name / code / dial code
CountryData.popular;             // NG, GH, ZA, KE, US, GB…
CountryService.init();           // optional: switch to a live source
CountryService.instance.getDialCodes(); // List<DialCode> for phone pickers ("🇳🇬 +234")

1500000.toCurrency();                        // ₦1,500,000.00
CurrencyUtils.formatAmount(2500, 'NGN');     // ₦2,500.00
CurrencyUtils.formatCompact(2450000, 'NGN'); // ₦2.45M

10. Validators & extensions #

TextFormField(validator: CommonValidators.nigerianPhoneValidator);
TextFormField(validator: CommonValidators.combine([
  (v) => CommonValidators.required(v, fieldName: 'Username'),
  (v) => CommonValidators.minLengthValidator(v, 3),
]));

'dev@example.com'.isValidEmail;   // true
'08012345678'.isValidNigerianPhone;
'hello world'.toTitleCase;        // Hello World
DateTime.now().toTimeAgo;         // "Just now"
[1, 2, 2, 3].distinct();          // [1, 2, 3]

11. Media, images & files #

final picked = await MediaUtils.pickImageFromGallery();
final compressed = await MediaUtils.compressImage(file, quality: 70);  // data-saver uploads
final thumb = await MediaUtils.extractThumbnailBytes(videoFile);

// file_picker 13 based (see UPGRADING.md)
final doc = await FileUtils.pickDocument();
final many = await FileUtils.pickMultipleFiles(type: FilePickerType.image, compressionQuality: 70);
final uri = await FileUtils.saveFile(fileName: 'invoice.pdf', bytes: pdfBytes);

12. Location #

final latLng = await LocationService.instance.getCurrentLatLng();
final address = await LocationService.instance.getFormattedAddress(6.5244, 3.3792);
final metres = LocationService.instance.calculateDistance(lat1, lon1, lat2, lon2);
LocationService.instance.setGeocodingLocale(const Locale('fr'));

13. Performance helpers #

final search = Debouncer(delay: const Duration(milliseconds: 400));
onChanged: (q) => search(() => cubit.search(q));

final tap = Throttler(duration: const Duration(seconds: 1));
onPressed: () => tap(submit);

final limiter = RateLimiter(maxCalls: 5, period: const Duration(minutes: 1));
if (!limiter(() => sendOtp())) showWait(limiter.timeUntilNextCall);

14. Name collisions to know about #

The barrel exports a few short, common names. If they clash with your code, hide them:

import 'package:common_utils2/common_utils2.dart' hide Failure, HttpClient;

Prefer naming your own types AppFailure, ApiClient, etc.

15. Platform setup checklist #

Android (android/app/build.gradle.kts)

android {
    compileSdk = 37
    defaultConfig { minSdk = 24 }
    compileOptions {
        isCoreLibraryDesugaringEnabled = true   // flutter_local_notifications
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}
dependencies { coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4") }

AndroidManifest.xml:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
<uses-permission android:name="android.permission.INTERNET"/>
<!-- inside <application> -->
<meta-data android:name="com.google.firebase.messaging.default_notification_channel_id"
           android:value="general"/>

iOS: enable Push Notifications and Background Modes → Remote notifications in Xcode, upload your APNs key to Firebase, and set the deployment target to 13.0.

License #

MIT — see LICENSE.

Author: Diwe Innocent · innocentdiwe.qzz.io · diweesomchi@gmail.com