getDocRefByIdWithConverter method

DocumentReference<T> getDocRefByIdWithConverter({
  1. required String id,
  2. String? collectionPathOverride,
})

Gets a document reference with type conversion

Returns DocumentReference with automatic conversion between Firestore and T Requires _fromJson and _toJson configuration

Parameters: id unique identifier of the document collectionPathOverride override path for collection groups

Features:

  • Automatic type conversion
  • Local ID field management
  • Document reference handling
  • Type-safe operations

Example:

final docRef = api.getDocRefByIdWithConverter<User>(id: 'user-123');
final snapshot = await docRef.get();
if (snapshot.exists) {
  final user = snapshot.data();
  print('User name ${user.name}');
}

See also:

Implementation

DocumentReference<T> getDocRefByIdWithConverter({
  required String id,
  String? collectionPathOverride,
}) {
  assert(
    _isCollectionGroup == (collectionPathOverride != null),
    'Firestore does not support finding a document by id when communicating with a collection group, '
    'therefore, you must specify the collectionPathOverride containing all parent collection and document ids '
    'in order to make this method work.',
  );
  _log.debug(
    message: 'Finding document with converter..',
    sensitiveData: SensitiveData(
      path: collectionPathOverride ?? _collectionPath(),
      id: id,
    ),
  );
  return _firebaseFirestore
      .doc('${collectionPathOverride ?? _collectionPath()}/$id')
      .withConverter<T>(
    fromFirestore: (snapshot, _) {
      final data = snapshot.data() ?? {};
      try {
        return _fromJson!(
          data
              .tryAddLocalId(
                snapshot.id,
                idFieldName: _idFieldName,
                tryAddLocalId: _tryAddLocalId,
              )
              .tryAddLocalDocumentReference(
                snapshot.reference,
                referenceFieldName: _documentReferenceFieldName,
                tryAddLocalDocumentReference: _tryAddLocalDocumentReference,
              ),
        );
      } catch (error, stackTrace) {
        _log.error(
          message:
              'Unexpected error caught while adding local id and document reference',
          sensitiveData: SensitiveData(
            path: collectionPathOverride ?? _collectionPath(),
            id: snapshot.id,
            data: data,
          ),
          error: InvalidJsonException(
            id: snapshot.id,
            path: snapshot.reference.path,
            api: runtimeType.toString(),
            data: data,
          ),
          stackTrace: stackTrace,
        );
        try {
          return _fromJsonError!(
            data
                .tryAddLocalId(
                  snapshot.id,
                  idFieldName: _idFieldName,
                  tryAddLocalId: _tryAddLocalId,
                )
                .tryAddLocalDocumentReference(
                  snapshot.reference,
                  referenceFieldName: _documentReferenceFieldName,
                  tryAddLocalDocumentReference: _tryAddLocalDocumentReference,
                ),
          );
        } catch (error, stackTrace) {
          _log.error(
            message:
                'Unexpected error caught while adding local id and document reference',
            sensitiveData: SensitiveData(
              path: collectionPathOverride ?? _collectionPath(),
              id: snapshot.id,
              data: data,
            ),
            error: error,
            stackTrace: stackTrace,
          );
          rethrow;
        }
      }
    },
    toFirestore: (data, _) {
      try {
        return _toJson!(data)
            .tryRemoveLocalId(
              idFieldName: _idFieldName,
              tryRemoveLocalId: _tryAddLocalId,
            )
            .tryRemoveLocalDocumentReference(
              referenceFieldName: _documentReferenceFieldName,
              tryRemoveLocalDocumentReference: _tryAddLocalDocumentReference,
            );
      } catch (error) {
        _log.error(
          message:
              'Unexpected error caught while removing local id and document reference',
          sensitiveData: SensitiveData(
            path: collectionPathOverride ?? _collectionPath(),
            id: id,
            data: data,
          ),
        );
        rethrow;
      }
    },
  );
}