firebase-rest-firestore 1.5.0 → 1.6.0

package/README.md

@@ -134,6 +134,43 @@ Parameters:
 
 Returns: The added document with auto-generated ID.
 
+### FieldValue
+
+Sentinels for special write behaviors, mirroring the native Firebase SDK.
+
+#### FieldValue.serverTimestamp()
+
+Sets the field to the server's request timestamp at write time (rather than an
+unreliable client clock). Works with `add`, `update`, `set`, and `createWithId`,
+including nested fields. The returned document contains the resolved `Date`.
+
+```typescript
+import { createFirestoreClient, FieldValue } from "firebase-rest-firestore";
+
+const client = createFirestoreClient(config);
+
+// On create (auto-generated ID)
+const post = await client.add("posts", {
+  title: "Hello",
+  createdAt: FieldValue.serverTimestamp(),
+});
+console.log(post.createdAt); // Date, set by the server
+
+// On update
+await client.update("posts", post.id, {
+  updatedAt: FieldValue.serverTimestamp(),
+});
+
+// Nested fields are supported too
+await client.collection("posts").doc(post.id).set({
+  meta: { touchedAt: FieldValue.serverTimestamp() },
+});
+```
+
+> Writes containing a `FieldValue` are sent through the Firestore `commit`
+> endpoint so the transform is applied server-side. A `FieldValue` cannot be
+> used inside an array.
+
 ## Error Handling
 
 Firebase REST Firestore throws exceptions with appropriate error messages when API requests fail. Here's an example of error handling:

package/dist/cjs/client.d.ts

