### Conventional Commit Message Examples

Source: https://github.com/sylphxltd/firestore_odm/blob/main/PUBLISHING.md

Examples of conventional commit messages that guide automatic versioning, illustrating how different prefixes trigger major, minor, patch, or no version bumps.

```bash
feat: add new query builder feature          # → Minor version bump
fix: resolve null pointer exception          # → Patch version bump
feat!: change API for better performance     # → Major version bump
docs: update README examples                 # → No version bump
```

--------------------------------

### Migrating Basic Firestore Setup to Firestore ODM in Dart

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/migration-guide.md

This snippet compares basic Firestore setup using `cloud_firestore` with `firestore_odm`. It shows how to transition from untyped collection references to type-safe ODM instances, detailing installation, schema definition, and code generation steps. The migration provides type-safe collection access and compile-time validation.

```Dart
import 'package:cloud_firestore/cloud_firestore.dart';

final firestore = FirebaseFirestore.instance;
final usersCollection = firestore.collection('users');
```

```Dart
import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:firestore_odm/firestore_odm.dart';
import 'schema.dart'; // Your schema file

final firestore = FirebaseFirestore.instance;
final db = FirestoreODM(appSchema, firestore: firestore);
final usersCollection = db.users; // Type-safe collection reference
```

--------------------------------

### Generate Firestore ODM Code with build_runner

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/getting-started.md

This command-line snippet shows how to run `build_runner` to generate the necessary ODM code based on your defined models and schema. The `--delete-conflicting-outputs` flag ensures a clean build.

```bash
dart run build_runner build --delete-conflicting-outputs
```

--------------------------------

### Clean and Install Application Bundle Components

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/linux/CMakeLists.txt

Defines installation rules to first clean the bundle directory, then install the main executable, Flutter ICU data, Flutter engine library, bundled plugin libraries, and native assets. It also handles the installation of Flutter assets, ensuring they are always up-to-date by re-copying.

```CMake
install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)

# Copy the native assets provided by the build.dart from all packages.
set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/linux/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)

# Fully re-copy the assets directory on each build to avoid having stale files
# from a previous install.
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)
```

--------------------------------

### Initialize and Use Firestore ODM for Data Operations

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/getting-started.md

This Dart example demonstrates how to initialize Firestore ODM and perform basic type-safe database operations. It covers creating a new user document, retrieving a user by ID, and querying users based on a field value.

```dart
import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:firestore_odm/firestore_odm.dart';
import 'schema.dart';

void main() async {
  final firestore = FirebaseFirestore.instance;
  final odm = FirestoreODM(appSchema, firestore: firestore);

  // Create a user
  await odm.users.insert(User(id: 'jane', name: 'Jane Smith', email: 'jane@example.com'));

  // Get a user
  final user = await odm.users('jane').get();
  print(user?.name); // Prints "Jane Smith"

  // Query users
  final smiths = await odm.users.where((_) => _.name(isEqualTo: 'Jane Smith')).get();
  print('Found ${smiths.length} users named Jane Smith');
}
```

--------------------------------

### Verify Firestore ODM Project Setup

Source: https://github.com/sylphxltd/firestore_odm/blob/main/CONTRIBUTING.md

Command to run all quality checks (format, analyze, test) to verify the local development setup of the Firestore ODM project.

```bash
melos run check
```

--------------------------------

### Local Path Dependency Configuration for Development

Source: https://github.com/sylphxltd/firestore_odm/blob/main/PUBLISHING.md

An example of configuring a package dependency using a local file path, which is suitable for monorepo development and automatically handled by Melos during publishing.

```yaml
dependencies:
  firestore_odm_annotation:
    path: ../firestore_odm_annotation  # ✅ Local development
```

--------------------------------

### Configure Installation Bundle Output Directory

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/linux/CMakeLists.txt

Defines the default installation prefix to be a relocatable bundle directory within the build output. This ensures that 'make install' creates a self-contained application bundle ready for distribution.

```CMake
# === Installation ===
# By default, "installing" just makes a relocatable bundle in the build
# directory.
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()
```

--------------------------------

### Configure CMake Installation Directories and Defaults

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/windows/CMakeLists.txt

Sets up installation directories for the application bundle, including data and library paths. It also makes the 'install' step default for Visual Studio builds and sets the default installation prefix to the build bundle directory.

```CMake
# === Installation ===
# Support files are copied into place next to the executable, so that it can
# run in place. This is done instead of making a separate bundle (as on Linux)
# so that building and running from within Visual Studio will work.
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
# Make the "install" step default, as it's required to run.
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")
```

--------------------------------

### Add Firestore ODM Dependencies to pubspec.yaml

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/getting-started.md

This snippet shows how to add the necessary dependencies for Firestore ODM to your `pubspec.yaml` file, including `cloud_firestore`, `firestore_odm`, `freezed_annotation`, `build_runner`, `firestore_odm_builder`, `freezed`, and `json_serializable` for development.

```yaml
# pubspec.yaml
dependencies:
  cloud_firestore: ^4.0.0 # Or your desired version
  firestore_odm: ^1.0.0
  # One of: freezed_annotation, json_annotation
  freezed_annotation: ^2.0.0

dev_dependencies:
  build_runner: ^2.0.0
  firestore_odm_builder: ^1.0.0
  # One of: freezed, json_serializable
  freezed: ^2.0.0
  json_serializable: ^6.0.0
```

--------------------------------

### Published Version Dependency Configuration

Source: https://github.com/sylphxltd/firestore_odm/blob/main/PUBLISHING.md

An example demonstrating how Melos automatically transforms local path dependencies into published version dependencies during the package publishing process.

```yaml
dependencies:
  firestore_odm_annotation: ^1.0.0    # ✅ Published version
```

--------------------------------

