mongodash 2.6.0 → 2.7.0

package/docs/reactive-tasks/testing.md

@@ -0,0 +1,187 @@
+# Testing Reactive Tasks
+
+Testing asynchronous, event-driven workflows is notoriously hard: the "done"
+state is not a return value from the code you called but a quiescent state of
+a background system. Mongodash ships with helpers that address this directly.
+
+> [!TIP]
+> For the generic polling helper (not tied to reactive tasks), see
+> [**`waitUntil`**](../testing.md).
+
+## `waitUntilReactiveTasksIdle`
+
+Blocks until the reactive-task subsystem is completely quiesced. This is
+essential for end-to-end tests where you want to assert the final state after
+a chain of cascading tasks has settled.
+
+### What it waits for
+
+It resolves only when **all** of the following validation checks pass
+simultaneously (and remain true for `stabilityDurationMs`):
+
+1.  **Planner empty** — the internal `ReactiveTaskPlanner` has no buffered
+    change-stream events waiting to be flushed.
+2.  **Workers idle** — no `ReactiveTaskWorker` is currently processing a task
+    (active count is 0).
+3.  **Database settled** — no tasks in any registered task collection are in
+    `pending`, `processing`, or `processing_dirty` state.
+    -   **Exception**: pending tasks scheduled for the _distant future_
+        (beyond the current `timeoutMs + stabilityDurationMs + 100ms`) are
+        ignored, so long retries (e.g. "retry in 1 hour") do not block your
+        test forever.
+
+### Usage
+
+```typescript
+import { waitUntilReactiveTasksIdle } from 'mongodash/testing';
+
+it('should process user registration workflow', async () => {
+    // 1. Trigger the workflow
+    await users.insertOne({ email: 'test@example.com', status: 'new' });
+
+    // 2. Wait for the reactive task to process the insert AND any cascading
+    //    tasks it may have triggered (welcome email, provisioning, etc.)
+    await waitUntilReactiveTasksIdle();
+
+    // 3. Assert the final state
+    const emailTask = await emailTasks.findOne({ email: 'test@example.com' });
+    expect(emailTask).toBeDefined();
+    expect(emailTask.status).toBe('sent');
+});
+```
+
+### Configuration
+
+Defaults are tuned for general use; override as needed:
+
+```typescript
+await waitUntilReactiveTasksIdle({
+    timeoutMs: 30000,
+    stabilityDurationMs: 200, // 200ms of "silence" to catch in-flight cascading tasks
+});
+```
+
+### Isolation with `whitelist`
+
+When running tests in parallel against a shared database, use `whitelist` to
+wait only for tasks that belong to this test. In whitelist mode the **active
+workers** check is skipped so another test's worker pool does not block you;
+the planner buffer check is still applied (otherwise we could return idle
+before a change event we care about has even been turned into a task row).
+
+```typescript
+await waitUntilReactiveTasksIdle({
+    whitelist: [
+        { collection: 'users', filter: { _id: userId } }, // specific user
+        { collection: 'orders', task: 'processOrder' },   // specific task on collection
+    ],
+});
+```
+
+> [!NOTE]
+> The idle check queries task records by `sourceDocId`. If your trigger is
+> very fast (e.g. a write immediately followed by `waitUntilReactiveTasksIdle`)
+> and the default `stabilityDurationMs` is low, you may need to raise
+> `stabilityDurationMs` to ensure the planner has had a chance to flush the
+> event into a task record. Alternatively, poll with `waitUntil` for the
+> task record to exist first, then call `waitUntilReactiveTasksIdle`.
+
+## `assertNoReactiveTaskErrors`
+
+Catches "silent failures" — tasks that threw and were logged but never
+propagated to the test as an assertion error.
+
+### Features
+
+-   **Time filtering** — only checks for errors that occurred after a given
+    `since` timestamp (typically test start).
+-   **Scope** — check globally or limit to specific source documents / task
+    names via `whitelist`.
+-   **Exclusions** — allow known errors (string or regex) without failing the
+    test.
+
+### Usage
+
+```typescript
+import { assertNoReactiveTaskErrors } from 'mongodash/testing';
+
+it('should process successfully', async () => {
+    const startTime = new Date();
+
+    // ... run test steps ...
+    await waitUntilReactiveTasksIdle();
+
+    await assertNoReactiveTaskErrors({ since: startTime });
+});
+```
+
+### Options
+
+```typescript
+await assertNoReactiveTaskErrors({
+    since: startTime, // required
+    whitelist: [{
+        collection: 'users',
+        filter: { _id: userId },
+    }],
+    excludeErrors: [
+        'Expected Failure',
+        /Authorization Error/,
+    ],
+});
+```
+
+## `configureForTesting`
+
+Production defaults (`debounce: 1000ms`, `minPollMs: 200ms`, etc.) are tuned
+for real workloads but make tests unnecessarily slow. `configureForTesting`
+overrides these globally with minimal values (typically `10ms`).
+
+Call it **once** in your test setup (`jest.setup.js`, `beforeAll`, etc.). It
+works whether called before or after task registration.
+
+```typescript
+import { configureForTesting } from 'mongodash/testing';
+
+beforeAll(() => {
+    configureForTesting();
+});
+```
+
+### Options
+
+```typescript
+configureForTesting({
+    debounce: 0,        // 0ms debounce (immediate planning)
+    minPollMs: 50,      // polling interval
+    minBatchIntervalMs: 50,
+});
+```
+
+## Whitelist rules
+
+`waitUntilReactiveTasksIdle` and `assertNoReactiveTaskErrors` share a
+`whitelist` option of type `WhitelistRule[]`. The type is exported so test
+suites can share scope definitions:
+
+```typescript
+import type { WhitelistRule } from 'mongodash/testing';
+
+const scopeToUser = (userId: string): WhitelistRule[] => [
+    { collection: 'users', filter: { _id: userId } },
+    { collection: 'notifications', filter: { userId } },
+];
+
+await waitUntilReactiveTasksIdle({ whitelist: scopeToUser(id) });
+await assertNoReactiveTaskErrors({ since, whitelist: scopeToUser(id) });
+```
+
+Rule semantics:
+
+-   **No `filter` and no `task`** — matches every document and every task in
+    that collection ("match-all").
+-   **`filter` that matches zero documents** — the rule is treated as
+    "skip this collection", useful when the rule is built from a variable
+    that may be empty.
+-   **Multiple rules for the same collection** — OR-merged into a single
+    filter. A `match-all` rule wins over others.

