firebase-rest-firestore 1.2.0 → 1.5.0

package/dist/{client.js → cjs/client.js}

@@ -6,24 +6,30 @@ const auth_1 = require("./utils/auth");
 const converter_1 = require("./utils/converter");
 const path_1 = require("./utils/path");
 const config_1 = require("./utils/config");
+const path_2 = require("./utils/path");
 /**
- * Firestoreクライアントクラス
+ * Firestore client class
  */
 class FirestoreClient {
     /**
-     * コンストラクタ
-     * @param config Firestore設定オブジェクト
+     * Constructor
+     * @param config Firestore configuration object
      */
     constructor(config) {
         this.token = null;
         this.tokenExpiry = 0;
         this.configChecked = false;
+        this.debug = false;
         this.config = config;
-        // ビルド時にはチェックを行わない
-        // 実際の操作時に遅延チェックを行う
+        this.pathUtil = (0, path_2.createFirestorePath)(config, config.debug || false);
+        this.debug = !!config.debug;
+        // Log configuration if debug is enabled
+        if (this.debug) {
+            console.log("Firestore client initialized with config:", JSON.stringify(this.config, null, 2));
+        }
     }
     /**
-     * 設定パラメータをチェック
+     * Check configuration parameters
      * @private
      */
     checkConfig() {
@@ -31,11 +37,11 @@ class FirestoreClient {
             return;
         }
         // 必須パラメータのチェック
-        const requiredParams = [
-            "projectId",
-            "privateKey",
-            "clientEmail",
-        ];
+        const requiredParams = ["projectId"];
+        // Only require auth parameters when not using emulator
+        if (!this.config.useEmulator) {
+            requiredParams.push("privateKey", "clientEmail");
+        }
         const missingParams = requiredParams.filter(param => !this.config[param]);
         if (missingParams.length > 0) {
             throw new Error(`Missing required Firestore configuration parameters: ${missingParams.join(", ")}`);
@@ -43,14 +49,24 @@ class FirestoreClient {
         this.configChecked = true;
     }
     /**
-     * 認証トークンを取得（キャッシュあり）
+     * Get authentication token (with caching)
      */
     async getToken() {
-        // 操作前に設定をチェック
+        // Check settings before operation
         this.checkConfig();
+        // In emulator mode, we don't need a token
+        if (this.config.useEmulator) {
+            if (this.debug) {
+                console.log("Emulator mode: skipping token generation");
+            }
+            return "emulator-fake-token";
+        }
         const now = Date.now();
         // トークンが期限切れか未取得の場合は新しく取得
         if (!this.token || now >= this.tokenExpiry) {
+            if (this.debug) {
+                console.log("Generating new auth token");
+            }
             this.token = await (0, auth_1.getFirestoreToken)(this.config);
             // 50分後に期限切れとする（実際は1時間）
             this.tokenExpiry = now + 50 * 60 * 1000;
@@ -58,23 +74,44 @@ class FirestoreClient {
         return this.token;
     }
     /**
-     * コレクションリファレンスを取得
-     * @param path コレクションパス
-     * @returns CollectionReferenceインスタンス
+     * Prepare request headers
+     * @param additionalHeaders Additional headers
+     * @returns Prepared headers object
+     * @private
+     */
+    async prepareHeaders(additionalHeaders = {}) {
+        const headers = {
+            "Content-Type": "application/json",
+            ...additionalHeaders,
+        };
+        // Only add auth token for production environment
+        if (!this.config.useEmulator) {
+            const token = await this.getToken();
+            headers["Authorization"] = `Bearer ${token}`;
+        }
+        else if (this.debug) {
+            console.log("Using emulator mode, skipping authorization header");
+        }
+        return headers;
+    }
+    /**
+     * Get collection reference
+     * @param path Collection path
+     * @returns CollectionReference instance
      */
     collection(path) {
-        // 設定チェックは実際の操作時に行われる
+        // Configuration check is performed at the time of actual operation
         return new CollectionReference(this, path);
     }
     /**
-     * ドキュメントリファレンスを取得
-     * @param path ドキュメントパス
-     * @returns DocumentReferenceインスタンス
+     * Get document reference
+     * @param path Document path
+     * @returns DocumentReference instance
      */
     doc(path) {
-        // 設定チェックは実際の操作時に行われる
+        // Configuration check is performed at the time of actual operation
         const parts = path.split("/");
-        if (parts.length % 2 === 0) {
+        if (parts.length % 2 !== 0) {
             throw new Error("Invalid document path. Document path must point to a document, not a collection.");
         }
         const collectionPath = parts.slice(0, parts.length - 1).join("/");
@@ -82,81 +119,116 @@ class FirestoreClient {
         return new DocumentReference(this, collectionPath, docId);
     }
     /**
-     * コレクショングループリファレンスを取得
-     * @param path コレクショングループのID
-     * @returns CollectionGroupインスタンス
+     * Get collection group reference
+     * @param path Collection group ID
+     * @returns CollectionGroup instance
      */
     collectionGroup(path) {
         return new CollectionGroup(this, path);
     }
     /**
-     * Firestoreにドキュメントを追加
-     * @param collectionName コレクション名
-     * @param data 追加するデータ
-     * @returns 追加されたドキュメント
+     * Add document to Firestore
+     * @param collectionName Collection name
+     * @param data Data to add
+     * @returns Added document
      */
     async add(collectionName, data) {
-        // 操作前に設定をチェック
+        // Check settings before operation
         this.checkConfig();
-        const url = (0, path_1.getFirestoreBasePath)(this.config.projectId, collectionName, this.config.databaseId);
+        if (this.debug) {
+            console.log(`Adding document to collection: ${collectionName}`, data);
+        }
+        const url = this.pathUtil.getCollectionPath(collectionName);
         const firestoreData = (0, converter_1.convertToFirestoreDocument)(data);
-        const token = await this.getToken();
+        if (this.debug) {
+            console.log(`Making request to: ${url}`, firestoreData);
+        }
+        const headers = await this.prepareHeaders();
         const response = await fetch(url, {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${token}`,
-            },
+            headers,
             body: JSON.stringify(firestoreData),
         });
+        if (this.debug) {
+            console.log(`Response status: ${response.status}`);
+        }
         if (!response.ok) {
-            throw new Error(`Firestore API error: ${response.statusText}`);
+            const errorText = await response.text();
+            if (this.debug) {
+                console.error(`Error response: ${errorText}`);
+            }
+            throw new Error(`Firestore API error: ${response.statusText || response.status} - ${errorText}`);
         }
         const result = (await response.json());
         return (0, converter_1.convertFromFirestoreDocument)(result);
     }
     /**
-     * ドキュメントを取得
-     * @param collectionName コレクション名
-     * @param documentId ドキュメントID
-     * @returns 取得したドキュメント（存在しない場合はnull）
+     * Get document
+     * @param collectionName Collection name
+     * @param documentId Document ID
+     * @returns Retrieved document (null if it doesn't exist)
      */
     async get(collectionName, documentId) {
-        // 操作前に設定をチェック
+        // Check settings before operation
         this.checkConfig();
-        const url = `${(0, path_1.getFirestoreBasePath)(this.config.projectId, collectionName, this.config.databaseId)}/${documentId}`;
-        const token = await this.getToken();
-        const response = await fetch(url, {
-            method: "GET",
-            headers: {
-                Authorization: `Bearer ${token}`,
-            },
-        });
-        if (response.status === 404) {
-            return null;
+        if (this.debug) {
+            console.log(`Getting document from collection: ${collectionName}, documentId: ${documentId}`);
         }
-        if (!response.ok) {
-            throw new Error(`Firestore API error: ${response.statusText}`);
+        const url = this.pathUtil.getDocumentPath(collectionName, documentId);
+        if (this.debug) {
+            console.log(`Making request to: ${url}`);
+        }
+        const headers = await this.prepareHeaders();
+        try {
+            const response = await fetch(url, {
+                method: "GET",
+                headers,
+            });
+            if (this.debug) {
+                console.log(`Response status: ${response.status}`);
+            }
+            // Capture response text for debugging
+            const responseText = await response.text();
+            if (this.debug) {
+                console.log(`Response text: ${responseText.substring(0, 200)}${responseText.length > 200 ? "..." : ""}`);
+            }
+            if (response.status === 404) {
+                return null;
+            }
+            if (!response.ok) {
+                throw new Error(`Firestore API error: ${response.statusText || response.status} - ${responseText}`);
+            }
+            // Parse the response text
+            const result = JSON.parse(responseText);
+            return (0, converter_1.convertFromFirestoreDocument)(result);
+        }
+        catch (error) {
+            console.error("Error in get method:", error);
+            throw error;
         }
-        const result = (await response.json());
-        return (0, converter_1.convertFromFirestoreDocument)(result);
     }
     /**
-     * ドキュメントを更新
-     * @param collectionName コレクション名
-     * @param documentId ドキュメントID
-     * @param data 更新するデータ
-     * @returns 更新されたドキュメント
+     * Update document
+     * @param collectionName Collection name
+     * @param documentId Document ID
+     * @param data Data to update
+     * @returns Updated document
      */
     async update(collectionName, documentId, data) {
-        // 操作前に設定をチェック
+        // Check settings before operation
         this.checkConfig();
-        const url = `${(0, path_1.getFirestoreBasePath)(this.config.projectId, collectionName, this.config.databaseId)}/${documentId}`;
-        // 既存のドキュメントを取得してからマージする
+        if (this.debug) {
+            console.log(`Updating document in collection: ${collectionName}, documentId: ${documentId}`, data);
+        }
+        const url = this.pathUtil.getDocumentPath(collectionName, documentId);
+        if (this.debug) {
+            console.log(`Making request to: ${url}`);
+        }
+        // Get existing document and merge
         const existingDoc = await this.get(collectionName, documentId);
         if (existingDoc) {
-            // ネストしたフィールドの対応
-            // data内にドット記法のキーがあるかチェック (例: "favorites.color")
+            // Check for nested fields
+            // Check if data contains dot notation keys (e.g., "favorites.color")
             const updateData = { ...data };
             const dotNotationKeys = Object.keys(data).filter(key => key.includes("."));
             if (dotNotationKeys.length > 0) {
@@ -195,186 +267,263 @@ class FirestoreClient {
             }
         }
         const firestoreData = (0, converter_1.convertToFirestoreDocument)(data);
-        const token = await this.getToken();
+        const headers = await this.prepareHeaders();
         const response = await fetch(url, {
             method: "PATCH",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${token}`,
-            },
+            headers,
             body: JSON.stringify(firestoreData),
         });
+        if (this.debug) {
+            console.log(`Response status: ${response.status}`);
+        }
         if (!response.ok) {
-            throw new Error(`Firestore API error: ${response.statusText}`);
+            const errorText = await response.text();
+            if (this.debug) {
+                console.error(`Error response: ${errorText}`);
+            }
+            throw new Error(`Firestore API error: ${response.statusText || response.status} - ${errorText}`);
         }
         const result = (await response.json());
         return (0, converter_1.convertFromFirestoreDocument)(result);
     }
     /**
-     * ドキュメントを削除
-     * @param collectionName コレクション名
-     * @param documentId ドキュメントID
-     * @returns 削除成功時はtrue
+     * Delete document
+     * @param collectionName Collection name
+     * @param documentId Document ID
+     * @returns true if deletion successful
      */
     async delete(collectionName, documentId) {
-        // 操作前に設定をチェック
+        // Check settings before operation
         this.checkConfig();
-        const url = `${(0, path_1.getFirestoreBasePath)(this.config.projectId, collectionName, this.config.databaseId)}/${documentId}`;
-        const token = await this.getToken();
+        if (this.debug) {
+            console.log(`Deleting document from collection: ${collectionName}, documentId: ${documentId}`);
+        }
+        const url = this.pathUtil.getDocumentPath(collectionName, documentId);
+        if (this.debug) {
+            console.log(`Making request to: ${url}`);
+        }
+        // Different header handling for emulator
+        const headers = {};
+        // Only add auth token for production environment
+        if (!this.config.useEmulator) {
+            const token = await this.getToken();
+            headers["Authorization"] = `Bearer ${token}`;
+        }
         const response = await fetch(url, {
             method: "DELETE",
-            headers: {
-                Authorization: `Bearer ${token}`,
-            },
+            headers,
         });
+        if (this.debug) {
+            console.log(`Response status: ${response.status}`);
+        }
         if (!response.ok) {
-            throw new Error(`Firestore API error: ${response.statusText}`);
+            const errorText = await response.text();
+            if (this.debug) {
+                console.error(`Error response: ${errorText}`);
+            }
+            throw new Error(`Firestore API error: ${response.statusText || response.status} - ${errorText}`);
         }
         return true;
     }
     /**
-     * コレクションのドキュメントを検索
-     * @param collectionPath コレクションパス
-     * @param options クエリオプション
-     * @param allDescendants 子孫コレクションを含むかどうか
-     * @returns 検索結果のドキュメント配列
+     * 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
      */
-    async query(collectionPath, options = {}, allDescendants) {
-        // 操作前に設定をチェック
+    async query(collectionPath, options = {}, allDescendants = false) {
+        // Check settings before operation
         this.checkConfig();
-        // :runQueryはコレクション単位ではなく、ドキュメントルート単位で実行
-        // コレクション名パス形式の場合は、endpointをドキュメントルートに置き換える。collectionNameはコレクションIDにする
-        // e.g) パス形式: collectionPath = "/users/123/items" の場合は、collectionPaths = ["users", "123", "items"], collectionName = "items", basePath += "/users/123"
-        // e.g) 単一形式: collectionPath = "items" の場合は、collectionPaths = ["items"], collectionName = "items", basePath += ""
-        const collectionPaths = collectionPath.split("/");
-        let basePath = `https://firestore.googleapis.com/v1/projects/${this.config.projectId}/databases/${this.config.databaseId || "(default)"}/documents`;
-        let collectionName = collectionPath;
-        if (collectionPaths.length > 1) {
-            basePath = `${basePath}/${collectionPaths.slice(0, -1).join("/")}`;
-            collectionName = collectionPaths[collectionPaths.length - 1];
-        }
-        const url = `${basePath}:runQuery`;
-        // クエリ構築
-        //allDescendants: falseの場合は直下のcollectionを参照。trueの場合は子孫コレクションも参照
-        const structuredQuery = {
-            from: [
-                {
-                    collectionId: collectionName,
-                    allDescendants,
+        try {
+            // Parse the collection path
+            const segments = collectionPath.split("/");
+            const collectionId = segments[segments.length - 1];
+            // Get the proper runQuery URL from our path helper
+            const queryUrl = this.pathUtil.getRunQueryPath(collectionPath);
+            if (this.debug) {
+                console.log(`Executing query on collection: ${collectionPath}`);
+                console.log(`Using runQuery URL: ${queryUrl}`);
+            }
+            // Create the structured query
+            const requestBody = {
+                structuredQuery: {
+                    from: [
+                        {
+                            collectionId,
+                            allDescendants,
+                        },
+                    ],
                 },
-            ],
-        };
-        // フィルター条件
-        if (options.where && options.where.length > 0) {
-            // シンプルなケース: 1つの条件の場合
-            if (options.where.length === 1) {
-                const condition = options.where[0];
-                structuredQuery.where = {
-                    fieldFilter: {
-                        field: { fieldPath: condition.field },
-                        op: condition.op,
-                        value: (0, converter_1.convertToFirestoreValue)(condition.value),
-                    },
+            };
+            // Add where filters if present
+            if (options.where && options.where.length > 0) {
+                // Map our operators to Firestore REST API operators
+                const opMap = {
+                    "==": "EQUAL",
+                    "!=": "NOT_EQUAL",
+                    "<": "LESS_THAN",
+                    "<=": "LESS_THAN_OR_EQUAL",
+                    ">": "GREATER_THAN",
+                    ">=": "GREATER_THAN_OR_EQUAL",
+                    "array-contains": "ARRAY_CONTAINS",
+                    in: "IN",
+                    "array-contains-any": "ARRAY_CONTAINS_ANY",
+                    "not-in": "NOT_IN",
                 };
+                // Single where clause
+                if (options.where.length === 1) {
+                    const filter = options.where[0];
+                    const firestoreOp = opMap[filter.op] || filter.op;
+                    requestBody.structuredQuery.where = {
+                        fieldFilter: {
+                            field: { fieldPath: filter.field },
+                            op: firestoreOp,
+                            value: (0, converter_1.convertToFirestoreValue)(filter.value),
+                        },
+                    };
+                }
+                // Multiple where clauses (AND)
+                else {
+                    requestBody.structuredQuery.where = {
+                        compositeFilter: {
+                            op: "AND",
+                            filters: options.where.map(filter => {
+                                const firestoreOp = opMap[filter.op] || filter.op;
+                                return {
+                                    fieldFilter: {
+                                        field: { fieldPath: filter.field },
+                                        op: firestoreOp,
+                                        value: (0, converter_1.convertToFirestoreValue)(filter.value),
+                                    },
+                                };
+                            }),
+                        },
+                    };
+                }
             }
-            else {
-                // 複数条件の場合
-                structuredQuery.where = {
-                    compositeFilter: {
-                        op: "AND",
-                        filters: options.where.map(condition => ({
-                            fieldFilter: {
-                                field: { fieldPath: condition.field },
-                                op: condition.op,
-                                value: (0, converter_1.convertToFirestoreValue)(condition.value),
-                            },
-                        })),
+            // Add order by if present
+            if (options.orderBy) {
+                requestBody.structuredQuery.orderBy = [
+                    {
+                        field: { fieldPath: options.orderBy },
+                        direction: options.orderDirection || "ASCENDING",
                     },
-                };
+                ];
             }
-        }
-        // 並べ替え
-        if (options.orderBy) {
-            structuredQuery.orderBy = [
-                {
-                    field: { fieldPath: options.orderBy },
-                    direction: options.orderDirection || "ASCENDING",
-                },
-            ];
-        }
-        // 制限
-        if (options.limit) {
-            structuredQuery.limit = options.limit;
-        }
-        // オフセット
-        if (options.offset) {
-            structuredQuery.offset = options.offset;
-        }
-        const token = await this.getToken();
-        // 修正: structuredQueryをラップしたリクエストボディを作成
-        const requestBody = {
-            structuredQuery: structuredQuery,
-        };
-        console.log("クエリリクエスト:", JSON.stringify(requestBody, null, 2));
-        try {
-            const response = await fetch(url, {
+            // Add limit if present
+            if (options.limit) {
+                requestBody.structuredQuery.limit = options.limit;
+            }
+            // Add offset if present
+            if (options.offset) {
+                requestBody.structuredQuery.offset = options.offset;
+            }
+            if (this.debug) {
+                console.log(`Request payload:`, JSON.stringify(requestBody, null, 2));
+            }
+            // Use the existing prepareHeaders method for authentication consistency
+            const headers = await this.prepareHeaders();
+            const response = await fetch(queryUrl, {
                 method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                    Authorization: `Bearer ${token}`,
-                },
+                headers,
                 body: JSON.stringify(requestBody),
             });
+            // Collect response for debugging
             const responseText = await response.text();
-            console.log("API レスポンス:", responseText);
+            if (this.debug) {
+                console.log(`API Response:`, responseText);
+            }
             if (!response.ok) {
-                throw new Error(`Firestore API error: ${response.statusText} - ${responseText}`);
+                throw new Error(`Firestore API error: ${response.status} - ${responseText}`);
             }
+            // Parse the response
             const results = JSON.parse(responseText);
-            console.log("変換前の結果:", results);
+            if (this.debug) {
+                console.log(`Results count: ${results?.length || 0}`);
+            }
+            // Process the results
+            if (!Array.isArray(results)) {
+                return [];
+            }
             const convertedResults = results
                 .filter(item => item.document)
                 .map(item => (0, converter_1.convertFromFirestoreDocument)(item.document));
-            console.log("変換後の結果:", convertedResults);
+            if (this.debug) {
+                console.log(`Converted results:`, convertedResults);
+            }
             return convertedResults;
         }
         catch (error) {
-            console.error("クエリ実行エラー:", error);
+            console.error("Query execution error:", error);
             throw error;
         }
     }
+    /**
+     * ドキュメントを作成または上書き
+     * @param collectionName コレクション名
+     * @param documentId ドキュメントID
+     * @param data ドキュメントデータ
+     * @returns 作成されたドキュメントのリファレンス
+     */
+    async createWithId(collectionName, documentId, data) {
+        // 操作前に設定をチェック
+        this.checkConfig();
+        const url = `${(0, path_1.getFirestoreBasePath)(this.config.projectId, this.config.databaseId, this.config)}/${collectionName}/${documentId}`;
+        const firestoreData = (0, converter_1.convertToFirestoreDocument)(data);
+        const token = await this.getToken();
+        const response = await fetch(url, {
+            method: "PATCH",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(firestoreData),
+        });
+        if (!response.ok) {
+            throw new Error(`Firestore API error: ${response.statusText}`);
+        }
+        const result = (await response.json());
+        return (0, converter_1.convertFromFirestoreDocument)(result);
+    }
 }
 exports.FirestoreClient = FirestoreClient;
 /**
- * コレクションリファレンスクラス
+ * Collection reference class
  */
 class CollectionReference {
     constructor(client, path) {
         this.client = client;
-        this.path = path;
+        this._path = path;
         this._queryConstraints = {
             where: [],
         };
     }
     /**
-     * すべての子孫コレクションを含むかどうか
+     * Get collection path
+     */
+    get path() {
+        return this._path;
+    }
+    /**
+     * Whether to include all descendant collections
      */
     get allDescendants() {
         return false;
     }
     /**
-     * ドキュメントリファレンスを取得
-     * @param documentPath ドキュメントID（省略時は自動生成）
-     * @returns DocumentReferenceインスタンス
+     * Get document reference
+     * @param documentPath Document ID (auto-generated if omitted)
+     * @returns DocumentReference instance
      */
     doc(documentPath) {
         const docId = documentPath || this._generateId();
         return new DocumentReference(this.client, this.path, docId);
     }
     /**
-     * ドキュメントを追加（IDは自動生成）
-     * @param data ドキュメントデータ
-     * @returns 作成されたドキュメントのリファレンス
+     * Add document (ID is auto-generated)
+     * @param data Document data
+     * @returns Reference to the created document
      */
     async add(data) {
         const result = await this.client.add(this.path, data);
@@ -382,17 +531,17 @@ class CollectionReference {
         return new DocumentReference(this.client, this.path, docId);
     }
     /**
-     * フィルター条件を追加
-     * @param fieldPath フィールドパス
-     * @param opStr 演算子
-     * @param value 値
-     * @returns Queryインスタンス
+     * Add filter condition
+     * @param fieldPath Field path
+     * @param opStr Operator
+     * @param value Value
+     * @returns Query instance
      */
     where(fieldPath, opStr, value) {
         const query = new Query(this.client, this.path, {
             ...this._queryConstraints,
         }, this.allDescendants);
-        // 演算子の変換
+        // Operator conversion
         let firestoreOp;
         switch (opStr) {
             case "==":
@@ -436,10 +585,10 @@ class CollectionReference {
         return query;
     }
     /**
-     * 並べ替え条件を追加
-     * @param fieldPath フィールドパス
-     * @param directionStr 並べ替え方向（'asc'または'desc'）
-     * @returns Queryインスタンス
+     * Add sorting condition
+     * @param fieldPath Field path
+     * @param directionStr Sort direction ('asc' or 'desc')
+     * @returns Query instance
      */
     orderBy(fieldPath, directionStr = "asc") {
         const query = new Query(this.client, this.path, {
@@ -451,9 +600,9 @@ class CollectionReference {
         return query;
     }
     /**
-     * 取得件数の制限を設定
-     * @param limit 最大件数
-     * @returns Queryインスタンス
+     * Set limit on number of results
+     * @param limit Maximum number
+     * @returns Query instance
      */
     limit(limit) {
         const query = new Query(this.client, this.path, {
@@ -463,9 +612,9 @@ class CollectionReference {
         return query;
     }
     /**
-     * スキップ件数を設定
-     * @param offset スキップ件数
-     * @returns Queryインスタンス
+     * Set number of documents to skip
+     * @param offset Number to skip
+     * @returns Query instance
      */
     offset(offset) {
         const query = new Query(this.client, this.path, {
@@ -475,19 +624,19 @@ class CollectionReference {
         return query;
     }
     /**
-     * クエリを実行
-     * @returns QuerySnapshotインスタンス
+     * Execute query
+     * @returns QuerySnapshot instance
      */
     async get() {
         const results = await this.client.query(this.path, this._queryConstraints, this.allDescendants);
         return new QuerySnapshot(results);
     }
     /**
-     * ランダムなIDを生成
-     * @returns ランダムなID
+     * Generate random ID
+     * @returns Random ID
      */
     _generateId() {
-        // 20文字のランダムなIDを生成
+        // Generate 20-character random ID
         const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
         let id = "";
         for (let i = 0; i < 20; i++) {
@@ -498,7 +647,7 @@ class CollectionReference {
 }
 exports.CollectionReference = CollectionReference;
 /**
- * ドキュメントリファレンスクラス
+ * Document reference class
  */
 class DocumentReference {
     constructor(client, collectionPath, docId) {
@@ -507,66 +656,71 @@ class DocumentReference {
         this.docId = docId;
     }
     /**
-     * ドキュメントIDを取得
+     * Get document ID
      */
     get id() {
         return this.docId;
     }
     /**
-     * ドキュメントのパスを取得
+     * Get document path
      */
     get path() {
         return `${this.collectionPath}/${this.docId}`;
     }
     /**
-     * サブコレクションを取得
-     * @param collectionPath サブコレクション名
-     * @returns CollectionReferenceインスタンス
+     * Get parent collection reference
+     */
+    get parent() {
+        return new CollectionReference(this.client, this.collectionPath);
+    }
+    /**
+     * Get subcollection
+     * @param collectionPath Subcollection name
+     * @returns CollectionReference instance
      */
     collection(collectionPath) {
         return new CollectionReference(this.client, `${this.path}/${collectionPath}`);
     }
     /**
-     * ドキュメントを取得
-     * @returns DocumentSnapshotインスタンス
+     * Get document
+     * @returns DocumentSnapshot instance
      */
     async get() {
         const data = await this.client.get(this.collectionPath, this.docId);
         return new DocumentSnapshot(this.docId, data);
     }
     /**
-     * ドキュメントを作成または上書き
-     * @param data ドキュメントデータ
-     * @param options オプション（mergeは現在サポートされていません）
-     * @returns WriteResultインスタンス
+     * Create or overwrite document
+     * @param data Document data
+     * @param options Options (merge is not currently supported)
+     * @returns WriteResult instance
      */
     async set(data, options) {
-        // 既存のドキュメントを取得
+        // Get existing document
         const existingDoc = await this.client.get(this.collectionPath, this.docId);
         if (existingDoc) {
-            // 既存のドキュメントがある場合は更新
+            // If existing document exists, update
             const mergedData = options?.merge ? { ...existingDoc, ...data } : data;
             await this.client.update(this.collectionPath, this.docId, mergedData);
         }
         else {
-            // 新規作成
-            const newData = { ...data, id: this.docId };
-            await this.client.add(this.collectionPath, newData);
+            // New creation
+            await this.client.createWithId(this.collectionPath, this.docId, data);
         }
         return new WriteResult();
     }
     /**
-     * ドキュメントを更新
-     * @param data 更新データ
-     * @returns WriteResultインスタンス
+     * Update document
+     * @param data Update data
+     * @returns WriteResult instance
      */
     async update(data) {
         await this.client.update(this.collectionPath, this.docId, data);
         return new WriteResult();
     }
     /**
-     * ドキュメントを削除
-     * @returns WriteResultインスタンス
+     * Delete document
+     * @returns WriteResult instance
      */
     async delete() {
         await this.client.delete(this.collectionPath, this.docId);
@@ -575,7 +729,7 @@ class DocumentReference {
 }
 exports.DocumentReference = DocumentReference;
 /**
- * コレクショングループ
+ * Collection group
  */
 class CollectionGroup {
     constructor(client, path) {
@@ -586,23 +740,23 @@ class CollectionGroup {
         };
     }
     /**
-     * すべての子孫コレクションを含むかどうか
+     * Whether to include all descendant collections
      */
     get allDescendants() {
         return true;
     }
     /**
-     * フィルター条件を追加
-     * @param fieldPath フィールドパス
-     * @param opStr 演算子
-     * @param value 値
-     * @returns Queryインスタンス
+     * Add filter condition
+     * @param fieldPath Field path
+     * @param opStr Operator
+     * @param value Value
+     * @returns Query instance
      */
     where(fieldPath, opStr, value) {
         const query = new Query(this.client, this.path, {
             ...this._queryConstraints,
         }, this.allDescendants);
-        // 演算子の変換
+        // Operator conversion
         let firestoreOp;
         switch (opStr) {
             case "==":
@@ -646,10 +800,10 @@ class CollectionGroup {
         return query;
     }
     /**
-     * 並べ替え条件を追加
-     * @param fieldPath フィールドパス
-     * @param directionStr 並べ替え方向（'asc'または'desc'）
-     * @returns Queryインスタンス
+     * Add sorting condition
+     * @param fieldPath Field path
+     * @param directionStr Sort direction ('asc' or 'desc')
+     * @returns Query instance
      */
     orderBy(fieldPath, directionStr = "asc") {
         const query = new Query(this.client, this.path, {
@@ -661,9 +815,9 @@ class CollectionGroup {
         return query;
     }
     /**
-     * 取得件数の制限を設定
-     * @param limit 最大件数
-     * @returns Queryインスタンス
+     * Set limit on number of results
+     * @param limit Maximum number
+     * @returns Query instance
      */
     limit(limit) {
         const query = new Query(this.client, this.path, {
@@ -673,9 +827,9 @@ class CollectionGroup {
         return query;
     }
     /**
-     * スキップ件数を設定
-     * @param offset スキップ件数
-     * @returns Queryインスタンス
+     * Set number of documents to skip
+     * @param offset Number to skip
+     * @returns Query instance
      */
     offset(offset) {
         const query = new Query(this.client, this.path, {
@@ -685,8 +839,8 @@ class CollectionGroup {
         return query;
     }
     /**
-     * クエリを実行
-     * @returns QuerySnapshotインスタンス
+     * Execute query
+     * @returns QuerySnapshot instance
      */
     async get() {
         const results = await this.client.query(this.path, this._queryConstraints, this.allDescendants);
@@ -695,7 +849,7 @@ class CollectionGroup {
 }
 exports.CollectionGroup = CollectionGroup;
 /**
- * クエリクラス
+ * Query class
  */
 class Query {
     constructor(client, collectionPath, constraints, allDescendants) {
@@ -705,17 +859,17 @@ class Query {
         this.allDescendants = allDescendants;
     }
     /**
-     * フィルター条件を追加
-     * @param fieldPath フィールドパス
-     * @param opStr 演算子
-     * @param value 値
-     * @returns Queryインスタンス
+     * Add filter condition
+     * @param fieldPath Field path
+     * @param opStr Operator
+     * @param value Value
+     * @returns Query instance
      */
     where(fieldPath, opStr, value) {
         const query = new Query(this.client, this.collectionPath, {
             ...this._queryConstraints,
         }, this.allDescendants);
-        // 演算子の変換
+        // Operator conversion
         let firestoreOp;
         switch (opStr) {
             case "==":
@@ -759,10 +913,10 @@ class Query {
         return query;
     }
     /**
-     * 並べ替え条件を追加
-     * @param fieldPath フィールドパス
-     * @param directionStr 並べ替え方向（'asc'または'desc'）
-     * @returns Queryインスタンス
+     * Add sorting condition
+     * @param fieldPath Field path
+     * @param directionStr Sort direction ('asc' or 'desc')
+     * @returns Query instance
      */
     orderBy(fieldPath, directionStr = "asc") {
         const query = new Query(this.client, this.collectionPath, {
@@ -774,9 +928,9 @@ class Query {
         return query;
     }
     /**
-     * 取得件数の制限を設定
-     * @param limit 最大件数
-     * @returns Queryインスタンス
+     * Set limit on number of results
+     * @param limit Maximum number
+     * @returns Query instance
      */
     limit(limit) {
         const query = new Query(this.client, this.collectionPath, {
@@ -786,9 +940,9 @@ class Query {
         return query;
     }
     /**
-     * スキップ件数を設定
-     * @param offset スキップ件数
-     * @returns Queryインスタンス
+     * Set number of documents to skip
+     * @param offset Number to skip
+     * @returns Query instance
      */
     offset(offset) {
         const query = new Query(this.client, this.collectionPath, {
@@ -798,8 +952,8 @@ class Query {
         return query;
     }
     /**
-     * クエリを実行
-     * @returns QuerySnapshotインスタンス
+     * Execute query
+     * @returns QuerySnapshot instance
      */
     async get() {
         const results = await this.client.query(this.collectionPath, this._queryConstraints, this.allDescendants);
@@ -808,7 +962,7 @@ class Query {
 }
 exports.Query = Query;
 /**
- * クエリ結果クラス
+ * Query result class
  */
 class QuerySnapshot {
     constructor(results) {
@@ -818,26 +972,26 @@ class QuerySnapshot {
         });
     }
     /**
-     * 結果のドキュメント配列
+     * Array of documents in the result
      */
     get docs() {
         return this._docs;
     }
     /**
-     * 結果が空かどうか
+     * Whether the result is empty
      */
     get empty() {
         return this._docs.length === 0;
     }
     /**
-     * 結果の件数
+     * Number of results
      */
     get size() {
         return this._docs.length;
     }
     /**
-     * 各ドキュメントに対してコールバックを実行
-     * @param callback 各ドキュメントに対して実行するコールバック関数
+     * Execute callback for each document
+     * @param callback Callback function to execute for each document
      */
     forEach(callback) {
         this._docs.forEach(callback);
@@ -845,7 +999,7 @@ class QuerySnapshot {
 }
 exports.QuerySnapshot = QuerySnapshot;
 /**
- * ドキュメントスナップショットクラス
+ * Document snapshot class
  */
 class DocumentSnapshot {
     constructor(id, data) {
@@ -853,20 +1007,20 @@ class DocumentSnapshot {
         this._data = data;
     }
     /**
-     * ドキュメントID
+     * Document ID
      */
     get id() {
         return this._id;
     }
     /**
-     * ドキュメントが存在するかどうか
+     * Whether the document exists
      */
     get exists() {
         return this._data !== null;
     }
     /**
-     * ドキュメントデータを取得
-     * @returns ドキュメントデータ（存在しない場合はundefined）
+     * Get document data
+     * @returns Document data (undefined if it doesn't exist)
      */
     data() {
         return this._data || undefined;
@@ -874,7 +1028,7 @@ class DocumentSnapshot {
 }
 exports.DocumentSnapshot = DocumentSnapshot;
 /**
- * 書き込み結果クラス
+ * Write result class
  */
 class WriteResult {
     constructor() {
@@ -883,28 +1037,37 @@ class WriteResult {
 }
 exports.WriteResult = WriteResult;
 /**
- * 新しいFirestoreクライアントインスタンスを作成
- * @param config Firestore設定オブジェクト
- * @returns FirestoreClientインスタンス
+ * 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
+ * });
  */
 function createFirestoreClient(config) {
-    // 秘密鍵のフォーマットを確認
+    // Check private key format
     if (config.privateKey) {
         config = {
             ...config,