emberflow 1.5.1 → 2.0.1

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,334 @@ 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. Emberflow's own
+> collection-group cleanup fields are covered by the shipped `firestore.indexes.json` fragment
+> (see **Firestore Indexes** below); composite indexes for your **own** cleanup configs must be
+> declared in your project's `firestore.indexes.json` and deployed with
+> `firebase deploy --only firestore:indexes`. If a rule fails, check the function logs for an
+> index-creation link.
+
+### Firestore Indexes (`firestore.indexes.json`)
+
+Emberflow's internal collection-group cleanup queries
+(`computations`/`createdAt`, `executions`/`execDate`, `processedIds`/`timestamp`) require
+single-field indexes at `COLLECTION_GROUP` scope, which Firestore does **not** auto-create. To
+avoid manual `COLLECTION_GROUP_ASC` exemptions, Emberflow ships those index definitions as a static
+`firestore.indexes.json` fragment at the root of the package.
+
+Emberflow only declares the indexes **its own internal queries require**. It does **not** manage
+your application's indexes — you keep those in your own `firestore.indexes.json`. This gives a
+single, unambiguous owner for every index: Emberflow owns the framework indexes, your app owns the
+rest.
+
+The shipped fragment contains single-field `fieldOverrides` that enable Emberflow's internal
+collection-group queries while preserving the collection-scope single-field indexes other queries
+still rely on.
+
+#### Option A — Merge with the `emberflow-indexes` CLI (recommended)
+
+Emberflow ships an `emberflow-indexes` binary that merges the shipped fragment into your
+project's `firestore.indexes.json` for you, so you never have to hand-copy the overrides.
+Run it via `npx` from the directory that holds your `firestore.indexes.json`:
+
+```bash
+npx emberflow-indexes merge
+```
+
+By default it reads `firestore.indexes.json` in the current directory (creating it from an empty
+base if it doesn't exist), merges in Emberflow's required overrides, and writes the file back.
+Useful flags:
+
+- `-p, --path <file>` — path to your `firestore.indexes.json` (default: `firestore.indexes.json`).
+- `-o, --out <file>` — where to write the merged result (default: same as `--path`).
+- `-f, --fragment <file>` — path to Emberflow's fragment (default: the copy shipped in the package).
+- `--dry-run` — print the merged result to stdout without writing to disk.
+
+The merge is safe to run repeatedly: it is keyed by `(collectionGroup, fieldPath)`, so it never
+creates a second override for the same field. If your file already has an override for one of
+Emberflow's fields, the CLI **unions the scope/order rows** into your existing entry (rather than
+clobbering it), and it leaves all of your own indexes untouched.
+
+Wire it into a Firebase **`predeploy`** hook so your indexes are always up to date before every
+deploy:
+
+```json
+// firebase.json
+{
+  "firestore": {
+    "indexes": "firestore.indexes.json",
+    "predeploy": [
+      "npx emberflow-indexes merge"
+    ]
+  }
+}
+```
+
+Then deploy as usual:
+
+```bash
+firebase deploy --only firestore:indexes
+```
+
+#### Option B — Merge manually
+
+If you'd rather not run the CLI, merge Emberflow's fragment into your project's
+`firestore.indexes.json` by hand. The fragment lives at
+`node_modules/emberflow/firestore.indexes.json` and looks like:
+
+```json
+{
+  "indexes": [],
+  "fieldOverrides": [
+    {
+      "collectionGroup": "computations",
+      "fieldPath": "createdAt",
+      "indexes": [
+        { "queryScope": "COLLECTION", "order": "ASCENDING" },
+        { "queryScope": "COLLECTION", "order": "DESCENDING" },
+        { "queryScope": "COLLECTION_GROUP", "order": "ASCENDING" },
+        { "queryScope": "COLLECTION_GROUP", "order": "DESCENDING" }
+      ]
+    }
+    // ...executions/execDate and processedIds/timestamp
+  ]
+}
+```
+
+Add its `indexes` and `fieldOverrides` entries alongside your own, then deploy:
+
+```bash
+firebase deploy --only firestore:indexes
+```
+
+#### Notes
+
+- **Field overrides**: When you add one of Emberflow's `fieldOverrides` for a field, it **replaces**
+  the field's automatic single-field index config — that's why each override keeps the `COLLECTION`
+  scope rows in addition to `COLLECTION_GROUP`, so collection-scope queries keep working. When
+  merging manually, never create two overrides for the same `(collectionGroup, fieldPath)`; union
+  the scope rows into a single entry (the CLI does this for you).
+- **Idempotent**: both the CLI merge and `firebase deploy --only firestore:indexes` are declarative
+  — unchanged entries are left as-is, so re-running/re-deploying is safe.
+- **Async builds**: A deploy only *requests* an index; it then sits in **Building** in the Firestore
+  console until Firestore finishes, so it may not be usable immediately after the deploy.
+
 ## 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/firestore.indexes.json