### Git Tag-based Release

Source: https://github.com/sylphxltd/firestore_odm/blob/main/PUBLISHING.md

Initiates a release by creating and pushing a Git tag, which triggers a GitHub Actions workflow for publishing.

```bash
git tag v1.0.1
git push origin v1.0.1
```

--------------------------------

### Install Flutter Assets and AOT Library with Clean-up

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/windows/CMakeLists.txt

Manages the installation of Flutter assets by first removing any stale asset directory and then copying the fresh assets. It also installs the AOT (Ahead-of-Time) library for 'Profile' and 'Release' builds only, optimizing performance for production.

```CMake
# Fully re-copy the assets directory on each build to avoid having stale files
# from a previous install.
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

# Install the AOT library on non-Debug builds only.
install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  CONFIGURATIONS Profile;Release
  COMPONENT Runtime)
```

--------------------------------

### Local Melos Commands for Package Publishing

Source: https://github.com/sylphxltd/firestore_odm/blob/main/PUBLISHING.md

A sequence of Melos commands to preview version changes, update versions, perform a dry-run publish test, and finally publish packages to pub.dev locally.

```bash
# 1. Preview version changes
melos version --dry-run

# 2. Update versions
melos version

# 3. Dry-run publish test
melos run publish:dry-run

# 4. Publish to pub.dev
melos run publish:packages
```

--------------------------------

### Troubleshooting Pub.dev Publishing Failures

Source: https://github.com/sylphxltd/firestore_odm/blob/main/PUBLISHING.md

Commands to check pub.dev credentials and perform a local dry-run publish test, useful for diagnosing issues when package publishing fails.

```bash
# Check credentials
dart pub login

# Test dry-run locally
melos run publish:dry-run
```

--------------------------------

### Install Application Executable and Core Runtime Files

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/windows/CMakeLists.txt

Installs the main application executable, the Flutter ICU data file, and the Flutter library to their respective bundle directories as part of the 'Runtime' component, enabling the application to run.

```CMake
install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Bootstrap Firestore ODM Workspace with Melos

Source: https://github.com/sylphxltd/firestore_odm/blob/main/CONTRIBUTING.md

Command to initialize and set up the project's monorepo workspace using Melos, installing dependencies and linking packages.

```bash
melos bootstrap
```

--------------------------------

### Example Dart Unit Test for FirestoreODM

Source: https://github.com/sylphxltd/firestore_odm/blob/main/CONTRIBUTING.md

A Dart code example demonstrating how to write a unit test for `FirestoreODM` using the `test` package, verifying collection reference creation.

```dart
import 'package:test/test.dart';
import 'package:firestore_odm/firestore_odm.dart';

void main() {
  group('FirestoreODM', () {
    test('should create collection reference', () {
      // Arrange
      const collectionPath = 'users';
      
      // Act
      final collection = FirestoreODM.collection(collectionPath);
      
      // Assert
      expect(collection.path, equals(collectionPath));
    });
  });
}
```

--------------------------------

### Generate and Retrieve Pub.dev Credentials

Source: https://github.com/sylphxltd/firestore_odm/blob/main/PUBLISHING.md

Commands to log in to pub.dev and retrieve the content of the generated credentials.json file, which is required as a GitHub Secret for automated publishing.

```bash
dart pub login

# Copy credentials file content
cat ~/.pub-cache/credentials.json

# Add to GitHub Secrets as PUB_CREDENTIALS
```

--------------------------------

### Package Health and Validation Commands

Source: https://github.com/sylphxltd/firestore_odm/blob/main/PUBLISHING.md

A set of Dart commands to check package dependencies, validate for publishing, analyze code for issues, and format code according to standards.

```bash
# Check package health
dart pub deps --style=tree

# Validate package
dart pub publish --dry-run

# Check for issues
dart analyze

# Format code
dart format .
```

--------------------------------

### Install Firestore ODM Dependencies

Source: https://github.com/sylphxltd/firestore_odm/blob/main/packages/firestore_odm/README.md

Provides the necessary `pubspec.yaml` configuration for installing `cloud_firestore`, `firestore_odm`, `freezed_annotation`, `build_runner`, `firestore_odm_builder`, `freezed`, and `json_serializable` to set up a Firestore ODM project.

```yaml
dependencies:
  cloud_firestore: ^4.0.0
  firestore_odm: ^2.0.0
  freezed_annotation: ^2.0.0

dev_dependencies:
  build_runner: ^2.0.0
  firestore_odm_builder: ^2.0.0
  freezed: ^2.0.0
  json_serializable: ^6.0.0
```

--------------------------------

### Install Firestore ODM and Dependencies

Source: https://github.com/sylphxltd/firestore_odm/blob/main/README.md

Provides the necessary `pubspec.yaml` configuration to install `cloud_firestore`, `firestore_odm`, `freezed_annotation`, and their respective `dev_dependencies` for code generation.

```YAML
dependencies:
  cloud_firestore: ^4.0.0
  firestore_odm: ^2.0.0
  freezed_annotation: ^2.0.0

dev_dependencies:
  build_runner: ^2.0.0
  firestore_odm_builder: ^2.0.0
  freezed: ^2.0.0
  json_serializable: ^6.0.0
