mongodash 2.6.0 → 2.8.0

package/dist/lib/testing/assertNoReactiveTaskErrors.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertNoReactiveTaskErrors = assertNoReactiveTaskErrors;
 const reactiveTasks_1 = require("../reactiveTasks");
+const resolveWhitelistFilter_1 = require("./resolveWhitelistFilter");
 /**
  * Asserts that no reactive tasks have failed during the test run.
  * Checks the 'executionHistory' and 'lastError' of tasks in all registered collections.
@@ -13,20 +14,23 @@ async function assertNoReactiveTaskErrors(options) {
     registry = schedulerToUse.getRegistry();
     const entries = registry.getAllEntries();
     const errorsFound = [];
+    const hasWhitelist = options.whitelist && options.whitelist.length > 0;
     for (const entry of entries) {
+        // If whitelist is active, check if this collection is relevant
+        let whitelistFilter = null;
+        if (hasWhitelist) {
+            const resolution = await (0, resolveWhitelistFilter_1.resolveWhitelistFilter)(options.whitelist, entry.sourceCollection);
+            if (resolution === 'skip')
+                continue;
+            if (resolution !== 'matchAll') {
+                whitelistFilter = resolution;
+            }
+        }
         // Build independent query for each collection
-        const query = {
-            // Optimization: Filter at database level for faster lookup
-            $or: [
-                { 'executionHistory.status': 'failed', 'executionHistory.at': { $gte: options.since } },
-                // Also check lastError if it happened recently (though executionHistory covers history)
-                // We rely on executionHistory for the time-based check.
-            ],
+        const baseQuery = {
+            $or: [{ 'executionHistory.status': 'failed', 'executionHistory.at': { $gte: options.since } }],
         };
-        if (options.sourceDocIds && options.sourceDocIds.length > 0) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            query.sourceDocId = { $in: options.sourceDocIds };
-        }
+        const query = whitelistFilter ? { $and: [baseQuery, whitelistFilter] } : baseQuery;
         const tasksWithHistory = await entry.tasksCollection.find(query).toArray();
         for (const taskRecord of tasksWithHistory) {
             if (!taskRecord.executionHistory)
@@ -39,7 +43,7 @@ async function assertNoReactiveTaskErrors(options) {
                 if (item.status !== 'failed')
                     continue;
                 const errorMessage = item.error || 'Unknown error';
-                // 3. Check Whitelist
+                // 3. Check Whitelist (excludeErrors)
                 let isExcluded = false;
                 if (options.excludeErrors) {
                     for (const pattern of options.excludeErrors) {

package/dist/lib/testing/assertNoReactiveTaskErrors.js.map

@@ -1 +1 @@
-{"version":3,"file":"assertNoReactiveTaskErrors.js","sourceRoot":"","sources":["../../../src/testing/assertNoReactiveTaskErrors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"assertNoReactiveTaskErrors.js","sourceRoot":"","sources":["../../../src/testing/assertNoReactiveTaskErrors.ts"],"names":[],"mappings":"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"}

package/dist/lib/testing/index.js

@@ -16,5 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./assertNoReactiveTaskErrors"), exports);
 __exportStar(require("./configureForTesting"), exports);
+__exportStar(require("./resolveWhitelistFilter"), exports);
+__exportStar(require("./waitUntil"), exports);
 __exportStar(require("./waitUntilReactiveTasksIdle"), exports);
 //# sourceMappingURL=index.js.map

package/dist/lib/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+DAA6C;AAC7C,wDAAsC;AACtC,+DAA6C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+DAA6C;AAC7C,wDAAsC;AACtC,2DAAyC;AACzC,8CAA4B;AAC5B,+DAA6C"}

package/dist/lib/testing/resolveWhitelistFilter.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWhitelistFilter = resolveWhitelistFilter;
+/**
+ * Build the `Filter<ReactiveTaskRecord>` for a single registry entry based on
+ * the provided whitelist rules. Extracted from `waitUntilReactiveTasksIdle` /
+ * `assertNoReactiveTaskErrors` so the two utilities cannot drift.
+ */
+async function resolveWhitelistFilter(whitelist, sourceCollection) {
+    const rules = whitelist.filter((rule) => rule.collection === sourceCollection.collectionName);
+    if (rules.length === 0) {
+        return 'skip';
+    }
+    const criteria = [];
+    for (const rule of rules) {
+        let ruleIds = null;
+        if (rule.filter) {
+            const matchingDocs = (await sourceCollection.find(rule.filter, { projection: { _id: 1 } }).toArray());
+            ruleIds = matchingDocs.map((d) => d._id);
+        }
+        if (ruleIds === null && !rule.task) {
+            // Rule covers every document in this collection and every task.
+            return 'matchAll';
+        }
+        // A filter-scoped rule that matched zero source documents can never
+        // contribute tasks of its own - drop it even when a task is also
+        // specified (the AND of "task=X" and "sourceDocId IN []" is still
+        // empty, so emitting that filter just produces useless `$in: []` queries).
+        if (ruleIds !== null && ruleIds.length === 0) {
+            continue;
+        }
+        const ruleCriteria = {};
+        if (rule.task) {
+            ruleCriteria.task = rule.task;
+        }
+        if (ruleIds !== null) {
+            ruleCriteria.sourceDocId = { $in: ruleIds };
+        }
+        criteria.push(ruleCriteria);
+    }
+    if (criteria.length === 0) {
+        // Rules matched this collection but every rule resolved to an empty
+        // document set - nothing to wait for / check.
+        return 'skip';
+    }
+    return { $or: criteria };
+}
+//# sourceMappingURL=resolveWhitelistFilter.js.map

