firebase-rest-firestore 1.1.2 → 1.5.0

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, };

package/dist/types/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Firestoreクライアントの設定インターフェース
+ */
+export interface FirestoreConfig {
+    projectId: string;
+    privateKey: string;
+    clientEmail: string;
+    databaseId?: string;
+    debug?: boolean;
+    useEmulator?: boolean;
+    emulatorHost?: string;
+    emulatorPort?: number;
+}
+/**
+ * Firestoreの値型定義
+ */
+export type FirestoreFieldValue = {
+    stringValue: string;
+} | {
+    integerValue: number;
+} | {
+    doubleValue: number;
+} | {
+    booleanValue: boolean;
+} | {
+    nullValue: null;
+} | {
+    timestampValue: string;
+} | {
+    mapValue: {
+        fields: Record<string, FirestoreFieldValue>;
+    };
+} | {
+    arrayValue: {
+        values: FirestoreFieldValue[];
+    };
+};
+/**
+ * Firestoreドキュメント型
+ */
+export interface FirestoreDocument {
+    name?: string;
+    fields: Record<string, FirestoreFieldValue>;
+    createTime?: string;
+    updateTime?: string;
+}
+/**
+ * Firestoreレスポンス型
+ */
+export interface FirestoreResponse {
+    name: string;
+    fields?: Record<string, FirestoreFieldValue>;
+    createTime?: string;
+    updateTime?: string;
+}
+/**
+ * クエリオプション型
+ */
+export interface QueryOptions {
+    where?: Array<{
+        field: string;
+        op: string;
+        value: any;
+    }>;
+    orderBy?: string;
+    orderDirection?: string;
+    limit?: number;
+    offset?: number;
+}

package/dist/types/utils/auth.d.ts

@@ -0,0 +1,13 @@
+import { FirestoreConfig } from "../types";
+/**
+ * Function to create a JWT (JSON Web Token)
+ * @param config Firestore configuration
+ * @returns JWT string
+ */
+export declare function createJWT(config: FirestoreConfig): Promise<string>;
+/**
+ * Function to get Firestore authentication token
+ * @param config Firestore configuration
+ * @returns Access token
+ */
+export declare function getFirestoreToken(config: FirestoreConfig): Promise<string>;

package/dist/types/utils/config.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 秘密鍵の文字列内にある改行コードのエスケープシーケンスを実際の改行に変換する
+ * @param privateKey 変換する秘密鍵文字列
+ * @returns 変換後の秘密鍵文字列
+ */
+export declare function formatPrivateKey(privateKey: string): string;

package/dist/types/utils/converter.d.ts

@@ -0,0 +1,27 @@
+import { FirestoreDocument, FirestoreFieldValue, FirestoreResponse } from "../types";
+/**
+ * JSの値をFirestore形式に変換する
+ * @param value 変換する値
+ * @returns Firestore形式の値
+ */
+export declare function convertToFirestoreValue(value: any): FirestoreFieldValue;
+/**
+ * Firestore形式からJSの値に変換する
+ * @param firestoreValue Firestore形式の値
+ * @returns JS形式の値
+ */
+export declare function convertFromFirestoreValue(firestoreValue: FirestoreFieldValue): any;
+/**
+ * オブジェクトをFirestoreドキュメント形式に変換
+ * @param data 変換するオブジェクト
+ * @returns Firestoreドキュメント
+ */
+export declare function convertToFirestoreDocument(data: Record<string, any>): FirestoreDocument;
+/**
+ * Firestoreドキュメントをオブジェクトに変換
+ * @param doc Firestoreレスポンス
+ * @returns 変換されたオブジェクト（idプロパティ付き）
+ */
+export declare function convertFromFirestoreDocument(doc: FirestoreResponse): Record<string, any> & {
+    id: string;
+};

package/dist/types/utils/path.d.ts

@@ -0,0 +1,73 @@
+import { FirestoreConfig } from "../types";
+/**
+ * Utility class for constructing Firestore URIs
+ * Consistently handles different types of paths and operations
+ */
+export declare class FirestorePath {
+    private projectId;
+    private databaseId;
+    private useEmulator;
+    private emulatorHost;
+    private emulatorPort;
+    private debug;
+    /**
+     * Constructor
+     */
+    constructor(config: FirestoreConfig, debug?: boolean);
+    /**
+     * Get Firestore base URL (without document path)
+     */
+    getBasePath(): string;
+    /**
+     * Get base URL + collection path for a collection root
+     * @param path Collection path (ex: "users" or "users/uid/posts")
+     */
+    getCollectionPath(path: string): string;
+    /**
+     * Get the complete URL for a document
+     * @param collectionPath Collection path
+     * @param documentId Document ID
+     */
+    getDocumentPath(collectionPath: string, documentId: string): string;
+    /**
+     * 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: string): {
+        url: string;
+        collectionId: string;
+        parentPath?: string;
+    };
+    /**
+     * Get reference path for parent document (for query construction)
+     * @param parentPath Parent document path
+     */
+    getParentReference(parentPath: string): string;
+    /**
+     * Get URL for runQuery
+     * @param collectionPath Collection path
+     * @returns URL for executing runQuery
+     */
+    getRunQueryPath(collectionPath: string): string;
+}
+/**
+ * Create an instance of FirestorePath class
+ * @param config Firestore configuration
+ * @param debug Debug mode
+ */
+export declare function createFirestorePath(config: FirestoreConfig, debug?: boolean): FirestorePath;
+/**
+ * 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 declare function getFirestoreBasePath(projectId: string, databaseId?: string, config?: FirestoreConfig): string;
+/**
+ * Extract document ID from document path
+ * @param path Document path
+ * @returns Document ID
+ */
+export declare function getDocumentId(path: string): string;

package/package.json

@@ -1,17 +1,29 @@
 {
   "name": "firebase-rest-firestore",
-  "version": "1.1.2",
+  "version": "1.5.0",
   "description": "Firebase Firestore REST API client for Edge runtime environments",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
   "files": [
     "dist",
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.json --emitDeclarationOnly --declarationDir dist/types",
+    "watch": "concurrently \"npm run watch:esm\" \"npm run watch:cjs\" \"npm run watch:types\"",
+    "watch:esm": "tsc -p tsconfig.esm.json --watch",
+    "watch:cjs": "tsc -p tsconfig.cjs.json --watch",
+    "watch:types": "tsc -p tsconfig.json --emitDeclarationOnly --declarationDir dist/types --watch",
     "prepublishOnly": "npm run build",
-    "test": "vitest"
+    "setup:local:env": "cp .env.local.example .env && echo 'Created .env file from local example.'",
+    "emulator:start": "cd test/emulator && firebase emulators:start -P demo-test-project",
+    "emulator:stop": "npx kill-port -y 4089 8089 9089",
+    "test": "vitest",
+    "test:emulator": "bash test/scripts/test-with-emulator.sh"
   },
   "keywords": [
     "firebase",
@@ -32,6 +44,7 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/node": "^18.16.0",
+    "concurrently": "^8.2.2",
     "dotenv": "^16.4.7",
     "semantic-release": "^24.2.3",
     "typescript": "^5.0.4",