@cougargrades/firebase-rest-firestore 1.6.0

package/dist/esm/utils/path.js

@@ -0,0 +1,169 @@
+/**
+ * Utility class for constructing Firestore URIs
+ * Consistently handles different types of paths and operations
+ */
+export class FirestorePath {
+    /**
+     * Constructor
+     */
+    constructor(config, debug = false) {
+        this.useEmulator = false;
+        this.emulatorHost = "localhost";
+        this.emulatorPort = 8080;
+        this.debug = false;
+        this.projectId = config.projectId;
+        this.databaseId = config.databaseId || "(default)";
+        this.debug = debug;
+        if (config.useEmulator) {
+            this.useEmulator = true;
+            this.emulatorHost = config.emulatorHost || "localhost";
+            this.emulatorPort = config.emulatorPort || 8080;
+        }
+    }
+    /**
+     * Get Firestore base URL (without document path)
+     */
+    getBasePath() {
+        const baseUrl = this.useEmulator
+            ? `http://${this.emulatorHost}:${this.emulatorPort}/v1`
+            : "https://firestore.googleapis.com/v1";
+        const path = `${baseUrl}/projects/${this.projectId}/databases/${this.databaseId}/documents`;
+        if (this.debug) {
+            console.log(`Generated base path: ${path}`);
+        }
+        return path;
+    }
+    /**
+     * Get base URL + collection path for a collection root
+     * @param path Collection path (ex: "users" or "users/uid/posts")
+     */
+    getCollectionPath(path) {
+        // Remove leading and trailing slashes
+        const cleanPath = path.replace(/^\/+|\/+$/g, '');
+        const fullPath = `${this.getBasePath()}/${cleanPath}`;
+        if (this.debug) {
+            console.log(`Generated collection path: ${fullPath}`);
+        }
+        return fullPath;
+    }
+    /**
+     * Get the complete URL for a document
+     * @param collectionPath Collection path
+     * @param documentId Document ID
+     */
+    getDocumentPath(collectionPath, documentId) {
+        const cleanCollectionPath = collectionPath.replace(/^\/+|\/+$/g, '');
+        const path = `${this.getBasePath()}/${cleanCollectionPath}/${documentId}`;
+        if (this.debug) {
+            console.log(`Generated document path: ${path}`);
+        }
+        return path;
+    }
+    /**
+     * Get URL for query execution
+     * @param path Collection path (ex: "users" or "users/uid/posts")
+     * @returns URL for query execution, collection ID, and parent path (if needed)
+     */
+    getQueryPath(path) {
+        // パスをセグメントに分割
+        const segments = path.replace(/^\/+|\/+$/g, '').split('/');
+        // 単一コレクションの場合
+        if (segments.length === 1) {
+            const url = `${this.getBasePath()}:runQuery`;
+            if (this.debug) {
+                console.log(`Generated query URL (single collection): ${url}`);
+                console.log(`Collection ID: ${segments[0]}`);
+            }
+            return {
+                url,
+                collectionId: segments[0]
+            };
+        }
+        // ネストしたコレクションパスの場合 (例: "users/uid/posts")
+        const collectionId = segments[segments.length - 1];
+        const parentSegments = segments.slice(0, -1);
+        const parentPath = parentSegments.join('/');
+        // ベースURLでネストしたドキュメントまでのパスを取得
+        const url = `${this.getBasePath()}:runQuery`;
+        if (this.debug) {
+            console.log(`Generated query URL (nested collection): ${url}`);
+            console.log(`Collection ID: ${collectionId}`);
+            console.log(`Parent path: ${parentPath}`);
+        }
+        return {
+            url,
+            collectionId,
+            parentPath
+        };
+    }
+    /**
+     * Get reference path for parent document (for query construction)
+     * @param parentPath Parent document path
+     */
+    getParentReference(parentPath) {
+        return `projects/${this.projectId}/databases/${this.databaseId}/documents/${parentPath}`;
+    }
+    /**
+     * Get URL for runQuery
+     * @param collectionPath Collection path
+     * @returns URL for executing runQuery
+     */
+    getRunQueryPath(collectionPath) {
+        // コレクションパス情報を取得
+        const { collectionId, parentPath } = this.getQueryPath(collectionPath);
+        // parentPathがある場合は、親ドキュメントパスを使用してURLを作成
+        if (parentPath) {
+            // getBasePathからベースURLを取得
+            const baseUrl = this.getBasePath().replace(/\/documents$/, '');
+            // 親ドキュメントパスを含むrunQueryのURL
+            const runQueryUrl = `${baseUrl}/documents/${parentPath}:runQuery`;
+            if (this.debug) {
+                console.log(`Generated runQuery URL for nested collection: ${runQueryUrl}`);
+                console.log(`Collection ID: ${collectionId}`);
+            }
+            return runQueryUrl;
+        }
+        // トップレベルコレクションの場合は、ベースパスを使用
+        const baseUrl = this.getBasePath();
+        const runQueryUrl = `${baseUrl}:runQuery`;
+        if (this.debug) {
+            console.log(`Generated runQuery URL for top-level collection: ${runQueryUrl}`);
+            console.log(`Collection ID: ${collectionId}`);
+        }
+        return runQueryUrl;
+    }
+}
+/**
+ * Create an instance of FirestorePath class
+ * @param config Firestore configuration
+ * @param debug Debug mode
+ */
+export function createFirestorePath(config, debug = false) {
+    return new FirestorePath(config, debug);
+}
+/**
+ * Get Firestore base path URL (without path)
+ * @param projectId Project ID
+ * @param databaseId Database ID (defaults to default)
+ * @param config Firestore configuration (for emulator settings)
+ * @returns Firestore base path URL (without path)
+ */
+export function getFirestoreBasePath(projectId, databaseId, config) {
+    // Use emulator URL for emulator mode
+    if (config?.useEmulator) {
+        const host = config.emulatorHost || "127.0.0.1";
+        const port = config.emulatorPort || 8080;
+        return `http://${host}:${port}/v1/projects/${projectId}/databases/${databaseId || "(default)"}/documents`;
+    }
+    // Use normal production environment URL
+    return `https://firestore.googleapis.com/v1/projects/${projectId}/databases/${databaseId || "(default)"}/documents`;
+}
+/**
+ * Extract document ID from document path
+ * @param path Document path
+ * @returns Document ID
+ */
+export function getDocumentId(path) {
+    const parts = path.split("/");
+    return parts[parts.length - 1];
+}

