@cougargrades/firebase-rest-firestore 1.6.0

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

@@ -0,0 +1,43 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+// 型定義のエクスポート
+__exportStar(require("./types"), exports);
+// クライアントのエクスポート
+const client_1 = require("./client");
+Object.defineProperty(exports, "FirestoreClient", { enumerable: true, get: function () { return client_1.FirestoreClient; } });
+Object.defineProperty(exports, "createFirestoreClient", { enumerable: true, get: function () { return client_1.createFirestoreClient; } });
+Object.defineProperty(exports, "CollectionReference", { enumerable: true, get: function () { return client_1.CollectionReference; } });
+Object.defineProperty(exports, "DocumentReference", { enumerable: true, get: function () { return client_1.DocumentReference; } });
+Object.defineProperty(exports, "CollectionGroup", { enumerable: true, get: function () { return client_1.CollectionGroup; } });
+Object.defineProperty(exports, "Query", { enumerable: true, get: function () { return client_1.Query; } });
+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; } });
+// ユーティリティ関数のエクスポート
+var auth_1 = require("./utils/auth");
+Object.defineProperty(exports, "getFirestoreToken", { enumerable: true, get: function () { return auth_1.getFirestoreToken; } });
+var converter_1 = require("./utils/converter");
+Object.defineProperty(exports, "convertToFirestoreValue", { enumerable: true, get: function () { return converter_1.convertToFirestoreValue; } });
+Object.defineProperty(exports, "convertFromFirestoreValue", { enumerable: true, get: function () { return converter_1.convertFromFirestoreValue; } });
+Object.defineProperty(exports, "convertToFirestoreDocument", { enumerable: true, get: function () { return converter_1.convertToFirestoreDocument; } });
+Object.defineProperty(exports, "convertFromFirestoreDocument", { enumerable: true, get: function () { return converter_1.convertFromFirestoreDocument; } });
+var path_1 = require("./utils/path");
+Object.defineProperty(exports, "getFirestoreBasePath", { enumerable: true, get: function () { return path_1.getFirestoreBasePath; } });
+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; } });

package/dist/cjs/types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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">);
+    /**
+     * The pattern for globally unique Firestore Document Reference paths
+     */
+    private static pattern;
+    /**
+     * Parse using URLPattern, which is a relatively new addition to the standard.
+     * See: https://urlpattern.spec.whatwg.org/#dom-urlpattern-protocol
+     * Added in Node.js v23: https://nodejs.org/api/url.html#class-urlpattern
+     * Baseline 2025 in browsers: https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/protocol
+     * @returns
+     */
+    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[];
+    };
+};
+/**
+ * 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,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiteralGeoPointValue = exports.LiteralDocumentReference = void 0;
+const urlpattern_polyfill_1 = require("urlpattern-polyfill");
+/**
+ * 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 using URLPattern, which is a relatively new addition to the standard.
+     * See: https://urlpattern.spec.whatwg.org/#dom-urlpattern-protocol
+     * Added in Node.js v23: https://nodejs.org/api/url.html#class-urlpattern
+     * Baseline 2025 in browsers: https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/protocol
+     * @returns
+     */
+    parse() {
+        const result = LiteralDocumentReference.pattern.exec(`https://hostname/${this.referenceValue}`);
+        if (!result)
+            throw new Error("Invalid document path. Path does not match pattern.");
+        const project_id = result.pathname.groups["project_id"];
+        if (!project_id)
+            throw new Error("Invalid document path. Path does not match pattern.");
+        const database_id = result.pathname.groups["database_id"];
+        if (!database_id)
+            throw new Error("Invalid document path. Path does not match pattern.");
+        const document_path = result.pathname.groups["document_path"];
+        if (!document_path)
+            throw new Error("Invalid document path. Path does not match pattern.");
+        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;
+/**
+ * The pattern for globally unique Firestore Document Reference paths
+ */
+LiteralDocumentReference.pattern = new urlpattern_polyfill_1.URLPattern({ pathname: `/projects/:project_id/databases/:database_id/documents/:document_path*` });
+/**
+ * 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/cjs/utils/auth.js

@@ -0,0 +1,94 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJWT = createJWT;
+exports.getFirestoreToken = getFirestoreToken;
+const jose = __importStar(require("jose"));
+/**
+ * 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);
+    const payload = {
+        iss: config.clientEmail,
+        sub: config.clientEmail,
+        aud: "https://oauth2.googleapis.com/token",
+        iat: now,
+        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");
+        // Create JWT
+        const token = await new jose.SignJWT(payload)
+            .setProtectedHeader({
+            alg: "RS256",
+            typ: "JWT",
+        })
+            .sign(privateKey);
+        return token;
+    }
+    catch (error) {
+        console.error("Error creating JWT:", error);
+        throw error;
+    }
+}
+/**
+ * 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: {
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+            assertion: await createJWT(config),
+        }),
+    });
+    const data = (await response.json());
+    return data.access_token;
+}

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

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

package/dist/cjs/utils/config.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatPrivateKey = formatPrivateKey;
+/**
+ * 秘密鍵の文字列内にある改行コードのエスケープシーケンスを実際の改行に変換する
+ * @param privateKey 変換する秘密鍵文字列
+ * @returns 変換後の秘密鍵文字列
+ */
+function formatPrivateKey(privateKey) {
+    if (privateKey.includes("\\n")) {
+        return privateKey.replace(/\\n/g, "\n");
+    }
+    return privateKey;
+}

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

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertToFirestoreValue = convertToFirestoreValue;
+exports.convertFromFirestoreValue = convertFromFirestoreValue;
+exports.convertToFirestoreDocument = convertToFirestoreDocument;
+exports.convertFromFirestoreDocument = convertFromFirestoreDocument;
+const client_1 = require("../client");
+const types_1 = require("../types");
+const path_1 = require("./path");
+/**
+ * JSの値をFirestore形式に変換する
+ * @param value 変換する値
+ * @returns Firestore形式の値
+ */
+function convertToFirestoreValue(value) {
+    // store in temporary variable to enable TypeScript to be more thorough
+    let unknown = value;
+    if (value instanceof Date) {
+        return { timestampValue: value.toISOString() };
+    }
+    else if (value instanceof client_1.DocumentReference) {
+        return { referenceValue: value["client"]["pathUtil"].getParentReference(value.path) };
+    }
+    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 &&
+        firestoreValue.arrayValue.values) {
+        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),
+        }), {}),
+    };
+}
+/**
+ * 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;