or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

collections-queries.mdcore-database.mddata-snapshots.mddata-types.mddocument-references.mdindex.mdtransactions-batches.md
tile.json

index.mddocs/

@firebase/firestore-types

@firebase/firestore-types provides comprehensive TypeScript type definitions for Firebase Firestore, serving as the foundational typing system for the Firebase JavaScript SDK's Firestore functionality. This package establishes type contracts for document operations, queries, real-time listeners, transactions, and offline capabilities, ensuring type safety across the entire Firebase ecosystem.

Package Information

  • Package Name: @firebase/firestore-types
  • Package Type: npm
  • Language: TypeScript (definitions only)
  • Installation: npm install @firebase/firestore-types (usually installed as a dependency)

Core Imports

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

Note: This package contains only TypeScript type definitions. In practice, these types are used with the actual Firebase SDK implementations.

Basic Usage

This package is typically used for type annotations when working with Firebase Firestore:

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

// Using with Firestore operations
function saveDocument(
  docRef: DocumentReference<DocumentData>, 
  data: DocumentData
): Promise<void> {
  return docRef.set(data);
}

Architecture

The type definitions are organized around several key concepts:

  • Core Database Types: FirebaseFirestore, DocumentData, UpdateData - fundamental database operations
  • Reference Types: DocumentReference, CollectionReference - typed references to database locations
  • Query System: Query, QuerySnapshot - type-safe query building and results
  • Snapshot Types: DocumentSnapshot, QueryDocumentSnapshot - typed data retrieval
  • Data Types: GeoPoint, Timestamp, Blob, FieldValue - Firestore-specific data types
  • Transaction Types: Transaction, WriteBatch - batch and atomic operations
  • Configuration Types: Settings, PersistenceSettings - database configuration
  • Utility Types: FieldPath, error types, and various options interfaces

Capabilities

Core Database Operations

Fundamental types for database connections, settings, and basic operations.

class FirebaseFirestore {
  settings(settings: Settings): void;
  useEmulator(host: string, port: number, options?: { mockUserToken?: EmulatorMockTokenOptions | string; }): void;
  collection(collectionPath: string): CollectionReference<DocumentData>;
  doc(documentPath: string): DocumentReference<DocumentData>;
}

interface Settings {
  host?: string;
  ssl?: boolean;
  cacheSizeBytes?: number;
  experimentalForceLongPolling?: boolean;
  experimentalAutoDetectLongPolling?: boolean;
  ignoreUndefinedProperties?: boolean;
  merge?: boolean;
}

Core Database Operations

Document References and Operations

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

class DocumentReference<T = DocumentData> {
  readonly id: string;
  readonly path: string;
  set(data: T): Promise<void>;
  set(data: Partial<T>, options: SetOptions): Promise<void>;
  update(data: UpdateData): Promise<void>;
  delete(): Promise<void>;
  get(options?: GetOptions): Promise<DocumentSnapshot<T>>;
  onSnapshot(observer: { next?: (snapshot: DocumentSnapshot<T>) => void; }): () => void;
}

Document References

Collections and Queries

Types for collection references, query building, and query result handling.

class CollectionReference<T = DocumentData> extends Query<T> {
  readonly id: string;
  readonly path: string;
  doc(documentPath?: string): DocumentReference<T>;
  add(data: T): Promise<DocumentReference<T>>;
}

class Query<T = DocumentData> {
  where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: any): Query<T>;
  orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): Query<T>;
  limit(limit: number): Query<T>;
  get(options?: GetOptions): Promise<QuerySnapshot<T>>;
}

Collections and Queries

Data Snapshots

Types for document and query snapshots that represent data retrieved from Firestore.

class DocumentSnapshot<T = DocumentData> {
  readonly exists: boolean;
  readonly id: string;
  readonly metadata: SnapshotMetadata;
  data(options?: SnapshotOptions): T | undefined;
  get(fieldPath: string | FieldPath, options?: SnapshotOptions): any;
}

class QuerySnapshot<T = DocumentData> {
  readonly docs: Array<QueryDocumentSnapshot<T>>;
  readonly size: number;
  readonly empty: boolean;
  docChanges(options?: SnapshotListenOptions): Array<DocumentChange<T>>;
}

Data Snapshots

Firestore Data Types

Specialized data types for Firestore including timestamps, geographic points, binary data, and field values.

class Timestamp {
  constructor(seconds: number, nanoseconds: number);
  static now(): Timestamp;
  static fromDate(date: Date): Timestamp;
  toDate(): Date;
  toMillis(): number;
}

class GeoPoint {
  constructor(latitude: number, longitude: number);
  readonly latitude: number;
  readonly longitude: number;
}

class FieldValue {
  static serverTimestamp(): FieldValue;
  static delete(): FieldValue;
  static arrayUnion(...elements: any[]): FieldValue;
  static increment(n: number): FieldValue;
}

Firestore Data Types

Transactions and Batches

Types for atomic operations, transactions, and batch writes.

class Transaction {
  get<T>(documentRef: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
  set<T>(documentRef: DocumentReference<T>, data: T): Transaction;
  update(documentRef: DocumentReference<any>, data: UpdateData): Transaction;
  delete(documentRef: DocumentReference<any>): Transaction;
}

class WriteBatch {
  set<T>(documentRef: DocumentReference<T>, data: T): WriteBatch;
  update(documentRef: DocumentReference<any>, data: UpdateData): WriteBatch;
  delete(documentRef: DocumentReference<any>): WriteBatch;
  commit(): Promise<void>;
}

Transactions and Batches

Common Types

Base Data Types

type DocumentData = { [field: string]: any };
type UpdateData = { [fieldPath: string]: any };
type LogLevel = 'debug' | 'error' | 'silent' | 'warn' | 'info' | 'verbose';

Error Handling

interface FirestoreError {
  code: FirestoreErrorCode;
  message: string;
  name: string;
  stack?: string;
}

type FirestoreErrorCode = 
  | 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded'
  | 'not-found' | 'already-exists' | 'permission-denied'
  | 'resource-exhausted' | 'failed-precondition' | 'aborted'
  | 'out-of-range' | 'unimplemented' | 'internal'
  | 'unavailable' | 'data-loss' | 'unauthenticated';