mongodash 2.6.0 → 2.8.0

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.8.0",
     "type": "commonjs",
     "description": "An utility library delivering super-useful and super-simple tools using MongoDB",
     "main": "./dist/lib/index.js",
@@ -10,6 +10,18 @@
             "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 +61,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 +76,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"
-    }
-  }
-}