firestore-batch-updater 1.0.0

package/dist/index.mjs

@@ -0,0 +1,616 @@
+// src/utils/logger.ts
+import * as fs from "fs";
+import * as path from "path";
+function getTimestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function generateLogFilename(operation) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  return `${operation}-${timestamp}.log`;
+}
+function ensureLogDirectory(logPath) {
+  if (!fs.existsSync(logPath)) {
+    fs.mkdirSync(logPath, { recursive: true });
+  }
+}
+function formatOperationLog(log) {
+  const lines = [];
+  const separator = "=".repeat(60);
+  lines.push(separator);
+  lines.push(`FIRESTORE BATCH OPERATION LOG`);
+  lines.push(separator);
+  lines.push("");
+  lines.push(`Operation: ${log.operation.toUpperCase()}`);
+  lines.push(`Collection: ${log.collection}`);
+  lines.push(`Started: ${log.startedAt}`);
+  lines.push(`Completed: ${log.completedAt}`);
+  lines.push("");
+  if (log.conditions && log.conditions.length > 0) {
+    lines.push("Conditions:");
+    for (const condition of log.conditions) {
+      lines.push(`  - ${condition.field} ${condition.operator} ${formatValue(condition.value)}`);
+    }
+    lines.push("");
+  }
+  if (log.updateData) {
+    lines.push("Update Data:");
+    lines.push(`  ${JSON.stringify(log.updateData, null, 2).replace(/\n/g, "\n  ")}`);
+    lines.push("");
+  }
+  lines.push(separator);
+  lines.push("SUMMARY");
+  lines.push(separator);
+  lines.push(`Total: ${log.summary.totalCount}`);
+  lines.push(`Success: ${log.summary.successCount}`);
+  lines.push(`Failure: ${log.summary.failureCount}`);
+  lines.push("");
+  if (log.entries.length > 0) {
+    lines.push(separator);
+    lines.push("DETAILS");
+    lines.push(separator);
+    lines.push("");
+    for (const entry of log.entries) {
+      const statusLabel = entry.status === "success" ? "[SUCCESS]" : "[FAILURE]";
+      lines.push(`${entry.timestamp} ${statusLabel} ${entry.documentId}`);
+      if (entry.error) {
+        lines.push(`  Error: ${entry.error}`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push(separator);
+  lines.push("END OF LOG");
+  lines.push(separator);
+  return lines.join("\n");
+}
+function formatValue(value) {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "string") {
+    return `"${value}"`;
+  }
+  return String(value);
+}
+function writeOperationLog(log, options) {
+  const logPath = options.path || "./logs";
+  const filename = options.filename || generateLogFilename(log.operation);
+  const fullPath = path.join(logPath, filename);
+  ensureLogDirectory(logPath);
+  const content = formatOperationLog(log);
+  fs.writeFileSync(fullPath, content, "utf-8");
+  return fullPath;
+}
+function createLogCollector(operation, collection, conditions, updateData) {
+  const startedAt = getTimestamp();
+  const entries = [];
+  return {
+    addEntry(documentId, status, error) {
+      entries.push({
+        timestamp: getTimestamp(),
+        documentId,
+        status,
+        error
+      });
+    },
+    getLog() {
+      const successCount = entries.filter((e) => e.status === "success").length;
+      const failureCount = entries.filter((e) => e.status === "failure").length;
+      return {
+        operation,
+        collection,
+        startedAt,
+        completedAt: getTimestamp(),
+        conditions,
+        updateData,
+        summary: {
+          totalCount: entries.length,
+          successCount,
+          failureCount
+        },
+        entries
+      };
+    },
+    finalize(options) {
+      const log = this.getLog();
+      return writeOperationLog(log, options);
+    }
+  };
+}
+
+// src/utils/index.ts
+function calculateProgress(current, total) {
+  const percentage = total === 0 ? 0 : Math.round(current / total * 100);
+  return {
+    current,
+    total,
+    percentage
+  };
+}
+function getAffectedFields(updateData) {
+  return Object.keys(updateData);
+}
+function mergeUpdateData(existingData, updateData) {
+  return {
+    ...existingData,
+    ...updateData
+  };
+}
+function isValidUpdateData(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length > 0;
+}
+function formatError(error, context) {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  return context ? `Error at ${context}: ${errorMessage}` : errorMessage;
+}
+
+// src/core/batch-updater.ts
+var BatchUpdater = class {
+  /**
+   * Create a new BatchUpdater instance
+   * @param firestore - Initialized Firestore instance from firebase-admin
+   */
+  constructor(firestore) {
+    this.conditions = [];
+    this.firestore = firestore;
+  }
+  /**
+   * Select a collection to operate on
+   * @param path - Collection path
+   * @returns This instance for chaining
+   */
+  collection(path2) {
+    this.collectionPath = path2;
+    this.conditions = [];
+    return this;
+  }
+  /**
+   * Add a where condition to filter documents
+   * @param field - Field path
+   * @param operator - Comparison operator
+   * @param value - Value to compare
+   * @returns This instance for chaining
+   */
+  where(field, operator, value) {
+    this.conditions.push({ field, operator, value });
+    return this;
+  }
+  /**
+   * Preview changes before executing update
+   * @param updateData - Data to update
+   * @returns Preview result with affected count and samples
+   */
+  async preview(updateData) {
+    this.validateSetup();
+    if (!isValidUpdateData(updateData)) {
+      throw new Error("Update data must be a non-empty object");
+    }
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    const affectedCount = snapshot.size;
+    const affectedFields = getAffectedFields(updateData);
+    const samples = [];
+    const sampleDocs = snapshot.docs.slice(0, 10);
+    for (const doc of sampleDocs) {
+      const before = doc.data();
+      const after = mergeUpdateData(before, updateData);
+      samples.push({
+        id: doc.id,
+        before,
+        after
+      });
+    }
+    return {
+      affectedCount,
+      samples,
+      affectedFields
+    };
+  }
+  /**
+   * Execute batch update operation
+   * @param updateData - Data to update
+   * @param options - Update options (e.g., progress callback, log options, batchSize for pagination)
+   * @returns Update result with success/failure counts and optional log file path
+   */
+  async update(updateData, options = {}) {
+    this.validateSetup();
+    if (!isValidUpdateData(updateData)) {
+      throw new Error("Update data must be a non-empty object");
+    }
+    const logCollector = options.log?.enabled ? createLogCollector("update", this.collectionPath, this.conditions, updateData) : null;
+    let successCount = 0;
+    let failureCount = 0;
+    let totalCount = 0;
+    const failedDocIds = [];
+    if (options.batchSize && options.batchSize > 0) {
+      const countQuery = this.buildQuery();
+      const countSnapshot = await countQuery.count().get();
+      totalCount = countSnapshot.data().count;
+      if (totalCount === 0) {
+        const result2 = {
+          successCount: 0,
+          failureCount: 0,
+          totalCount: 0
+        };
+        if (logCollector && options.log) {
+          result2.logFilePath = logCollector.finalize(options.log);
+        }
+        return result2;
+      }
+      let processedCount = 0;
+      let lastDoc = null;
+      while (true) {
+        let paginatedQuery = this.buildQuery().limit(options.batchSize);
+        if (lastDoc) {
+          paginatedQuery = paginatedQuery.startAfter(lastDoc);
+        }
+        const snapshot = await paginatedQuery.get();
+        if (snapshot.empty) {
+          break;
+        }
+        const bulkWriter = this.firestore.bulkWriter();
+        const docIdMap = /* @__PURE__ */ new Map();
+        for (const doc of snapshot.docs) {
+          docIdMap.set(doc.ref.path, doc.id);
+        }
+        bulkWriter.onWriteResult((ref) => {
+          successCount++;
+          processedCount++;
+          const docId = docIdMap.get(ref.path) || ref.id;
+          logCollector?.addEntry(docId, "success");
+          if (options.onProgress) {
+            const progress = calculateProgress(processedCount, totalCount);
+            options.onProgress(progress);
+          }
+        });
+        bulkWriter.onWriteError((error) => {
+          failureCount++;
+          processedCount++;
+          const docId = error.documentRef?.id || "unknown";
+          failedDocIds.push(docId);
+          logCollector?.addEntry(docId, "failure", error.message);
+          if (options.onProgress) {
+            const progress = calculateProgress(processedCount, totalCount);
+            options.onProgress(progress);
+          }
+          return false;
+        });
+        for (const doc of snapshot.docs) {
+          bulkWriter.update(doc.ref, updateData);
+        }
+        await bulkWriter.close();
+        lastDoc = snapshot.docs[snapshot.docs.length - 1];
+        if (snapshot.docs.length < options.batchSize) {
+          break;
+        }
+      }
+    } else {
+      const query = this.buildQuery();
+      const snapshot = await query.get();
+      totalCount = snapshot.size;
+      if (totalCount === 0) {
+        const result2 = {
+          successCount: 0,
+          failureCount: 0,
+          totalCount: 0
+        };
+        if (logCollector && options.log) {
+          result2.logFilePath = logCollector.finalize(options.log);
+        }
+        return result2;
+      }
+      const bulkWriter = this.firestore.bulkWriter();
+      let processedCount = 0;
+      const docIdMap = /* @__PURE__ */ new Map();
+      for (const doc of snapshot.docs) {
+        docIdMap.set(doc.ref.path, doc.id);
+      }
+      bulkWriter.onWriteResult((ref) => {
+        successCount++;
+        processedCount++;
+        const docId = docIdMap.get(ref.path) || ref.id;
+        logCollector?.addEntry(docId, "success");
+        if (options.onProgress) {
+          const progress = calculateProgress(processedCount, totalCount);
+          options.onProgress(progress);
+        }
+      });
+      bulkWriter.onWriteError((error) => {
+        failureCount++;
+        processedCount++;
+        const docId = error.documentRef?.id || "unknown";
+        failedDocIds.push(docId);
+        logCollector?.addEntry(docId, "failure", error.message);
+        if (options.onProgress) {
+          const progress = calculateProgress(processedCount, totalCount);
+          options.onProgress(progress);
+        }
+        return false;
+      });
+      for (const doc of snapshot.docs) {
+        bulkWriter.update(doc.ref, updateData);
+      }
+      await bulkWriter.close();
+    }
+    const result = {
+      successCount,
+      failureCount,
+      totalCount,
+      failedDocIds: failedDocIds.length > 0 ? failedDocIds : void 0
+    };
+    if (logCollector && options.log) {
+      result.logFilePath = logCollector.finalize(options.log);
+    }
+    return result;
+  }
+  /**
+   * Get specific field values from matching documents
+   * @param fieldPath - Field path to retrieve
+   * @returns Array of field values with document IDs
+   */
+  async getFields(fieldPath) {
+    this.validateSetup();
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    const results = [];
+    for (const doc of snapshot.docs) {
+      const data = doc.data();
+      const value = this.getNestedValue(data, fieldPath);
+      results.push({
+        id: doc.id,
+        value
+      });
+    }
+    return results;
+  }
+  /**
+   * Create multiple documents in batch
+   * @param documents - Array of documents to create
+   * @param options - Create options (e.g., progress callback, log options)
+   * @returns Create result with success/failure counts, created IDs, and optional log file path
+   */
+  async create(documents, options = {}) {
+    this.validateSetup();
+    if (!Array.isArray(documents) || documents.length === 0) {
+      throw new Error("Documents array must be non-empty");
+    }
+    for (const doc of documents) {
+      if (!isValidUpdateData(doc.data)) {
+        throw new Error("Each document must have valid data");
+      }
+    }
+    const totalCount = documents.length;
+    let successCount = 0;
+    let failureCount = 0;
+    const createdIds = [];
+    const failedDocIds = [];
+    const logCollector = options.log?.enabled ? createLogCollector("create", this.collectionPath) : null;
+    const bulkWriter = this.firestore.bulkWriter();
+    const collection = this.firestore.collection(this.collectionPath);
+    let processedCount = 0;
+    bulkWriter.onWriteResult((ref) => {
+      successCount++;
+      processedCount++;
+      createdIds.push(ref.id);
+      logCollector?.addEntry(ref.id, "success");
+      if (options.onProgress) {
+        const progress = calculateProgress(processedCount, totalCount);
+        options.onProgress(progress);
+      }
+    });
+    bulkWriter.onWriteError((error) => {
+      failureCount++;
+      processedCount++;
+      const docId = error.documentRef?.id || "unknown";
+      failedDocIds.push(docId);
+      logCollector?.addEntry(docId, "failure", error.message);
+      if (options.onProgress) {
+        const progress = calculateProgress(processedCount, totalCount);
+        options.onProgress(progress);
+      }
+      return false;
+    });
+    for (const doc of documents) {
+      const docRef = doc.id ? collection.doc(doc.id) : collection.doc();
+      bulkWriter.create(docRef, doc.data);
+    }
+    await bulkWriter.close();
+    const result = {
+      successCount,
+      failureCount,
+      totalCount,
+      createdIds,
+      failedDocIds: failedDocIds.length > 0 ? failedDocIds : void 0
+    };
+    if (logCollector && options.log) {
+      result.logFilePath = logCollector.finalize(options.log);
+    }
+    return result;
+  }
+  /**
+   * Upsert documents matching query conditions
+   * Updates existing documents or creates them if they don't exist
+   * @param updateData - Data to set/merge
+   * @param options - Upsert options (e.g., progress callback, log options, batchSize for pagination)
+   * @returns Upsert result with success/failure counts and optional log file path
+   */
+  async upsert(updateData, options = {}) {
+    this.validateSetup();
+    if (!isValidUpdateData(updateData)) {
+      throw new Error("Update data must be a non-empty object");
+    }
+    const logCollector = options.log?.enabled ? createLogCollector("upsert", this.collectionPath, this.conditions, updateData) : null;
+    let successCount = 0;
+    let failureCount = 0;
+    let totalCount = 0;
+    const failedDocIds = [];
+    if (options.batchSize && options.batchSize > 0) {
+      const countQuery = this.buildQuery();
+      const countSnapshot = await countQuery.count().get();
+      totalCount = countSnapshot.data().count;
+      if (totalCount === 0) {
+        const result2 = {
+          successCount: 0,
+          failureCount: 0,
+          totalCount: 0
+        };
+        if (logCollector && options.log) {
+          result2.logFilePath = logCollector.finalize(options.log);
+        }
+        return result2;
+      }
+      let processedCount = 0;
+      let lastDoc = null;
+      while (true) {
+        let paginatedQuery = this.buildQuery().limit(options.batchSize);
+        if (lastDoc) {
+          paginatedQuery = paginatedQuery.startAfter(lastDoc);
+        }
+        const snapshot = await paginatedQuery.get();
+        if (snapshot.empty) {
+          break;
+        }
+        const bulkWriter = this.firestore.bulkWriter();
+        const docIdMap = /* @__PURE__ */ new Map();
+        for (const doc of snapshot.docs) {
+          docIdMap.set(doc.ref.path, doc.id);
+        }
+        bulkWriter.onWriteResult((ref) => {
+          successCount++;
+          processedCount++;
+          const docId = docIdMap.get(ref.path) || ref.id;
+          logCollector?.addEntry(docId, "success");
+          if (options.onProgress) {
+            const progress = calculateProgress(processedCount, totalCount);
+            options.onProgress(progress);
+          }
+        });
+        bulkWriter.onWriteError((error) => {
+          failureCount++;
+          processedCount++;
+          const docId = error.documentRef?.id || "unknown";
+          failedDocIds.push(docId);
+          logCollector?.addEntry(docId, "failure", error.message);
+          if (options.onProgress) {
+            const progress = calculateProgress(processedCount, totalCount);
+            options.onProgress(progress);
+          }
+          return false;
+        });
+        for (const doc of snapshot.docs) {
+          bulkWriter.set(doc.ref, updateData, { merge: true });
+        }
+        await bulkWriter.close();
+        lastDoc = snapshot.docs[snapshot.docs.length - 1];
+        if (snapshot.docs.length < options.batchSize) {
+          break;
+        }
+      }
+    } else {
+      const query = this.buildQuery();
+      const snapshot = await query.get();
+      totalCount = snapshot.size;
+      if (totalCount === 0) {
+        const result2 = {
+          successCount: 0,
+          failureCount: 0,
+          totalCount: 0
+        };
+        if (logCollector && options.log) {
+          result2.logFilePath = logCollector.finalize(options.log);
+        }
+        return result2;
+      }
+      const bulkWriter = this.firestore.bulkWriter();
+      let processedCount = 0;
+      const docIdMap = /* @__PURE__ */ new Map();
+      for (const doc of snapshot.docs) {
+        docIdMap.set(doc.ref.path, doc.id);
+      }
+      bulkWriter.onWriteResult((ref) => {
+        successCount++;
+        processedCount++;
+        const docId = docIdMap.get(ref.path) || ref.id;
+        logCollector?.addEntry(docId, "success");
+        if (options.onProgress) {
+          const progress = calculateProgress(processedCount, totalCount);
+          options.onProgress(progress);
+        }
+      });
+      bulkWriter.onWriteError((error) => {
+        failureCount++;
+        processedCount++;
+        const docId = error.documentRef?.id || "unknown";
+        failedDocIds.push(docId);
+        logCollector?.addEntry(docId, "failure", error.message);
+        if (options.onProgress) {
+          const progress = calculateProgress(processedCount, totalCount);
+          options.onProgress(progress);
+        }
+        return false;
+      });
+      for (const doc of snapshot.docs) {
+        bulkWriter.set(doc.ref, updateData, { merge: true });
+      }
+      await bulkWriter.close();
+    }
+    const result = {
+      successCount,
+      failureCount,
+      totalCount,
+      failedDocIds: failedDocIds.length > 0 ? failedDocIds : void 0
+    };
+    if (logCollector && options.log) {
+      result.logFilePath = logCollector.finalize(options.log);
+    }
+    return result;
+  }
+  /**
+   * Validate that collection is set
+   * @private
+   */
+  validateSetup() {
+    if (!this.collectionPath) {
+      throw new Error("Collection path is required. Call .collection() first.");
+    }
+  }
+  /**
+   * Build Firestore query with all conditions
+   * @private
+   */
+  buildQuery() {
+    let query = this.firestore.collection(
+      this.collectionPath
+    );
+    for (const condition of this.conditions) {
+      query = query.where(condition.field, condition.operator, condition.value);
+    }
+    return query;
+  }
+  /**
+   * Get nested value from object using dot notation
+   * @private
+   */
+  getNestedValue(obj, path2) {
+    const keys = path2.split(".");
+    let current = obj;
+    for (const key of keys) {
+      if (current === null || current === void 0) {
+        return void 0;
+      }
+      current = current[key];
+    }
+    return current;
+  }
+};
+export {
+  BatchUpdater,
+  calculateProgress,
+  createLogCollector,
+  formatError,
+  formatOperationLog,
+  getAffectedFields,
+  isValidUpdateData,
+  mergeUpdateData,
+  writeOperationLog
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "firestore-batch-updater",
+  "version": "1.0.0",
+  "description": "Batch update Firestore documents with query-based filtering and preview",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "firebase",
+    "firestore",
+    "batch",
+    "update",
+    "bulk",
+    "query"
+  ],
+  "author": "exiivy98",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "firebase-admin": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.50.1",
+    "@typescript-eslint/parser": "^8.50.1",
+    "eslint": "^9.39.2",
+    "firebase-admin": "^13.6.0",
+    "prettier": "^3.7.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/exiivy98/firestore-batch-updater.git"
+  }
+}