@cougargrades/firebase-rest-firestore 1.6.0

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

@@ -0,0 +1,393 @@
+# 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
+
+- Works in Edge runtime environments where Firebase Admin SDK is not available
+- Full CRUD operations support
+- TypeScript support
+- Token caching for better performance
+- Simple and intuitive API
+- Explicit configuration without hidden environment variable dependencies
+
+## Installation
+
+```bash
+npm install firebase-rest-firestore
+```
+
+## Quick Start
+
+```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",
+});
+
+// Add a document
+const newDoc = await firestore.add("collection", {
+  name: "Test Document",
+  value: 100,
+});
+
+// Get a document
+const doc = await firestore.get("collection", newDoc.id);
+
+// Update a document
+await firestore.update("collection", newDoc.id, { value: 200 });
+
+// Query documents
+const querySnapshot = await firestore
+  .collection("games")
+  .where("score", ">", 50)
+  .where("active", "==", true)
+  .orderBy("score", "desc")
+  .limit(10)
+  .get();
+
+// Process query results
+const games = [];
+querySnapshot.forEach(doc => {
+  games.push({
+    id: doc.id,
+    ...doc.data(),
+  });
+});
+console.log("Games with score > 50:", games);
+
+// Delete a document
+await firestore.delete("collection", newDoc.id);
+```
+
+## Configuration
+
+The `FirestoreConfig` object requires the following properties:
+
+| Property    | Description                  |
+| ----------- | ---------------------------- |
+| projectId   | Firebase project ID          |
+| privateKey  | Service account private key  |
+| clientEmail | Service account client email |
+
+## API Reference
+
+### FirestoreClient
+
+The main class for interacting with Firestore.
+
+#### collection(collectionPath).add(data)
+
+Creates a new document with an auto-generated ID in the specified collection.
+
+Parameters:
+
+- `data`: Document data to be added
+
+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)
+
+Retrieves a document by ID.
+
+#### update(collectionName, documentId, data)
+
+Updates an existing document.
+
+#### delete(collectionName, documentId)
+
+Deletes a document.
+
+#### query(collectionName, options)
+
+Queries documents in a collection with filtering, ordering, and pagination.
+
+### createFirestoreClient(config)
+
+Creates a new FirestoreClient instance with the provided configuration.
+
+#### add(collectionName, data)
+
+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
+
+Firebase REST Firestore throws exceptions with appropriate error messages when API requests fail. Here's an example of error handling:
+
+```typescript
+try {
+  // Try to get a document
+  const game = await firestore.get("games", "non-existent-id");
+
+  // If document doesn't exist, null is returned
+  if (game === null) {
+    console.log("Document not found");
+    return;
+  }
+
+  // Process document if it exists
+  console.log("Fetched game:", game);
+} catch (error) {
+  // Handle API errors (authentication, network, etc.)
+  console.error("Firestore error:", error.message);
+}
+```
+
+Common error cases:
+
+- Authentication errors (invalid credentials)
+- Network errors
+- Invalid query parameters
+- Firestore rate limits
+
+## Query Options Details
+
+The `query` method supports the following options for filtering, sorting, and paginating Firestore documents:
+
+### where
+
+Specify multiple filter conditions. Each condition is an object with the following properties:
+
+- `field`: The field name to filter on
+- `op`: The comparison operator. Available values:
+  - `EQUAL`: Equal to
+  - `NOT_EQUAL`: Not equal to
+  - `LESS_THAN`: Less than
+  - `LESS_THAN_OR_EQUAL`: Less than or equal to
+  - `GREATER_THAN`: Greater than
+  - `GREATER_THAN_OR_EQUAL`: Greater than or equal to
+  - `ARRAY_CONTAINS`: Array contains
+  - `IN`: Equal to any of the specified values
+  - `ARRAY_CONTAINS_ANY`: Array contains any of the specified values
+  - `NOT_IN`: Not equal to any of the specified values
+- `value`: The value to compare against
+
+```typescript
+// Query games with score > 50 and active = true
+const games = await firestore.query("games", {
+  where: [
+    { field: "score", op: "GREATER_THAN", value: 50 },
+    { field: "active", op: "EQUAL", value: true },
+  ],
+});
+```
+
+### orderBy
+
+Specifies the field name to sort results by. Results are sorted in ascending order by default.
+
+```typescript
+// Sort by creation time
+const games = await firestore.query("games", {
+  orderBy: "createdAt",
+});
+```
+
+### limit
+
+Limits the maximum number of results returned.
+
+```typescript
+// Get at most 10 documents
+const games = await firestore.query("games", {
+  limit: 10,
+});
+```
+
+### offset
+
+Specifies the number of results to skip. Useful for pagination.
+
+```typescript
+// Skip the first 20 results and get the next 10
+const games = await firestore.query("games", {
+  offset: 20,
+  limit: 10,
+});
+```
+
+Example of a compound query:
+
+```typescript
+// Get top 10 active games by score
+const topGames = await firestore.query("games", {
+  where: [{ field: "active", op: "EQUAL", value: true }],
+  orderBy: "score", // Sort by score
+  limit: 10,
+});
+```
+
+## Edge Runtime Examples
+
+### Cloudflare Workers
+
+```typescript
+// Set these environment variables in wrangler.toml
+// FIREBASE_PROJECT_ID
+// FIREBASE_PRIVATE_KEY
+// FIREBASE_CLIENT_EMAIL
+
+import { createFirestoreClient } from "firebase-rest-firestore";
+
+export default {
+  async fetch(request, env, ctx) {
+    // Load configuration from environment variables
+    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;
+
+    // Example API endpoint
+    if (path === "/api/games" && request.method === "GET") {
+      try {
+        // Get active games
+        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
+// Set these environment variables in .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) {
+  // Load configuration from environment variables
+  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 {
+    // Get the latest 10 documents
+    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" },
+    });
+  }
+}
+```
+
+## Performance Considerations
+
+### Token Caching
+
+Firebase REST Firestore caches JWT tokens to improve performance. By default, tokens are cached for 50 minutes (actual token expiry is 1 hour). This eliminates the need to generate a new token for each request, improving API request speed.
+
+```typescript
+// Tokens are cached internally, so multiple requests
+// have minimal authentication overhead
+const doc1 = await firestore.get("collection", "doc1");
+const doc2 = await firestore.get("collection", "doc2");
+const doc3 = await firestore.get("collection", "doc3");
+```
+
+### Query Optimization
+
+When dealing with large amounts of data, consider the following:
+
+1. **Set appropriate limits**: Always use the `limit` parameter to restrict the number of documents returned.
+
+2. **Query only needed fields**: Future versions will add support for retrieving only specific fields.
+
+3. **Create indexes**: For complex queries, create appropriate indexes in the Firebase console.
+
+4. **Use pagination**: When retrieving large datasets, implement pagination using `offset` and `limit`.
+
+### Edge Environment Considerations
+
+In edge environments, be aware of:
+
+1. **Cold starts**: Initial execution has token generation overhead.
+
+2. **Memory usage**: Be mindful of memory limits when processing large amounts of data.
+
+3. **Timeouts**: Long-running queries may hit edge environment timeout limits.
+
+## Limitations and Roadmap
+
+### Current Limitations
+
+- **Batch operations**: The current version does not support batch processing for operating on multiple documents at once.
+- **Transactions**: Atomic transaction operations are not supported.
+- **Real-time listeners**: Due to the nature of REST APIs, real-time data synchronization is not supported.
+- **Subcollections**: The current version has limited direct support for nested subcollections.
+
+### Future Roadmap
+
+The following features are planned for future versions:
+
+- Batch operations support
+- Basic transaction support
+- Improved subcollection support
+- More detailed query options (compound indexes, etc.)
+- Performance optimizations
+
+Please report feature requests and bugs via GitHub Issues.
+
+## License
+
+MIT