🧠 Synrg

Synrg is a comprehensive Flutter utility package that abstracts and unifies Firebase services, modular state management, data modeling, query building, UI feedback, and validation — all with developer experience in mind.

It provides an opinionated architecture for building scalable Flutter apps with:

• Firebase (Auth, Firestore, Storage, Functions, Remote Config, Realtime DB, Analytics, Crashlytics, Performance)
• BLoC integration with enhanced state and UI feedback
• Strongly typed indexing, validation, and serialization logic
• Production-ready UI modal system
• 150+ domain-specific validators

---

✨ Features

• ✅ SynrgBlocProvider with automatic modal display and analytics
• 🔐 Firebase Authentication & profile management
• 🗃 Firestore abstraction with SynrgIndexer and paginated querying
• ⚡ Cloud Functions typed wrapper with result status
• 📁 Firebase Storage simplified upload/download/delete
• 🌐 Firebase Remote Config wrapper
• 🔄 Realtime Database write, update, listen and delete
• 📊 Firebase Analytics & Performance tracing
• 🛠 Crashlytics error logging and custom attributes
• 🔎 Query builder (QueryFilter) and parser
• 📦 Abstract base class SynrgClass for ID, map, and parent tracking
• 🧪 Extensive validation library for IDs, formats, geo, finance, healthcare, etc.

---

📦 Installation

Add dependency

flutter pub add synrg

Add synrg to your pubspec.yaml:

dependencies:
  synrg: ^latest

Make sure to initialize Firebase in your project.

---

🚀 Getting Started

import 'package:synrg/synrg.dart';

void main() async {
  await Firebase.initializeApp();

  SynrgCrashlytics.instance.initialize();
  SynrgAuth.initialize(Indexer.profiles);
}

Indexer.profiles is an optional parameter, if the app manages users it will use the passed index to query for the users in formation in sign in, register or update flows.

---

🧩 Modules

1. SynrgBlocProvider

A wrapper over BlocProvider + BlocConsumer that listens for modals and analytics automatically. The listener is there to show messages to the user, using this you can trigger a modal in the ui from the bloc's event code. It also logs the state changes and adds performance metrics

SynrgBlocProvider<MyBloc>(
  bloc: MyBloc()..add(MyInitEvent()),
  builder: (context, state) {
    if (state is MyStateReady) {
      return MyPage();
    }
    return CircularProgressIndicator();
  },
);

Requires states to extend SynrgState:

class MyState extends SynrgState {
  const MyState({this.modal}) : super(modal: modal);
  final SynrgModal? modal;

  @override
  Map<String, dynamic> toMap() => {...};
}

2. SynrgModal

In BLoC, the logic is located in the events. What this enables is to show the user information from the event logic. Show toasts, dialogs, drawers, etc., based on state.

emit(MyState(modal: SynrgModal(
  message: 'Operation failed',
  level: AlertLevel.error,
  type: SynrgModalType.toast,
)));

3. SynrgAuth

Firebase Authentication + Profile sync

await SynrgAuth.instance.signIn(email, password);
final user = SynrgAuth.instance.profile;

4. SynrgIndexer<T>

The indexer is a Firestore helper. Given a model you specify the mapping method and the table name and all the basic interactions are already taken care of.

class Indexer {
  static final profiles = SynrgIndexer<Profile>('profile', Profile.fromMap);
  static final projects = SynrgIndexer<Project>('project', Project.fromMap);
}

final project = await Indexer.projects.get('id123');
await Indexer.projects.save(Project(name: 'New Project'));

Supports pagination, filtering, and batch ops.

5. SynrgFunction<T>

Cloud Functions with result status: This is similar to the Indexer as it maps the result to the specified output type

class Payments {
  static Future<Profile?> payments({
    required String clientId,
    required int amount,
  }) async {
    final result =
        await SynrgFunction<Profile>('payments', Profile.fromMap).call({
      'clientId': clientId,
      'amount': amount,
    });
    if (result.status == SynrgFunctionStatus.success) {
      return result.result;
    } else {
      throw Exception('Failed to process payment: ${result.status}');
    }
  }
}


final result = await Payments.payments(clientId: 'id', amount: 'abc');

if (result =! null) {
  print(result.name);
}

6. SynrgStorage

final url = await SynrgStorage.instance.uploadFile('path/file.png', file);
await SynrgStorage.instance.deleteFile('path/file.png');

7. SynrgRealtimeDatabase

await SynrgRealtimeDatabase.instance.writeData('users/1', {'name': 'Ana'});
final snapshot = await SynrgRealtimeDatabase.instance.readData('users/1');

8. SynrgRemoteConfig

await SynrgRemoteConfig.instance.initialize();
final showBanner = SynrgRemoteConfig.instance.getBool('show_banner');

9. SynrgCrashlytics

SynrgCrashlytics.instance.logError(error, stackTrace);
SynrgCrashlytics.instance.setUserIdentifier(userId);

10. SynrgPerformance

final trace = await SynrgPerformance.instance.startTrace('my-trace');
// ... do work
await SynrgPerformance.instance.stopTrace(trace);

11. SynrgAnalytics

SynrgAnalytics.instance.logEvent('screen_view', {'page': 'home'});

12. QueryFilter

Query utilities for SynrgIndexer:

final filters = [
  QueryFilter('status', isEqualTo: 'active'),
  QueryFilter('price', isLessThanOrEqualTo: 100),
];
await index.query(filters);

Supports .toString() and .fromString(...) for dynamic queries.

13. SynrgClass

Your models should extend SynrgClass for auto-saving and ID handling:

class Project extends SynrgClass {
  final String name;

  Project({required this.name, super.id});

  @override
  Map<String, dynamic> toMap() => {'id': id, 'name': name};

  factory Project.fromMap(Map<String, dynamic> map) =>
      Project(name: map['name'], id: map['id']);
}

---

🧪 Validation

Import validators from synrg/validators.dart for:

• 📍 Address & Location (zip, city, lat/lng, etc.)
• 💳 Finance (credit card, CVV, IBAN, etc.)
• 📆 Date & Time (HH:mm:ss, timestamp, etc.)
• 📦 Logistics (SKU, barcode, VIN, tracking)
• 🧬 Healthcare (blood type, allergies, medical IDs)
• 🎓 Education (student ID, GPA, course code)
• 🌍 Tech & Network (IPv4/6, MAC, URL, domain, regex, JSON)
• 📄 Files & Content (file size, extension, CSV, Markdown, etc.)

Example:

TextFormField(
  validator: validateEmailAddress,
)

---

🔧 Requirements

• Flutter 3.16+
• Firebase (initialized in your app)
• BLoC (optional but recommended)

---

🤝 Contributing

PRs welcome! Please open issues for feedback, bugs or ideas.

---

📄 License

MIT © Your Name or Org