firebase-rest-firestore 1.2.0 → 1.6.0

package/dist/cjs/field-value.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Sentinel values for special write behaviors, mirroring the native Firebase
+ * SDK's `FieldValue`. Currently only `serverTimestamp()` is supported.
+ *
+ * A `FieldValue` is not a real field value: when used as a field in a write it
+ * is translated into a Firestore field transform (applied server-side) rather
+ * than serialized as data. Using one anywhere else (e.g. inside an array) is an
+ * error.
+ */
+export declare class FieldValue {
+    readonly methodName: "serverTimestamp";
+    private constructor();
+    /**
+     * Returns a sentinel that sets the field to the server's request timestamp at
+     * write time, e.g. `client.add("posts", { createdAt: FieldValue.serverTimestamp() })`.
+     */
+    static serverTimestamp(): FieldValue;
+    /**
+     * Whether this sentinel represents the same transform as another.
+     */
+    isEqual(other: FieldValue): boolean;
+}

package/dist/cjs/field-value.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldValue = void 0;
+/**
+ * Sentinel values for special write behaviors, mirroring the native Firebase
+ * SDK's `FieldValue`. Currently only `serverTimestamp()` is supported.
+ *
+ * A `FieldValue` is not a real field value: when used as a field in a write it
+ * is translated into a Firestore field transform (applied server-side) rather
+ * than serialized as data. Using one anywhere else (e.g. inside an array) is an
+ * error.
+ */
+class FieldValue {
+    constructor(methodName) {
+        this.methodName = methodName;
+    }
+    /**
+     * Returns a sentinel that sets the field to the server's request timestamp at
+     * write time, e.g. `client.add("posts", { createdAt: FieldValue.serverTimestamp() })`.
+     */
+    static serverTimestamp() {
+        return new FieldValue("serverTimestamp");
+    }
+    /**
+     * Whether this sentinel represents the same transform as another.
+     */
+    isEqual(other) {
+        return other instanceof FieldValue && other.methodName === this.methodName;
+    }
+}
+exports.FieldValue = FieldValue;

package/dist/{index.d.ts → cjs/index.d.ts}

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