```

--------------------------------

### Install Bundled Plugin Libraries

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/windows/CMakeLists.txt

Conditionally installs any bundled plugin libraries to the application's library directory if they are defined. This ensures all necessary plugin dependencies are included in the final installation.

```CMake
if(PLUGIN_BUNDLED_LIBRARIES)
  install(FILES "${PLUGIN_BUNDLED_LIBRARIES}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Install Native Assets from Build Directory

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/windows/CMakeLists.txt

Copies native assets generated by `build.dart` from the specified Windows build directory to the application's library installation directory. This ensures platform-specific native dependencies are correctly deployed.

```CMake
# Copy the native assets provided by the build.dart from all packages.
set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/windows/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)
```

--------------------------------

### Querying Users: Before and After Firestore ODM

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/introduction.md

This example demonstrates the difference in querying and data retrieval between the standard `cloud_firestore` package and Firestore ODM. It highlights how Firestore ODM introduces type safety, IDE support, and simplified query building compared to the manual, string-based approach of `cloud_firestore`.

```Dart
// String-based, error-prone
final snapshot = await FirebaseFirestore.instance
  .collection('users')
  .where('isActive', isEqualTo: true)
  .where('age', isGreaterThan: 18)
  .get();

List<Map<String, dynamic>> users = snapshot.docs
  .map((doc) => doc.data())
  .toList();
```

```Dart
// Type-safe, IDE-supported
List<User> users = await db.users
  .where(($) => $.and(
    $.isActive(isEqualTo: true),
    $.age(isGreaterThan: 18),
  ))
  .get();
```

--------------------------------

### Fetching a Query Once

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/fetching-data.md

Once you have constructed a query (by starting with a collection reference and optionally adding `where`, `orderBy`, or `limit` clauses), you execute it by calling `.get()`. This returns a `Future` that resolves to a `List` of your model objects.

```dart
// Define a query for active users, sorted by age
final activeUsersQuery = db.users
  .where(($) => $.isActive(isEqualTo: true))
  .orderBy(($) => $.age(descending: true));

// Execute the query to get the results
// Returns Future<List<User>>
final List<User> activeUsers = await activeUsersQuery.get();

for (final user in activeUsers) {
  print('${user.name} is ${user.age} years old.');
}
```

--------------------------------

### Define Firestore ODM Schema in Dart

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/getting-started.md

This Dart snippet illustrates how to group your Firestore collections into a schema using `@Schema()` and `@Collection()` annotations. This schema acts as the single source of truth for your database structure, enabling type-safe operations.

```dart
// lib/schema.dart
import 'package:firestore_odm/firestore_odm.dart';
import 'models/user.dart';

part 'schema.odm.dart';

@Schema()
@Collection<User>("users")
final appSchema = _$AppSchema;
```

--------------------------------

### Install Melos Globally for Project Management

Source: https://github.com/sylphxltd/firestore_odm/blob/main/CONTRIBUTING.md

Command to activate Melos, a monorepo management tool, globally using Dart's package manager, `pub`.

```bash
dart pub global activate melos
```

--------------------------------

### Install AOT Library for Non-Debug Builds

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/linux/CMakeLists.txt

Installs the Ahead-of-Time (AOT) compiled library only when the build type is not 'Debug'. This optimizes the application for release by including the pre-compiled code.

```CMake
if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Manual Firestore Pagination Implementation in Dart

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/migration-guide.md

This snippet demonstrates the traditional, manual approach to implementing pagination in Firestore using `orderBy`, `limit`, and `startAfterDocument`. It highlights the necessity of precisely matching `orderBy` clauses for subsequent pages and the potential for errors in manual cursor management.

```dart
// First page
Query query = usersCollection
  .orderBy('createdAt', descending: true)
  .limit(10);

QuerySnapshot firstPage = await query.get();
List<QueryDocumentSnapshot> docs = firstPage.docs;

// Next page - manual cursor management (error-prone!)
if (docs.isNotEmpty) {
  DocumentSnapshot lastDoc = docs.last;
  Query nextQuery = usersCollection
    .orderBy('createdAt', descending: true) // Must match exactly!
    .startAfterDocument(lastDoc)
    .limit(10);
  
  QuerySnapshot nextPage = await nextQuery.get();
}
```

--------------------------------

### CMake Configuration for Flutter Library and System Dependencies

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/linux/flutter/CMakeLists.txt

Configures the Flutter library's build environment by finding and linking required system-level dependencies like GTK, GLIB, and GIO using PkgConfig. It also defines the paths for the Flutter library and its header files, making them available for subsequent build steps and installation.

```CMake
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
pkg_check_modules(GLIB REQUIRED IMPORTED_TARGET glib-2.0)
pkg_check_modules(GIO REQUIRED IMPORTED_TARGET gio-2.0)

set(FLUTTER_LIBRARY "${EPHEMERAL_DIR}/libflutter_linux_gtk.so")

# Published to parent scope for install step.
set(FLUTTER_LIBRARY ${FLUTTER_LIBRARY} PARENT_SCOPE)
set(FLUTTER_ICU_DATA_FILE "${EPHEMERAL_DIR}/icudtl.dat" PARENT_SCOPE)
set(PROJECT_BUILD_DIR "${PROJECT_DIR}/build/" PARENT_SCOPE)
set(AOT_LIBRARY "${PROJECT_DIR}/build/lib/libapp.so" PARENT_SCOPE)

list(APPEND FLUTTER_LIBRARY_HEADERS
  "fl_basic_message_channel.h"
  "fl_binary_codec.h"
  "fl_binary_messenger.h"
  "fl_dart_project.h"
  "fl_engine.h"
  "fl_json_message_codec.h"
  "fl_json_method_codec.h"
  "fl_message_codec.h"
  "fl_method_call.h"
  "fl_method_channel.h"
  "fl_method_codec.h"
  "fl_method_response.h"
  "fl_plugin_registrar.h"
  "fl_plugin_registry.h"
  "fl_standard_message_codec.h"
  "fl_standard_method_codec.h"
  "fl_string_codec.h"
  "fl_value.h"
  "fl_view.h"
  "flutter_linux.h"
)
list_prepend(FLUTTER_LIBRARY_HEADERS "${EPHEMERAL_DIR}/flutter_linux/")
add_library(flutter INTERFACE)
target_include_directories(flutter INTERFACE
  "${EPHEMERAL_DIR}"
)
target_link_libraries(flutter INTERFACE "${FLUTTER_LIBRARY}")
target_link_libraries(flutter INTERFACE
  PkgConfig::GTK
  PkgConfig::GLIB
  PkgConfig::GIO
)
add_dependencies(flutter flutter_assemble)
```

--------------------------------

### Install Dependencies for Dart Firestore ODM Project

Source: https://github.com/sylphxltd/firestore_odm/blob/main/packages/firestore_odm_annotation/README.md

Provides the necessary `pubspec.yaml` configuration for installing `cloud_firestore`, `firestore_odm`, `freezed_annotation`, and their respective `dev_dependencies` like `build_runner`, `firestore_odm_builder`, `freezed`, and `json_serializable`.

```yaml
dependencies:
  cloud_firestore: ^4.0.0
  firestore_odm: ^2.0.0
  freezed_annotation: ^2.0.0

dev_dependencies:
  build_runner: ^2.0.0
  firestore_odm_builder: ^2.0.0
  freezed: ^2.0.0
  json_serializable: ^6.0.0
```

--------------------------------

### Manually Bumping Package Version with Melos

Source: https://github.com/sylphxltd/firestore_odm/blob/main/PUBLISHING.md

A Melos command to manually increment the major version of a specific package, useful for resolving version conflicts or forcing a major update.

```bash
melos version firestore_odm_annotation major
```

--------------------------------

### Firestore ODM Basic Aggregations (Before Migration)

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/migration-guide.md

Illustrates the limitations of basic Firestore aggregations before migrating to the ODM. It shows how only a simple count operation is available, requiring manual calculations for more complex statistics and lacking streaming capabilities.

```dart
// Only basic count available
AggregateQuerySnapshot countSnapshot = await usersCollection
  .where('isActive', isEqualTo: true)
  .count()
  .get();

int count = countSnapshot.count;

// No sum/average support
// No streaming aggregations
// Manual calculation required for complex stats
```

--------------------------------

### Install Firestore ODM Dependencies (YAML)

Source: https://github.com/sylphxltd/firestore_odm/blob/main/packages/firestore_odm_builder/README.md

Provides the necessary pubspec.yaml dependencies for integrating cloud_firestore, firestore_odm, and related build tools like freezed and json_serializable into a Dart project.

```YAML
dependencies:
  cloud_firestore: ^4.0.0
  firestore_odm: ^2.0.0
  freezed_annotation: ^2.0.0

dev_dependencies:
  build_runner: ^2.0.0
  firestore_odm_builder: ^2.0.0
  freezed: ^2.0.0
  json_serializable: ^6.0.0
```

--------------------------------

### Firestore ODM Pagination with Smart Builder

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/migration-guide.md

Demonstrates how to implement type-safe pagination using Firestore ODM's Smart Builder. It shows fetching the first page, subsequent pages with automatic cursor extraction using `startAfterObject()`, and multi-field ordering, eliminating manual cursor management and ensuring consistency.

```dart
// First page with Smart Builder
List<User> firstPage = await db.users
  .orderBy(($) => $.createdAt(descending: true))
  .limit(10)
  .get();

// Next page - zero inconsistency risk!
if (firstPage.isNotEmpty) {
  List<User> nextPage = await db.users
    .orderBy(($) => $.createdAt(descending: true)) // Same orderBy
    .startAfterObject(firstPage.last) // Auto-extracts cursor
    .limit(10)
    .get();
}

// Multi-field ordering with type safety
List<User> complexPage = await db.users
  .orderBy(($) => (
    $.profile.followers(descending: true),
    $.name(), // ascending
  ))
  .limit(10)
  .get();
```

--------------------------------

### Initialize and Access Firestore ODM Collections in Dart

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/schema-definition.md

This Dart example shows how to initialize the Firestore ODM instance by providing the generated schema and a `FirebaseFirestore` instance. Once initialized, it demonstrates how to access type-safe collection references (e.g., `db.users`, `db.posts`) for interacting with your Firestore database.

```dart
import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:firestore_odm/firestore_odm.dart';
import 'schema.dart'; // Your schema file

final firestore = FirebaseFirestore.instance;

// Create the ODM instance
final db = FirestoreODM(firestoreDatabase, firestore: firestore);

// Now you can access your collections with type-safety
final usersCollection = db.users;
final postsCollection = db.posts;
```

--------------------------------

### Real-time Streaming Aggregations with Firestore ODM

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/README.md

This example showcases Firestore ODM's unique ability to perform real-time streaming aggregations (count, sum, average), a feature not available in standard `cloud_firestore`, providing live statistics updates.

```dart
// ❌ Standard - No streaming aggregations
// Only basic count, no real-time updates

// ✅ ODM - Real-time streaming aggregations (unique feature!)
db.users.aggregate(($) => (
  count: $.count(),
  averageAge: $.age.average(),
)).stream.listen((result) {
  print('Live stats: ${result.count} users, avg age ${result.averageAge}');
});
```

--------------------------------

### Firestore ODM Manual Transactions (Before Migration)

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/migration-guide.md

Depicts the manual approach to Firestore transactions, requiring explicit read-before-write logic and manual data extraction and updates using raw `Map<String, dynamic>` operations. This method is prone to errors and less efficient.

```dart
await FirebaseFirestore.instance.runTransaction((transaction) async {
  // Must manually ensure all reads happen before writes
  DocumentSnapshot userDoc = await transaction.get(
    usersCollection.doc('user1')
  );
  DocumentSnapshot receiverDoc = await transaction.get(
    usersCollection.doc('user2')
  );
  
  // Manual data extraction
  Map<String, dynamic> userData = userDoc.data() as Map<String, dynamic>;
  Map<String, dynamic> receiverData = receiverDoc.data() as Map<String, dynamic>;
  
  int userBalance = userData['balance'];
  int receiverBalance = receiverData['balance'];
  
  // Manual map updates
  transaction.update(usersCollection.doc('user1'), {
    'balance': userBalance - 100,
  });
  transaction.update(usersCollection.doc('user2'), {
    'balance': receiverBalance + 100,
  });
});
```

--------------------------------

### Define Flutter Library Paths and Headers for CMake

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/windows/flutter/CMakeLists.txt

Defines CMake variables for the Flutter Windows DLL, ICU data file, project build directory, and AOT library, publishing them to the parent scope for installation steps. It also lists and transforms Flutter library header paths to include the ephemeral directory.

```CMake
set(FLUTTER_LIBRARY "${EPHEMERAL_DIR}/flutter_windows.dll")

# Published to parent scope for install step.
set(FLUTTER_LIBRARY ${FLUTTER_LIBRARY} PARENT_SCOPE)
set(FLUTTER_ICU_DATA_FILE "${EPHEMERAL_DIR}/icudtl.dat" PARENT_SCOPE)
set(PROJECT_BUILD_DIR "${PROJECT_DIR}/build/" PARENT_SCOPE)
set(AOT_LIBRARY "${PROJECT_DIR}/build/windows/app.so" PARENT_SCOPE)

list(APPEND FLUTTER_LIBRARY_HEADERS
  "flutter_export.h"
  "flutter_windows.h"
  "flutter_messenger.h"
  "flutter_plugin_registrar.h"
  "flutter_texture_registrar.h"
)
list(TRANSFORM FLUTTER_LIBRARY_HEADERS PREPEND "${EPHEMERAL_DIR}/")
```

--------------------------------

### Implementing Smart Pagination with Firestore ODM

Source: https://github.com/sylphxltd/firestore_odm/blob/main/packages/firestore_odm/README.md

This example demonstrates Firestore ODM's Smart Builder pagination, which eliminates common pagination bugs. It shows how to fetch the first page with ordering and then retrieve subsequent pages using `startAfterObject`, which automatically extracts cursor values from the last document of the previous page, ensuring type-safe and consistent pagination.

```Dart
// Get first page with ordering
final page1 = await db.users
  .orderBy(($) => ($.followers(descending: true), $.name()))
  .limit(10)
  .get();

// Get next page with perfect type-safety - zero inconsistency risk
// The same orderBy ensures cursor consistency automatically
final page2 = await db.users
  .orderBy(($) => ($.followers(descending: true), $.name()))
  .startAfterObject(page1.last) // Auto-extracts cursor values
  .limit(10)
  .get();
```

--------------------------------

### Smart Update Strategies with Firestore ODM

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/README.md

This example demonstrates Firestore ODM's intelligent update patterns (patch, incrementalModify) compared to the manual map construction required by standard `cloud_firestore`. ODM simplifies complex updates like incrementing fields or adding array elements.

```dart
// ❌ Standard - Manual map construction
await userDoc.update({
  'profile.followers': FieldValue.increment(1),
  'tags': FieldValue.arrayUnion(['verified']),
});

// ✅ ODM - Three intelligent update patterns
await userDoc.patch(($) => [
  $.profile.followers.increment(1),
  $.tags.add('verified'),
]);

await userDoc.incrementalModify((user) => user.copyWith(
  age: user.age + 1, // Auto-detects -> FieldValue.increment(1)
));
```

--------------------------------

### Firestore ODM Comprehensive Aggregations

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/migration-guide.md

Showcases the enhanced aggregation capabilities of Firestore ODM. It demonstrates performing multiple aggregations (count, average, sum) in a single request and implementing real-time streaming aggregations for live statistics, providing type-safe results.

```dart
// Multiple aggregations in one request
final stats = await db.users
  .where(($) => $.isActive(isEqualTo: true))
  .aggregate(($) => (
    count: $.count(),
    averageAge: $.age.average(),
    totalFollowers: $.profile.followers.sum(),
  ))
  .get();

print('Count: ${stats.count}');
print('Average age: ${stats.averageAge}');
print('Total followers: ${stats.totalFollowers}');

// Streaming aggregations (unique feature!)
db.users
  .where(($) => $.isActive(isEqualTo: true))
  .aggregate(($) => (count: $.count()))
  .stream
  .listen((result) {
    print('Live count: ${result.count}');
  });
```

--------------------------------

### Setting Up Local Documentation Development

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/README.md

Instructions for developers to set up and run the project's documentation locally, enabling real-time preview and development.

```bash
cd docs
npm install
npm run dev
```

--------------------------------

### Firestore ODM: Testing User Operations with Fake Cloud Firestore

Source: https://github.com/sylphxltd/firestore_odm/blob/main/README.md

This example illustrates how to integrate Firestore ODM with `fake_cloud_firestore` for unit testing. It sets up a mock Firestore instance, performs a document insertion, and then retrieves and asserts the data, ensuring reliable and isolated tests.

```dart
import 'package:fake_cloud_firestore/fake_cloud_firestore.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  test('user operations work correctly', () async {
    final firestore = FakeFirebaseFirestore();
    final db = FirestoreODM(appSchema, firestore: firestore);

    await db.users.insert(User(id: 'test', name: 'Test User', email: 'test@example.com', age: 25));

    final user = await db.users('test').get();
    expect(user?.name, 'Test User');
  });
}
```

--------------------------------

### Firestore ODM Automatic Deferred Writes in Transactions

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/migration-guide.md

Illustrates the simplified and safer transaction management with Firestore ODM. It shows how the ODM automatically handles read-before-write, uses typed models for data manipulation, and defers write operations until the end of the transaction, ensuring atomicity and reducing boilerplate.

```dart
await db.runTransaction((tx) async {
  // Reads happen automatically first
  User? sender = await tx.users('user1').get();
  User? receiver = await tx.users('user2').get();
  
  if (sender == null || receiver == null) {
    throw Exception('User not found');
  }
  
  if (sender.balance < 100) {
    throw Exception('Insufficient funds');
  }
  
  // Writes are automatically deferred until the end
  await tx.users('user1').incrementalModify((user) => user.copyWith(
    balance: user.balance - 100, // Becomes atomic decrement
  ));
  
  await tx.users('user2').incrementalModify((user) => user.copyWith(
    balance: user.balance + 100, // Becomes atomic increment
  ));
});
```

--------------------------------

### Implementing Smart Pagination with Firestore ODM

Source: https://github.com/sylphxltd/firestore_odm/blob/main/packages/firestore_odm_builder/README.md

This example demonstrates Firestore ODM's Smart Builder pagination, designed to eliminate common Firestore pagination bugs. It shows how to fetch the first page with specific ordering and then retrieve subsequent pages using `startAfterObject`, which automatically extracts cursor values from the last document of the previous page, ensuring type-safe and consistent pagination.

```Dart
// Get first page with ordering
final page1 = await db.users
  .orderBy(($) => ($.followers(descending: true), $.name()))
  .limit(10)
  .get();
