Document References

class DocumentReference<T = DocumentData, T2 extends DocumentData = DocumentData> {
  private constructor();
  
  /** Document ID */
  readonly id: string;
  
  /** Firestore instance this reference belongs to */
  readonly firestore: FirebaseFirestore;
  
  /** Parent collection reference */
  readonly parent: CollectionReference<T>;
  
  /** Full document path */
  readonly path: string;
  
  /** Get a collection reference nested under this document */
  collection(collectionPath: string): CollectionReference<DocumentData>;
  
  /** Check if this reference equals another */
  isEqual(other: DocumentReference<T>): boolean;
  
  /** Set document data, replacing existing data */
  set(data: T): Promise<void>;
  set(data: Partial<T>, options: SetOptions): Promise<void>;
  
  /** Update specific fields in the document */
  update(data: UpdateData): Promise<void>;
  update(
    field: string | FieldPath,
    value: any,
    ...moreFieldsAndValues: any[]
  ): Promise<void>;
  
  /** Delete this document */
  delete(): Promise<void>;
  
  /** Read the document once */
  get(options?: GetOptions): Promise<DocumentSnapshot<T>>;
  
  /** Listen for document changes */
  onSnapshot(observer: {
    next?: (snapshot: DocumentSnapshot<T>) => void;
    error?: (error: FirestoreError) => void;
    complete?: () => void;
  }): () => void;
  onSnapshot(
    options: SnapshotListenOptions,
    observer: {
      next?: (snapshot: DocumentSnapshot<T>) => void;
      error?: (error: FirestoreError) => void;
      complete?: () => void;
    }
  ): () => void;
  onSnapshot(
    onNext: (snapshot: DocumentSnapshot<T>) => void,
    onError?: (error: FirestoreError) => void,
    onCompletion?: () => void
  ): () => void;
  onSnapshot(
    options: SnapshotListenOptions,
    onNext: (snapshot: DocumentSnapshot<T>) => void,
    onError?: (error: FirestoreError) => void,
    onCompletion?: () => void
  ): () => void;
  
  /** Convert this reference to use a different data type */
  withConverter(converter: null): DocumentReference<DocumentData>;
  withConverter<U>(converter: FirestoreDataConverter<U>): DocumentReference<U>;
}

interface SetOptions {
  /** Merge with existing data instead of replacing */
  readonly merge?: boolean;
  
  /** Specific fields to merge */
  readonly mergeFields?: (string | FieldPath)[];
}

interface GetOptions {
  /** Source preference for reads */
  readonly source?: 'default' | 'server' | 'cache';
}

interface SnapshotListenOptions {
  /** Include metadata changes in listener callbacks */
  readonly includeMetadataChanges?: boolean;
}

interface SnapshotOptions {
  /** How to handle server timestamps */
  readonly serverTimestamps?: 'estimate' | 'previous' | 'none';
}

import type { DocumentReference, DocumentData } from "@firebase/firestore-types";

// Type-safe document operations
async function manageDocument(
  docRef: DocumentReference<{ name: string; age: number }>,
  userData: { name: string; age: number }
) {
  // Create or replace document
  await docRef.set(userData);
  
  // Update specific fields
  await docRef.update({ age: userData.age + 1 });
  
  // Read document
  const snapshot = await docRef.get();
  if (snapshot.exists) {
    const data = snapshot.data(); // Typed as { name: string; age: number }
    console.log('User:', data?.name);
  }
  
  // Delete document
  await docRef.delete();
}

import type { DocumentReference, DocumentSnapshot } from "@firebase/firestore-types";

function listenToDocument(docRef: DocumentReference<{ count: number }>) {
  // Listen with observer pattern
  const unsubscribe = docRef.onSnapshot({
    next: (snapshot: DocumentSnapshot<{ count: number }>) => {
      if (snapshot.exists) {
        const data = snapshot.data();
        console.log('Current count:', data?.count);
      }
    },
    error: (error) => {
      console.error('Listener error:', error);
    },
    complete: () => {
      console.log('Listener completed');
    }
  });
  
  // Stop listening
  return unsubscribe;
}

import type { FirestoreDataConverter, QueryDocumentSnapshot, SnapshotOptions } from "@firebase/firestore-types";

interface User {
  name: string;
  email: string;
  createdAt: Date;
}

const userConverter: FirestoreDataConverter<User> = {
  toFirestore(user: User): DocumentData {
    return {
      name: user.name,
      email: user.email,
      createdAt: user.createdAt
    };
  },
  
  fromFirestore(snapshot: QueryDocumentSnapshot, options: SnapshotOptions): User {
    const data = snapshot.data(options);
    return {
      name: data.name,
      email: data.email,
      createdAt: data.createdAt.toDate()
    };
  }
};

// Use with document reference
function getTypedReference(docRef: DocumentReference) {
  return docRef.withConverter(userConverter);
}