firebase-rest-firestore 1.5.0 → 1.6.1

package/dist/esm/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レスポンス

package/dist/esm/utils/converter.js

@@ -1,3 +1,6 @@
+import { DocumentReference } from "../client";
+import { FieldValue } from "../field-value";
+import { LiteralDocumentReference, LiteralGeoPointValue, } from "../types";
 import { getDocumentId } from "./path";
 /**
  * JSの値をFirestore形式に変換する
@@ -5,9 +8,24 @@ import { getDocumentId } from "./path";
  * @returns Firestore形式の値
  */
 export function convertToFirestoreValue(value) {
+    if (value instanceof FieldValue) {
+        // Sentinels (e.g. serverTimestamp) must be extracted into field transforms
+        // before conversion. Reaching here means one was used where Firestore
+        // cannot express a transform (such as inside an array).
+        throw new Error("FieldValue (e.g. serverTimestamp()) can only be used as a top-level or nested document field value, not inside an array.");
+    }
     if (value instanceof Date) {
         return { timestampValue: value.toISOString() };
     }
+    else if (value instanceof DocumentReference) {
+        return { referenceValue: value.referenceValue };
+    }
+    else if (value instanceof LiteralDocumentReference) {
+        return { referenceValue: value.referenceValue };
+    }
+    else if (value instanceof LiteralGeoPointValue) {
+        return { geoPointValue: value.geoPointValue };
+    }
     else if (typeof value === "string") {
         return { stringValue: value };
     }
@@ -63,15 +81,21 @@ export function convertFromFirestoreValue(firestoreValue) {
     else if ("timestampValue" in firestoreValue) {
         return new Date(firestoreValue.timestampValue);
     }
+    else if ("geoPointValue" in firestoreValue) {
+        return new LiteralGeoPointValue(firestoreValue);
+    }
+    else if ("referenceValue" in firestoreValue) {
+        return new LiteralDocumentReference(firestoreValue);
+    }
     else if ("mapValue" in firestoreValue && firestoreValue.mapValue.fields) {
         return Object.entries(firestoreValue.mapValue.fields).reduce((acc, [key, val]) => ({
             ...acc,
             [key]: convertFromFirestoreValue(val),
         }), {});
     }
-    else if ("arrayValue" in firestoreValue &&
-        firestoreValue.arrayValue.values) {
-        return firestoreValue.arrayValue.values.map(convertFromFirestoreValue);
+    else if ("arrayValue" in firestoreValue) {
+        // The `values` field can be undefined, meaning that this is an empty array
+        return (firestoreValue.arrayValue.values ?? []).map(convertFromFirestoreValue);
     }
     return null;
 }
@@ -88,6 +112,91 @@ export function convertToFirestoreDocument(data) {
         }), {}),
     };
 }
+/**
+ * Whether a value is a plain JS object (`{}` / `Object.create(null)`), as
+ * opposed to a class instance such as `Date`, `DocumentReference`,
+ * `LiteralGeoPointValue`, `LiteralDocumentReference`, `FieldValue`, or an array.
+ * Only plain objects are recursed into when extracting field transforms.
+ */
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Escape a single field name for use in a Firestore field path. Simple names
+ * (`[A-Za-z_][A-Za-z0-9_]*`) are used as-is; anything else (dashes, dots,
+ * leading digits, spaces, ...) is wrapped in backticks with `\` and `` ` ``
+ * escaped, so a literal dot in a key is treated as part of the name rather than
+ * a path separator.
+ * See: https://firebase.google.com/docs/firestore/reference/rest/v1/projects.databases.documents#Document
+ */
+function escapeFieldPathSegment(segment) {
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(segment)) {
+        return segment;
+    }
+    return "`" + segment.replace(/\\/g, "\\\\").replace(/`/g, "\\`") + "`";
+}
+/**
+ * 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 function extractFieldTransforms(data, prefix = "") {
+    const fields = {};
+    const transforms = [];
+    for (const [key, value] of Object.entries(data)) {
+        const escapedKey = escapeFieldPathSegment(key);
+        const fieldPath = prefix ? `${prefix}.${escapedKey}` : escapedKey;
+        if (value instanceof FieldValue) {
+            if (value.methodName === "serverTimestamp") {
+                transforms.push({ fieldPath, setToServerValue: "REQUEST_TIME" });
+            }
+            else {
+                throw new Error(`Unsupported FieldValue: ${value.methodName}`);
+            }
+        }
+        else if (isPlainObject(value)) {
+            const nested = extractFieldTransforms(value, fieldPath);
+            fields[key] = nested.fields;
+            transforms.push(...nested.transforms);
+        }
+        else {
+            fields[key] = value;
+        }
+    }
+    return { fields, transforms };
+}
+/**
+ * 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 function buildCommitWrite(documentName, fields, transforms, currentDocument) {
+    const write = {
+        update: { name: documentName, fields },
+    };
+    if (transforms.length > 0) {
+        write.updateTransforms = transforms;
+    }
+    if (currentDocument) {
+        write.currentDocument = currentDocument;
+    }
+    return write;
+}
 /**
  * Firestoreドキュメントをオブジェクトに変換
  * @param doc Firestoreレスポンス

package/dist/types/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/types/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/types/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/types/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/types/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レスポンス

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firebase-rest-firestore",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Firebase Firestore REST API client for Edge runtime environments",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -23,6 +23,7 @@
     "emulator:start": "cd test/emulator && firebase emulators:start -P demo-test-project",
     "emulator:stop": "npx kill-port -y 4089 8089 9089",
     "test": "vitest",
+    "test:unit": "vitest run test/converter.test.ts test/references.test.ts test/field-value.test.ts test/request-headers.test.ts",
     "test:emulator": "bash test/scripts/test-with-emulator.sh"
   },
   "keywords": [
@@ -46,7 +47,7 @@
     "@types/node": "^18.16.0",
     "concurrently": "^8.2.2",
     "dotenv": "^16.4.7",
-    "semantic-release": "^24.2.3",
+    "semantic-release": "25.0.8",
     "typescript": "^5.0.4",
     "vitest": "^3.0.9"
   },