```

```Dart
// Get next page with perfect type-safety - zero inconsistency risk
// The same orderBy ensures cursor consistency automatically
final page2 = await db.users
  .orderBy(($) => ($.followers(descending: true), $.name()))
  .startAfterObject(page1.last) // Auto-extracts cursor values
  .limit(10)
  .get();
```

--------------------------------

### Building Project Documentation for Deployment

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/README.md

Commands to compile the documentation source files into a static build, ready for deployment to a web server or hosting platform like GitHub Pages.

```bash
cd docs
npm run build
```

--------------------------------

### Building Firestore Queries: Standard vs. Type-Safe ODM

Source: https://github.com/sylphxltd/firestore_odm/blob/main/packages/firestore_odm_builder/README.md

This example contrasts query building in standard `cloud_firestore` with Firestore ODM. Standard queries use string-based field paths, which are prone to runtime errors from typos. Firestore ODM offers a type-safe query builder with IDE support, ensuring compile-time validation and improved readability for complex logical queries.

```Dart
// ❌ Standard - String-based field paths, typos cause runtime errors
final result = await FirebaseFirestore.instance
  .collection('users')
  .where('isActive', isEqualTo: true)
  .where('profile.followers', isGreaterThan: 100)
  .where('age', isLessThan: 30)
  .get();