package/dist/{index.js → cjs/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.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;
+exports.WriteResult = exports.DocumentSnapshot = exports.QuerySnapshot = exports.Query = exports.CollectionGroup = exports.DocumentReference = exports.CollectionReference = exports.createFirestoreClient = exports.FirestoreClient = exports.formatPrivateKey = exports.getDocumentId = exports.getFirestoreBasePath = exports.convertFromFirestoreDocument = exports.convertToFirestoreDocument = exports.convertFromFirestoreValue = exports.convertToFirestoreValue = exports.getFirestoreToken = exports.FieldValue = void 0;
 // 型定義のエクスポート
 __exportStar(require("./types"), exports);
 // クライアントのエクスポート
@@ -28,6 +28,9 @@ Object.defineProperty(exports, "Query", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "QuerySnapshot", { enumerable: true, get: function () { return client_1.QuerySnapshot; } });
 Object.defineProperty(exports, "DocumentSnapshot", { enumerable: true, get: function () { return client_1.DocumentSnapshot; } });
 Object.defineProperty(exports, "WriteResult", { enumerable: true, get: function () { return client_1.WriteResult; } });
+// FieldValue センチネルのエクスポート
+var field_value_1 = require("./field-value");
+Object.defineProperty(exports, "FieldValue", { enumerable: true, get: function () { return field_value_1.FieldValue; } });
 // ユーティリティ関数のエクスポート
 var auth_1 = require("./utils/auth");
 Object.defineProperty(exports, "getFirestoreToken", { enumerable: true, get: function () { return auth_1.getFirestoreToken; } });
@@ -41,4 +44,3 @@ Object.defineProperty(exports, "getFirestoreBasePath", { enumerable: true, get:
 Object.defineProperty(exports, "getDocumentId", { enumerable: true, get: function () { return path_1.getDocumentId; } });
 var config_1 = require("./utils/config");
 Object.defineProperty(exports, "formatPrivateKey", { enumerable: true, get: function () { return config_1.formatPrivateKey; } });
-Object.defineProperty(exports, "formatConfig", { enumerable: true, get: function () { return config_1.formatConfig; } });

package/dist/cjs/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Firestoreクライアントの設定インターフェース
+ */
+export interface FirestoreConfig {
+    projectId: string;
+    privateKey: string;
+    clientEmail: string;
+    databaseId?: string;
+    debug?: boolean;
+    useEmulator?: boolean;
+    emulatorHost?: string;
+    emulatorPort?: number;
+}
+/**
+ * A reference to a document. For example: `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
+ * Used to represent document references globally and not connected to any particular client.
+ */
+export declare class LiteralDocumentReference {
+    referenceValue: string;
+    constructor(options: Pick<LiteralDocumentReference, "referenceValue">);
+    /**
+     * Globally unique Firestore document reference paths look like:
+     *   projects/{project_id}/databases/{database_id}/documents/{document_path}
+     * The database id (e.g. `(default)`) never contains a slash, while the
+     * document path may contain many. A single anchored regex parses this
+     * without pulling in a URLPattern polyfill.
+     */
+    private static readonly pattern;
+    private parse;
+    /**
+     * Get Project ID
+     */
+    get project_id(): string;
+    /**
+     * Get Database ID
+     * Ex: `(default)`
+     */
+    get database_id(): string;
+    /**
+     * Get document ID
+     */
+    get id(): string;
+    /**
+     * Get the collection ID
+     */
+    get collectionPath(): string;
+    /**
+     * Get document path
+     */
+    get path(): string;
+}
+/**
+ * A geo point value representing a point on the surface of Earth.
+ */
+export declare class LiteralGeoPointValue {
+    geoPointValue: {
+        /**
+         * The latitude in degrees. It must be in the range [-90.0, +90.0].
+         */
+        latitude: number;
+        /**
+         * The longitude in degrees. It must be in the range [-180.0, +180.0].
+         */
+        longitude: number;
+    };
+    constructor(options: Pick<LiteralGeoPointValue, "geoPointValue">);
+}
+/**
+ * Firestoreの値型定義
+ * See: https://github.com/googleapis/google-api-nodejs-client/blob/5870dfe31f4885eebc82c19f7471c50403308f26/src/apis/firestore/v1.ts#L2246
+ */
+export type FirestoreFieldValue = {
+    stringValue: string;
+} | {
+    integerValue: number;
+} | {
+    doubleValue: number;
+} | {
+    booleanValue: boolean;
+} | {
+    nullValue: null;
+} | {
+    timestampValue: string;
+} | Pick<LiteralGeoPointValue, 'geoPointValue'> | Pick<LiteralDocumentReference, 'referenceValue'> | {
+    mapValue: {
+        fields: Record<string, FirestoreFieldValue>;
+    };
+} | {
+    arrayValue: {
+        values: FirestoreFieldValue[];
+    };
+};
+/**
+ * A Firestore field transform applied server-side during a commit write.
+ * See: https://firebase.google.com/docs/firestore/reference/rest/v1/Write#FieldTransform
+ */
+export interface FieldTransform {
+    fieldPath: string;
+    setToServerValue: "REQUEST_TIME";
+}
+/**
+ * A single write in a `documents:commit` request.
+ */
+export interface CommitWrite {
+    update: {
+        name: string;
+        fields: Record<string, FirestoreFieldValue>;
+    };
+    updateTransforms?: FieldTransform[];
+    currentDocument?: {
+        exists?: boolean;
+        updateTime?: string;
+    };
+}
+/**
+ * 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/cjs/types.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiteralGeoPointValue = exports.LiteralDocumentReference = void 0;
+/**
+ * A reference to a document. For example: `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
+ * Used to represent document references globally and not connected to any particular client.
+ */
+class LiteralDocumentReference {
+    constructor(options) {
+        this.referenceValue = options.referenceValue;
+    }
+    parse() {
+        const match = LiteralDocumentReference.pattern.exec(this.referenceValue);
+        if (!match) {
+            throw new Error("Invalid document path. Path does not match pattern.");
+        }
+        const [, project_id, database_id, document_path] = match;
+        return { project_id, database_id, document_path };
+    }
+    /**
+     * Get Project ID
+     */
+    get project_id() {
+        return this.parse().project_id;
+    }
+    /**
+     * Get Database ID
+     * Ex: `(default)`
+     */
+    get database_id() {
+        return this.parse().database_id;
+    }
+    /**
+     * Get document ID
+     */
+    get id() {
+        const path = this.parse().document_path;
+        const parts = path.split("/");
+        const docId = parts[parts.length - 1];
+        return docId;
+    }
+    /**
+     * Get the collection ID
+     */
+    get collectionPath() {
+        const path = this.parse().document_path;
+        const parts = path.split("/");
+        const collectionPath = parts.slice(0, parts.length - 1).join("/");
+        return collectionPath;
+    }
+    /**
+     * Get document path
+     */
+    get path() {
+        return this.parse().document_path;
+    }
+}
+exports.LiteralDocumentReference = LiteralDocumentReference;
+/**
+ * Globally unique Firestore document reference paths look like:
+ *   projects/{project_id}/databases/{database_id}/documents/{document_path}
+ * The database id (e.g. `(default)`) never contains a slash, while the
+ * document path may contain many. A single anchored regex parses this
+ * without pulling in a URLPattern polyfill.
+ */
+LiteralDocumentReference.pattern = /^projects\/([^/]+)\/databases\/([^/]+)\/documents\/(.+)$/;
+/**
+ * A geo point value representing a point on the surface of Earth.
+ */
+class LiteralGeoPointValue {
+    constructor(options) {
+        this.geoPointValue = options.geoPointValue;
+    }
+}
+exports.LiteralGeoPointValue = LiteralGeoPointValue;

package/dist/cjs/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/{utils → cjs/utils}/auth.js

@@ -37,9 +37,9 @@ exports.createJWT = createJWT;
 exports.getFirestoreToken = getFirestoreToken;
 const jose = __importStar(require("jose"));
 /**
- * JWT（JSON Web Token）を作成する関数
- * @param config Firestore設定
- * @returns JWT文字列
+ * Function to create a JWT (JSON Web Token)
+ * @param config Firestore configuration
+ * @returns JWT string
  */
 async function createJWT(config) {
     const now = Math.floor(Date.now() / 1000);
@@ -48,13 +48,13 @@ async function createJWT(config) {
         sub: config.clientEmail,
         aud: "https://oauth2.googleapis.com/token",
         iat: now,
-        exp: now + 3600, // 1時間後に期限切れ
+        exp: now + 3600, // Expires in 1 hour
         scope: "https://www.googleapis.com/auth/datastore",
     };
     try {
-        // 秘密鍵をインポート
+        // Import the private key
         const privateKey = await jose.importPKCS8(config.privateKey, "RS256");
-        // JWTを作成
+        // Create JWT
         const token = await new jose.SignJWT(payload)
             .setProtectedHeader({
             alg: "RS256",
@@ -69,12 +69,16 @@ async function createJWT(config) {
     }
 }
 /**
- * Firestoreの認証トークンを取得する関数
- * @param config Firestore設定
- * @returns アクセストークン
+ * Function to get Firestore authentication token
+ * @param config Firestore configuration
+ * @returns Access token
  */
 async function getFirestoreToken(config) {
-    // トークンを取得するためのリクエスト
+    // No authentication in emulator mode (returns a dummy token)
+    if (config.useEmulator) {
+        return "firebase-emulator-auth-token";
+    }
+    // Normal authentication process
     const response = await fetch("https://oauth2.googleapis.com/token", {
         method: "POST",
         headers: {

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

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

package/dist/{utils → cjs/utils}/config.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatPrivateKey = formatPrivateKey;
-exports.formatConfig = formatConfig;
 /**
  * 秘密鍵の文字列内にある改行コードのエスケープシーケンスを実際の改行に変換する
  * @param privateKey 変換する秘密鍵文字列
@@ -13,14 +12,3 @@ function formatPrivateKey(privateKey) {
     }
     return privateKey;
 }
-/**
- * FirestoreConfigオブジェクトの秘密鍵をフォーマットする
- * @param config 元のconfigオブジェクト
- * @returns 秘密鍵をフォーマットしたconfigオブジェクト
- */
-function formatConfig(config) {
-    return {
-        ...config,
-        privateKey: formatPrivateKey(config.privateKey),
-    };
-}

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

@@ -0,0 +1,57 @@
+import { CommitWrite, FieldTransform, 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;
+/**
+ * Split write data into plain field values and Firestore field transforms.
+ *
+ * `FieldValue` sentinels (e.g. `serverTimestamp()`) are pulled out into
+ * transforms keyed by their (escaped, dot-separated) field path; everything
+ * else is left untouched in `fields`. Recursion only descends into plain
+ * objects, so class instances (Date / references / geo points) are treated as
+ * leaves.
+ *
+ * @param data Write data (JS values, may contain FieldValue sentinels)
+ * @param prefix Field-path prefix used while recursing (internal, pre-escaped)
+ */
+export declare function extractFieldTransforms(data: Record<string, any>, prefix?: string): {
+    fields: Record<string, any>;
+    transforms: FieldTransform[];
+};
+/**
+ * Build a single `documents:commit` write that updates a document and applies
+ * field transforms. `updateTransforms` / `currentDocument` are only included
+ * when relevant.
+ *
+ * @param documentName Full resource name (projects/.../documents/<path>)
+ * @param fields Already-converted Firestore field values
+ * @param transforms Field transforms to apply after the update
+ * @param currentDocument Optional precondition (e.g. `{ exists: false }`)
+ */
+export declare function buildCommitWrite(documentName: string, fields: Record<string, FirestoreFieldValue>, transforms: FieldTransform[], currentDocument?: {
+    exists?: boolean;
+    updateTime?: string;
+}): CommitWrite;
+/**
+ * Firestoreドキュメントをオブジェクトに変換
+ * @param doc Firestoreレスポンス
+ * @returns 変換されたオブジェクト（idプロパティ付き）
+ */
+export declare function convertFromFirestoreDocument(doc: FirestoreResponse): Record<string, any> & {
+    id: string;
+};