tessl/npm-firebase--firestore-types

TypeScript type definitions for Firebase Firestore providing comprehensive type safety for database operations

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Document References

Name: tessl/npm-firebase--firestore-types
Author: tessl

Types for document references and document-level operations including reads, writes, real-time listeners, and data conversion.

Capabilities

DocumentReference Class

Reference to a specific Firestore document, providing type-safe operations.

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>;
}

Options Interfaces

Configuration options for document operations.

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';
}

Usage Examples

Basic Document Operations

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();
}

Real-time Listeners

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;
}

Data Conversion

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);
}