firebase-rest-firestore 1.2.0 → 1.6.0

package/dist/cjs/utils/converter.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertToFirestoreValue = convertToFirestoreValue;
+exports.convertFromFirestoreValue = convertFromFirestoreValue;
+exports.convertToFirestoreDocument = convertToFirestoreDocument;
+exports.extractFieldTransforms = extractFieldTransforms;
+exports.buildCommitWrite = buildCommitWrite;
+exports.convertFromFirestoreDocument = convertFromFirestoreDocument;
+const client_1 = require("../client");
+const field_value_1 = require("../field-value");
+const types_1 = require("../types");
+const path_1 = require("./path");
+/**
+ * JSの値をFirestore形式に変換する
+ * @param value 変換する値
+ * @returns Firestore形式の値
+ */
+function convertToFirestoreValue(value) {
+    if (value instanceof field_value_1.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 client_1.DocumentReference) {
+        return { referenceValue: value.referenceValue };
+    }
+    else if (value instanceof types_1.LiteralDocumentReference) {
+        return { referenceValue: value.referenceValue };
+    }
+    else if (value instanceof types_1.LiteralGeoPointValue) {
+        return { geoPointValue: value.geoPointValue };
+    }
+    else if (typeof value === "string") {
+        return { stringValue: value };
+    }
+    else if (typeof value === "number") {
+        return Number.isInteger(value)
+            ? { integerValue: value }
+            : { doubleValue: value };
+    }
+    else if (typeof value === "boolean") {
+        return { booleanValue: value };
+    }
+    else if (value === null || value === undefined) {
+        return { nullValue: null };
+    }
+    else if (Array.isArray(value)) {
+        return {
+            arrayValue: {
+                values: value.map(item => convertToFirestoreValue(item)),
+            },
+        };
+    }
+    else if (typeof value === "object") {
+        const fields = Object.entries(value).reduce((acc, [key, val]) => ({
+            ...acc,
+            [key]: convertToFirestoreValue(val),
+        }), {});
+        return { mapValue: { fields } };
+    }
+    // デフォルトは文字列化
+    return { stringValue: String(value) };
+}
+/**
+ * Firestore形式からJSの値に変換する
+ * @param firestoreValue Firestore形式の値
+ * @returns JS形式の値
+ */
+function convertFromFirestoreValue(firestoreValue) {
+    if ("stringValue" in firestoreValue) {
+        return firestoreValue.stringValue;
+    }
+    else if ("integerValue" in firestoreValue) {
+        return Number(firestoreValue.integerValue);
+    }
+    else if ("doubleValue" in firestoreValue) {
+        return firestoreValue.doubleValue;
+    }
+    else if ("booleanValue" in firestoreValue) {
+        return firestoreValue.booleanValue;
+    }
+    else if ("nullValue" in firestoreValue) {
+        return null;
+    }
+    else if ("timestampValue" in firestoreValue) {
+        return new Date(firestoreValue.timestampValue);
+    }
+    else if ("geoPointValue" in firestoreValue) {
+        return new types_1.LiteralGeoPointValue(firestoreValue);
+    }
+    else if ("referenceValue" in firestoreValue) {
+        return new types_1.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) {
+        // The `values` field can be undefined, meaning that this is an empty array
+        return (firestoreValue.arrayValue.values ?? []).map(convertFromFirestoreValue);
+    }
+    return null;
+}
+/**
+ * オブジェクトをFirestoreドキュメント形式に変換
+ * @param data 変換するオブジェクト
+ * @returns Firestoreドキュメント
+ */
+function convertToFirestoreDocument(data) {
+    return {
+        fields: Object.entries(data).reduce((acc, [key, value]) => ({
+            ...acc,
+            [key]: convertToFirestoreValue(value),
+        }), {}),
+    };
+}
+/**
+ * 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)
+ */
+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 field_value_1.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 }`)
+ */
+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レスポンス
+ * @returns 変換されたオブジェクト（idプロパティ付き）
+ */
+function convertFromFirestoreDocument(doc) {
+    if (!doc.fields)
+        return { id: (0, path_1.getDocumentId)(doc.name) };
+    const result = Object.entries(doc.fields).reduce((acc, [key, value]) => ({
+        ...acc,
+        [key]: convertFromFirestoreValue(value),
+    }), {});
+    return {
+        ...result,
+        id: (0, path_1.getDocumentId)(doc.name),
+    };
+}

package/dist/cjs/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/dist/cjs/utils/path.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirestorePath = void 0;
+exports.createFirestorePath = createFirestorePath;
+exports.getFirestoreBasePath = getFirestoreBasePath;
+exports.getDocumentId = getDocumentId;
+/**
+ * Utility class for constructing Firestore URIs
+ * Consistently handles different types of paths and operations
+ */
+class FirestorePath {
+    /**
+     * Constructor
+     */
+    constructor(config, debug = false) {
+        this.useEmulator = false;
+        this.emulatorHost = "localhost";
+        this.emulatorPort = 8080;
+        this.debug = false;
+        this.projectId = config.projectId;
+        this.databaseId = config.databaseId || "(default)";
+        this.debug = debug;
+        if (config.useEmulator) {
+            this.useEmulator = true;
+            this.emulatorHost = config.emulatorHost || "localhost";
+            this.emulatorPort = config.emulatorPort || 8080;
+        }
+    }
+    /**
+     * Get Firestore base URL (without document path)
+     */
+    getBasePath() {
+        const baseUrl = this.useEmulator
+            ? `http://${this.emulatorHost}:${this.emulatorPort}/v1`
+            : "https://firestore.googleapis.com/v1";
+        const path = `${baseUrl}/projects/${this.projectId}/databases/${this.databaseId}/documents`;
+        if (this.debug) {
+            console.log(`Generated base path: ${path}`);
+        }
+        return path;
+    }
+    /**
+     * Get base URL + collection path for a collection root
+     * @param path Collection path (ex: "users" or "users/uid/posts")
+     */
+    getCollectionPath(path) {
+        // Remove leading and trailing slashes
+        const cleanPath = path.replace(/^\/+|\/+$/g, '');
+        const fullPath = `${this.getBasePath()}/${cleanPath}`;
+        if (this.debug) {
+            console.log(`Generated collection path: ${fullPath}`);
+        }
+        return fullPath;
+    }
+    /**
+     * Get the complete URL for a document
+     * @param collectionPath Collection path
+     * @param documentId Document ID
+     */
+    getDocumentPath(collectionPath, documentId) {
+        const cleanCollectionPath = collectionPath.replace(/^\/+|\/+$/g, '');
+        const path = `${this.getBasePath()}/${cleanCollectionPath}/${documentId}`;
+        if (this.debug) {
+            console.log(`Generated document path: ${path}`);
+        }
+        return path;
+    }
+    /**
+     * 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) {
+        // パスをセグメントに分割
+        const segments = path.replace(/^\/+|\/+$/g, '').split('/');
+        // 単一コレクションの場合
+        if (segments.length === 1) {
+            const url = `${this.getBasePath()}:runQuery`;
+            if (this.debug) {
+                console.log(`Generated query URL (single collection): ${url}`);
+                console.log(`Collection ID: ${segments[0]}`);
+            }
+            return {
+                url,
+                collectionId: segments[0]
+            };
+        }
+        // ネストしたコレクションパスの場合 (例: "users/uid/posts")
+        const collectionId = segments[segments.length - 1];
+        const parentSegments = segments.slice(0, -1);
+        const parentPath = parentSegments.join('/');
+        // ベースURLでネストしたドキュメントまでのパスを取得
+        const url = `${this.getBasePath()}:runQuery`;
+        if (this.debug) {
+            console.log(`Generated query URL (nested collection): ${url}`);
+            console.log(`Collection ID: ${collectionId}`);
+            console.log(`Parent path: ${parentPath}`);
+        }
+        return {
+            url,
+            collectionId,
+            parentPath
+        };
+    }
+    /**
+     * Get reference path for parent document (for query construction)
+     * @param parentPath Parent document path
+     */
+    getParentReference(parentPath) {
+        return `projects/${this.projectId}/databases/${this.databaseId}/documents/${parentPath}`;
+    }
+    /**
+     * Get URL for runQuery
+     * @param collectionPath Collection path
+     * @returns URL for executing runQuery
+     */
+    getRunQueryPath(collectionPath) {
+        // コレクションパス情報を取得
+        const { collectionId, parentPath } = this.getQueryPath(collectionPath);
+        // parentPathがある場合は、親ドキュメントパスを使用してURLを作成
+        if (parentPath) {
+            // getBasePathからベースURLを取得
+            const baseUrl = this.getBasePath().replace(/\/documents$/, '');
+            // 親ドキュメントパスを含むrunQueryのURL
+            const runQueryUrl = `${baseUrl}/documents/${parentPath}:runQuery`;
+            if (this.debug) {
+                console.log(`Generated runQuery URL for nested collection: ${runQueryUrl}`);
+                console.log(`Collection ID: ${collectionId}`);
+            }
+            return runQueryUrl;
+        }
+        // トップレベルコレクションの場合は、ベースパスを使用
+        const baseUrl = this.getBasePath();
+        const runQueryUrl = `${baseUrl}:runQuery`;
+        if (this.debug) {
+            console.log(`Generated runQuery URL for top-level collection: ${runQueryUrl}`);
+            console.log(`Collection ID: ${collectionId}`);
+        }
+        return runQueryUrl;
+    }
+}
+exports.FirestorePath = FirestorePath;
+/**
+ * Create an instance of FirestorePath class
+ * @param config Firestore configuration
+ * @param debug Debug mode
+ */
+function createFirestorePath(config, debug = false) {
+    return new FirestorePath(config, debug);
+}
+/**
+ * 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)
+ */
+function getFirestoreBasePath(projectId, databaseId, config) {
+    // Use emulator URL for emulator mode
+    if (config?.useEmulator) {
+        const host = config.emulatorHost || "127.0.0.1";
+        const port = config.emulatorPort || 8080;
+        return `http://${host}:${port}/v1/projects/${projectId}/databases/${databaseId || "(default)"}/documents`;
+    }
+    // Use normal production environment URL
+    return `https://firestore.googleapis.com/v1/projects/${projectId}/databases/${databaseId || "(default)"}/documents`;
+}
+/**
+ * Extract document ID from document path
+ * @param path Document path
+ * @returns Document ID
+ */
+function getDocumentId(path) {
+    const parts = path.split("/");
+    return parts[parts.length - 1];
+}