package/dist/types/client.d.ts

@@ -0,0 +1,417 @@
+import { FirestoreConfig, QueryOptions } from "./types";
+/**
+ * Firestore client class
+ */
+export declare class FirestoreClient {
+    private token;
+    private tokenExpiry;
+    private config;
+    private configChecked;
+    private debug;
+    private pathUtil;
+    /**
+     * Constructor
+     * @param config Firestore configuration object
+     */
+    constructor(config: FirestoreConfig);
+    /**
+     * Check configuration parameters
+     * @private
+     */
+    private checkConfig;
+    /**
+     * Get authentication token (with caching)
+     */
+    private getToken;
+    /**
+     * Prepare request headers
+     * @param additionalHeaders Additional headers
+     * @returns Prepared headers object
+     * @private
+     */
+    private prepareHeaders;
+    /**
+     * Get collection reference
+     * @param path Collection path
+     * @returns CollectionReference instance
+     */
+    collection(path: string): CollectionReference;
+    /**
+     * Get document reference
+     * @param path Document path
+     * @returns DocumentReference instance
+     */
+    doc(path: string): DocumentReference;
+    /**
+     * Get collection group reference
+     * @param path Collection group ID
+     * @returns CollectionGroup instance
+     */
+    collectionGroup(path: string): CollectionGroup;
+    /**
+     * Add document to Firestore
+     * @param collectionName Collection name
+     * @param data Data to add
+     * @returns Added document
+     */
+    add(collectionName: string, data: Record<string, any>): Promise<Record<string, any> & {
+        id: string;
+    }>;
+    /**
+     * Get document
+     * @param collectionName Collection name
+     * @param documentId Document ID
+     * @returns Retrieved document (null if it doesn't exist)
+     */
+    get(collectionName: string, documentId: string): Promise<(Record<string, any> & {
+        id: string;
+    }) | null>;
+    /**
+     * Update document
+     * @param collectionName Collection name
+     * @param documentId Document ID
+     * @param data Data to update
+     * @returns Updated document
+     */
+    update(collectionName: string, documentId: string, data: Record<string, any>): Promise<Record<string, any> & {
+        id: string;
+    }>;
+    /**
+     * Delete document
+     * @param collectionName Collection name
+     * @param documentId Document ID
+     * @returns true if deletion successful
+     */
+    delete(collectionName: string, documentId: string): Promise<boolean>;
+    /**
+     * Query documents in a collection
+     * @param collectionPath Collection path
+     * @param options Query options
+     * @param allDescendants Whether to include descendant collections
+     * @returns Array of documents matching the query
+     */
+    query(collectionPath: string, options?: QueryOptions, allDescendants?: boolean): Promise<(Record<string, any> & {
+        id: string;
+    })[]>;
+    /**
+     * ドキュメントを作成または上書き
+     * @param collectionName コレクション名
+     * @param documentId ドキュメントID
+     * @param data ドキュメントデータ
+     * @returns 作成されたドキュメントのリファレンス
+     */
+    createWithId(collectionName: string, documentId: string, data: Record<string, any>): Promise<Record<string, any> & {
+        id: string;
+    }>;
+}
+/**
+ * Collection reference class
+ */
+export declare class CollectionReference {
+    private client;
+    private _path;
+    private _queryConstraints;
+    constructor(client: FirestoreClient, path: string);
+    /**
+     * Get collection path
+     */
+    get path(): string;
+    /**
+     * Whether to include all descendant collections
+     */
+    get allDescendants(): boolean;
+    /**
+     * Get document reference
+     * @param documentPath Document ID (auto-generated if omitted)
+     * @returns DocumentReference instance
+     */
+    doc(documentPath?: string): DocumentReference;
+    /**
+     * Add document (ID is auto-generated)
+     * @param data Document data
+     * @returns Reference to the created document
+     */
+    add(data: Record<string, any>): Promise<DocumentReference>;
+    /**
+     * Add filter condition
+     * @param fieldPath Field path
+     * @param opStr Operator
+     * @param value Value
+     * @returns Query instance
+     */
+    where(fieldPath: string, opStr: string, value: any): Query;
+    /**
+     * Add sorting condition
+     * @param fieldPath Field path
+     * @param directionStr Sort direction ('asc' or 'desc')
+     * @returns Query instance
+     */
+    orderBy(fieldPath: string, directionStr?: "asc" | "desc"): Query;
+    /**
+     * Set limit on number of results
+     * @param limit Maximum number
+     * @returns Query instance
+     */
+    limit(limit: number): Query;
+    /**
+     * Set number of documents to skip
+     * @param offset Number to skip
+     * @returns Query instance
+     */
+    offset(offset: number): Query;
+    /**
+     * Execute query
+     * @returns QuerySnapshot instance
+     */
+    get(): Promise<QuerySnapshot>;
+    /**
+     * Generate random ID
+     * @returns Random ID
+     */
+    private _generateId;
+}
+/**
+ * Document reference class
+ */
+export declare class DocumentReference {
+    private client;
+    private collectionPath;
+    private docId;
+    constructor(client: FirestoreClient, collectionPath: string, docId: string);
+    /**
+     * Get document ID
+     */
+    get id(): string;
+    /**
+     * Get document path
+     */
+    get path(): string;
+    /**
+     * Get parent collection reference
+     */
+    get parent(): CollectionReference;
+    /**
+     * Get subcollection
+     * @param collectionPath Subcollection name
+     * @returns CollectionReference instance
+     */
+    collection(collectionPath: string): CollectionReference;
+    /**
+     * Get document
+     * @returns DocumentSnapshot instance
+     */
+    get(): Promise<DocumentSnapshot>;
+    /**
+     * Create or overwrite document
+     * @param data Document data
+     * @param options Options (merge is not currently supported)
+     * @returns WriteResult instance
+     */
+    set(data: Record<string, any>, options?: {
+        merge?: boolean;
+    }): Promise<WriteResult>;
+    /**
+     * Update document
+     * @param data Update data
+     * @returns WriteResult instance
+     */
+    update(data: Record<string, any>): Promise<WriteResult>;
+    /**
+     * Delete document
+     * @returns WriteResult instance
+     */
+    delete(): Promise<WriteResult>;
+}
+/**
+ * Collection group
+ */
+export declare class CollectionGroup {
+    private client;
+    private path;
+    private _queryConstraints;
+    constructor(client: FirestoreClient, path: string);
+    /**
+     * Whether to include all descendant collections
+     */
+    get allDescendants(): boolean;
+    /**
+     * Add filter condition
+     * @param fieldPath Field path
+     * @param opStr Operator
+     * @param value Value
+     * @returns Query instance
+     */
+    where(fieldPath: string, opStr: string, value: any): Query;
+    /**
+     * Add sorting condition
+     * @param fieldPath Field path
+     * @param directionStr Sort direction ('asc' or 'desc')
+     * @returns Query instance
+     */
+    orderBy(fieldPath: string, directionStr?: "asc" | "desc"): Query;
+    /**
+     * Set limit on number of results
+     * @param limit Maximum number
+     * @returns Query instance
+     */
+    limit(limit: number): Query;
+    /**
+     * Set number of documents to skip
+     * @param offset Number to skip
+     * @returns Query instance
+     */
+    offset(offset: number): Query;
+    /**
+     * Execute query
+     * @returns QuerySnapshot instance
+     */
+    get(): Promise<QuerySnapshot>;
+}
+/**
+ * Query class
+ */
+export declare class Query {
+    private client;
+    private collectionPath;
+    private allDescendants;
+    _queryConstraints: {
+        where: Array<{
+            field: string;
+            op: string;
+            value: any;
+        }>;
+        orderBy?: string;
+        orderDirection?: string;
+        limit?: number;
+        offset?: number;
+    };
+    constructor(client: FirestoreClient, collectionPath: string, constraints: {
+        where: Array<{
+            field: string;
+            op: string;
+            value: any;
+        }>;
+        orderBy?: string;
+        orderDirection?: string;
+        limit?: number;
+        offset?: number;
+    }, allDescendants: boolean);
+    /**
+     * Add filter condition
+     * @param fieldPath Field path
+     * @param opStr Operator
+     * @param value Value
+     * @returns Query instance
+     */
+    where(fieldPath: string, opStr: string, value: any): Query;
+    /**
+     * Add sorting condition
+     * @param fieldPath Field path
+     * @param directionStr Sort direction ('asc' or 'desc')
+     * @returns Query instance
+     */
+    orderBy(fieldPath: string, directionStr?: "asc" | "desc"): Query;
+    /**
+     * Set limit on number of results
+     * @param limit Maximum number
+     * @returns Query instance
+     */
+    limit(limit: number): Query;
+    /**
+     * Set number of documents to skip
+     * @param offset Number to skip
+     * @returns Query instance
+     */
+    offset(offset: number): Query;
+    /**
+     * Execute query
+     * @returns QuerySnapshot instance
+     */
+    get(): Promise<QuerySnapshot>;
+}
+/**
+ * Query result class
+ */
+export declare class QuerySnapshot {
+    private _docs;
+    constructor(results: Array<Record<string, any>>);
+    /**
+     * Array of documents in the result
+     */
+    get docs(): DocumentSnapshot[];
+    /**
+     * Whether the result is empty
+     */
+    get empty(): boolean;
+    /**
+     * Number of results
+     */
+    get size(): number;
+    /**
+     * Execute callback for each document
+     * @param callback Callback function to execute for each document
+     */
+    forEach(callback: (result: DocumentSnapshot) => void): void;
+}
+/**
+ * Document snapshot class
+ */
+export declare class DocumentSnapshot {
+    private _id;
+    private _data;
+    constructor(id: string, data: Record<string, any> | null);
+    /**
+     * Document ID
+     */
+    get id(): string;
+    /**
+     * Whether the document exists
+     */
+    get exists(): boolean;
+    /**
+     * Get document data
+     * @returns Document data (undefined if it doesn't exist)
+     */
+    data(): Record<string, any> | undefined;
+}
+/**
+ * Write result class
+ */
+export declare class WriteResult {
+    /**
+     * Write timestamp
+     */
+    readonly writeTime: Date;
+    constructor();
+}
+/**
+ * Create a new Firestore client instance
+ * @param config Firestore configuration object
+ * @returns FirestoreClient instance
+ *
+ * @example
+ * // Connect to default database
+ * const db = createFirestoreClient({
+ *   projectId: 'your-project-id',
+ *   privateKey: 'your-private-key',
+ *   clientEmail: 'your-client-email'
+ * });
+ *
+ * // Connect to a different named database
+ * const customDb = createFirestoreClient({
+ *   projectId: 'your-project-id',
+ *   privateKey: 'your-private-key',
+ *   clientEmail: 'your-client-email',
+ *   databaseId: 'your-database-id'
+ * });
+ *
+ * // Connect to local emulator (no auth required)
+ * const emulatorDb = createFirestoreClient({
+ *   projectId: 'demo-project',
+ *   useEmulator: true,
+ *   emulatorHost: '127.0.',
+ *   emulatorPort: 8080,
+ *   debug: true // Optional: enables detailed logging
+ * });
+ */
+export declare function createFirestoreClient(config: FirestoreConfig): FirestoreClient;

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./types";
+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 } from "./utils/config";
+export { FirestoreClient, createFirestoreClient, CollectionReference, DocumentReference, CollectionGroup, Query, QuerySnapshot, DocumentSnapshot, WriteResult, };