@@ -0,0 +1,35 @@
+{
+  "indexes": [],
+  "fieldOverrides": [
+    {
+      "collectionGroup": "computations",
+      "fieldPath": "createdAt",
+      "indexes": [
+        { "queryScope": "COLLECTION", "order": "ASCENDING" },
+        { "queryScope": "COLLECTION", "order": "DESCENDING" },
+        { "queryScope": "COLLECTION_GROUP", "order": "ASCENDING" },
+        { "queryScope": "COLLECTION_GROUP", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "executions",
+      "fieldPath": "execDate",
+      "indexes": [
+        { "queryScope": "COLLECTION", "order": "ASCENDING" },
+        { "queryScope": "COLLECTION", "order": "DESCENDING" },
+        { "queryScope": "COLLECTION_GROUP", "order": "ASCENDING" },
+        { "queryScope": "COLLECTION_GROUP", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "processedIds",
+      "fieldPath": "timestamp",
+      "indexes": [
+        { "queryScope": "COLLECTION", "order": "ASCENDING" },
+        { "queryScope": "COLLECTION", "order": "DESCENDING" },
+        { "queryScope": "COLLECTION_GROUP", "order": "ASCENDING" },
+        { "queryScope": "COLLECTION_GROUP", "order": "DESCENDING" }
+      ]
+    }
+  ]
+}

package/lib/bin/merge-indexes.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+export interface MergeCliOptions {
+    command: string;
+    targetPath: string;
+    outPath: string;
+    fragmentPath: string;
+    dryRun: boolean;
+}
+export declare function defaultFragmentPath(): string;
+export declare function parseArgs(argv: string[]): MergeCliOptions;
+export declare function runMerge(options: MergeCliOptions): string;
+export declare function printUsage(): void;
+export declare function main(argv: string[]): void;

package/lib/bin/merge-indexes.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+"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 (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = exports.printUsage = exports.runMerge = exports.parseArgs = exports.defaultFragmentPath = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const firestore_indexes_1 = require("../utils/firestore-indexes");
+const DEFAULT_TARGET = "firestore.indexes.json";
+const EMPTY_INDEXES = { indexes: [], fieldOverrides: [] };
+// Path to Emberflow's shipped firestore.indexes.json fragment. When the compiled
+// CLI runs from lib/bin/merge-indexes.js, the fragment sits at the package root,
+// two directories up.
+function defaultFragmentPath() {
+    return path.resolve(__dirname, "..", "..", "firestore.indexes.json");
+}
+exports.defaultFragmentPath = defaultFragmentPath;
+function parseArgs(argv) {
+    var _a, _b, _c, _d;
+    const args = [...argv];
+    const command = (_a = args.shift()) !== null && _a !== void 0 ? _a : "";
+    let targetPath = DEFAULT_TARGET;
+    let outPath = "";
+    let fragmentPath = "";
+    let dryRun = false;
+    while (args.length > 0) {
+        const arg = args.shift();
+        switch (arg) {
+            case "--path":
+            case "-p":
+                targetPath = (_b = args.shift()) !== null && _b !== void 0 ? _b : targetPath;
+                break;
+            case "--out":
+            case "-o":
+                outPath = (_c = args.shift()) !== null && _c !== void 0 ? _c : outPath;
+                break;
+            case "--fragment":
+            case "-f":
+                fragmentPath = (_d = args.shift()) !== null && _d !== void 0 ? _d : fragmentPath;
+                break;
+            case "--dry-run":
+                dryRun = true;
+                break;
+            default:
+                throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    return {
+        command,
+        targetPath,
+        outPath: outPath || targetPath,
+        fragmentPath: fragmentPath || defaultFragmentPath(),
+        dryRun,
+    };
+}
+exports.parseArgs = parseArgs;
+function readIndexesFile(filePath, fallback) {
+    if (!fs.existsSync(filePath)) {
+        if (fallback) {
+            return fallback;
+        }
+        throw new Error(`File not found: ${filePath}`);
+    }
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+// Read the target and fragment files, merge them and (unless dryRun) write the
+// result back. Returns the serialized merged content.
+function runMerge(options) {
+    const fragment = readIndexesFile(options.fragmentPath);
+    const target = readIndexesFile(options.targetPath, EMPTY_INDEXES);
+    const merged = (0, firestore_indexes_1.mergeFirestoreIndexes)(target, fragment);
+    const output = `${JSON.stringify(merged, null, 2)}\n`;
+    if (options.dryRun) {
+        console.log(output);
+        return output;
+    }
+    fs.writeFileSync(options.outPath, output, "utf8");
+    console.log(`Merged Emberflow indexes from ${options.fragmentPath} into ${options.outPath}.`);
+    return output;
+}
+exports.runMerge = runMerge;
+function printUsage() {
+    console.log([
+        "Usage: emberflow-indexes merge [options]",
+        "",
+        "Merge Emberflow's required Firestore indexes into your firestore.indexes.json.",
+        "",
+        "Options:",
+        "  -p, --path <file>      Path to your firestore.indexes.json (default: firestore.indexes.json)",
+        "  -o, --out <file>       Where to write the merged result (default: same as --path)",
+        "  -f, --fragment <file>  Path to Emberflow's fragment (default: the shipped copy)",
+        "      --dry-run          Print the merged result without writing to disk",
+        "  -h, --help             Show this help",
+    ].join("\n"));
+}
+exports.printUsage = printUsage;
+function main(argv) {
+    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+        printUsage();
+        return;
+    }
+    const options = parseArgs(argv);
+    if (options.command !== "merge") {
+        printUsage();
+        throw new Error(`Unknown command: ${options.command || "(none)"}`);
+    }
+    runMerge(options);
+}
+exports.main = main;
+if (require.main === module) {
+    try {
+        main(process.argv.slice(2));
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=merge-indexes.js.map

package/lib/bin/merge-indexes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-indexes.js","sourceRoot":"","sources":["../../src/bin/merge-indexes.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,uCAAyB;AACzB,2CAA6B;AAC7B,kEAAmF;AAEnF,MAAM,cAAc,GAAG,wBAAwB,CAAC;AAChD,MAAM,aAAa,GAAqB,EAAC,OAAO,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAC,CAAC;AAU1E,iFAAiF;AACjF,iFAAiF;AACjF,sBAAsB;AACtB,SAAgB,mBAAmB;IACjC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,wBAAwB,CAAC,CAAC;AACvE,CAAC;AAFD,kDAEC;AAED,SAAgB,SAAS,CAAC,IAAc;;IACtC,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,MAAM,OAAO,GAAG,MAAA,IAAI,CAAC,KAAK,EAAE,mCAAI,EAAE,CAAC;IACnC,IAAI,UAAU,GAAG,cAAc,CAAC;IAChC,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,YAAY,GAAG,EAAE,CAAC;IACtB,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE;QACtB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,EAAY,CAAC;QACnC,QAAQ,GAAG,EAAE;YACb,KAAK,QAAQ,CAAC;YACd,KAAK,IAAI;gBACP,UAAU,GAAG,MAAA,IAAI,CAAC,KAAK,EAAE,mCAAI,UAAU,CAAC;gBACxC,MAAM;YACR,KAAK,OAAO,CAAC;YACb,KAAK,IAAI;gBACP,OAAO,GAAG,MAAA,IAAI,CAAC,KAAK,EAAE,mCAAI,OAAO,CAAC;gBAClC,MAAM;YACR,KAAK,YAAY,CAAC;YAClB,KAAK,IAAI;gBACP,YAAY,GAAG,MAAA,IAAI,CAAC,KAAK,EAAE,mCAAI,YAAY,CAAC;gBAC5C,MAAM;YACR,KAAK,WAAW;gBACd,MAAM,GAAG,IAAI,CAAC;gBACd,MAAM;YACR;gBACE,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC;SAC7C;KACF;IAED,OAAO;QACL,OAAO;QACP,UAAU;QACV,OAAO,EAAE,OAAO,IAAI,UAAU;QAC9B,YAAY,EAAE,YAAY,IAAI,mBAAmB,EAAE;QACnD,MAAM;KACP,CAAC;AACJ,CAAC;AAtCD,8BAsCC;AAED,SAAS,eAAe,CAAC,QAAgB,EAAE,QAA2B;IACpE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE;QAC5B,IAAI,QAAQ,EAAE;YACZ,OAAO,QAAQ,CAAC;SACjB;QACD,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC;KAChD;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAqB,CAAC;AAC3E,CAAC;AAED,+EAA+E;AAC/E,sDAAsD;AACtD,SAAgB,QAAQ,CAAC,OAAwB;IAC/C,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,IAAA,yCAAqB,EAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;IAEtD,IAAI,OAAO,CAAC,MAAM,EAAE;QAClB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpB,OAAO,MAAM,CAAC;KACf;IAED,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,OAAO,CAAC,GAAG,CAAC,iCAAiC,OAAO,CAAC,YAAY,SAAS,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC;IAC9F,OAAO,MAAM,CAAC;AAChB,CAAC;AAdD,4BAcC;AAED,SAAgB,UAAU;IACxB,OAAO,CAAC,GAAG,CAAC;QACV,0CAA0C;QAC1C,EAAE;QACF,gFAAgF;QAChF,EAAE;QACF,UAAU;QACV,gGAAgG;QAChG,qFAAqF;QACrF,mFAAmF;QACnF,0EAA0E;QAC1E,yCAAyC;KAC1C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAChB,CAAC;AAbD,gCAaC;AAED,SAAgB,IAAI,CAAC,IAAc;IACjC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;QACvE,UAAU,EAAE,CAAC;QACb,OAAO;KACR;IAED,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,OAAO,CAAC,OAAO,KAAK,OAAO,EAAE;QAC/B,UAAU,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,CAAC,OAAO,IAAI,QAAQ,EAAE,CAAC,CAAC;KACpE;IAED,QAAQ,CAAC,OAAO,CAAC,CAAC;AACpB,CAAC;AAbD,oBAaC;AAED,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE;IAC3B,IAAI;QACF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;KAC7B;IAAC,OAAO,GAAG,EAAE;QACZ,OAAO,CAAC,KAAK,CAAE,GAAa,CAAC,OAAO,CAAC,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;KACjB;CACF"}

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 {};