package/docs/testing.md

@@ -1,123 +1,89 @@
-# Testing Utilities
+# Testing
 
-Mongodash provides a set of utilities to help you write robust End-to-End (E2E) tests for your asynchronous applications.
+Mongodash's asynchronous subsystems (reactive tasks, cron, change streams)
+need more than a fixed `setTimeout` in tests. This page lists the testing
+utilities the library provides, grouped by scope.
 
-## `waitUntilReactiveTasksIdle`
+## Generic
 
-A specialized helper for testing **Reactive Tasks**. It blocks execution until the reactive task system is completely quiesced.
+### `waitUntil`
 
-This is essential for testing "side effects" and "cascading tasks" where you want to assert the final state of the system after a chain of events has completed.
+A general-purpose polling helper that resolves once a condition function
+returns `true`. Useful when the built-in waits are too broad (e.g. waiting
+for an HTTP side effect or an external queue) or as a building block for
+your own utilities.
 
-### What it waits for
-
-It resolves only when **ALL** of the following validation checks pass simultaneously (or for the `stabilityDurationMs`):
-
-1.  **Planner Empty**: The internal `ReactiveTaskPlanner` has no buffered Change Stream events waiting to be flushed.
-2.  **Workers Idle**: No `ResponsiveTaskWorker` is currently processing a task (active count is 0).
-3.  **Database Settled**: No tasks in any registered task collection are in `pending`, `processing`, or `processing_dirty` state.
-    *   **Exception**: Pending tasks scheduled for the **distant future** (beyond the current timeout + stability window) are ignored. This ensures that long-term retries (e.g., "retry in 1 hour") do not cause your tests to timeout.
-
-### Usage
+It includes a **time-jump detector**: if a breakpoint or a suspended laptop
+pauses the event loop for more than a second, the deadline is extended by
+the observed pause so the wait does not falsely time out.
 
 ```typescript
-import { waitUntilReactiveTasksIdle } from 'mongodash/testing';
-
-it('should process user registration workflow', async () => {
-    // 1. Trigger the workflow
-    await users.insertOne({ email: 'test@example.com', status: 'new' });
+import { waitUntil } from 'mongodash/testing';
 
-    // 2. Wait for the reactive task to process ONLY the insert
-    //    AND any subsequent tasks that might be triggered (e.g. sending email)
-    await waitUntilReactiveTasksIdle();
-
-    // 3. Assert the final state
-    const emailTask = await emailTasks.findOne({ email: 'test@example.com' });
-    expect(emailTask).toBeDefined();
-    expect(emailTask.status).toBe('sent');
-});
+await waitUntil(
+    async () => (await getBalance(userId)) === 100,
+    { timeoutMs: 5000, pollIntervalMs: 50, stabilityDurationMs: 100 },
+);
 ```
 
-### Configuration
-
-You can override the default options if needed, though the defaults are tuned for general use.
+| Option | Default | Description |
+| :--- | :--- | :--- |
+| `timeoutMs` | `10000` | Maximum time before throwing. |
+| `pollIntervalMs` | `50` | How often the condition is evaluated. |
+| `stabilityDurationMs` | `0` | How long the condition must _remain_ true before resolving. Prevents flakiness when a state briefly flips true then false. |
 
