firebase-rest-firestore 0.2.2 → 0.3.1

package/README.ja.md

@@ -0,0 +1,294 @@
+# Firebase REST Firestore
+
+Firebase Firestore REST API クライアント - Cloudflare Workers や Vercel Edge Functions などのエッジランタイム環境向け。
+
+## 特徴
+
+- Firebase Admin SDK が利用できないエッジランタイム環境で動作
+- 完全な CRUD 操作のサポート
+- TypeScript サポート
+- パフォーマンス向上のためのトークンキャッシング
+- シンプルで直感的な API
+- 環境変数への暗黙的な依存がない明示的な設定
+
+## インストール
+
+```bash
+npm install firebase-rest-firestore
+```
+
+## 使用方法
+
+```typescript
+import { initializeFirestore } from "firebase-rest-firestore";
+
+// SDK互換クライアントを初期化
+const db = initializeFirestore({
+  projectId: "your-project-id",
+  privateKey: "your-private-key",
+  clientEmail: "your-client-email",
+});
+
+// コレクションリファレンスの取得
+const gamesRef = db.collection("games");
+
+// ドキュメントの追加
+const gameRef = await gamesRef.add({
+  name: "New Game",
+  createdAt: new Date(),
+  score: 100,
+});
+
+// ドキュメントの取得
+const gameSnapshot = await gameRef.get();
+console.log(gameSnapshot.data());
+
+// ドキュメントの更新
+await gameRef.update({
+  score: 200,
+});
+
+// ドキュメントの削除
+await gameRef.delete();
+
+// クエリの実行
+const highScoreGames = await gamesRef
+  .where("score", ">", 150)
+  .where("createdAt", "<", new Date())
+  .get();
+
+highScoreGames.forEach(doc => {
+  console.log(doc.id, "=>", doc.data());
+});
+```
+
+## API リファレンス
+
+### createFirestoreClient(config)
+
+Firestore クライアントを作成します。
+
+#### パラメータ
+
+- `config` (object): クライアント設定
+  - `projectId` (string): Firebase プロジェクト ID
+  - `privateKey` (string): サービスアカウントの秘密鍵
+  - `clientEmail` (string): サービスアカウントのメールアドレス
+
+#### 戻り値
+
+以下のメソッドを持つ Firestore クライアントオブジェクト：
+
+### collection(collectionPath).add(data)
+
+コレクション内に自動生成された ID を持つ新しいドキュメントを作成します。
+
+#### パラメータ
+
+- `data` (object): ドキュメントデータ
+
+#### 戻り値
+
+作成されたドキュメントへの参照。
+
+### collection(collectionPath).doc(id?).set(data)
+
+指定された ID でドキュメントを作成または上書きします。ID が指定されていない場合は自動的に生成されます。
+
+#### パラメータ
+
+- `id` (string, オプション): ドキュメントの ID
+- `data` (object): ドキュメントデータ
+
+#### 戻り値
+
+プロミス（作成または上書き操作の完了時に解決）。
+
+### client.get(collection, id)
+
+ドキュメントを取得します。
+
+#### パラメータ
+
+- `collection` (string): ドキュメントが属するコレクション名
+- `id` (string): 取得するドキュメントの ID
+
+#### 戻り値
+
+ドキュメントデータを含むオブジェクト。ドキュメントが存在しない場合は null。
+
+### client.update(collection, id, data)
+
+既存のドキュメントを更新します。
+
+#### パラメータ
+
+- `collection` (string): ドキュメントが属するコレクション名
+- `id` (string): 更新するドキュメントの ID
+- `data` (object): 更新するフィールドを含むオブジェクト
+
+#### 戻り値
+
+更新されたドキュメントを表すオブジェクト。
+
+### client.delete(collection, id)
+
+ドキュメントを削除します。
+
+#### パラメータ
+
+- `collection` (string): ドキュメントが属するコレクション名
+- `id` (string): 削除するドキュメントの ID
+
+#### 戻り値
+
+成功した場合は true。
+
+### client.query(collection, filters, options?)
+
+コレクションに対してクエリを実行します。
+
+#### パラメータ
+
+- `collection` (string): クエリするコレクション名
+- `filters` (array): 各フィルタは[フィールド, 演算子, 値]の形式の配列
+- `options` (object, オプション):
+  - `orderBy` (array, オプション): 並べ替えの指定（例：[['score', 'desc'], ['createdAt', 'asc']]）
+  - `limit` (number, オプション): 結果の最大数
+  - `offset` (number, オプション): スキップする結果の数
+  - `startAt` (any, オプション): この値から始まるドキュメントを返す
+  - `startAfter` (any, オプション): この値の後に始まるドキュメントを返す
+  - `endAt` (any, オプション): この値で終わるドキュメントを返す
+  - `endBefore` (any, オプション): この値の前に終わるドキュメントを返す
+
+#### 戻り値
+
+クエリ条件に一致するドキュメントの配列。
+
+## Next.js 環境での設定
+
+Next.js アプリでは、サーバーサイドでのみ実行されるように設定してください：
+
+```typescript
+// Initialize in a server component or API route
+import { createFirestoreClient } from "firebase-rest-firestore";
+
+export async function getServerSideProps() {
+  // Server-side only code
+  const firestore = createFirestoreClient({
+    projectId: process.env.FIREBASE_PROJECT_ID,
+    privateKey: process.env.FIREBASE_PRIVATE_KEY,
+    clientEmail: process.env.FIREBASE_CLIENT_EMAIL,
+  });
+
+  const data = await firestore.query("collection", [
+    /* your filters */
+  ]);
+
+  return {
+    props: {
+      data: JSON.parse(JSON.stringify(data)),
+    },
+  };
+}
+```
+
+## Cloudflare Workers 環境での使用
+
+```typescript
+import { createFirestoreClient } from "firebase-rest-firestore";
+
+export default {
+  async fetch(request, env) {
+    const firestore = createFirestoreClient({
+      projectId: env.FIREBASE_PROJECT_ID,
+      privateKey: env.FIREBASE_PRIVATE_KEY,
+      clientEmail: env.FIREBASE_CLIENT_EMAIL,
+    });
+
+    // APIロジックの実装...
+    const data = await firestore.query("collection", [
+      /* your filters */
+    ]);
+
+    return new Response(JSON.stringify(data), {
+      headers: { "Content-Type": "application/json" },
+    });
+  },
+};
+```
+
+## クイックスタート
+
+```typescript
+import { createFirestoreClient } from "firebase-rest-firestore";
+
+// 設定オブジェクトでクライアントを初期化
+const firestore = createFirestoreClient({
+  projectId: "your-project-id",
+  privateKey: "your-private-key",
+  clientEmail: "your-client-email",
+});
+
+// ドキュメントの追加
+const newDoc = await firestore.add("collection", {
+  name: "テストドキュメント",
+  value: 100,
+});
+
+// ドキュメントの取得
+const doc = await firestore.get("collection", newDoc.id);
+
+// ドキュメントの更新
+await firestore.update("collection", newDoc.id, { value: 200 });
+
+// ドキュメントのクエリ
+const querySnapshot = await firestore
+  .collection("games")
+  .where("score", ">", 50)
+  .where("active", "==", true)
+  .orderBy("score", "desc")
+  .limit(10)
+  .get();
+
+const games = [];
+querySnapshot.forEach(doc => {
+  games.push({
+    id: doc.id,
+    ...doc.data(),
+  });
+});
+console.log("Games with score > 50:", games);
+
+// ドキュメントの削除
+await firestore.delete("collection", newDoc.id);
+```
+
+## 設定
+
+Firestore の権限を持つ Firebase サービスアカウントが必要です：
+
+```typescript
+createFirestoreClient({
+  projectId: "your-project-id",
+  privateKey: "your-private-key", // エスケープされた改行(\\n)を含む場合、自動的にフォーマットされます
+  clientEmail: "your-client-email",
+});
+```
+
+## API リファレンス
+
+### add(collectionName, data)
+
+コレクションに新しいドキュメントを追加します。
+
+パラメータ:
+
+- `collectionName`: コレクション名
+- `data`: 追加するドキュメントデータ
+
+戻り値: 自動生成された ID を持つ追加されたドキュメント。
+
+## ライセンス
+
+MIT