package/dist/lib/testing/resolveWhitelistFilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveWhitelistFilter.js","sourceRoot":"","sources":["../../../src/testing/resolveWhitelistFilter.ts"],"names":[],"mappings":";;AAqCA,wDAiDC;AAtDD;;;;GAIG;AACI,KAAK,UAAU,sBAAsB,CACxC,SAA0B,EAC1B,gBAAuE;IAEvE,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,KAAK,gBAAgB,CAAC,cAAc,CAAC,CAAC;IAC9F,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,MAAM,CAAC;IAClB,CAAC;IAED,MAAM,QAAQ,GAAsC,EAAE,CAAC;IAEvD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,OAAO,GAAqB,IAAI,CAAC;QAErC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,MAAM,YAAY,GAAG,CAAC,MAAM,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAe,CAAC;YACpH,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC7C,CAAC;QAED,IAAI,OAAO,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACjC,gEAAgE;YAChE,OAAO,UAAU,CAAC;QACtB,CAAC;QAED,oEAAoE;QACpE,iEAAiE;QACjE,kEAAkE;QAClE,2EAA2E;QAC3E,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3C,SAAS;QACb,CAAC;QAED,MAAM,YAAY,GAA+B,EAAE,CAAC;QACpD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACZ,YAAY,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAClC,CAAC;QACD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACnB,YAAY,CAAC,WAAW,GAAG,EAAE,GAAG,EAAE,OAA8C,EAAE,CAAC;QACvF,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAChC,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,oEAAoE;QACpE,8CAA8C;QAC9C,OAAO,MAAM,CAAC;IAClB,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;AAC7B,CAAC"}

package/dist/lib/testing/waitUntilReactiveTasksIdle.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.waitUntilReactiveTasksIdle = waitUntilReactiveTasksIdle;
 const _debug = require("debug");
 const reactiveTasks_1 = require("../reactiveTasks");
