emberflow 1.5.0 → 2.0.0

package/README.md

@@ -9,6 +9,8 @@ Emberflow is a library for Firebase Functions that simplifies the process of set
 - **Business Logics**: Define complex business rules that are automatically triggered by Firestore changes.
 - **View Logics**: Easily create and maintain denormalized data (views) across your database.
 - **Patch Logics**: Handle versioning and data migrations seamlessly.
+- **Group Patch Engine**: Run one-time back-fills or bulk patch-logics runs over an entire collection, with progress tracking.
+- **Pluggable Cleanup**: Automatically purge stale documents on a schedule using declarative, config-driven cleanup rules.
 - **Billing Protection**: Built-in budget monitoring to prevent unexpected costs.
 
 ## Usage
@@ -36,19 +38,23 @@ import { securityConfigs } from "./security";
 import { validatorConfigs } from "./validators";
 import { logics } from "./business-logics";
 import { patchLogicConfigs } from "./patch-logics";
+import { cleanupConfigs } from "./cleanup-configs";
+import { backFillPatchConfigs } from "./one-time-patches";
 
 admin.initializeApp();
 
-const { functionsConfig } = initializeEmberFlow(
+const { functionsConfig } = initializeEmberFlow({
   projectConfig,
   admin,
   dbStructure,
   Entity,
   securityConfigs,
   validatorConfigs,
-  logics,
-  patchLogicConfigs
-);
+  logicConfigs: logics,
+  patchLogicConfigs,
+  cleanupConfigs, // optional, see "Collection Cleanup" below
+  backFillPatchConfigs, // optional, see "Group Patch Engine" below
+});
 
 // Export the generated functions
 Object.entries(functionsConfig).forEach(([key, value]) => {
@@ -56,6 +62,8 @@ Object.entries(functionsConfig).forEach(([key, value]) => {
 });
 ```
 
+`initializeEmberFlow` takes a single options object (`InitializeEmberFlowOptions`). `projectConfig`, `admin`, `dbStructure`, `Entity`, `securityConfigs`, `validatorConfigs`, `logicConfigs`, and `patchLogicConfigs` are required; `cleanupConfigs`, `backFillPatchConfigs`, and `userRegisterFn` are optional.
+
 ## Configuration
 
 Emberflow relies on several configuration objects to define how your project behaves.
@@ -139,6 +147,225 @@ export const logics: LogicConfig[] = [
 ];
 ```
 
+### Patch Logics (`patchLogicConfigs`)
+
+Patch logics handle data migrations and versioning. They are triggered when a document's `@dataVersion` is lower than the required version defined in the patch logic configurations.
+
+#### 1. Define the `PatchLogicFn`
+A patch logic function transforms existing document data to a new version.
+
+```typescript
+import { PatchLogicFn, LogicResult } from "emberflow/src/types";
+
+const updateUserData: PatchLogicFn = async (dstPath, data) => {
+  const { fullName } = data;
+  const [firstName, lastName] = fullName.split(" ");
+
+  return {
+    name: "updateUserData",
+    status: "finished",
+    documents: [
+      {
+        action: "merge",
+        dstPath: dstPath,
+        doc: { firstName, lastName },
+        instructions: { fullName: "del" },
+      },
+    ],
+  };
+};
+```
+
+#### 2. Configure the `PatchLogicConfig`
+Register the patch logic for a specific entity and version.
+
+```typescript
+import { PatchLogicConfig } from "emberflow/src/types";
+
+export const patchLogicConfigs: PatchLogicConfig[] = [
+  {
+    name: "updateUserData",
+    entity: "User",
+    patchLogicFn: updateUserData,
+    version: "1.1.0", // The version this patch achieves
+  },
+];
+```
+
+#### 3. How it Works
+- **Triggering**: There are two ways patch logics run:
+    - **Automatic, per-document (default)**: You only register `patchLogicConfigs`. Emberflow
+      automatically queues and runs them for a single document during form submissions or
+      document distribution whenever a version mismatch is detected — projects don't call
+      anything directly here.
+    - **On-demand, collection-wide (bulk migration)**: To re-run patch logics across every
+      existing document in a collection, call the public `queueGroupPatch({ path, patchType:
+      "patch-logics", appVersion })` (see the [Group Patch Engine](#group-patch-engine-queuegrouppatch-getgrouppatchprogress-backfillpatchconfig)
+      below). Progress can be polled with `getGroupPatchProgress`.
+- **Asynchronous Execution**: They run asynchronously via Pub/Sub to ensure high performance.
+- **Version-gating**: In both cases a `PatchLogicConfig` only fires when `config.version <=`
+  the current `appVersion` **and** the document's `@dataVersion` is older than `config.version`.
+  After a successful patch, the document's `@dataVersion` is bumped so it won't run again.
+- **Versioning**:
+    - **`@dataVersion`**: Incremented automatically after a patch is successfully applied.
+    - **`minDataVersion`**: In `LogicConfig`, use this to ensure business logic only runs on compatible data.
+    - **`obsoleteStartingFromVersion`**: In `LogicConfig`, use this to retire old logic based on the `appVersion`.
+- **Transactions**: Executed within Firestore transactions to ensure data integrity.
+
+### Group Patch Engine (`queueGroupPatch`, `getGroupPatchProgress`, `BackFillPatchConfig`)
+
+Emberflow ships with a generic, collection-wide batch engine for running a patch over every
+document in a collection (paging 500 docs at a time, tracking progress, and self-rescheduling
+over Pub/Sub until done). Each run is identified by a `patchType`:
+
+- **`"back-fill"`**: a version-free, one-time bulk back-fill. The actual work is delegated to a
+  `BackFillPatchConfig` resolved by `backFillPatchName`. Emberflow ships with a built-in
+  `ancestorIdsPatchConfig` (named `"ancestor-ids"`) that populates the `@entity`/ancestor id
+  fields used internally — it is **always registered automatically**, so you can trigger it with
+  `queueGroupPatch` at any time without registering it yourself. `appVersion` is **not** used for
+  `back-fill` runs (it's only required for `"patch-logics"`).
+- **`"patch-logics"`**: runs `runPatchLogics(appVersion, path)` for every document in the
+  collection, useful for bulk-applying `patchLogicConfigs` migrations.
+
+#### 1. Register a custom `BackFillPatchConfig`
+
+```typescript
+import { BackFillPatchConfig } from "emberflow/src/types";
+
+const myBackFill: BackFillPatchConfig = {
+  name: "my-back-fill", // used as backFillPatchName; must be unique
+  patchFn: async (collectionPath, docs) => {
+    // Bulk-update `docs` here, e.g. via a single db.batch() commit.
+  },
+};
+
+export const backFillPatchConfigs: BackFillPatchConfig[] = [myBackFill];
+```
+
+Pass `backFillPatchConfigs` to `initializeEmberFlow` (see step 2 above). The built-in
+`"ancestor-ids"` config is always registered automatically; registering a config with a
+duplicate name, or the reserved name `"ancestor-ids"`, throws during initialization.
+
+#### 2. Trigger a group patch
+
+```typescript
+import { queueGroupPatch } from "emberflow";
+
+// Kick off the built-in ancestor-ids back-fill for a collection
+await queueGroupPatch({
+  path: "/users/user123/feeds",
+  patchType: "back-fill",
+  backFillPatchName: "ancestor-ids",
+});
+
+// Kick off your own back-fill
+await queueGroupPatch({
+  path: "/users/user123/feeds",
+  patchType: "back-fill",
+  backFillPatchName: "my-back-fill",
+});
+
+// Bulk-apply patch logics for a target appVersion
+await queueGroupPatch({
+  path: "/users/user123/feeds",
+  patchType: "patch-logics",
+  appVersion: "1.2.0",
+});
+```
+
+`queueGroupPatch` accepts either a collection path or a document path (in which case the parent
+collection is derived). There is no guard/auth on it — it's meant to be called from your own
+trusted code (e.g. an admin-only Cloud Function or script). Placeholder paths (e.g.
+`/users/{userId}/feeds`) are automatically hydrated into concrete collection paths before patching.
+
+> If `backFillPatchName` doesn't resolve to a registered `BackFillPatchConfig` (or a
+> `"patch-logics"` run is missing its `appVersion`), the run is set to status `"error"` — there is
+> no silent default.
+
+#### 3. Track progress
+
+```typescript
+import { getGroupPatchProgress } from "emberflow";
+
+const progress = await getGroupPatchProgress({
+  collectionPath: "/users/user123/feeds",
+  patchType: "back-fill",
+  backFillPatchName: "ancestor-ids",
+});
+// progress?.status -> "running" | "completed" | "error" | "reset"
+```
+
+Progress is tracked independently per `patchType`/`backFillPatchName`, so different patches
+running against the same collection never clobber each other's status. The status doc lives at
+`@emberflow/internal/group-patches/<collection>_back-fill_<backFillPatchName>` (or
+`..._patch-logics` for `"patch-logics"` runs).
+
+### Collection Cleanup (`cleanupConfigs`, `CleanupConfig`)
+
+Emberflow ships with a single, scheduled `cleanupCollections` Cloud Function that runs **every
+hour** and purges stale documents based on declarative rules. Instead of writing a bespoke
+scheduled function for each collection you want to prune, you describe *what* to delete with a
+`CleanupConfig` and Emberflow handles the *how* (querying, batching, recursive subtree deletion,
+and self-paced iteration).
+
+Two layers of rules are merged and executed by the same runner:
+
+1. **Built-in (framework) rules** — always active. They keep Emberflow's own internal
+   bookkeeping collections tidy (Pub/Sub `processedIds`, metric `executions`/`computations`,
+   view-logic executions, and `@actions` — the latter also nulls out the corresponding
+   `forms/{uid}/{formId}` entries in the Realtime Database).
+2. **Project-supplied rules** — whatever you pass via the optional `cleanupConfigs` init option.
+   These are appended to the built-in rules, so your rules run alongside them.
+
+#### 1. Define a `CleanupConfig`
+
+```typescript
+import { CleanupConfig } from "emberflow/src/types";
+
+export const cleanupConfigs: CleanupConfig[] = [
+  {
+    // Exact collection path, or a collection-group name when isCollectionGroup=true.
+    collectionPath: "askJaris",
+    // Match this subcollection name anywhere in Firestore (collection-group query).
+    isCollectionGroup: true,
+    // Timestamp/Date field compared against the computed cutoff.
+    timestampField: "createdAt",
+    // Delete docs whose timestampField is older than (value · unit).
+    // unit is one of "hours" | "days" | "months".
+    olderThan: { value: 1, unit: "months" },
+    // Optional extra server-side filters, ANDed with the age threshold.
+    conditions: [
+      { fieldName: "hasTopic", operator: "==", value: false },
+    ],
+    // recursive defaults to true: each matched doc is deleted with its whole
+    // subtree. Set to false to delete only the matched documents.
+    recursive: true,
+  },
+];
+```
+
+Then pass `cleanupConfigs` to `initializeEmberFlow` (see step 2 in **Usage** above).
+
+#### 2. How it Works
+
+- **Scheduling**: A single `cleanupCollections` scheduled function runs `every 1 hours`. You can
+  override its schedule/region/memory/timeout via `projectConfig.functionsConfig.cleanupCollections`.
+- **Cutoff computation**: `olderThan` is converted to a cutoff `Date`; documents whose
+  `timestampField` is `< cutoff` are selected. `"months"` is calendar-aware (it subtracts
+  calendar months rather than a fixed number of days).
+- **Extra filters (`conditions`)**: Optional `QueryCondition` entries (`{ fieldName, operator,
+  value }`) are ANDed with the age threshold as additional server-side `where` clauses.
+- **Deletion mode (`recursive`)**: Defaults to `true`, deleting each matched document together
+  with its entire subtree. Set `recursive: false` to delete only the matched documents (leaving
+  any subcollections untouched).
+- **Isolation**: Each config is executed independently inside its own `try/catch`, so a failure
+  in one rule (e.g. a missing index) won't stop the others; failures are logged and the number of
+  deleted documents per collection is reported to the logs.
+
+> **Composite indexes**: Collection-group queries and any `conditions` combined with the
+> timestamp filter may require composite Firestore indexes in your project. If a rule fails,
+> check the function logs for an index-creation link.
+
 ## Reference
 
 For more detailed examples on how to set up these configuration files, you can check the `src/sample-custom` folder in the Emberflow repository.

package/lib/index-utils.d.ts

@@ -1,4 +1,4 @@
-import { Action, LogicResult, LogicResultDoc, MetricExecution, RunBusinessLogicStatus, SecurityFn, TxnGet, ValidateFormResult } from "./types";
+import { Action, GroupPatchType, LogicResult, LogicResultDoc, MetricExecution, BackFillPatchConfig, RunBusinessLogicStatus, SecurityFn, TxnGet, ValidateFormResult } from "./types";
 import { database, firestore } from "firebase-admin";
 import { BatchUtil } from "./utils/batch";
 import type { FirestoreEvent } from "firebase-functions/v2/firestore";
@@ -10,6 +10,7 @@ import Transaction = firestore.Transaction;
 export declare const _mockable: {
     getViewLogicConfigs: () => import("./types").ViewLogicConfig[];
     getPatchLogicConfigs: () => import("./types").PatchLogicConfig[];
+    getOneTimePatchConfigs: () => BackFillPatchConfig[];
     createNowTimestamp: () => firestore.Timestamp;
     saveMetricExecution: typeof saveMetricExecution;
     getBatchUtil: () => BatchUtil;
@@ -33,14 +34,24 @@ export declare function onDeleteFunction(event: FirestoreEvent<QueryDocumentSnap
 export declare function createMetricLogicDoc(logicName: string): Promise<void>;
 export declare function convertLogicResultsToMetricExecutions(logicResults: LogicResult[]): MetricExecution[];
 declare function saveMetricExecution(metricExecutions: MetricExecution[]): Promise<void>;
-export declare function cleanMetricExecutions(_event: ScheduledEvent): Promise<void>;
 export declare function createMetricComputation(_event: ScheduledEvent): Promise<void>;
-export declare function cleanMetricComputations(_event: ScheduledEvent): Promise<void>;
 export declare function distributeFnTransactional(txn: Transaction, logicResults: LogicResult[], appVersion: string): Promise<LogicResultDoc[]>;
 /**
- * Internal logic for patching siblings. Exported for background worker.
- * @param {string} collectionPath The path to the collection to patch.
- * @param {string} lastPatchedId The ID of the last document patched in the previous batch.
+ * Built-in, version-free bulk back-fill that restores the original ancestor-ids
+ * patching behavior. Runs `addAncestorIds` per doc and commits all updates in a
+ * single `db.batch()`, only updating keys that are currently undefined.
  */
-export declare function patchSiblingsWithAncestorIds(collectionPath: string, lastPatchedId?: string): Promise<void>;
+export declare const ancestorIdsPatchConfig: BackFillPatchConfig;
+export interface PatchGroupDocsParams {
+    collectionPath: string;
+    patchType: GroupPatchType;
+    backFillPatchName?: string;
+    appVersion?: string;
+    lastPatchedId?: string;
+}
+/**
+ * Internal engine logic for patching a collection page-by-page. Exported for background worker.
+ * @param {PatchGroupDocsParams} params The collection path, patch type, and cursor.
+ */
+export declare function patchGroupDocs(params: PatchGroupDocsParams): Promise<void>;
 export {};

package/lib/index-utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.patchSiblingsWithAncestorIds = exports.distributeFnTransactional = exports.cleanMetricComputations = exports.createMetricComputation = exports.cleanMetricExecutions = exports.convertLogicResultsToMetricExecutions = exports.createMetricLogicDoc = exports.onDeleteFunction = exports.expandConsolidateAndGroupByDstPath = exports.getSecurityFn = exports.groupDocsByTargetDocPath = exports.runBusinessLogics = exports.delayFormSubmissionAndCheckIfCancelled = exports.getFormModifiedFields = exports.validateForm = exports.distributeLater = exports.distributeFnNonTransactional = exports.distributeDoc = exports._mockable = void 0;
+exports.patchGroupDocs = exports.ancestorIdsPatchConfig = exports.distributeFnTransactional = exports.createMetricComputation = exports.convertLogicResultsToMetricExecutions = exports.createMetricLogicDoc = exports.onDeleteFunction = exports.expandConsolidateAndGroupByDstPath = exports.getSecurityFn = exports.groupDocsByTargetDocPath = exports.runBusinessLogics = exports.delayFormSubmissionAndCheckIfCancelled = exports.getFormModifiedFields = exports.validateForm = exports.distributeLater = exports.distributeFnNonTransactional = exports.distributeDoc = exports._mockable = void 0;
 const firebase_admin_1 = require("firebase-admin");
 const index_1 = require("./index");
 const paths_1 = require("./utils/paths");
@@ -15,6 +15,7 @@ var Timestamp = firebase_admin_1.firestore.Timestamp;
 exports._mockable = {
     getViewLogicConfigs: () => index_1.viewLogicConfigs,
     getPatchLogicConfigs: () => index_1.patchLogicConfigs,
+    getOneTimePatchConfigs: () => index_1.backFillPatchConfigs,
     createNowTimestamp: () => index_1.admin.firestore.Timestamp.now(),
     saveMetricExecution: saveMetricExecution,
     getBatchUtil: () => batch_1.BatchUtil.getInstance(),
@@ -91,18 +92,6 @@ async function distributeDoc(logicResultDoc, appVersion, batch, txn) {
         if (doc) {
             if (action === "create") {
                 (0, paths_1.addAncestorIds)(dstPath, doc);
-                // Only patch siblings in real environment, not during tests that expect a specific number of firestore calls
-                if (process.env.JEST_WORKER_ID === undefined) {
-                    const collectionPath = (0, paths_1.getParentPath)(dstPath);
-                    if (collectionPath && collectionPath.includes("/")) {
-                        const patchStatusPath = `@emberflow/internal/group-query-patches/${collectionPath.replace(/\//g, "_")}`;
-                        const patchStatusRef = index_1.db.doc(patchStatusPath);
-                        const patchStatusDoc = await patchStatusRef.get();
-                        if (!patchStatusDoc.exists) {
-                            await (0, distribution_1.queueAncestorIdsPatch)(dstPath);
-                        }
-                    }
-                }
             }
             let updateData = {};
             if (destProp) {
@@ -140,7 +129,7 @@ async function distributeDoc(logicResultDoc, appVersion, batch, txn) {
     }
     else if (action === "submit-form") {
         if (txn) {
-            console.error("Submit-form is not supported in transactional logic result");
+            console.debug("Submit-form in transactional logic result will be handled after transaction success");
         }
         else {
             console.debug("Queuing submit form...");
@@ -499,20 +488,6 @@ async function saveMetricExecution(metricExecutions) {
         });
     }
 }
-async function cleanMetricExecutions(_event) {
-    console.info("Running cleanMetricExecutions");
-    const metricsSnapshot = await index_1.db.collection("@metrics").get();
-    let i = 0;
-    for (const metricDoc of metricsSnapshot.docs) {
-        const query = metricDoc.ref.collection("executions")
-            .where("execDate", "<", new Date(Date.now() - 1000 * 60 * 60 * 24 * 7));
-        await (0, misc_1.deleteCollection)(query, (snapshot) => {
-            i += snapshot.size;
-        });
-    }
-    console.info(`Cleaned ${i} logic metric executions`);
-}
-exports.cleanMetricExecutions = cleanMetricExecutions;
 async function createMetricComputation(_event) {
     console.info("Creating metric computation");
     const metricsSnapshot = await index_1.db.collection("@metrics").get();
@@ -556,20 +531,6 @@ async function createMetricComputation(_event) {
     }
 }
 exports.createMetricComputation = createMetricComputation;
-async function cleanMetricComputations(_event) {
-    console.info("Running cleanMetricComputations");
-    const metricsSnapshot = await index_1.db.collection("@metrics").get();
-    let i = 0;
-    for (const metricDoc of metricsSnapshot.docs) {
-        const query = metricDoc.ref.collection("computations")
-            .where("createdAt", "<", new Date(Date.now() - 1000 * 60 * 60 * 24 * 30));
-        await (0, misc_1.deleteCollection)(query, (snapshot) => {
-            i += snapshot.size;
-        });
-    }
-    console.info(`Cleaned ${i} logic metric computations`);
-}
-exports.cleanMetricComputations = cleanMetricComputations;
 async function distributeFnTransactional(txn, logicResults, appVersion) {
     const distributedLogicResultDocs = [];
     const transactionalResults = logicResults.filter((result) => result.transactional);
@@ -590,12 +551,40 @@ async function distributeFnTransactional(txn, logicResults, appVersion) {
 }
 exports.distributeFnTransactional = distributeFnTransactional;
 /**
- * Internal logic for patching siblings. Exported for background worker.
- * @param {string} collectionPath The path to the collection to patch.
- * @param {string} lastPatchedId The ID of the last document patched in the previous batch.
+ * Built-in, version-free bulk back-fill that restores the original ancestor-ids
+ * patching behavior. Runs `addAncestorIds` per doc and commits all updates in a
+ * single `db.batch()`, only updating keys that are currently undefined.
  */
-async function patchSiblingsWithAncestorIds(collectionPath, lastPatchedId) {
-    const patchStatusPath = `@emberflow/internal/group-query-patches/${collectionPath.replace(/\//g, "_")}`;
+exports.ancestorIdsPatchConfig = {
+    name: "ancestor-ids",
+    patchFn: async (_collectionPath, docs) => {
+        const currentBatch = index_1.db.batch();
+        let count = 0;
+        for (const doc of docs) {
+            const data = doc.data();
+            const updatedData = {};
+            const fullPath = doc.ref.path.startsWith("/") ? doc.ref.path : `/${doc.ref.path}`;
+            (0, paths_1.addAncestorIds)(fullPath, updatedData);
+            const keysToUpdate = Object.keys(updatedData).filter((key) => data[key] === undefined);
+            if (keysToUpdate.length > 0) {
+                const patchData = {};
+                keysToUpdate.forEach((key) => patchData[key] = updatedData[key]);
+                currentBatch.update(doc.ref, patchData);
+                count++;
+            }
+        }
+        if (count > 0) {
+            await currentBatch.commit();
+        }
+    },
+};
+/**
+ * Internal engine logic for patching a collection page-by-page. Exported for background worker.
+ * @param {PatchGroupDocsParams} params The collection path, patch type, and cursor.
+ */
+async function patchGroupDocs(params) {
+    const { collectionPath, patchType, backFillPatchName, appVersion, lastPatchedId } = params;
+    const patchStatusPath = (0, distribution_1.getGroupPatchStatusPath)(collectionPath, patchType, backFillPatchName);
     const patchStatusRef = index_1.db.doc(patchStatusPath);
     const patchStatusDoc = await patchStatusRef.get();
     const patchStatusData = patchStatusDoc.data();
@@ -604,59 +593,65 @@ async function patchSiblingsWithAncestorIds(collectionPath, lastPatchedId) {
     }
     // Handle "reset" status by starting from scratch
     const effectiveLastId = (patchStatusData === null || patchStatusData === void 0 ? void 0 : patchStatusData.status) === "reset" ? undefined : lastPatchedId;
-    console.info(`[AncestorIdsPatch] Patching siblings for collection: ${collectionPath}${effectiveLastId ? ` starting from ${effectiveLastId}` : ""}`);
+    console.info(`[GroupPatch] Patching docs for collection: ${collectionPath}${effectiveLastId ? ` starting from ${effectiveLastId}` : ""}`);
     let query = index_1.db.collection(collectionPath).orderBy(index_1.admin.firestore.FieldPath.documentId());
     if (effectiveLastId) {
         query = query.startAfter(effectiveLastId);
     }
-    const siblingsSnapshot = await query.limit(500).get();
-    if (siblingsSnapshot.empty) {
+    const docsSnapshot = await query.limit(500).get();
+    if (docsSnapshot.empty) {
         await patchStatusRef.set({
             status: "completed",
+            patchType,
+            backFillPatchName: backFillPatchName !== null && backFillPatchName !== void 0 ? backFillPatchName : null,
             patchedAt: index_1.admin.firestore.Timestamp.now(),
             collectionPath,
         }, { merge: true });
-        console.info(`[AncestorIdsPatch] Completed patching for collection: ${collectionPath}`);
+        console.info(`[GroupPatch] Completed patching for collection: ${collectionPath}`);
         return;
     }
-    const currentBatch = index_1.db.batch();
-    let count = 0;
-    let lastId = lastPatchedId;
-    for (const siblingDoc of siblingsSnapshot.docs) {
-        const data = siblingDoc.data();
-        const updatedData = {};
-        const fullPath = siblingDoc.ref.path.startsWith("/") ? siblingDoc.ref.path : `/${siblingDoc.ref.path}`;
-        (0, paths_1.addAncestorIds)(fullPath, updatedData);
-        const keysToUpdate = Object.keys(updatedData).filter((key) => data[key] === undefined);
-        if (keysToUpdate.length > 0) {
-            const patchData = {};
-            keysToUpdate.forEach((key) => patchData[key] = updatedData[key]);
-            currentBatch.update(siblingDoc.ref, patchData);
-            count++;
-        }
-        lastId = siblingDoc.id;
-    }
+    const lastId = docsSnapshot.docs[docsSnapshot.docs.length - 1].id;
     try {
-        if (count > 0) {
-            await currentBatch.commit();
+        if (patchType === "patch-logics") {
+            if (!appVersion) {
+                throw new Error(`Missing appVersion for patch-logics on collection: ${collectionPath}`);
+            }
+            for (const doc of docsSnapshot.docs) {
+                const fullPath = doc.ref.path.startsWith("/") ? doc.ref.path : `/${doc.ref.path}`;
+                await (0, patch_logics_1.runPatchLogics)(appVersion, fullPath);
+            }
+        }
+        else if (patchType === "back-fill") {
+            const config = exports._mockable.getOneTimePatchConfigs().find((c) => c.name === backFillPatchName);
+            if (!config) {
+                throw new Error(`Unresolved back-fill patch "${backFillPatchName}" for collection: ${collectionPath}`);
+            }
+            await config.patchFn(collectionPath, docsSnapshot.docs);
+        }
+        else {
+            throw new Error(`Unknown patchType "${patchType}" for collection: ${collectionPath}`);
         }
-        const totalPatched = ((patchStatusData === null || patchStatusData === void 0 ? void 0 : patchStatusData.status) === "reset" ? 0 : ((patchStatusData === null || patchStatusData === void 0 ? void 0 : patchStatusData.count) || 0)) + count;
+        const totalPatched = ((patchStatusData === null || patchStatusData === void 0 ? void 0 : patchStatusData.status) === "reset" ? 0 : ((patchStatusData === null || patchStatusData === void 0 ? void 0 : patchStatusData.count) || 0)) + docsSnapshot.docs.length;
         await patchStatusRef.set({
-            status: "processing",
+            status: "running",
+            patchType,
+            backFillPatchName: backFillPatchName !== null && backFillPatchName !== void 0 ? backFillPatchName : null,
             lastPatchedId: lastId,
             collectionPath,
             count: totalPatched,
             updatedAt: index_1.admin.firestore.Timestamp.now(),
         }, { merge: true });
-        console.info(`[AncestorIdsPatch] Batch Complete: Patched ${count} siblings for collection: ${collectionPath}. Total patched so far: ${totalPatched}. Rescheduling next batch...`);
+        console.info(`[GroupPatch] Batch Complete: Patched ${docsSnapshot.docs.length} docs for collection: ${collectionPath}. Total patched so far: ${totalPatched}. Rescheduling next batch...`);
         // Reschedule for next batch
-        await (0, distribution_1.queueAncestorIdsPatch)(collectionPath, lastId);
+        await (0, distribution_1.queueGroupPatch)({ path: collectionPath, patchType, backFillPatchName, appVersion, lastPatchedId: lastId });
     }
     catch (error) {
-        console.error(`[AncestorIdsPatch] Error in patchSiblingsWithAncestorIds for ${collectionPath}:`, error);
+        console.error(`[GroupPatch] Error in patchGroupDocs for ${collectionPath}:`, error);
         // On error, we set status to error and store the error message
         await patchStatusRef.set({
             status: "error",
+            patchType,
+            backFillPatchName: backFillPatchName !== null && backFillPatchName !== void 0 ? backFillPatchName : null,
             error: error instanceof Error ? error.message : String(error),
             updatedAt: index_1.admin.firestore.Timestamp.now(),
         }, { merge: true });
@@ -666,5 +661,5 @@ async function patchSiblingsWithAncestorIds(collectionPath, lastPatchedId) {
         throw error;
     }
 }
-exports.patchSiblingsWithAncestorIds = patchSiblingsWithAncestorIds;
+exports.patchGroupDocs = patchGroupDocs;
 //# sourceMappingURL=index-utils.js.map