fiber_firebase_annotations 1.0.8

A Dart annotation package providing lightweight metadata for Firebase-oriented code generation. It defines structured annotations for Firestore, Realtime Database, Storage, and domain models, enabling [...]

fiber_firebase_annotation

fiber_firebase_annotation is a Dart annotation package designed to power a Firebase-oriented code generation system. It allows you to define typed, declarative, and consistent data models for Firestore, Database, Storage, without embedding any Firebase-specific logic into application code. This package does not generate any code by itself. It only provides the annotations consumed by Fiber code generators.

Goals

• Define your data structure once
• Automatically generate:
  • Firestore / Database models
  • Typed Storage access helpers
  • Typed constants
  • fromMap / toMap mappings
• Decouple business logic from Firebase infrastructure
• Enable future backend migration (Firebase → another backend)

Installation

dependencies:
  fiber_firebase_annotation: ^1.0.6

To be used in conjunction with Fiber code generation packages (fiber_*_gen).

Annotation Overview

Domain	Primary Annotation
Firestore	@FirestoreCollectionGen(...), @FirestoreSubCollectionGen(...)
Database	@DatabaseGen(...)
Storage	@StorageNode(...)

Firebase Firestore

Use @FirestoreCollectionGen(...) to define a root Firestore collection.

@FirestoreCollectionGen(collection: "__fbs__users")
class User {
  // fields...
}

This annotation is intended for models that represent top-level Firestore collections, such as:

• users
• projects
• stores
• threads

The generator can use this information to produce:

• collection name constants
• typed collection references
• helper methods for queries and document access

Use @FirestoreSubCollectionGen(...) to define a subcollection inside a Firestore document.

@FirestoreSubCollectionGen(parent: "__fbs__chats", collection: "__fbs__messages")
class Message {
  // fields...
}

This is useful for modeling hierarchical relationships such as:

• users/{userId}/notifications
• chats/{chatId}/messages
• projects/{projectId}/tasks

Realtime Database

The @DatabaseGen(...) annotation is used to declare a Firebase Realtime Database schema in a declarative way, enabling automatic code generation within the Fiber ecosystem.

It defines entry points for Realtime Database instances, without embedding any runtime Firebase logic or serialization code in the application layer.

@DatabaseGen(databaseURL: "https://myapp-users.firebaseio.com", name: "usersDB")
class UserDatabaseModel {
  // fields...
}

This annotation allows the build system to:

• generate strongly typed database accessors
• produce models aligned with the underlying JSON structure
• centralize database configuration (URL and logical name)
• remove boilerplate for serialization and deserialization

Firebase Storage

The @StorageGen(...) annotation is used to declaratively define the structure of a Firebase Storage bucket, enabling automatic generation of strongly typed storage accessors and path helpers.

Instead of manually concatenating string paths, storage hierarchies are described once and transformed into a type-safe, IDE-completable API by Fiber generators.

@StorageGen(
  root: [
    StorageNode(
      name: "users",
      children: [
        StorageNode(name: "avatars"),
        StorageNode(
          name: "documents",
          children: [
            StorageNode(name: "contracts"),
            StorageNode(name: "invoices"),
          ],
        ),
      ],
    ),
    StorageNode(name: "projects"),
  ],
)
class Storage {}

This annotation describes the entire storage tree, including nested folders and dynamic segments.