@@ -30,6 +30,30 @@ export declare class FirestoreClient {
      * @private
      */
     private prepareHeaders;
+    /**
+     * Build the fully-qualified Firestore reference value for a document path,
+     * e.g. `projects/{projectId}/databases/{databaseId}/documents/{path}`.
+     * Used to encode a DocumentReference without exposing internal path helpers.
+     * @param documentPath Document path (ex: "users/uid/posts/postId")
+     */
+    getReferenceValue(documentPath: string): string;
+    /**
+     * Apply a single write through the `documents:commit` endpoint. This is the
+     * only REST path that supports field transforms (e.g. server timestamps).
+     * @param collectionName Collection path
+     * @param documentId Document ID
+     * @param fields Already-converted Firestore field values
+     * @param transforms Field transforms to apply after the update
+     * @param currentDocument Optional precondition (e.g. `{ exists: false }`)
+     * @private
+     */
+    private commit;
+    /**
+     * Commit a write and read the document back, so the resolved transform
+     * values (e.g. the server timestamp) are returned to the caller.
+     * @private
+     */
+    private commitAndRead;
     /**
      * Get collection reference
      * @param path Collection path
@@ -57,6 +81,14 @@ export declare class FirestoreClient {
     add(collectionName: string, data: Record<string, any>): Promise<Record<string, any> & {
         id: string;
     }>;
+    /**
+     * Create a document that contains field transforms (e.g. serverTimestamp)
+     * with an auto-generated ID. Uses the commit endpoint with an
+     * `exists: false` precondition and retries on the (astronomically unlikely)
+     * ID collision, mirroring the uniqueness of server-generated IDs.
+     * @private
+     */
+    private addWithTransforms;
     /**
      * Get document
      * @param collectionName Collection name
@@ -186,6 +218,11 @@ export declare class DocumentReference {
      * Get document path
      */
     get path(): string;
+    /**
+     * Fully-qualified Firestore reference value for this document, e.g.
+     * `projects/{projectId}/databases/{databaseId}/documents/{path}`.
+     */
+    get referenceValue(): string;
     /**
      * Get parent collection reference
      */

package/dist/cjs/client.js

@@ -7,6 +7,17 @@ const converter_1 = require("./utils/converter");
 const path_1 = require("./utils/path");
 const config_1 = require("./utils/config");
 const path_2 = require("./utils/path");
+/**
+ * Generate a random 20-character document ID (same alphabet as the Firebase SDKs).
+ */
+function generateAutoId() {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    let id = "";
+    for (let i = 0; i < 20; i++) {
+        id += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return id;
+}
 /**
  * Firestore client class
  */
@@ -94,6 +105,63 @@ class FirestoreClient {
         }
         return headers;
     }
+    /**
+     * Build the fully-qualified Firestore reference value for a document path,
+     * e.g. `projects/{projectId}/databases/{databaseId}/documents/{path}`.
+     * Used to encode a DocumentReference without exposing internal path helpers.
+     * @param documentPath Document path (ex: "users/uid/posts/postId")
+     */
+    getReferenceValue(documentPath) {
+        return this.pathUtil.getParentReference(documentPath);
+    }
+    /**
+     * Apply a single write through the `documents:commit` endpoint. This is the
+     * only REST path that supports field transforms (e.g. server timestamps).
+     * @param collectionName Collection path
+     * @param documentId Document ID
+     * @param fields Already-converted Firestore field values
+     * @param transforms Field transforms to apply after the update
+     * @param currentDocument Optional precondition (e.g. `{ exists: false }`)
+     * @private
+     */
+    async commit(collectionName, documentId, fields, transforms, currentDocument) {
+        const documentName = this.pathUtil.getParentReference(`${collectionName}/${documentId}`);
+        const write = (0, converter_1.buildCommitWrite)(documentName, fields, transforms, currentDocument);
+        const url = `${this.pathUtil.getBasePath()}:commit`;
+        if (this.debug) {
+            console.log(`Committing write to: ${url}`, JSON.stringify(write));
+        }
+        const headers = await this.prepareHeaders();
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ writes: [write] }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            if (this.debug) {
+                console.error(`Error response: ${errorText}`);
+            }
+            const error = new Error(`Firestore API error: ${response.statusText || response.status} - ${errorText}`);
+            error.status = response.status;
+            error.alreadyExists =
+                response.status === 409 || /ALREADY_EXISTS/.test(errorText);
+            throw error;
+        }
+    }
+    /**
+     * Commit a write and read the document back, so the resolved transform
+     * values (e.g. the server timestamp) are returned to the caller.
+     * @private
+     */
+    async commitAndRead(collectionName, documentId, fields, transforms, currentDocument) {
+        await this.commit(collectionName, documentId, fields, transforms, currentDocument);
+        const saved = await this.get(collectionName, documentId);
+        if (!saved) {
+            throw new Error(`Document ${collectionName}/${documentId} could not be read back after commit`);
+        }
+        return saved;
+    }
     /**
      * Get collection reference
      * @param path Collection path
@@ -138,6 +206,12 @@ class FirestoreClient {
         if (this.debug) {
             console.log(`Adding document to collection: ${collectionName}`, data);
         }
+        // When the data contains field transforms (e.g. serverTimestamp), the
+        // create must go through the commit endpoint with a client-generated ID.
+        const { fields: plainData, transforms } = (0, converter_1.extractFieldTransforms)(data);
+        if (transforms.length > 0) {
+            return this.addWithTransforms(collectionName, plainData, transforms);
+        }
         const url = this.pathUtil.getCollectionPath(collectionName);
         const firestoreData = (0, converter_1.convertToFirestoreDocument)(data);
         if (this.debug) {
@@ -162,6 +236,31 @@ class FirestoreClient {
         const result = (await response.json());
         return (0, converter_1.convertFromFirestoreDocument)(result);
     }
+    /**
+     * Create a document that contains field transforms (e.g. serverTimestamp)
+     * with an auto-generated ID. Uses the commit endpoint with an
+     * `exists: false` precondition and retries on the (astronomically unlikely)
+     * ID collision, mirroring the uniqueness of server-generated IDs.
+     * @private
+     */
+    async addWithTransforms(collectionName, plainData, transforms) {
+        const fields = (0, converter_1.convertToFirestoreDocument)(plainData).fields;
+        const maxAttempts = 5;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const documentId = generateAutoId();
+            try {
+                return await this.commitAndRead(collectionName, documentId, fields, transforms, { exists: false });
+            }
+            catch (error) {
+                const collided = error?.alreadyExists;
+                if (collided && attempt < maxAttempts - 1) {
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw new Error("Failed to generate a unique document ID after multiple attempts");
+    }
     /**
      * Get document
      * @param collectionName Collection name
@@ -266,6 +365,13 @@ class FirestoreClient {
                 data = { ...existingDoc, ...data };
             }
         }
+        // Route writes that contain field transforms (e.g. serverTimestamp)
+        // through the commit endpoint; the merged document is sent as the update.
+        const { fields: plainData, transforms } = (0, converter_1.extractFieldTransforms)(data);
+        if (transforms.length > 0) {
+            const fields = (0, converter_1.convertToFirestoreDocument)(plainData).fields;
+            return this.commitAndRead(collectionName, documentId, fields, transforms);
+        }
         const firestoreData = (0, converter_1.convertToFirestoreDocument)(data);
         const headers = await this.prepareHeaders();
         const response = await fetch(url, {
@@ -469,6 +575,13 @@ class FirestoreClient {
     async createWithId(collectionName, documentId, data) {
         // 操作前に設定をチェック
         this.checkConfig();
+        // Route writes that contain field transforms (e.g. serverTimestamp)
+        // through the commit endpoint (which creates the document if absent).
+        const { fields: plainData, transforms } = (0, converter_1.extractFieldTransforms)(data);
+        if (transforms.length > 0) {
+            const fields = (0, converter_1.convertToFirestoreDocument)(plainData).fields;
+            return this.commitAndRead(collectionName, documentId, fields, transforms);
+        }
         const url = `${(0, path_1.getFirestoreBasePath)(this.config.projectId, this.config.databaseId, this.config)}/${collectionName}/${documentId}`;
         const firestoreData = (0, converter_1.convertToFirestoreDocument)(data);
         const token = await this.getToken();
@@ -636,13 +749,7 @@ class CollectionReference {
      * @returns Random ID
      */
     _generateId() {
-        // Generate 20-character random ID
-        const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
-        let id = "";
-        for (let i = 0; i < 20; i++) {
-            id += chars.charAt(Math.floor(Math.random() * chars.length));
-        }
-        return id;
+        return generateAutoId();
     }
 }
 exports.CollectionReference = CollectionReference;
@@ -667,6 +774,13 @@ class DocumentReference {
     get path() {
         return `${this.collectionPath}/${this.docId}`;
     }
+    /**
+     * Fully-qualified Firestore reference value for this document, e.g.
+     * `projects/{projectId}/databases/{databaseId}/documents/{path}`.
+     */
+    get referenceValue() {
+        return this.client.getReferenceValue(this.path);
+    }
     /**
      * Get parent collection reference
      */

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/cjs/index.d.ts

@@ -1,5 +1,6 @@
 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";

package/dist/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.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; } });

package/dist/cjs/types.d.ts

@@ -11,8 +11,63 @@ export interface FirestoreConfig {
     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;
@@ -26,7 +81,7 @@ export type FirestoreFieldValue = {
     nullValue: null;
 } | {
     timestampValue: string;
-} | {
+} | Pick<LiteralGeoPointValue, 'geoPointValue'> | Pick<LiteralDocumentReference, 'referenceValue'> | {
     mapValue: {
         fields: Record<string, FirestoreFieldValue>;
     };
@@ -35,6 +90,28 @@ export type FirestoreFieldValue = {
         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ドキュメント型
  */

package/dist/cjs/types.js

@@ -1,2 +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/converter.d.ts

@@ -1,4 +1,4 @@
-import { FirestoreDocument, FirestoreFieldValue, FirestoreResponse } from "../types";
+import { CommitWrite, FieldTransform, FirestoreDocument, FirestoreFieldValue, FirestoreResponse } from "../types";
 /**
  * JSの値をFirestore形式に変換する
  * @param value 変換する値
@@ -17,6 +17,36 @@ export declare function convertFromFirestoreValue(firestoreValue: FirestoreField
  * @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レスポンス