package/README.md

@@ -1,5 +1,7 @@
 # Firebase REST Firestore
 
+[日本語版はこちら(Japanese Version)](./README.ja.md)
+
 Firebase Firestore REST API client for Edge runtime environments like Cloudflare Workers and Vercel Edge Functions.
 
 ## Features
@@ -10,8 +12,6 @@ Firebase Firestore REST API client for Edge runtime environments like Cloudflare
 - Token caching for better performance
 - Simple and intuitive API
 - Explicit configuration without hidden environment variable dependencies
-- Firebase Admin SDK compatible interface (v0.2.0+)
-- Lazy configuration validation for Next.js compatibility (v0.2.1+)
 
 ## Installation
 
@@ -19,55 +19,7 @@ Firebase Firestore REST API client for Edge runtime environments like Cloudflare
 npm install firebase-rest-firestore
 ```
 
-## Usage
-
-### Basic usage with explicit configuration
-
-```typescript
-import { createFirestoreClient } from "firebase-rest-firestore";
-
-// Create a client with your configuration
-const firestore = createFirestoreClient({
-  projectId: "your-project-id",
-  privateKey: "your-private-key",
-  clientEmail: "your-client-email",
-});
-
-// Create a document
-const game = await firestore.create("games", {
-  name: "New Game",
-  createdAt: new Date(),
-  score: 100,
-  active: true,
-});
-console.log("Created game ID:", game.id);
-
-// Get a document
-const fetchedGame = await firestore.get("games", game.id);
-console.log("Fetched game:", fetchedGame);
-
-// Update a document
-const updatedGame = await firestore.update("games", game.id, {
-  ...fetchedGame,
-  name: "Updated Game Name",
-  updatedAt: new Date(),
-});
-
-// Query documents
-const userGames = await firestore.query("games", {
-  where: [{ field: "score", op: "GREATER_THAN", value: 50 }],
-  orderBy: "createdAt",
-  limit: 10,
-});
-console.log("Games with score > 50:", userGames);
-
-// Delete a document
-await firestore.delete("games", game.id);
-```
-
-### Firebase Admin SDK Compatible Interface (v0.2.0+)
-
-From version 0.2.0, firebase-rest-firestore provides a Firebase Admin SDK compatible interface:
+## Quick Start
 
 ```typescript
 import { createFirestoreClient } from "firebase-rest-firestore";
