import { type DocumentData, DocumentReference, DocumentSnapshot, Transaction, WriteBatch } from 'firebase/firestore'; import { type FirestoreData, type FirestoreKey, type FirestoreObject, type FirestoreValue } from './types.js'; /** * Abstract base class for Firestore documents * Used for type-safe batch operations */ export declare abstract class BaseFirestoreDocument { abstract save(force?: boolean, transaction?: Transaction | WriteBatch): Promise; abstract delete(transaction?: Transaction | WriteBatch): Promise; } /** * ActiveRecord-style Firestore document class with change tracking * @template Key - Document key type (object with key fields or string array) * @template Data - Document data type extending FirestoreData */ export declare class FirestoreDocument extends BaseFirestoreDocument { get static(): typeof FirestoreDocument; /** * Path template for building document paths (e.g., "users/{userId}/posts/{postId}") * Override in subclasses to define the document path structure */ static pathTemplate: string; /** * Database ID to use for this document class * Override in subclasses to use a specific database (default: '') */ static databaseId: string; /** * Default key for new documents * Override in subclasses to provide custom default key (e.g., using newId() or timeId()) * Use getter to generate new IDs on each access */ static get defaultKey(): FirestoreKey | string[] | object | undefined; /** * Default data for new documents * Override in subclasses to provide custom default values * Use getter to generate fresh default values on each access (e.g., new Date()) */ static get defaultData(): FirestoreData | object | undefined; reference?: DocumentReference; private _key?; private readonly _data; /** Proxy wrapper for _data that tracks changes and provides dynamic _id access */ private readonly _proxyData; private _exists; private _isLoaded; /** Tracks old values of changed fields for rollback */ private readonly _updated; /** Indicates if all fields should be saved (set operation) */ private _updatedAll; /** Queues for async snapshot generators */ private _snapshotQueues; /** Unsubscribe function for real-time listener */ private _unwatch?; /** Cached snapshot generator */ private _snapshotGenerator?; /** * Document key used to identify this document */ get key(): Key | undefined; /** * Document ID from Firestore */ get id(): string; /** * Document data accessible via Proxy for change tracking */ get data(): Data; /** * Whether this document exists in Firestore */ get exists(): boolean; /** * Whether this document is new (not yet saved to Firestore) */ get isNew(): boolean; /** * Whether this document has unsaved changes */ get isDirty(): boolean; /** * Whether this document has been loaded from Firestore */ get isLoaded(): boolean; constructor(keyOrRef?: Key | string | DocumentReference, data?: Partial | DocumentSnapshot | null, exists?: boolean); /** * Loads document data from Firestore * @param transaction - Optional transaction to use for the read * @param cache - If true and document already loaded, skip loading * @returns This document instance */ get(transaction?: Transaction, cache?: boolean): Promise; /** * Overwrites the entire document in Firestore * @param data - Optional data to set (uses current data if undefined) * @param transaction - Optional transaction or batch to use */ set(data?: Data, transaction?: Transaction | WriteBatch): Promise; /** * Updates only changed fields in Firestore * @param transaction - Optional transaction or batch to use */ update(transaction?: Transaction | WriteBatch): Promise; /** * Saves document to Firestore (auto-detects whether to set or update) * @param force - If true, always uses set() instead of update() * @param transaction - Optional transaction or batch to use */ save(force?: boolean, transaction?: Transaction | WriteBatch): Promise; /** * Recursively serializes a plain object for Firestore storage * Iterates through all properties and serializes each value * @param obj - Plain object to serialize * @returns Serialized object ready for Firestore */ protected serializeObject(obj: FirestoreObject): FirestoreObject; /** * Recursively serializes a value for Firestore storage * Converts Date objects to Timestamp and recursively processes nested structures * Override this method in subclasses to add custom type conversions * @param value - The value to serialize * @returns The serialized value ready for Firestore */ protected serializeValue(value: FirestoreValue): FirestoreValue; /** * Recursively unserializes a plain object from Firestore * Iterates through all properties and unserializes each value * @param obj - Plain object to unserialize * @returns Unserialized object with JavaScript types */ protected unserializeObject(obj: FirestoreObject): FirestoreObject; /** * Recursively unserializes a value from Firestore * Converts Timestamp objects to Date and recursively processes nested structures * Override this method in subclasses to add custom type conversions * @param value - The value to unserialize * @returns The unserialized value with JavaScript types */ protected unserializeValue(value: FirestoreValue): FirestoreValue; /** * Serializes document data for Firestore storage * @param data - Document data to serialize * @param updatedValues - Optional map of updated fields (serializes only these if provided) * @returns Serialized data ready for Firestore */ protected serialize(data: FirestoreObject, updatedValues?: Map): FirestoreObject; /** * Unserializes document data from Firestore * @param data - Firestore data to unserialize * @returns Unserialized data with JavaScript types */ protected unserialize(data: FirestoreObject): FirestoreObject; /** * Called before saving document to Firestore * Override this method in subclasses to add validation or data transformation * @throws Error if validation fails - the save operation will be aborted */ protected beforeSave(): void; /** * Clears update tracking and marks document as existing after a successful save * Override this method in subclasses to add custom post-save logic */ protected afterSave(): void; /** * Sets a single field value and tracks the change * @param key - Field name * @param value - New value (undefined marks field for deletion) */ protected setValue(key: string, value: unknown): void; /** * Replaces document data and updates change tracking * @param data - New data or snapshot * @param updatedAll - Whether to mark all fields as updated * @returns true if data was changed, false if identical */ protected setData(data: Data | DocumentSnapshot, updatedAll?: boolean): boolean; /** * Deletes document from Firestore * @param transaction - Optional transaction or batch to use */ delete(transaction?: Transaction | WriteBatch): Promise; /** * Returns a deep copy of the document data including _id * @returns Deep cloned document data with _id from reference */ toObject(): Data; /** * Watches document for real-time updates * @param callback - Called when document data changes * @returns Function to cancel the watch */ watch(callback?: (data?: Data) => void): () => void; /** * Cancels all active snapshot listeners */ unwatch(): void; /** * Gets an async generator for document snapshots * Returns the same generator instance on subsequent calls * @yields Document instances on each change */ get snapshot(): AsyncGenerator>; /** * Sets the document key from a Key object or path string * @param keyOrPath - Document key object or path string */ protected setKey(keyOrPath: Key | string): void; /** * Sets the document reference and extracts the key from its path * @param ref - Firestore document reference */ protected setReference(ref: DocumentReference): void; /** * Updates document data and metadata from a Firestore snapshot * Sets _exists flag, extracts document ID and key, and unserializes data * @param snapshot - Firestore document snapshot */ setDataFromSnapshot(snapshot: DocumentSnapshot): void; } //# sourceMappingURL=document.d.ts.map