```

```Dart
// ✅ ODM - Type-safe query builder with IDE support
final result = await db.users
  .where(($) => $.and(
    $.isActive(isEqualTo: true),
    $.profile.followers(isGreaterThan: 100),
    $.age(isLessThan: 30),
  ))
  .get();
```

--------------------------------

### Implementing Type-Safe Firestore Pagination with Smart Builder

Source: https://github.com/sylphxltd/firestore_odm/blob/main/packages/firestore_odm_annotation/README.md

This example showcases Firestore ODM's Smart Builder for pagination, designed to eliminate common bugs. It demonstrates how to fetch the first page with specific ordering and then retrieve subsequent pages using `startAfterObject`, which automatically extracts cursor values from the last document of the previous page, ensuring consistent pagination with type safety.

```Dart
// Get first page with ordering
final page1 = await db.users
  .orderBy(($) => ($.followers(descending: true), $.name()))
  .limit(10)
  .get();
```

```Dart
// Get next page with perfect type-safety - zero inconsistency risk
// The same orderBy ensures cursor consistency automatically
final page2 = await db.users
  .orderBy(($) => ($.followers(descending: true), $.name()))
  .startAfterObject(page1.last) // Auto-extracts cursor values
  .limit(10)
  .get();
```

--------------------------------

### Migrating Firestore Document Write Operations to Firestore ODM

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/migration-guide.md

This section compares manual Firestore document creation and updates with the type-safe approach offered by Firestore ODM. It demonstrates how to transition from using raw maps and `FieldValue` to typed models and ODM's `insert()`, `patch()`, and `incrementalModify()` methods for cleaner, more robust data manipulation.

```dart
// Create a document
await usersCollection.doc('user123').set({
  'name': 'John Doe',
  'email': 'john@example.com',
  'age': 30,
  'isActive': true,
  'createdAt': FieldValue.serverTimestamp(),
});