+const resolveWhitelistFilter_1 = require("./resolveWhitelistFilter");
 const waitUntil_1 = require("./waitUntil");
 const debug = _debug('mongodash:testing');
 async function waitUntilReactiveTasksIdle(customOptions = {}) {
@@ -13,16 +14,22 @@ async function waitUntilReactiveTasksIdle(customOptions = {}) {
         const planner = reactiveTasks_1._scheduler.taskPlannerInstance;
         const runner = reactiveTasks_1._scheduler.concurrentRunnerInstance;
         const registry = reactiveTasks_1._scheduler.getRegistry();
-        // --- 1. Global Checks (Always run) ---
-        // 1. Check Internal Buffers (Planner)
+        // --- 1. Global Checks ---
+        // The planner buffer check is kept in whitelist mode too: change-stream
+        // events for *our* collections land there before task records exist,
+        // and skipping the check altogether would let us return idle before
+        // the events have been turned into rows the DB check below can see.
+        // The worker check is only applied globally - in whitelist mode
+        // other tests' workers must not block us.
         if (planner && !planner.isEmpty) {
             debug('Planner not empty');
             return false;
         }
-        // 2. Check Active Workers (Runner)
-        if (runner && runner.activeWorkers > 0) {
-            debug(`Active workers: ${runner.activeWorkers}`);
-            return false;
+        if (!hasWhitelist) {
+            if (runner && runner.activeWorkers > 0) {
+                debug(`Active workers: ${runner.activeWorkers}`);
+                return false;
+            }
         }
         // --- 2. Check Database ---
         const entries = registry.getAllEntries();
@@ -31,47 +38,11 @@ async function waitUntilReactiveTasksIdle(customOptions = {}) {
             // If whitelisting is active, we only check tasks that match the whitelist
             let whitelistFilter = null;
             if (hasWhitelist) {
-                const rules = customOptions.whitelist.filter((rule) => rule.collection === entry.sourceCollection.collectionName);
-                if (rules.length === 0) {
+                const resolution = await (0, resolveWhitelistFilter_1.resolveWhitelistFilter)(customOptions.whitelist, entry.sourceCollection);
+                if (resolution === 'skip')
                     continue;
-                }
-                const criteria = [];
-                let matchAll = false;
-                for (const rule of rules) {
-                    let ruleIds = null;
-                    if (rule.filter) {
-                        // If we have a filter, we need to find which docs match it.
-                        // We can't filter tasks directly by source properties efficiently without joining,
-                        // so we find the matching source docs first.
-                        const matchingDocs = (await entry.sourceCollection.find(rule.filter, { projection: { _id: 1 } }).toArray());
-                        ruleIds = matchingDocs.map((d) => d._id);
-                    }
-                    if (ruleIds === null && !rule.task) {
-                        // One rule validates 'all', so we wait for everything in this collection
-                        matchAll = true;
-                        break;
-                    }
-                    if (rule.task) {
-                        criteria.push({ task: rule.task });
-                    }
-                    if (ruleIds !== null) {
-                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                        criteria.push({ sourceDocId: { $in: ruleIds } });
-                    }
-                }
-                if (!matchAll) {
-                    if (criteria.length > 0) {
-                        whitelistFilter = { $or: criteria };
-                    }
-                    else {
-                        // Whitelist is active, but we have rules that result in effectively "nothing"
-                        // (e.g. filter returned no docs).
-                        // If we have NO criteria and NO matchAll, it implies we wait for nothing on this collection?
-                        // Or should we treat it as blocking?
-                        // If filter didn't match any doc, then we effectively wait for nothing for that rule.
-                        // If ALL rules resulted in nothing, we continue to next entry.
-                        continue;
-                    }
+                if (resolution !== 'matchAll') {
+                    whitelistFilter = resolution;
                 }
             }
             const stableThresholdMs = (options.timeoutMs || 0) + (options.stabilityDurationMs || 0) + 100;

package/dist/lib/testing/waitUntilReactiveTasksIdle.js.map

@@ -1 +1 @@
-{"version":3,"file":"waitUntilReactiveTasksIdle.js","sourceRoot":"","sources":["../../../src/testing/waitUntilReactiveTasksIdle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"waitUntilReactiveTasksIdle.js","sourceRoot":"","sources":["../../../src/testing/waitUntilReactiveTasksIdle.ts"],"names":[],"mappings":";;AA+BA,gEA0EC;AAzGD,gCAAgC;AAEhC,oDAAkE;AAClE,qEAAiF;AACjF,2CAA0D;AAE1D,MAAM,KAAK,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAyBnC,KAAK,UAAU,0BAA0B,CAAC,gBAAmD,EAAE;IAClG,MAAM,OAAO,mBACT,SAAS,EAAE,KAAK,EAChB,cAAc,EAAE,EAAE,EAClB,mBAAmB,EAAE,GAAG,IACrB,aAAa,CACnB,CAAC;IAEF,MAAM,YAAY,GAAG,aAAa,CAAC,SAAS,IAAI,aAAa,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IAEnF,MAAM,IAAA,qBAAS,EAAC,KAAK,IAAI,EAAE;QACvB,6BAA6B;QAC7B,MAAM,OAAO,GAAG,0BAAU,CAAC,mBAAmB,CAAC;QAC/C,MAAM,MAAM,GAAG,0BAAU,CAAC,wBAAwB,CAAC;QACnD,MAAM,QAAQ,GAAG,0BAAU,CAAC,WAAW,EAAE,CAAC;QAE1C,2BAA2B;QAC3B,wEAAwE;QACxE,qEAAqE;QACrE,oEAAoE;QACpE,oEAAoE;QACpE,gEAAgE;QAChE,0CAA0C;QAC1C,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAC9B,KAAK,CAAC,mBAAmB,CAAC,CAAC;YAC3B,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,IAAI,CAAC,YAAY,EAAE,CAAC;YAChB,IAAI,MAAM,IAAI,MAAM,CAAC,aAAa,GAAG,CAAC,EAAE,CAAC;gBACrC,KAAK,CAAC,mBAAmB,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;gBACjD,OAAO,KAAK,CAAC;YACjB,CAAC;QACL,CAAC;QAED,4BAA4B;QAC5B,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,EAAE,CAAC;QAEzC,wEAAwE;QACxE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC1B,0EAA0E;YAC1E,IAAI,eAAe,GAAsC,IAAI,CAAC;YAE9D,IAAI,YAAY,EAAE,CAAC;gBACf,MAAM,UAAU,GAAG,MAAM,IAAA,+CAAsB,EAAC,aAAa,CAAC,SAAU,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;gBAClG,IAAI,UAAU,KAAK,MAAM;oBAAE,SAAS;gBACpC,IAAI,UAAU,KAAK,UAAU,EAAE,CAAC;oBAC5B,eAAe,GAAG,UAAU,CAAC;gBACjC,CAAC;YACL,CAAC;YAED,MAAM,iBAAiB,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,mBAAmB,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC;YAE9F,MAAM,SAAS,GAA+B;gBAC1C,GAAG,EAAE;oBACD,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,YAAY,EAAE,kBAAkB,CAAC,EAAE,EAAE;oBACvD;wBACI,MAAM,EAAE,SAAS;wBACjB,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,iBAAiB,CAAC,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;qBAChG;iBACJ;aACJ,CAAC;YAEF,MAAM,KAAK,GAA+B,eAAe,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,SAAS,EAAE,eAAe,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;YAE/G,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,eAAe,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YAEhE,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACZ,KAAK,CAAC,cAAc,KAAK,CAAC,eAAe,CAAC,cAAc,QAAQ,KAAK,eAAe,CAAC,CAAC;gBACtF,OAAO,KAAK,CAAC;YACjB,CAAC;QACL,CAAC;QAED,OAAO,IAAI,CAAC;IAChB,CAAC,EAAE,OAAO,CAAC,CAAC;AAChB,CAAC"}

package/dist/types/ConcurrentRunner.d.ts

@@ -23,6 +23,22 @@ export declare class ConcurrentRunner {
     start(tryRunATask: TryRunATaskCallback): void;
     stop(): Promise<void>;
     speedUp(sourceName: string): void;
+    /**
+     * Override the back-off schedule so the next poll for `sourceName`
+     * happens at approximately `runAt` (a millisecond epoch timestamp).
+     * Intended for callers that already know when their next unit of work
+     * is due - e.g. cron scheduling an hour out - to skip wasted polls.
+     *
+     * - `runAt` must be a finite number; non-finite values are ignored.
+     * - If `state.nextRunAt` is already at or before `now`, the write is
+     *   skipped: something more urgent (usually {@link speedUp}) has
+     *   already signalled an immediate poll and we must not push it
+     *   back out. The worker picks up the signal on its next iteration.
+     * - Otherwise `nextRunAt` is overwritten with `runAt` (even if `runAt`
+     *   is in the past - that behaves like {@link speedUp}).
+     * - Back-off is reset so a subsequent wake-up fires at `minPollMs`.
+     */
+    setNextRunAt(sourceName: string, runAt: number): void;
     updateAllSources(options: Partial<SourceOptions>): void;
     private runWorker;
     private prolongNextRun;

package/dist/types/createContinuousLock.d.ts

@@ -1,6 +1,22 @@
 import { Collection, ObjectId } from 'mongodb';
 type StopContinuousLock = () => Promise<void>;
+export interface CreateContinuousLockOptions {
+    /**
+     * Initial value of the lock property written by whoever acquired the lock.
+     * When provided, every renewal becomes a compare-and-swap: the update only
+     * succeeds if the lock still carries the previously-written value. If another
+     * actor has taken over the lock in the meantime, `onLockLost` is invoked and
+     * no further renewals are attempted. This prevents a slow renewal from
+     * accidentally extending a lock that has already been stolen.
+     */
+    expectedInitialValue?: unknown;
+    /**
+     * Invoked once when CAS detects we no longer own the lock. Only fires when
+     * `expectedInitialValue` is set. Renewals stop after this callback.
+     */
+    onLockLost?: () => void;
+}
 export declare function createContinuousLock<DocumentType extends {
     _id: string | ObjectId;
-}>(collection: Collection<DocumentType>, documentId: DocumentType['_id'], lockProperty: keyof DocumentType, lockTime: number): StopContinuousLock;
+}>(collection: Collection<DocumentType>, documentId: DocumentType['_id'], lockProperty: keyof DocumentType, lockTime: number, options?: CreateContinuousLockOptions): StopContinuousLock;
 export {};

package/dist/types/cronTasks.d.ts

@@ -1,6 +1,19 @@
 import { CronExpressionOptions } from 'cron-parser';
 export interface InitOptions {
     runCronTasks: boolean;
+    /**
+     * Maximum number of cron tasks this instance will execute in parallel.
+     *
+     * The default of `1` preserves the historical behaviour: one task is
+     * processed at a time per instance. Raise it when you have many
+     * independent cron tasks and want to avoid head-of-line blocking (a
+     * long-running task delaying unrelated ones).
+     *
+     * Tasks with the same id are always serialised via the per-task lock
+     * (`lockedTill`), so raising this does not cause a single task to run
+     * twice in parallel.
+     */
+    cronTaskConcurrency: number;
     cronExpressionParserOptions: CronExpressionOptions;
     cronTaskCaller: CronTaskCaller;
     cronTaskFilter: CronTaskFilter;
@@ -64,8 +77,10 @@ export declare function cronTask(taskId: TaskId, interval: Interval, task: TaskF
  */
 export declare function getCronTasksList(query?: CronTaskQuery): Promise<CronPagedResult<CronTaskRecord>>;
 /**
- * Triggers a cron task immediately.
- * Alias for scheduleCronTaskImmediately but returns the new state or confirmation.
+ * @deprecated Alias for {@link scheduleCronTaskImmediately}. Prefer that name for
+ * clarity - it describes exactly what happens (the task is scheduled to run on
+ * the next polling tick, not necessarily this very millisecond). This alias will
+ * be removed in a future major version.
  */
 export declare function triggerCronTask(taskId: TaskId): Promise<void>;
 /**

package/dist/types/index.d.ts

@@ -5,12 +5,12 @@ import { InitOptions as GetMongoClientInitOptions } from './getMongoClient';
 import { OnError } from './OnError';
 import { OnInfo } from './OnInfo';
 import { InitOptions as ReactiveTasksInitOptions } from './reactiveTasks';
-export { CODE_CRON_TASK_FAILED, CODE_CRON_TASK_FINISHED, CODE_CRON_TASK_SCHEDULED, CODE_CRON_TASK_STARTED, CronPagedResult, cronTask, CronTaskQuery, CronTaskRecord, CronTaskStatus, getCronTasksList, Interval, runCronTask, scheduleCronTaskImmediately, startCronTasks, stopCronTasks, TaskFunction, TaskId, triggerCronTask, } from './cronTasks';
+export { CODE_CRON_TASK_FAILED, CODE_CRON_TASK_FINISHED, CODE_CRON_TASK_SCHEDULED, CODE_CRON_TASK_STARTED, CronPagedResult, cronTask, CronTaskQuery, CronTaskRecord, CronTaskStatus, getCronTasksList, getRegisteredCronTaskIds, Interval, runCronTask, scheduleCronTaskImmediately, startCronTasks, stopCronTasks, TaskFunction, TaskId, triggerCronTask, } from './cronTasks';
 export { getCollection } from './getCollection';
 export { getMongoClient } from './getMongoClient';
 export { OnError } from './OnError';
 export { processInBatches, ProcessInBatchesOptions, ProcessInBatchesResult } from './processInBatches';
-export { CODE_REACTIVE_TASK_FAILED, CODE_REACTIVE_TASK_FINISHED, CODE_REACTIVE_TASK_LEADER_LOCK_LOST, CODE_REACTIVE_TASK_PLANNER_RECONCILIATION_FINISHED, CODE_REACTIVE_TASK_PLANNER_RECONCILIATION_STARTED, CODE_REACTIVE_TASK_PLANNER_STARTED, CODE_REACTIVE_TASK_PLANNER_STOPPED, CODE_REACTIVE_TASK_PLANNER_STREAM_ERROR, CODE_REACTIVE_TASK_STARTED, countReactiveTasks, getPrometheusMetrics, getReactiveTasks, reactiveTask, ReactiveTask, ReactiveTaskHandler, retryReactiveTasks, startReactiveTasks, stopReactiveTasks, TaskConditionFailedError, _scheduler, } from './reactiveTasks';
+export { CODE_REACTIVE_TASK_CLEANUP, CODE_REACTIVE_TASK_FAILED, CODE_REACTIVE_TASK_FINISHED, CODE_REACTIVE_TASK_INITIALIZED, CODE_REACTIVE_TASK_LEADER_LOCK_LOST, CODE_REACTIVE_TASK_LOCK_LOST, CODE_REACTIVE_TASK_PLANNER_RECONCILIATION_FINISHED, CODE_REACTIVE_TASK_PLANNER_RECONCILIATION_STARTED, CODE_REACTIVE_TASK_PLANNER_STARTED, CODE_REACTIVE_TASK_PLANNER_STOPPED, CODE_REACTIVE_TASK_PLANNER_STREAM_ERROR, CODE_REACTIVE_TASK_STARTED, countReactiveTasks, getPrometheusMetrics, getReactiveTasks, PagedResult, PaginationOptions, reactiveTask, ReactiveTask, ReactiveTaskHandler, ReactiveTaskQuery, ReactiveTaskRecord, ReactiveTaskStatus, retryReactiveTasks, startReactiveTasks, stopReactiveTasks, TaskConditionFailedError, _scheduler, } from './reactiveTasks';
 export { OperationalTaskController, serveDashboard } from './task-management';
 export * from './testing';
 export { isLockAlreadyAcquiredError, LockAlreadyAcquiredError, withLock, WithLockOptions } from './withLock';

package/dist/types/reactiveTasks/LeaderElector.d.ts

@@ -1,6 +1,6 @@
 import { GlobalsCollection } from '../globalsCollection';
-import { OnInfo } from '../OnInfo';
 import { OnError } from '../OnError';
+import { OnInfo } from '../OnInfo';
 export interface LeaderElectorCallbacks {
     onBecomeLeader: () => Promise<void>;
     onLoseLeader: () => Promise<void>;
@@ -35,6 +35,20 @@ export declare class LeaderElector {
     get isLeader(): boolean;
     start(): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * Give up leadership locally. The DB lock is NOT released - the next
+     * heartbeat will likely re-acquire it (unless another instance raced
+     * in). onLoseLeader is fired asynchronously so callers (e.g. the
+     * scheduler wiring this to a flush-failure path) get a clean
+     * planner.stop() before the next heartbeat restarts it, rather than
+     * starting a new planner on top of a live one.
+     *
+     * Note: the follow-up onBecomeLeader that fires after a forced loss
+     * looks identical to a real leader election and will increment
+     * reactive_tasks_leader_elections_total; see the event codes
+     * CODE_REACTIVE_TASK_PLANNER_STREAM_ERROR and the flush-failure
+     * counter to disambiguate "real" flapping from restart-driven ones.
+     */
     forceLoseLeader(): void;
     private runLeaderElectionLoop;
     private tryAcquireLock;

package/dist/types/reactiveTasks/MetricsCollector.d.ts

@@ -1,9 +1,7 @@
 import type { Registry } from 'prom-client';
 import { GlobalsCollection } from '../globalsCollection';
 import { OnError } from '../OnError';
-import { OnInfo } from '../OnInfo';
 import { LeaderElector } from './LeaderElector';
-import { ReactiveTaskPlanner } from './ReactiveTaskPlanner';
 import { ReactiveTaskRegistry } from './ReactiveTaskRegistry';
 import { ReactiveTaskSchedulerOptions } from './ReactiveTaskTypes';
 /**
@@ -15,7 +13,12 @@ import { ReactiveTaskSchedulerOptions } from './ReactiveTaskTypes';
  * - **local**: Returns metrics from THIS instance only.
  *   Use when Prometheus scrapes each pod individually (K8s Pod Monitors).
  *
- * Global stats (queue depth, lag) are computed on-the-fly by the **Leader only**.
+ * Global stats (queue depth, lag, change-stream lag, reconciliation timestamp)
+ * are computed by the Leader. In `cluster` mode the Leader also pushes these
+ * values into the registry document on each push interval so a scrape that
+ * lands on a Follower still returns a complete metrics view - bounded-stale
+ * at `GLOBAL_STATS_STALE_MULTIPLIER * pushIntervalMs` (2x by default,
+ * i.e. a single missed push is tolerated).
  */
 export declare class MetricsCollector {
     private enabled;
@@ -24,17 +27,19 @@ export declare class MetricsCollector {
     private readonly registry;
     private readonly globalsCollection;
     private readonly leaderElector;
-    private readonly onInfo;
     private readonly onError;
     private promClientModule;
     private localPromRegistry?;
     private globalStatsRegistry?;
     private metricDuration?;
     private metricRetries?;
+    private metricLeaderElections?;
+    private metricLockLost?;
+    private metricStreamErrors?;
+    private metricFlushFailures?;
     private pushInterval?;
     private queueMetricsPromise;
-    planner?: ReactiveTaskPlanner;
-    constructor(instanceId: string, registry: ReactiveTaskRegistry, globalsCollection: GlobalsCollection, leaderElector: LeaderElector, options: ReactiveTaskSchedulerOptions['monitoring'], onInfo?: OnInfo, onError?: OnError);
+    constructor(instanceId: string, registry: ReactiveTaskRegistry, globalsCollection: GlobalsCollection, leaderElector: LeaderElector, options: ReactiveTaskSchedulerOptions['monitoring'], onError?: OnError);
     private initPrometheus;
     private initLocalMetrics;
     private initGlobalStatsMetrics;
@@ -42,11 +47,17 @@ export declare class MetricsCollector {
     stop(): void;
     recordTaskExecution(task: string, status: 'success' | 'failed', durationMs: number): void;
     recordRetry(task: string): void;
+    recordLeaderElection(): void;
+    recordLockLost(task: string): void;
+    recordStreamError(): void;
+    recordFlushFailure(): void;
     getPrometheusMetrics(): Promise<Registry | null>;
     /**
      * Returns aggregated metrics from ALL instances.
      * Fetches other instances' metrics from DB and merges with fresh local metrics.
-     * Leader also includes global stats.
+     * Global stats: leader computes fresh; followers read the leader's last
+     * push from the registry doc (so a scrape that hits a follower still
+     * returns queue depth / lag / reconciliation / stream-lag gauges).
      */
     private getClusterMetrics;
     /**
@@ -54,7 +65,7 @@ export declare class MetricsCollector {
      * Leader also includes global stats.
      */
     private getLocalMetrics;
-    private fetchOtherInstancesMetrics;
+    private fetchClusterStateFromDb;
     private getLocalMetricsAsJson;
     private getGlobalStatsAsJson;
     private triggerGlobalStatsCollection;

package/dist/types/reactiveTasks/ReactiveTaskPlanner.d.ts

@@ -6,6 +6,15 @@ import { ReactiveTaskRegistry } from './ReactiveTaskRegistry';
 export interface PlannerCallbacks {
     onStreamError: () => void;
     onTaskPlanned: (tasksCollectionName: string, debounceMs: number) => void;
+    /** Fired when a batch flush fails. Records the metric and should trigger a planner restart. */
+    onFlushFailure?: () => void;
+    /**
+     * Fired when the planner needs to restart due to a flush failure (distinct from a
+     * real change-stream error). Callers should trigger a leader-election cycle here
+     * instead of reacting to `onStreamError`, so flush failures don't pollute the
+     * stream-error metric.
+     */
+    onRequestRestart?: () => void;
 }
 /**
  * Responsible for listening to MongoDB Change Stream events and planning tasks.
@@ -31,6 +40,7 @@ export declare class ReactiveTaskPlanner {
     private batchFlushTimer;
     private batchFirstEventTime;
     private isFlushing;
+    private lastFlushFailed;
     private metaDocId;
     private lastClusterTime;
     private ops;
@@ -59,6 +69,7 @@ export declare class ReactiveTaskPlanner {
     private groupEventsByCollection;
     private processDeletions;
     private executeUpsertOperations;
+    private throwOnAnyRejection;
     private handleStreamError;
     private checkEvolutionStrategies;
     private checkTriggerEvolution;

package/dist/types/reactiveTasks/ReactiveTaskRepository.d.ts

@@ -24,11 +24,20 @@ export declare class ReactiveTaskRepository<T extends Document> {
     findAndLockNextTask(taskDefs: ReactiveTaskInternal<T>[], options: {
         visibilityTimeoutMs: number;
     }): Promise<ReactiveTaskRecord<T> | null>;
+    /**
+     * Finalize a task record (success or failure). Returns `true` when the
+     * update matched the record, `false` when it did not - which in
+     * practice means another worker has since re-claimed the task (its
+     * startedAt no longer matches) and this call was a no-op.
+     *
+     * Callers that care about the distinction (e.g. to suppress success /
+     * failure metrics for a stolen task) should inspect the return value.
+     */
     finalizeTask(taskRecord: ReactiveTaskRecord<T>, strategy: ReactiveTaskRetryStrategy, error?: Error, debounceMs?: number, executionStats?: {
         durationMs: number;
     }, executionHistoryLimit?: number, options?: {
         session?: import('mongodb').ClientSession;
-    }): Promise<void>;
+    }): Promise<boolean>;
     deferTask(taskRecord: ReactiveTaskRecord<T>, delay: number | Date): Promise<void>;
     executeBulkWrite(operations: Parameters<Collection<ReactiveTaskRecord<T>>['bulkWrite']>[0], options?: CompatibleBulkWriteOptions): Promise<void>;
     findTasks(filter: Filter<ReactiveTaskRecord<T>>, options?: {

package/dist/types/reactiveTasks/ReactiveTaskTypes.d.ts

@@ -103,6 +103,19 @@ export interface RegistryDocument {
         lastSeen: Date | string;
         metrics: unknown;
     }>;
+    /**
+     * Cluster-wide stats (queue depth, global lag, change-stream lag,
+     * last reconciliation). Written only by the current Leader on each
+     * push; non-leaders read it so that a follower-served scrape in
+     * `cluster` mode can return a complete metrics view. A single field
+     * (not per-instance) prevents double-counting across leader
+     * transitions - the next leader overwrites on its first push.
+     */
+    globalStats?: {
+        updatedAt: Date | string;
+        leaderId: string;
+        metrics: unknown;
+    };
 }
 /**
  * Error thrown when `getDocument` fails because the document no longer matches the filter
@@ -336,6 +349,7 @@ export interface ReactiveTaskCaller {
 export declare const CODE_REACTIVE_TASK_STARTED = "reactiveTaskStarted";
 export declare const CODE_REACTIVE_TASK_FINISHED = "reactiveTaskFinished";
 export declare const CODE_REACTIVE_TASK_FAILED = "reactiveTaskFailed";
+export declare const CODE_REACTIVE_TASK_LOCK_LOST = "reactiveTaskLockLost";
 export declare const CODE_REACTIVE_TASK_PLANNER_STARTED = "reactiveTaskPlannerStarted";
 export declare const CODE_REACTIVE_TASK_PLANNER_STOPPED = "reactiveTaskPlannerStopped";
 export declare const CODE_REACTIVE_TASK_PLANNER_RECONCILIATION_STARTED = "reactiveTaskPlannerReconciliationStarted";
@@ -345,6 +359,11 @@ export declare const CODE_REACTIVE_TASK_LEADER_LOCK_LOST = "reactiveTaskLeaderLo
 export declare const CODE_REACTIVE_TASK_INITIALIZED = "reactiveTaskInitialized";
 export declare const CODE_REACTIVE_TASK_CLEANUP = "reactiveTaskCleanup";
 export declare const CODE_MANUAL_TRIGGER = "manualTrigger";
+/**
+ * @internal
+ * Document id used by the planner for its meta document. Exposed for the
+ * dashboard and advanced tooling - not part of the public API contract.
+ */
 export declare const REACTIVE_TASK_META_DOC_ID = "_mongodash_planner_meta";
 /**
  * Filter for querying tasks.

package/dist/types/reactiveTasks/index.d.ts

@@ -6,7 +6,13 @@ import { ReactiveTaskManager } from './ReactiveTaskManager';
 import { ReactiveTaskPlanner } from './ReactiveTaskPlanner';
 import { ReactiveTaskRegistry } from './ReactiveTaskRegistry';
 import { PagedResult, PaginationOptions, ReactiveTask, ReactiveTaskQuery, ReactiveTaskRecord, ReactiveTaskSchedulerOptions } from './ReactiveTaskTypes';
-export { CODE_REACTIVE_TASK_CLEANUP, CODE_REACTIVE_TASK_FAILED, CODE_REACTIVE_TASK_FINISHED, CODE_REACTIVE_TASK_INITIALIZED, CODE_REACTIVE_TASK_LEADER_LOCK_LOST, CODE_REACTIVE_TASK_PLANNER_RECONCILIATION_FINISHED, CODE_REACTIVE_TASK_PLANNER_RECONCILIATION_STARTED, CODE_REACTIVE_TASK_PLANNER_STARTED, CODE_REACTIVE_TASK_PLANNER_STOPPED, CODE_REACTIVE_TASK_PLANNER_STREAM_ERROR, CODE_REACTIVE_TASK_STARTED, PagedResult, PaginationOptions, ReactiveTask, ReactiveTaskCaller, ReactiveTaskFilter, ReactiveTaskHandler, ReactiveTaskQuery, ReactiveTaskRecord, ReactiveTaskSchedulerOptions, ReactiveTaskStatus, REACTIVE_TASK_META_DOC_ID, TaskConditionFailedError, } from './ReactiveTaskTypes';
+export { CODE_REACTIVE_TASK_CLEANUP, CODE_REACTIVE_TASK_FAILED, CODE_REACTIVE_TASK_FINISHED, CODE_REACTIVE_TASK_INITIALIZED, CODE_REACTIVE_TASK_LEADER_LOCK_LOST, CODE_REACTIVE_TASK_LOCK_LOST, CODE_REACTIVE_TASK_PLANNER_RECONCILIATION_FINISHED, CODE_REACTIVE_TASK_PLANNER_RECONCILIATION_STARTED, CODE_REACTIVE_TASK_PLANNER_STARTED, CODE_REACTIVE_TASK_PLANNER_STOPPED, CODE_REACTIVE_TASK_PLANNER_STREAM_ERROR, CODE_REACTIVE_TASK_STARTED, PagedResult, PaginationOptions, ReactiveTask, ReactiveTaskCaller, ReactiveTaskFilter, ReactiveTaskHandler, ReactiveTaskQuery, ReactiveTaskRecord, ReactiveTaskSchedulerOptions, ReactiveTaskStatus, REACTIVE_TASK_META_DOC_ID, TaskConditionFailedError, } from './ReactiveTaskTypes';
+/**
+ * @internal
+ * Exported only for the built-in OperationalTaskController / dashboard bridge
+ * and for advanced testing. Not part of the public API contract: fields and
+ * methods on the scheduler instance can change between minor versions.
+ */
 export { scheduler as _scheduler };
 export type InitOptions = {
     globalsCollection: GlobalsCollection;
@@ -54,7 +60,7 @@ export declare class ReactiveTaskScheduler {
         debounce?: number;
     }): void;
     get forceDebounce(): number | string | undefined;
-    addTask(taskDef: ReactiveTask<Document>): Promise<void>;
+    addTask<T extends Document>(taskDef: ReactiveTask<T>): Promise<void>;
     /**
      * Starts the entire system - leader election and workers.
      */

package/dist/types/testing/assertNoReactiveTaskErrors.d.ts

@@ -1,4 +1,5 @@
 import { ReactiveTaskScheduler } from '../reactiveTasks';
+import { WhitelistRule } from './resolveWhitelistFilter';
 export interface AssertNoReactiveTaskErrorsOptions {
     /**
      * Check for errors occurring after this time.
@@ -6,11 +7,10 @@ export interface AssertNoReactiveTaskErrorsOptions {
      */
     since: Date;
     /**
-     * Optional: Check only tasks related to these specific source documents.
-     * Useful when other tests might be generating noise in the background.
-     * Supports generic ID types (ObjectId, string, number).
+     * Optional: Check only tasks related to specific entities.
+     * If provided, errors in collections/tasks not matching the whitelist are ignored.
      */
-    sourceDocIds?: unknown[];
+    whitelist?: WhitelistRule[];
     /**
      * Optional: Whitelist specific errors.
      * If a string is provided, exact match is required.

package/dist/types/testing/index.d.ts

@@ -1,3 +1,5 @@
 export * from './assertNoReactiveTaskErrors';
 export * from './configureForTesting';
+export * from './resolveWhitelistFilter';
+export * from './waitUntil';
 export * from './waitUntilReactiveTasksIdle';

package/dist/types/testing/resolveWhitelistFilter.d.ts

@@ -0,0 +1,35 @@
+import { Collection, Document, Filter } from 'mongodb';
+import { ReactiveTaskRecord } from '../reactiveTasks';
+/**
+ * A single rule used by the testing utilities to scope checks to a set of
+ * source documents.
+ */
+export interface WhitelistRule {
+    collection: string;
+    /**
+     * Filter to find relevant source documents. When omitted every document
+     * in the collection is considered.
+     */
+    filter?: Filter<Document>;
+    /**
+     * Optional: restrict to a specific reactive task name.
+     */
+    task?: string;
+}
+/**
+ * Resolution outcome for a whitelist against one registry entry.
+ *
+ * - `'skip'`: the whitelist has rules, but none apply to this collection or
+ *   the source filters matched zero documents. Callers should skip this
+ *   entry entirely.
+ * - `'matchAll'`: at least one rule for this collection wants the full
+ *   collection. Callers should apply no extra filter.
+ * - An object: the caller should AND this filter with its base query.
+ */
+export type WhitelistResolution = 'skip' | 'matchAll' | Filter<ReactiveTaskRecord>;
+/**
+ * Build the `Filter<ReactiveTaskRecord>` for a single registry entry based on
+ * the provided whitelist rules. Extracted from `waitUntilReactiveTasksIdle` /
+ * `assertNoReactiveTaskErrors` so the two utilities cannot drift.
+ */
+export declare function resolveWhitelistFilter(whitelist: WhitelistRule[], sourceCollection: Pick<Collection<Document>, 'collectionName' | 'find'>): Promise<WhitelistResolution>;