firebase-rest-firestore 0.3.0 → 1.0.0

package/README.ja.md

@@ -218,6 +218,77 @@ export default {
 };
 ```
 
+## クイックスタート
+
+```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

@@ -19,7 +19,7 @@ Firebase Firestore REST API client for Edge runtime environments like Cloudflare
 npm install firebase-rest-firestore
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
 import { createFirestoreClient } from "firebase-rest-firestore";
@@ -31,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
@@ -79,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
@@ -151,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)
+
+Adds a new document to the specified collection.
+
+Parameters:
+
+- `collectionName`: Name of the collection
+- `data`: Document data to be added
 
-Helper function to load configuration from environment variables.
+Returns: The added document with auto-generated ID.
 
 ## Error Handling
 

package/dist/client.d.ts

@@ -34,12 +34,18 @@ export declare class FirestoreClient {
      */
     doc(path: string): DocumentReference;
     /**
-     * Firestoreにドキュメントを作成
+     * コレクショングループリファレンスを取得
+     * @param path コレクショングループのID
+     * @returns CollectionGroupインスタンス
+     */
+    collectionGroup(path: string): CollectionGroup;
+    /**
+     * 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;
     }>;
     /**
@@ -70,11 +76,12 @@ export declare class FirestoreClient {
     delete(collectionName: string, documentId: string): Promise<boolean>;
     /**
      * コレクションのドキュメントを検索
-     * @param collectionName コレクション名
+     * @param collectionPath コレクションパス
      * @param options クエリオプション
+     * @param allDescendants 子孫コレクションを含むかどうか
      * @returns 検索結果のドキュメント配列
      */
-    query(collectionName: string, options?: QueryOptions): Promise<(Record<string, any> & {
+    query(collectionPath: string, options: QueryOptions | undefined, allDescendants: boolean): Promise<(Record<string, any> & {
         id: string;
     })[]>;
 }
@@ -86,6 +93,10 @@ export declare class CollectionReference {
     private path;
     private _queryConstraints;
     constructor(client: FirestoreClient, path: string);
+    /**
+     * すべての子孫コレクションを含むかどうか
+     */
+    get allDescendants(): boolean;
     /**
      * ドキュメントリファレンスを取得
      * @param documentPath ドキュメントID（省略時は自動生成）
@@ -184,12 +195,58 @@ export declare class DocumentReference {
      */
     delete(): Promise<WriteResult>;
 }
+/**
+ * コレクショングループ
+ */
+export declare class CollectionGroup {
+    private client;
+    private path;
+    private _queryConstraints;
+    constructor(client: FirestoreClient, path: string);
+    /**
+     * すべての子孫コレクションを含むかどうか
+     */
+    get allDescendants(): boolean;
+    /**
+     * フィルター条件を追加
+     * @param fieldPath フィールドパス
+     * @param opStr 演算子
+     * @param value 値
+     * @returns Queryインスタンス
+     */
+    where(fieldPath: string, opStr: string, value: any): Query;
+    /**
+     * 並べ替え条件を追加
+     * @param fieldPath フィールドパス
+     * @param directionStr 並べ替え方向（'asc'または'desc'）
+     * @returns Queryインスタンス
+     */
+    orderBy(fieldPath: string, directionStr?: "asc" | "desc"): Query;
+    /**
+     * 取得件数の制限を設定
+     * @param limit 最大件数
+     * @returns Queryインスタンス
+     */
+    limit(limit: number): Query;
+    /**
+     * スキップ件数を設定
+     * @param offset スキップ件数
+     * @returns Queryインスタンス
+     */
+    offset(offset: number): Query;
+    /**
+     * クエリを実行
+     * @returns QuerySnapshotインスタンス
+     */
+    get(): Promise<QuerySnapshot>;
+}
 /**
  * クエリクラス
  */
 export declare class Query {
     private client;
     private collectionPath;
+    private allDescendants;
     _queryConstraints: {
         where: Array<{
             field: string;
@@ -211,7 +268,7 @@ export declare class Query {
         orderDirection?: string;
         limit?: number;
         offset?: number;
-    });
+    }, allDescendants: boolean);
     /**
      * フィルター条件を追加
      * @param fieldPath フィールドパス

package/dist/client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WriteResult = exports.DocumentSnapshot = exports.QuerySnapshot = exports.Query = exports.DocumentReference = exports.CollectionReference = exports.FirestoreClient = void 0;
+exports.WriteResult = exports.DocumentSnapshot = exports.QuerySnapshot = exports.Query = exports.CollectionGroup = exports.DocumentReference = exports.CollectionReference = exports.FirestoreClient = void 0;
 exports.createFirestoreClient = createFirestoreClient;
 const auth_1 = require("./utils/auth");
 const converter_1 = require("./utils/converter");
@@ -82,12 +82,20 @@ class FirestoreClient {
         return new DocumentReference(this, collectionPath, docId);
     }
     /**
-     * Firestoreにドキュメントを作成
+     * コレクショングループリファレンスを取得
+     * @param path コレクショングループのID
+     * @returns CollectionGroupインスタンス
+     */
+    collectionGroup(path) {
+        return new CollectionGroup(this, path);
+    }
+    /**
+     * 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);
@@ -184,20 +192,35 @@ class FirestoreClient {
     }
     /**
      * コレクションのドキュメントを検索
-     * @param collectionName コレクション名
+     * @param collectionPath コレクションパス
      * @param options クエリオプション
+     * @param allDescendants 子孫コレクションを含むかどうか
      * @returns 検索結果のドキュメント配列
      */
-    async query(collectionName, options = {}) {
+    async query(collectionPath, options = {}, allDescendants) {
         // 操作前に設定をチェック
         this.checkConfig();
-        // 修正: URLの形式を修正
         // :runQueryはコレクション単位ではなく、ドキュメントルート単位で実行
-        const basePath = `https://firestore.googleapis.com/v1/projects/${this.config.projectId}/databases/(default)/documents`;
+        // コレクション名パス形式の場合は、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/(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 }],
+            from: [
+                {
+                    collectionId: collectionName,
+                    allDescendants,
+                },
+            ],
         };
         // フィルター条件
         if (options.where && options.where.length > 0) {
@@ -246,11 +269,10 @@ class FirestoreClient {
             structuredQuery.offset = options.offset;
         }
         const token = await this.getToken();
-        // リクエストボディ
+        // 修正: structuredQueryをラップしたリクエストボディを作成
         const requestBody = {
             structuredQuery: structuredQuery,
         };
-        console.log("クエリURL:", url);
         console.log("クエリリクエスト:", JSON.stringify(requestBody, null, 2));
         try {
             const response = await fetch(url, {
@@ -292,6 +314,12 @@ class CollectionReference {
             where: [],
         };
     }
+    /**
+     * すべての子孫コレクションを含むかどうか
+     */
+    get allDescendants() {
+        return false;
+    }
     /**
      * ドキュメントリファレンスを取得
      * @param documentPath ドキュメントID（省略時は自動生成）
@@ -307,7 +335,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);
     }
@@ -321,7 +349,7 @@ class CollectionReference {
     where(fieldPath, opStr, value) {
         const query = new Query(this.client, this.path, {
             ...this._queryConstraints,
-        });
+        }, this.allDescendants);
         // 演算子の変換
         let firestoreOp;
         switch (opStr) {
@@ -374,7 +402,7 @@ class CollectionReference {
     orderBy(fieldPath, directionStr = "asc") {
         const query = new Query(this.client, this.path, {
             ...this._queryConstraints,
-        });
+        }, this.allDescendants);
         query._queryConstraints.orderBy = fieldPath;
         query._queryConstraints.orderDirection =
             directionStr === "asc" ? "ASCENDING" : "DESCENDING";
@@ -388,7 +416,7 @@ class CollectionReference {
     limit(limit) {
         const query = new Query(this.client, this.path, {
             ...this._queryConstraints,
-        });
+        }, this.allDescendants);
         query._queryConstraints.limit = limit;
         return query;
     }
@@ -400,7 +428,7 @@ class CollectionReference {
     offset(offset) {
         const query = new Query(this.client, this.path, {
             ...this._queryConstraints,
-        });
+        }, this.allDescendants);
         query._queryConstraints.offset = offset;
         return query;
     }
@@ -409,7 +437,7 @@ class CollectionReference {
      * @returns QuerySnapshotインスタンス
      */
     async get() {
-        const results = await this.client.query(this.path, this._queryConstraints);
+        const results = await this.client.query(this.path, this._queryConstraints, this.allDescendants);
         return new QuerySnapshot(results);
     }
     /**
@@ -481,7 +509,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();
     }
@@ -504,14 +532,135 @@ class DocumentReference {
     }
 }
 exports.DocumentReference = DocumentReference;
+/**
+ * コレクショングループ
+ */
+class CollectionGroup {
+    constructor(client, path) {
+        this.client = client;
+        this.path = path;
+        this._queryConstraints = {
+            where: [],
+        };
+    }
+    /**
+     * すべての子孫コレクションを含むかどうか
+     */
+    get allDescendants() {
+        return true;
+    }
+    /**
+     * フィルター条件を追加
+     * @param fieldPath フィールドパス
+     * @param opStr 演算子
+     * @param value 値
+     * @returns Queryインスタンス
+     */
+    where(fieldPath, opStr, value) {
+        const query = new Query(this.client, this.path, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        // 演算子の変換
+        let firestoreOp;
+        switch (opStr) {
+            case "==":
+                firestoreOp = "EQUAL";
+                break;
+            case "!=":
+                firestoreOp = "NOT_EQUAL";
+                break;
+            case "<":
+                firestoreOp = "LESS_THAN";
+                break;
+            case "<=":
+                firestoreOp = "LESS_THAN_OR_EQUAL";
+                break;
+            case ">":
+                firestoreOp = "GREATER_THAN";
+                break;
+            case ">=":
+                firestoreOp = "GREATER_THAN_OR_EQUAL";
+                break;
+            case "array-contains":
+                firestoreOp = "ARRAY_CONTAINS";
+                break;
+            case "in":
+                firestoreOp = "IN";
+                break;
+            case "array-contains-any":
+                firestoreOp = "ARRAY_CONTAINS_ANY";
+                break;
+            case "not-in":
+                firestoreOp = "NOT_IN";
+                break;
+            default:
+                firestoreOp = opStr;
+        }
+        query._queryConstraints.where.push({
+            field: fieldPath,
+            op: firestoreOp,
+            value,
+        });
+        return query;
+    }
+    /**
+     * 並べ替え条件を追加
+     * @param fieldPath フィールドパス
+     * @param directionStr 並べ替え方向（'asc'または'desc'）
+     * @returns Queryインスタンス
+     */
+    orderBy(fieldPath, directionStr = "asc") {
+        const query = new Query(this.client, this.path, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        query._queryConstraints.orderBy = fieldPath;
+        query._queryConstraints.orderDirection =
+            directionStr === "asc" ? "ASCENDING" : "DESCENDING";
+        return query;
+    }
+    /**
+     * 取得件数の制限を設定
+     * @param limit 最大件数
+     * @returns Queryインスタンス
+     */
+    limit(limit) {
+        const query = new Query(this.client, this.path, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        query._queryConstraints.limit = limit;
+        return query;
+    }
+    /**
+     * スキップ件数を設定
+     * @param offset スキップ件数
+     * @returns Queryインスタンス
+     */
+    offset(offset) {
+        const query = new Query(this.client, this.path, {
+            ...this._queryConstraints,
+        }, this.allDescendants);
+        query._queryConstraints.offset = offset;
+        return query;
+    }
+    /**
+     * クエリを実行
+     * @returns QuerySnapshotインスタンス
+     */
+    async get() {
+        const results = await this.client.query(this.path, this._queryConstraints, this.allDescendants);
+        return new QuerySnapshot(results);
+    }
+}
+exports.CollectionGroup = CollectionGroup;
 /**
  * クエリクラス
  */
 class Query {
-    constructor(client, collectionPath, constraints) {
+    constructor(client, collectionPath, constraints, allDescendants) {
         this.client = client;
         this.collectionPath = collectionPath;
         this._queryConstraints = constraints;
+        this.allDescendants = allDescendants;
     }
     /**
      * フィルター条件を追加
@@ -523,7 +672,7 @@ class Query {
     where(fieldPath, opStr, value) {
         const query = new Query(this.client, this.collectionPath, {
             ...this._queryConstraints,
-        });
+        }, this.allDescendants);
         // 演算子の変換
         let firestoreOp;
         switch (opStr) {
@@ -576,7 +725,7 @@ class Query {
     orderBy(fieldPath, directionStr = "asc") {
         const query = new Query(this.client, this.collectionPath, {
             ...this._queryConstraints,
-        });
+        }, this.allDescendants);
         query._queryConstraints.orderBy = fieldPath;
         query._queryConstraints.orderDirection =
             directionStr === "asc" ? "ASCENDING" : "DESCENDING";
@@ -590,7 +739,7 @@ class Query {
     limit(limit) {
         const query = new Query(this.client, this.collectionPath, {
             ...this._queryConstraints,
-        });
+        }, this.allDescendants);
         query._queryConstraints.limit = limit;
         return query;
     }
@@ -602,7 +751,7 @@ class Query {
     offset(offset) {
         const query = new Query(this.client, this.collectionPath, {
             ...this._queryConstraints,
-        });
+        }, this.allDescendants);
         query._queryConstraints.offset = offset;
         return query;
     }
@@ -611,7 +760,7 @@ class Query {
      * @returns QuerySnapshotインスタンス
      */
     async get() {
-        const results = await this.client.query(this.collectionPath, this._queryConstraints);
+        const results = await this.client.query(this.collectionPath, this._queryConstraints, this.allDescendants);
         return new QuerySnapshot(results);
     }
 }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export * from "./types";
-import { FirestoreClient, createFirestoreClient, CollectionReference, DocumentReference, Query, QuerySnapshot, DocumentSnapshot, WriteResult } from "./client";
+import { FirestoreClient, createFirestoreClient, CollectionReference, DocumentReference, CollectionGroup, Query, QuerySnapshot, DocumentSnapshot, WriteResult } from "./client";
 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, };
+export { FirestoreClient, createFirestoreClient, CollectionReference, DocumentReference, CollectionGroup, 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.formatConfig = exports.formatPrivateKey = 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.CollectionGroup = 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);
 // クライアントのエクスポート
@@ -23,6 +23,7 @@ Object.defineProperty(exports, "FirestoreClient", { enumerable: true, get: funct
 Object.defineProperty(exports, "createFirestoreClient", { enumerable: true, get: function () { return client_1.createFirestoreClient; } });
 Object.defineProperty(exports, "CollectionReference", { enumerable: true, get: function () { return client_1.CollectionReference; } });
 Object.defineProperty(exports, "DocumentReference", { enumerable: true, get: function () { return client_1.DocumentReference; } });
+Object.defineProperty(exports, "CollectionGroup", { enumerable: true, get: function () { return client_1.CollectionGroup; } });
 Object.defineProperty(exports, "Query", { enumerable: true, get: function () { return client_1.Query; } });
 Object.defineProperty(exports, "QuerySnapshot", { enumerable: true, get: function () { return client_1.QuerySnapshot; } });
 Object.defineProperty(exports, "DocumentSnapshot", { enumerable: true, get: function () { return client_1.DocumentSnapshot; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firebase-rest-firestore",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Firebase Firestore REST API client for Edge runtime environments",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,13 +29,16 @@
     "jose": "^4.14.4"
   },
   "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
     "@types/node": "^18.16.0",
     "dotenv": "^16.4.7",
+    "semantic-release": "^24.2.3",
     "typescript": "^5.0.4",
     "vitest": "^3.0.9"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=20.8.1"
   },
   "repository": {
     "type": "git",