@@ -79,33 +31,17 @@ const firestore = createFirestoreClient({
   clientEmail: "your-client-email",
 });
 
-// Create a document with auto-generated ID
-const gameRef = firestore.collection("games").doc();
-await gameRef.set({
-  name: "New Game",
-  createdAt: new Date(),
-  score: 100,
-  active: true,
-});
-console.log("Created game ID:", gameRef.id);
-
-// Create a document with specific ID
-await firestore.collection("games").doc("game123").set({
-  name: "Specific Game",
-  createdAt: new Date(),
+// Add a document
+const newDoc = await firestore.add("collection", {
+  name: "Test Document",
+  value: 100,
 });
 
 // Get a document
-const gameDoc = await firestore.doc("games/game123").get();
-if (gameDoc.exists) {
-  console.log("Fetched game:", gameDoc.data());
-}
+const doc = await firestore.get("collection", newDoc.id);
 
 // Update a document
-await firestore.collection("games").doc("game123").update({
-  name: "Updated Game Name",
-  updatedAt: new Date(),
-});
+await firestore.update("collection", newDoc.id, { value: 200 });
 
 // Query documents
 const querySnapshot = await firestore
@@ -127,19 +63,7 @@ querySnapshot.forEach(doc => {
 console.log("Games with score > 50:", games);
 
 // Delete a document
-await firestore.collection("games").doc("game123").delete();
-
-// Working with subcollections
-const commentRef = firestore
-  .collection("games")
-  .doc("game123")
-  .collection("comments")
-  .doc();
-
-await commentRef.set({
-  text: "Great game!",
-  createdAt: new Date(),
-});
+await firestore.delete("collection", newDoc.id);
 ```
 
 ## Configuration
@@ -158,9 +82,26 @@ The `FirestoreConfig` object requires the following properties:
 
 The main class for interacting with Firestore.
 
-#### create(collectionName, data)
+#### collection(collectionPath).add(data)
+
+Creates a new document with an auto-generated ID in the specified collection.
+
+Parameters:
+
+- `data`: Document data to be added
 
-Creates a new document in the specified collection.
+Returns: A reference to the created document.
+
+#### collection(collectionPath).doc(id?).set(data)
+
+Creates or overwrites a document with the specified ID. If no ID is provided, one will be auto-generated.
+
+Parameters:
+
+- `id` (optional): Document ID
+- `data`: Document data
+
+Returns: A promise that resolves when the set operation is complete.
 
 #### get(collectionName, documentId)
 
@@ -182,9 +123,16 @@ Queries documents in a collection with filtering, ordering, and pagination.
 
 Creates a new FirestoreClient instance with the provided configuration.
 
-### loadConfigFromEnv()
+#### add(collectionName, data)
 
-Helper function to load configuration from environment variables.
+Adds a new document to the specified collection.
+
+Parameters:
+
+- `collectionName`: Name of the collection
+- `data`: Document data to be added
+
+Returns: The added document with auto-generated ID.
 
 ## Error Handling
 
@@ -443,451 +391,3 @@ Please report feature requests and bugs via GitHub Issues.
 ## License
 
 MIT
-
----
-
-# Firebase REST Firestore (日本語ドキュメント)
-
-Firebase Firestore REST API クライアントは、Cloudflare Workers や Vercel Edge Functions などのエッジランタイム環境向けに設計されています。
-
-## 特徴
-
-- Firebase Admin SDK が利用できないエッジランタイム環境で動作
-- 完全な CRUD 操作のサポート
-- TypeScript サポート
-- パフォーマンス向上のためのトークンキャッシュ
-- シンプルで直感的な API
-- 環境変数に依存しない明示的な設定
-- Firebase Admin SDK compatible interface (v0.2.0+)
-- Next.js 互換性のための遅延設定検証 (v0.2.1+)
-
-## インストール
-
-```bash
-npm install firebase-rest-firestore
-```
-
-## 使い方
-
-### 基本的な使い方（明示的な設定）
-
-```typescript
-import { createFirestoreClient } from "firebase-rest-firestore";
-
-// 設定を指定してクライアントを作成
-const firestore = createFirestoreClient({
-  projectId: "あなたのプロジェクトID",
-  privateKey: "サービスアカウントの秘密鍵",
-  clientEmail: "サービスアカウントのメールアドレス",
-});
-
-// ドキュメントの作成
-const game = await firestore.create("games", {
-  name: "新しいゲーム",
-  createdAt: new Date(),
-  score: 100,
-  active: true,
-});
-console.log("作成されたゲームID:", game.id);
-
-// ドキュメントの取得
-const fetchedGame = await firestore.get("games", game.id);
-console.log("取得したゲーム:", fetchedGame);
-
-// ドキュメントの更新
-const updatedGame = await firestore.update("games", game.id, {
-  ...fetchedGame,
-  name: "更新されたゲーム名",
-  updatedAt: new Date(),
-});
-
-// ドキュメントのクエリ
-const userGames = await firestore.query("games", {
-  where: [{ field: "score", op: "GREATER_THAN", value: 50 }],
-  orderBy: "createdAt",
-  limit: 10,
-});
-console.log("スコアが50より大きいゲーム:", userGames);
-
-// ドキュメントの削除
-await firestore.delete("games", game.id);
-```
-
-### Firebase Admin SDK 互換インターフェース (v0.2.0+)
-
-バージョン 0.2.0 から、firebase-rest-firestore は Firebase Admin SDK と互換性のあるインターフェースを提供しています：
-
-```typescript
-import { createFirestoreClient } from "firebase-rest-firestore";
-
-// 設定を指定してクライアントを作成
-const firestore = createFirestoreClient({
-  projectId: "あなたのプロジェクトID",
-  privateKey: "サービスアカウントの秘密鍵",
-  clientEmail: "サービスアカウントのメールアドレス",
-});
-
-// 自動生成IDでドキュメントを作成
-const gameRef = firestore.collection("games").doc();
-await gameRef.set({
-  name: "新しいゲーム",
-  createdAt: new Date(),
-  score: 100,
-  active: true,
-});
-console.log("作成されたゲームID:", gameRef.id);
-
-// 特定のIDでドキュメントを作成
-await firestore.collection("games").doc("game123").set({
-  name: "特定のゲーム",
-  createdAt: new Date(),
-});
-
-// ドキュメントの取得
-const gameDoc = await firestore.doc("games/game123").get();
-if (gameDoc.exists) {
-  console.log("取得したゲーム:", gameDoc.data());
-}
-
-// ドキュメントの更新
-await firestore.collection("games").doc("game123").update({
-  name: "更新されたゲーム名",
-  updatedAt: new Date(),
-});
-
-// ドキュメントのクエリ
-const querySnapshot = await firestore
-  .collection("games")
-  .where("score", ">", 50)
-  .where("active", "==", true)
-  .orderBy("score", "desc")
-  .limit(10)
-  .get();
-
-// クエリ結果の処理
-const games = [];
-querySnapshot.forEach(doc => {
-  games.push({
-    id: doc.id,
-    ...doc.data(),
-  });
-});
-console.log("スコアが50より大きいゲーム:", games);
-
-// ドキュメントの削除
-await firestore.collection("games").doc("game123").delete();
-
-// サブコレクションの操作
-const commentRef = firestore
-  .collection("games")
-  .doc("game123")
-  .collection("comments")
-  .doc();
-
-await commentRef.set({
-  text: "素晴らしいゲーム！",
-  createdAt: new Date(),
-});
-```
-
-## 設定
-
-`FirestoreConfig`オブジェクトには以下のプロパティが必要です：
-
-| プロパティ  | 説明                               |
-| ----------- | ---------------------------------- |
-| projectId   | Firebase プロジェクト ID           |
-| privateKey  | サービスアカウントの秘密鍵         |
-| clientEmail | サービスアカウントのメールアドレス |
-
-## API リファレンス
-
-### FirestoreClient
-
-Firestore と対話するためのメインクラスです。
-
-#### create(collectionName, data)
-
-指定されたコレクションに新しいドキュメントを作成します。
-
-#### get(collectionName, documentId)
-
-ID によってドキュメントを取得します。
-
-#### update(collectionName, documentId, data)
-
-既存のドキュメントを更新します。
-
-#### delete(collectionName, documentId)
-
-ドキュメントを削除します。
-
-#### query(collectionName, options)
-
-フィルタリング、並べ替え、ページネーションを使用してコレクション内のドキュメントをクエリします。
-
-### createFirestoreClient(config)
-
-提供された設定で新しい FirestoreClient インスタンスを作成します。
-
-### loadConfigFromEnv()
-
-環境変数から設定を読み込むためのヘルパー関数です。
-
-## エラーハンドリング
-
-Firebase REST Firestore は、API リクエスト中にエラーが発生した場合、適切なエラーメッセージを含む例外をスローします。以下はエラーハンドリングの例です：
-
-```typescript
-try {
-  // ドキュメントの取得を試みる
-  const game = await firestore.get("games", "non-existent-id");
-
-  // ドキュメントが存在しない場合はnullが返される
-  if (game === null) {
-    console.log("ドキュメントが見つかりませんでした");
-    return;
-  }
-
-  // ドキュメントが存在する場合の処理
-  console.log("取得したゲーム:", game);
-} catch (error) {
-  // API呼び出し中のエラー（認証エラーやネットワークエラーなど）
-  console.error("Firestoreエラー:", error.message);
-}
-```
-
-一般的なエラーケース：
-
-- 認証エラー（無効なクレデンシャル）
-- ネットワークエラー
-- 無効なクエリパラメータ
-- Firestore のレート制限
-
-## クエリオプションの詳細
-
-`query`メソッドでは、以下のオプションを使用して Firestore のドキュメントをフィルタリング、ソート、ページネーションできます：
-
-### where
-
-複数のフィルター条件を指定できます。各条件は以下のプロパティを持つオブジェクトです：
-
-- `field`: フィルタリングするフィールド名
-- `op`: 比較演算子。以下の値が使用可能です：
-  - `EQUAL`: 等しい
-  - `NOT_EQUAL`: 等しくない
-  - `LESS_THAN`: より小さい
-  - `LESS_THAN_OR_EQUAL`: 以下
-  - `GREATER_THAN`: より大きい
-  - `GREATER_THAN_OR_EQUAL`: 以上
-  - `ARRAY_CONTAINS`: 配列に含まれる
-  - `IN`: 指定した値のいずれかに等しい
-  - `ARRAY_CONTAINS_ANY`: 配列が指定した値のいずれかを含む
-  - `NOT_IN`: 指定した値のいずれにも等しくない
-- `value`: 比較する値
-
-```typescript
-// スコアが50より大きく、activeがtrueのゲームを検索
-const games = await firestore.query("games", {
-  where: [
-    { field: "score", op: "GREATER_THAN", value: 50 },
-    { field: "active", op: "EQUAL", value: true },
-  ],
-});
-```
-
-### orderBy
-
-結果を並べ替えるフィールド名を指定します。デフォルトでは昇順（ASCENDING）でソートされます。
-
-```typescript
-// 作成日時で並べ替え
-const games = await firestore.query("games", {
-  orderBy: "createdAt",
-});
-```
-
-### limit
-
-返される結果の最大数を指定します。
-
-```typescript
-// 最大10件のドキュメントを取得
-const games = await firestore.query("games", {
-  limit: 10,
-});
-```
-
-### offset
-
-結果のスキップ数を指定します。ページネーションに使用できます。
-
-```typescript
-// 最初の20件をスキップして、次の10件を取得
-const games = await firestore.query("games", {
-  offset: 20,
-  limit: 10,
-});
-```
-
-複合クエリの例：
-
-```typescript
-// アクティブなゲームをスコアの高い順に10件取得
-const topGames = await firestore.query("games", {
-  where: [{ field: "active", op: "EQUAL", value: true }],
-  orderBy: "score", // スコアでソート
-  limit: 10,
-});
-```
-
-## エッジランタイムでの使用例
-
-### Cloudflare Workers
-
-```typescript
-// wrangler.toml に以下の環境変数を設定してください
-// FIREBASE_PROJECT_ID
-// FIREBASE_PRIVATE_KEY
-// FIREBASE_CLIENT_EMAIL
-
-import { createFirestoreClient } from "firebase-rest-firestore";
-
-export default {
-  async fetch(request, env, ctx) {
-    // 環境変数から設定を読み込む
-    const firestore = createFirestoreClient({
-      projectId: env.FIREBASE_PROJECT_ID,
-      privateKey: env.FIREBASE_PRIVATE_KEY.replace(/\\n/g, "\n"),
-      clientEmail: env.FIREBASE_CLIENT_EMAIL,
-    });
-
-    const url = new URL(request.url);
-    const path = url.pathname;
-
-    // APIエンドポイントの例
-    if (path === "/api/games" && request.method === "GET") {
-      try {
-        // アクティブなゲームを取得
-        const games = await firestore.query("games", {
-          where: [{ field: "active", op: "EQUAL", value: true }],
-          limit: 10,
-        });
-
-        return new Response(JSON.stringify(games), {
-          headers: { "Content-Type": "application/json" },
-        });
-      } catch (error) {
-        return new Response(JSON.stringify({ error: error.message }), {
-          status: 500,
-          headers: { "Content-Type": "application/json" },
-        });
-      }
-    }
-
-    return new Response("Not found", { status: 404 });
-  },
-};
-```
-
-### Vercel Edge Functions
-
-```typescript
-// .env.local に以下の環境変数を設定してください
-// FIREBASE_PROJECT_ID
-// FIREBASE_PRIVATE_KEY
-// FIREBASE_CLIENT_EMAIL
-
-import { createFirestoreClient } from "firebase-rest-firestore";
-
-export const config = {
-  runtime: "edge",
-};
-
-export default async function handler(request) {
-  // 環境変数から設定を読み込む
-  const firestore = createFirestoreClient({
-    projectId: process.env.FIREBASE_PROJECT_ID,
-    privateKey: process.env.FIREBASE_PRIVATE_KEY.replace(/\\n/g, "\n"),
-    clientEmail: process.env.FIREBASE_CLIENT_EMAIL,
-  });
-
-  try {
-    // 最新の10件のドキュメントを取得
-    const documents = await firestore.query("posts", {
-      orderBy: "createdAt",
-      limit: 10,
-    });
-
-    return new Response(JSON.stringify(documents), {
-      headers: { "Content-Type": "application/json" },
-    });
-  } catch (error) {
-    return new Response(JSON.stringify({ error: error.message }), {
-      status: 500,
-      headers: { "Content-Type": "application/json" },
-    });
-  }
-}
-```
-
-## パフォーマンスに関する注意点
-
-### トークンキャッシュ
-
-Firebase REST Firestore は、パフォーマンスを向上させるために JWT トークンをキャッシュします。デフォルトでは、トークンは 50 分間キャッシュされます（実際のトークン有効期限は 1 時間）。これにより、リクエストごとに新しいトークンを生成する必要がなくなり、API リクエストの速度が向上します。
-
-```typescript
-// トークンは内部的にキャッシュされるため、
-// 複数のリクエストでも認証のオーバーヘッドは最小限に抑えられます
-const doc1 = await firestore.get("collection", "doc1");
-const doc2 = await firestore.get("collection", "doc2");
-const doc3 = await firestore.get("collection", "doc3");
-```
-
-### クエリの最適化
-
-大量のデータを扱う場合は、以下の点に注意してください：
-
-1. **適切な制限を設定する**: 常に`limit`パラメータを使用して、返されるドキュメント数を制限してください。
-
-2. **必要なフィールドのみをクエリする**: 将来のバージョンでは、特定のフィールドのみを取得する機能が追加される予定です。
-
-3. **インデックスの作成**: 複雑なクエリを実行する場合は、Firebase コンソールで適切なインデックスを作成してください。
-
-4. **ページネーションの使用**: 大量のデータを取得する場合は、`offset`と`limit`を組み合わせてページネーションを実装してください。
-
-### エッジ環境での注意点
-
-エッジ環境では、以下の点に注意してください：
-
-1. **コールドスタート**: 初回実行時にはトークン生成のオーバーヘッドがあります。
-
-2. **メモリ使用量**: 大量のデータを一度に処理する場合は、メモリ制限に注意してください。
-
-3. **タイムアウト**: 長時間実行されるクエリは、エッジ環境のタイムアウト制限に達する可能性があります。
-
-## 制限事項とロードマップ
-
-### 現在の制限事項
-
-- **バッチ操作**: 現在のバージョンでは、複数のドキュメントを一度に操作するバッチ処理はサポートされていません。
-- **トランザクション**: 原子的なトランザクション操作はサポートされていません。
-- **リアルタイムリスナー**: REST API の性質上、リアルタイムのデータ同期はサポートされていません。
-- **サブコレクション**: 現在のバージョンでは、ネストされたサブコレクションの直接的なサポートは限定的です。
-
-### 将来のロードマップ
-
-以下の機能は将来のバージョンで実装予定です：
-
-- バッチ操作のサポート
-- 基本的なトランザクションのサポート
-- サブコレクションの改善されたサポート
-- より詳細なクエリオプション（複合インデックスなど）
-- パフォーマンス最適化
-
-機能リクエストやバグ報告は、GitHub の Issue でお知らせください。
-
-## ライセンス
-
-MIT

package/dist/client.d.ts

@@ -34,12 +34,12 @@ export declare class FirestoreClient {
      */
     doc(path: string): DocumentReference;
     /**
-     * Firestoreにドキュメントを作成
+     * Firestoreにドキュメントを追加
      * @param collectionName コレクション名
-     * @param data 作成するデータ
-     * @returns 作成されたドキュメント
+     * @param data 追加するデータ
+     * @returns 追加されたドキュメント
      */
-    create(collectionName: string, data: Record<string, any>): Promise<Record<string, any> & {
+    add(collectionName: string, data: Record<string, any>): Promise<Record<string, any> & {
         id: string;
     }>;
     /**

package/dist/client.js

@@ -5,6 +5,7 @@ exports.createFirestoreClient = createFirestoreClient;
 const auth_1 = require("./utils/auth");
 const converter_1 = require("./utils/converter");
 const path_1 = require("./utils/path");
+const config_1 = require("./utils/config");
 /**
  * Firestoreクライアントクラス
  */
@@ -81,12 +82,12 @@ class FirestoreClient {
         return new DocumentReference(this, collectionPath, docId);
     }
     /**
-     * Firestoreにドキュメントを作成
+     * Firestoreにドキュメントを追加
      * @param collectionName コレクション名
-     * @param data 作成するデータ
-     * @returns 作成されたドキュメント
+     * @param data 追加するデータ
+     * @returns 追加されたドキュメント
      */
-    async create(collectionName, data) {
+    async add(collectionName, data) {
         // 操作前に設定をチェック
         this.checkConfig();
         const url = (0, path_1.getFirestoreBasePath)(this.config.projectId, collectionName);
@@ -190,25 +191,42 @@ class FirestoreClient {
     async query(collectionName, options = {}) {
         // 操作前に設定をチェック
         this.checkConfig();
-        const url = `${(0, path_1.getFirestoreBasePath)(this.config.projectId, collectionName)}:runQuery`;
+        // 修正: URLの形式を修正
+        // :runQueryはコレクション単位ではなく、ドキュメントルート単位で実行
+        const basePath = `https://firestore.googleapis.com/v1/projects/${this.config.projectId}/databases/(default)/documents`;
+        const url = `${basePath}:runQuery`;
         // クエリ構築
         const structuredQuery = {
             from: [{ collectionId: collectionName }],
         };
         // フィルター条件
         if (options.where && options.where.length > 0) {
-            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),
-                        },
-                    })),
-                },
-            };
+            // シンプルなケース: 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),
+                    },
+                };
+            }
+            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),
+                            },
+                        })),
+                    },
+                };
+            }
         }
         // 並べ替え
         if (options.orderBy) {
@@ -228,23 +246,37 @@ class FirestoreClient {
             structuredQuery.offset = options.offset;
         }
         const token = await this.getToken();
-        const response = await fetch(url, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${token}`,
-            },
-            body: JSON.stringify({
-                structuredQuery,
-            }),
-        });
-        if (!response.ok) {
-            throw new Error(`Firestore API error: ${response.statusText}`);
+        // 修正: structuredQueryをラップしたリクエストボディを作成
+        const requestBody = {
+            structuredQuery: structuredQuery,
+        };
+        console.log("クエリリクエスト:", JSON.stringify(requestBody, null, 2));
+        try {
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify(requestBody),
+            });
+            const responseText = await response.text();
+            console.log("API レスポンス:", responseText);
+            if (!response.ok) {
+                throw new Error(`Firestore API error: ${response.statusText} - ${responseText}`);
+            }
+            const results = JSON.parse(responseText);
+            console.log("変換前の結果:", results);
+            const convertedResults = results
+                .filter(item => item.document)
+                .map(item => (0, converter_1.convertFromFirestoreDocument)(item.document));
+            console.log("変換後の結果:", convertedResults);
+            return convertedResults;
+        }
+        catch (error) {
+            console.error("クエリ実行エラー:", error);
+            throw error;
         }
-        const results = (await response.json());
-        return results
-            .filter(item => item.document)
-            .map(item => (0, converter_1.convertFromFirestoreDocument)(item.document));
     }
 }
 exports.FirestoreClient = FirestoreClient;
@@ -274,7 +306,7 @@ class CollectionReference {
      * @returns 作成されたドキュメントのリファレンス
      */
     async add(data) {
-        const result = await this.client.create(this.path, data);
+        const result = await this.client.add(this.path, data);
         const docId = result.id;
         return new DocumentReference(this.client, this.path, docId);
     }
@@ -448,7 +480,7 @@ class DocumentReference {
         else {
             // 新規作成
             const newData = { ...data, id: this.docId };
-            await this.client.create(this.collectionPath, newData);
+            await this.client.add(this.collectionPath, newData);
         }
         return new WriteResult();
     }
@@ -664,5 +696,12 @@ exports.WriteResult = WriteResult;
  * @returns FirestoreClientインスタンス
  */
 function createFirestoreClient(config) {
+    // 秘密鍵のフォーマットを確認
+    if (config.privateKey) {
+        config = {
+            ...config,
+            privateKey: (0, config_1.formatPrivateKey)(config.privateKey),
+        };
+    }
     return new FirestoreClient(config);
 }

package/dist/index.d.ts

@@ -3,4 +3,5 @@ import { FirestoreClient, createFirestoreClient, CollectionReference, DocumentRe
 export { getFirestoreToken } from "./utils/auth";
 export { convertToFirestoreValue, convertFromFirestoreValue, convertToFirestoreDocument, convertFromFirestoreDocument, } from "./utils/converter";
 export { getFirestoreBasePath, getDocumentId } from "./utils/path";
+export { formatPrivateKey, formatConfig } from "./utils/config";
 export { FirestoreClient, createFirestoreClient, CollectionReference, DocumentReference, Query, QuerySnapshot, DocumentSnapshot, WriteResult, };

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WriteResult = exports.DocumentSnapshot = exports.QuerySnapshot = exports.Query = exports.DocumentReference = exports.CollectionReference = exports.createFirestoreClient = exports.FirestoreClient = exports.getDocumentId = exports.getFirestoreBasePath = exports.convertFromFirestoreDocument = exports.convertToFirestoreDocument = exports.convertFromFirestoreValue = exports.convertToFirestoreValue = exports.getFirestoreToken = void 0;
+exports.WriteResult = exports.DocumentSnapshot = exports.QuerySnapshot = exports.Query = exports.DocumentReference = exports.CollectionReference = exports.createFirestoreClient = exports.FirestoreClient = exports.formatConfig = exports.formatPrivateKey = exports.getDocumentId = exports.getFirestoreBasePath = exports.convertFromFirestoreDocument = exports.convertToFirestoreDocument = exports.convertFromFirestoreValue = exports.convertToFirestoreValue = exports.getFirestoreToken = void 0;
 // 型定義のエクスポート
 __exportStar(require("./types"), exports);
 // クライアントのエクスポート
@@ -38,3 +38,6 @@ Object.defineProperty(exports, "convertFromFirestoreDocument", { enumerable: tru
 var path_1 = require("./utils/path");
 Object.defineProperty(exports, "getFirestoreBasePath", { enumerable: true, get: function () { return path_1.getFirestoreBasePath; } });
 Object.defineProperty(exports, "getDocumentId", { enumerable: true, get: function () { return path_1.getDocumentId; } });
+var config_1 = require("./utils/config");
+Object.defineProperty(exports, "formatPrivateKey", { enumerable: true, get: function () { return config_1.formatPrivateKey; } });
+Object.defineProperty(exports, "formatConfig", { enumerable: true, get: function () { return config_1.formatConfig; } });

package/dist/utils/config.d.ts

@@ -0,0 +1,13 @@
+import { FirestoreConfig } from "../types";
+/**
+ * 秘密鍵の文字列内にある改行コードのエスケープシーケンスを実際の改行に変換する
+ * @param privateKey 変換する秘密鍵文字列
+ * @returns 変換後の秘密鍵文字列
+ */
+export declare function formatPrivateKey(privateKey: string): string;
+/**
+ * FirestoreConfigオブジェクトの秘密鍵をフォーマットする
+ * @param config 元のconfigオブジェクト
+ * @returns 秘密鍵をフォーマットしたconfigオブジェクト
+ */
+export declare function formatConfig(config: FirestoreConfig): FirestoreConfig;

package/dist/utils/config.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatPrivateKey = formatPrivateKey;
+exports.formatConfig = formatConfig;
+/**
+ * 秘密鍵の文字列内にある改行コードのエスケープシーケンスを実際の改行に変換する
+ * @param privateKey 変換する秘密鍵文字列
+ * @returns 変換後の秘密鍵文字列
+ */
+function formatPrivateKey(privateKey) {
+    if (privateKey.includes("\\n")) {
+        return privateKey.replace(/\\n/g, "\n");
+    }
+    return privateKey;
+}
+/**
+ * FirestoreConfigオブジェクトの秘密鍵をフォーマットする
+ * @param config 元のconfigオブジェクト
+ * @returns 秘密鍵をフォーマットしたconfigオブジェクト
+ */
+function formatConfig(config) {
+    return {
+        ...config,
+        privateKey: formatPrivateKey(config.privateKey),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firebase-rest-firestore",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Firebase Firestore REST API client for Edge runtime environments",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,7 @@
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "vitest"
   },
   "keywords": [
     "firebase",
@@ -30,7 +30,9 @@
   },
   "devDependencies": {
     "@types/node": "^18.16.0",
-    "typescript": "^5.0.4"
+    "dotenv": "^16.4.7",
+    "typescript": "^5.0.4",
+    "vitest": "^3.0.9"
   },
   "engines": {
     "node": ">=16.0.0"