// Update a document
await usersCollection.doc('user123').update({
  'age': FieldValue.increment(1),
  'tags': FieldValue.arrayUnion(['premium']),
  'lastLogin': FieldValue.serverTimestamp(),
});
```

```dart
// Create a document - type-safe model
await db.users.insert(User(
  id: 'user123',
  name: 'John Doe',
  email: 'john@example.com',
  age: 30,
  isActive: true,
));

// Update with three powerful strategies:

// 1. Patch - Explicit atomic operations
await db.users('user123').patch(($) => [
  $.age.increment(1),
  $.tags.add('premium'),
  $.lastLogin.serverTimestamp(),
]);

// 2. IncrementalModify - Smart atomic detection
await db.users('user123').incrementalModify((user) => user.copyWith(
  age: user.age + 1, // Auto-detects -> FieldValue.increment(1)
  tags: [...user.tags, 'premium'], // Auto-detects -> FieldValue.arrayUnion()
  lastLogin: FirestoreODM.serverTimestamp,
));
```

--------------------------------

### Define a User Model with Firestore ODM in Dart

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/getting-started.md

This Dart code defines a `User` data model using `freezed` and `firestore_odm_annotation`. It demonstrates how to mark the document ID field with `@DocumentIdField()` and includes necessary imports for Firestore ODM integration.

```dart
// lib/models/user.dart
import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:firestore_odm_annotation/firestore_odm_annotation.dart';
import 'package:freezed_annotation/freezed_annotation.dart';