-```typescript
-await waitUntilReactiveTasksIdle({
-    timeoutMs: 30000,
-    stabilityDurationMs: 200, // Wait for 200ms of "silence" to catch in-flight cascading tasks
-});
-```
+## Reactive tasks
 
-## `assertNoReactiveTaskErrors`
+See [**Testing Reactive Tasks**](./reactive-tasks/testing.md) for:
 
-Ensures that no reactive tasks have failed during your test execution. This is critical for catching "silent failures" where a task failed but didn't crash the application or the test.
+-   `waitUntilReactiveTasksIdle` — wait for the reactive-task subsystem to
+    fully settle (planner empty, workers idle, DB drained).
+-   `assertNoReactiveTaskErrors` — catch silent failures a handler logged
+    but never threw up the stack.
+-   `configureForTesting` — replace production debounce / polling intervals
+    with testing-friendly values.
+-   `WhitelistRule` — scope the above helpers to specific
+    collections / documents / tasks for parallel tests.
 
-### Features
+## Cron tasks
 
-- **Time filtering**: Only checks for errors that occurred after a specific time (e.g., the start of your test).
-- **Scope**: Can check globally or for specific source documents.
-- **Filtering**: Allows ignoring "expected" errors (e.g., negative tests).
+Cron tasks expose a few helpers from the main entry point that are primarily
+useful in tests. They live on the main `mongodash` module alongside the
+cron API rather than under `mongodash/testing`:
 
-### Usage
+### Run a task synchronously
 
 ```typescript
-import { assertNoReactiveTaskErrors } from 'mongodash/testing';
-
-it('should process successfully', async () => {
-    const startTime = new Date();
+import { runCronTask } from 'mongodash';
 
-    // ... run test steps ...
-    await waitUntilReactiveTasksIdle();
-
-    // Verify no tasks failed
-    await assertNoReactiveTaskErrors({ since: startTime });
+it('processes pending invoices', async () => {
+    await runCronTask('invoice-sweep');
+    const processed = await invoices.countDocuments({ status: 'processed' });
+    expect(processed).toBeGreaterThan(0);
 });
 ```
 
-### Options
+`runCronTask(taskId)` enqueues the task and awaits its completion. It throws
+if called from inside another running cron task (use
+`scheduleCronTaskImmediately` / `triggerCronTask` there instead).
 
-```typescript
-await assertNoReactiveTaskErrors({
-    since: startTime, // Required: Check for errors after this time
-    sourceDocIds: [docId], // Optional: Limit check to specific source documents
-    excludeErrors: [ // Optional: Allow known errors (strings or RegEx)
-        'Expected Failure',
-        /Authorization Error/
-    ]
-});
-```
-
-## `configureForTesting`
-
-A helper to configure the library for fast, deterministic testing execution.
-
-By default, the library is optimized for production scenarios (e.g. `debounce: 1000ms`, `minPollMs: 200ms`). In tests, these delays cause unnecessary slowness.
-
-`configureForTesting` overrides these defaults globally to minimal values (e.g. `10ms`).
-
-### Usage
-
-Call this **once** in your global test setup (e.g. `jest.setup.js` or `beforeAll`).
+### Disable the scheduler
 
-It works regardless of whether you call it before or after registering your tasks.
+Running background cron jobs in unit tests causes non-determinism. Two
+options:
 
 ```typescript
-import { configureForTesting } from 'mongodash/testing';
-
-beforeAll(() => {
-    // Sets debounce, polling, and batching to 10ms
-    configureForTesting();
-});
+// Option A: never auto-start.
+await mongodash.init({ ..., runCronTasks: false });
+
+// Option B: stop after init.
+import { stopCronTasks, startCronTasks } from 'mongodash';
+stopCronTasks();
+// ...
+startCronTasks(); // if a test needs it back
 ```
 
-### Options
-
-You can customize specific values if needed:
+Called before the first `cronTask()` registration, `stopCronTasks()` also
+prevents any task from starting later in the process.
 
-```typescript
-configureForTesting({
-    debounce: 0,        // Force 0ms debounce (immediate execution)
-    minPollMs: 50,      // Poll every 50ms
-    minBatchIntervalMs: 50
-});
-```
+See [**Cron Tasks**](./cron-tasks.md) for the full cron reference.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mongodash",
-    "version": "2.6.0",
+    "version": "2.7.0",
     "type": "commonjs",
     "description": "An utility library delivering super-useful and super-simple tools using MongoDB",
     "main": "./dist/lib/index.js",
@@ -10,6 +10,16 @@
             "types": "./dist/types/index.d.ts",
             "import": "./dist/lib/index.js",
             "default": "./dist/lib/index.js"
