firebase-rest-firestore 1.2.0 → 1.6.0

package/README.md

@@ -134,6 +134,43 @@ Parameters:
 
 Returns: The added document with auto-generated ID.
 
+### FieldValue
+
+Sentinels for special write behaviors, mirroring the native Firebase SDK.
+
+#### FieldValue.serverTimestamp()
+
+Sets the field to the server's request timestamp at write time (rather than an
+unreliable client clock). Works with `add`, `update`, `set`, and `createWithId`,
+including nested fields. The returned document contains the resolved `Date`.
+
+```typescript
+import { createFirestoreClient, FieldValue } from "firebase-rest-firestore";
+
+const client = createFirestoreClient(config);
+
+// On create (auto-generated ID)
+const post = await client.add("posts", {
+  title: "Hello",
+  createdAt: FieldValue.serverTimestamp(),
+});
+console.log(post.createdAt); // Date, set by the server
+
+// On update
+await client.update("posts", post.id, {
+  updatedAt: FieldValue.serverTimestamp(),
+});
+
+// Nested fields are supported too
+await client.collection("posts").doc(post.id).set({
+  meta: { touchedAt: FieldValue.serverTimestamp() },
+});
+```
+
+> Writes containing a `FieldValue` are sent through the Firestore `commit`
+> endpoint so the transform is applied server-side. A `FieldValue` cannot be
+> used inside an array.
+
 ## Error Handling
 
 Firebase REST Firestore throws exceptions with appropriate error messages when API requests fail. Here's an example of error handling:

package/dist/cjs/client.d.ts