part 'user.freezed.dart';
part 'user.g.dart';

@freezed
class User with _$User {
  const factory User({
    // This field is automatically populated with the document ID
    @DocumentIdField() required String id,
    required String name,
    required String email,
    required int age,
    DateTime? lastLogin,
  }) = _User;

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}
```

--------------------------------

### Migrating Firestore Subcollection Access to Type-Safe ODM

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/migration-guide.md

This snippet demonstrates the transition from manual subcollection path construction and untyped data retrieval to type-safe, automatically generated subcollection access using `firestore_odm`. The ODM approach simplifies nested collection navigation and enables fully typed operations, eliminating manual serialization and improving code readability.

```dart
// Manual subcollection access
CollectionReference userPosts = usersCollection
  .doc('user123')
  .collection('posts');

// Manual path construction for nested subcollections
CollectionReference postComments = usersCollection
  .doc('user123')
  .collection('posts')
  .doc('post456')
  .collection('comments');

// No type safety, manual serialization
QuerySnapshot postsSnapshot = await userPosts.get();
List<Map<String, dynamic>> posts = postsSnapshot.docs
  .map((doc) => doc.data() as Map<String, dynamic>)
  .toList();
```

```dart
// Schema definition with subcollections
@Schema()
@Collection<User>("users")
@Collection<Post>("users/*/posts")
@Collection<Comment>("users/*/posts/*/comments")
final appSchema = _$AppSchema;

// Type-safe subcollection access
final userPosts = db.users('user123').posts;
final postComments = db.users('user123').posts('post456').comments;

// Fully typed operations
List<Post> posts = await userPosts.get();
await userPosts.insert(Post(
  id: 'new-post',
  title: 'My New Post',
  content: 'Post content...',
));
```

--------------------------------

### Configure Flutter Desktop Application with CMake

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/linux/runner/CMakeLists.txt

This CMakeLists.txt defines the build process for a Flutter desktop application. It sets the minimum CMake version, defines the project, creates the executable target, includes source files, applies standard build settings, adds preprocessor definitions for the application ID, and links necessary libraries like Flutter and GTK.

```CMake
cmake_minimum_required(VERSION 3.13)
project(runner LANGUAGES CXX)

# Define the application target. To change its name, change BINARY_NAME in the
# top-level CMakeLists.txt, not the value here, or `flutter run` will no longer
# work.
#
# Any new source files that you add to the application should be added here.
add_executable(${BINARY_NAME}
  "main.cc"
  "my_application.cc"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
)

# Apply the standard set of build settings. This can be removed for applications
# that need different build settings.
apply_standard_settings(${BINARY_NAME})

# Add preprocessor definitions for the application ID.
add_definitions(-DAPPLICATION_ID="${APPLICATION_ID}")

# Add dependency libraries. Add any application-specific dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter)
target_link_libraries(${BINARY_NAME} PRIVATE PkgConfig::GTK)

target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")
```

--------------------------------

### Access Firestore Subcollections in Dart

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/subcollections.md

This Dart code illustrates how to access and interact with a defined subcollection. It shows chaining property accessors from a parent document reference (userDoc.posts) to get a subcollection reference, allowing standard collection operations like get() and insert(). It also demonstrates accessing deeply nested subcollections.

```Dart
// Get a reference to a specific user document
final userDoc = db.users('jane-doe');

// Access the 'posts' subcollection for that user
final postsCollection = userDoc.posts;

// Now you can perform any standard collection operation on it
final allPosts = await postsCollection.get();

await postsCollection.insert(
  Post(id: 'my-first-post', title: 'Hello from a subcollection!'),
);

// Example of accessing a nested sub-subcollection
// This would require a "users/*/posts/*/comments" definition in the schema.
final comments = db.users('jane-doe').posts('my-first-post').comments;
```

--------------------------------

### Deleting a Single Document

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/writing-documents.md

Provides an example of how to delete a single document by calling the `.delete()` method on a document reference.

```dart
await db.users('jane-doe').delete();
```

--------------------------------

### Build Flutter Wrapper Application Static Library

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/windows/flutter/CMakeLists.txt

Creates a static library `flutter_wrapper_app` using the core and application-specific C++ wrapper sources. It applies standard build settings, links against the `flutter` interface library, and includes necessary header paths. This library is crucial for the main Flutter application runner.

```CMake
add_library(flutter_wrapper_app STATIC
  ${CPP_WRAPPER_SOURCES_CORE}
  ${CPP_WRAPPER_SOURCES_APP}
)
apply_standard_settings(flutter_wrapper_app)
target_link_libraries(flutter_wrapper_app PUBLIC flutter)
target_include_directories(flutter_wrapper_app PUBLIC
  "${WRAPPER_ROOT}/include"
)
add_dependencies(flutter_wrapper_app flutter_assemble)
```

--------------------------------

### Manual Release Process for Firestore ODM

Source: https://github.com/sylphxltd/firestore_odm/blob/main/CONTRIBUTING.md

Commands for manually versioning packages and publishing them to pub.dev, including a dry run option, using Melos.

```bash
# Version packages
melos version --patch --yes