+        },
+        "./testing": {
+            "types": "./dist/types/testing/index.d.ts",
+            "import": "./dist/lib/testing/index.js",
+            "default": "./dist/lib/testing/index.js"
+        }
+    },
+    "typesVersions": {
+        "*": {
+            "testing": ["./dist/types/testing/index.d.ts"]
         }
     },
     "files": [
@@ -49,7 +59,7 @@
     },
     "dependencies": {
         "@sapphire/duration": "^1.2.0",
-        "cron-parser": "^5.4.0",
+        "cron-parser": "^5.5.0",
         "debug": "^4.4.3",
         "fast-json-stable-stringify": "^2.1.0"
     },
@@ -64,41 +74,41 @@
     },
     "devDependencies": {
         "@arethetypeswrong/cli": "^0.18.2",
-        "@commitlint/cli": "^20.2.0",
+        "@commitlint/cli": "^20.5.0",
         "@semantic-release/changelog": "^6.0.3",
         "@semantic-release/git": "^10.0.1",
-        "@stryker-mutator/core": "^9.4.0",
-        "@stryker-mutator/jest-runner": "^9.4.0",
-        "@types/debug": "^4.1.12",
+        "@stryker-mutator/core": "^9.6.1",
+        "@stryker-mutator/jest-runner": "^9.6.1",
+        "@types/debug": "^4.1.13",
         "@types/jest": "^30.0.0",
-        "@types/lodash": "^4.17.21",
-        "@types/node": "^25.0.3",
-        "@types/sinon": "^21.0.0",
-        "@typescript-eslint/eslint-plugin": "^8.51.0",
-        "@typescript-eslint/parser": "^8.51.0",
+        "@types/lodash": "^4.17.24",
+        "@types/node": "^25.6.0",
+        "@types/sinon": "^21.0.1",
+        "@typescript-eslint/eslint-plugin": "^8.58.2",
+        "@typescript-eslint/parser": "^8.58.2",
         "correlation-id": "^5.2.0",
         "coveralls": "^3.1.1",
         "deepdash": "^5.3.9",
-        "eslint": "^9.39.2",
+        "eslint": "^9.39.4",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-no-only-tests": "^3.3.0",
-        "eslint-plugin-prettier": "^5.5.4",
-        "globals": "^16.5.0",
+        "eslint-plugin-prettier": "^5.5.5",
+        "globals": "^17.5.0",
         "husky": "^9.1.7",
-        "jest": "^30.2.0",
+        "jest": "^30.3.0",
         "js-yaml": "4.1.1",
-        "lint-staged": "^16.2.7",
-        "lodash": "^4.17.21",
-        "mongodb": "^7.0.0",
+        "lint-staged": "^16.4.0",
+        "lodash": "^4.18.1",
+        "mongodb": "^7.1.1",
         "npm-run-all": "^4.1.5",
         "organize-imports-cli": "^0.10.0",
-        "path-to-regexp": "8.3.0",
-        "prettier": "^3.7.4",
+        "path-to-regexp": "8.4.2",
+        "prettier": "^3.8.3",
         "prom-client": "^15.1.3",
-        "publint": "^0.3.16",
-        "semantic-release": "^25.0.2",
-        "sinon": "^21.0.1",
-        "ts-jest": "^29.4.6",
+        "publint": "^0.3.18",
+        "semantic-release": "^25.0.3",
+        "sinon": "^21.1.2",
+        "ts-jest": "^29.4.9",
         "ts-node": "^10.9.2",
         "typescript": "^5.9.3",
         "vitepress": "^1.6.4"

package/docs/.vitepress/cache/deps/_metadata.json

@@ -1,31 +0,0 @@
-{
-  "hash": "65ae190e",
-  "configHash": "1734f516",
-  "lockfileHash": "68b03582",
-  "browserHash": "246dbe54",
-  "optimized": {
-    "vue": {
-      "src": "../../../../node_modules/vue/dist/vue.runtime.esm-bundler.js",
-      "file": "vue.js",
-      "fileHash": "1ab8f95b",
-      "needsInterop": false
-    },
-    "vitepress > @vue/devtools-api": {
-      "src": "../../../../node_modules/@vue/devtools-api/dist/index.js",
-      "file": "vitepress___@vue_devtools-api.js",
-      "fileHash": "eb38336e",
-      "needsInterop": false
-    },
-    "vitepress > @vueuse/core": {
-      "src": "../../../../node_modules/@vueuse/core/index.mjs",
-      "file": "vitepress___@vueuse_core.js",
-      "fileHash": "d06fa19f",
-      "needsInterop": false
-    }
-  },
-  "chunks": {
-    "chunk-LE5NDSFD": {
-      "file": "chunk-LE5NDSFD.js"
-    }
-  }
-}