@cougargrades/firebase-rest-firestore 1.6.0

package/dist/cjs/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;