# Publish (dry run first)
melos run publish:dry-run
melos run publish
```

--------------------------------

### Define C++ Wrapper Source Files for Flutter

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/windows/flutter/CMakeLists.txt

Appends core, plugin, and application-specific C++ wrapper source files to distinct CMake lists. These lists are then transformed to include the full path from the `WRAPPER_ROOT` directory, preparing them for library compilation.

```CMake
list(APPEND CPP_WRAPPER_SOURCES_CORE
  "core_implementations.cc"
  "standard_codec.cc"
)
list(TRANSFORM CPP_WRAPPER_SOURCES_CORE PREPEND "${WRAPPER_ROOT}/")
list(APPEND CPP_WRAPPER_SOURCES_PLUGIN
  "plugin_registrar.cc"
)
list(TRANSFORM CPP_WRAPPER_SOURCES_PLUGIN PREPEND "${WRAPPER_ROOT}/")
list(APPEND CPP_WRAPPER_SOURCES_APP
  "flutter_engine.cc"
  "flutter_view_controller.cc"
)
list(TRANSFORM CPP_WRAPPER_SOURCES_APP PREPEND "${WRAPPER_ROOT}/")
```

--------------------------------

### Integrate Flutter Build System and Dependencies

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/linux/CMakeLists.txt

Includes the Flutter-managed build directory, finds and checks for GTK system dependencies, adds the application's subdirectory, and ensures the main binary depends on the `flutter_assemble` target. It also sets the runtime output directory to prevent running unbundled executables.

```CMake
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})

# System-level dependencies.
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)

# Application build; see runner/CMakeLists.txt.
add_subdirectory("runner")

# Run the Flutter tool portions of the build. This must not be removed.
add_dependencies(${BINARY_NAME} flutter_assemble)

# Only the install-generated bundle's copy of the executable will launch
# correctly, since the resources must in the right relative locations. To avoid
# people trying to run the unbundled copy, put it in a subdirectory instead of
# the default top-level location.
set_target_properties(${BINARY_NAME}
  PROPERTIES
  RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/intermediates_do_not_run"
)
```

--------------------------------

### Run All Quality Checks Before Committing

Source: https://github.com/sylphxltd/firestore_odm/blob/main/CONTRIBUTING.md

Command to execute all pre-commit quality checks, including formatting, static analysis, and tests, using Melos.

```bash
melos run check
```

--------------------------------

### Initialize CMake Project and Define Binary Name

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/windows/CMakeLists.txt

Sets the minimum required CMake version, defines the project name and supported languages (CXX), and specifies the executable's on-disk name. It also explicitly opts into modern CMake policy behaviors to avoid warnings with recent versions.

```CMake
cmake_minimum_required(VERSION 3.14)
project(flutter_example LANGUAGES CXX)

# The name of the executable created for the application. Change this to change
# the on-disk name of your application.
set(BINARY_NAME "flutter_example")

# Explicitly opt in to modern CMake behaviors to avoid warnings with recent
# versions of CMake.
cmake_policy(VERSION 3.14...3.25)
```

--------------------------------

### Configure Flutter Desktop Application Runner with CMake

Source: https://github.com/sylphxltd/firestore_odm/blob/main/apps/flutter_example/windows/runner/CMakeLists.txt

This snippet defines the CMake configuration for the Flutter desktop runner. It sets the minimum CMake version, defines the project, adds the executable target with its source files, applies standard build settings, defines preprocessor macros for versioning and compatibility, links required libraries, and ensures the Flutter tool's build steps are executed.

```CMake
cmake_minimum_required(VERSION 3.14)
project(runner LANGUAGES CXX)

# Define the application target. To change its name, change BINARY_NAME in the
# top-level CMakeLists.txt, not the value here, or `flutter run` will no longer
# work.
#
# Any new source files that you add to the application should be added here.
add_executable(${BINARY_NAME} WIN32
  "flutter_window.cpp"
  "main.cpp"
  "utils.cpp"
  "win32_window.cpp"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
  "Runner.rc"
  "runner.exe.manifest"
)

# Apply the standard set of build settings. This can be removed for applications
# that need different build settings.
apply_standard_settings(${BINARY_NAME})

# Add preprocessor definitions for the build version.
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION=\"${FLUTTER_VERSION}\"")
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_MAJOR=${FLUTTER_VERSION_MAJOR}")
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_MINOR=${FLUTTER_VERSION_MINOR}")
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_PATCH=${FLUTTER_VERSION_PATCH}")
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_BUILD=${FLUTTER_VERSION_BUILD}")

# Disable Windows macros that collide with C++ standard library functions.
target_compile_definitions(${BINARY_NAME} PRIVATE "NOMINMAX")

# Add dependency libraries and include directories. Add any application-specific
# dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter flutter_wrapper_app)
target_link_libraries(${BINARY_NAME} PRIVATE "dwmapi.lib")
target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")

# Run the Flutter tool portions of the build. This must not be removed.
add_dependencies(${BINARY_NAME} flutter_assemble)
```

--------------------------------

### Perform basic count aggregation with Firestore ODM (Dart)

Source: https://github.com/sylphxltd/firestore_odm/blob/main/docs/guide/aggregations.md

Demonstrates how to use the `.count()` method to get the total number of documents or the number of documents matching a specific query in Firestore using the ODM. This is the simplest aggregation available.

```Dart
// Get the total number of users
final userCount = await db.users.count().get();

// Get the number of active users
final activeUserCount = await db.users
  .where(($) => $.isActive(isEqualTo: true))
  .count()
  .get();

print('There are $activeUserCount active users.');
```

--------------------------------

### Perform Bulk Update and Delete Operations in Dart Firestore ODM

Source: https://github.com/sylphxltd/firestore_odm/blob/main/packages/firestore_odm_annotation/README.md

Illustrates how to perform bulk operations on collections based on queries. It shows examples of updating multiple premium users by incrementing points and deleting inactive users efficiently.

```dart
// Update all premium users
await db.users
  .where(($) => $.isPremium(isEqualTo: true))
  .patch(($) => [$.points.increment(100)]);

// Delete inactive users
await db.users
  .where(($) => $.status(isEqualTo: 'inactive'))
  .delete();
```