@@ -0,0 +1,454 @@
+import { FirestoreConfig, QueryOptions } from "./types";
+/**
+ * Firestore client class
+ */
+export declare class FirestoreClient {
+    private token;
+    private tokenExpiry;
+    private config;
+    private configChecked;
+    private debug;
+    private pathUtil;
+    /**
+     * Constructor
+     * @param config Firestore configuration object
+     */
+    constructor(config: FirestoreConfig);
+    /**
+     * Check configuration parameters
+     * @private
+     */
+    private checkConfig;
+    /**
+     * Get authentication token (with caching)
+     */
+    private getToken;
+    /**
+     * Prepare request headers
+     * @param additionalHeaders Additional headers
+     * @returns Prepared headers object
+     * @private
+     */
+    private prepareHeaders;
+    /**
+     * Build the fully-qualified Firestore reference value for a document path,
+     * e.g. `projects/{projectId}/databases/{databaseId}/documents/{path}`.
+     * Used to encode a DocumentReference without exposing internal path helpers.
+     * @param documentPath Document path (ex: "users/uid/posts/postId")
+     */
+    getReferenceValue(documentPath: string): string;
+    /**
+     * Apply a single write through the `documents:commit` endpoint. This is the
+     * only REST path that supports field transforms (e.g. server timestamps).
+     * @param collectionName Collection path
+     * @param documentId Document ID
+     * @param fields Already-converted Firestore field values
+     * @param transforms Field transforms to apply after the update
+     * @param currentDocument Optional precondition (e.g. `{ exists: false }`)
+     * @private
+     */
+    private commit;
+    /**
+     * Commit a write and read the document back, so the resolved transform
+     * values (e.g. the server timestamp) are returned to the caller.
+     * @private
+     */
+    private commitAndRead;
+    /**
+     * Get collection reference
+     * @param path Collection path
+     * @returns CollectionReference instance
+     */
+    collection(path: string): CollectionReference;
+    /**
+     * Get document reference
+     * @param path Document path
+     * @returns DocumentReference instance
+     */
+    doc(path: string): DocumentReference;
+    /**
+     * Get collection group reference
+     * @param path Collection group ID
+     * @returns CollectionGroup instance
+     */
+    collectionGroup(path: string): CollectionGroup;
+    /**
+     * Add document to Firestore
+     * @param collectionName Collection name
+     * @param data Data to add
+     * @returns Added document
+     */
+    add(collectionName: string, data: Record<string, any>): Promise<Record<string, any> & {
+        id: string;
+    }>;
+    /**
+     * Create a document that contains field transforms (e.g. serverTimestamp)
+     * with an auto-generated ID. Uses the commit endpoint with an
+     * `exists: false` precondition and retries on the (astronomically unlikely)
+     * ID collision, mirroring the uniqueness of server-generated IDs.
+     * @private
+     */
+    private addWithTransforms;
+    /**
+     * Get document
+     * @param collectionName Collection name
+     * @param documentId Document ID
+     * @returns Retrieved document (null if it doesn't exist)
+     */
+    get(collectionName: string, documentId: string): Promise<(Record<string, any> & {
+        id: string;
+    }) | null>;
+    /**
+     * Update document
+     * @param collectionName Collection name
+     * @param documentId Document ID
+     * @param data Data to update
+     * @returns Updated document
+     */
+    update(collectionName: string, documentId: string, data: Record<string, any>): Promise<Record<string, any> & {
+        id: string;
+    }>;
+    /**
+     * Delete document
+     * @param collectionName Collection name
+     * @param documentId Document ID
+     * @returns true if deletion successful
+     */
+    delete(collectionName: string, documentId: string): Promise<boolean>;
+    /**
+     * Query documents in a collection
+     * @param collectionPath Collection path
+     * @param options Query options
+     * @param allDescendants Whether to include descendant collections
+     * @returns Array of documents matching the query
+     */
+    query(collectionPath: string, options?: QueryOptions, allDescendants?: boolean): Promise<(Record<string, any> & {
+        id: string;
+    })[]>;
+    /**
+     * ドキュメントを作成または上書き
+     * @param collectionName コレクション名
+     * @param documentId ドキュメントID
+     * @param data ドキュメントデータ
+     * @returns 作成されたドキュメントのリファレンス
+     */
+    createWithId(collectionName: string, documentId: string, data: Record<string, any>): Promise<Record<string, any> & {
+        id: string;
+    }>;
+}
+/**
+ * Collection reference class
+ */
+export declare class CollectionReference {
+    private client;
+    private _path;
+    private _queryConstraints;
+    constructor(client: FirestoreClient, path: string);
+    /**
+     * Get collection path
+     */
+    get path(): string;
+    /**
+     * Whether to include all descendant collections
+     */
+    get allDescendants(): boolean;
+    /**
+     * Get document reference
+     * @param documentPath Document ID (auto-generated if omitted)
+     * @returns DocumentReference instance
+     */
+    doc(documentPath?: string): DocumentReference;
+    /**
+     * Add document (ID is auto-generated)
+     * @param data Document data
+     * @returns Reference to the created document
+     */
+    add(data: Record<string, any>): Promise<DocumentReference>;
+    /**
+     * Add filter condition
+     * @param fieldPath Field path
+     * @param opStr Operator
+     * @param value Value
+     * @returns Query instance
+     */
+    where(fieldPath: string, opStr: string, value: any): Query;
+    /**
+     * Add sorting condition
+     * @param fieldPath Field path
+     * @param directionStr Sort direction ('asc' or 'desc')
+     * @returns Query instance
+     */
+    orderBy(fieldPath: string, directionStr?: "asc" | "desc"): Query;
+    /**
+     * Set limit on number of results
+     * @param limit Maximum number
+     * @returns Query instance
+     */
+    limit(limit: number): Query;
+    /**
+     * Set number of documents to skip
+     * @param offset Number to skip
+     * @returns Query instance
+     */
+    offset(offset: number): Query;
+    /**
+     * Execute query
+     * @returns QuerySnapshot instance
+     */
+    get(): Promise<QuerySnapshot>;
+    /**
+     * Generate random ID
+     * @returns Random ID
+     */
+    private _generateId;
+}
+/**
+ * Document reference class
+ */
+export declare class DocumentReference {
+    private client;
+    private collectionPath;
+    private docId;
+    constructor(client: FirestoreClient, collectionPath: string, docId: string);
+    /**
+     * Get document ID
+     */
+    get id(): string;
+    /**
+     * Get document path
+     */
+    get path(): string;
+    /**
+     * Fully-qualified Firestore reference value for this document, e.g.
+     * `projects/{projectId}/databases/{databaseId}/documents/{path}`.
+     */
+    get referenceValue(): string;
+    /**
+     * Get parent collection reference
+     */
+    get parent(): CollectionReference;
+    /**
+     * Get subcollection
+     * @param collectionPath Subcollection name
+     * @returns CollectionReference instance
+     */
+    collection(collectionPath: string): CollectionReference;
+    /**
+     * Get document
+     * @returns DocumentSnapshot instance
+     */
+    get(): Promise<DocumentSnapshot>;
+    /**
+     * Create or overwrite document
+     * @param data Document data
+     * @param options Options (merge is not currently supported)
+     * @returns WriteResult instance
+     */
+    set(data: Record<string, any>, options?: {
+        merge?: boolean;
+    }): Promise<WriteResult>;
+    /**
+     * Update document
+     * @param data Update data
+     * @returns WriteResult instance
+     */
+    update(data: Record<string, any>): Promise<WriteResult>;
+    /**
+     * Delete document
+     * @returns WriteResult instance
+     */
+    delete(): Promise<WriteResult>;
+}
+/**
+ * Collection group
+ */
+export declare class CollectionGroup {
+    private client;
+    private path;
+    private _queryConstraints;
+    constructor(client: FirestoreClient, path: string);
+    /**
+     * Whether to include all descendant collections
+     */
+    get allDescendants(): boolean;
+    /**
+     * Add filter condition
+     * @param fieldPath Field path
+     * @param opStr Operator
+     * @param value Value
+     * @returns Query instance
+     */
+    where(fieldPath: string, opStr: string, value: any): Query;
+    /**
+     * Add sorting condition
+     * @param fieldPath Field path
+     * @param directionStr Sort direction ('asc' or 'desc')
+     * @returns Query instance
+     */
+    orderBy(fieldPath: string, directionStr?: "asc" | "desc"): Query;
+    /**
+     * Set limit on number of results
+     * @param limit Maximum number
+     * @returns Query instance
+     */
+    limit(limit: number): Query;
+    /**
+     * Set number of documents to skip
+     * @param offset Number to skip
+     * @returns Query instance
+     */
+    offset(offset: number): Query;
+    /**
+     * Execute query
+     * @returns QuerySnapshot instance
+     */
+    get(): Promise<QuerySnapshot>;
+}
+/**
+ * Query class
+ */
+export declare class Query {
+    private client;
+    private collectionPath;
+    private allDescendants;
+    _queryConstraints: {
+        where: Array<{
+            field: string;
+            op: string;
+            value: any;
+        }>;
+        orderBy?: string;
+        orderDirection?: string;
+        limit?: number;
+        offset?: number;
+    };
+    constructor(client: FirestoreClient, collectionPath: string, constraints: {
+        where: Array<{
+            field: string;
+            op: string;
+            value: any;
+        }>;
+        orderBy?: string;
+        orderDirection?: string;
+        limit?: number;
+        offset?: number;
+    }, allDescendants: boolean);
+    /**
+     * Add filter condition
+     * @param fieldPath Field path
+     * @param opStr Operator
+     * @param value Value
+     * @returns Query instance
+     */
+    where(fieldPath: string, opStr: string, value: any): Query;
+    /**
+     * Add sorting condition
+     * @param fieldPath Field path
+     * @param directionStr Sort direction ('asc' or 'desc')
+     * @returns Query instance
+     */
+    orderBy(fieldPath: string, directionStr?: "asc" | "desc"): Query;
+    /**
+     * Set limit on number of results
+     * @param limit Maximum number
+     * @returns Query instance
+     */
+    limit(limit: number): Query;
+    /**
+     * Set number of documents to skip
+     * @param offset Number to skip
+     * @returns Query instance
+     */
+    offset(offset: number): Query;
+    /**
+     * Execute query
+     * @returns QuerySnapshot instance
+     */
+    get(): Promise<QuerySnapshot>;
+}
+/**
+ * Query result class
+ */
+export declare class QuerySnapshot {
+    private _docs;
+    constructor(results: Array<Record<string, any>>);
+    /**
+     * Array of documents in the result
+     */
+    get docs(): DocumentSnapshot[];
+    /**
+     * Whether the result is empty
+     */
+    get empty(): boolean;
+    /**
+     * Number of results
+     */
+    get size(): number;
+    /**
+     * Execute callback for each document
+     * @param callback Callback function to execute for each document
+     */
+    forEach(callback: (result: DocumentSnapshot) => void): void;
+}
+/**
+ * Document snapshot class
+ */
+export declare class DocumentSnapshot {
+    private _id;
+    private _data;
+    constructor(id: string, data: Record<string, any> | null);
+    /**
+     * Document ID
+     */
+    get id(): string;
+    /**
+     * Whether the document exists
+     */
+    get exists(): boolean;
+    /**
+     * Get document data
+     * @returns Document data (undefined if it doesn't exist)
+     */
+    data(): Record<string, any> | undefined;
+}
+/**
+ * Write result class
+ */
+export declare class WriteResult {
+    /**
+     * Write timestamp
+     */
+    readonly writeTime: Date;
+    constructor();
+}
+/**
+ * Create a new Firestore client instance
+ * @param config Firestore configuration object
+ * @returns FirestoreClient instance
+ *
+ * @example
+ * // Connect to default database
+ * const db = createFirestoreClient({
+ *   projectId: 'your-project-id',
+ *   privateKey: 'your-private-key',
+ *   clientEmail: 'your-client-email'
+ * });
+ *
+ * // Connect to a different named database
+ * const customDb = createFirestoreClient({
+ *   projectId: 'your-project-id',
+ *   privateKey: 'your-private-key',
+ *   clientEmail: 'your-client-email',
+ *   databaseId: 'your-database-id'
+ * });
+ *
+ * // Connect to local emulator (no auth required)
+ * const emulatorDb = createFirestoreClient({
+ *   projectId: 'demo-project',
+ *   useEmulator: true,
+ *   emulatorHost: '127.0.',
+ *   emulatorPort: 8080,
+ *   debug: true // Optional: enables detailed logging
+ * });
+ */
+export declare function createFirestoreClient(config: FirestoreConfig): FirestoreClient;